Skip to main content

Module watermark

Module watermark 

Source
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_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.

Structs§

RangeEnd
Where a list scan ends once it drains its resolved range, as its terminal frame renders it (see ResolvedScan::range_end).

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 checkpoint coordinate of a list_checkpoints boundary cursor at a scan frontier inside checkpoint cp. The cursor encoding is asymmetric: ascending Boundary cursors resume at their checkpoint, so the frontier cp is used directly; descending Boundary cursors treat the checkpoint 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. position is the boundary cursor coordinates the caller has already resolved for its scan domain (see boundary_cursor_cp for the checkpoint scanners’ direction adjustment), whose public position is where the frame resumes; boundary 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. position is the item’s cursor coordinates (list_checkpoints passes its cp_seq), whose public position is the item’s key in ledger coordinates; the frame’s cursor_position follows from it (see Position::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.