Struct EvmCacheBuilder 

pub struct EvmCacheBuilder<P> { /* private fields */ }

Fluent builder for EvmCache.

A readable alternative to the positional EvmCache::with_cache constructor. Defaults: latest block, no disk cache, SpecId::CANCUN.

let provider = ProviderBuilder::new()
    .network::<AnyNetwork>()
    .connect_http("https://example-rpc.invalid".parse()?);
let cache = EvmCache::builder(Arc::new(provider))
    .latest_block()
    .spec(SpecId::CANCUN)
    .build()
    .await;

Implementations

impl<P> EvmCacheBuilder<P>

where P: Provider<AnyNetwork> + 'static,

pub fn new(provider: Arc<P>) -> Self

Start a builder over the given provider.

pub fn max_concurrent_proofs(self, cap: usize) -> Self

Cap the default account-proof fetcher’s concurrent eth_getProof fan-out (default 8, name-symmetric with BulkCallConfig::max_concurrent_calls).

eth_getProof is single-address at the RPC level, so when the root gate or an account resync probes N tracked accounts in one seam call, concurrency is the only wall-clock lever: N × RTT serial becomes ~ceil(N / cap) × RTT. Values are clamped to at least 1. Custom fetchers installed via set_account_proof_fetcher ignore this knob.

pub fn block(self, block: BlockId) -> Self

Pin simulations and RPC fetches to a specific block.

Use this to fork at a fixed height for reproducible simulation. Without a call to block or latest_block the builder defaults to the latest block at build time.

pub fn latest_block(self) -> Self

Pin to the latest block.

The height is resolved when build fetches the block header, so the cache forks at whatever was latest at construction. Use block instead to pin a fixed, reproducible height.

pub fn spec(self, spec_id: SpecId) -> Self

Set the EVM hardfork spec (must match the chain’s execution layer).

pub fn chain_id(self, chain_id: u64) -> Self

Set the chain ID reported to simulations via the CHAINID opcode.

Recommended. This is the explicit, authoritative way to set the chain ID. If left unset, build infers it from the provider (eth_chainId), falling back to 1 (Ethereum mainnet) only if that query fails. A disk cache_config also carries a chain_id (which additionally namespaces the on-disk cache directory); when both are set, the value passed here wins for the CHAINID opcode, so keep them consistent.

pub fn cache_config(self, cache_config: CacheConfig) -> Self

Enable disk-backed caching with the given configuration.

Supplying a CacheConfig turns on persistence of EVM state, bytecodes, and immutable data under the configured chain directory; the cache is loaded on build and flushed on drop. Omit it for a purely in-memory cache backed solely by RPC.

pub fn shared_memory_capacity(self, capacity: SharedMemoryCapacity) -> Self

Set how much EVM shared memory to pre-allocate per simulation context.

Defaults to SharedMemoryCapacity::Fixed with 64 * 1024 bytes (65,536 bytes). Use Fixed(n) to pin a size, or SharedMemoryCapacity::Auto to size it from the chain state loaded at build time (e.g. a bincode state file supplied via cache_config). See SharedMemoryCapacity for the trade-offs.

pub fn storage_batch_config(self, config: impl Into<StorageBatchConfig>) -> Self

Set the concrete storage batch-fetch configuration for this cache instance.

The config controls the batch size and concurrency used by the provider-backed StorageBatchFetchFn. Defaults to StorageBatchConfig::default (the CacheSpeedMode::Slow preset). Different cache instances can use different values in the same process. Zero values are normalized to one.

pub fn speed_mode(self, mode: CacheSpeedMode) -> Self

Set the storage batch-fetch profile from a preset.

Shorthand for storage_batch_config with mode.into().

pub fn storage_fetch_strategy(self, strategy: StorageFetchStrategy) -> Self

Choose how the cache’s batch storage fetcher loads slots.

Defaults to StorageFetchStrategy::BulkCall with BulkCallConfig::default: bulk eth_call state-override extraction, repaired by (and degrading to) the point-read fetcher that storage_batch_config tunes. Use StorageFetchStrategy::PointRead to restore the classic per-slot behavior.

pub fn bulk_call_config(self, config: BulkCallConfig) -> Self

Tune the bulk eth_call extraction path.

Shorthand for storage_fetch_strategy with StorageFetchStrategy::BulkCall(config) — e.g. raising max_slots_per_call on a provider with a generous gas cap, or selecting CallDispatch::CallMany on Erigon-lineage endpoints.

pub fn block_context_requirements(self, reqs: BlockContextRequirements) -> Self

Set which block-context header fields the cache requires.

See BlockContextRequirements. Defaults to lenient. Only try_build enforces non-lenient requirements at construction; the infallible build always stays lenient.

pub fn strict_block_context(self, strict: bool) -> Self

Convenience toggle: require every block-context field (true) or none (false).

Equivalent to block_context_requirements with strict / lenient. Enforced only by try_build.

pub async fn build(self) -> EvmCache

Build the EvmCache, fetching the pinned block’s header for context.

If a chain ID was not set via chain_id, it is inferred from the provider (eth_chainId); see chain_id for the full resolution order.

This constructor is infallible and always uses lenient enforcement (a missing block-context field is silently defaulted). To enforce BlockContextRequirements at construction, use try_build instead.

pub async fn try_build(self) -> Result<EvmCache, BlockContextError>

Build the EvmCache, enforcing the configured BlockContextRequirements against the fetched block header.

Builds the cache the same way build does, then, if the requirements are non-lenient, validates the pinned block’s header:

• if the header could not be fetched (the provider errored or returned no block), returns BlockContextError::FetchFailed;
• otherwise validates the fetched header via BlockContextRequirements::validate_header and propagates any BlockContextError::MissingField.

A lenient build never errors (it does not fetch a header solely to validate). On success the requirements are stored on the returned cache so a later advance_block enforces them too.