SubscriptionService

SubscriptionService provides filtered, real-time streams of checkpoints, transactions, and events.

Each Subscribe API pairs with the LedgerService List API of the same name: requests take the same filter message, and responses carry the same item and watermark shapes with identical cursor semantics.

Subscriptions do not support resumption. A new subscription always begins at the current tip of the chain as seen by the server (the latest executed checkpoint). To recover data missed between subscriptions, replay the gap with the paired List API: pass the last received Watermark.cursor as options.after on the List request (for checkpoints, pass the last received cursor + 1 as start_checkpoint). The List scan reads from the indexed tip, which may trail the subscription's start position; repeat the List call as the index advances until the replay reaches the position established by the subscription's first frame.

A subscription behaves like an unbounded ascending scan: every frame carries the subscriber's resume point, and progress advances as checkpoints are fully covered. Two delivery guarantees keep sparse filters live: the first frame on a filtered subscription is a progress-only frame establishing the stream's start position, and progress continues to advance with bounded staleness even when no item matches.

Subscription streams have no successful end: they run until cancelled by the client or terminated by the server with a gRPC status.