Giga store migration guide by Kbhat1 · Pull Request #3227 · sei-protocol/sei-chain

Kbhat1 · 2026-04-10T15:48:42Z

Describe your changes and provide context

Giga Store migration guide + safety checks for EVM SS write/read modes
Validates config-level mode combinations, rejects startup when the EVM SS DB is missing or empty while Cosmos SS has history, and rejects mismatched earliest versions post-recovery
Together these catch the case where an operator flips evm-ss-write-mode/evm-ss-read-mode off cosmos_only without state syncing
Docs also updated to cover the full migration flow

Testing performed to validate your change

Unit tests
Verifying on node

github-actions · 2026-04-10T15:49:42Z

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

Build	Format	Lint	Breaking	Updated (UTC)
`✅ passed`	`✅ passed`	`✅ passed`	`✅ passed`	Apr 21, 2026, 11:18 PM

codecov · 2026-04-16T19:11:27Z

Codecov Report

❌ Patch coverage is 76.74419% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.31%. Comparing base (f2f5f21) to head (fb40ff5).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
sei-db/state_db/ss/composite/store.go	76.82%	14 Missing and 5 partials ⚠️
app/seidb.go	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3227      +/-   ##
==========================================
- Coverage   59.36%   59.31%   -0.06%     
==========================================
  Files        2072     2072              
  Lines      169942   170956    +1014     
==========================================
+ Hits       100887   101401     +514     
- Misses      60271    60772     +501     
+ Partials     8784     8783       -1

Flag	Coverage Δ
sei-chain-pr	`54.68% <76.74%> (?)`
sei-db	`69.36% <ø> (-1.05%)`	⬇️

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

Files with missing lines	Coverage Δ
sei-cosmos/server/config/config.go	`93.04% <100.00%> (-1.40%)`	⬇️
sei-db/config/ss_config.go	`100.00% <100.00%> (ø)`
app/seidb.go	`73.25% <50.00%> (+4.65%)`	⬆️
sei-db/state_db/ss/composite/store.go	`67.53% <76.82%> (-2.50%)`	⬇️

... and 24 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.

yzang2019 · 2026-04-17T19:20:52Z

+
+	cosmosLatest := s.cosmosStore.GetLatestVersion()
+	evmLatest := s.evmStore.GetLatestVersion()
+	if cosmosLatest > 0 && evmLatest == 0 {


After state sync, it seems we will only set earliestVersion for SS:

But what about latestVersion? Is that set as well?

Replaces the two-field StateStoreConfig.WriteMode / ReadMode with a single EVMMode enum that takes only "cosmos_only" or "split". The previous matrix (cosmos_only / dual_write / split_write crossed with cosmos_only / evm_first / split_read) produced configurations whose behavior was hard to reason about — in particular, evm_first's fallback-to-cosmos semantics masked inconsistencies between the two backends and hid the iterator routing bug that broke pointer lookups on Giga-enabled nodes. Under "split" there is no fallback: a read or iterate that would miss returns empty rather than silently routing to a different backend. Scope is the SS (State Store) layer only. The SC layer still uses the older WriteMode / ReadMode enums; those were left untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- mapstructure tag on EVMMode is now "evm-ss-mode", matching the TOML key used in app.toml and the viper binding. - Renamed tests that still mentioned the removed modes (SplitWrite, SplitRead, CosmosOnlyWrite) so the names describe behavior under the new single EVMMode field. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The tag is dead code for StateStoreConfig — Unmarshal is only used in ParseConfig (app.toml template generation), which doesn't read from viper at all. The live runtime path uses viper.GetString directly and bypasses mapstructure. Other fields in the same struct share the same "tag doesn't match TOML key" pattern, so touching only this one made the struct more inconsistent. A uniform cleanup of the tags can happen separately if desired. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…fy-modes # Conflicts: # sei-db/state_db/ss/composite/store.go

sei-cosmos/server/config/config_test.go was still referencing the removed StateStore.WriteMode / ReadMode fields and the old WriteMode/ReadMode constants (SplitWrite, SplitRead, CosmosOnlyWrite, CosmosOnlyRead). Updated the StateStore blocks to use the single EVMMode field and EVMModeSplit / EVMModeCosmosOnly constants. SC blocks (which still use WriteMode/ReadMode) are untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Replaces the short-lived EVMMode string enum (cosmos_only / split) with a plain bool EVMSplit. The enum only ever had two values so the string type carried no real information beyond "on or off"; a bool reads more naturally, eliminates parse/validate code, and drops any chance of a typo in app.toml silently falling back to a default. Key -> flow: TOML state-store.evm-ss-split = {true|false} (default false) viper v.GetBool("state-store.evm-ss-split") flag FlagEVMSSSplit -> cast.ToBool struct StateStoreConfig.EVMSplit bool runtime evmStore opened iff EVMSplit; routing keys off evmStore != nil Deletes sei-db/config/evm_mode.go entirely. Collapses the composite "evmRouted" helper to a nil check — if evmStore was opened, EVMSplit was true at startup and it's the sole home for EVM data. Import and recovery paths likewise drop the mode comparison. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three DB-state guards in NewCompositeStateStore prevent the common footgun of flipping evm-ss-split on without first state syncing: 1. validateEVMSSDirectory: reject if Cosmos SS has history but the EVM SS directory is missing or empty. Runs before the EVM SS DB is opened so a rejected config leaves no empty data/evm_ss/ behind. 2. validateEVMSSPreRecovery: catch the same misconfiguration when the directory exists but its DBs are empty (e.g. from a prior failed attempt). WAL replay only covers the last KeepRecent blocks so it cannot rebuild a fresh EVM SS from scratch. 3. validateEVMSSPostRecovery: reject mismatched earliest versions between Cosmos SS and EVM SS — indicates the two DBs came from different snapshots or were pruned independently. The config-level mode validation from the original PR is dropped: EVMSplit is a bool, so there is no invalid string to reject. Adds docs/migration/giga_store_migration.md covering the full flow and these checks. Drops the old TestConstructorRecoversStalEVM test whose premise (rebuild EVM SS from WAL when dir is missing) is exactly the scenario the new guards correctly refuse. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Kbhat1 force-pushed the kartik/giga-store-migration-guide branch 6 times, most recently from 40043e3 to d99185c Compare April 16, 2026 19:01

Kbhat1 marked this pull request as ready for review April 16, 2026 19:03

Kbhat1 force-pushed the kartik/giga-store-migration-guide branch from d99185c to aa0c47d Compare April 16, 2026 19:07

Kbhat1 force-pushed the kartik/giga-store-migration-guide branch 3 times, most recently from 6a55ffa to cf8803c Compare April 16, 2026 19:24

Kbhat1 added the non-app-hash-breaking label Apr 16, 2026

Kbhat1 requested review from blindchaser, cody-littley, jewei1997 and yzang2019 April 16, 2026 20:17

yzang2019 reviewed Apr 17, 2026

View reviewed changes

yzang2019 approved these changes Apr 17, 2026

View reviewed changes

jewei1997 approved these changes Apr 17, 2026

View reviewed changes

Kbhat1 and others added 7 commits April 20, 2026 12:32

Merge remote-tracking branch 'origin/main' into kartik/giga-ss-simpli…

ade80e8

…fy-modes # Conflicts: # sei-db/state_db/ss/composite/store.go

Kbhat1 force-pushed the kartik/giga-store-migration-guide branch from 99330ad to 53d4092 Compare April 21, 2026 23:00

docs(giga): note EVM SS is point-query only by design

fb40ff5

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Giga store migration guide#3227

Giga store migration guide#3227
Kbhat1 wants to merge 8 commits intomainfrom
kartik/giga-store-migration-guide

Kbhat1 commented Apr 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Apr 16, 2026 •

edited

Loading

Uh oh!

yzang2019 Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Kbhat1 commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe your changes and provide context

Testing performed to validate your change

Uh oh!

github-actions Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

yzang2019 Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Kbhat1 commented Apr 10, 2026 •

edited

Loading

github-actions Bot commented Apr 10, 2026 •

edited

Loading

codecov Bot commented Apr 16, 2026 •

edited

Loading