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/argument.proto
Messages
Argument
An argument to a programmable transaction command.
Enums
ArgumentKind
ARGUMENT_KIND_UNKNOWN
GAS
INPUT
ProgrammableTransaction
inputs).RESULT
ProgrammableTransaction
commands).sui/rpc/v2beta2/signature_scheme.proto
Enums
SignatureScheme
ED25519
SECP256K1
SECP256R1
MULTISIG
BLS12381
ZKLOGIN
PASSKEY
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
reported
ValidatorSet
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/ledger_service.proto
Messages
BatchGetObjectsRequest
object_id,version,digest
.BatchGetObjectsResponse
BatchGetTransactionsRequest
digest
.BatchGetTransactionsResponse
GetCheckpointRequest
sequence_number,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/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_UNKNOWN
ADDRESS
OBJECT
SHARED
IMMUTABLE
CONSENSUS_ADDRESS
sui/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/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/live_data_service.proto
Messages
Balance
Balance information for a specific coin type.
CoinMetadata
Metadata for a coin type
0x2::coin::CoinMetadata
object or 0x2::sui::coin_registry::CoinData object (when registered with CoinRegistry).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.parent,field_id
.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.object_id,version,object_type
.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
SupplyState
SUPPLY_STATE_UNKNOWN
FIXED
DynamicFieldKind
DYNAMIC_FIELD_KIND_UNKNOWN
FIELD
OBJECT
TransactionChecks
ENABLED
DISABLED
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_PARAMETER
Package
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_UNKNOWN
COPY
DROP
STORE
KEY
DatatypeKind
DATATYPE_KIND_UNKNOWN
STRUCT
ENUM
Visibility
VISIBILITY_UNKNOWN
PRIVATE
PUBLIC
FRIEND
Reference
REFERENCE_UNKNOWN
IMMUTABLE
MUTABLE
Type
TYPE_UNKNOWN
ADDRESS
BOOL
U8
U16
U32
U64
U128
U256
VECTOR
DATATYPE
TYPE_PARAMETER
sui/rpc/v2beta2/checkpoint.proto
Messages
Checkpoint
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/object.proto
Messages
Object
An object on the Sui blockchain.
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/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/gas_cost_summary.proto
Messages
GasCostSummary
Summary of gas charges.
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/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/object_reference.proto
sui/rpc/v2beta2/transaction_execution_service.proto
Messages
ExecuteTransactionRequest
finality
.UserSiganture
s 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/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
.UnchangedConsensusObject
A consensus object that wasn't changed during execution.
Enums
IdOperation
ID_OPERATION_UNKNOWN
NONE
CREATED
DELETED
InputObjectState
INPUT_OBJECT_STATE_UNKNOWN
INPUT_OBJECT_STATE_DOES_NOT_EXIST
INPUT_OBJECT_STATE_EXISTS
OutputObjectState
OUTPUT_OBJECT_STATE_UNKNOWN
OUTPUT_OBJECT_STATE_DOES_NOT_EXIST
OUTPUT_OBJECT_STATE_OBJECT_WRITE
OUTPUT_OBJECT_STATE_PACKAGE_WRITE
UnchangedConsensusObjectKind
UNCHANGED_CONSENSUS_OBJECT_KIND_UNKNOWN
READ_ONLY_ROOT
MUTATE_CONSENSUS_STREAM_ENDED
READ_CONSENSUS_STREAM_ENDED
CANCELED
PER_EPOCH_CONFIG
sui/rpc/v2beta2/name_service.proto
Messages
LookupNameRequest
@name
as well as name.sui
formats.LookupNameResponse
NameRecord
Field<Domain,NameRecord>
.RegistrationNFT
assigned to this record. The owner of the corrisponding RegistrationNFT
has the rights to be able to change and adjust the target_address
of this domain. It is possible that the ID changes if the record expires and is purchased by someone else.DataEntry
ReverseLookupNameRequest
ReverseLookupNameResponse
Services (name_service.proto)
NameService
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_UNKNOWN
PURE
IMMUTABLE_OR_OWNED
SHARED
RECEIVING
sui/rpc/v2beta2/balance_change.proto
sui/rpc/v2beta2/error_reason.proto
Enums
ErrorReason
ERROR_REASON_UNKNOWN
FIELD_INVALID
FIELD_MISSING
sui/rpc/v2beta2/protocol_config.proto
Messages
ProtocolConfig
AttributesEntry
FeatureFlagsEntry
sui/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.
CheckpointSummary
s 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. CheckpointSummary
s 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_UNKNOWN
ECMH_LIVE_OBJECT_SET
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.