fix(storage): reject a data directory from another network

[MegaRedHand]

Stacked on #554 (fix/resume-db-without-checkpoint-url). Base is that branch, so this diff is just the genesis check. Merge #554 first.

🗒️ Description / Motivation

Store::from_db_state decided whether a data directory was ours by comparing genesis_time alone, read from the persisted ChainConfig, and on mismatch logged a warning and returned None — "treat as empty":

if persisted_config.genesis_time != expected_genesis_time {
    warn!(..., "Persisted DB has a different genesis_time; treating as empty");
    return Ok(None);
}

Two problems with that.

1. "Treat as empty" is not empty. The caller then wrote a fresh anchor over the foreign chain's rows without clearing them. get_signed_blocks_by_slot_range resolves each slot through BlockRoots with no anchor check:

for slot in start_slot..=end_slot {
    let Some(root_bytes) = view.get(Table::BlockRoots, &encode_block_root_key(slot))? else { continue };
    // ... no check that this root belongs to the current chain
}

so for slots the new chain had not reached yet, BlocksByRange served the other network's blocks to peers, who reject them and score-penalize us. (Fork choice is unaffected: compute_lmd_ghost_head is seeded from latest_justified, so foreign roots are unreachable and never accumulate weight.)

2. ChainConfig is { genesis_time: u64 }. A network regenerated with the same genesis time but a different validator set was not detected at all — the DB was resumed as if it were ours. #554 makes the DB readable without --checkpoint-sync-url, which puts that case on the default restart path.

What Changed

crates/common/types/src/genesis.rs — new verify_state_genesis(state, genesis_time, expected_validators) plus a GenesisConfig::verify_state convenience wrapper, and a GenesisMismatch error enum. Compares genesis time and the full validator registry: count, sequential indices, and both pubkeys per validator. The validator set is fixed at genesis (nothing in the state transition mutates it), so any state of our chain must carry exactly that registry, whatever slot it sits at.

crates/storage/src/store.rs — from_db_state takes &GenesisConfig and verifies the finalized state (never pruned, and the state the anchor is rebuilt from) rather than the persisted config. A mismatch is now Error::GenesisMismatch. A missing finalized state is Error::UnexpectedMissingState instead of silently "empty".

bin/ethlambda/src/checkpoint_sync.rs — verify_checkpoint_state had its own copy of the same four checks; it now delegates to the shared function, and GenesisTimeMismatch / ValidatorCountMismatch / NonSequentialValidatorIndex / ValidatorPubkeyMismatch collapse into one Genesis(#[from] GenesisMismatch). Its checkpoint-only sanity checks stay put — slot != 0 must not apply to the DB path, since a data directory legitimately sits at genesis while a downloaded anchor never does.

crates/storage/src/lib.rs — export Error. It was a private type appearing in public signatures, so callers could not name it to match on it.

bin/ethlambda/src/main.rs — fetch_initial_state propagates the error (if let Some(store) = Store::from_db_state(..)?) instead of swallowing it with if let Ok(Some(..)).

Correctness / Behavior Guarantees

DB in data directory	before	after
Ours	resumed	resumed
Different GENESIS_TIME	warn → new anchor written over foreign rows	startup aborts, DB untouched
Same GENESIS_TIME, different validator set	undetected, resumed as ours	startup aborts
Genuinely empty	initialize	initialize (unchanged)

Aborting is deliberate rather than falling back: there is no safe way to reuse the directory, so the operator has to fix --data-dir or remove it. The error names what differs, e.g. persisted state does not match the configured genesis: validator 1 pubkey mismatch (attestation or proposal key).

Operational note for reviewers: any flow that reuses a data directory across a genesis regeneration now fails to boot loudly instead of silently restarting from a fresh anchor. lean-quickstart's --generateGenesis implies --cleanData, so local devnets are unaffected; ansible/Hive flows that regenerate genesis in place would need to clear the directory.

Tests Added / Run

crates/common/types — 5 tests on verify_state: accepts a state from the same genesis; rejects different genesis time, different validator count, swapped validator keys at the same count and genesis time, and non-sequential indices.

crates/storage — from_db_state_errors_on_genesis_time_mismatch and from_db_state_errors_on_validator_set_mismatch.

bin/ethlambda — fails_when_db_genesis_time_differs (also asserts the original DB still loads under its own genesis, i.e. it was not overwritten) and fails_when_db_validator_set_differs.

One test changed contract rather than being fixed: from_db_state_returns_none_on_genesis_time_mismatch encoded the "treat as empty" behavior this PR removes. It is replaced by the two ..._errors_on_... tests above. Flagging explicitly since that is a deliberate contract change, not a broken test.

make fmt && make lint && make test    # 30 test binaries, 0 failures

Related Issues / PRs

• Stacked on fix(startup): resume from existing DB without a checkpoint URL #554

✅ Verification Checklist

• Ran make fmt — clean
• Ran make lint (clippy with -D warnings) — clean
• Ran make test (cargo test --workspace --profile release-fast) — all passing

[github-actions]

🤖 Kimi Code Review

This PR introduces a critical security fix for network identity verification while refactoring genesis validation into a shared, testable module. The changes prevent accidental cross-network data corruption and ensure validator registry integrity.

Security & Correctness

Critical Fix: Foreign Network Detection

• File: crates/storage/src/store.rs (lines 647-666)
• Issue Resolved: Previously, from_db_state only checked genesis_time and silently treated mismatches as empty databases (with just a warning). This allowed a node to potentially re-initialize on top of a foreign chain's data, leaving orphaned blocks that could be served to peers via BlocksByRange.
• Fix: Now validates the full validator registry (count, sequential indices, and both XMSS pubkeys) against the configured genesis. Returns Error::GenesisMismatch as a hard error, aborting startup.

Checkpoint Sync Validation

• File: bin/ethlambda/src/checkpoint_sync.rs (lines 202-205)
• Improvement: Replaces inline validation with shared verify_state_genesis function, ensuring checkpoint sync and disk-resume paths use identical network-identity checks. The Genesis error variant (line 49) properly encapsulates all mismatch scenarios.

Code Quality

Error Handling

• File: crates/common/types/src/genesis.rs (lines 7-21)
• The new GenesisMismatch enum provides structured error contexts for debugging. The #[from] implementations in CheckpointSyncError and Error enable ergonomic propagation.

Performance

• File: crates/storage/src/store.rs (lines 657-666)
• Loading the full finalized state at startup to verify validators is O(n) in validator count. For networks with large validator sets (e.g., 1M+), this adds startup overhead but is acceptable given the security requirements. Consider documenting this cost.

Testing

• File: crates/storage/src/store.rs (lines 2993-3060)
• Excellent test coverage for the three cases: empty DB, matching genesis, and both types of mismatch (time vs. validators).
• File: bin/ethlambda/src/main.rs (lines 981-1022)
• Integration tests verify that foreign databases are neither loaded nor overwritten.

Minor Observations

1. Error Message Clarity

   • File: crates/common/types/src/genesis.rs (line 13)
   • The format string "(expected {position}, got {got})" is correct since position equals the expected index, but consider renaming the field to expected in NonSequentialIndex for clarity, or adjust the template to avoid confusion.

2. State Retrieval Safety

   • File: crates/storage/src/store.rs (line 661)
   • Using latest_finalized to load the verification state assumes the finalized state is never pruned. Ensure this invariant holds in your pruning strategy, or document that the latest finalized state must be retained.

3. Iterator Safety

   • File: crates/common/types/src/genesis.rs (line 70)
   • The zip usage is safe due to the preceding length check, but consider adding a debug assertion or using zip_eq (from itertools) in future to panic on length mismatch in debug builds.

Consensus Considerations

The validator registry verification correctly enforces Ethereum's network identity definition:

• Genesis time and validator set are the canonical network identifiers
• Sequential index validation (0..n) ensures state integrity
• Dual pubkey comparison (attestation + proposal) aligns with 3SF-mini's XMSS requirements

Acknowledgment: The refactoring effectively deduplicates validation logic between sync and storage layers, reducing maintenance burden and preventing divergence in security-critical checks.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[github-actions]

🤖 Codex Code Review

1. High: the new startup guard only proves that the finalized state matches the configured genesis; it does not prove that the persisted canonical indices are clean. Store::from_db_state accepts the DB after genesis.verify_state(&state) on the finalized state (crates/storage/src/store.rs), but BlocksByRange is still served directly from Table::BlockRoots (crates/storage/src/store.rs, crates/net/p2p/src/req_resp/handlers.rs). Since init_store writes new anchor metadata/index rows without clearing old ones (crates/storage/src/store.rs), a data dir that was already contaminated by the previous “re-anchor over foreign DB” behavior can still pass this new check and continue serving stale foreign canonical blocks. If the intent is to close that security hole, startup needs either a stronger integrity check over the canonical chain/index tables or a one-time cleanup/migration path for previously mixed directories.

No other correctness issues stood out in the diff; the shared genesis-identity check itself is a solid improvement.

I couldn’t run the Rust tests here because this environment has a read-only Cargo/rustup home and no network access, so this is a static review only.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt

[greptile-apps]

Greptile Summary

This PR prevents a node from reusing a data directory belonging to another network.

• Adds shared genesis identity verification covering genesis time, validator count, sequential indices, and validator public keys.
• Applies that verification to persisted finalized state and checkpoint-sync state.
• Propagates storage identity and missing-state errors to abort startup instead of overwriting foreign data.
• Exports the storage error type and documents the new startup behavior.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code defect identified.

The shared identity validation matches the state model’s immutable validator registry, persisted-state failures now propagate before any replacement anchor is written, and checkpoint-specific sanity checks remain intact.

Important Files Changed

Filename	Overview
crates/common/types/src/genesis.rs	Adds a shared, well-tested genesis identity check over genesis time and the immutable validator registry.
crates/storage/src/store.rs	Validates the persisted finalized state before resuming and returns explicit errors rather than treating foreign data as empty.
bin/ethlambda/src/checkpoint_sync.rs	Reuses the shared genesis verifier while retaining checkpoint-specific structural checks.
bin/ethlambda/src/main.rs	Propagates persisted-store errors so foreign data aborts startup without being overwritten.
crates/storage/src/error.rs	Adds explicit errors for missing finalized state and genesis mismatch.
crates/storage/src/lib.rs	Publicly exports the storage error type used by public fallible APIs.
docs/checkpoint_sync.md	Documents foreign-state rejection and the shared checkpoint/persisted-state identity checks.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Open data directory] --> B{Chain metadata present?}
  B -- No --> C[Initialize from genesis or checkpoint]
  B -- Yes --> D[Load finalized state]
  D --> E{Matches configured genesis?}
  E -- Yes --> F[Resume persisted store]
  E -- No --> G[Abort startup without modifying DB]
  D --> H{State missing or unreadable?}
  H -- Yes --> G

Loading

_{Reviews (1): Last reviewed commit: "fix(storage): reject a data directory fr..." | Re-trigger Greptile}