Module watermark 

Shared Watermark construction for the v2 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 completion boundary (checkpoint, the inclusive boundary checkpoint the scan has fully covered in the request’s ordering direction). 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 checkpoint C does NOT prove C complete (more matches may sit at higher/lower transaction or event positions). Their covered bound is advanced before C — see advance_covered_bound_before_checkpoint.
• list_checkpoints dedupes checkpoint numbers, so “checkpoint C emitted” means “checkpoint C complete.” Its item path directly records C; independently resolved frontier candidates are folded with merge_covered_checkpoint_bound.

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

Enums

NaturalRangeEnd

Terminal of a successful list scan that renders as the trailing payload-free QueryEnd frame. ItemLimit never reaches this type: the drive loops fuse it onto the final item frame and suppress the trailing frame. The wire reason and the watermark policy are projections of the same value, so they cannot disagree.

ScanTerminal

Functions

advance_covered_bound_before_checkpoint

Advance the inclusive covered bound using a checkpoint that is not itself proven complete. Transactions, events, and scan frontiers can leave more matches within checkpoint C, so the candidate excludes C: C - 1 ascending and C + 1 descending. The adjusted candidate is then merged by max ascending or 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).

merge_covered_checkpoint_bound

Merge a fully covered checkpoint candidate into the accumulated inclusive bound. The bound advances by max in ascending scans and min in descending scans.

scan_frontier_cursor_cp

Resolve the checkpoint coordinate embedded in a transaction/event/checkpoint scan-frontier cursor independently from the optional completed-checkpoint claim. A missing mapping is representable only at the numeric edge where the frontier itself supplies the sole safe checkpoint coordinate.