Skip to content

rpc: serve GetObject max_version, and at_checkpoint as a visibility bound - #28631

Draft
nickvikeras wants to merge 1 commit into
nickv/object-versions-rpcfrom
nickv/object-max-version
Draft

nickvikeras wants to merge 1 commit into
nickv/object-versions-rpcfrom
nickv/object-max-version

Conversation

@nickvikeras

@nickvikeras nickvikeras commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Replaces #28434, which GitHub marked merged into a stack branch by mistake during a rebase; its review history is there.

Description

GraphQL's rootVersion reads take an object's newest version at or below a version, and its checkpoint-scoped exact-version reads hide versions written after the viewed checkpoint. Both come from Postgres obj_versions today. This PR serves the new GetObjectRequest.max_version (MystenLabs/sui-apis#42, MystenLabs/sui-rust-sdk#329) from the fullnode and kv-rpc. It also serves at_checkpoint combined with version or max_version as a visibility bound, and both answers match Postgres, except for deletions and wraps with V1 effects, which deliberately differ (see "Difference from Postgres" below). With version: NOT_FOUND if that version was written after the checkpoint. With max_version and at_checkpoint K: the server selects the newest version at or below min(max_version, v_H), where v_X is the object's version at the end of checkpoint X and H is the height the server reports for the read, and answers NOT_FOUND if that version was written after K (it is above v_K) or deleted or wrapped the object. There is no fallback to an older version visible at K, so address(rootVersion: V).dynamicField agrees with object(version: V) at the same checkpoint. Versions above v_H never count, so a bounded answer depends only on the request and H. Without at_checkpoint, the fullnode reads max_version from its live state (decision 31 of the min-checkpoint design), and kv-rpc reads it at its served height, as K = H (decision 25).

Stacked on #28630.

  • Fullnode: max_version reads find_object_lt_or_eq_version through a new RpcStateReader::get_object_lt_or_eq_version. Without at_checkpoint, that is the whole read: it goes through the execution cache and counts every version the node holds, including versions above the highest indexed checkpoint. With at_checkpoint, H is the highest checkpoint every rpc index has committed (the bound at_checkpoint reads already use), and v_K and v_H come from the object_version_by_checkpoint index; v_H is read only when max_version is at or above v_K. Simulacrum and the transactional test runner's store record no deletions or wraps. Their max_version returns the newest live version at or below the bound, or INTERNAL when there is none. On a node whose object lower bound is above 0 (pruned, or restored from a snapshot), a version or max_version read of a version it no longer holds fails per item with OUT_OF_RANGE / BELOW_EARLIEST_AVAILABLE.
  • Fullnode, V1 effects: the rpc-store index records a deletion or wrap at TransactionEffects::lamport_version. For V1 effects that value is recomputed from the modified objects alone, so it can sit below the tombstone the perpetual store holds at the version the transaction executed at, which also counts read-only inputs such as Clock. No version lies between the two, so when the index row is not a live version, the read scans down from max_version and keeps a version only if it is below the row. The index rows already on disk stay as they are, so the read path handles both. kv-rpc records removals at their ref versions.
  • Difference from Postgres, V1 effects (deliberate): Postgres obj_versions also records a V1 deletion or wrap at the recomputed lamport version, so for a max_version at or above that version and below the tombstone, Postgres (and GraphQL rootVersion today) answers that the object does not exist. Both servers here deliberately follow the chain rule instead: they place the removal at its tombstone version, as the chain's find_object_lt_or_eq_version does, so a rootVersion bound in that gap returns the last live version where Postgres returned null. This affects only objects deleted or wrapped by transactions with V1 effects (early mainnet history); Postgres-vs-gRPC parity checks allowlist it.
  • kv-rpc: max_version is served behind the same flag as at_checkpoint, enable-object-at-checkpoint, which from this PR on also needs the alpha kvstore_object_tombstones pipeline ([kvstore] Add opt-in object tombstones to the objects table #28414) backfilled from genesis; both alpha pipelines' watermarks then bound the served height. Both pipelines are deployed and backfilled together, so one flag covers them. H is the served height, with or without at_checkpoint: max_version without at_checkpoint reads as at_checkpoint = served height, since a version-addressed answer looks immutable and must not depend on how far the tombstones pipeline has run. kv-rpc's bare GetPackage is bounded the same way.
  • kv-rpc reads: a batch runs these reads in rpc: serve GetObject/BatchGetObjects at_checkpoint from the fullnode and kv-rpc #28630's BatchGetObjects pipeline. Each lookup's version-index reads, and a max_version read's scan of objects, run in that pipeline's scan stage, so every one goes through the request limiter and returns its permit whether or not the objects reads are taking lookups. A request reads each (object, checkpoint) of the index at most once, and each version-index read is a single-row forward read ([kvstore] Order object_versions_by_checkpoint newest-first #28624). A version read with at_checkpoint reads v_K first and its objects row only if the version was written by K, so it takes one more round trip than an exact read without at_checkpoint, and it skips the row of a version written after K. A max_version read reads v_K and, when H is above K, v_H at the same time in the same scan, so it takes two round trips with its objects read. v_H decides nothing when the object did not exist at K, was deleted or wrapped there, or max_version is below v_K; reading it anyway costs a read in those cases and saves a round trip in the others. Below v_K the read scans objects from max_version. At or above v_K, if the object did not change after K, the index row answers (NOT_FOUND for a deletion or wrap, otherwise version v_K through the batched objects reads), and otherwise the read is NOT_FOUND or a scan that must find v_K itself.
  • sui-fork: max_version resolves against the remote pinned at the fork checkpoint, so it never returns a version created on the live chain after the fork, and cached local versions count only from the object's version at the fork checkpoint upward. Bounded reads go through the fullnode's GetObject path, so they follow the same rule.
  • Known gap: fullnode requests without x-sui-min-checkpoint get the informational x-sui-checkpoint-height, the live-index height. A bounded read is bounded by the all-pipelines indexed height H, which can lag that height, and a max_version read without at_checkpoint reads live state, which can run ahead of it; the fullnode does not read x-sui-min-checkpoint yet. On kv-rpc the two are the same served height. Fullnode and kv-rpc answers to max_version agree only with at_checkpoint.

Test plan

  • A kv-rpc unit test checks every version against every checkpoint bound against a model of the chain rule: exact and max_version, single and batch, with and without contents. test_max_version_at_checkpoint_counts_versions_up_to_the_served_height covers a version written after K (NOT_FOUND) and one above the served height (does not count). Unit tests also cover flag gating and the served height, including test_max_version_without_checkpoint_is_bounded_by_the_served_height. test_batch_answers_each_request_and_reads_each_row_once adds a version and a max_version lookup at the checkpoint of an at_checkpoint lookup: the three share one version-index read at that checkpoint and one objects read, and the batch makes two version-index reads in all, the second for the max_version lookup's v_H.
  • test_max_version_and_checkpoint_bounds_need_the_flag (kv-rpc): with enable-object-at-checkpoint off, max_version (with or without at_checkpoint) and version + at_checkpoint reads fail with UNIMPLEMENTED / NOT_SERVED_HERE, cause disabled_by_config, alone and as a whole batch, even when at_checkpoint is above the served height; with the flag on, that last read is OUT_OF_RANGE.
  • kv_rpc_tests::test_get_object_max_version_and_checkpoint_bounds runs the same reads against the BigTable emulator over the create, mutate, wrap, unwrap and delete lifecycle. The object skips a version mid-lifecycle, and a max_version inside the gap returns the older version. It also covers the version + max_version rejection.
  • The fullnode simtest get_object_lifecycle adds every-version max_version reads and bounded reads, with the same version gap, and a max_version that selects a version written after the bound.
  • A sui-rpc-api unit test, max_version_at_checkpoint_follows_chain_rule, checks bounded reads against the chain rule, with each removal at its tombstone version, for every checkpoint and highest indexed checkpoint, over a lifecycle whose wrap and deletion have V1 effects (index rows below their tombstones) and with versions in the object store above the highest indexed checkpoint. It asserts the V1 case above: a max_version between a removal's index row and its tombstone returns the version before the removal.
  • sui-rpc-api unit tests cover pruned versions: missing_versions_are_refused_on_pruned_nodes, missing_versions_fail_only_their_own_batch_items and at_checkpoint_visibility_misses_stay_not_found. The fullnode simtest get_object_at_checkpoint_below_available_floor is extended: a version or max_version read of a pruned version fails at the object lower bound, with or without at_checkpoint, a version above the latest is NOT_FOUND, and in a batch only the failing item fails.
  • sui-fork unit tests: a bounded read never serves a version created after the fork, through the store and through GetObject. The not-yet-indexed and pruned-floor tests cover bounded reads.
  • Contents-free reads of deleted or wrapped objects: kvstore unit and emulator tests, plus a kv-rpc test that a deleted object is NOT_FOUND both unversioned and at its removal version.

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: LedgerService.GetObject and BatchGetObjects accept max_version, which returns the object's newest version at or below it, or NOT_FOUND if the object was deleted or wrapped at that version. A request that sets both version and max_version fails with INVALID_ARGUMENT. at_checkpoint can now be combined with version or max_version, matching Postgres-backed GraphQL: the read fails with NOT_FOUND if the selected version was written after the checkpoint. The archival kv-rpc service serves max_version only with enable-object-at-checkpoint: true, which from this release also needs the alpha kvstore_object_tombstones pipeline backfilled from genesis, and bounds it by the served height. On fullnodes, a max_version read without at_checkpoint reads the node's live state and counts every version it holds. On fullnodes that prune object versions or were restored from a snapshot, a version or max_version read of a version the node no longer holds now fails per item with OUT_OF_RANGE / BELOW_EARLIEST_AVAILABLE (lowestAvailableCheckpoint = the node's lowest checkpoint with object data) instead of NOT_FOUND; a version above the object's latest is still NOT_FOUND. Deletions and wraps with V1 effects (early mainnet history) deliberately differ from Postgres-backed GraphQL: a max_version between such a removal's lamport version and its tombstone returns the last live version, where GraphQL rootVersion returned null.
    These reads are refused, and a batch containing one fails as a whole:
    • kv-rpc with enable-object-at-checkpoint off: max_version reads, with or without at_checkpoint, and version + at_checkpoint reads fail with UNIMPLEMENTED / NOT_SERVED_HERE, cause disabled_by_config.
    • Fullnodes that keep only the latest version of each object (compactor): every max_version read, with or without at_checkpoint, and every version + at_checkpoint read fail with UNIMPLEMENTED / NOT_SERVED_HERE, cause no_object_history. GraphQL rootVersion reads served by such a node hit this.
    • Fullnodes, any selector with at_checkpoint: UNIMPLEMENTED / NOT_SERVED_HERE, cause no_rpc_indexes, on nodes without rpc indexes; UNAVAILABLE / NOT_READY, cause index_empty or restore_backfill, while the indexes have not committed a checkpoint or are backfilling history after a restore.
  • JSON-RPC:
  • GraphQL:
  • CLI:
  • Rust SDK:
  • Indexing Framework:

@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch from 3eac85c to 64cb09e Compare November 11, 2026 01:21
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from a6e9581 to 2eae992 Compare November 11, 2026 01:21
@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch from 64cb09e to ca6de3b Compare November 11, 2026 02:33
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch 2 times, most recently from 10e06f1 to f8a29aa Compare November 13, 2026 04:15
@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch 2 times, most recently from a8c49c2 to 57d4bc0 Compare November 13, 2026 11:11
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from f8a29aa to 93bc0e8 Compare November 13, 2026 11:11
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from 93bc0e8 to 1632e3b Compare November 14, 2026 01:04
@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch from 57d4bc0 to 03f6b9c Compare November 14, 2026 01:04
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from 1632e3b to 7216bc0 Compare November 14, 2026 06:25
@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch 2 times, most recently from 0a96336 to 28bd38f Compare November 14, 2026 18:50
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch from 7216bc0 to 008a861 Compare November 14, 2026 18:50
@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch from 28bd38f to a14241d Compare November 15, 2026 02:09
@nickvikeras
nickvikeras force-pushed the nickv/object-max-version branch from a14241d to 54aaf67 Compare November 15, 2026 19:59

This branch has not been deployed

No deployments
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