Skip to main content

foundry_evm_core/fork/
multi.rs

1//! Support for running multiple fork backends.
2//!
3//! The design is similar to the single `SharedBackend`, `BackendHandler` but supports multiple
4//! concurrently active pairs at once.
5
6use super::{BlobExcessGasAndPrice, BlockEnv, CreateFork, Fork, bal};
7use crate::{evm::EthEvmNetwork, opts::ForkContext};
8use alloy_eips::{BlockNumHash, eip7928::BlockAccessList};
9use alloy_network::AnyNetwork;
10use alloy_primitives::map::HashMap;
11use foundry_common::sh_warn;
12use foundry_config::Config;
13use foundry_evm_networks::{NetworkConfigs, NetworkVariant};
14use foundry_fork_db::{
15    BackendHandler, BlockchainDb, ForkBlock, SharedBackend, cache::BlockchainDbMeta,
16};
17use futures::{
18    FutureExt, StreamExt,
19    channel::mpsc::{Receiver, Sender, channel},
20    stream::Fuse,
21    task::{Context, Poll},
22};
23use std::{
24    collections::BTreeSet,
25    fmt::{self, Write},
26    pin::Pin,
27    sync::{
28        Arc, Mutex,
29        atomic::{AtomicBool, AtomicUsize, Ordering},
30        mpsc::{Sender as OneshotSender, channel as oneshot_channel},
31    },
32    time::Duration,
33};
34
35/// The _unique_ identifier for a specific fork, this could be the name of the network a custom
36/// descriptive name.
37#[derive(Clone, Debug, PartialEq, Eq, Hash)]
38pub struct ForkId(pub String);
39
40impl ForkId {
41    /// Returns the identifier for a Fork from a URL and block number.
42    pub fn new(url: &str, num: Option<u64>) -> Self {
43        Self::new_with_context(url, num, None)
44    }
45
46    fn new_with_context(
47        url: &str,
48        num: Option<u64>,
49        context: Option<&crate::opts::ForkContext>,
50    ) -> Self {
51        let mut id = url.to_string();
52        if let Some(context) = context {
53            write!(
54                id,
55                "#{}:{}:{}:{}:{:?}:{:?}:{:?}:{:?}",
56                context.execution_chain_id,
57                context.source_chain_id,
58                context.network,
59                context.network_profile.execution_profile_name(),
60                context.hardfork,
61                context.instance_id,
62                context.source_fork_block_number,
63                context.source_fork_block_hash
64            )
65            .unwrap();
66        }
67        id.push('@');
68        match num {
69            Some(n) => write!(id, "{n:#x}").unwrap(),
70            None => id.push_str("latest"),
71        }
72        Self(id)
73    }
74
75    /// Returns the identifier for an exactly resolved fork.
76    fn resolved(url: &str, fork: &Fork) -> Self {
77        let mut id = Self::exact(url, fork, fork.block());
78        if fork.state_by_number {
79            id.0.push_str("#state-by-number");
80        }
81        id
82    }
83
84    /// Exact rolls always read state by hash, regardless of the parent fork's state mode.
85    fn exact(url: &str, fork: &Fork, block: BlockNumHash) -> Self {
86        let mut id = Self::new_with_context(url, Some(block.number), Some(&fork.context())).0;
87        write!(id, "#{}:{}", block.hash, fork.source_id()).unwrap();
88        Self(id)
89    }
90
91    /// Returns the identifier of the fork.
92    pub fn as_str(&self) -> &str {
93        &self.0
94    }
95}
96
97impl fmt::Display for ForkId {
98    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
99        self.0.fmt(f)
100    }
101}
102
103impl<T: Into<String>> From<T> for ForkId {
104    fn from(id: T) -> Self {
105        Self(id.into())
106    }
107}
108
109/// Backend and identity returned after creating or rolling a fork.
110pub struct ForkResult {
111    /// Identifier assigned to the fork.
112    pub id: ForkId,
113    /// Backend pinned to the resolved fork block.
114    pub backend: SharedBackend<AnyNetwork, BlockEnv>,
115    /// Exact source and block identity used to construct the backend.
116    pub fork: Fork,
117}
118
119/// The Sender half of multi fork pair.
120/// Can send requests to the `MultiForkHandler` to create forks.
121#[derive(Clone, Debug)]
122#[must_use]
123pub struct MultiFork {
124    /// Channel to send `Request`s to the handler.
125    handler: Sender<Request>,
126    /// Ensures that all rpc resources get flushed properly.
127    _shutdown: Arc<ShutDownMultiFork>,
128}
129
130impl MultiFork {
131    /// Creates a new pair and spawns the `MultiForkHandler` on a background thread.
132    pub fn spawn() -> Self {
133        Self::spawn_with_forks(HashMap::default(), None)
134    }
135
136    /// Starts an independent registry sharing the existing remote caches.
137    pub(crate) fn scoped(&self) -> eyre::Result<Self> {
138        let (sender, rx) = oneshot_channel();
139        self.handler
140            .clone()
141            .try_send(Request::CloneForks(sender))
142            .map_err(|e| eyre::eyre!("{e:?}"))?;
143        Ok(Self::spawn_with_forks(rx.recv()?, Some(self._shutdown.clone())))
144    }
145
146    fn spawn_with_forks(
147        forks: HashMap<ForkId, CreatedFork>,
148        parent: Option<Arc<ShutDownMultiFork>>,
149    ) -> Self {
150        trace!(target: "fork::multi", "spawning multifork");
151        let (mut fork, mut handler) = Self::new();
152        handler.forks = forks;
153        Arc::get_mut(&mut fork._shutdown).unwrap()._parent = parent;
154
155        // Spawn a light-weight thread just for sending and receiving data from the remote
156        // client(s).
157        let fut = async move {
158            // Flush cache every 60s, this ensures that long-running fork tests get their
159            // cache flushed from time to time.
160            // NOTE: we install the interval here because the `tokio::timer::Interval`
161            // requires a rt.
162            handler.set_flush_cache_interval(Duration::from_secs(60));
163            handler.await
164        };
165        match tokio::runtime::Handle::try_current() {
166            Ok(rt) => _ = rt.spawn(fut),
167            Err(_) => {
168                trace!(target: "fork::multi", "spawning multifork backend thread");
169                _ = std::thread::Builder::new()
170                    .name("multi-fork-backend".into())
171                    .spawn(move || {
172                        tokio::runtime::Builder::new_current_thread()
173                            .enable_all()
174                            .build()
175                            .expect("failed to build tokio runtime")
176                            .block_on(fut)
177                    })
178                    .expect("failed to spawn thread")
179            }
180        }
181
182        trace!(target: "fork::multi", "spawned MultiForkHandler thread");
183        fork
184    }
185
186    /// Creates a new pair multi fork pair.
187    ///
188    /// Use [`spawn`](Self::spawn) instead.
189    #[doc(hidden)]
190    pub fn new() -> (Self, MultiForkHandler) {
191        let (handler, handler_rx) = channel(1);
192        let _shutdown =
193            Arc::new(ShutDownMultiFork { handler: Some(handler.clone()), _parent: None });
194        (Self { handler, _shutdown }, MultiForkHandler::new(handler_rx))
195    }
196
197    /// Returns a fork backend.
198    ///
199    /// If no matching fork backend exists it will be created.
200    pub fn create_fork(&self, fork: CreateFork) -> eyre::Result<ForkResult> {
201        trace!("Creating new fork, url={}, block={:?}", fork.url, fork.evm_opts.fork_block_number);
202        let (sender, rx) = oneshot_channel();
203        let req = Request::CreateFork(Box::new(fork), sender);
204        self.handler.clone().try_send(req).map_err(|e| eyre::eyre!("{:?}", e))?;
205        rx.recv()?
206    }
207
208    /// Rolls the block of the fork.
209    ///
210    /// If no matching fork backend exists it will be created.
211    pub fn roll_fork(&self, fork: ForkId, block: u64) -> eyre::Result<ForkResult> {
212        trace!(?fork, ?block, "rolling fork");
213        let (sender, rx) = oneshot_channel();
214        let req = Request::RollFork(fork, block, sender);
215        self.handler.clone().try_send(req).map_err(|e| eyre::eyre!("{:?}", e))?;
216        rx.recv()?
217    }
218
219    /// Rolls to an exact parent block, optionally warming its cache before transaction replay.
220    pub(crate) fn roll_fork_exact_with_bal(
221        &self,
222        fork: ForkId,
223        block: BlockNumHash,
224        prewarm_bal: bool,
225    ) -> eyre::Result<ForkResult> {
226        trace!(?fork, ?block, "rolling fork to exact block");
227        let (sender, rx) = oneshot_channel();
228        let req = Request::RollForkExact(fork, block, prewarm_bal, sender);
229        self.handler.clone().try_send(req).map_err(|e| eyre::eyre!("{:?}", e))?;
230        rx.recv()?
231    }
232
233    /// Returns the corresponding fork if it exists.
234    ///
235    /// Returns `None` if no matching fork backend is available.
236    pub fn get_fork(
237        &self,
238        id: impl Into<ForkId>,
239    ) -> eyre::Result<Option<SharedBackend<AnyNetwork, BlockEnv>>> {
240        let id = id.into();
241        trace!(?id, "get fork backend");
242        let (sender, rx) = oneshot_channel();
243        let req = Request::GetFork(id, sender);
244        self.handler.clone().try_send(req).map_err(|e| eyre::eyre!("{:?}", e))?;
245        Ok(rx.recv()?)
246    }
247
248    /// Returns the options used to create the corresponding fork if it exists.
249    ///
250    /// Returns `None` if no matching fork is available.
251    pub fn get_fork_options(&self, id: impl Into<ForkId>) -> eyre::Result<Option<CreateFork>> {
252        let (sender, rx) = oneshot_channel();
253        let req = Request::GetForkOptions(id.into(), sender);
254        self.handler.clone().try_send(req).map_err(|e| eyre::eyre!("{:?}", e))?;
255        Ok(rx.recv()?)
256    }
257}
258
259type CreateFuture = Pin<
260    Box<
261        dyn Future<
262                Output = eyre::Result<(
263                    ForkId,
264                    CreateFork,
265                    Fork,
266                    BlockEnv,
267                    Option<BlockAccessList>,
268                )>,
269            > + Send,
270    >,
271>;
272type CreateSender = OneshotSender<eyre::Result<ForkResult>>;
273
274/// Request that's send to the handler.
275#[derive(Debug)]
276enum Request {
277    CloneForks(OneshotSender<HashMap<ForkId, CreatedFork>>),
278    /// Creates a new ForkBackend.
279    CreateFork(Box<CreateFork>, CreateSender),
280    /// Returns the Fork backend for the `ForkId` if it exists.
281    GetFork(ForkId, OneshotSender<Option<SharedBackend<AnyNetwork, BlockEnv>>>),
282    /// Adjusts the block that's being forked, by creating a new fork at the new block.
283    RollFork(ForkId, u64, CreateSender),
284    /// Adjusts the fork to an already resolved exact block.
285    RollForkExact(ForkId, BlockNumHash, bool, CreateSender),
286    /// Shutdowns the entire `MultiForkHandler`, see `ShutDownMultiFork`
287    ShutDown(OneshotSender<()>),
288    /// Returns the options used to create the `ForkId` if it exists.
289    GetForkOptions(ForkId, OneshotSender<Option<CreateFork>>),
290}
291
292enum ForkTask {
293    /// Contains the future that will establish a new fork.
294    Create {
295        future: CreateFuture,
296        id: ForkId,
297        prewarm_bal: bool,
298        no_fork_bal: bool,
299        sender: CreateSender,
300        additional_senders: Vec<CreateSender>,
301    },
302}
303
304/// The type that manages connections in the background.
305#[must_use = "futures do nothing unless polled"]
306pub struct MultiForkHandler {
307    /// Incoming requests from the `MultiFork`.
308    incoming: Fuse<Receiver<Request>>,
309
310    /// All active handlers.
311    ///
312    /// It's expected that this list will be rather small (<10).
313    handlers: Vec<(ForkId, BackendHandler<AnyNetwork, BlockEnv>)>,
314
315    // tasks currently in progress
316    pending_tasks: Vec<ForkTask>,
317
318    /// All _unique_ forkids mapped to their corresponding backend.
319    ///
320    /// Note: The backend can be shared by multiple ForkIds if the target the same provider and
321    /// block number.
322    forks: HashMap<ForkId, CreatedFork>,
323
324    /// Optional periodic interval to flush rpc cache.
325    flush_cache_interval: Option<tokio::time::Interval>,
326
327    /// Prefetch workers of the backends created by this handler.
328    prefetches: Vec<super::prefetch::Prefetch>,
329}
330
331impl MultiForkHandler {
332    fn new(incoming: Receiver<Request>) -> Self {
333        Self {
334            incoming: incoming.fuse(),
335            handlers: Default::default(),
336            pending_tasks: Default::default(),
337            forks: Default::default(),
338            flush_cache_interval: None,
339            prefetches: Default::default(),
340        }
341    }
342
343    /// Sets the interval after which all rpc caches should be flushed periodically.
344    pub fn set_flush_cache_interval(&mut self, period: Duration) -> &mut Self {
345        self.flush_cache_interval =
346            Some(tokio::time::interval_at(tokio::time::Instant::now() + period, period));
347        self
348    }
349
350    /// Returns the list of additional senders of a matching task for the given id, if any.
351    fn find_in_progress_task(
352        &mut self,
353        id: &ForkId,
354        prewarm_bal: bool,
355        no_fork_bal: bool,
356    ) -> Option<&mut Vec<CreateSender>> {
357        for ForkTask::Create {
358            id: in_progress,
359            prewarm_bal: pending_prewarm,
360            no_fork_bal: pending_opt_out,
361            additional_senders,
362            ..
363        } in &mut self.pending_tasks
364        {
365            if in_progress == id
366                && *pending_prewarm == prewarm_bal
367                && *pending_opt_out == no_fork_bal
368            {
369                return Some(additional_senders);
370            }
371        }
372        None
373    }
374
375    fn create_fork(&mut self, fork: CreateFork, sender: CreateSender) {
376        self.create_fork_with_identity(fork, None, false, None, sender);
377    }
378
379    fn create_fork_with_identity(
380        &mut self,
381        fork: CreateFork,
382        expected_identity: Option<ForkContext>,
383        prewarm_bal: bool,
384        exact_block: Option<(Fork, BlockNumHash)>,
385        sender: CreateSender,
386    ) {
387        let no_fork_bal = fork.evm_opts.no_fork_bal;
388        let prewarm_bal = prewarm_bal && !no_fork_bal;
389        let resolved_id =
390            exact_block.as_ref().map(|(parent, block)| ForkId::exact(&fork.url, parent, *block));
391        trace!(?resolved_id, "creating fork");
392
393        // Only deduplicate requests that already carry an exact identity. Unresolved requests at
394        // the same URL and height can resolve to different blocks across a reorganization.
395        if let Some(fork_id) = &resolved_id
396            && let Some(in_progress) = self.find_in_progress_task(fork_id, prewarm_bal, no_fork_bal)
397        {
398            in_progress.push(sender);
399            return;
400        }
401
402        let already_prewarmed = resolved_id
403            .as_ref()
404            .and_then(|id| self.forks.get(id))
405            .is_some_and(|fork| fork.bal_prewarmed.load(Ordering::Relaxed));
406
407        // Need to create a new fork.
408        let task_id =
409            resolved_id.unwrap_or_else(|| ForkId::new(&fork.url, fork.evm_opts.fork_block_number));
410        let needs_bal = prewarm_bal && !already_prewarmed;
411        let future = Box::pin(create_fork(fork, expected_identity, needs_bal, exact_block));
412        self.pending_tasks.push(ForkTask::Create {
413            future,
414            id: task_id,
415            prewarm_bal,
416            no_fork_bal,
417            sender,
418            additional_senders: Vec::new(),
419        });
420    }
421
422    fn insert_new_fork(
423        &mut self,
424        fork_id: ForkId,
425        fork: CreatedFork,
426        sender: CreateSender,
427        additional_senders: Vec<CreateSender>,
428    ) {
429        self.forks.insert(fork_id.clone(), fork.clone());
430        let resolved = fork.fork.clone();
431        let _ = sender.send(Ok(ForkResult {
432            id: fork_id.clone(),
433            backend: fork.backend.clone(),
434            fork: resolved.clone(),
435        }));
436
437        // Notify all additional senders and track unique forkIds.
438        for sender in additional_senders {
439            let next_fork_id = fork.inc_senders(fork_id.clone());
440            self.forks.insert(next_fork_id.clone(), fork.clone());
441            let _ = sender.send(Ok(ForkResult {
442                id: next_fork_id,
443                backend: fork.backend.clone(),
444                fork: resolved.clone(),
445            }));
446        }
447    }
448
449    fn on_request(&mut self, req: Request) {
450        match req {
451            Request::CloneForks(sender) => {
452                let _ = sender.send(self.forks.clone());
453            }
454            Request::CreateFork(fork, sender) => self.create_fork(*fork, sender),
455            Request::GetFork(fork_id, sender) => {
456                let fork = self.forks.get(&fork_id).map(|f| f.backend.clone());
457                let _ = sender.send(fork);
458            }
459            Request::RollFork(fork_id, block, sender) => {
460                if let Some(fork) = self.forks.get(&fork_id) {
461                    trace!(target: "fork::multi", "rolling {} to {}", fork_id, block);
462                    let expected_identity = Some(fork.fork.context());
463                    let mut opts = fork.opts.clone();
464                    opts.evm_opts.fork_block_number = Some(block);
465                    opts.evm_opts.fork_block_number_is_inferred = false;
466                    self.create_fork_with_identity(opts, expected_identity, false, None, sender)
467                } else {
468                    let _ =
469                        sender.send(Err(eyre::eyre!("No matching fork exists for {}", fork_id)));
470                }
471            }
472            Request::RollForkExact(fork_id, block, prewarm_bal, sender) => {
473                if let Some(fork) = self.forks.get(&fork_id) {
474                    trace!(target: "fork::multi", "rolling {} to exact block {:?}", fork_id, block);
475                    let mut opts = fork.opts.clone();
476                    opts.evm_opts.fork_block_number = Some(block.number);
477                    opts.evm_opts.fork_state_by_number = false;
478                    opts.evm_opts.fork_block_number_is_inferred = false;
479                    self.create_fork_with_identity(
480                        opts,
481                        None,
482                        prewarm_bal,
483                        Some((fork.fork.clone(), block)),
484                        sender,
485                    )
486                } else {
487                    let _ =
488                        sender.send(Err(eyre::eyre!("No matching fork exists for {}", fork_id)));
489                }
490            }
491            Request::ShutDown(sender) => {
492                trace!(target: "fork::multi", "received shutdown signal");
493                // We're emptying all fork backends, this way we ensure all caches get flushed.
494                self.forks.clear();
495                self.handlers.clear();
496                // Reads fail once the handlers are gone, so the workers exit promptly, and the
497                // last of them flushes the cache before the shutdown completes.
498                for prefetch in self.prefetches.drain(..) {
499                    prefetch.stop();
500                }
501                let _ = sender.send(());
502            }
503            Request::GetForkOptions(fork_id, sender) => {
504                let fork = self.forks.get(&fork_id).map(|f| f.opts.clone());
505                let _ = sender.send(fork);
506            }
507        }
508    }
509}
510
511// Drives all handler to completion.
512// This future will finish once all underlying BackendHandler are completed.
513impl Future for MultiForkHandler {
514    type Output = ();
515
516    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
517        let this = self.get_mut();
518
519        // Receive new requests.
520        loop {
521            match this.incoming.poll_next_unpin(cx) {
522                Poll::Ready(Some(req)) => this.on_request(req),
523                Poll::Ready(None) => {
524                    // Channel closed, but we still need to drive the fork handlers to completion.
525                    trace!(target: "fork::multi", "request channel closed");
526                    break;
527                }
528                Poll::Pending => break,
529            }
530        }
531
532        // Advance all tasks.
533        for n in (0..this.pending_tasks.len()).rev() {
534            let task = this.pending_tasks.swap_remove(n);
535            match task {
536                ForkTask::Create {
537                    mut future,
538                    id,
539                    prewarm_bal,
540                    no_fork_bal,
541                    sender,
542                    additional_senders,
543                } => {
544                    if let Poll::Ready(resp) = future.poll_unpin(cx) {
545                        let resp = resp.and_then(|(fork_id, opts, resolved, block_env, mut bal)| {
546                            let (fork_id, fork) = if let Some(mut cached) =
547                                this.forks.get(&fork_id).cloned()
548                            {
549                                if bal.is_some()
550                                    && resolved.fingerprint() != cached.fork.fingerprint()
551                                {
552                                    debug!(target: "backend::fork", "ignoring fork BAL for a different cache identity");
553                                    bal = None;
554                                }
555                                // Share the remote cache, RPC client, and block while retaining
556                                // this consumer's selector, execution environment, and BAL
557                                // policy. The fork ID includes the block hash, so the cached
558                                // block is the same block.
559                                cached.opts = opts;
560                                cached.fork = Fork {
561                                    client: cached.fork.client,
562                                    block: cached.fork.block,
563                                    ..resolved
564                                };
565                                (cached.inc_senders(fork_id), cached)
566                            } else {
567                                // Only a new backend loads the disk cache.
568                                let (backend, handler) =
569                                    create_backend(&opts, &resolved, &block_env)?;
570                                // Only a fork of `latest` starts cold on each new head; rolls and
571                                // pinned blocks do not prefetch. Prefetching reads older cache
572                                // files, so it follows the disk caching settings.
573                                let evm_opts = &opts.evm_opts;
574                                if evm_opts.fork_prefetch
575                                    && opts.enable_caching
576                                    && !resolved.state_by_number
577                                    && (evm_opts.fork_block_number.is_none()
578                                        || evm_opts.fork_block_number_is_inferred)
579                                {
580                                    this.prefetches
581                                        .extend(super::prefetch::spawn(&resolved, &backend));
582                                }
583                                this.handlers.push((fork_id.clone(), handler));
584                                (fork_id, CreatedFork::new(opts, resolved, backend))
585                            };
586                            Ok((fork_id, fork, bal))
587                        });
588                        match resp {
589                            Ok((fork_id, fork, bal)) => {
590                                // Apply only after choosing the backend, including an existing
591                                // cache.
592                                if let Some(bal) = bal {
593                                    bal::cache_bal(&fork.backend.data(), bal);
594                                    fork.bal_prewarmed.store(true, Ordering::Relaxed);
595                                }
596                                this.insert_new_fork(fork_id, fork, sender, additional_senders);
597                            }
598                            Err(err) => {
599                                let _ = sender.send(Err(eyre::eyre!("{err}")));
600                                for sender in additional_senders {
601                                    let _ = sender.send(Err(eyre::eyre!("{err}")));
602                                }
603                            }
604                        }
605                    } else {
606                        this.pending_tasks.push(ForkTask::Create {
607                            future,
608                            id,
609                            prewarm_bal,
610                            no_fork_bal,
611                            sender,
612                            additional_senders,
613                        });
614                    }
615                }
616            }
617        }
618
619        // Advance all handlers.
620        for n in (0..this.handlers.len()).rev() {
621            let (id, mut handler) = this.handlers.swap_remove(n);
622            match handler.poll_unpin(cx) {
623                Poll::Ready(_) => {
624                    trace!(target: "fork::multi", "fork {:?} completed", id);
625                }
626                Poll::Pending => {
627                    this.handlers.push((id, handler));
628                }
629            }
630        }
631
632        if this.handlers.is_empty() && this.incoming.is_done() {
633            trace!(target: "fork::multi", "completed");
634            return Poll::Ready(());
635        }
636
637        // Periodically flush cached RPC state.
638        if this
639            .flush_cache_interval
640            .as_mut()
641            .map(|interval| interval.poll_tick(cx).is_ready())
642            .unwrap_or_default()
643            && !this.forks.is_empty()
644        {
645            trace!(target: "fork::multi", "tick flushing caches");
646            // Only the registry owning a handler flushes its cache, once per backend.
647            let forks = this
648                .handlers
649                .iter()
650                .filter_map(|(id, _)| this.forks.get(id))
651                .map(|fork| fork.backend.clone())
652                .collect::<Vec<_>>();
653            // Flush this on new thread to not block here.
654            std::thread::Builder::new()
655                .name("flusher".into())
656                .spawn(move || {
657                    for fork in forks {
658                        fork.flush_cache();
659                    }
660                })
661                .expect("failed to spawn thread");
662        }
663
664        Poll::Pending
665    }
666}
667
668/// Tracks the created Fork
669#[derive(Debug, Clone)]
670struct CreatedFork {
671    /// How the fork was initially created.
672    opts: CreateFork,
673    /// The immutable remote fork owned by this backend.
674    fork: Fork,
675    /// Copy of the sender.
676    backend: SharedBackend<AnyNetwork, BlockEnv>,
677    /// How many consumers there are, since a `SharedBacked` can be used by multiple
678    /// consumers.
679    num_senders: Arc<AtomicUsize>,
680    /// Whether this exact shared backend has successfully received a validated parent BAL.
681    bal_prewarmed: Arc<AtomicBool>,
682}
683
684impl CreatedFork {
685    pub fn new(opts: CreateFork, fork: Fork, backend: SharedBackend<AnyNetwork, BlockEnv>) -> Self {
686        Self {
687            opts,
688            fork,
689            backend,
690            num_senders: Arc::new(AtomicUsize::new(1)),
691            bal_prewarmed: Arc::default(),
692        }
693    }
694
695    /// Increment senders and return unique identifier of the fork.
696    fn inc_senders(&self, fork_id: ForkId) -> ForkId {
697        format!(
698            "{}-{}",
699            fork_id.as_str(),
700            self.num_senders.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
701        )
702        .into()
703    }
704}
705
706/// A type that's used to signaling the `MultiForkHandler` when it's time to shut down.
707///
708/// This is essentially a sync on drop, so that the `MultiForkHandler` can flush all rpc cashes.
709///
710/// This type intentionally does not implement `Clone` since it's intended that there's only once
711/// instance.
712#[derive(Debug)]
713struct ShutDownMultiFork {
714    handler: Option<Sender<Request>>,
715    // Keep shared backend handlers alive until this registry has shut down.
716    _parent: Option<Arc<Self>>,
717}
718
719impl Drop for ShutDownMultiFork {
720    fn drop(&mut self) {
721        trace!(target: "fork::multi", "initiating shutdown");
722        let (sender, rx) = oneshot_channel();
723        let req = Request::ShutDown(sender);
724        if let Some(mut handler) = self.handler.take()
725            && handler.try_send(req).is_ok()
726        {
727            let _ = rx.recv();
728            trace!(target: "fork::cache", "multifork backend shutdown");
729        }
730    }
731}
732
733/// Creates a new fork.
734///
735/// This resolves the fork block and environment through the endpoint. The handler creates the
736/// backend with [`create_backend`] only if no backend exists for the fork ID.
737async fn create_fork(
738    mut fork: CreateFork,
739    expected_identity: Option<ForkContext>,
740    prewarm_bal: bool,
741    exact_block: Option<(Fork, BlockNumHash)>,
742) -> eyre::Result<(ForkId, CreateFork, Fork, BlockEnv, Option<BlockAccessList>)> {
743    // Ensure evm_opts reflects the fork URL (may differ from the resolved CreateFork url when
744    // created via cheatcodes, where evm_opts is cloned from the base config).
745    let execution_networks = fork.evm_opts.networks;
746    let require_endpoint_family_match =
747        fork.evm_opts.fork_network_is_inferred || !execution_networks.has_network_selection();
748    let targets_new_endpoint =
749        fork.evm_opts.fork_url.as_ref().is_some_and(|endpoint| endpoint != &fork.url)
750            || fork
751                .evm_opts
752                .fork_endpoint
753                .as_ref()
754                .is_some_and(|identity| identity.endpoint != fork.url);
755    if targets_new_endpoint {
756        // The EVM implementation is already fixed, so use its family as the fallback for a custom
757        // endpoint without metadata. Clear identity and chain values inferred from the old URL;
758        // authoritative metadata from the new endpoint is still checked below.
759        fork.evm_opts.fork_endpoint = None;
760        fork.evm_opts.expected_fork_endpoint = None;
761        fork.evm_opts.fork_network_is_inferred = false;
762        if fork.evm_opts.fork_chain_id_is_inferred {
763            fork.evm_opts.env.chain_id = None;
764            fork.evm_opts.fork_chain_id_is_inferred = false;
765        }
766        if fork.evm_opts.fork_block_number_is_inferred {
767            fork.evm_opts.fork_block_number = None;
768            fork.evm_opts.fork_block_number_is_inferred = false;
769        }
770    }
771    fork.evm_opts.fork_url = Some(fork.url.clone());
772
773    // Initialise the fork environment.
774    // Here we use [`AnyNetwork`] to maximize compatibility with custom chains, aligned with
775    // `EvmOpts::env` impl.
776    let resolved = if let Some((parent, block)) = exact_block {
777        let provider = parent.provider::<AnyNetwork>();
778        fork.evm_opts.check_fork_endpoint(&provider, &parent).await?;
779        let fork_state = parent.at_block(block).await?;
780        fork.evm_opts.check_fork_endpoint(&provider, &fork_state).await?;
781        fork_state
782    } else {
783        fork.evm_opts.prepare_fork().await?.expect("fork URL is configured")
784    };
785    let any_provider = resolved.provider::<AnyNetwork>();
786    let fork_context = resolved.context();
787    let evm_env = fork.evm_opts.fork_env_from_block::<EthEvmNetwork, AnyNetwork>(
788        fork.evm_opts.chain_id_override().unwrap_or(fork_context.execution_chain_id),
789        fork_context.source_chain_id,
790        &resolved.block,
791    );
792    // An endpoint without Anvil node info takes an explicitly selected network as its profile, so
793    // its recognized chain ID decides the family it belongs to. Fork contexts require a recognized
794    // hardfork, so a reported hardfork means node info reported the family.
795    let chain = fork_context.source_chain_id;
796    let source = match NetworkVariant::from_known_chain_id(chain) {
797        Ok(Some(network)) if fork_context.hardfork.is_none() => {
798            NetworkConfigs::default().with_rpc_identity(network, chain)
799        }
800        _ => fork_context.network_profile,
801    };
802    if !execution_networks.supports_fork_source(&source) {
803        let (fork, selected) =
804            (source.execution_profile_name(), execution_networks.execution_profile_name());
805        eyre::ensure!(
806            !require_endpoint_family_match,
807            "cannot create a `{fork}` fork with an EVM instantiated for `{selected}`; run the script with --rpc-url pointing to the forked chain to select its EVM"
808        );
809        // An explicit network selection is kept even when the fork belongs to another family, so
810        // warn once per source chain and family pair instead of failing.
811        static WARNED: Mutex<BTreeSet<(u64, &str, &str)>> = Mutex::new(BTreeSet::new());
812        if WARNED.lock().unwrap().insert((chain, fork, selected)) {
813            let _ = sh_warn!(
814                "fork of chain {chain} belongs to `{fork}`, but the selected network is `{selected}`, so the fork runs with `{selected}` rules"
815            );
816        }
817    }
818    if let Some(expected) = expected_identity {
819        eyre::ensure!(
820            fork_context.has_same_endpoint_identity(expected),
821            "fork endpoint identity changed while the fork was being rolled"
822        );
823    }
824    let bal = if prewarm_bal {
825        bal::prepare(&any_provider, &resolved, &resolved.block).await
826    } else {
827        None
828    };
829    let fork_id = ForkId::resolved(&fork.url, &resolved);
830
831    let block_env = cache_block_env(&evm_env.block, resolved.block.header.excess_blob_gas);
832    Ok((fork_id, fork, resolved, block_env, bal))
833}
834
835/// Creates the backend of a resolved fork.
836///
837/// This loads the disk cache of the fork block, so it only runs for a new fork ID.
838fn create_backend(
839    fork: &CreateFork,
840    resolved: &Fork,
841    block_env: &BlockEnv,
842) -> eyre::Result<(SharedBackend<AnyNetwork, BlockEnv>, BackendHandler<AnyNetwork, BlockEnv>)> {
843    let fork_context = resolved.context();
844    let number = resolved.number();
845    let account_fetch_policy = crate::backend::account_fetch_policy_for_source(
846        fork_context.source_chain_id,
847        fork_context.network_profile,
848    );
849    let meta = BlockchainDbMeta::new(block_env.clone(), fork.url.clone())
850        .with_fork_identity(resolved.hash(), resolved.source_id())
851        .with_account_fetch_policy(account_fetch_policy);
852
853    // Determine the cache path if caching is enabled.
854    // Number-addressed state can follow a replacement block, so keep it in memory only.
855    let cache_path = if fork.enable_caching && !resolved.state_by_number {
856        Config::foundry_block_cache_dir(fork_context.source_chain_id, number)
857    } else {
858        None
859    };
860
861    let provider = resolved.provider::<AnyNetwork>();
862    let db = BlockchainDb::new(meta, cache_path);
863    let anchor = ForkBlock::with_rpc_number(
864        block_env.number.saturating_to(),
865        resolved.number(),
866        resolved.hash(),
867    );
868    if resolved.state_by_number {
869        SharedBackend::new_with_anchor_by_number(provider, db, anchor)
870    } else {
871        SharedBackend::new_with_anchor(provider, db, anchor)
872    }
873}
874
875/// Returns the block environment recorded in the fork cache's metadata.
876///
877/// The disk cache keeps the block environment layout written before evm2, so existing caches stay
878/// valid.
879/// `excess_blob_gas` is the fork header's, which evm2 only keeps as the blob base fee.
880fn cache_block_env(block: &evm2::env::BlockEnv, excess_blob_gas: Option<u64>) -> BlockEnv {
881    let mut env = BlockEnv {
882        number: block.number,
883        beneficiary: block.beneficiary,
884        timestamp: block.timestamp,
885        gas_limit: block.gas_limit.saturating_to(),
886        basefee: block.basefee.saturating_to(),
887        difficulty: block.difficulty,
888        prevrandao: Some(block.prevrandao.into()),
889        slot_num: block.slot_num.saturating_to(),
890        ..Default::default()
891    };
892    if let Some(excess_blob_gas) = excess_blob_gas {
893        env.blob_excess_gas_and_price = Some(BlobExcessGasAndPrice {
894            excess_blob_gas,
895            blob_gasprice: block.blob_basefee.saturating_to(),
896        });
897    }
898    env
899}
900
901#[cfg(test)]
902mod tests {
903    use super::*;
904    use crate::opts::EvmOpts;
905    use alloy_chains::NamedChain;
906    use alloy_eips::{
907        eip7691::BLOB_GASPRICE_UPDATE_FRACTION_PECTRA,
908        eip7928::{AccountChanges, BlockAccessIndex, SlotChanges, StorageChange},
909    };
910    use alloy_network::{AnyHeader, AnyRpcBlock, AnyRpcHeader, TransactionBuilder};
911    use alloy_primitives::{Address, B256, U256, bytes};
912    use alloy_provider::{Provider, ProviderBuilder, mock::Asserter};
913    use alloy_rpc_types::{Block, TransactionRequest};
914    use alloy_serde::WithOtherFields;
915    use foundry_common::provider::get_http_provider;
916    use foundry_fork_db::AccountFetchPolicy;
917    use foundry_test_utils::rpc::{
918        spawn_rpc_proxy_method_not_found_before, spawn_rpc_proxy_recording_method,
919    };
920    use futures::{channel::oneshot, task::noop_waker_ref};
921    use std::sync::mpsc::{Receiver as OneshotReceiver, TryRecvError};
922
923    fn context(block_number: u64) -> ForkContext {
924        ForkContext {
925            execution_chain_id: 1,
926            source_chain_id: 1,
927            network: NetworkVariant::Ethereum,
928            network_profile: NetworkConfigs::default(),
929            block_number,
930            hardfork: None,
931            instance_id: None,
932            source_fork_block_number: None,
933            source_fork_block_hash: None,
934        }
935    }
936
937    #[test]
938    fn resolved_fork_ids_include_hash_and_source_identity() {
939        let url = "http://localhost:8545";
940        let first = Fork::test(
941            url,
942            None,
943            None,
944            Some(1),
945            BlockNumHash::new(1, B256::with_last_byte(1)),
946            context(1),
947        );
948        let replacement = Fork::test(
949            url,
950            None,
951            None,
952            Some(1),
953            BlockNumHash::new(1, B256::with_last_byte(2)),
954            context(1),
955        );
956        let authenticated = Fork::test(
957            url,
958            Some(&["Authorization: secret".to_string()]),
959            None,
960            Some(1),
961            BlockNumHash::new(1, B256::with_last_byte(1)),
962            context(1),
963        );
964
965        assert_ne!(ForkId::resolved(url, &first), ForkId::resolved(url, &replacement));
966        assert_ne!(ForkId::resolved(url, &first), ForkId::resolved(url, &authenticated));
967        let mut numbered = first.clone();
968        numbered.state_by_number = true;
969        assert_ne!(ForkId::resolved(url, &first), ForkId::resolved(url, &numbered));
970        assert_eq!(ForkId::resolved(url, &first), ForkId::exact(url, &numbered, first.block()));
971    }
972
973    #[test]
974    fn account_fetch_policy_follows_source_identity() {
975        assert_eq!(
976            crate::backend::account_fetch_policy_for_source(
977                NamedChain::Tempo as u64,
978                NetworkConfigs::with_ethereum(),
979            ),
980            AccountFetchPolicy::RequireAccountInfoWithExtension,
981        );
982        assert_eq!(
983            crate::backend::account_fetch_policy_for_source(
984                NamedChain::Mainnet as u64,
985                NetworkConfigs::with_tempo(),
986            ),
987            AccountFetchPolicy::Auto,
988        );
989        assert_eq!(
990            crate::backend::account_fetch_policy_for_source(123_456, NetworkConfigs::with_tempo(),),
991            AccountFetchPolicy::RequireAccountInfoWithExtension,
992        );
993        // Local development chain IDs do not identify a family; the endpoint profile does.
994        for chain in [NamedChain::Dev, NamedChain::AnvilHardhat] {
995            assert_eq!(
996                crate::backend::account_fetch_policy_for_source(
997                    chain as u64,
998                    NetworkConfigs::with_tempo(),
999                ),
1000                AccountFetchPolicy::RequireAccountInfoWithExtension,
1001            );
1002            assert_eq!(
1003                crate::backend::account_fetch_policy_for_source(
1004                    chain as u64,
1005                    NetworkConfigs::with_ethereum(),
1006                ),
1007                AccountFetchPolicy::Auto,
1008            );
1009        }
1010    }
1011
1012    #[test]
1013    fn fork_bal_pending_requests_preserve_opt_out() {
1014        let url = "http://localhost:8545";
1015        let resolved = Fork::test(
1016            url,
1017            None,
1018            None,
1019            Some(1),
1020            BlockNumHash::new(1, B256::with_last_byte(1)),
1021            context(1),
1022        );
1023        let (_, receiver) = channel(1);
1024        let mut handler = MultiForkHandler::new(receiver);
1025        let mut fork = CreateFork {
1026            enable_caching: false,
1027            url: url.to_string(),
1028            evm_opts: Default::default(),
1029        };
1030        let (sender, _) = oneshot_channel();
1031        handler.create_fork_with_identity(
1032            fork.clone(),
1033            None,
1034            false,
1035            Some((resolved.clone(), resolved.block())),
1036            sender,
1037        );
1038        fork.evm_opts.no_fork_bal = true;
1039        let (sender, _) = oneshot_channel();
1040        handler.create_fork_with_identity(
1041            fork.clone(),
1042            None,
1043            false,
1044            Some((resolved.clone(), resolved.block())),
1045            sender,
1046        );
1047        assert_eq!(handler.pending_tasks.len(), 2, "each fork must retain its opt-out policy");
1048        let (sender, _) = oneshot_channel();
1049        handler.create_fork_with_identity(
1050            fork.clone(),
1051            None,
1052            false,
1053            Some((resolved.clone(), resolved.block())),
1054            sender,
1055        );
1056        assert_eq!(handler.pending_tasks.len(), 2, "identical policies can share creation");
1057        fork.evm_opts.no_fork_bal = false;
1058        let (sender, _) = oneshot_channel();
1059        handler.create_fork_with_identity(
1060            fork.clone(),
1061            None,
1062            true,
1063            Some((resolved.clone(), resolved.block())),
1064            sender,
1065        );
1066        assert_eq!(handler.pending_tasks.len(), 3, "prewarming must not join ordinary creation");
1067        let (sender, _) = oneshot_channel();
1068        handler.create_fork_with_identity(
1069            fork,
1070            None,
1071            true,
1072            Some((resolved.clone(), resolved.block())),
1073            sender,
1074        );
1075        assert_eq!(handler.pending_tasks.len(), 3, "matching prewarm requests can share creation");
1076    }
1077
1078    #[test]
1079    fn fork_bal_fills_selected_cache_for_equivalent_profiles() {
1080        let url = "http://localhost:8545";
1081        let block = BlockNumHash::new(1, B256::with_last_byte(1));
1082        let address = Address::with_last_byte(1);
1083        let create = |resolved: Fork| {
1084            let provider = ProviderBuilder::<_, _, AnyNetwork>::default()
1085                .connect_mocked_client(Asserter::new());
1086            let meta = BlockchainDbMeta::new(BlockEnv::default(), url.to_string())
1087                .with_fork_identity(resolved.hash(), resolved.source_id());
1088            let (backend, handler) = SharedBackend::new_with_anchor(
1089                provider,
1090                BlockchainDb::new(meta, None),
1091                ForkBlock::with_rpc_number(1, 1, resolved.hash()),
1092            )
1093            .unwrap();
1094            let opts = CreateFork {
1095                enable_caching: false,
1096                url: url.to_string(),
1097                evm_opts: Default::default(),
1098            };
1099            (CreatedFork::new(opts, resolved, backend), handler)
1100        };
1101
1102        for profile in [NetworkConfigs::default(), NetworkConfigs::with_ethereum()] {
1103            let cached = Fork::test(url, None, None, None, block, context(1));
1104            let candidate = Fork::test(
1105                url,
1106                None,
1107                None,
1108                Some(1),
1109                block,
1110                ForkContext { network_profile: profile, ..context(1) },
1111            );
1112            let id = ForkId::resolved(url, &candidate);
1113            assert_eq!(id, ForkId::resolved(url, &cached));
1114            assert_eq!(candidate.fingerprint(), cached.fingerprint());
1115            let (cached, cached_handler) = create(cached);
1116            let cached_db = cached.backend.data();
1117            let bal = vec![AccountChanges::new(address).with_storage_change(SlotChanges::new(
1118                U256::ONE,
1119                vec![StorageChange::new(BlockAccessIndex::new(1), U256::from(42))],
1120            ))];
1121            let future = futures::future::ready(Ok((
1122                id.clone(),
1123                cached.opts.clone(),
1124                candidate,
1125                BlockEnv::default(),
1126                Some(bal),
1127            )));
1128            let (_incoming, receiver) = channel(1);
1129            let mut manager = MultiForkHandler::new(receiver);
1130            manager.forks.insert(id.clone(), cached);
1131            manager.handlers.push((id.clone(), cached_handler));
1132            let (sender, receiver) = oneshot_channel();
1133            manager.pending_tasks.push(ForkTask::Create {
1134                future: Box::pin(future),
1135                id: id.clone(),
1136                prewarm_bal: true,
1137                no_fork_bal: false,
1138                sender,
1139                additional_senders: Vec::new(),
1140            });
1141
1142            assert!(manager.poll_unpin(&mut Context::from_waker(noop_waker_ref())).is_pending());
1143            let result = receiver.try_recv().unwrap().unwrap();
1144            assert!(Arc::ptr_eq(&result.backend.data(), &cached_db));
1145            // Reusing the cached backend creates no second backend.
1146            assert_eq!(manager.handlers.len(), 1);
1147            assert_eq!(
1148                cached_db
1149                    .storage
1150                    .read()
1151                    .get(&address)
1152                    .and_then(|slots| slots.get(&U256::ONE))
1153                    .copied(),
1154                Some(U256::from(42)),
1155            );
1156            assert!(manager.forks[&id].bal_prewarmed.load(Ordering::Relaxed));
1157        }
1158    }
1159
1160    #[tokio::test(flavor = "multi_thread")]
1161    async fn fork_state_by_number_does_not_load_or_overwrite_hash_cache() {
1162        let chain_id = u64::from_be_bytes(B256::random()[..8].try_into().unwrap());
1163        let (_api, handle) = anvil::spawn(
1164            anvil::NodeConfig::test().with_chain_id(Some(chain_id)).with_no_mining(true),
1165        )
1166        .await;
1167        let opts = EvmOpts {
1168            fork_url: Some(handle.http_endpoint()),
1169            fork_block_number: Some(0),
1170            ..Default::default()
1171        };
1172        let resolved = opts.prepare_fork().await.unwrap().unwrap();
1173        let (env, _) = opts.env_at_fork::<EthEvmNetwork>(Some(&resolved)).await.unwrap();
1174        let path = Config::foundry_block_cache_dir(chain_id, resolved.number()).unwrap();
1175        assert!(!path.exists());
1176        let meta = BlockchainDbMeta::new(
1177            cache_block_env(&env.block, resolved.block.header.excess_blob_gas),
1178            handle.http_endpoint(),
1179        )
1180        .with_fork_identity(resolved.hash(), resolved.source_id());
1181        let cached = BlockchainDb::new(meta.clone(), Some(path.clone()));
1182        let address = Address::with_last_byte(0x42);
1183        cached.storage().write().entry(address).or_default().insert(U256::ZERO, U256::from(42));
1184        cached.cache().flush();
1185        assert!(path.exists());
1186
1187        for state_by_number in [true, false] {
1188            let fork = CreateFork {
1189                url: handle.http_endpoint(),
1190                enable_caching: true,
1191                evm_opts: EvmOpts { fork_state_by_number: state_by_number, ..opts.clone() },
1192            };
1193            let (_, fork, fork_state, block_env, _) =
1194                create_fork(fork, None, false, None).await.unwrap();
1195            let (backend, handler) = create_backend(&fork, &fork_state, &block_env).unwrap();
1196            assert_eq!(backend.data().storage.read().contains_key(&address), !state_by_number);
1197            if state_by_number {
1198                backend
1199                    .data()
1200                    .storage
1201                    .write()
1202                    .entry(address)
1203                    .or_default()
1204                    .insert(U256::ZERO, U256::from(99));
1205            }
1206            backend.flush_cache();
1207            drop(backend);
1208            drop(handler);
1209            let reloaded = BlockchainDb::new(meta.clone(), Some(path.clone()));
1210            assert_eq!(reloaded.storage().read()[&address][&U256::ZERO], U256::from(42));
1211        }
1212        std::fs::remove_file(&path).unwrap();
1213        std::fs::remove_dir(path.parent().unwrap()).unwrap();
1214    }
1215
1216    async fn complete_fork(
1217        manager: &mut MultiForkHandler,
1218        receiver: OneshotReceiver<eyre::Result<ForkResult>>,
1219    ) -> ForkResult {
1220        tokio::time::timeout(
1221            Duration::from_secs(10),
1222            futures::future::poll_fn(|cx| {
1223                assert!(manager.poll_unpin(cx).is_pending());
1224                match receiver.try_recv() {
1225                    Ok(result) => Poll::Ready(result),
1226                    Err(TryRecvError::Empty) => Poll::Pending,
1227                    Err(error) => panic!("fork response channel closed: {error}"),
1228                }
1229            }),
1230        )
1231        .await
1232        .unwrap()
1233        .unwrap()
1234    }
1235
1236    #[tokio::test(flavor = "multi_thread")]
1237    async fn fork_bal_reuses_prewarmed_cache_only_for_equivalent_identities() {
1238        let (api, handle) = anvil::spawn(
1239            anvil::NodeConfig::test()
1240                .with_chain_id(Some(1u64))
1241                .with_hardfork(Some(anvil::EthereumHardfork::Amsterdam.into()))
1242                .with_genesis_timestamp(Some(1_800_000_000u64))
1243                .with_no_mining(true),
1244        )
1245        .await;
1246        let address = Address::with_last_byte(0x42);
1247        api.anvil_set_code(address, bytes!("602a60015500")).await.unwrap();
1248        api.send_transaction(WithOtherFields::new(
1249            TransactionRequest::default()
1250                .with_from(handle.dev_accounts().next().unwrap())
1251                .with_to(address)
1252                .with_nonce(0)
1253                // Enough for the EIP-8037 state gas of creating slot one.
1254                .with_gas_limit(1_000_000)
1255                .with_gas_price(2_000_000_000),
1256        ))
1257        .await
1258        .unwrap();
1259        api.mine_one().await.unwrap();
1260        let block = handle.http_provider().get_block_by_number(1.into()).await.unwrap().unwrap();
1261        let block = BlockNumHash::new(1, block.header.hash);
1262        // Expose native BALs through an endpoint without mutable Anvil identity.
1263        let endpoint = spawn_rpc_proxy_method_not_found_before(
1264            handle.http_endpoint(),
1265            "anvil_nodeInfo",
1266            usize::MAX,
1267        )
1268        .await;
1269        let (endpoint, bal_requests) =
1270            spawn_rpc_proxy_recording_method(endpoint, "eth_getBlockAccessList").await;
1271        let (endpoint, probes) = spawn_rpc_proxy_recording_method(endpoint, "anvil_nodeInfo").await;
1272        let (_incoming, receiver) = channel(1);
1273        let mut manager = MultiForkHandler::new(receiver);
1274        let mut first = None;
1275        let mut probe_counts = Vec::new();
1276        let other_headers = ["X-Test-Source: other".to_string()];
1277
1278        for (profile, headers) in [
1279            (NetworkConfigs::default(), None),
1280            (NetworkConfigs::with_ethereum(), None),
1281            (NetworkConfigs::default(), None),
1282            (NetworkConfigs::default(), Some(other_headers.as_slice())),
1283        ] {
1284            let evm_opts = EvmOpts {
1285                fork_url: Some(endpoint.clone()),
1286                fork_block_number: Some(1),
1287                fork_headers: headers.map(<[_]>::to_vec),
1288                networks: profile,
1289                ..Default::default()
1290            };
1291            let resolved = evm_opts.prepare_fork().await.unwrap().unwrap();
1292            assert_eq!(resolved.block(), block);
1293            let fingerprint = resolved.fingerprint();
1294            let fork = CreateFork { enable_caching: false, url: endpoint.clone(), evm_opts };
1295            let before = probes.lock().unwrap().len();
1296            let (sender, receiver) = oneshot_channel();
1297            manager.create_fork_with_identity(
1298                fork,
1299                None,
1300                true,
1301                Some((resolved.clone(), resolved.block())),
1302                sender,
1303            );
1304            let result = tokio::time::timeout(
1305                Duration::from_secs(10),
1306                futures::future::poll_fn(|cx| {
1307                    assert!(manager.poll_unpin(cx).is_pending());
1308                    match receiver.try_recv() {
1309                        Ok(result) => Poll::Ready(result),
1310                        Err(std::sync::mpsc::TryRecvError::Empty) => Poll::Pending,
1311                        Err(error) => panic!("fork response channel closed: {error}"),
1312                    }
1313                }),
1314            )
1315            .await
1316            .unwrap()
1317            .unwrap();
1318
1319            let db = result.backend.data();
1320            assert_eq!(
1321                Arc::ptr_eq(first.get_or_insert_with(|| db.clone()), &db),
1322                headers.is_none(),
1323            );
1324            assert_eq!(result.fork.fingerprint(), fingerprint);
1325            assert_eq!(db.storage.read()[&address][&U256::ONE], U256::from(42));
1326            assert!(manager.forks[&result.id].bal_prewarmed.load(Ordering::Relaxed));
1327            assert_eq!(bal_requests.lock().unwrap().len(), if headers.is_some() { 2 } else { 1 });
1328            probe_counts.push(probes.lock().unwrap().len() - before);
1329        }
1330
1331        // Only cold caches need the two source probes surrounding BAL preparation.
1332        assert_eq!(probe_counts[0], probe_counts[1] + 2);
1333        assert_eq!(probe_counts[1], probe_counts[2]);
1334        assert_eq!(probe_counts[0], probe_counts[3]);
1335    }
1336
1337    #[tokio::test(flavor = "multi_thread")]
1338    async fn fork_bal_shared_backend_preserves_opposite_policies_on_roll() {
1339        let (api, handle) = anvil::spawn(
1340            anvil::NodeConfig::test()
1341                .with_chain_id(Some(1u64))
1342                .with_hardfork(Some(anvil::EthereumHardfork::Amsterdam.into()))
1343                .with_genesis_timestamp(Some(1_800_000_000u64))
1344                .with_no_mining(true),
1345        )
1346        .await;
1347        let mut blocks = Vec::new();
1348        for number in 1..=3 {
1349            api.mine_one().await.unwrap();
1350            let block =
1351                handle.http_provider().get_block_by_number(number.into()).await.unwrap().unwrap();
1352            blocks.push(BlockNumHash::new(number, block.header.hash));
1353        }
1354        // Expose native BALs through an endpoint without mutable Anvil identity.
1355        let endpoint = spawn_rpc_proxy_method_not_found_before(
1356            handle.http_endpoint(),
1357            "anvil_nodeInfo",
1358            usize::MAX,
1359        )
1360        .await;
1361        let (endpoint, bal_requests) =
1362            spawn_rpc_proxy_recording_method(endpoint, "eth_getBlockAccessList").await;
1363        let resolved = EvmOpts {
1364            fork_url: Some(endpoint.clone()),
1365            fork_block_number: Some(1),
1366            ..Default::default()
1367        }
1368        .prepare_fork()
1369        .await
1370        .unwrap()
1371        .unwrap();
1372        assert_eq!(resolved.block(), blocks[0]);
1373
1374        for disabled_first in [false, true] {
1375            let (_incoming, receiver) = channel(1);
1376            let mut manager = MultiForkHandler::new(receiver);
1377            bal_requests.lock().unwrap().clear();
1378            let mut requests = [false, true].map(|no_fork_bal| {
1379                let fork = CreateFork {
1380                    enable_caching: false,
1381                    url: endpoint.clone(),
1382                    evm_opts: EvmOpts {
1383                        fork_url: Some(endpoint.clone()),
1384                        fork_block_number: Some(1),
1385                        no_fork_bal,
1386                        ..Default::default()
1387                    },
1388                };
1389                let (sender, receiver) = oneshot_channel();
1390                manager.create_fork(fork, sender);
1391                let ForkTask::Create { future, .. } = manager.pending_tasks.last_mut().unwrap();
1392                let original = std::mem::replace(future, Box::pin(futures::future::pending()));
1393                let (release, gate) = oneshot::channel();
1394                // Run real creation, but explicitly control which result reaches backend reuse.
1395                *future = Box::pin(async move {
1396                    let result = original.await;
1397                    gate.await.unwrap();
1398                    result
1399                });
1400                (no_fork_bal, release, receiver)
1401            });
1402            assert_eq!(manager.pending_tasks.len(), 2);
1403            if disabled_first {
1404                requests.reverse();
1405            }
1406            let [
1407                (first_policy, first_gate, first_receiver),
1408                (second_policy, second_gate, second_receiver),
1409            ] = requests;
1410            first_gate.send(()).unwrap();
1411            let first = complete_fork(&mut manager, first_receiver).await;
1412            assert!(matches!(second_receiver.try_recv(), Err(TryRecvError::Empty)));
1413            assert_eq!(manager.pending_tasks.len(), 1);
1414            second_gate.send(()).unwrap();
1415            let second = complete_fork(&mut manager, second_receiver).await;
1416
1417            assert_ne!(first.id, second.id);
1418            assert!(Arc::ptr_eq(&first.backend.data(), &second.backend.data()));
1419            assert!(Arc::ptr_eq(first.fork.client.inner(), second.fork.client.inner()));
1420            assert!(Arc::ptr_eq(&first.fork.block, &second.fork.block));
1421            assert_eq!(manager.forks[&first.id].opts.evm_opts.no_fork_bal, first_policy);
1422            assert_eq!(manager.forks[&second.id].opts.evm_opts.no_fork_bal, second_policy);
1423            assert!(bal_requests.lock().unwrap().is_empty());
1424
1425            // Each roll targets a cold block so shared prewarming cannot mask a lost policy.
1426            for (no_fork_bal, fork, block) in
1427                [(first_policy, first, blocks[1]), (second_policy, second, blocks[2])]
1428            {
1429                bal_requests.lock().unwrap().clear();
1430                let (sender, receiver) = oneshot_channel();
1431                manager.on_request(Request::RollForkExact(fork.id, block, true, sender));
1432                let rolled = complete_fork(&mut manager, receiver).await;
1433                assert_eq!(rolled.fork.block(), block);
1434                assert_eq!(manager.forks[&rolled.id].opts.evm_opts.no_fork_bal, no_fork_bal);
1435                assert_eq!(
1436                    manager.forks[&rolled.id].bal_prewarmed.load(Ordering::Relaxed),
1437                    !no_fork_bal,
1438                );
1439                let expected =
1440                    if no_fork_bal { vec![] } else { vec![serde_json::json!([block.hash])] };
1441                assert_eq!(*bal_requests.lock().unwrap(), expected);
1442            }
1443        }
1444    }
1445
1446    #[tokio::test(flavor = "multi_thread")]
1447    async fn can_read_write_cache() {
1448        let endpoint = &*foundry_test_utils::rpc::next_http_rpc_endpoint();
1449        let provider = get_http_provider(endpoint);
1450
1451        let block_num = provider.get_block_number().await.unwrap();
1452
1453        let mut evm_opts = Config::figment().extract::<EvmOpts>().unwrap();
1454        evm_opts.fork_url = Some(endpoint.to_string());
1455        evm_opts.fork_block_number = Some(block_num);
1456
1457        let backend = crate::backend::Backend::<EthEvmNetwork>::spawn(
1458            evm_opts.get_fork(&Config::default(), NamedChain::Mainnet as u64, None),
1459            evm_opts.local_evm_env::<EthEvmNetwork>(),
1460        )
1461        .unwrap();
1462        let fork = backend.fork().unwrap();
1463        let fork_hash = fork.hash();
1464        let source_id = fork.source_id();
1465        let (evm_env, _) = backend.env(&evm_opts).await.unwrap();
1466
1467        // some rng contract from etherscan.
1468        let address = alloy_primitives::address!("0x63091244180ae240c87d1f528f5f269134cb07b3");
1469
1470        let num_slots = 5;
1471        let _account = backend.basic(address);
1472        for idx in 0..num_slots {
1473            let _ = backend.storage(address, U256::from(idx));
1474        }
1475        drop(backend);
1476
1477        let block_env = cache_block_env(&evm_env.block, fork.block.header.excess_blob_gas);
1478        let meta = BlockchainDbMeta::new(block_env, endpoint.to_string())
1479            .with_fork_identity(fork_hash, source_id);
1480
1481        let db = BlockchainDb::new(
1482            meta,
1483            Some(Config::foundry_block_cache_dir(NamedChain::Mainnet, block_num).unwrap()),
1484        );
1485        assert!(db.accounts().read().contains_key(&address));
1486        assert!(db.storage().read().contains_key(&address));
1487        assert_eq!(db.storage().read().get(&address).unwrap().len(), num_slots as usize);
1488    }
1489
1490    #[test]
1491    fn cache_block_env_records_blob_excess_gas() {
1492        let fork_block = |excess_blob_gas| {
1493            // A mainnet block after Prague and before Osaka.
1494            let header =
1495                AnyHeader { timestamp: 1_750_000_000, excess_blob_gas, ..Default::default() };
1496            AnyRpcBlock::new(
1497                Block::new(AnyRpcHeader::from_sealed(header.seal(B256::ZERO)), Default::default())
1498                    .into(),
1499            )
1500        };
1501        let cache_env = |block: &AnyRpcBlock| {
1502            let env =
1503                EvmOpts::default().fork_env_from_block::<EthEvmNetwork, AnyNetwork>(1, 1, block);
1504            cache_block_env(&env.block, block.header.excess_blob_gas)
1505        };
1506
1507        // The cache records the blob price for the header's excess blob gas.
1508        let mut expected = BlockEnv::default();
1509        expected
1510            .set_blob_excess_gas_and_price(62_652_416, BLOB_GASPRICE_UPDATE_FRACTION_PECTRA as u64);
1511        assert_eq!(
1512            cache_env(&fork_block(Some(62_652_416))).blob_excess_gas_and_price,
1513            expected.blob_excess_gas_and_price
1514        );
1515        assert_eq!(
1516            cache_env(&fork_block(None)).blob_excess_gas_and_price,
1517            BlockEnv::default().blob_excess_gas_and_price
1518        );
1519    }
1520}