Module cache 

The forked-EVM state cache: lazy RPC loading, a layered write funnel, and cheap copy-on-write snapshots.

EvmCache is the core handle. It fronts a foundry_fork_db-backed fork database with a hot revm cache layer, lazily fetching account and storage state from a provider on the first miss and serving it locally thereafter. Targeted writes and purges (StateUpdate, balance/code overrides, verified code seeds) flow through a single write funnel — never the RPC path — so event-driven state maintenance never round-trips. EvmCache::snapshot produces an immutable, Arc-shared, cross-thread EvmSnapshot (see snapshot) for parallel fan-out; overlay layers per-simulation state on top. See the crate-root docs for the full state stack and docs/INTERNALS.md for the snapshot cost model.

Re-exports

pub use overlay::EvmOverlay;

pub use slot_observations::SlotObservationTracker;

pub use snapshot::EvmSnapshot;

Modules

IERC20

Module containing a contract’s types and functions.

overlay

Per-simulation state overlays layered over a snapshot or the live cache.

slot_observations

Storage-slot change-frequency tracking and freshness heuristics.

snapshot

Immutable, shareable EVM state snapshots.

Structs

AccountProof

Account header + optional storage-proof slots from eth_getProof. slots is populated only for requested storage keys; an empty key list is a root-only probe (account fields + storage_hash, no slot payload).

AnyNetworkType

Re-export AnyNetwork for callers that need to construct providers. Types for a catch-all network.

BlockContextRequirements

Which block-context header fields a cache requires to be present.

BlockStateAccountDiff

Final account/storage values observed for one account in a block trace.

BlockStateDiff

Final state changes observed from a block-level state-diff trace.

BlockStateStorageDiff

Final value for one storage slot observed from a block trace.

CacheConfig

Configuration for disk-based caching of EVM state.

CallSimulationResult

Outcome of a simulated call: status, return data, gas used, and the touched access list. #[non_exhaustive] — construct via the simulation APIs and match with a wildcard arm.

CodeMismatch

One contradicted code claim from EvmCache::verify_code_seeds.

CodeVerifyReport

Outcome of EvmCache::verify_code_seeds: how each Pending canonical code claim resolved against the chain at the pinned block.

EvmCache

EVM cache with lazy-loading RPC backend.

EvmCacheBuilder

Fluent builder for EvmCache.

EvmSession

A session for executing multiple EVM operations without committing to the underlying DB.

ImmutableDataCache

Cache for immutable on-chain data that doesn’t change between blocks.

PrewarmReport

Outcome of EvmCache::prewarm_slots.

StorageBatchConfig

Concrete tuning knobs for the provider-backed StorageBatchFetchFn.

TxConfig

Per-call transaction-environment overrides for a simulation.

Enums

CacheSpeedMode

Preset runtime tuning profile for cache-side batch storage fetches.

CodeSeedState

Provenance + trust state of an address’s cached bytecode, for code that did not arrive via the lazy RPC backend.

MissingTargetBehavior

Behavior when overriding code at a target account that is not known to the cache/backend.

SharedMemoryCapacity

How much EVM shared memory (per-context working memory) to pre-allocate for simulations.

SimStatus

Outcome of a balance-delta-tracking simulation.

StorageFetchStrategy

How a cache’s batch storage fetcher loads slots.

Functions

load_binary_state

Load binary EVM state and populate the BlockchainDb.

parse_evm_spec

Parse an EVM hardfork spec name (e.g. from TOML config) into a revm SpecId.

point_read_storage_fetcher

Build the classic point-read StorageBatchFetchFn: JSON-RPC batches of eth_getStorageAt, sized and throttled by StorageBatchConfig.

save_binary_state

Save the current BlockchainDb state to a binary file.

Type Aliases

AccountFieldsFetchFn

Callback fetching (balance, EXTCODEHASH) samples for many addresses at a pinned block — one bulk eth_call by default (the ACCOUNT_FIELDS_EXTRACTOR_CODE program). Sync and type-erased with the same bridging rules as StorageBatchFetchFn (multi-thread tokio runtime required for the default provider-backed implementation).

AccountProofFetchFn

Callback for fetching account headers (and optional storage-proof slots) directly from RPC via eth_getProof, mirroring StorageBatchFetchFn.

BlockStateDiffFetchFn

Callback for fetching one block’s state diff through debug/trace RPC.

ForkCacheDB

The database type used by the EVM cache. CacheDB wraps SharedBackend which lazily fetches data from RPC on-demand.

RpcCallFn

Callback for making direct RPC eth_call requests, bypassing revm simulation. Used when batch-querying many contracts where revm’s lazy storage fetching would be prohibitively slow (e.g. querying 500+ gauge contracts).

StorageBatchFetchFn

Callback for batch-fetching storage slots directly from RPC, bypassing SharedBackend.