refactor: make Context and Evm generic over DB type

[Gabriel-Trintinalia]

Summary

Makes Context and Evm generic over the database type, enabling zevm to execute against any storage backend — not just the built-in InMemoryDB.

Changes

• Context(comptime DB: type) — Context is now a generic type parameterized on the database. DefaultContext = Context(InMemoryDB) is exported as an alias so all existing call sites are unchanged.
• EvmFor(comptime DB: type) — Evm is now a generic type parameterized on the database. Evm = EvmFor(InMemoryDB) preserves the existing concrete type.
• Removes the FallbackFns vtable — the comptime DB dispatch makes it unnecessary.
• Adds O(1) CREATE address collision check via the journal's warm set (replaces an O(n) scan).

Why a generic Context is necessary

On main, Context holds journaled_state: Journal(InMemoryDB) — the database type is hardcoded. This works for the standard execution path (blockchain tests, t8n) where all pre-state is loaded into InMemoryDB upfront.

zevm-stateless needs a different execution mode: stateless block execution. Instead of rebuilding the full pre-state in memory, it executes directly against a `WitnessDatabase` that serves every account/storage read by running a live MPT proof against the pre-state root:

// zevm-stateless/src/executor/main.zig
const witness_db = WitnessDatabase.init(node_index, pre_state_root, codes, block_hashes);
var ctx = Context(WitnessDatabase).new(witness_db, spec);

Every basic(address) / storage(address, key) call cryptographically verifies that the returned value is consistent with pre_state_root. This is the core security guarantee of stateless execution — without it, a prover could supply arbitrary account balances.

Using InMemoryDB for this would require pre-decoding all MPT witness nodes and loading them into a hashmap upfront, which defeats the purpose: there would be no proof verification and no way to detect a malicious witness.

Because Zig requires struct fields to have a compile-time-known type, `Context` must be parameterized on the DB type for this to work. `Journal(DB)` was already generic on `main`; this PR extends that to Context and Evm.

Impact on existing users

None. All existing code that used Context or Evm continues to work via the DefaultContext and Evm aliases which resolve to Context(InMemoryDB) and EvmFor(InMemoryDB) respectively.

Test plan

• `zig build test` passes
• All existing users of `Context` / `Evm` unaffected

🤖 Generated with Claude Code

---

Note

High Risk
High risk because it refactors core execution plumbing (Context, Evm, Host, journaling) and changes gas/account-access behavior around cold/warm checks, which can affect correctness of execution, state commits, and EIP-specific accounting.

Overview
Makes execution generic over the database backend. Context is replaced with Context(DB) and a DefaultContext = Context(InMemoryDB) alias, and handler Evm becomes EvmFor(DB) with the existing Evm preserved as the InMemoryDB specialization.

Reworks interpreter↔state integration to support typed DBs and correct access tracking. Host now type-erases the journal behind a JournalVTable, adds cold-check helpers, and updates call/create setup/finalization to snapshot/commit/revert per-frame tracking; the mainnet handler now warms access lists without eager DB loads and commits/discards per-tx tracking alongside commitTx.

Improves Block Access List (EIP-7928) correctness and CREATE collision checks. Opcodes (CALL, BALANCE, EXTCODE*, SLOAD, SELFDESTRUCT) now charge warm/cold gas before loading from DB and explicitly untrackAddress on OOG paths to avoid recording phantom accesses; Journal adds cold-check APIs, storage write revert metadata, and optional DB hooks, while InMemoryDB gains an O(1) hasNonZeroStorageForAddress index used for CREATE address-collision detection.

^{Written by Cursor Bugbot for commit b85262d. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[cursor]

isAddressCold misses access-list check causing false OOG

High Severity

The new isAddressCold only checks coinbase for addresses in evm_state with a stale transaction_id, but loadAccountMutOptionalCode (unchanged) checks the full warm_addresses.isCold(address) which also covers precompiles and access-list entries. In multi-tx block execution, an access-list address loaded in a prior tx will be reported as cold by isAddressCold but warm by accountInfo. The CALL opcode pre-check at line 138–145 uses isAddressCold and will incorrectly halt with OOG when gas is between WARM_ACCOUNT_ACCESS (100) and COLD_ACCOUNT_ACCESS (2600).

Additional Locations (1)

• src/interpreter/opcodes/call.zig#L137-L145

 

[garyschulte]

What is the reasoning behind using a witness db in zevm-stateless (and lazily decode) versus using an in-memory db where we pre-load with witness (and use a hash pool to prevent unecessary re-hashing) ?

It seems fine to have a generic db interface, I am wondering what the reasoning is behind using a witness db though. If it is performance considerations, do you have performance numbers that show the witness db to be faster?

moreover, I think this statement makes a false claim:

Using InMemoryDB for this would require pre-decoding all MPT witness nodes and loading them into a hashmap upfront, which defeats the purpose: there would be no proof verification and no way to detect a malicious witness.

[garyschulte]

what is chain with type void? should it be in the interface if it has no type and no constraints?

it looks like a pre-existing vestige. We can leave it I guess, but for a stateless client, all of the chain methods and the void type are just weird baggage.