Skip to content

feat(seid): add statesync export and import - #4861

Draft
blindchaser wants to merge 8 commits into
yiren/giga-ss5-epoch-seedfrom
yiren/giga-ss5-cli
Draft

blindchaser wants to merge 8 commits into
yiren/giga-ss5-epoch-seedfrom
yiren/giga-ss5-cli

Conversation

@blindchaser

@blindchaser blindchaser commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds seid statesync export and import. export packs a FlatKV checkpoint and its state sync
proof file into one archive, and import installs that archive into a fresh Autobahn fullnode
home. This lets an operator start a Giga fullnode without a peer to state sync from.
Stacked on PR 4860 (epoch registry), which
is stacked on PR 4858 (FlatKV).

How it works:

  • export links the checkpoint so pruning cannot remove it, and refuses a checkpoint without a
    matching proof file. With --out - it prints {"height":H} on stderr.
  • The archive holds a manifest (chain id, height, row count, byte count, state hash), then the
    proof, then the FlatKV rows in chunks.
  • import imports the rows into a staging dir and requires the checkpoint stats and state hash
    to equal the manifest. It opens the epoch registry of the checkpoint in memory and verifies the
    proof signatures with it.
  • It installs in a fixed order: the restore marker, the proof file, the epoch registry, the app
    hash of H as the restore anchor in an empty app-hash vault, and last the FlatKV checkpoint. An
    import that fails or stops can run again on the same home.

The manifest state hash is an integrity check. Trust comes from the AppQC of H+1 that the node
verifies after it starts.

For reviewers

  • Seed reviewers: please check the install order in importWith against what the seed reads at
    startup.

Test plan

  • Archive tests: malformed manifests, unknown or unsafe entries, and oversized windows are refused.
  • Import tests: a validator home, another chain, a home with data, a truncated archive, a proof
    signed by another validator, and rows or a state hash that do not match the manifest. A retry
    replaces an earlier import, and a completed import holds the anchor.
  • Child-process tests stop export and import at each step and check that a retry succeeds.
  • scripts/ramtest.sh ./cmd/seid/cmd/statesync ./sei-tendermint/node -race,
    make fmtcheck and golangci-lint v2.14.0 are clean.

blindchaser and others added 2 commits November 13, 2026 18:01
create packs the current FlatKV checkpoint of a running Autobahn node and its state sync proof file
into a tar.zst archive, to a file or to stdout. restore installs one into a fresh fullnode home.
Both refuse unless [giga.state_sync] enabled is true.

restore imports the archived rows into a staged checkpoint, verifies it, and requires its row count,
bytes and state hash to equal the manifest. It then prepares the epoch registry from the checkpoint
before it writes its marker.

After the marker, restore installs the epoch registry and then the checkpoint, so FlatKV reaches the
marker height only when the home is complete. With an earlier restore's marker present, restore
clears that FlatKV data before it extracts, so the free space check counts it. restore deletes only
data that its own marker shows it wrote, and completes when it is run again after any failure or
crash.

create removes what an earlier stopped run left, and locks the staging parent and the output dir, so
a second create on either fails at once. With --out -, create takes stdout before the parent command
hooks run, so log lines cannot enter the archive.

Co-authored-by: Cursor <cursoragent@cursor.com>
…tore

`seid state-sync-snapshot restore` now verifies the archived state sync
proof file against the epoch registry of the checkpoint: the road block
against the epoch of height H, and the AppQC against its committee. An
archive whose proof does not verify is refused before the home changes.

After it seeds the epoch registry and before it installs FlatKV, restore
stores the AppQC's app hash as the restore anchor at H, the first record
of the empty app-hash vault. Node startup publishes that anchor through
SetupComplete(H), so the seed only has to write the block records.

- statesyncproof: Proof.Verify(epoch).
- p2p: VerifyStateSyncProof(registry, data, road).
- node: VerifyStateSyncProof, StoreRestoreAnchor, and the shared test
  fixture StateSyncProofForTesting.
- restore: new stop step "restore anchor stored"; the failure goals
  check the vault at every step.

Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

The latest Buf updates on your PR. Results from workflow Buf / buf (pull_request).

BuildFormatLintBreakingUpdated (UTC)
✅ passed✅ passed✅ passed✅ passedNov 17, 2026, 4:41 AM

@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 72.57653% with 215 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.68%. Comparing base (06bbf5a) to head (4f4fafe).

Files with missing lines Patch % Lines
cmd/seid/cmd/statesync/command.go 14.28% 90 Missing ⚠️
cmd/seid/cmd/statesync/import.go 81.04% 40 Missing ⚠️
cmd/seid/cmd/statesync/export.go 81.20% 28 Missing ⚠️
cmd/seid/cmd/statesync/pack.go 78.00% 22 Missing ⚠️
cmd/seid/cmd/statesync/extract.go 85.58% 16 Missing ⚠️
sei-tendermint/internal/p2p/state_sync_proof.go 0.00% 12 Missing ⚠️
sei-tendermint/node/restore_anchor.go 81.81% 4 Missing ⚠️
sei-tendermint/node/testonly.go 89.47% 2 Missing ⚠️
cmd/seid/cmd/statesync/manifest.go 97.43% 1 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@                      Coverage Diff                      @@
##           yiren/giga-ss5-epoch-seed    #4861      +/-   ##
=============================================================
+ Coverage                      61.64%   61.68%   +0.03%     
=============================================================
  Files                           2082     2090       +8     
  Lines                         162138   162949     +811     
=============================================================
+ Hits                           99946   100511     +565     
- Misses                         62187    62433     +246     
  Partials                           5        5              
Flag Coverage Δ
sei-chain 59.89% <72.57%> (+0.05%) ⬆️
sei-db 75.41% <ø> (+0.23%) ⬆️
sei-db-state-db 81.59% <ø> (-0.04%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
cmd/seid/cmd/root.go 73.66% <100.00%> (+0.11%) ⬆️
giga/config/config.go 91.62% <ø> (ø)
sei-tendermint/autobahn/statesyncproof/proof.go 93.93% <100.00%> (+0.49%) ⬆️
sei-tendermint/node/setup.go 65.05% <100.00%> (+0.30%) ⬆️
cmd/seid/cmd/statesync/manifest.go 97.43% <97.43%> (ø)
sei-tendermint/node/testonly.go 73.91% <89.47%> (+73.91%) ⬆️
sei-tendermint/node/restore_anchor.go 81.81% <81.81%> (ø)
sei-tendermint/internal/p2p/state_sync_proof.go 0.00% <0.00%> (ø)
cmd/seid/cmd/statesync/extract.go 85.58% <85.58%> (ø)
cmd/seid/cmd/statesync/pack.go 78.00% <78.00%> (ø)
... and 3 more

... and 36 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@blindchaser blindchaser changed the title feat(seid): add state-sync-snapshot create and restore feat(seid): add statesync export and import Nov 17, 2026
blindchaser and others added 2 commits November 16, 2026 23:19
statesync import opens the checkpoint epoch registry with
node.OpenCheckpointEpochs, verifies the state sync proof against it, and
installs it with node.InstallEpochRegistry. The epoch-registry staging
dir is gone.

Co-authored-by: Cursor <cursoragent@cursor.com>

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