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 overlay::MissingState;

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.

DurableCheckpointBlock

Canonical block committed by a durable checkpoint.

DurableCheckpointIdentity

Stable identity of one durable cache consumer.

DurableCheckpointMetadata

Public commit metadata stored alongside the cache snapshot.

DurableCheckpointStore

Filesystem-backed durable checkpoint store.

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.

LoadedDurableCheckpoint

A decoded checkpoint awaiting identity/hash validation and restore.

PrewarmReport

Outcome of EvmCache::prewarm_slots.

ReadSetHydrationReport

Exact-block hydration result for one learned execution read set.

ReadSetWarmupBatch

Declared known slots plus calls with unknown read sets.

ReadSetWarmupCall

One call whose storage read set may be remotely discovered.

ReadSetWarmupConfig

Heuristic configuration for EvmCache::prewarm_read_sets.

ReadSetWarmupReport

Outcome of cache-owned read-set warming.

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.

DurableCheckpointError

Durable checkpoint persistence or compatibility failure.

MissingTargetBehavior

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

ReadSetHydrationFailure

One exact-hydration failure, with enough structure for callers to decide whether to retry, re-warm, or reject a candidate.

ReadSetWarmupError

A cache-owned read-set warmup could not honor its selected discovery policy.

ReadSetWarmupStrategy

Read-set discovery policy.

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.

Constants

DEFAULT_MAX_DURABLE_CHECKPOINT_BYTES

Default upper bound for a single durable checkpoint file (512 MiB).

Functions

account_proof_fetcher

Build the cache’s bounded provider-backed eth_getProof callback without constructing an EvmCache.

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.

provider_storage_fetcher

Build the same provider-backed storage fetcher selected by an EvmCacheBuilder without constructing an EvmCache.

save_binary_state

Save the current BlockchainDb state to a binary file.

Type Aliases

AccessListFetchFn

Callback for deriving calls’ read sets via eth_createAccessList.

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.