Sui Full Node gRPC
This content describes an alpha/beta feature or service. These early stage features and services are in active development, so details are likely to change.
This feature or service is currently available in
- Devnet
- Testnet
- Mainnet
Sui Full node gRPC API will replace the JSON-RPC on Full nodes, such that JSON-RPC will be deprecated when gRPC API is generally available.
sui/rpc/v2beta2/protocol_config.proto
Messages
ProtocolConfig
AttributesEntry
FeatureFlagsEntry
sui/rpc/v2beta2/live_data_service.proto
Messages
Balance
Balance information for a specific coin type.
CoinMetadata
Metadata for a coin type
CoinTreasury
Information about a coin type's 0x2::coin::TreasuryCap and its total available supply
CommandOutput
CommandResult
An intermediate result/output from the execution of a single command
DynamicField
GetBalanceRequest
Request message for LiveDataService.GetBalance.
GetBalanceResponse
Response message for LiveDataService.GetBalance.
Return the total coin balance for one coin type, owned by the address owner.
GetCoinInfoRequest
Request message for NodeService.GetCoinInfo.
GetCoinInfoResponse
Response message for NodeService.GetCoinInfo.
0x2::coin::CoinMetadata if it exists and has not been wrapped.0x2::coin::RegulatedCoinMetadata object.0x2::coin::TreasuryCap if it exists and has not been wrapped.ListBalancesRequest
Request message for LiveDataService.ListBalances.
50 entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.ListBalances call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListBalances must match the call that provided the page token.ListBalancesResponse
Response message for LiveDataService.ListBalances.
Return the total coin balance for all coin types, owned by the address owner.
page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.ListDynamicFieldsRequest
Request message for NodeService.ListDynamicFields
50 entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.ListDynamicFields call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListDynamicFields must match the call that provided the page token.ListDynamicFieldsResponse
Response message for NodeService.ListDynamicFields
page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.ListOwnedObjectsRequest
0x2::coin::Coin will return all Coin<T> objects regardless of the type parameter T. Providing a type with a type param will retrict the returned objects to only those objects that match the provided type parameters, e.g. 0x2::coin::Coin<0x2::sui::SUI> will only return Coin<SUI> objects.50 entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.ListOwnedObjects call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListOwnedObjects must match the call that provided the page token.ListOwnedObjectsResponse
page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.RegulatedCoinMetadata
Information about a regulated coin, which indicates that it makes use of the transfer deny list.
SimulateTransactionRequest
checks is DISABLED.SimulateTransactionResponse
Services (live_data_service.proto)
LiveDataService
Enums
DynamicFieldKind
DYNAMIC_FIELD_KIND_UNKNOWNFIELDOBJECTTransactionChecks
ENABLEDDISABLEDsui/rpc/v2beta2/epoch.proto
Messages
Epoch
0x3::sui_system::SystemState) at the beginning of the epoch, for past epochs, or the current state for the current epoch.sui/rpc/v2beta2/transaction.proto
Messages
ActiveJwk
A new JWK.
AuthenticatorStateExpire
Expire old JWKs.
AuthenticatorStateUpdate
Update the set of valid JWKs.
CanceledTransaction
A transaction that was canceled.
ChangeEpoch
System transaction used to change the epoch.
ChangeEpoch txn, the validator must write out the following modules. Modules are provided with the version they will be upgraded to, their modules in serialized form (which include their package ID), and a list of their transitive dependencies.Command
A single command in a programmable transaction.
forall T: Vec<T> -> vector<T> Given n-values of the same type, it constructs a vector. For non-objects or an empty vector, the type tag must be specified.(&mut Coin<T>, Vec<Coin<T>>) It merges n-coins into the first coin.(&mut Coin<T>, Vec<u64>) -> Vec<Coin<T>> It splits off some amounts into new coins with those amounts.(Vec<forall T:key+store. T>, address) It sends n-objects to the specified address. These objects must have store (public transfer) and either the previous owner must be an address or the object must be newly created.UpgradeTicket that must have been produced from an earlier command in the same programmable transaction.ConsensusCommitPrologue
Consensus commit prologue system transaction.
This message can represent V1, V2, and V3 prologue types.
ConsensusDeterminedVersionAssignments
Version assignments performed by consensus.
EndOfEpochTransaction
Set of operations run at the end of the epoch to close out the current epoch and start the next one.
EndOfEpochTransactionKind
Operation run at the end of an epoch.
ExecutionTimeObservation
ExecutionTimeObservations
GasPayment
Payment information for executing a transaction.
GenesisTransaction
The genesis transaction.
Jwk
A JSON web key.
Struct that contains info for a JWK. A list of them for different kinds can be retrieved from the JWK endpoint (for example, &#lt;https://www.googleapis.com/oauth2/v3/certs>). The JWK is used to verify the JWT token.
JwkId
Key to uniquely identify a JWK.
MakeMoveVector
Command to build a Move vector out of a set of individual elements.
MergeCoins
Command to merge multiple coins of the same type into a single coin.
coin. All listed coins must be of the same type and be the same type as coinMoveCall
Command to call a Move function.
Functions that can be called by a MoveCall command are those that have a function signature
that is either entry or public (which don't have a reference return type).
ProgrammableTransaction
A user transaction.
Contains a series of native commands and Move calls where the results of one command can be used in future commands.
Publish
Command to publish a new Move package.
RandomnessStateUpdate
Randomness update.
SplitCoins
Command to split a single coin object into multiple coins.
SystemPackage
System package.
Transaction
A transaction.
TransactionExpiration
A TTL for a transaction.
TransactionKind
Transaction type.
ChangeEpoch variant is now deprecated (but the ChangeEpoch struct is still used by EndOfEpochTransaction).TransferObjects
Command to transfer ownership of a set of objects to an address.
Upgrade
Command to upgrade an already published package.
ValidatorExecutionTimeObservation
VersionAssignment
Object version assignment from consensus.
Enums
ExecutionTimeObservationKind
EXECUTION_TIME_OBSERVATION_KIND_UNKNOWNMOVE_ENTRY_POINTTRANSFER_OBJECTSSPLIT_COINSMERGE_COINSPUBLISHMAKE_MOVE_VECTORUPGRADETransactionExpirationKind
TRANSACTION_EXPIRATION_KIND_UNKNOWNNONEEPOCHsui/rpc/v2beta2/argument.proto
Messages
Argument
An argument to a programmable transaction command.
Enums
ArgumentKind
ARGUMENT_KIND_UNKNOWNGASINPUTProgrammableTransaction inputs).RESULTProgrammableTransaction commands).sui/rpc/v2beta2/subscription_service.proto
Messages
SubscribeCheckpointsRequest
Request message for SubscriptionService.SubscribeCheckpoints
SubscribeCheckpointsResponse
Response message for SubscriptionService.SubscribeCheckpoints
Services (subscription_service.proto)
SubscriptionService
sui/rpc/v2beta2/object_reference.proto
sui/rpc/v2beta2/input.proto
Messages
Input
An input to a user transaction.
kind is IMMUTABLE_OR_OWNED or RECEIVING or if kind is SHARED this is the initial version of the object when it was sharedEnums
InputKind
INPUT_KIND_UNKNOWNPUREIMMUTABLE_OR_OWNEDSHAREDRECEIVINGsui/rpc/v2beta2/owner.proto
Messages
Owner
Enum of different types of ownership for an object.
initial_shared_version if kind is SHARED or start_version if kind CONSENSUS_ADDRESS.Enums
OwnerKind
OWNER_KIND_UNKNOWNADDRESSOBJECTSHAREDIMMUTABLECONSENSUS_ADDRESSsui/rpc/v2beta2/checkpoint_summary.proto
Messages
CheckpointCommitment
A commitment made by a checkpoint.
CheckpointSummary
A header for a checkpoint on the Sui blockchain.
On the Sui network, checkpoints define the history of the blockchain. They are quite similar to the concept of blocks used by other blockchains like Bitcoin or Ethereum. The Sui blockchain, however, forms checkpoints after transaction execution has already happened to provide a certified history of the chain, instead of being formed before execution.
Checkpoints commit to a variety of state, including but not limited to:
- The hash of the previous checkpoint.
- The set of transaction digests, their corresponding effects digests, as well as the set of user signatures that authorized its execution.
- The objects produced by a transaction.
- The set of live objects that make up the current state of the chain.
- On epoch transitions, the next validator committee.
CheckpointSummarys themselves don't directly include all of the previous information but they
are the top-level type by which all the information is committed to transitively via cryptographic
hashes included in the summary. CheckpointSummarys are signed and certified by a quorum of
the validator committee in a given epoch to allow verification of the chain's state.
CheckpointSummary. This will be None only for the first, or genesis, checkpoint.CheckpointSummary is not an evolvable structure - it must be readable by any version of the code. Therefore, to allow extensions to be added to CheckpointSummary, opaque data can be added to checkpoints, which can be deserialized based on the current protocol version.EndOfEpochData
Data, which when included in a CheckpointSummary, signals the end of an Epoch.
ValidatorCommittee for the next epoch.Enums
CheckpointCommitmentKind
CHECKPOINT_COMMITMENT_KIND_UNKNOWNECMH_LIVE_OBJECT_SETsui/rpc/v2beta2/executed_transaction.proto
Messages
ExecutedTransaction
TransactionEvents for this transaction. This field might be empty, even if it was explicitly requested, if the transaction didn't produce any events. sui.types.TransactionEffects.events_digest is populated if the transaction produced any events.sui/rpc/v2beta2/move_package.proto
Messages
DatatypeDescriptor
Describes a Move Datatype.
defining_id is the storage_id of the package version that first introduced or added that type.FieldDescriptor
Descriptor of a field that belongs to a struct or enum variant
FunctionDescriptor
Descriptor of a Move function
Linkage
Upgraded package info for the linkage table.
Module
A Move Module.
OpenSignature
Representation of a type signature that could appear as a function parameter or return value.
OpenSignatureBody
Representation of a type signature that could appear as a field type for a struct or enum
type is TYPE_PARAMETERPackage
A Move Package
original_id (sometimes also called its runtime_id) is the storage_id of the first version of this package that has been published. The original_id/runtime_id is stable across all versions of the package and does not ever change.storage_id is the Sui ObjectId of the package on-chain. Outside of system packages the storage_id for every package version is different.TypeOrigin
Identifies a struct and the module it was defined in.
TypeParameter
A generic type parameter used in the declaration of a struct or enum.
VariantDescriptor
Descriptor of an enum variant
Enums
Ability
Ability classifies what operations are permitted for a given typeABILITY_UNKNOWNCOPYDROPSTOREKEYDatatypeKind
DATATYPE_KIND_UNKNOWNSTRUCTENUMVisibility
VISIBILITY_UNKNOWNPRIVATEPUBLICFRIENDReference
REFERENCE_UNKNOWNIMMUTABLEMUTABLEType
TYPE_UNKNOWNADDRESSBOOLU8U16U32U64U128U256VECTORDATATYPETYPE_PARAMETERsui/rpc/v2beta2/balance_change.proto
sui/rpc/v2beta2/event.proto
Messages
Event
An event.
MoveCall command that triggered this event to be emitted.MoveCall command that triggered this event to be emitted.TransactionEvents
Events emitted during the successful execution of a transaction.
sui/rpc/v2beta2/system_state.proto
Messages
MoveTable
A message that represents a Move 0x2::table::Table or 0x2::bag::Bag
StakeSubsidy
StakingPool
A staking pool embedded in each validator struct in the system state object.
None if the pool is pre-active and Some(<epoch_number>) if active or inactive.None = {pre-active, active}, Some(<epoch_number>) if in-active, and it was de-activated at epoch <epoch_number>.activation_epoch of this pool and contains exchange rates at the beginning of each epoch, i.e., right after the rewards for the previous epoch have been deposited into the pool. key: u64 (epoch number), value: PoolTokenExchangeRateStakedSui object, updated at epoch boundaries.StorageFund
Struct representing the onchain storage fund.
storage_rebate of all objects currently stored on-chain. To maintain this invariant, the only inflow of this balance is storage charges collected from transactions, and the only outflow is storage rebates of transactions, including both the portion refunded to the transaction senders as well as the non-refundable portion taken out and put into non_refundable_balance.SystemParameters
validator_low_stake_threshold for this many epochs before being kicked out.validator_low_stake_threshold are considered to have low stake and will be escorted out of the validator set after being below this threshold for more than validator_low_stake_grace_period number of epochs.validator_very_low_stake_threshold will be removed immediately at epoch change, no grace period.SystemState
safe_mode_ are accumulated during safe mode when advance_epoch_safe_mode is executed. They will eventually be processed once we are out of safe mode.Validator
Definition of a Validator in the system contracts
Note: fields of ValidatorMetadata are flattened into this type
ValidatorMetadata structValidatorReportRecord
reportedValidatorSet
active_validators it is added to this table so that stakers can continue to withdraw their stake from it. key: address (staking pool Id), value: 0x3::validator_wrapper::ValidatorWrapperactive_validators.advance_epoch function.Validator structs. When an address calls request_add_validator_candidate, they get added to this table and become a preactive validator. When the candidate has met the min stake requirement, they can call request_add_validator to officially add them to the active validator set active_validators next epoch. key: address (sui address of the validator), value: 0x3::validator_wrapper::ValidatorWrapperAtRiskValidatorsEntry
sui/rpc/v2beta2/transaction_execution_service.proto
Messages
ExecuteTransactionRequest
finality.UserSigantures authorizing the execution of the provided transaction.ExecuteTransactionResponse
Response message for NodeService.ExecuteTransaction.
TransactionFinality
Indicates the finality of the executed transaction.
Services (transaction_execution_service.proto)
TransactionExecutionService
sui/rpc/v2beta2/execution_status.proto
Messages
CleverError
CoinDenyListError
CommandArgumentError
An error with an argument to a command.
CongestedObjects
Set of objects that were congested, leading to the transaction's cancellation.
ExecutionError
An error that can occur during the execution of a transaction.
ExecutionStatus
The status of an executed transaction.
IndexError
MoveAbort
MoveLocation
Location in Move bytecode where an error occurred.
PackageUpgradeError
An error with upgrading a package.
SizeError
A size error.
TypeArgumentError
Type argument error.
Enums
CommandArgumentErrorKind
COMMAND_ARGUMENT_ERROR_KIND_UNKNOWNTYPE_MISMATCHINVALID_BCS_BYTESINVALID_USAGE_OF_PURE_ARGUMENTINVALID_ARGUMENT_TO_PRIVATE_ENTRY_FUNCTIONINDEX_OUT_OF_BOUNDSindex field will be set indicating the invalid index value.SECONDARY_INDEX_OUT_OF_BOUNDSindex and subresult fields will be set indicating the invalid index value.INVALID_RESULT_ARITYindex field will be set indicating the invalid index value.INVALID_GAS_COIN_USAGETransferObject command.INVALID_VALUE_USAGEINVALID_OBJECT_BY_VALUEINVALID_OBJECT_BY_MUT_REF&mut.SHARED_OBJECT_OPERATION_NOT_ALLOWEDINVALID_ARGUMENT_ARITYExecutionErrorKind
EXECUTION_ERROR_KIND_UNKNOWNINSUFFICIENT_GASINVALID_GAS_OBJECTGas object.INVARIANT_VIOLATIONFEATURE_NOT_YET_SUPPORTEDOBJECT_TOO_BIGPACKAGE_TOO_BIGCIRCULAR_OBJECT_OWNERSHIPINSUFFICIENT_COIN_BALANCECOIN_BALANCE_OVERFLOWPUBLISH_ERROR_NON_ZERO_ADDRESSSUI_MOVE_VERIFICATION_ERRORMOVE_PRIMITIVE_RUNTIME_ERRORMOVE_ABORTVM_VERIFICATION_OR_DESERIALIZATION_ERRORVM_INVARIANT_VIOLATIONFUNCTION_NOT_FOUNDARITY_MISMATCHTYPE_ARITY_MISMATCHNON_ENTRY_FUNCTION_INVOKEDCOMMAND_ARGUMENT_ERRORTYPE_ARGUMENT_ERRORUNUSED_VALUE_WITHOUT_DROPINVALID_PUBLIC_FUNCTION_RETURN_TYPEINVALID_TRANSFER_OBJECTEFFECTS_TOO_LARGEPUBLISH_UPGRADE_MISSING_DEPENDENCYPUBLISH_UPGRADE_DEPENDENCY_DOWNGRADEPACKAGE_UPGRADE_ERRORWRITTEN_OBJECTS_TOO_LARGECERTIFICATE_DENIEDSUI_MOVE_VERIFICATION_TIMEDOUTSHARED_OBJECT_OPERATION_NOT_ALLOWEDINPUT_OBJECT_DELETEDEXECUTION_CANCELED_DUE_TO_SHARED_OBJECT_CONGESTIONADDRESS_DENIED_FOR_COINCOIN_TYPE_GLOBAL_PAUSEEXECUTION_CANCELED_DUE_TO_RANDOMNESS_UNAVAILABLEMOVE_VECTOR_ELEM_TOO_BIGMOVE_RAW_VALUE_TOO_BIGINVALID_LINKAGEPackageUpgradeErrorKind
PACKAGE_UPGRADE_ERROR_KIND_UNKNOWNUNABLE_TO_FETCH_PACKAGENOT_A_PACKAGEINCOMPATIBLE_UPGRADEDIGEST_DOES_NOT_MATCHUNKNOWN_UPGRADE_POLICYPACKAGE_ID_DOES_NOT_MATCHPackageId in upgrade ticket.TypeArgumentErrorKind
TYPE_ARGUMENT_ERROR_KIND_UNKNOWNTYPE_NOT_FOUNDCONSTRAINT_NOT_SATISFIEDsui/rpc/v2beta2/move_package_service.proto
Messages
GetDatatypeRequest
GetDatatypeResponse
GetFunctionRequest
GetFunctionResponse
GetPackageRequest
GetPackageResponse
ListPackageVersionsRequest
1000 entries will be returned. The maximum value is 10000; values above 10000 will be coerced to 10000.ListPackageVersions call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListPackageVersions must match the call that provided the page token.ListPackageVersionsResponse
page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.PackageVersion
A simplified representation of a package version
Services (move_package_service.proto)
MovePackageService
sui/rpc/v2beta2/checkpoint.proto
Messages
Checkpoint
sui/rpc/v2beta2/ledger_service.proto
Messages
BatchGetObjectsRequest
object_id,version,digest.BatchGetObjectsResponse
BatchGetTransactionsRequest
object_id,version,digest.BatchGetTransactionsResponse
GetCheckpointRequest
object_id,version,digest.GetCheckpointResponse
GetEpochRequest
epoch.GetEpochResponse
GetObjectRequest
object_id,version,digest.GetObjectResponse
GetObjectResult
GetServiceInfoRequest
GetServiceInfoResponse
mainnet, testnet, and so on.GetTransactionRequest
digest.GetTransactionResponse
GetTransactionResult
Services (ledger_service.proto)
LedgerService
sui/rpc/v2beta2/signature_verification_service.proto
Messages
VerifySignatureRequest
PersonalMessage and TransactionData and the Bcs.name must be set to indicate which type of message is being verified.VerifySignatureResponse
is_valid is false, this is the reason for why the signature verification failed.Services (signature_verification_service.proto)
SignatureVerificationService
sui/rpc/v2beta2/checkpoint_contents.proto
Messages
CheckpointContents
The committed to contents of a checkpoint.
CheckpointedTransactionInfo
Transaction information committed to in a checkpoint.
sui/rpc/v2beta2/effects.proto
Messages
ChangedObject
Input/output state of an object that was changed during execution.
TransactionEffects
The effects of executing a transaction.
None if the transaction does not emit any event.changed_objects vector. System transaction that don't require gas will leave this as None.UnchangedSharedObject
A shared object that wasn't changed during execution.
Enums
IdOperation
ID_OPERATION_UNKNOWNNONECREATEDDELETEDInputObjectState
INPUT_OBJECT_STATE_UNKNOWNINPUT_OBJECT_STATE_DOES_NOT_EXISTINPUT_OBJECT_STATE_EXISTSOutputObjectState
OUTPUT_OBJECT_STATE_UNKNOWNOUTPUT_OBJECT_STATE_DOES_NOT_EXISTOUTPUT_OBJECT_STATE_OBJECT_WRITEOUTPUT_OBJECT_STATE_PACKAGE_WRITEUnchangedSharedObjectKind
UNCHANGED_SHARED_OBJECT_KIND_UNKNOWNREAD_ONLY_ROOTMUTATE_DELETEDREAD_DELETEDCANCELEDPER_EPOCH_CONFIGsui/rpc/v2beta2/object.proto
Messages
Object
An object on the Sui blockchain.
sui/rpc/v2beta2/error_reason.proto
Enums
ErrorReason
ERROR_REASON_UNKNOWNFIELD_INVALIDFIELD_MISSINGsui/rpc/v2beta2/signature.proto
Messages
CircomG1
A G1 point.
CircomG2
A G2 point.
MultisigAggregatedSignature
Aggregated signature from members of a multisig committee.
MultisigCommittee
A multisig committee.
MultisigMember
A member in a multisig committee.
MultisigMemberPublicKey
Set of valid public keys for multisig committee members.
MultisigMemberSignature
A signature from a member of a multisig committee.
PasskeyAuthenticator
A passkey authenticator.
See
struct.PasskeyAuthenticator
for more information on the requirements on the shape of the
client_data_json field.
SimpleSignature
Either an ed25519, secp256k1 or secp256r1 signature
UserSignature
A signature from a user.
MULTISIG.PASSKEY.ZKLOGIN.ValidatorAggregatedSignature
An aggregated signature from multiple validators.
ValidatorCommittee from this epoch to verify this signature.ValidatorCommittee
The validator set for a particular epoch.
ValidatorCommitteeMember
A member of a validator committee.
ZkLoginAuthenticator
A zklogin authenticator.
ZkLoginClaim
A claim of the iss in a zklogin proof.
ZkLoginInputs
A zklogin groth16 proof and the required inputs to perform proof verification.
ZkLoginProof
A zklogin groth16 proof.
ZkLoginPublicIdentifier
Public key equivalent for zklogin authenticators.
sui/rpc/v2beta2/bcs.proto
Messages
Bcs
Bcs contains an arbitrary type that is serialized using the
BCS
format as well as a name that identifies the type of the serialized value.
sui/rpc/v2beta2/gas_cost_summary.proto
Messages
GasCostSummary
Summary of gas charges.
sui/rpc/v2beta2/signature_scheme.proto
Enums
SignatureScheme
ED25519SECP256K1SECP256R1MULTISIGBLS12381ZKLOGINPASSKEYgoogle/rpc/error_details.proto
Messages
BadRequest
Describes violations in a client request. This error type focuses on the syntactic aspects of the request.
FieldViolation
A message type used to describe a single bad request field.
text,json message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } optional string email = 1; repeated EmailType type = 2; } string full_name = 1; repeated EmailAddress email_addresses = 2; } In this example, in proto field could take one of the following values: * full_name for a violation in the full_name value * email_addresses[1].email for a violation in the email field of the first email_addresses message * email_addresses[3].type[2] for a violation in the second type value in the third email_addresses message. In JSON, the same values are represented as: * fullName for a violation in the fullName value * emailAddresses[1].email for a violation in the email field of the first emailAddresses message * emailAddresses[3].type[2] for a violation in the second type value in the third emailAddresses message.[A-Z][A-Z0-9_]+[A-Z0-9], which represents UPPER_SNAKE_CASE.DebugInfo
Describes additional debugging info.
ErrorInfo
Describes the cause of the error with structured details.
Example of an error when contacting the "pubsub.googleapis.com" API when it is not enabled:
{ "reason": "API_DISABLED"
"domain": "googleapis.com"
"metadata": {
"resource": "projects/123",
"service": "pubsub.googleapis.com"
}
}
This response indicates that the pubsub.googleapis.com API is not enabled.
Example of an error that is returned when attempting to create a Spanner instance in a region that is out of stock:
{ "reason": "STOCKOUT"
"domain": "spanner.googleapis.com",
"metadata": {
"availableRegions": "us-central1,us-east2"
}
}
[a-z][a-zA-Z0-9-_]+ but should ideally be lowerCamelCase. Also, they must be limited to 64 characters in length. When identifying the current value of an exceeded limit, the units should be contained in the key, not the value. For example, rather than {"instanceLimit": "100/request"}, should be returned as, {"instanceLimitPerRequest": "100"}, if the client exceeds the number of instances that can be created in a single (batch) request.[A-Z][A-Z0-9_]+[A-Z0-9], which represents UPPER_SNAKE_CASE.MetadataEntry
Help
Provides links to documentation or for performing an out of band action.
For example, if a quota check failed with an error indicating the calling project hasn't enabled the accessed service, this can contain a URL pointing directly to the right place in the developer console to flip the bit.
Link
Describes a URL link.
LocalizedMessage
Provides a localized error message that is safe to return to the user which can be attached to an RPC error.
PreconditionFailure
Describes what preconditions have failed.
For example, if an RPC failed because it required the Terms of Service to be acknowledged, it could list the terms of service violation in the PreconditionFailure message.
Violation
A message type used to describe a single precondition failure.
QuotaFailure
Describes how a quota check failed.
For example if a daily limit was exceeded for the calling project,
a service could respond with a QuotaFailure detail containing the project
id and the description of the quota limit that was exceeded. If the
calling project hasn't enabled the service in the developer console, then
a service could respond with the project id and set service_disabled
to true.
Also see RetryInfo and Help types for other details about handling a quota failure.
Violation
A message type used to describe a single quota violation. For example, a daily quota or a custom quota that was exceeded.
clientip:<ip address of client> or project:<Google developer project id>.RequestInfo
Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback.
ResourceInfo
Describes the resource that is being accessed.
writer permission on the developer console project.user:<owner email> or project:<Google developer project id>.RetryInfo
Describes when the clients can retry a failed request. Clients could ignore the recommendation here or retry when this information is missing from error responses.
It's always recommended that clients should use exponential backoff when retrying.
Clients should wait until retry_delay amount of time has passed since
receiving the error response before retrying. If retrying requests also
fail, clients should use an exponential backoff scheme to gradually increase
the delay between retries based on retry_delay, until either a maximum
number of retries have been reached or a maximum retry delay cap has been
reached.
google/rpc/status.proto
Messages
Status
The Status type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It is
used by gRPC. Each Status message contains
three pieces of data: error code, error message, and error details.
You can find out more about this error model and how to work with it in the API Design Guide.
google/protobuf/struct.proto
Messages
ListValue
ListValue is a wrapper around a repeated field of values.
The JSON representation for ListValue is JSON array.
Struct
Struct represents a structured data value, consisting of fields
which map to dynamically typed values. In some languages, Struct
might be supported by a native representation. For example, in
scripting languages like JS a struct is represented as an
object. The details of that representation are described together
with the proto support for the language.
The JSON representation for Struct is JSON object.
FieldsEntry
Value
Value represents a dynamically typed value which can be either
null, a number, a string, a boolean, a recursive struct value, or a
list of values. A producer of value is expected to set one of these
variants. Absence of any variant indicates an error.
The JSON representation for Value is JSON value.
Value.Enums
NullValue
NullValue is a singleton enumeration to represent the null value for the Value type union. The JSON representation for NullValue is JSON null.NULL_VALUEgoogle/protobuf/field_mask.proto
Messages
FieldMask
FieldMask represents a set of symbolic field paths, for example:
paths: "f.a" paths: "f.b.d"
Here f represents a field in some root message, a and b
fields in the message found in f, and d a field found in the
message in f.b.
Field masks are used to specify a subset of fields that should be returned by a get operation or modified by an update operation. Field masks also have a custom JSON encoding (see below).
Field Masks in Projections
When used in the context of a projection, a response message or sub-message is filtered by the API to only contain those fields as specified in the mask. For example, if the mask in the previous example is applied to a response message as follows:
f { a : 22 b { d : 1 x : 2 } y : 13 } z: 8
The result will not contain specific values for fields x,y and z (their value will be set to the default, and omitted in proto text output):
f { a : 22 b { d : 1 } }
A repeated field is not allowed except at the last position of a paths string.
If a FieldMask object is not present in a get operation, the operation applies to all fields (as if a FieldMask of all fields had been specified).
Note that a field mask does not necessarily apply to the top-level response message. In case of a REST get operation, the field mask applies directly to the response, but in case of a REST list operation, the mask instead applies to each individual message in the returned resource list. In case of a REST custom method, other definitions may be used. Where the mask applies will be clearly documented together with its declaration in the API. In any case, the effect on the returned resource/resources is required behavior for APIs.
Field Masks in Update Operations
A field mask in update operations specifies which fields of the targeted resource are going to be updated. The API is required to only change the values of the fields as specified in the mask and leave the others untouched. If a resource is passed in to describe the updated values, the API ignores the values of all fields not covered by the mask.
If a repeated field is specified for an update operation, new values will
be appended to the existing repeated field in the target resource. Note that
a repeated field is only allowed in the last position of a paths string.
If a sub-message is specified in the last position of the field mask for an update operation, then new value will be merged into the existing sub-message in the target resource.
For example, given the target message:
f { b { d: 1 x: 2 } c: [1] }
And an update message:
f { b { d: 10 } c: [2] }
then if the field mask is:
paths: ["f.b", "f.c"]
then the result will be:
f { b { d: 10 x: 2 } c: [1, 2] }
An implementation may provide options to override this default behavior for repeated and message fields.
In order to reset a field's value to the default, the field must be in the mask and set to the default value in the provided resource. Hence, in order to reset all fields of a resource, provide a default instance of the resource and set all fields in the mask, or do not provide a mask as described below.
If a field mask is not present on update, the operation applies to all fields (as if a field mask of all fields has been specified). Note that in the presence of schema evolution, this may mean that fields the client does not know and has therefore not filled into the request will be reset to their default. If this is unwanted behavior, a specific service may require a client to always specify a field mask, producing an error if not.
As with get operations, the location of the resource which describes the updated values in the request message depends on the operation kind. In any case, the effect of the field mask is required to be honored by the API.
Considerations for HTTP REST
The HTTP kind of an update operation which uses a field mask must be set to PATCH instead of PUT in order to satisfy HTTP semantics (PUT must only be used for full updates).
JSON Encoding of Field Masks
In JSON, a field mask is encoded as a single string where paths are separated by a comma. Fields name in each path are converted to/from lower-camel naming conventions.
As an example, consider the following message declarations:
message Profile { User user = 1; Photo photo = 2; } message User { string display_name = 1; string address = 2; }
In proto a field mask for Profile may look as such:
mask { paths: "user.display_name" paths: "photo" }
In JSON, the same mask is represented as below:
{ mask: "user.displayName,photo" }
Field Masks and Oneof Fields
Field masks treat fields in oneofs just as regular fields. Consider the following message:
message SampleMessage { oneof test_oneof { string name = 4; SubMessage sub_message = 9; } }
The field mask can be:
mask { paths: "name" }
Or:
mask { paths: "sub_message" }
Note that oneof type names ("test_oneof" in this case) cannot be used in paths.
Field Mask Verification
The implementation of any API method which has a FieldMask type field in the
request should verify the included field paths, and return an
INVALID_ARGUMENT error if any path is unmappable.
google/protobuf/timestamp.proto
Messages
Timestamp
A Timestamp represents a point in time independent of any time zone
or calendar, represented as seconds and fractions of seconds at
nanosecond resolution in UTC Epoch time. It is encoded using the
Proleptic Gregorian Calendar which extends the Gregorian calendar
backwards to year one. It is encoded assuming all minutes are 60
seconds long, i.e. leap seconds are "smeared" so that no leap second
table is needed for interpretation. Range is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
Restricting to that range ensures that conversion to
and from RFC 3339 date strings is possible.
See https://www.ietf.org/rfc/rfc3339.txt.
Examples
Example 1: Compute Timestamp from POSIX time().
Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);
Example 2: Compute Timestamp from POSIX gettimeofday().
struct timeval tv;
gettimeofday(&tv, NULL);
Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);
Example 3: Compute Timestamp from Win32 GetSystemTimeAsFileTime().
FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) &#lt;&#lt; 32) | ft.dwLowDateTime;
// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); //
Example 4: Compute Timestamp from Java System.currentTimeMillis().
long millis = System.currentTimeMillis();
Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
.setNanos((int) ((millis % 1000) * 1000000)).build();
Example 5: Compute Timestamp from current time in Python.
timestamp = Timestamp()
timestamp.GetCurrentTime()
JSON Mapping
In JSON format, the Timestamp type is encoded as a string in the
RFC 3339 format. That is, the
format is {year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z
where {year} is always expressed using four digits while {month}, {day},
{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
seconds, which can go up to 9 digits (so up to 1 nanosecond resolution),
are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
is required, though only UTC (as indicated by "Z") is presently supported.
For example, 2017-01-15T01:30:15.01Z encodes 15.01 seconds past
01:30 UTC on January 15, 2017.
In JavaScript, you can convert a Date object to this format using the
standard toISOString()
method. In Python, you can convert a standard datetime.datetime object
to this format using strftime
with the time format spec %Y-%m-%dT%H:%M:%S.%fZ. Likewise, in Java, you
can use the Joda Time's ISODateTimeFormat.dateTime()
to obtain a formatter capable of generating timestamps in this format.
1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.google/protobuf/duration.proto
Messages
Duration
A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.
Examples
Example 1: Compute Duration from two Timestamps in pseudo code.
Timestamp start = ...; Timestamp end = ...; Duration duration = ...;
duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos;
if (duration.seconds &#lt; 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos &#lt; 0) { duration.seconds -= 1; duration.nanos += 1000000000; }
Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
Timestamp start = ...; Duration duration = ...; Timestamp end = ...;
end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos;
if (end.nanos &#lt; 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; }
Example 3: Compute Duration from datetime.timedelta in Python.
td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td)
JSON Mapping
In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".
seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.google/protobuf/empty.proto
Messages
Empty
A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance:
service Foo {
rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}
google/protobuf/any.proto
Messages
Any
Any contains an arbitrary serialized protocol buffer message along with a
URL that describes the type of the serialized message.
Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type.
Example 1: Pack and unpack a message in C++.
Foo foo = ...; Any any; any.PackFrom(foo); ... if (any.UnpackTo(&foo)) { ... }
Example 2: Pack and unpack a message in Java.
Foo foo = ...; Any any = Any.pack(foo); ... if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or ... if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); }
Example 3: Pack and unpack a message in Python.
foo = Foo(...) any = Any() any.Pack(foo) ... if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) ...
Example 4: Pack and unpack a message in Go
foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { ... } ... foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { ... }
The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".
JSON
The JSON representation of an Any value uses the regular
representation of the deserialized, embedded message, with an
additional field @type which contains the type URL. Example:
package google.profile; message Person { string first_name = 1; string last_name = 2; }
{ "@type": "type.googleapis.com/google.profile.Person", "firstName": &#lt;string>, "lastName": &#lt;string> }
If the embedded message type is well-known and has a custom JSON
representation, that representation will be embedded adding a field
value which holds the custom JSON in addition to the @type
field. Example (for message [google.protobuf.Duration][]):
{ "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" }
path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.Scalar Value Types
double
float
int32
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.
int64
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.
uint32
Uses variable-length encoding.
uint64
Uses variable-length encoding.
sint32
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.
sint64
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.
fixed32
Always four bytes. More efficient than uint32 if values are often greater than 2^28.
fixed64
Always eight bytes. More efficient than uint64 if values are often greater than 2^56.
sfixed32
Always four bytes.
sfixed64
Always eight bytes.
bool
string
A string must always contain UTF-8 encoded or 7-bit ASCII text.
bytes
May contain any arbitrary sequence of bytes.