Skip to content

LedgerService.ListCheckpoints ​

List checkpoints matching the provided filters.

Checkpoints are returned in ascending or descending checkpoint sequence number order according to the query options ordering. 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.LedgerService/ListCheckpoints. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.

Request: ListCheckpointsRequest ​

Request message for LedgerService.ListCheckpoints.

FieldTypeDescription
read_maskgoogle.protobuf.FieldMaskOptional. Mask for specifying which parts of the Checkpoint should be returned (e.g. summary, contents, signatures).
start_checkpointuint64Optional. Start of the checkpoint range to query (inclusive). Defaults to genesis.
end_checkpointuint64Optional. End of the checkpoint range to query (exclusive). Defaults to the current indexed ledger tip.
filterTransactionFilterOptional. DNF filter over indexed transaction dimensions. A checkpoint matches if any transaction it contains satisfies the filter. If absent, all checkpoints in the range are returned.
optionsQueryOptionsOptional cursor-bounded query options. If unspecified, reads in ascending order with the default item limit. The server enforces a maximum item limit and silently coerces larger values down to it. To paginate, pass the last received Watermark.cursor as options.after (ascending) or options.before (descending) on the next request.

Response: ListCheckpointsResponse ​

Response message for LedgerService.ListCheckpoints. Every frame carries a watermark with a safe resume cursor. A frame with checkpoint set delivers one matching item; a frame without it reports scan progress or terminal completion. Watermarks never regress in the requested ordering but may repeat. end is set exactly once, on the final frame of a successful stream. For QUERY_END_REASON_ITEM_LIMIT, that frame also carries the final item. For every other end reason, the final frame has no checkpoint payload.

FieldTypeDescription
checkpointCheckpointOne matching checkpoint.
watermarkWatermarkProgress watermark as of this frame. Present on every frame. A ScanLimit terminal watermark may repeat the previous frame's cursor when its authoritative scan frontier was already emitted.
endQueryEndSet exactly once, on the final frame of a successful query stream.

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.

Watermark ​

Progress of a scan, carried on every response frame, whether or not the frame delivers a matching item. Watermarks never regress in the requested ordering, but consecutive frames may carry the same watermark when additional work does not advance the safe resume frontier. A watermark has two parts:

  • The resume point, in two forms: cursor, opaque, for the server, and cursor_position, in ledger coordinates, for clients to order frames and drop duplicates. - Coverage: checkpoint, the boundary checkpoint the scan has proven fully covered. It trails the resume point. To continue in the same direction, set the request's start (ascending) or end (descending) at cursor_position. To read in the other direction, set the other bound at cursor_position from a frame without an item; from a frame with an item, start a page after the item at its key with the finest index incremented, or end a page before it at its key. In both cases pass cursor as options.after with a start and as options.before with an end.
FieldTypeDescription
cursorbytesOpaque cursor at the resume point. Set on every watermark. Use as options.after (ascending) or options.before (descending) on the next request to resume from here. The most recently received cursor is always the safe resume point. Pass cursors back unchanged; never compare or inspect them. Cursors that differ can name the same point, and their encoding may change.
checkpointuint64The inclusive boundary checkpoint that the scan has fully covered within the request's effective interval, in the request's ordering direction: an ascending scan has emitted every matching item in the interval at checkpoints <= checkpoint (strictly greater ones may still hold matches); a descending scan has emitted every matching item in the interval at checkpoints >= checkpoint. This boundary never regresses in the scan direction, but it may repeat while the cursor advances. Unset until the scan's first checkpoint is fully covered. For example, a scan resumed from a cursor that lands mid-checkpoint leaves this unset until the next checkpoint boundary in the scan direction is fully covered. A watermark still has a valid resume cursor while this field is unset.
cursor_positionLedgerPositionThe resume point in ledger coordinates. Set on every watermark by servers that support it. Ascending, every match from the request's start up to (excluding) cursor_position has been delivered. Descending, every match from cursor_position up to (excluding) the request's end has been delivered. On a frame that carries an item, ascending, it is the boundary just past the item, so it is not the item's own key: it is that key with its finest index incremented (event_index for events, transaction_index for transactions, checkpoint for checkpoints). Descending, it is the boundary just before the item, which is the item's key. It never moves before the request's start (ascending) or past its end (descending), so an ascending request that starts beyond what the server has indexed gets its start echoed back: the resume point says where the client is, not where the ledger is. cursor may then name an earlier point; bounds intersect, so resuming with both starts at cursor_position.

grpcurl ​

bash
grpcurl -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "read_mask": {
    "paths": [
      "sequence_number",
      "digest"
    ]
  },
  "filter": {
    "terms": [
      {
        "literals": [
          {
            "move_call": {
              "function": "0x0000000000000000000000000000000000000000000000000000000000000003::sui_system::request_add_stake"
            }
          }
        ]
      }
    ]
  },
  "options": {
    "limit": 5,
    "ordering": "ORDERING_DESCENDING"
  }
}' \
  mainnet-grpc.inodra.com:443 \
  sui.rpc.v2.LedgerService/ListCheckpoints

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

TypeScript ​

typescript
import { GrpcTypes, 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.ledgerService.listCheckpoints({
  readMask: { paths: ['sequence_number', 'digest'] },
  filter: {
    terms: [
      {
        literals: [
          {
            negated: false,
            predicate: {
              oneofKind: 'moveCall',
              moveCall: {
                function:
                  '0x0000000000000000000000000000000000000000000000000000000000000003::sui_system::request_add_stake'
              }
            }
          }
        ]
      }
    ]
  },
  options: { limit: 5, ordering: GrpcTypes.Ordering.DESCENDING }
})
for await (const frame of call.responses) {
  if (frame.checkpoint) console.log(frame.checkpoint.sequenceNumber)
}

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

Credits ​

1 credit to open the stream, then 2 credits per streamed message, including watermark-only progress messages and the final message. See credits and billing for the full table.

The full-stack Sui data layer.