Expand description
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, the same resume point in ledger coordinates (cursor_position, a
LedgerPoint), and 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_eventsscan within a checkpoint, so an item at checkpointCdoes NOT proveCcomplete (more matches may sit at higher/lower transaction or event positions). Their covered bound is advanced beforeC— seeadvance_covered_bound_before_checkpoint.list_checkpointsdedupes checkpoint numbers, so “checkpointCemitted” means “checkpointCcomplete.” Its item path directly recordsC; independently resolved frontier candidates are folded withmerge_covered_checkpoint_bound.
This module owns the shared pieces; each handler keeps only its API-specific frontier-to-candidate adapter.
Structs§
- Range
End - Where a list scan ends once it drains its resolved range, as its terminal frame renders it
(see
ResolvedScan::range_end).
Enums§
- Natural
Range End - Terminal of a successful list scan that renders as the trailing
payload-free
QueryEndframe.ItemLimitnever 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. - Scan
Terminal
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 excludesC:C - 1ascending andC + 1descending. The adjusted candidate is then merged by max ascending or min descending. - boundary_
cursor_ cp - Resolve the checkpoint coordinate of a
list_checkpointsboundary cursor at a scan frontier inside checkpointcp. The cursor encoding is asymmetric: ascendingBoundarycursors resume at their checkpoint, so the frontier cp is used directly; descendingBoundarycursors treat the checkpoint as an EXCLUSIVE upper bound, socp + 1is needed to keepcpitself included on resume. - boundary_
watermark - Build a standalone scan-frontier
Watermark.positionis the boundary cursor coordinates the caller has already resolved for its scan domain (seeboundary_cursor_cpfor the checkpoint scanners’ direction adjustment), whose public position is where the frame resumes;boundarythe accumulated completion boundary. - item_
watermark - Build the embedded
Watermarkfor an item: the cursor encodes this item’s position (so the next request’safter/beforeresumes past it) plus the current direction-matching checkpoint boundary.positionis the item’s cursor coordinates (list_checkpointspasses its cp_seq), whose public position is the item’s key in ledger coordinates; the frame’scursor_positionfollows from it (seePosition::item_resume). - 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.