Module watermark 

Shared Watermark construction for the v2alpha list APIs.

Both ledger-history backends — the fullnode (sui-rpc-api) and bigtable (sui-kv-rpc) — and all three list handlers (list_transactions, list_events, list_checkpoints) emit the same wire Watermark: a resume cursor plus a direction-matching completion boundary (checkpoint_hi ascending / checkpoint_lo descending). The cursor encoding and the boundary bookkeeping are identical; what differs per API is how a scan position resolves into a completion-boundary candidate:

• list_transactions / list_events scan within a checkpoint, so an item at cp C does NOT prove C complete (more matches may sit at higher/lower tx_seqs / event_seqs). Their boundary candidate is C ∓ 1 — see advance_boundary_excluding_cp.
• list_checkpoints dedupes cp_seq, so “cp C emitted” ≡ “cp C complete.” It feeds C straight into advance_checkpoint_boundary for items, and translates its scan frontier into a cp-space candidate itself before doing the same.

This module owns the shared pieces; each handler keeps only its API-specific frontier-to-candidate adapter.

Functions

advance_boundary_excluding_cp

Fold a cp whose own checkpoint is NOT proven complete into the accumulated boundary (list_transactions / list_events: cp C may still hold further matches at other tx_seqs / event_seqs; and any scan frontier, which lands partway through the checkpoint it resolves to). The boundary excludes C itself: C - 1 ascending / C + 1 descending.

advance_checkpoint_boundary

Fold an already-resolved completion-boundary candidate into the accumulated boundary, keeping the most-advanced value in scan direction: the max ascending, the min descending.

boundary_cursor_cp

Resolve the boundary-cursor checkpoint coordinate for a list_transactions / list_events scan frontier. The cursor encoding is asymmetric: ascending Boundary cursors advance the cp-range start, so the frontier cp is used directly; descending Boundary cursors treat the cp coordinate as an EXCLUSIVE upper bound, so cp + 1 is needed to keep cp itself included on resume.

boundary_watermark

Build a standalone scan-frontier Watermark. cursor_cp / position are the boundary cursor coordinates the caller has already resolved for its scan domain (see boundary_cursor_cp for the per-checkpoint scanners’ direction adjustment); boundary is the accumulated completion boundary.

item_watermark

Build the embedded Watermark for an item: the cursor encodes this item’s position (so the next request’s after/before resumes past it) plus the current direction-matching checkpoint boundary. cp / position are the item’s cursor coordinates (list_checkpoints passes its cp_seq for both).

reached_range_end

Whether the scan reached the natural end of the requested range (the ledger tip or a requested end_checkpoint) rather than being truncated by an item or scan limit, or bounded by a client cursor. Only natural completion proves the range’s final checkpoint complete.

terminal_boundary_watermark

Boundary watermark emitted once a scan has drained its entire resolved range under natural completion. Unlike per-item watermarks it can claim the range’s final checkpoint complete — end_checkpoint - 1 ascending (the exclusive cp upper) or end_checkpoint descending (the inclusive cp lower) — because no further items exist in it within the requested range. The (end_checkpoint, end_position) cursor resumes exactly past the scanned range.