Module cold_start 

Protocol-neutral cold-start sync for EvmCache.

Cold start declares rounds of authoritative slot work — verify, probe, probe_roots, accounts, discover — and drives a bounded multi-round loop via a pure ColdStartPlanner. Every verify and probe slot yields a per-slot SlotOutcome distinguishing a genuine on-chain zero (SlotFetch::Zero) from a fetch failure (SlotFetch::FetchFailed) — closing the “archive-miss” gap where a transient fetch failure was indistinguishable from absence.

The module is gated behind the reactive feature. The per-slot SlotOutcome / SlotFetch surface lives ungated in crate::freshness and is re-exported here for consumer ergonomics.

Design

• The driver performs every fetch and call; planners are pure and IO-free, handed only a StateView and a ColdStartResults.
• Verify-phase changes are injected via the dual-layer inject_storage_batch_fresh and are visible to the next on_results through the state view.
• A run can be pinned to a block hash via ColdStartPin::Hash; with require_canonical: true, a reorged hash makes the run fail fast. This is the cold-start reorg defense by design.

Runtime requirement

Like the rest of the crate’s RPC seams, cold-start fetching drives async work synchronously and must run on a multi-thread tokio runtime.

Example

A planner that authoritatively warms a fixed working set of slots in one round. (See examples/cold_start.rs for the runnable discover-then-verify version.)

use alloy_primitives::{Address, U256};
use evm_fork_cache::cache::EvmCache;
use evm_fork_cache::events::StateView;
use evm_fork_cache::{
    ColdStartConfig, ColdStartError, ColdStartPlan, ColdStartPlanner, ColdStartResults,
    ColdStartStep,
};

struct WarmSlots {
    slots: Vec<(Address, U256)>,
}

impl ColdStartPlanner for WarmSlots {
    fn initial_plan(&mut self, _state: &dyn StateView) -> ColdStartPlan {
        // Round 1: re-fetch these slots authoritatively and inject the fresh values.
        ColdStartPlan { verify: self.slots.clone(), ..Default::default() }
    }
    fn on_results(&mut self, _r: &ColdStartResults, _s: &dyn StateView) -> ColdStartStep {
        ColdStartStep::Done
    }
}

// `run_cold_start` needs a live cache on a multi-thread runtime; this helper
// shows the call shape (it is never invoked, so the doctest needs no runtime).
let mut planner = WarmSlots { slots };
let report = cache.run_cold_start(&mut planner, ColdStartConfig::default())?;
assert_eq!(report.rounds, 1);

Re-exports

pub use roots::RootBaseline;

pub use roots::RootBaselinePlanner;

pub use roots::RootProbeOutcome;

pub use crate::freshness::SlotFetch;

pub use crate::freshness::SlotOutcome;

Modules

roots

Cold-start root baseline (roots.bin): persist observed storage roots so a restarting process can cheaply detect which tracked accounts changed while it was down.

Structs

ColdStartCall

A read-only view-call whose touched storage and accounts are captured during the discover phase.

ColdStartCallResult

The result of one discover view-call: the raw EVM execution result and the storage/account access list it touched (filtered by restrict_to).

ColdStartConfig

Configuration for a cold-start run.

ColdStartPlan

A single round of cold-start work, declared by a ColdStartPlanner.

ColdStartResults

The outcome of executing one ColdStartPlan round.

ColdStartRoundSummary

Per-round breakdown recorded in ColdStartRunReport::per_round.

ColdStartRunReport

Summary of a completed cold-start run, returned by run_cold_start on success.

RoundOutcome

The outcome of a single cold-start round, always carrying the (possibly partial) ColdStartResults.

Enums

ColdStartError

A hard error that aborts a cold-start round or run.

ColdStartPin

How the driver pins the block for the run’s reads.

ColdStartStep

The planner’s decision after a round completes.

Traits

ColdStartPlanner

Drives a bounded multi-round cold start.