Repository navigation
rpc: serve GetObject max_version, and at_checkpoint as a visibility bound - #28631
Draft
nickvikeras wants to merge 1 commit into
Draft
nickvikeras wants to merge 1 commit into
nickvikeras wants to merge 1 commit into
Conversation
This was referenced Nov 10, 2026
nickvikeras
force-pushed
the
nickv/object-max-version
branch
from
November 11, 2026 01:21
3eac85c to
64cb09e
Compare
nickvikeras
force-pushed
the
nickv/object-versions-rpc
branch
from
November 11, 2026 01:21
a6e9581 to
2eae992
Compare
nickvikeras
force-pushed
the
nickv/object-max-version
branch
from
November 11, 2026 02:33
64cb09e to
ca6de3b
Compare
nickvikeras
force-pushed
the
nickv/object-versions-rpc
branch
2 times, most recently
from
November 13, 2026 04:15
10e06f1 to
f8a29aa
Compare
nickvikeras
force-pushed
the
nickv/object-max-version
branch
2 times, most recently
from
November 13, 2026 11:11
a8c49c2 to
57d4bc0
Compare
nickvikeras
force-pushed
the
nickv/object-versions-rpc
branch
from
November 13, 2026 11:11
f8a29aa to
93bc0e8
Compare
1 of 8 tasks
nickvikeras
force-pushed
the
nickv/object-versions-rpc
branch
from
November 14, 2026 01:04
93bc0e8 to
1632e3b
Compare
nickvikeras
force-pushed
the
nickv/object-max-version
branch
from
November 14, 2026 01:04
57d4bc0 to
03f6b9c
Compare
nickvikeras
force-pushed
the
nickv/object-versions-rpc
branch
from
November 14, 2026 06:25
1632e3b to
7216bc0
Compare
nickvikeras
force-pushed
the
nickv/object-max-version
branch
2 times, most recently
from
November 14, 2026 18:50
0a96336 to
28bd38f
Compare
nickvikeras
force-pushed
the
nickv/object-versions-rpc
branch
from
November 14, 2026 18:50
7216bc0 to
008a861
Compare
This was referenced Nov 14, 2026
nickvikeras
force-pushed
the
nickv/object-max-version
branch
from
November 15, 2026 02:09
28bd38f to
a14241d
Compare
nickvikeras
force-pushed
the
nickv/object-max-version
branch
from
November 15, 2026 19:59
a14241d to
54aaf67
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces #28434, which GitHub marked merged into a stack branch by mistake during a rebase; its review history is there.
Description
GraphQL's
rootVersionreads 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 Postgresobj_versionstoday. This PR serves the newGetObjectRequest.max_version(MystenLabs/sui-apis#42, MystenLabs/sui-rust-sdk#329) from the fullnode and kv-rpc. It also servesat_checkpointcombined withversionormax_versionas a visibility bound, and both answers match Postgres, except for deletions and wraps with V1 effects, which deliberately differ (see "Difference from Postgres" below). Withversion:NOT_FOUNDif that version was written after the checkpoint. Withmax_versionandat_checkpointK: the server selects the newest version at or belowmin(max_version, v_H), wherev_Xis the object's version at the end of checkpoint X and H is the height the server reports for the read, and answersNOT_FOUNDif that version was written after K (it is abovev_K) or deleted or wrapped the object. There is no fallback to an older version visible at K, soaddress(rootVersion: V).dynamicFieldagrees withobject(version: V)at the same checkpoint. Versions abovev_Hnever count, so a bounded answer depends only on the request and H. Withoutat_checkpoint, the fullnode readsmax_versionfrom 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.
max_versionreadsfind_object_lt_or_eq_versionthrough a newRpcStateReader::get_object_lt_or_eq_version. Withoutat_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. Withat_checkpoint, H is the highest checkpoint every rpc index has committed (the boundat_checkpointreads already use), andv_Kandv_Hcome from theobject_version_by_checkpointindex;v_His read only whenmax_versionis at or abovev_K. Simulacrum and the transactional test runner's store record no deletions or wraps. Theirmax_versionreturns the newest live version at or below the bound, orINTERNALwhen there is none. On a node whose object lower bound is above 0 (pruned, or restored from a snapshot), aversionormax_versionread of a version it no longer holds fails per item withOUT_OF_RANGE/BELOW_EARLIEST_AVAILABLE.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 frommax_versionand 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.obj_versionsalso records a V1 deletion or wrap at the recomputed lamport version, so for amax_versionat or above that version and below the tombstone, Postgres (and GraphQLrootVersiontoday) 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'sfind_object_lt_or_eq_versiondoes, so arootVersionbound 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.max_versionis served behind the same flag asat_checkpoint,enable-object-at-checkpoint, which from this PR on also needs the alphakvstore_object_tombstonespipeline ([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 withoutat_checkpoint:max_versionwithoutat_checkpointreads asat_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 bareGetPackageis bounded the same way.BatchGetObjectspipeline. Each lookup's version-index reads, and amax_versionread's scan ofobjects, run in that pipeline's scan stage, so every one goes through the request limiter and returns its permit whether or not theobjectsreads 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). Aversionread withat_checkpointreadsv_Kfirst and itsobjectsrow only if the version was written by K, so it takes one more round trip than an exact read withoutat_checkpoint, and it skips the row of a version written after K. Amax_versionread readsv_Kand, when H is above K,v_Hat the same time in the same scan, so it takes two round trips with itsobjectsread.v_Hdecides nothing when the object did not exist at K, was deleted or wrapped there, ormax_versionis belowv_K; reading it anyway costs a read in those cases and saves a round trip in the others. Belowv_Kthe read scansobjectsfrommax_version. At or abovev_K, if the object did not change after K, the index row answers (NOT_FOUNDfor a deletion or wrap, otherwise versionv_Kthrough the batchedobjectsreads), and otherwise the read isNOT_FOUNDor a scan that must findv_Kitself.max_versionresolves 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'sGetObjectpath, so they follow the same rule.x-sui-min-checkpointget the informationalx-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 amax_versionread withoutat_checkpointreads live state, which can run ahead of it; the fullnode does not readx-sui-min-checkpointyet. On kv-rpc the two are the same served height. Fullnode and kv-rpc answers tomax_versionagree only withat_checkpoint.Test plan
max_version, single and batch, with and without contents.test_max_version_at_checkpoint_counts_versions_up_to_the_served_heightcovers 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, includingtest_max_version_without_checkpoint_is_bounded_by_the_served_height.test_batch_answers_each_request_and_reads_each_row_onceadds aversionand amax_versionlookup at the checkpoint of anat_checkpointlookup: the three share one version-index read at that checkpoint and oneobjectsread, and the batch makes two version-index reads in all, the second for themax_versionlookup'sv_H.test_max_version_and_checkpoint_bounds_need_the_flag(kv-rpc): withenable-object-at-checkpointoff,max_version(with or withoutat_checkpoint) andversion+at_checkpointreads fail withUNIMPLEMENTED/NOT_SERVED_HERE, causedisabled_by_config, alone and as a whole batch, even whenat_checkpointis above the served height; with the flag on, that last read isOUT_OF_RANGE.kv_rpc_tests::test_get_object_max_version_and_checkpoint_boundsruns the same reads against the BigTable emulator over the create, mutate, wrap, unwrap and delete lifecycle. The object skips a version mid-lifecycle, and amax_versioninside the gap returns the older version. It also covers theversion+max_versionrejection.get_object_lifecycleadds every-versionmax_versionreads and bounded reads, with the same version gap, and amax_versionthat selects a version written after the bound.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: amax_versionbetween a removal's index row and its tombstone returns the version before the removal.missing_versions_are_refused_on_pruned_nodes,missing_versions_fail_only_their_own_batch_itemsandat_checkpoint_visibility_misses_stay_not_found. The fullnode simtestget_object_at_checkpoint_below_available_flooris extended: aversionormax_versionread of a pruned version fails at the object lower bound, with or withoutat_checkpoint, a version above the latest isNOT_FOUND, and in a batch only the failing item fails.GetObject. The not-yet-indexed and pruned-floor tests cover bounded reads.NOT_FOUNDboth 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.
LedgerService.GetObjectandBatchGetObjectsacceptmax_version, which returns the object's newest version at or below it, orNOT_FOUNDif the object was deleted or wrapped at that version. A request that sets bothversionandmax_versionfails withINVALID_ARGUMENT.at_checkpointcan now be combined withversionormax_version, matching Postgres-backed GraphQL: the read fails withNOT_FOUNDif the selected version was written after the checkpoint. The archival kv-rpc service servesmax_versiononly withenable-object-at-checkpoint: true, which from this release also needs the alphakvstore_object_tombstonespipeline backfilled from genesis, and bounds it by the served height. On fullnodes, amax_versionread withoutat_checkpointreads the node's live state and counts every version it holds. On fullnodes that prune object versions or were restored from a snapshot, aversionormax_versionread of a version the node no longer holds now fails per item withOUT_OF_RANGE/BELOW_EARLIEST_AVAILABLE(lowestAvailableCheckpoint= the node's lowest checkpoint with object data) instead ofNOT_FOUND; a version above the object's latest is stillNOT_FOUND. Deletions and wraps with V1 effects (early mainnet history) deliberately differ from Postgres-backed GraphQL: amax_versionbetween such a removal's lamport version and its tombstone returns the last live version, where GraphQLrootVersionreturned null.These reads are refused, and a batch containing one fails as a whole:
enable-object-at-checkpointoff:max_versionreads, with or withoutat_checkpoint, andversion+at_checkpointreads fail withUNIMPLEMENTED/NOT_SERVED_HERE, causedisabled_by_config.max_versionread, with or withoutat_checkpoint, and everyversion+at_checkpointread fail withUNIMPLEMENTED/NOT_SERVED_HERE, causeno_object_history. GraphQLrootVersionreads served by such a node hit this.at_checkpoint:UNIMPLEMENTED/NOT_SERVED_HERE, causeno_rpc_indexes, on nodes without rpc indexes;UNAVAILABLE/NOT_READY, causeindex_emptyorrestore_backfill, while the indexes have not committed a checkpoint or are backfilling history after a restore.