Struct EvmOverlay 

pub struct EvmOverlay { /* private fields */ }

Per-simulation mutable overlay on an immutable snapshot.

Lookup order: dirty layer → snapshot → ext_db (optional RPC fallback).

This type is Send (unlike EvmCache) because it uses no Rc/RefCell. Each simulation task gets its own EvmOverlay with a cheap Arc::clone of the shared EvmSnapshot.

Reuse across simulations (Pillar A.2)

A worker doing many sims against the same snapshot can call Self::new once and Self::reset between sims instead of allocating a fresh overlay each time. The reusable shared-memory buffer is also recycled across calls — see Self::call_raw — without making the overlay !Send.

Implementations

impl EvmOverlay

pub fn new(snapshot: Arc<EvmSnapshot>, ext_db: Option<SharedBackend>) -> Self

Create a new overlay on the given snapshot.

The reusable shared-memory buffer is pre-allocated to the snapshot’s configured shared-memory capacity (see SharedMemoryCapacity).

pub fn reset(&mut self)

Clear the per-simulation dirty layer so this overlay can be reused for the next simulation against the same snapshot, without reallocating (Pillar A.2).

A worker doing K sims calls Self::new once and reset() between sims instead of allocating a fresh overlay (plus dirty maps plus an Arc clone) each time. After reset() the overlay reads the pristine snapshot again — it is exactly equivalent to a freshly-built overlay on the same snapshot. The snapshot Arc, the optional ext_db, and the reusable shared-memory buffer (kept at capacity) are retained.

pub fn blockhash_zero_fallback(&self) -> bool

true if any BLOCKHASH read on this overlay fell through to the ZERO fallback (no snapshot-provided hash for that number and no ext_db) since construction or the last reset.

The freshness validator uses this to fail closed: a sim that read a hash its ext-db-less overlays cannot resolve is reported Unverified rather than silently confirmed against a ZERO stand-in.

Only reads revm actually routes to the database can set this: requests outside the EVM’s valid lookback window ([current − 256, current)) return spec-mandated ZERO without a database call — that value is correct on-chain too, so such reads are deliberately not flagged.

pub fn chain_id(&self) -> u64

Chain ID of the block context captured by the underlying snapshot.

This is the value installed into cfg.chain_id by Self::build_evm.

pub fn block_number(&self) -> Option<u64>

Block number of the snapshot’s block context, or None if it was not captured.

When present this is the block.number simulations run against; when None, Self::build_evm leaves revm’s default block number in place.

pub fn basefee(&self) -> Option<u64>

Base fee of the snapshot’s block context, or None if it was not captured.

Note that base-fee checks are disabled in the simulation EVM, so this is informational rather than enforced against the transaction.

pub fn timestamp(&self) -> Option<u64>

Timestamp of the snapshot’s block context, or None if it was not captured.

When None, Self::build_evm substitutes the current wall-clock time for block.timestamp.

pub fn build_evm( &mut self, ) -> MainnetEvm<Context<BlockEnv, TxEnv, CfgEnv, &'_ mut EvmOverlay, Journal<&'_ mut EvmOverlay>, ()>>

Build a revm EVM instance backed by this overlay.

This allocates a fresh 64 KB shared-memory buffer each call: it hands the EVM out to the caller and cannot reclaim the buffer afterwards, so it cannot recycle the overlay’s reusable buffer. The internal call methods (Self::call_raw, etc.) recycle the buffer instead (Pillar A.2).

Note: The returned EVM is !Send (due to LocalContext’s Rc<RefCell>), but this is fine because it’s created and used within a single task.

pub fn call_raw( &mut self, from: Address, to: Address, calldata: Bytes, ) -> Result<ExecutionResult>

Execute a non-committing call and return the raw ExecutionResult.

The EVM state is reverted to a checkpoint after execution on both success and failure, so the call never mutates this overlay’s dirty layer. Each overlay simulation is therefore isolated: repeated calls all observe the same base state.

A revert or halt is not an error here — it is reported through the returned ExecutionResult variant. Only failure to build or transact the call yields Err.

Errors

Returns an error if the TxEnv cannot be built from the given inputs, or if revm fails to transact the call (for example a database error while loading state from the RPC fallback).

Examples

let mut overlay = EvmOverlay::new(snapshot, None);
let result = overlay.call_raw(Address::ZERO, Address::ZERO, Bytes::new())?;
// State is reverted; a second call sees the same base state.
let _again = overlay.call_raw(Address::ZERO, Address::ZERO, Bytes::new())?;

pub fn simulate_with_transfer_tracking( &mut self, from: Address, to: Address, calldata: Bytes, owner: Address, tokens: Option<impl IntoIterator<Item = Address>>, commit: bool, ) -> SimulationResult<CallSimulationResult>

Simulate a call with transfer tracking via the TransferInspector.

This is the overlay-compatible equivalent of super::EvmCache::simulate_with_transfer_tracking. It captures ERC20 Transfer events during execution to compute balance deltas for owner (restricted to tokens when provided) without relying on pre/post balance queries.

On a reverting or halting call the EVM state is reverted to a checkpoint before returning, so a failed simulation never mutates this overlay. On success the call either commits the journaled changes into the overlay’s dirty layer (commit == true) or reverts them (commit == false); a non-committing run leaves each overlay simulation isolated from the next.

Errors

Returns an error if the TxEnv cannot be built, if revm fails to transact the call, if the call reverts (mapped from the revert payload), or if the call halts. In every error case the EVM state is reverted first, regardless of commit.

Examples

let mut overlay = EvmOverlay::new(snapshot, None);
let sim = overlay.simulate_with_transfer_tracking(
    owner,
    token,
    Bytes::new(),
    owner,
    Some([token]),
    false, // non-committing: state is reverted afterwards
)?;
let _delta = sim.token_deltas.get(&token);

pub fn call_raw_with_inspector<I>( &mut self, from: Address, to: Address, calldata: Bytes, tx: &TxConfig, inspector: I, commit: bool, ) -> SimulationResult<(ExecutionResult, I)>

where I: for<'a> Inspector<Context<BlockEnv, TxEnv, CfgEnv, &'a mut EvmOverlay, Journal<&'a mut EvmOverlay>, ()>>,

Run a single call with a caller-supplied Inspector, returning the raw ExecutionResult and handing the inspector back for the caller to read.

This is the inspector-generic public seam: where Self::simulate_with_transfer_tracking hard-wires the TransferInspector, this accepts any revm::Inspector — a CallTracer, an InspectorStack composing several, or a caller-defined one. It honors a full TxConfig (value/gas/nonce/access list) exactly like Self::call_raw_with_access_list_with and recycles the reusable shared-memory buffer like the other call methods.

Unlike simulate_with_transfer_tracking, a revert or halt is not an error: the raw ExecutionResult variant (Success / Revert / Halt) is returned as Ok so the inspector’s captured frames (e.g. a reverted call tree) remain observable. Only a tx-env build failure or a transact/database error yields Err.

On a successful transact the journaled changes are either committed into the overlay’s dirty layer (commit == true) or reverted (commit == false), matching Self::simulate_with_transfer_tracking. On a revert/halt the checkpoint is always reverted regardless of commit, so a failed call never mutates this overlay. On a transact error the checkpoint is reverted too.

Errors

Returns an error if the TxEnv cannot be built from from/to/tx, or if revm fails to transact the call (e.g. a database error while loading state).

Examples

let mut overlay = EvmOverlay::new(snapshot, None);
let (result, tracer) = overlay.call_raw_with_inspector(
    Address::ZERO,
    to,
    Bytes::new(),
    &TxConfig::default(),
    CallTracer::new(),
    false,
)?;
let _ = result;
let _trace = tracer.into_trace();

pub fn simulate_bundle( &mut self, txs: &[BundleTx], opts: &BundleOptions, ) -> SimulationResult<BundleResult>

Apply txs in order against this overlay over cumulative block state, with a revert policy and coinbase/miner-payment accounting (Phase 6 Track A+B).

Each transaction observes the committed writes of the ones before it: the bundle runs on a single overlay/EVM with one outer checkpoint plus a per-transaction inner checkpoint, so it does not rebuild a fresh overlay per transaction. See the bundle module for the public vocabulary (BundleTx, BundleOptions, RevertPolicy, TxOutcome, BundleResult).

Revert policy

• RevertPolicy::Atomic: the first transaction that reverts/halts rolls the whole bundle back to the outer checkpoint, sets succeeded = false, and stops (per_tx ends at the failing transaction). coinbase_payment is 0 and the overlay is unchanged.
• RevertPolicy::AllowReverts: a revert at a whitelisted index rolls back only that transaction (inner checkpoint) and execution continues; a revert at a non-whitelisted index behaves like Atomic.

Coinbase accounting

coinbase_payment is the block beneficiary’s balance delta across the kept transactions. Under EIP-1559 revm credits the beneficiary only the priority fee ((effective_gas_price − basefee) × gas_used) and burns the base fee in-EVM, so the delta is the honest miner payment (plus any direct coinbase tips). Saturating.

Commit semantics

opts.commit == true folds the bundle’s cumulative state into this overlay’s dirty layer (observable by subsequent overlay calls); false reverts the outer checkpoint so the overlay is unchanged. A failed atomic bundle never leaves partial state regardless of commit.

Errors

Returns SimError if a transaction environment cannot be built or revm fails to transact (e.g. a database error). A transaction reverting is not an error — it is reported through the per-transaction TxOutcome and the revert policy.

pub fn call_raw_with_access_list( &mut self, from: Address, to: Address, calldata: Bytes, ) -> Result<(ExecutionResult, StorageAccessList)>

Execute a non-committing call and return the result plus the touched StorageAccessList.

The access list is collected from every account marked touched in the journaled state after execution, recording both the touched accounts and the storage slots accessed under each.

The EVM state is reverted to a checkpoint after a successful transact on both success and revert/halt outcomes, so the call never mutates this overlay’s dirty layer and each overlay simulation stays isolated. As with Self::call_raw, a revert or halt is reported through the returned ExecutionResult rather than as an error.

Errors

Returns an error if the TxEnv cannot be built, or if revm fails to transact the call (for example a database error while loading state).

Examples

let mut overlay = EvmOverlay::new(snapshot, None);
let (result, access_list) =
    overlay.call_raw_with_access_list(Address::ZERO, Address::ZERO, Bytes::new())?;

pub fn call_raw_with_access_list_with( &mut self, from: Address, to: Address, calldata: Bytes, tx: &TxConfig, ) -> Result<(ExecutionResult, StorageAccessList)>

Like call_raw_with_access_list but honors a full TxConfig: native value, gas_limit, gas_price, nonce, and a pre-warming EIP-2930 access_list.

This is what the freshness optimistic loop uses so a SimRequest’s tx environment — e.g. a payable call carrying value, or a gas-bounded call — is reproduced faithfully instead of silently running as a zero-value, default-gas call. Like the shorthand it is non-committing (the checkpoint is reverted) and returns the captured storage access list.

pub fn override_slot(&mut self, address: Address, slot: U256, value: U256)

Write a storage value into this overlay’s dirty layer.

The dirty layer takes precedence over the snapshot on subsequent reads (see the lookup order on EvmOverlay), so this injects a value into a snapshot-backed overlay without mutating the shared snapshot.

Freshness validation

This is the freshness validator’s correction step. When a slot the snapshot captured is found to be stale, the validator writes the freshly-fetched value here and then re-runs the simulation (e.g. via Self::call_raw): the re-run reads the corrected slot out of the dirty layer instead of the stale snapshot value, so the corrected result becomes observable. Because the override lives only in this overlay, other overlays sharing the same Arc<EvmSnapshot> are unaffected.

Examples

let mut overlay = EvmOverlay::new(snapshot, None);
// Inject the fresh value, then re-run to observe the corrected result.
overlay.override_slot(token, slot, U256::from(42u64));
let corrected = overlay.call_raw(Address::ZERO, token, Bytes::new())?;

pub fn call_sol<C: SolCall>( &mut self, to: Address, call: C, ) -> Result<C::Return>

Execute a non-committing typed Solidity call from Address::ZERO, decoding the return — the overlay counterpart to EvmCache::call_sol.

let bal = overlay.call_sol(token, IErc20::balanceOfCall { account: alice })?;

pub fn call_sol_from<C: SolCall>( &mut self, from: Address, to: Address, call: C, ) -> Result<C::Return>

Execute a non-committing typed Solidity call from an explicit sender, decoding the return.

pub fn mock_balance( &mut self, token: Address, holder: Address, amount: U256, ) -> SimulationResult<bool>

Mock holder’s ERC-20 balance of token to amount — overlay-local.

Discovers the balance mapping slot and layout (Solidity / Vyper / Solady) from a single balanceOf(holder) simulation, writes amount to that slot in this overlay’s dirty layer via override_slot, and verifies. The cache and snapshot are never mutated; the mock is dropped with the overlay.

Returns Ok(true) if set and verified, Ok(false) if no balance slot was discoverable or the write did not drive the return (e.g. a rebasing token, or holder == Address::ZERO, which is refused). A failed attempt leaves no stray write.

pub fn mock_allowance( &mut self, token: Address, owner: Address, spender: Address, amount: U256, ) -> SimulationResult<bool>

Mock owner’s ERC-20 allowance to spender on token — overlay-local.

Discovers the (nested) allowance mapping entry keyed by both addresses, writes amount (pass U256::MAX for “unlimited”), and verifies. Refuses owner == Address::ZERO. Same isolation and failure semantics as mock_balance.

pub fn mock_view( &mut self, to: Address, calldata: Bytes, desired: U256, ) -> SimulationResult<bool>

Mock the return value of a single-word view call by finding the storage slot that drives it and overriding that slot — overlay-local.

Runs to.calldata, identifies the SLOAD whose loaded value equals the call’s returned word (see HashStorageProbe::slots_returning), writes desired there, and verifies the call now returns desired. Works for balances, allowances, totalSupply, and any getter that returns a single stored word. Returns Ok(false) (leaving no stray write) when the return is computed from more than one slot, so it can’t be set by a single override.

pub fn mock_call<C: SolCall>( &mut self, to: Address, call: C, desired: U256, ) -> SimulationResult<bool>

Typed mock_view: mock the desired return of a SolCall getter that returns a single word.

overlay.mock_call(token, IErc20::totalSupplyCall {}, U256::from(1_000u64))?;

Trait Implementations

impl Database for EvmOverlay

type Error = DatabaseError

The database error type.

fn basic( &mut self, address: Address, ) -> Result<Option<AccountInfo>, Self::Error>

Gets basic account information.

fn code_by_hash(&mut self, code_hash: B256) -> Result<Bytecode, Self::Error>

Gets account code by its hash.

fn storage( &mut self, address: Address, index: U256, ) -> Result<U256, Self::Error>

Gets storage value of address at index.

fn block_hash(&mut self, number: u64) -> Result<B256, Self::Error>

Gets block hash by block number.

fn storage_by_account_id( &mut self, address: Address, account_id: usize, storage_key: Uint<256, 4>, ) -> Result<Uint<256, 4>, Self::Error>

Gets storage value of account by its id. By default call Database::storage method.

impl DatabaseCommit for EvmOverlay

fn commit(&mut self, changes: HashMap<Address, Account>)

Commit changes to the database.

fn commit_iter(&mut self, changes: &mut dyn Iterator<Item = (Address, Account)>)

Commit changes to the database with an iterator.