Skip to content

[sui-rpc-api][sui-kv-rpc] Rename Event* range elements to IntraTx*, two step resolution from cp range to scan range - #27724

Closed
wlmyng wants to merge 7 commits into
mainfrom
wlmyng/ledger-history-window-resolution
Closed

[sui-rpc-api][sui-kv-rpc] Rename Event* range elements to IntraTx*, two step resolution from cp range to scan range#27724
wlmyng wants to merge 7 commits into
mainfrom
wlmyng/ledger-history-window-resolution

Conversation

@wlmyng

@wlmyng wlmyng commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Description

Initial consolidation of checkpoint-window resolution so a resolved scan is constructed one way and owns its lifecycle identically in sui-rpc-api and usi-kv-rpc.

Every resolve_{tx,event}_range special-cased the empty checkpoint window with an early return. However, this obfuscated the fact that it still performs a checkpoint-summary read to map cp to tx, and hand-built the same record through a second constructor empty_at. These parallel paths had to independently agree, which led to multiple copies and potential drift. One thing to flag is the entry_checkpoint instantiation on an empty window special case (where on descending, entry_checkpoint = terminal_checkpoint, while in the non-empty case it is terminal_checkpoint - 1. Consider an example where [10, 10) descending vs [3, 10) dsecending.)

This special case was eliminated once checkpoint_to_tx_range returned the corresponding [t, t) range for some empty [c, c) range.

Commits

  • e9f503d — kv checkpoint_to_tx_range is empty-safe: [x,x) → [t,t), [0,0) → 0..0, and non-empty windows resolve both boundaries in one batched read. Callers now project checkpoint→tx range unconditionally; since the empty path always did a terminal lookup anyway, this costs nothing.
  • 9b87dd1 — remove the CheckpointRange middleman: every caller immediately resolved it, so ResolvedCheckpointRange::from_request now validates, clamps to the indexed tip, tightens by cursors, and attributes exhaustion in one call.
  • 7015b5f — lane-neutral renames: EventPosition / EventScanBounds / ResolvedEventRange → IntraTxCoordinate / IntraTxScanBounds / ResolvedIntraTxRange. Events are today's only per-transaction-indexed lane, not forever.
  • b9ef884 — ResolvedIntraTxRange::resolve(cp_range, tx_range, options): one constructor replacing empty_at plus the per-call-site struct literals, reducing the ways the record can be built.
  • 464e065 / 8cffd7e — move apply_cursor_bounds from QueryOptions onto ResolvedIntraTxRange / ResolvedRange. Pure move: the resolved record owns its lifecycle, in preparation for a generic range over Bound in the next PR.

Test plan

Existing tests pass.

New unit tests for ResolvedIntraTxRange::resolve

  • empty windows produce the correct record in ascending or descending ordering
  • entry/ terminal
  • cursor application identical

Release notes

Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required.

For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates.

  • Protocol:
  • Nodes (Validators and Full nodes):
  • gRPC:
  • JSON-RPC:
  • GraphQL:
  • CLI:
  • Rust SDK:
  • Indexing Framework:

@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 18:11 — with GitHub Actions Active
@vercel

vercel Bot commented Aug 17, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
sui-docs Ready Ready Preview Aug 18, 2026 6:35pm
2 Skipped Deployments
Project Deployment Actions Updated (UTC)
multisig-toolkit Ignored Ignored Preview Aug 18, 2026 6:35pm
sui-kiosk Ignored Ignored Preview Aug 18, 2026 6:35pm

Request Review

An error occurred while trying to automatically change base from wlmyng/query-options-grouping to main August 17, 2026 18:46
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from 6661544 to 8955013 Compare August 17, 2026 19:25
@github-actions github-actions Bot added the Type: Documentation Improvements or additions to documentation label Aug 17, 2026
wlmyng added 3 commits August 17, 2026 13:38
Same behavior on sui-kv-rpc and sui-rpc-api to unconditionally project
cp to tx range before is_empty() check, since we always do a lookup for
the terminal cursor. This will help eliminate the special case empty_at
for ResolvedXRange, as empty windows instead ride the same projection
path.
CheckpointRange::from_request + .resolve(options) was a two-step every
handler sequenced across two places. ResolvedCheckpointRange::from_request
fuses them into one call — the intermediate struct dissolves, its fields
becoming locals of the fused body; validation, tip clamp, cursor clamps,
and exhaustion attribution are preserved branch for branch.

kv handlers previously validated checkpoint bounds before options; they
now build options first, matching the fullnode order, so on a request
with both invalid the options error wins on both backends.
EventPosition -> IntraTxCoordinate, EventScanBounds -> IntraTxScanBounds,
ResolvedEventRange -> ResolvedIntraTxRange, apply_event_cursor_bounds ->
apply_intra_tx_cursor_bounds. Rust-side vocabulary only — the wire
Position::Events variant and the packed event_seq encoding are untouched.
The coordinate space is (tx_seq, index-within-tx); events are its first
lane, ListPackages the next. Known residue: the coordinate's field is
still named event_index — renaming it is deferred to a compiler-assisted
pass.
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from 2840088 to f972b10 Compare August 17, 2026 20:39
@wlmyng
wlmyng changed the base branch from wlmyng/query-options-grouping to main August 17, 2026 21:02
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 21:06 — with GitHub Actions Active
@github-actions github-actions Bot removed the Type: Documentation Improvements or additions to documentation label Aug 17, 2026
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from 76a2c0c to 7cff068 Compare August 17, 2026 21:13
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 21:13 — with GitHub Actions Active
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 21:18 — with GitHub Actions Active
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from 7deaf25 to e5496d1 Compare August 17, 2026 21:27
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 21:27 — with GitHub Actions Active
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from e5496d1 to db04d7a Compare August 17, 2026 22:16
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 22:17 — with GitHub Actions Active
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from db04d7a to 5906f65 Compare August 17, 2026 22:20
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 22:20 — with GitHub Actions Active
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from 5906f65 to a6ddb1b Compare August 17, 2026 23:32
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 23:32 — with GitHub Actions Active
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from a6ddb1b to f972b10 Compare August 17, 2026 23:42
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 23:42 — with GitHub Actions Active
@wlmyng wlmyng changed the title ledger-history: one-call checkpoint-window resolution [sui-rpc-api][sui-kv-rpc] Rename Event* range elements to IntraTx*, two step resolution from cp range to scan range Aug 17, 2026
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from f972b10 to b57b49b Compare August 17, 2026 23:56
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 23:56 — with GitHub Actions Active
@wlmyng
wlmyng force-pushed the wlmyng/ledger-history-window-resolution branch from b57b49b to 8cffd7e Compare August 17, 2026 23:56
@wlmyng
wlmyng deployed to sui-typescript-aws-kms-test-env August 17, 2026 23:56 — with GitHub Actions Active
@wlmyng

wlmyng commented Aug 19, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by a re-cut of this stack with cleaner PR boundaries (renames → behavior-preserving consolidation with characterization pins → wire-semantics alignment → unification → symbolic resume): #27751#27752#27753#27754#27755. Content is carried over commit-for-commit; the old branch stays as reference.

@wlmyng wlmyng closed this Aug 19, 2026
@wlmyng
wlmyng deleted the wlmyng/ledger-history-window-resolution branch August 19, 2026 07:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant