Skip to content

SubscriptionService.SubscribeCheckpoints ​

Subscribe to the stream of checkpoints.

The stream begins at the latest executed checkpoint as seen by the server and yields checkpoints matching the filter as they are executed. A checkpoint matches if any transaction it contains satisfies the filter.

Endpoint ​

NetworkHostAuthentication
Mainnetmainnet-grpc.inodra.com:443x-api-key metadata
Testnettestnet-grpc.inodra.com:443x-api-key metadata

Full method name: sui.rpc.v2.SubscriptionService/SubscribeCheckpoints. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.

Request: SubscribeCheckpointsRequest ​

Request message for SubscriptionService.SubscribeCheckpoints.

FieldTypeDescription
read_maskgoogle.protobuf.FieldMaskOptional. Mask for specifying which parts of the Checkpoint should be returned (e.g. summary, contents, signatures). cursor is always populated and is not subject to the mask.
filterTransactionFilterOptional. DNF filter over indexed transaction dimensions. A checkpoint matches if any transaction it contains satisfies the filter. If absent, every checkpoint is streamed.

Response: SubscribeCheckpointsResponse ​

Response message for SubscriptionService.SubscribeCheckpoints. A checkpoint stream's position is checkpoint-granular, so the cursor sequence number stands in for the Watermark message the other subscription responses carry. Progress-only frames (with checkpoint unset) occur only on filtered streams: on an unfiltered stream every frame carries both fields, in order and without gaps.

FieldTypeDescription
cursoruint64Required. The checkpoint sequence number the stream has fully covered, inclusive: every matching checkpoint from the stream's start position through cursor has been delivered. Present on every frame and advances monotonically.
checkpointCheckpointThe matching checkpoint. Unset when this frame only advances the cursor past non-matching checkpoints.

Checkpoint ​

FieldTypeDescription
sequence_numberuint64The height of this checkpoint.
digeststringThe digest of this Checkpoint's CheckpointSummary.
summaryCheckpointSummaryThe CheckpointSummary for this checkpoint.
signatureValidatorAggregatedSignatureAn aggregated quorum signature from the validator committee that certified this checkpoint.
contentsCheckpointContentsThe CheckpointContents for this checkpoint.
transactionsrepeated ExecutedTransactionList of transactions included in this checkpoint.
objectsObjectSetSet of objects either referenced as inputs or produced as outputs by transactions included in this checkpoint. In order to benefit from deduplication of objects that appear in multiple transactions in this checkpoint, objects will only be present here and the transactions.objects field will not be populated.

grpcurl ​

bash
grpcurl -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "read_mask": {
    "paths": [
      "sequence_number",
      "digest"
    ]
  }
}' \
  mainnet-grpc.inodra.com:443 \
  sui.rpc.v2.SubscriptionService/SubscribeCheckpoints

Server reflection is enabled, so no proto files are needed for grpcurl. Field masks are written as {"paths": [...]}.

TypeScript ​

typescript
import { GrpcWebFetchTransport, SuiGrpcClient } from '@mysten/sui/grpc'

const transport = new GrpcWebFetchTransport({
  baseUrl: 'https://mainnet-grpc.inodra.com',
  meta: { 'x-api-key': process.env.INODRA_API_KEY! }
})
const client = new SuiGrpcClient({ network: 'mainnet', transport })

const call = client.subscriptionService.subscribeCheckpoints({
  readMask: { paths: ['sequence_number', 'digest'] }
})
for await (const frame of call.responses) {
  console.log(frame.checkpoint?.sequenceNumber)
}

@mysten/sui v2 has no typed method for this RPC, so the sample calls the generated client.subscriptionService service client. Install with npm install @mysten/sui and set INODRA_API_KEY. The gRPC gateway guide covers native gRPC transport for backends.

Credits ​

Billed by volume: 5 credits to open the stream, then 1 credit per 50 KB of encoded message with a 1-credit minimum per message (20 credits per MB). A full mainnet checkpoint without a mask is about 400 KB, roughly 8 credits; a read_mask that keeps only what you need brings a message down to the minimum. See credits and billing for the full table.

The full-stack Sui data layer.