SubscribeCheckpoints - Real-Time Checkpoint Streaming
Stream finalized Sui checkpoints with the gRPC Subscription Service. Learn how field masks, server-side transaction filtering, and gap recovery work.
Sui RPC endpoint: endpoint URLs, plans and pricing.
Stream Finalized Sui Checkpoints
SubscriptionService.SubscribeCheckpoints is a server-streaming RPC that
delivers finalized Sui checkpoints without polling. When a subscription starts,
the server begins with its latest executed checkpoint. While the connection is
active, unfiltered responses arrive in order and without gaps.
Server-side checkpoint filtering
The optional filter is a TransactionFilter. A checkpoint matches if any transaction it contains satisfies that filter. Matching checkpoint payloads can include nonmatching transactions.
Filtered subscriptions can emit progress-only frames containing cursor without checkpoint. Advance covered progress only after processing all earlier matching items.
Method Signature
- Service:
sui.rpc.v2.SubscriptionService - Method:
SubscribeCheckpoints - Type: Server-streaming RPC
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
const ENDPOINT = 'api-sui-mainnet-full.n.dwellir.com:443';
const API_TOKEN = 'your_api_token_here';
const packageDefinition = protoLoader.loadSync(
'./protos/sui/rpc/v2/subscription_service.proto',
{
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true,
includeDirs: ['./protos']
}
);
const descriptor = grpc.loadPackageDefinition(packageDefinition) as any;
const client = new descriptor.sui.rpc.v2.SubscriptionService(
ENDPOINT,
grpc.credentials.createSsl()
);
const metadata = new grpc.Metadata();
metadata.add('x-api-key', API_TOKEN);
const request = {
read_mask: {
paths: [
'sequence_number',
'digest',
'summary.timestamp',
'transactions.digest'
]
}
};
let lastCursor: bigint | undefined;
let processing = Promise.resolve();
const stream = client.SubscribeCheckpoints(request, metadata);
// Abbreviated skeleton: this promise chain preserves order but is an
// unbounded queue. Add bounded backpressure and the reconnect/backfill
// sequence from the guide before using it in a lossless pipeline.
stream.on('data', (response: any) => {
processing = processing.then(() => handleCheckpoint(response)).catch((error) => {
console.error('Checkpoint processing failed:', error);
});
});
async function handleCheckpoint(response: any) {
const cursor = BigInt(response.cursor);
const checkpoint = response.checkpoint;
if (!checkpoint) return;
if (lastCursor !== undefined && cursor <= lastCursor) {
console.log('Skipping duplicate or stale checkpoint', response.cursor);
return;
}
if (lastCursor !== undefined && cursor > lastCursor + 1n) {
reportCheckpointGap(lastCursor + 1n, cursor - 1n);
return;
}
lastCursor = cursor;
console.log({
cursor: response.cursor,
sequenceNumber: checkpoint.sequence_number,
digest: checkpoint.digest,
timestamp: checkpoint.summary?.timestamp
});
}
stream.on('error', (error: grpc.ServiceError) => {
console.error('Stream failed:', error.message);
// Reconnect and historical backfill are intentionally omitted here.
});
function reportCheckpointGap(first: bigint, last: bigint) {
console.warn(
`Gap detected: backfill checkpoints ${first} through ${last} before continuing`
);
}The generated language examples are abbreviated gap-detection skeletons. They show the request and response shapes, but intentionally omit a production reconnect loop, historical fetch implementation, and bounded backpressure. Follow Recover After a Disconnect before using them in a lossless pipeline. Generate all Sui v2 client stubs with the language-specific setup before running the Python example.
The request has two optional fields:
message SubscribeCheckpointsRequest {
optional google.protobuf.FieldMask read_mask = 1;
optional TransactionFilter filter = 2;
}Each streamed response wraps the selected checkpoint data with a cursor:
message SubscribeCheckpointsResponse {
optional uint64 cursor = 1;
optional Checkpoint checkpoint = 2;
}The cursor identifies the checkpoint position in the live stream. It is useful for detecting gaps and deciding where a historical backfill must begin, but it is not a resume cursor that can be supplied to a new subscription.
Choose a Field Mask
A field mask controls response shape, not stream selection. Every active
unfiltered subscription receives one response for every checkpoint. Use filter to select matching checkpoints.
| Monitoring goal | Suggested checkpoint field paths |
|---|---|
| Checkpoint identity and time | sequence_number, digest, summary.timestamp |
| Transaction confirmation | transactions.digest |
| Transactions sent by a wallet | transactions.digest, transactions.transaction.sender |
| Wallet balance changes | transactions.digest, transactions.balance_changes |
| Move calls | transactions.digest, transactions.transaction.kind |
| Emitted events | transactions.digest, transactions.events.events |
| Changed object owners | transactions.digest, transactions.effects.changed_objects |
Tracking every way a wallet can be affected usually requires more than the transaction sender. Include balance changes and changed-object ownership when you need incoming transfers, object mutations, or other indirect effects.
Subscribe with TypeScript
This unfiltered example requests checkpoint identity, timestamp, transaction senders, balance changes, Move commands, and events. It serializes processing, preserves the last successfully processed cursor, and stops live processing when it finds a gap. Add bounded storage for the illustrated buffer in production.
const request = {
read_mask: {
paths: [
'sequence_number',
'digest',
'summary.timestamp',
'transactions.digest',
'transactions.transaction.sender',
'transactions.transaction.kind',
'transactions.balance_changes',
'transactions.events.events'
]
}
};
let lastProcessedCursor: bigint | undefined;
let recovering = false;
const bufferedResponses = [];
let processing = Promise.resolve();
const stream = client.SubscribeCheckpoints(request, metadata);
stream.on('data', (response) => {
processing = processing.then(() => handleCheckpoint(response)).catch((error) => {
console.error('Checkpoint processing failed', error);
});
});
async function handleCheckpoint(response) {
if (recovering) {
bufferedResponses.push(response);
return;
}
const checkpoint = response.checkpoint;
if (!checkpoint) return;
const cursor = BigInt(response.cursor);
if (lastProcessedCursor !== undefined && cursor <= lastProcessedCursor) {
console.log('Skipping duplicate or stale checkpoint', response.cursor);
return;
}
if (lastProcessedCursor !== undefined && cursor > lastProcessedCursor + 1n) {
recovering = true;
bufferedResponses.push(response);
console.warn('Checkpoint gap detected', {
firstMissing: (lastProcessedCursor + 1n).toString(),
lastMissing: (cursor - 1n).toString()
});
// Run the recovery sequence below, then drain bufferedResponses in cursor
// order before clearing recovering.
return;
}
console.log('Checkpoint received', {
cursor: response.cursor,
sequenceNumber: checkpoint.sequence_number,
digest: checkpoint.digest,
timestamp: checkpoint.summary?.timestamp,
transactionCount: checkpoint.transactions?.length ?? 0
});
await processMatchingTransactions(checkpoint);
lastProcessedCursor = cursor;
}
stream.on('error', (error) => {
console.error('Checkpoint stream failed', {
code: error.code,
message: error.message,
lastProcessedCursor: lastProcessedCursor?.toString()
});
});Generated clients can expose protobuf field names differently. The examples on
this page use snake_case, matching clients configured with keepCase: true.
Filter Transactions Client-Side
Use server-side filters for indexed predicates. Apply additional conditions to the transactions inside each returned checkpoint:
function normalizeSuiId(value: string | undefined): string {
if (!value) return '';
const hex = value.toLowerCase().replace(/^0x/, '');
return `0x${hex.padStart(64, '0')}`;
}
const watchedAddress = normalizeSuiId('0x...');
const watchedPackage = normalizeSuiId('0x2');
const watchedModule = 'coin';
const watchedEventType = `${watchedPackage}::${watchedModule}::WatchedEvent`;
async function processMatchingTransactions(checkpoint: any): Promise<void> {
for (const executed of checkpoint.transactions ?? []) {
const sentByWallet =
normalizeSuiId(executed.transaction?.sender) === watchedAddress;
const changedWalletBalance = (executed.balance_changes ?? []).some(
(change: any) =>
normalizeSuiId(change.address) === watchedAddress
);
const calledWatchedModule = (
executed.transaction?.kind?.programmable_transaction?.commands ?? []
).some((command: any) => {
const moveCall = command.move_call;
return (
normalizeSuiId(moveCall?.package) === watchedPackage &&
moveCall?.module === watchedModule
);
});
const emittedWatchedEvent = (executed.events?.events ?? []).some(
(event: any) => {
const emittedByWatchedModule =
normalizeSuiId(event.package_id) === watchedPackage &&
event.module === watchedModule;
const matchesDeclaredEventType = event.event_type === watchedEventType;
return emittedByWatchedModule || matchesDeclaredEventType;
}
);
if (sentByWallet || changedWalletBalance || calledWatchedModule || emittedWatchedEvent) {
await handleMatchingTransaction(executed);
}
}
}event.package_id and event.module identify the top-level Move call that
triggered emission. event.event_type identifies the declared event type.
Those packages can differ, so retain only the predicate that matches the
monitoring requirement.
Field masks keep this processing efficient by omitting transaction signatures, object contents, effects, and other data that the matcher does not need.
Recover After a Disconnect
A new subscription starts at the latest checkpoint known to the server. It does not replay from the previous connection's cursor automatically.
The following sequence and the cursor + 1 gap check apply to the unfiltered examples on this page. They do not apply to a filtered stream, which can skip nonmatching checkpoints.
Use this recovery sequence:
- Persist the last processed cursor or checkpoint sequence number.
- Reconnect with exponential backoff.
- Compare every new cursor with the last processed cursor. Skip a duplicate or
stale response when
cursor <= lastProcessedCursor. - If
cursor > lastProcessedCursor + 1, record the missing range and buffer the gap-detecting response and every later response. Do not process or advance the persisted cursor for any buffered response yet. - Call
LedgerService.GetServiceInfoand inspectlowest_available_checkpoint. If the first missing checkpoint is still retained, fetch each missing checkpoint withLedgerService.GetCheckpoint. - If the gap predates
lowest_available_checkpoint, recover from an archival endpoint or your own durable checkpoint store instead. - Process the backfill in order, then drain buffered live data in cursor order.
Advance
lastProcessedCursoronly after each downstream operation succeeds.
Do not assume a reconnect is lossless. The in-order, gap-free guarantee applies to an active subscription, not across separate connections. A retained full node cannot guarantee lossless recovery after a sufficiently long outage unless an archival endpoint or durable checkpoint store covers the missing range.
Recover a filtered subscription
Persist the last fully covered cursor after processing all earlier matching checkpoints. Cursor-only frames advance coverage without carrying a checkpoint.
After reconnecting, buffer live responses. Let savedCursor be your persisted position and firstCursor be the first buffered response's cursor.
If firstCursor > savedCursor, replay the gap with LedgerService.ListCheckpoints using the same filter and read mask:
- Set
start_checkpointtosavedCursor + 1. - Set
end_checkpointtofirstCursor + 1. The end bound is exclusive, so this includesfirstCursor. - After each response, process any matching checkpoint before persisting its covered progress.
- Read covered progress from
watermark.checkpoint. It can be absent before the scan fully covers its first checkpoint. - For pagination or scan limits, pass the last
watermark.cursorasoptions.afterwhile preserving the checkpoint bounds.
The historical index can trail the live stream. Repeat scans as indexing advances until watermark.checkpoint >= firstCursor; reaching the current indexed tip alone is insufficient.
Then drain buffered responses in cursor order. Skip every response whose cursor is at or below the last covered cursor, including any checkpoint already processed by replay.
Use integer arithmetic for checkpoint cursors. The historical watermark.cursor is an opaque continuation token, distinct from watermark.checkpoint.
A jump between matching checkpoints does not prove data loss. Track covered progress and deduplicate overlap between replay and the live buffer.
Operational Guidance
- Use keepalives appropriate for your client and network path.
- Persist progress only after downstream processing succeeds.
- Apply backpressure instead of dropping checkpoints when processing falls behind.
- Request narrow field masks to reduce serialization work and bandwidth.
- Regenerate clients from the current official Sui protobuf definitions when upgrading API versions.
- Use paired List methods for retained history. Use GraphQL or an archival source for queries beyond the node's retention window.
Related Resources
- GetCheckpoint - Backfill a checkpoint by sequence number
- GetTransaction - Retrieve a transaction by digest
- Sui gRPC documentation - Native Sui concepts and usage
- Sui subscription protobuf - Authoritative request and response schema
Need help with real-time streaming? Contact our support team or review the Sui gRPC overview.
SimulateTransaction
Simulate Sui transactions before execution to preview effects, gas costs, and potential errors via gRPC. Essential for safe transaction building with Dwellir.
SubscribeTransactions
Stream live Sui transactions over gRPC with field masks, server-side filters, progress watermarks, and gap recovery guidance.