Skip to content

rpc: GetEpoch end-of-epoch fields - #28600

Open
nickvikeras wants to merge 1 commit into
nickv/pinned-read-boundsfrom
nickv/epoch-fields
Open

nickvikeras wants to merge 1 commit into
nickv/pinned-read-boundsfrom
nickv/epoch-fields

Conversation

@nickvikeras

@nickvikeras nickvikeras commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Description

GraphQL's Epoch reads move from Postgres to kv-rpc, so LedgerService/GetEpoch serves the end-of-epoch data GraphQL reads there, from both the fullnode and kv-rpc.

Stacked on #28577. Depends on MystenLabs/sui-apis#53 and MystenLabs/sui-rust-sdk#344, pinned at 09f4c23. Because #344 is based on SDK master, the pin also brings in MystenLabs/sui-rust-sdk#337: the ledger-stream client orders frames by Watermark.cursor_position and ends a stream with DATA_LOSS on a frame without it. 1.82's sui-rpc-api does not send it. 1.83's sends it on item and scan-frontier frames, and on a terminal frame unless the request resumed from a transaction or event cursor that carries no public position, such as one minted by 1.82 (whose cursors have none). 1.84 and main send it on every frame. The running epoch's system_state at kv-rpc's served height is split out into #28607, which is stacked on #28663.

Mini design doc

Design. The new Epoch fields come from the stored epoch rows on both servers (rpc-store on the fullnode, BigTable epochs on kv-rpc):

  • transaction_end_exclusive
  • ended_in_safe_mode
  • system_epoch_info
  • epoch_commitments

These are set exactly when last_checkpoint is. transaction_start_inclusive is the previous epoch's transaction_end_exclusive, or 0 for epoch 0. One shared helper in sui-rpc-api fills the fields for both servers. kv-rpc reads epochs through the request's limited BigTable client.

Decisions.

  • The latest epoch. On the fullnode, GetEpoch without an epoch answers for the live system state's epoch, as before: the fullnode's plain reads are live (decision 31 of the min-checkpoint design). On kv-rpc it answers for the epoch of its served height H, as every kv-rpc read does. For an epoch after the latest, the fullnode answers NOT_FOUND and kv-rpc an empty response (kv-rpc: answer NOT_FOUND for an epoch it has not served #28608 makes it NOT_FOUND).
  • End fields: on the fullnode, last_checkpoint, end and the end fields appear as soon as the rpc-store row has them. On kv-rpc, an epoch that ends above H has no last_checkpoint, end or end fields yet, even when the indexer has already written them.
  • A safe-mode epoch: ended_in_safe_mode = true and no system_epoch_info, because no SystemEpochInfoEvent was emitted.
  • Fullnode epoch constants: the live system state's epoch takes its protocol_config, start and reference_gas_price from the live state. Any other epoch takes them from its rpc-store row, not from its stored system-state snapshot.
  • The fullnode after a restore: a restore that lands mid-epoch seeds that epoch's row from the restore-point state, without start_checkpoint.
    • For a past epoch, the fullnode does not serve that state as system_state.
    • The rpc-store merge no longer lets such a seed overwrite a known epoch-start state.
    • The real start state arrives only if the node's history reaches the epoch's first checkpoint.

Impact and rollout. Additive fields on both servers, with no flag. The fullnode's latest epoch stays the live one. Right after an epoch change, the epoch that just ended has its end fields on the fullnode only once the rpc indexes have indexed its last checkpoint. On kv-rpc, system_state is always the epoch-start snapshot here; #28607 serves the running epoch's state at the served height. Fullnode/kv-rpc parity holds for ended epochs; for the running epoch the fullnode answers from its live state and kv-rpc at H.

Test coverage. The unit tests cover kv-rpc against a mock BigTable and the rpc-store merge. The e2e tests run the fullnode, kv-rpc, and both against one chain. Not covered end to end:

  • an epoch that ended in safe mode (unit tests only)
  • a fullnode restored mid-epoch

Test plan

New tests:

  • sui-kv-rpc: end_fields_are_served_once_the_epoch_has_ended_at_the_served_height: end fields are hidden above the served height, safe-mode counters are unset, and the first transaction comes from the previous epoch.
  • sui-rpc-store: partial_seed_does_not_clobber_known_start_record.
  • sui-e2e-tests: get_epoch_end_fields, where the fullnode's end fields match the last checkpoint's summary.
  • sui-indexer-alt-e2e-tests: test_get_epoch_matches_between_fullnode_and_kv_rpc: one chain served by both servers. An ended epoch's stored fields, end fields and system_state match. The running epoch is not compared: the fullnode answers for it from its live state.

Release notes

  • Protocol:
  • Nodes (Validators and Full nodes):
  • gRPC: GetEpoch adds the end-of-epoch fields transaction_start_inclusive, transaction_end_exclusive, ended_in_safe_mode, system_epoch_info and epoch_commitments.
  • JSON-RPC:
  • GraphQL:
  • CLI:
  • Rust SDK:
  • Indexing Framework:

@nickvikeras nickvikeras changed the title rpc: GetEpoch system_state_at, SystemState.bcs and end-of-epoch fields rpc: GetEpoch end-of-epoch fields, and kv-rpc's current-epoch system state Nov 6, 2026
@nickvikeras
nickvikeras force-pushed the nickv/object-versions-rpc branch 2 times, most recently from 2090827 to d533742 Compare November 6, 2026 21:34
@nickvikeras nickvikeras changed the title rpc: GetEpoch end-of-epoch fields, and kv-rpc's current-epoch system state rpc: GetEpoch end-of-epoch fields Nov 6, 2026
@nickvikeras
nickvikeras changed the base branch from nickv/object-versions-rpc to main November 6, 2026 22:15
nickvikeras added a commit that referenced this pull request Nov 6, 2026
# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	crates/sui-kv-rpc/src/bigtable_client.rs
#	crates/sui-rpc-api/src/grpc/v2/ledger_service/mod.rs
nickvikeras added a commit that referenced this pull request Nov 6, 2026
# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	crates/sui-kv-rpc/src/bigtable_client.rs
#	crates/sui-rpc-api/src/grpc/v2/ledger_service/mod.rs
nickvikeras added a commit that referenced this pull request Nov 7, 2026
# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	crates/sui-kv-rpc/src/bigtable_client.rs
#	crates/sui-rpc-api/src/grpc/v2/ledger_service/mod.rs
nickvikeras added a commit that referenced this pull request Nov 7, 2026
# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	crates/sui-kv-rpc/src/bigtable_client.rs
#	crates/sui-rpc-api/src/grpc/v2/ledger_service/mod.rs
nickvikeras added a commit that referenced this pull request Nov 7, 2026
# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	crates/sui-kv-rpc/src/bigtable_client.rs
#	crates/sui-rpc-api/src/grpc/v2/ledger_service/mod.rs
nickvikeras added a commit that referenced this pull request Nov 7, 2026
# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	crates/sui-kv-rpc/src/bigtable_client.rs
#	crates/sui-rpc-api/src/grpc/v2/ledger_service/mod.rs
@nickvikeras
nickvikeras marked this pull request as ready for review November 11, 2026 00:59
@nickvikeras
nickvikeras requested a review from a team as a code owner November 11, 2026 00:59
@nickvikeras
nickvikeras force-pushed the nickv/epoch-fields branch 3 times, most recently from cfa86ca to bcaa403 Compare November 13, 2026 11:11
@nickvikeras
nickvikeras changed the base branch from main to nickv/pinned-read-bounds November 14, 2026 06:26
GraphQL's Epoch reads move from Postgres to kv-rpc, so GetEpoch serves
the end-of-epoch data GraphQL reads there, from both the fullnode and
kv-rpc: transaction_end_exclusive, ended_in_safe_mode, system_epoch_info
and epoch_commitments come from the stored epoch rows (rpc-store
EpochInfo now carries them) and are set exactly when last_checkpoint
is; transaction_start_inclusive comes from the previous epoch's end.
kv-rpc reads epochs through the request's limited client.

The fullnode's latest epoch is the live system state's, and its
end-of-epoch fields appear as soon as the rpc-store row has them.
kv-rpc answers as of its served height: an epoch that ends above it
has not ended yet.

The rpc-store merge no longer lets a mid-epoch restore seed overwrite a
known epoch-start state, and the fullnode does not serve a seeded
mid-epoch state as a past epoch's system_state. Also bumps
sui-rust-sdk to 09f4c23 (MystenLabs/sui-rust-sdk#344) and drops the
unused CheckpointData::epoch_info.

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.

2 participants