Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion evm/installing-seid-cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,6 @@ Available Commands:
config Create or query an application CLI configuration file
debug Tool for helping with debugging your application
ethreplay replay EVM transactions
export Export state to JSON
gentx Generate a genesis tx carrying a self delegation
help Help about any command
init Initialize private validator, p2p, genesis, and application configuration files
Expand Down
36 changes: 36 additions & 0 deletions node/giga-storage-migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@

<Warning>To roll back cleanly to `evm-ss-split = false`, run another state sync. Under `evm-ss-split = true`, EVM writes go only to the EVM SS DB, so Cosmos SS does not have those writes. If you restart with `evm-ss-split = false`, the node stops opening the EVM SS DB. However, EVM-state queries miss anything written after the Giga state sync until you run state sync again without the split.</Warning>

## FlatKV EVM SC migration flow

Check warning on line 193 in node/giga-storage-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/giga-storage-migration.mdx#L193

Use sentence case for headings: 'FlatKV EVM SC migration flow'.

Everything above concerns the **SS** (State Store) layer. The **SC** (State
Commit) layer has a separate migration path. It moves the hot `evm/` data out
Expand Down Expand Up @@ -306,7 +306,43 @@
command creates. The store has no migration metadata, so the node starts in
`memiavl_only`.



### Rollback and historical reads below retained FlatKV history

FlatKV retains only a bounded window of history (its snapshots plus WAL). A
version below that floor cannot be reconstructed, so operations that would need
it are now refused up front instead of failing part-way through or serving
approximate state.

- **Rollback.** A rollback to a version below the retained FlatKV history floor
is refused before any backend state is mutated. The node returns an error
wrapping `ErrVersionUnreachable` whose message ends with `use state sync
instead`. Because the check runs first, both memIAVL and FlatKV are left at
their original version and the store stays usable. To reach a target below the
floor, run a state sync instead.
- **Historical reads and exports.** Read-only loads (`LoadVersionReadOnly`) and
exports (`Exporter`) at a version below the floor now return an error wrapping
`ErrVersionUnreachable` rather than panicking or serving approximate state.
Reachable versions — those at or above the retained floor, including a seeded
snapshot floor bridged by the WAL — still succeed.

### Automatic cleanup of a stale idle FlatKV directory

In `auto` write mode, the node discards a stale idle FlatKV directory at startup
(during load). An idle FlatKV directory holds only a seed with no migration
state. It is treated as stale when its version is above memIAVL's, or more than
one block behind memIAVL. Such a directory is removed and recreated exactly at
the next migration kickoff, so it is safe to discard.

A FlatKV directory that is exactly one block behind memIAVL is **not** stale: it
is a torn kickoff commit left by a crash between the memIAVL and FlatKV commits
of the kickoff block. The node preserves that FlatKV directory, rolls memIAVL
back to the seed, and replays the kickoff block to the canonical app hash. When
a stale idle directory is discarded, the node logs a `discarding stale idle
flatkv directory` warning with the memIAVL and FlatKV versions.

## FAQ

Check warning on line 345 in node/giga-storage-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/giga-storage-migration.mdx#L345

Use sentence case for headings: 'FAQ'.

### Where do the data files live after migrating?

Expand All @@ -321,7 +357,7 @@
corresponding default path.
- This migration does not change SC data (`memiavl` and FlatKV).

### Does Giga SS Store change the app hash or consensus?

Check warning on line 360 in node/giga-storage-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/giga-storage-migration.mdx#L360

Use sentence case for headings: 'Does Giga SS Store change the app hash or consensus?'.

No. Giga SS Store changes only the SS layer, which does not affect the app hash.
It is a per-node change that is invisible to the network.
Expand All @@ -347,12 +383,12 @@
missing EVM state at query time. The safety checks above block this scenario at
startup.

### Does Giga SS Store support historical proofs?

Check warning on line 386 in node/giga-storage-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/giga-storage-migration.mdx#L386

Use sentence case for headings: 'Does Giga SS Store support historical proofs?'.

No, and neither does SeiDB. SS stores raw KVs and does not reconstruct
IAVL-style proofs.

### Does enabling Giga Storage change the receipt backend?

Check warning on line 391 in node/giga-storage-migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/giga-storage-migration.mdx#L391

Use sentence case for headings: 'Does enabling Giga Storage change the receipt backend?'.

In the `localnode` and `rpcnode` configuration scripts, setting
`GIGA_STORAGE=true` defaults `RECEIPT_BACKEND` to `pebble` unless you set
Expand Down
16 changes: 16 additions & 0 deletions node/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
top -p $(pgrep seid)
```

## AppHash mismatch errors

Check warning on line 87 in node/troubleshooting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/troubleshooting.mdx#L87

Use sentence case for headings: 'AppHash mismatch errors'.

If you get an AppHash mismatch, capture the state to compare it with a known-good version:

Expand Down Expand Up @@ -184,7 +184,7 @@

When you report a problem, always include the app hash, commit hash, and block height from your logs.

### Identifying AppHash errors

Check warning on line 187 in node/troubleshooting.mdx

View check run for this annotation

Mintlify / Mintlify Validation (seilabs) - vale-spellcheck

node/troubleshooting.mdx#L187

Use sentence case for headings: 'Identifying AppHash errors'.

In logs, AppHash errors usually look like this:

Expand Down Expand Up @@ -453,6 +453,22 @@

Then try the rollback steps again.



### Rollback target below the FlatKV retained history floor

On Giga Storage nodes, EVM state lives in a FlatKV store that only retains a bounded window of history (its retained snapshots plus WAL). A rollback can only reconstruct a target version that falls inside that window. If you ask to roll back to a version below the FlatKV retained history floor, the rollback is now refused up front, before any backend state is touched, so the store is left intact and still usable.

The error wraps a "version unreachable" condition and advises using state sync instead. It looks like this:

```text
flatkv cannot roll back to version [TARGET]: version unreachable: ...; use state sync instead
```

Because the target cannot be reconstructed from retained history, there is nothing to roll back to. Resync the node from a recent [snapshot](/node/snapshot) or with [state sync](/node/statesync) instead.

<Note>Historical read-only loads and exports below the same FlatKV history floor now fail with the same "version unreachable" error rather than panicking or serving approximate state. Reachable versions still succeed.</Note>

## HashVault app-hash equivocation panic

Under Autobahn, HashVault halts a node that tries to commit a different app hash for a height it already finalized. For background, see [HashVault](/node/technical-reference#hashvault-app-hash-equivocation-guard).
Expand Down
Loading