diff --git a/evm/installing-seid-cli.mdx b/evm/installing-seid-cli.mdx index f30f135..5480b7c 100644 --- a/evm/installing-seid-cli.mdx +++ b/evm/installing-seid-cli.mdx @@ -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 diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx index 06760e2..2f9187b 100644 --- a/node/giga-storage-migration.mdx +++ b/node/giga-storage-migration.mdx @@ -306,6 +306,42 @@ In the default `auto` write mode, the node does not use a FlatKV store that this 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 ### Where do the data files live after migrating? diff --git a/node/troubleshooting.mdx b/node/troubleshooting.mdx index 69ef919..ad73aa5 100644 --- a/node/troubleshooting.mdx +++ b/node/troubleshooting.mdx @@ -453,6 +453,22 @@ This means that you did not shut down the node properly. In that case, try to sh 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. + +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. + ## 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).