Skip to main content

foundry_evm_core/fork/
prefetch.rs

1//! Prefetches a new fork block's remote cache from the keys of an older cached block.
2//!
3//! A fork of `latest` gets an empty cache on each new head, and every cold account or storage read
4//! then blocks the EVM for one RPC round trip. Earlier runs on the same chain read mostly the same
5//! accounts and slots, so the keys of the newest older cache file predict the reads. The keys are
6//! read again at the new block through the fork backend, so the cache stays exact for that block.
7//! The cache file keeps only the keys the EVM then reads, so a wrong prediction only costs an RPC
8//! request and does not carry over to the next block.
9//!
10//! A call is predicted more precisely by simulating it on the endpoint, see [`prefetch_call`].
11
12use super::Fork;
13use crate::{
14    constants::{CHEATCODE_ADDRESS, HARDHAT_CONSOLE_ADDRESS},
15    precompiles::P256_VERIFY,
16};
17use alloy_network::Network;
18use alloy_primitives::{Address, B256, Bytes, KECCAK256_EMPTY, U256, map::B256HashMap};
19use alloy_rpc_types::{TransactionRequest, state::StateOverride};
20use evm2::{bytecode::Bytecode, evm::Cache};
21use foundry_config::Config;
22use foundry_fork_db::{
23    ForkBlockEnv, SharedBackend,
24    backend::BlockingMode,
25    cache::{JsonBlockCacheDB, MemDb},
26};
27use parking_lot::Mutex;
28use std::{
29    path::{Path, PathBuf},
30    sync::{
31        Arc,
32        atomic::{AtomicBool, Ordering},
33        mpsc,
34    },
35};
36
37/// Prefetch requests in flight at once. The fork backend sends its own cold reads without a limit;
38/// this bound keeps a large key set from flooding a public endpoint.
39const MAX_CONCURRENT_REQUESTS: usize = 32;
40
41/// Largest number of accounts and slots to prefetch. Older cache files can hold the union of many
42/// runs; past this size, a prefetch can cost more requests than it saves.
43const MAX_KEYS: usize = 4096;
44
45/// Runtime code that returns one zero word, standing in for the cheatcode contract in a
46/// simulation on the fork's endpoint: `PUSH1 0x20 PUSH1 0x00 RETURN`.
47const CHEATCODE_STUB: Bytes = Bytes::from_static(&[0x60, 0x20, 0x60, 0x00, 0xf3]);
48
49/// Largest local state, in bytes of code and storage, sent as overrides with a simulated call.
50const MAX_OVERRIDE_BYTES: usize = 512 * 1024;
51
52enum Key {
53    Account(Address),
54    Slot(Address, U256),
55}
56
57/// Starts a background prefetch through `backend` if its cache is empty.
58///
59/// Each key is read through the backend like an EVM read, so the backend fetches and caches it with
60/// its own request path, and a key it already has costs no request. Loading the previous cache file
61/// runs in the background too, so it does not block the fork handler.
62pub(crate) fn spawn<N: Network, B: ForkBlockEnv>(
63    fork: &Fork,
64    backend: &SharedBackend<N, B>,
65) -> Option<Prefetch> {
66    if !backend.data().accounts.read().is_empty() {
67        return None;
68    }
69    let runtime = tokio::runtime::Handle::try_current().ok()?;
70    let (chain, number) = (fork.context().source_chain_id, fork.number());
71    let stop = Arc::new(AtomicBool::new(false));
72    let (done_tx, done) = mpsc::channel::<()>();
73    let backend = backend.with_blocking_mode(BlockingMode::Block);
74    let coordinator_stop = Arc::clone(&stop);
75    runtime.clone().spawn_blocking(move || {
76        let stop = coordinator_stop;
77        if let Some(path) =
78            Config::foundry_chain_cache_dir(chain).and_then(|dir| previous_cache_file(&dir, number))
79            && let Ok(previous) = JsonBlockCacheDB::<B>::load(&path)
80            && !stop.load(Ordering::Relaxed)
81        {
82            let keys = keys(previous.db());
83            debug!(target: "fork::prefetch", ?path, keys = keys.len(), "prefetching fork cache");
84            // Workers take the next key without a lock held during a read.
85            let keys = Arc::new(Mutex::new(keys.into_iter()));
86            for _ in 0..MAX_CONCURRENT_REQUESTS {
87                let (keys, stop, done_tx) = (Arc::clone(&keys), Arc::clone(&stop), done_tx.clone());
88                let backend = backend.clone();
89                runtime.spawn_blocking(move || {
90                    while !stop.load(Ordering::Relaxed) {
91                        let Some(key) = keys.lock().next() else { break };
92                        // A prefetched key stays out of the cache file until the EVM reads it.
93                        let read = match key {
94                            Key::Account(address) => backend.prefetch_basic(address),
95                            Key::Slot(address, slot) => backend.prefetch_storage(address, slot),
96                        };
97                        // The EVM fetches any key it still needs, so stop at the first failure.
98                        if read.is_err() {
99                            break;
100                        }
101                    }
102                    // Drop the backend clone before reporting done, as below.
103                    drop(backend);
104                    drop(done_tx);
105                });
106            }
107        }
108        // The last backend clone flushes the disk cache, so drop it before reporting done.
109        drop(backend);
110        drop(done_tx);
111    });
112    Some(Prefetch { stop, done })
113}
114
115/// Background prefetch workers of one fork backend.
116pub(crate) struct Prefetch {
117    stop: Arc<AtomicBool>,
118    done: mpsc::Receiver<()>,
119}
120
121impl Prefetch {
122    /// Stops the workers and waits until they and their coordinator exit, so whichever holds the
123    /// last backend clone flushes the disk cache before shutdown completes.
124    pub(crate) fn stop(self) {
125        self.stop.store(true, Ordering::Relaxed);
126        // Returns once every worker has dropped its sender.
127        let _ = self.done.recv();
128    }
129}
130
131/// Returns the cache file of the newest block below `number` in a chain cache directory.
132fn previous_cache_file(dir: &Path, number: u64) -> Option<PathBuf> {
133    std::fs::read_dir(dir)
134        .ok()?
135        .filter_map(|entry| {
136            let entry = entry.ok()?;
137            let block = entry.file_name().to_str()?.parse::<u64>().ok()?;
138            (block < number && entry.file_type().ok()?.is_file()).then_some((block, entry.path()))
139        })
140        .max_by_key(|(block, _)| *block)
141        .map(|(_, path)| path)
142}
143
144/// Returns the accounts first, then the slots, up to [`MAX_KEYS`].
145fn keys(db: &MemDb) -> Vec<Key> {
146    let accounts = db.accounts.read();
147    let storage = db.storage.read();
148    accounts
149        .keys()
150        .map(|&address| Key::Account(address))
151        .chain(
152            storage.iter().flat_map(|(&address, slots)| {
153                slots.keys().map(move |&slot| Key::Slot(address, slot))
154            }),
155        )
156        .take(MAX_KEYS)
157        .collect()
158}
159
160/// Returns the local state of a fork context that differs from `remote`, the state the fork loaded
161/// from its endpoint, as overrides for a simulation there, with a stub for the cheatcode contract.
162/// Such state is the test contract and balances set with cheatcodes.
163///
164/// Returns `None` when nothing differs, so endpoints without override support still simulate, or
165/// when the state is larger than [`MAX_OVERRIDE_BYTES`].
166pub(crate) fn state_override(remote: &MemDb, local: &Cache) -> Option<StateOverride> {
167    let remote_accounts = remote.accounts.read();
168    let remote_storage = remote.storage.read();
169    let mut overrides = StateOverride::default();
170    let mut bytes = 0;
171    for (address, info) in &local.accounts {
172        // An absent account keeps its remote state; the simulation only predicts reads.
173        let Some(info) = info else { continue };
174        let remote = remote_accounts.get(address);
175        // Code that is neither inline nor in the contracts is unknown and not overridden, unless
176        // its hash is the empty code hash.
177        let code = remote
178            .is_none_or(|remote| remote.code_hash != info.code_hash)
179            .then(|| {
180                let code = info.code.as_ref().or_else(|| local.contracts.get(&info.code_hash));
181                code.map(Bytecode::original_bytes)
182                    .or_else(|| info.is_empty_code_hash().then(Bytes::new))
183            })
184            .flatten();
185        let balance = remote.is_none_or(|remote| remote.balance != info.balance);
186        let nonce = remote.is_none_or(|remote| remote.nonce != info.nonce);
187        if code.is_some() || balance || nonce {
188            bytes += code.as_ref().map_or(0, |code| code.len());
189            let account = overrides.entry(*address).or_default();
190            account.code = code;
191            account.balance = balance.then_some(info.balance);
192            account.nonce = nonce.then_some(info.nonce);
193        }
194    }
195    for (address, storage) in &local.storage {
196        // Wiped storage replaces the whole remote storage.
197        let remote = remote_storage.get(address).filter(|_| !storage.wiped);
198        let slots = storage
199            .slots
200            .iter()
201            .filter(|&(slot, value)| remote.and_then(|remote| remote.get(slot)) != Some(value))
202            .map(|(slot, value)| (B256::from(*slot), B256::from(*value)))
203            .collect::<B256HashMap<_>>();
204        bytes += slots.len() * 64;
205        if bytes > MAX_OVERRIDE_BYTES {
206            return None;
207        }
208        if storage.wiped {
209            overrides.entry(*address).or_default().state = Some(slots);
210        } else if !slots.is_empty() {
211            overrides.entry(*address).or_default().state_diff = Some(slots);
212        }
213    }
214    if overrides.is_empty() || bytes > MAX_OVERRIDE_BYTES {
215        return None;
216    }
217    overrides.entry(CHEATCODE_ADDRESS).or_default().code = Some(CHEATCODE_STUB);
218    Some(overrides)
219}
220
221/// Simulates a call on the fork's endpoint and prefetches the state it touches, see
222/// [`SharedBackend::prefetch_access_list`]. With `overrides`, the `local` state over the fork goes
223/// along as overrides.
224///
225/// Calls to precompiles up to `P256VERIFY` at `0x100`, to the cheatcode contract and to the console
226/// are skipped. A call sent without overrides is skipped when the fork loaded its target without
227/// code. It is also skipped when `local` holds its target but the fork never loaded it.
228pub(crate) fn prefetch_call<N: Network, B: ForkBlockEnv>(
229    backend: &SharedBackend<N, B>,
230    caller: Address,
231    target: Address,
232    value: U256,
233    input: Bytes,
234    local: Option<&Cache>,
235    overrides: bool,
236) {
237    if target <= P256_VERIFY || target == CHEATCODE_ADDRESS || target == HARDHAT_CONSOLE_ADDRESS {
238        return;
239    }
240    let remote = backend.data();
241    let remote_code = remote.accounts.read().get(&target).map(|account| account.code_hash);
242    let local_account = local.and_then(|local| local.accounts.get(&target)?.as_ref());
243    // Local code tells apart contracts at one address, such as the test contracts of two suites.
244    let code_hash = local_account
245        .map(|account| account.code_hash)
246        .filter(|&code_hash| remote_code != Some(code_hash))
247        .unwrap_or_default();
248    let tx = TransactionRequest::default().from(caller).to(target).value(value).input(input.into());
249    // Checked first, so a call that is not simulated does not build its overrides.
250    if !backend.wants_access_list(&tx, code_hash, overrides) {
251        return;
252    }
253    let overrides = local.filter(|_| overrides).and_then(|local| state_override(&remote, local));
254    // Without overrides, the endpoint runs its own code at the target. A target the fork loaded
255    // without code, such as a contract created on the fork, runs no code there. A native
256    // precompile without code runs no opcodes, so the endpoint lists none of its reads either. A
257    // target the context holds but the fork never loaded, such as a contract created before the
258    // fork was selected, is unknown there.
259    if overrides.is_none()
260        && remote_code.map_or(local_account.is_some(), |remote| remote == KECCAK256_EMPTY)
261    {
262        return;
263    }
264    backend.prefetch_access_list(tx, overrides, code_hash);
265}
266
267#[cfg(test)]
268mod tests {
269    use super::*;
270
271    #[test]
272    fn picks_newest_cache_file_below_block() {
273        let dir = std::env::temp_dir().join(format!("foundry-prefetch-{}", std::process::id()));
274        std::fs::create_dir_all(dir.join("120")).unwrap();
275        for block in ["90", "100", "110", "130", "notes"] {
276            std::fs::write(dir.join(block), b"{}").unwrap();
277        }
278
279        // `120` is a directory, as anvil writes it, and `130` is not below the block.
280        assert_eq!(previous_cache_file(&dir, 125), Some(dir.join("110")));
281        assert_eq!(previous_cache_file(&dir, 90), None);
282        std::fs::remove_dir_all(&dir).unwrap();
283    }
284}