We’re happy to announce the launch of the Sui GraphQL RPC service, as part of our ongoing efforts to provide the best web3 infrastructure and developer experience. This MVP is available for mainnet
and testnet
networks.
Getting Started
Mainnet online IDE: https://sui-mainnet.mystenlabs.com/graphql
Testnet online IDE: https://sui-testnet.mystenlabs.com/graphql
Documentation:
- Getting started: https://docs.sui.io/guides/developer/getting-started/graphql-rpc
- Concepts: https://docs.sui.io/concepts/graphql-rpc
- Reference API: https://docs.sui.io/references/sui-graphql
The online IDE provides an interactive experience by offering auto-completion (use Ctrl+Space) and in-built documentation (click on the book-like icon on the top left). The Getting Started documentation has a number of examples that you can use to get started. Note that any addresses or object IDs in the examples correspond to the mainnet
data.
Upcoming Breaking Changes
Please note that we expect to be landing breaking changes to the schema on most of the upcoming major releases (every 3 months), while we’re continuing the development and improvements for this service.
Releases and Timeline
The first version of RPC 2.0 is released as 2024-1.0. This version of the RPC supports all MVP features in the proposed schema and it is deployed by Mysten Labs and shared with third-party RPC providers for integration into their services.
There will be two types of releases: major (every 3 months), and minor (every 2 weeks with bug-fixes). Major releases will be announced and will likely contain breaking changes. The next major release is at the end of Q1’24. In between major releases, we will have patch releases every two weeks.
Each RPC major version will receive 6 months of support for bugfixes. Publicly available Mysten-operated RPC instances will also continue to provide access to an RPC version for 6 months after its initial release. Clients that continue to use versions older than 6 months will be automatically routed to the oldest supported version by the public Mysten RPC instances. E.g. clients who continue to use 2023-10.x
past the release of 2024-04.y
will automatically be served responses by 2024-01.z
to limit the number of versions an RPC provider needs to support.
Setting Versions
API versions can be supplied as a header, not including the patch version (e.g. X-Sui-RPC-Version: 2023.10
). If a header is not supplied, the latest released version is assumed.
The response header will include the full version used to respond to the request, including the patch version (e.g. X-Sui-RPC-Version: 2023.10.2
).
Feedback
We welcome feedback that you have, particularly about performance issues, so please post it in this thread.
Disclaimer & Limitations
Please note that this service is offered as is, without a SLA.
The endpoint is rate-limited to avoid congestion and misuse (this service is not intended for production) and it does have some limits on the complexity of the queries one can make. Please use this query to find the current rate limits on the GraphQL queries:
{
serviceConfig {
maxQueryDepth
maxQueryNodes
maxOutputNodes
maxDbQueryCost
defaultPageSize
maxPageSize
requestTimeoutMs
maxQueryPayloadSize
maxTypeArgumentDepth
maxTypeArgumentWidth
maxTypeNodes
maxMoveValueDepth
}
}
By default, there is a query timeout of 15s. If the time limit is exceeded, the query is stopped and an error is returned.
There are a few unsupported features and/or limitations for this MVP launch:
- Subscriptions are not supported.
- Queries requesting stake related information might be a bit slower or fail the first time, depending on an internal cache. If it fails, try again after a couple of minutes.
- Some performance optimizations are still in progress, thus some queries may be slower than expected. Please let us know if you encounter such issues.
- Consistency between queries for disparate fields in the same GraphQL request are a work in progress, so there may be some rare opportunities for inconsistencies to appear in such cases.
CHANGELOG
Bug Fixes
- Fixed the order in which transaction blocks were returned when paginating backwards.
#15661 - Fixed bugs where the lamport version for object changes would incorrectly report
null
.
#15040
Breaking Changes
Pagination
Fields that return variable length output have been systematically refactored:
- Fields that were already paginated have been renamed to remove the
Connection
suffix from their name (e.g.coinConnection
becomescoins
), but not their type (coins
still returns aCoinConnection
). - Cursor values are now all obfuscated.
- Paginated fields now all support forward and backward pagination, with accurate previous an next page detection.
- Fields that previously returned arrays have been updated to return a paginated response.
#15933, #15782, #15749, #15721, #15712, #15661, #15528, #15586, #15526, #15525, #15524, #15485, #15484, #15475, #15474, #15473, #15472, #15471, #15470, #15467
Additionally, the service enforces a new “output node estimate” limit, which calculates an estimate of how large the query output will be (accounting for page limits on paginated fields), and enforces a limit on this.
Removal of Explicit Upcasts
Operations that offered explicitly upcasts, such as Coin.asMoveObject
, MoveObject.asObject
, etc have been replaced by interfaces that allow the user to query fields from MoveObject
on its sub-types (like Coin
). The newly introduced interfaces are:
IOwner
IObject
IMoveObject
These interfaces are cascading, so a Coin
implements all three, and can access fields on MoveObject
, Object
, and Owner
without explicitly upcasting to them.
Epoch and System State
- The last
Checkpoint
in the epoch no longer exposesEndOfEpochData
– this information is exposed viaEpoch
instead.
#15522 SystemStateSummary
has been merged intoEpoch
.
#15489
Transactions
- Removed the
SENT
andPAID
enum variants fromAddressTransactionBlockRelationship
, to be added back when their associated queries can be implemented efficiently.
#15661 - The
sender
field forTransactionBlock
andEvent
will now returnnull
if the transaction in question was sent by the system (instead of0x0
).
#15580, #15147 - Simplified
TransactionBlock.signatures
to be just a Base64 blob, and not a dedicated type with a single Base64 field.
#15145 - Improved the format for
TransactionBlockEffects.errors
, to be more human readable.
#15039
Cascading Filters
Filters, like ObjectFilter
, EventFilter
, and TransactionBlockFilter
that included constraints on modules and types have collapsed the fields relevant to those queries into
one.
For example, EventFilter.eventPackage
, EventFilter.eventModule
, EventFilter.eventType
have been replaced with a single EventFilter.eventType
filter, that expects one of the following formats:
package
, matching all types in the package.package::module
, matching all types in the module.package::module::Type
, matching the type or all type instantiations of the type.package::module::Type<TypeParams, ...>
, matching a specific type instantiation.
#15712, #15661, #15303, #15200
Filter Intersection
Previously, in the case of nested queries, where the filter in the nested query conflicted with a filter implied by its context, the filter implied by the context would override the inner filter:
query {
address(address: "X") {
transactionBlocks(filter: { signAddress: "Y" }) {
nodes { digest }
}
}
}
This behavior has been changed so that such that filters are always intersected. This means the above query would return no results, rather than ignore the signAddress
filter parameter.
Renamed Fields
Various field names have been revised in response to feedback during RPC 1.5:
IOwner.defaultNameServiceName
has been renamed todefaultSuinsName
.
#15761Query.resolveNameServiceAddress
has been renamed toresolveSuinsName
.
#15760Event.senders
has been renamed toEvent.sender
as a transaction can currently only have one sender.
#15580- A number of fields have been renamed to use
camelCase
formatting:queryPayload
(show-usage extension),typeParameters
in various Move Type-related scalars.
#15574 - References to
struct
in type definitions, signatures, etc have been renamed todatatype
in preparation for enum support in Move.
#15549 Checkpoint.validatorSignature
has been renamed toCheckpoint.validatorSignatures
as it contains multiple signatures.
#15522StakedSui.activeEpoch
andStakedSui.requestEpoch
were renamed to past tense.
#15329- Renamed
location
toaddress
, everywhere.
#15196
Object Ownership
IOwner.objects
now returns pages ofMoveObject
s, rather thanObject
, becauseMovePackage
s are immutable and therefore not owned by any other entity.
#15804Object.kind
andObject.owner
have been merged into a singleIObject.owner
field that specifies whether an object is address-owned, immutable, shared, or a child object, and based on context, also includes the owner address/object or the initial shared version in case of shared objects.
#15569
Error codes
Certain user errors, related to input parsing issues no longer produce an error code indicating that the issue is a user error. This is a known issue which will be addressed in a future patch
release. This issue affects the parsing of SuiNS domains, types, type filters, and Base58 digests.
#15781, #15760, #15749, #15527
Directives
Unrecognized directives will cause the request to produce an error. The GraphQL service explicitly supports the @skip
and @include
directives.
New Features
Transaction Execution
- Implemented
Mutation.executeTransactionBlock
as per the proposed schema.
#15820, #15118 - Implemented
Query.dryRunTransactionBlock
. Theepoch
parameter has been removed from this API as it was not used downstream.
#15717
Historical Reads and Consistency
TransactionBlock.gasPayments
returns the gas objects at the version they were used as payment, not their latest version.
#15721Object
queries that filter on version can now access historical data, for a limited window of time (the available range), as opposed to always returning the latest versions of objects.
#15967, #15958, #15963, #15932, #15931, #15915, #15914- Implemented consistent pagination: Fetching further pages for a paginated response will continue to return results from the state of the chain at the point the first page was fetched, and will not reflect changes that were indexed in more recent checkpoints, as long as the checkpoint at the start of the range remains in the available range (5 to 15 minute historical window).
#16006, #15996, #15962, #15961, #15960, #15959
Epoch
- Added per-epoch stats (checkpoint count, gas fees, stake rewards and subsidies).
#14979 - Moved
liveObjectDigest
fromCheckpoint
toEpoch
. #15993 - Implemented
totalTransactions
. #15993
MoveObject
- Implemented
asSuinsRegistration
to attempt to downcast aMoveObject
to aSuinsRegistration
.
#15760
MovePackage
- Removed
MoveModuleId
replaced systematically withMoveModule
.
#15020 - Implemented
MoveModule
according to draft schema.
#15018, #15016, #15015, #15013 - Implemented
MoveStruct
according to draft schema.
#14974
MoveType
- Included type information for structs in type layouts.
#15409 - Implemented
abilities
field that exposes the concrete abilities of a given type.
#15407
MoveValue
- Special case the representation
0x2::object::ID
to match the representation ofUID
andaddress
in the JSON representation of Move Values.
#15408
Object
- Implemented
receivedTransactionBlocks
, which is similar toAddress.transactionBlocks
but specialised to only fetch the transactions that sent objects to this object (as objects cannot sign transactions).
#15823 - Implemented support for the
ObjectFilter.objectKeys
filter to filter for objects of a specific version.
#15712 - Implemented
display
.
#15391
Owner
- Implemented
asObject
to attempt to downcast an Owner (which could be an object or an address), to an object.
#15826 - Implements
suinsRegistrations
to list the SuiNS Registration NFTs owned by an entity.
#15390
Query
- Implemented
availableRange
which indicates what range of checkpoints the indexer can produce consistent results for.
#15460, #15219 - Implemented
type
query to look-up information about a particular concrete type (layout, abilities, etc).
#15278
ServiceConfig
- Exposed
maxOutputNodes
#15492 - Exposed limits related to type resolution.
#15442 - Exposed
defaultPageSize
limit, a new configuration distinct frommaxPageSize
.
#15009, #15000
Stake
- Implemented
poolId
. #15993
TransactionBlock
- Implemented support for
TransactionBlockFilter.kind
to filter to just system or programmable transactions.
#15661 - Completed representation of
ProgrammableTransactionBlock
.
#15211, #15188, #15186, #15185, #15184, #15183, #15182, #15179,
#15146, #15095, #15082, #15074, #15043
TransactionBlockEffects
- Implemented support for
TransactionBlockEffects.events
.
#15429 - Implemented
unchangedSharedObjects
to view the shared objects that were read but not modified by the transaction.
#15269
Validator
- Implemented
apy
field, whose type was changed fromFloat
toInt
(basis points).
#15173
ValidatorSet
- Implemented
pendingActiveValidatorsId
,stakingPoolMappingsId
,inactivePoolsId
,validatorCandidatesId
. #15993