SubscribeEvents - Stream Live Sui Events
Stream filtered live Sui Move events over gRPC with field masks, progress watermarks, and historical gap recovery.
SubscriptionService.SubscribeEvents streams live events from the node's current tip. Use an EventFilter for server-side selection and a field mask to control each event payload.
Method Signature
- Service:
sui.rpc.v2.SubscriptionService - Method:
SubscribeEvents - Type: Server-streaming RPC
Recover after a disconnect
Subscriptions do not resume automatically. Persist watermark.cursor only after processing all earlier matching items.
For event recovery, request both transaction_digest and event_index in the subscription and replay masks.
After reconnecting, buffer live responses. Let firstCursor be the first buffered frame's watermark.cursor and keep it fixed during replay.
Call ListEvents with the same filter and read mask:
- Set
options.afterto the saved, fully processedwatermark.cursor. - Set
options.beforetofirstCursor. - Set
options.limitto the desired page size. - Omit
start_checkpointandend_checkpointfor this cursor-bounded replay.
Process each returned item before advancing saved progress. Inspect the terminal frame's end.reason:
| End reason | Action |
|---|---|
QUERY_END_REASON_ITEM_LIMIT or QUERY_END_REASON_SCAN_LIMIT | Set options.after to the terminal watermark.cursor and fetch the next page. Keep options.before fixed. |
QUERY_END_REASON_LEDGER_TIP | The index trails the live boundary. Resume from the terminal watermark.cursor after indexing advances, with the same options.before. |
QUERY_END_REASON_CURSOR_BOUND | Replay reached the requested boundary. Drain the buffered live responses. |
Other end reasons and RPC errors do not establish completion. Resume from the last fully processed progress after addressing the error.
Use end.reason for completion; watermark.checkpoint can lag at a cursor boundary. Cursors are opaque base64 tokens, so preserve them without arithmetic or lexical comparison.
Deduplicate replay and buffered data by transaction digest and event index before applying downstream effects. Persist progress-only watermarks only after all earlier matching items have been processed.
Recovery beyond the node's retained history requires an archival source or a durable local store.
Related Methods
See the official Sui gRPC schema for the current protobuf definition.
See filter syntax and examples. Filtered subscriptions can send progress-only frames with no item. Persist their watermark after processing all earlier items.
SubscribeTransactions
Stream live Sui transactions over gRPC with field masks, server-side filters, progress watermarks, and gap recovery guidance.
ExecuteTransaction
Execute signed transactions on Sui blockchain via gRPC. Learn how to submit transactions, handle signatures, and verify execution with Dwellir's high-performance infrastructure.