evm_fork_cache/cold_start/
plan.rs

1//! What a cold-start round declares it wants done.
2//!
3//! A [`ColdStartPlan`] is a pure, IO-free description handed to the driver. All
4//! four phases are optional and an empty plan is a valid no-op round.
5
6use alloy_primitives::{Address, Bytes, U256};
7
8/// A single round of cold-start work, declared by a
9/// [`ColdStartPlanner`](crate::cold_start::ColdStartPlanner).
10///
11/// All four phases are optional; an empty plan is a valid no-op round. The driver
12/// executes the phases in a fixed order: **accounts → verify → probe → discover**.
13///
14/// - `verify` slots are authoritatively re-fetched, classified, and (when changed)
15///   injected into the cache via the dual-layer
16///   [`inject_storage_batch_fresh`](crate::cache::EvmCache::inject_storage_batch_fresh).
17/// - `probe` slots are classified at the pinned block **without** injecting.
18/// - `accounts` are pre-seeded into the cache before discovery runs.
19/// - `discover` view-calls capture the `(address, slot)` pairs and accounts they
20///   touch.
21///
22/// ```
23/// use alloy_primitives::{Address, Bytes, U256};
24/// use evm_fork_cache::{ColdStartCall, ColdStartPlan};
25///
26/// // Verify one known slot and discover more via a read-only view-call.
27/// let plan = ColdStartPlan {
28///     verify: vec![(Address::repeat_byte(0x11), U256::from(0))],
29///     discover: vec![ColdStartCall {
30///         from: Address::ZERO,
31///         to: Address::repeat_byte(0x11),
32///         calldata: Bytes::new(),
33///         restrict_to: None,
34///     }],
35///     ..Default::default()
36/// };
37/// assert_eq!(plan.verify.len(), 1);
38/// assert_eq!(plan.discover.len(), 1);
39/// ```
40#[derive(Clone, Debug, Default)]
41pub struct ColdStartPlan {
42    /// Slots to authoritatively re-fetch, classify, and inject when changed.
43    pub verify: Vec<(Address, U256)>,
44    /// Slots to classify at the pinned block without injecting.
45    pub probe: Vec<(Address, U256)>,
46    /// Accounts to pre-seed into the cache before discovery.
47    pub accounts: Vec<Address>,
48    /// View-calls whose touched slots and accounts are captured.
49    pub discover: Vec<ColdStartCall>,
50}
51
52/// A read-only view-call whose touched storage and accounts are captured during
53/// the discover phase.
54///
55/// When `restrict_to` is `Some`, the captured `slots` and `accounts` are filtered
56/// to the named addresses; an empty restricted capture is observable as an empty
57/// access list (distinct from a non-empty discovery).
58#[derive(Clone, Debug)]
59pub struct ColdStartCall {
60    /// Transaction sender.
61    pub from: Address,
62    /// Call target.
63    pub to: Address,
64    /// Calldata.
65    pub calldata: Bytes,
66    /// When set, filters captured slots and accounts to these addresses.
67    pub restrict_to: Option<Vec<Address>>,
68}
evm_fork_cache/cold_start/plan.rs

evm_fork_cache/cold_start/
plan.rs
