Struct BlockSimHandle 

pub struct BlockSimHandle<'a> { /* private fields */ }

Owns a per-block shared EVM (one CacheDB + revm Context, state overrides applied once) for the in-process sim fan-out (Tier 1).

Built ONCE per block by BlockSimHandle::build (the strategy’s dispatch_profitable_results calls it), then each candidate path is simulated SERIALLY by the strategy’s simulate_path_on_evm over the shared &mut evm exposed by BlockSimHandle::evm_mut. Per-path isolation is revm’s finalize() (clears the journal between paths — execute()’s SSTOREs live in the per-path State returned by finalize, never committed to the shared CacheDB; see the module-level note above). The CacheDB + EVM drop naturally at end of block — no cross-block caching in Tier 1, so memory is bounded by one block’s working set.

Serial (not buffer_unordered) because a shared &mut evm can’t be held across 'static+Send futures. The benchmark’s config B (serial-warm, ~1 µs p50) beats config A (parallel-cold, ~590 µs p50) by ~60× — losing concurrency is a NET WIN because the per-path RPC cold-miss dwarfs the per-path EVM execution.

The state overrides — owner ETH funding, executor code injection, warmup slots, WETH balance — are all per-block-invariant, so applying them once at BlockSimHandle::build is semantically identical to applying them per-path.

Implementations

impl<'a> BlockSimHandle<'a>

pub fn build( provider: &AlloyProvider, base_fee_next: u128, current_block: u64, block_timestamp: u64, override_params: &SimulationOverrideParams, oracle: &'a dyn SimAnchorOracle, warm_cache: &Arc<RwLock<WarmCodeCacheInner>>, storage_memo: Option<&Arc<StorageMemo>>, verify_divergence: bool, ) -> Option<Self>

Build the per-block shared EVM: the layered DB (AlloyDB → WrapDatabaseAsync → BotStateDb → WarmCodeCache → CacheDB), the state overrides applied ONCE (every override is per-block-invariant), and the revm Context pinned to the block env. Returns None on a build failure (no ambient multi-threaded runtime for WrapDatabaseAsync, or an override-application error); the caller tallies rpc-failed for every candidate in that case.

The block-env primitives (provider, base_fee_next, current_block, block_timestamp) + the projected SimulationOverrideParams are handed in directly — the engine never names the strategy’s SimulateContext (ADR-019 D7, decision R — strategy/engine separation).

warm_cache is the cross-block persistent bytecode + account-existence layer (super::WarmCodeCache); it persists across blocks via the engine owner’s Arc<RwLock<WarmCodeCacheInner>> (cloned into the per-block WarmCodeCache wrapper value here — only the inner map survives across blocks). The per-block CacheDB layered above still drops at end of block (overrides + mutable storage are per-block).

WrapDatabaseAsync::new returns None if there is no runtime or the runtime is CurrentThread. The pump drives the dispatch through pyo3_async_runtimes (Builder::new_multi_thread()), so the None path is unreachable in production — None means the dispatch host lost its runtime.

pub fn evm_mut(&mut self) -> &mut BlockEvm<'a>

Borrow the shared per-block EVM mutably — the strategy’s simulate_path_on_evm drives this &mut evm per candidate path. The fan-out is serial, so the borrow is never aliased. Per-path isolation is revm’s finalize() (the strategy clears the journal between paths via the finalize() calls inside simulate_path_on_evm — execute()’s SSTOREs stay in the per-path State, never committed to the shared CacheDB).

pub fn scratch_evm(&mut self) -> Option<&mut ScratchEvm<ScratchDb<'a>>>

The frame-replay seam (super::frame_replay): a scratch engine over a FRESHLY STACKED instance of the layered DB (same layers, new instances — the shared EVM’s journal and per-block CacheDB are never aliased; the cross-block WarmCodeCacheInner owner arc IS shared, so warm bytecode/account caches carry over). State overrides are NOT applied — a foreign frame runs against chain state, not the strategy’s executor funding. Built lazily ONCE and kept for the handle’s life, so the scratch’s warmed read-caches serve every later frame; only the scratch’s per-frame DB layer is discarded. The cold path is counted (the soak-budget rpc_reads).

Returns None when no ambient multi-threaded runtime exists for the fresh WrapDatabaseAsync (same failure surface as Self::build).