Skip to main content

foundry_evm_core/
opts.rs

1use crate::{
2    constants::DEFAULT_CREATE2_DEPLOYER,
3    evm::{
4        EvmEnv, EvmEnvFor, EvmFactoryFor, FoundryEvmFactory, FoundryEvmNetwork, SpecFor, SpecOf,
5        TransactionRequestFor, TypesFor,
6    },
7    fork::{CreateFork, Fork},
8    utils::{apply_chain_and_block_specific_env_changes_for_chain, block_env_from_header},
9};
10use alloy_consensus::BlockHeader;
11use alloy_eips::BlockNumHash;
12use alloy_network::{
13    AnyNetwork, BlockResponse, Network, TransactionBuilder, primitives::HeaderResponse,
14};
15use alloy_primitives::{Address, B256, BlockNumber, Bytes, ChainId, U64, U256};
16use alloy_provider::{Provider, RootProvider};
17use alloy_rpc_client::RpcClient;
18use alloy_rpc_types::{
19    BlockNumberOrTag,
20    anvil::{Metadata, NodeInfo},
21};
22use evm2::{EvmFeatures, Version, env::BlockEnv};
23use eyre::{OptionExt, WrapErr};
24use foundry_common::{
25    ALCHEMY_FREE_TIER_CUPS, NON_ARCHIVE_NODE_WARNING,
26    provider::{ProviderBuilder, is_rpc_method_not_found},
27};
28use foundry_compilers::artifacts::EvmVersion;
29use foundry_config::{Chain, Config, ExecutionSpec, FoundryHardfork, GasLimit, evm_spec_id};
30use foundry_evm_networks::{NetworkConfigs, NetworkVariant};
31use serde::{Deserialize, Serialize};
32use std::fmt::Write;
33use url::Url;
34
35/// EVM execution options, including the configured remote fork.
36///
37/// Fork handling separates two responsibilities. Endpoint discovery identifies and caches the
38/// execution family without selecting a block. Exact resolution binds the configured source and
39/// selector to a block number, hash, and endpoint context. Forge normally performs discovery
40/// before resolution, while callers that already know the network can resolve directly.
41///
42/// Resolution revalidates the endpoint identity around its remote reads. A cached discovery that
43/// found no Anvil identity has nothing to revalidate and is reused instead, so the chain ID and
44/// the `anvil_nodeInfo` probe of such an endpoint are requested once, by discovery.
45///
46/// An implicit `latest` selector remains unchanged in these options; only the returned
47/// [`Fork`] is pinned to the exact block observed during resolution.
48#[derive(Clone, Debug, Serialize, Deserialize)]
49pub struct EvmOpts {
50    /// The EVM environment configuration.
51    #[serde(flatten)]
52    pub env: Env,
53
54    /// Fetch state over a remote instead of starting from empty state.
55    #[serde(rename = "eth_rpc_url")]
56    pub fork_url: Option<String>,
57
58    /// Pins the block number for the state fork.
59    pub fork_block_number: Option<u64>,
60
61    /// Fetch fork state by block number for RPCs that cannot serve it by hash.
62    #[serde(default)]
63    pub fork_state_by_number: bool,
64
65    /// The number of retries.
66    pub fork_retries: Option<u32>,
67
68    /// Initial retry backoff.
69    pub fork_retry_backoff: Option<u64>,
70
71    /// Headers to use with `fork_url`
72    pub fork_headers: Option<Vec<String>>,
73
74    /// JWT secret to use with the configured RPC endpoint.
75    #[serde(rename = "eth_rpc_jwt")]
76    pub rpc_jwt: Option<String>,
77
78    /// Headers to use with the configured RPC endpoint.
79    #[serde(rename = "eth_rpc_headers")]
80    pub rpc_headers: Option<Vec<String>>,
81
82    /// Request timeout to use with the configured RPC endpoint.
83    #[serde(rename = "eth_rpc_timeout")]
84    pub rpc_timeout: Option<u64>,
85
86    /// Whether to accept invalid certificates from the configured RPC endpoint.
87    #[serde(default, rename = "eth_rpc_accept_invalid_certs")]
88    pub rpc_accept_invalid_certs: bool,
89
90    /// Whether to disable automatic proxy detection for the configured RPC endpoint.
91    #[serde(default, rename = "eth_rpc_no_proxy")]
92    pub rpc_no_proxy: bool,
93
94    /// The available compute units per second.
95    ///
96    /// See also <https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second>
97    pub compute_units_per_second: Option<u64>,
98
99    /// Disables RPC rate limiting entirely.
100    pub no_rpc_rate_limit: bool,
101
102    /// Disables storage caching entirely.
103    pub no_storage_caching: bool,
104
105    /// Disables parent-block BAL cache prewarming for transaction-hash forks.
106    #[serde(default)]
107    pub no_fork_bal: bool,
108
109    /// Prefetches remote fork state before the EVM reads it, see `Config::fork_prefetch`.
110    #[serde(default)]
111    pub fork_prefetch: bool,
112
113    /// The initial balance of each deployed test contract.
114    pub initial_balance: U256,
115
116    /// The address which will be executing all tests.
117    pub sender: Address,
118
119    /// Enables the FFI cheatcode.
120    pub ffi: bool,
121
122    /// Makes every cheatcode that opens a network connection fail. Only callers set it; config
123    /// cannot.
124    #[serde(skip)]
125    pub no_network: bool,
126
127    /// Use the create 2 factory in all cases including tests and non-broadcasting scripts.
128    pub always_use_create_2_factory: bool,
129
130    /// Verbosity mode of EVM output as number of occurrences.
131    pub verbosity: u8,
132
133    /// The memory limit per EVM execution in bytes.
134    /// If this limit is exceeded, a `MemoryLimitOOG` result is thrown.
135    pub memory_limit: u64,
136
137    /// Whether to enable isolation of calls.
138    pub isolate: bool,
139
140    /// Whether to disable block gas limit checks.
141    pub disable_block_gas_limit: bool,
142
143    /// Whether to enable tx gas limit checks as imposed by Osaka (EIP-7825) and
144    /// Amsterdam (EIP-8037).
145    pub enable_tx_gas_limit: bool,
146
147    #[serde(flatten)]
148    /// Networks with enabled features.
149    pub networks: NetworkConfigs,
150
151    /// The CREATE2 deployer's address.
152    pub create2_deployer: Address,
153
154    /// Most recently discovered endpoint identity, cached for network dispatch and revalidation.
155    ///
156    /// An identity without Anvil metadata also stands in for later identity snapshots of the same
157    /// endpoint.
158    #[serde(skip)]
159    pub fork_endpoint: Option<ForkEndpointIdentity>,
160
161    /// Endpoint identity promoted to an invariant that later discovery must match.
162    #[serde(skip)]
163    pub expected_fork_endpoint: Option<ForkEndpointIdentity>,
164
165    /// Whether the active network selection was inferred from the fork endpoint.
166    #[serde(skip)]
167    pub fork_network_is_inferred: bool,
168
169    /// Whether `env.chain_id` was inferred from the fork endpoint.
170    #[serde(skip)]
171    pub fork_chain_id_is_inferred: bool,
172
173    /// Whether `fork_block_number` was pinned from the fork endpoint's latest block.
174    #[serde(skip)]
175    pub fork_block_number_is_inferred: bool,
176}
177
178/// A snapshot of the execution and upstream-source identity exposed by an RPC endpoint.
179///
180/// This identity is independent of the block selector Forge resolves. In particular,
181/// `source_fork_block_*` describes the upstream block from which an Anvil endpoint was itself
182/// forked; the target block selected for local execution belongs to [`Fork`]. Equality
183/// detects observable endpoint identity changes, including Anvil instance resets, and
184/// execution-profile changes between related RPC reads.
185#[derive(Clone, Debug, PartialEq, Eq)]
186pub struct ForkEndpointIdentity {
187    /// RPC URL from which this identity was discovered.
188    ///
189    /// Request headers and JWT credentials are bound separately by [`Fork`].
190    pub endpoint: String,
191    /// Chain ID exposed through `eth_chainId`.
192    pub execution_chain_id: ChainId,
193    /// Underlying source chain ID, when the endpoint is itself a fork.
194    pub source_chain_id: ChainId,
195    /// EVM family exposed by the endpoint.
196    pub network: NetworkVariant,
197    /// Complete execution profile exposed by the endpoint.
198    pub network_profile: NetworkConfigs,
199    /// Raw hardfork name reported by an Anvil endpoint.
200    pub reported_hardfork: Option<String>,
201    /// Parsed hardfork exposed by an Anvil endpoint, when recognized.
202    pub hardfork: Option<FoundryHardfork>,
203    /// Anvil instance identifier used to detect resets during multi-call discovery.
204    pub instance_id: Option<B256>,
205    /// Block number from which an Anvil endpoint was forked.
206    pub source_fork_block_number: Option<BlockNumber>,
207    /// Block hash from which an Anvil endpoint was forked.
208    pub source_fork_block_hash: Option<B256>,
209}
210
211#[derive(Clone, Copy, Debug, PartialEq, Eq)]
212enum EndpointHardforkPolicy {
213    /// Permit an unrecognized hardfork during early network-family discovery.
214    Optional,
215    /// Require a recognized hardfork before constructing an execution environment.
216    Required,
217}
218
219/// Best-effort Anvil detection that becomes strict after positive identification.
220///
221/// Before the first successful `anvil_nodeInfo` response, any probe failure means that the
222/// optional capability is unavailable. Mandatory standard RPC reads still expose endpoint-wide
223/// failures. Once a response or cached endpoint identity identifies Anvil, every later probe
224/// failure is returned so it cannot hide an endpoint reset or execution-profile change.
225///
226/// The probe is not repeated for an endpoint whose cached discovery found no Anvil identity, see
227/// [`EvmOpts::discovered_non_anvil_chain_id`].
228#[derive(Clone, Copy, Debug, Default)]
229struct AnvilNodeInfoProbe {
230    identified: bool,
231}
232
233impl AnvilNodeInfoProbe {
234    const fn new(identified: bool) -> Self {
235        Self { identified }
236    }
237
238    async fn request<N: Network, P: Provider<N>>(
239        &mut self,
240        provider: &P,
241    ) -> eyre::Result<Option<NodeInfo>> {
242        match provider.raw_request::<_, NodeInfo>("anvil_nodeInfo".into(), ()).await {
243            Ok(node_info) => {
244                self.identified = true;
245                Ok(Some(node_info))
246            }
247            Err(_) if !self.identified => Ok(None),
248            Err(error) => Err(error).wrap_err("failed to determine network family from endpoint"),
249        }
250    }
251}
252
253fn endpoint_hardfork(
254    network: NetworkVariant,
255    hardfork: &str,
256    policy: EndpointHardforkPolicy,
257) -> eyre::Result<Option<FoundryHardfork>> {
258    match network.parse_hardfork(hardfork) {
259        Ok(hardfork) => Ok(Some(hardfork)),
260        Err(_) if policy == EndpointHardforkPolicy::Optional => Ok(None),
261        Err(error) => Err(eyre::Report::msg(error)).wrap_err_with(|| {
262            format!("unsupported hardfork `{hardfork}` reported for `{network}`")
263        }),
264    }
265}
266
267/// Endpoint identity paired with the remote block number backing a fork.
268///
269/// [`Fork`] adds the exact block hash and configured RPC source. The remote
270/// `block_number` may differ from a remapped EVM block number on L2s, and the source chain ID
271/// remains distinct from a configured `CHAINID` opcode override.
272#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize)]
273pub struct ForkContext {
274    /// Chain ID exposed through `eth_chainId`.
275    pub execution_chain_id: ChainId,
276    /// Underlying source chain ID.
277    pub source_chain_id: ChainId,
278    /// Execution network exposed by the endpoint.
279    pub network: NetworkVariant,
280    /// Complete execution profile exposed by the endpoint.
281    pub network_profile: NetworkConfigs,
282    /// Actual block number fetched from the fork endpoint.
283    pub block_number: BlockNumber,
284    /// Exact hardfork reported by the fork endpoint, when available.
285    pub hardfork: Option<FoundryHardfork>,
286    /// Anvil instance identifier, when exposed by the endpoint.
287    pub instance_id: Option<B256>,
288    /// Block number from which the endpoint itself was forked.
289    pub source_fork_block_number: Option<BlockNumber>,
290    /// Block hash from which the endpoint itself was forked.
291    pub source_fork_block_hash: Option<B256>,
292}
293
294impl ForkContext {
295    /// Returns whether this block context belongs to `identity`.
296    pub fn matches_identity(self, identity: &ForkEndpointIdentity) -> bool {
297        self.execution_chain_id == identity.execution_chain_id
298            && self.source_chain_id == identity.source_chain_id
299            && self.network == identity.network
300            && self.network_profile == identity.network_profile
301            && self.hardfork == identity.hardfork
302            && self.instance_id == identity.instance_id
303            && self.source_fork_block_number == identity.source_fork_block_number
304            && self.source_fork_block_hash == identity.source_fork_block_hash
305    }
306
307    /// Returns whether two block contexts belong to the same endpoint identity.
308    pub(crate) fn has_same_endpoint_identity(self, other: Self) -> bool {
309        self.execution_chain_id == other.execution_chain_id
310            && self.source_chain_id == other.source_chain_id
311            && self.network == other.network
312            && self.network_profile == other.network_profile
313            && self.hardfork == other.hardfork
314            && self.instance_id == other.instance_id
315            && self.source_fork_block_number == other.source_fork_block_number
316            && self.source_fork_block_hash == other.source_fork_block_hash
317    }
318
319    /// Returns whether two contexts can reuse a backend pinned by block number.
320    pub fn has_same_backend_target(self, other: Self) -> bool {
321        self.has_same_endpoint_identity(other) && self.block_number == other.block_number
322    }
323}
324
325impl Default for EvmOpts {
326    fn default() -> Self {
327        Self {
328            env: Env::default(),
329            fork_url: None,
330            fork_block_number: None,
331            fork_state_by_number: false,
332            fork_retries: None,
333            fork_retry_backoff: None,
334            fork_headers: None,
335            rpc_jwt: None,
336            rpc_headers: None,
337            rpc_timeout: None,
338            rpc_accept_invalid_certs: false,
339            rpc_no_proxy: false,
340            compute_units_per_second: None,
341            no_rpc_rate_limit: false,
342            no_storage_caching: false,
343            no_fork_bal: false,
344            fork_prefetch: false,
345            initial_balance: U256::default(),
346            sender: Address::default(),
347            ffi: false,
348            no_network: false,
349            always_use_create_2_factory: false,
350            verbosity: 0,
351            memory_limit: 0,
352            isolate: false,
353            disable_block_gas_limit: false,
354            enable_tx_gas_limit: false,
355            networks: NetworkConfigs::default(),
356            create2_deployer: DEFAULT_CREATE2_DEPLOYER,
357            fork_endpoint: None,
358            expected_fork_endpoint: None,
359            fork_network_is_inferred: false,
360            fork_chain_id_is_inferred: false,
361            fork_block_number_is_inferred: false,
362        }
363    }
364}
365
366impl EvmOpts {
367    /// Clears state derived from a fork endpoint while preserving explicit configuration.
368    fn clear_endpoint_derived_fork_state(&mut self) {
369        if self.fork_block_number_is_inferred {
370            self.fork_block_number = None;
371            self.fork_block_number_is_inferred = false;
372        }
373        self.fork_endpoint = None;
374        self.expected_fork_endpoint = None;
375        if self.fork_network_is_inferred {
376            self.networks = self.networks.with_rpc_profile(NetworkConfigs::default());
377            self.fork_network_is_inferred = false;
378        }
379        if self.fork_chain_id_is_inferred {
380            self.env.chain_id = None;
381            self.fork_chain_id_is_inferred = false;
382        }
383    }
384
385    /// Selects a new fork URL and clears endpoint-derived state from the previous source.
386    pub fn set_fork_url(&mut self, fork_url: String) {
387        if self.fork_url.as_ref() == Some(&fork_url) {
388            return;
389        }
390        self.fork_url = Some(fork_url);
391        self.clear_endpoint_derived_fork_state();
392    }
393
394    /// Invalidates endpoint-derived state when the effective RPC source changed since `fork` was
395    /// resolved.
396    ///
397    /// The effective source consists of the URL, active headers, and JWT. Explicit block, network,
398    /// and chain-ID selections are retained so the new source is resolved under the same user
399    /// configuration.
400    pub fn invalidate_fork_endpoint_if_source_changed(&mut self, fork: &Fork) -> bool {
401        let matches = self.fork_url.as_deref().is_some_and(|fork_url| {
402            fork.matches_source(fork_url, self.fork_source_headers(), self.rpc_jwt.as_deref())
403        });
404        if matches {
405            return false;
406        }
407        self.clear_endpoint_derived_fork_state();
408        true
409    }
410
411    /// Applies an explicit network override, replacing any endpoint-inferred selection.
412    pub fn set_explicit_network(&mut self, network: NetworkVariant) {
413        self.networks = network.into();
414        self.fork_network_is_inferred = false;
415    }
416
417    /// Requires subsequent local fork construction to use this exact endpoint identity.
418    pub fn expect_fork_endpoint(
419        &mut self,
420        identity: ForkEndpointIdentity,
421        network_is_inferred: bool,
422    ) {
423        self.fork_endpoint = Some(identity.clone());
424        self.expected_fork_endpoint = Some(identity);
425        self.fork_network_is_inferred = network_is_inferred;
426    }
427
428    fn ensure_expected_fork_endpoint(&self, identity: &ForkEndpointIdentity) -> eyre::Result<()> {
429        if let Some(expected) = &self.expected_fork_endpoint
430            && expected != identity
431        {
432            eyre::bail!(
433                "fork endpoint {} changed after its execution context was selected",
434                fork_endpoint_description(&identity.endpoint)
435            );
436        }
437        Ok(())
438    }
439
440    /// Rejects an inferred network whose endpoint now reports a different execution profile.
441    fn ensure_inferred_execution_profile(
442        &self,
443        identity: &ForkEndpointIdentity,
444    ) -> eyre::Result<()> {
445        eyre::ensure!(
446            !self.fork_network_is_inferred
447                || self.networks.has_same_execution_profile(&identity.network_profile),
448            "fork endpoint {} changed execution profile from `{}` to `{}`; rebuild the EVM for \
449             the new network",
450            fork_endpoint_description(&identity.endpoint),
451            self.networks.execution_profile_name(),
452            identity.network_profile.execution_profile_name()
453        );
454        Ok(())
455    }
456
457    pub(crate) fn chain_id_override(&self) -> Option<ChainId> {
458        (!self.fork_chain_id_is_inferred).then_some(self.env.chain_id).flatten()
459    }
460
461    fn endpoint_network_fallback(&self) -> NetworkConfigs {
462        if self.networks.has_network_selection() && !self.fork_network_is_inferred {
463            self.networks
464        } else {
465            NetworkConfigs::default()
466        }
467    }
468
469    fn anvil_node_info_probe(&self) -> AnvilNodeInfoProbe {
470        let endpoint = self.fork_url.as_deref();
471        let identified = [self.fork_endpoint.as_ref(), self.expected_fork_endpoint.as_ref()]
472            .into_iter()
473            .flatten()
474            .any(|identity| {
475                Some(identity.endpoint.as_str()) == endpoint && identity.reported_hardfork.is_some()
476            });
477        AnvilNodeInfoProbe::new(identified)
478    }
479
480    /// Returns the chain ID of the configured endpoint if its cached discovery found no Anvil
481    /// identity.
482    ///
483    /// Without Anvil node info the identity is derived from the chain ID alone: there is no
484    /// instance, hardfork, or upstream fork that a reset could change between two reads. Later
485    /// snapshots of the same endpoint therefore reuse the discovered chain ID instead of
486    /// requesting `eth_chainId` and probing `anvil_nodeInfo` again. An endpoint that
487    /// `node_info_probe` or a cached identity identifies as Anvil is never reused and keeps its
488    /// strict revalidation.
489    fn discovered_non_anvil_chain_id(
490        &self,
491        node_info_probe: AnvilNodeInfoProbe,
492    ) -> Option<ChainId> {
493        if node_info_probe.identified {
494            return None;
495        }
496        let endpoint = self.fork_url.as_deref()?;
497        self.fork_endpoint
498            .as_ref()
499            .filter(|identity| identity.endpoint == endpoint)
500            .map(|identity| identity.execution_chain_id)
501    }
502
503    pub(crate) fn fork_source_headers(&self) -> Option<&[String]> {
504        self.fork_headers.as_deref().or(self.rpc_headers.as_deref())
505    }
506
507    #[cfg(test)]
508    fn test_fork(&self, fork_url: &str, block: BlockNumHash, context: ForkContext) -> Fork {
509        let mut fork = Fork::test(
510            fork_url,
511            self.fork_source_headers(),
512            self.rpc_jwt.as_deref(),
513            self.fork_block_number,
514            block,
515            context,
516        );
517        fork.state_by_number = self.fork_state_by_number;
518        fork
519    }
520
521    /// Converts an implicit `latest` selector into a block-number selector in place.
522    ///
523    /// This only reads the endpoint's current block number; it does not resolve a block hash or
524    /// endpoint identity and is therefore not a reorg-safe fork snapshot. Create a
525    /// [`Backend`](crate::backend::Backend) when preflight and execution must share an exact
526    /// identity.
527    pub async fn pin_fork_block(&mut self) -> eyre::Result<Option<BlockNumber>> {
528        if self.fork_block_number.is_none()
529            && let Some(fork_url) = &self.fork_url
530        {
531            self.fork_block_number = Some(
532                self.fork_provider_with_url::<AnyNetwork>(fork_url)?.get_block_number().await?,
533            );
534            self.fork_block_number_is_inferred = true;
535        }
536        Ok(self.fork_block_number)
537    }
538
539    /// Resolves the configured fork source and selector to an exact snapshot without changing
540    /// `self`.
541    ///
542    /// Endpoint identity is read before and after the target block and the operation is retried if
543    /// it changes. The result binds the configured RPC source, configured selector, exact block
544    /// number and hash, and [`ForkContext`]. When the selector is implicit `latest`, only the
545    /// returned [`Fork`] is pinned.
546    pub(crate) async fn prepare_fork(&self) -> eyre::Result<Option<Fork>> {
547        let Some(fork_url) = &self.fork_url else { return Ok(None) };
548        let client = self.fork_rpc_client(fork_url)?;
549        let provider = RootProvider::<AnyNetwork>::new(client.clone());
550        let target = match self.fork_block_number {
551            Some(block_number) => BlockNumberOrTag::Number(block_number),
552            None => BlockNumberOrTag::Latest,
553        };
554        let mut node_info_probe = self.anvil_node_info_probe();
555        let (block, _, context) =
556            self.resolve_fork_block_with_context(&provider, target, &mut node_info_probe).await?;
557        Ok(Some(Fork::new(self, client, block, context)))
558    }
559
560    /// Returns whether the configured CREATE2 deployer existed at the resolved fork block.
561    pub(crate) async fn can_use_create2_deployer_at(
562        &self,
563        fork: Option<&Fork>,
564    ) -> eyre::Result<bool> {
565        let Some(_) = &self.fork_url else {
566            eyre::ensure!(fork.is_none(), "resolved fork provided without a configured fork");
567            return Ok(self.create2_deployer == DEFAULT_CREATE2_DEPLOYER);
568        };
569        let fork = fork.ok_or_else(|| eyre::eyre!("fork must be resolved"))?;
570        let provider = self.provider_for_fork::<AnyNetwork>(fork)?;
571        self.check_fork_endpoint(&provider, fork).await?;
572        let code: Bytes = provider
573            .raw_request("eth_getCode".into(), (self.create2_deployer, fork.state_block_id()))
574            .await?;
575        let available = !code.is_empty();
576        self.check_fork_endpoint(&provider, fork).await?;
577        Ok(available)
578    }
579
580    /// Returns a provider configured for an already resolved fork.
581    pub(crate) fn provider_for_fork<N: Network>(
582        &self,
583        fork: &Fork,
584    ) -> eyre::Result<RootProvider<N>> {
585        eyre::ensure!(
586            fork.matches_request(self),
587            "resolved fork does not match the configured source and selector"
588        );
589        Ok(fork.provider())
590    }
591
592    pub(crate) async fn check_fork_endpoint<N: Network, P: Provider<N>>(
593        &self,
594        provider: &P,
595        fork: &Fork,
596    ) -> eyre::Result<()> {
597        let mut node_info_probe = self.anvil_node_info_probe();
598        node_info_probe.identified |= fork.context().hardfork.is_some();
599        let identity = self
600            .resolve_fork_endpoint_once(
601                provider,
602                &mut node_info_probe,
603                EndpointHardforkPolicy::Required,
604            )
605            .await?;
606        self.ensure_expected_fork_endpoint(&identity)?;
607        self.ensure_inferred_execution_profile(&identity)?;
608        eyre::ensure!(
609            fork.context().matches_identity(&identity),
610            "fork endpoint {} changed after its block and execution context were resolved",
611            fork_endpoint_description(self.fork_url.as_deref().unwrap_or_default())
612        );
613        Ok(())
614    }
615
616    /// Returns an account nonce at the exact block and endpoint identity of `fork`.
617    pub(crate) async fn transaction_count_at_fork(
618        &self,
619        account: Address,
620        fork: &Fork,
621    ) -> eyre::Result<u64> {
622        let provider = self.provider_for_fork::<AnyNetwork>(fork)?;
623        self.check_fork_endpoint(&provider, fork).await?;
624        let nonce: U64 = provider
625            .raw_request("eth_getTransactionCount".into(), (account, fork.state_block_id()))
626            .await?;
627        self.check_fork_endpoint(&provider, fork).await?;
628        Ok(nonce.to())
629    }
630
631    /// Returns a `RootProvider` for the given fork URL configured with options in `self` and
632    /// annotated `Network` type.
633    pub fn fork_provider_with_url<N: Network>(
634        &self,
635        fork_url: &str,
636    ) -> eyre::Result<RootProvider<N>> {
637        Ok(RootProvider::new(self.fork_rpc_client(fork_url)?))
638    }
639
640    pub(crate) fn fork_rpc_client(&self, fork_url: &str) -> eyre::Result<RpcClient> {
641        let mut builder = ProviderBuilder::<AnyNetwork>::new(fork_url)
642            .maybe_max_retry(self.fork_retries)
643            .maybe_initial_backoff(self.fork_retry_backoff)
644            .maybe_headers(self.fork_headers.clone().or_else(|| self.rpc_headers.clone()))
645            .compute_units_per_second(self.get_compute_units_per_second())
646            .accept_invalid_certs(self.rpc_accept_invalid_certs)
647            .no_proxy(self.rpc_no_proxy);
648        if let Some(jwt) = &self.rpc_jwt {
649            builder = builder.jwt(jwt);
650        }
651        if let Some(timeout) = self.rpc_timeout {
652            builder = builder.timeout(std::time::Duration::from_secs(timeout));
653        }
654        builder.build_client()
655    }
656
657    /// Discovers and caches the network configuration and endpoint identity for a fork.
658    ///
659    /// This is the dispatch phase of fork setup: explicit network selections are preserved, while
660    /// inferred chain and network settings are applied when no override exists. The method does not
661    /// resolve or pin a fork block; block resolution happens during backend creation or through
662    /// [`Self::env_with_fork_context`]. Repeated calls only inspect the endpoint again as
663    /// described by [`Self::fork_endpoint_identity`].
664    pub async fn infer_network_from_fork(&mut self) -> eyre::Result<()> {
665        let previous_identity = self.fork_endpoint.clone();
666        let Some(fork_url) = self.fork_url.clone() else {
667            self.fork_endpoint = None;
668            self.expected_fork_endpoint = None;
669            if self.fork_network_is_inferred {
670                self.networks = self.networks.with_rpc_profile(NetworkConfigs::default());
671                self.fork_network_is_inferred = false;
672            }
673            if self.fork_chain_id_is_inferred {
674                self.env.chain_id = None;
675                self.fork_chain_id_is_inferred = false;
676            }
677            if self.fork_block_number_is_inferred {
678                self.fork_block_number = None;
679                self.fork_block_number_is_inferred = false;
680            }
681            return Ok(());
682        };
683        let explicit_network =
684            self.networks.has_network_selection() && !self.fork_network_is_inferred;
685        let identity = self.fork_endpoint_identity().await?;
686        self.ensure_expected_fork_endpoint(&identity)?;
687        if self.fork_network_is_inferred
688            && previous_identity.as_ref().is_some_and(|previous| {
689                previous.endpoint == fork_url
690                    && previous.network_profile != identity.network_profile
691            })
692        {
693            eyre::bail!(
694                "fork endpoint {} changed execution profile from `{}` to `{}`; rebuild \
695                 the EVM for the new network",
696                fork_endpoint_description(&fork_url),
697                self.networks.execution_profile_name(),
698                identity.network_profile.execution_profile_name()
699            );
700        }
701
702        if self.env.chain_id.is_none() || self.fork_chain_id_is_inferred {
703            self.env.chain_id = Some(identity.execution_chain_id);
704            self.fork_chain_id_is_inferred = true;
705        }
706        if !explicit_network {
707            self.networks = self.networks.with_rpc_profile(identity.network_profile);
708            self.fork_network_is_inferred = true;
709        }
710        debug_assert_eq!(identity.endpoint, fork_url);
711        self.fork_endpoint = Some(identity);
712        Ok(())
713    }
714
715    /// Discovers a stable identity snapshot without selecting a fork block.
716    ///
717    /// Each attempt reads `eth_chainId` and the optional Anvil identity methods before and after,
718    /// and returns only when both snapshots agree. Before Anvil is positively identified, a failed
719    /// `anvil_nodeInfo` probe is treated as absence of optional Anvil identity information: the
720    /// identity then depends on the chain ID alone and is returned from the first snapshot without
721    /// a confirming one. Later probe failures are strict. This method does not mutate or cache the
722    /// returned identity in `self`.
723    pub async fn discover_fork_endpoint(&self) -> eyre::Result<ForkEndpointIdentity> {
724        let fork_url = self.fork_url.as_deref().ok_or_eyre("fork URL is not configured")?;
725        let provider = self.fork_provider_with_url::<AnyNetwork>(fork_url)?;
726        let unknown_fallback = self.endpoint_network_fallback();
727        let mut node_info_probe = self.anvil_node_info_probe();
728        for _ in 0..3 {
729            let before_chain_id = provider
730                .get_chain_id()
731                .await
732                .wrap_err("failed to retrieve chain ID from fork endpoint")?;
733            let Some(before_node_info) = node_info_probe.request(&provider).await? else {
734                return Self::non_anvil_fork_endpoint_identity(
735                    fork_url,
736                    before_chain_id,
737                    Some(unknown_fallback),
738                );
739            };
740            let before = Self::resolve_fork_endpoint_identity(
741                &provider,
742                fork_url,
743                before_chain_id,
744                Some(before_node_info),
745                Some(unknown_fallback),
746                EndpointHardforkPolicy::Optional,
747            )
748            .await?;
749            let after_chain_id = provider
750                .get_chain_id()
751                .await
752                .wrap_err("failed to confirm chain ID from fork endpoint")?;
753            let after_node_info = node_info_probe.request(&provider).await?;
754            let after = Self::resolve_fork_endpoint_identity(
755                &provider,
756                fork_url,
757                after_chain_id,
758                after_node_info,
759                Some(unknown_fallback),
760                EndpointHardforkPolicy::Optional,
761            )
762            .await?;
763            if before_chain_id == after_chain_id && before == after {
764                return Ok(before);
765            }
766        }
767        eyre::bail!(
768            "fork endpoint {} changed while its identity was being resolved",
769            fork_endpoint_description(fork_url)
770        );
771    }
772
773    /// Returns the identity of the configured fork endpoint, inspecting it only when necessary.
774    ///
775    /// A cached discovery that found no Anvil identity is returned without new requests. Anvil
776    /// endpoints and endpoints without a cached discovery are inspected through
777    /// [`Self::discover_fork_endpoint`], so a reset or execution-profile change of an Anvil
778    /// endpoint is still observed.
779    pub async fn fork_endpoint_identity(&self) -> eyre::Result<ForkEndpointIdentity> {
780        let fork_url = self.fork_url.as_deref().ok_or_eyre("fork URL is not configured")?;
781        if let Some(execution_chain_id) =
782            self.discovered_non_anvil_chain_id(self.anvil_node_info_probe())
783        {
784            return Self::non_anvil_fork_endpoint_identity(
785                fork_url,
786                execution_chain_id,
787                Some(self.endpoint_network_fallback()),
788            );
789        }
790        self.discover_fork_endpoint().await
791    }
792
793    /// Reads one endpoint identity snapshot without performing a stability check.
794    ///
795    /// The shared node-info probe starts permissive for endpoints that do not expose Anvil methods
796    /// and becomes strict after Anvil is identified. Callers either bracket mutable remote reads
797    /// with two snapshots or use this helper to revalidate an already resolved fork. No request is
798    /// sent for an endpoint whose cached discovery found no Anvil identity.
799    async fn resolve_fork_endpoint_once<N: Network, P: Provider<N>>(
800        &self,
801        provider: &P,
802        node_info_probe: &mut AnvilNodeInfoProbe,
803        hardfork_policy: EndpointHardforkPolicy,
804    ) -> eyre::Result<ForkEndpointIdentity> {
805        let fork_url = self.fork_url.as_deref().ok_or_eyre("fork URL is not configured")?;
806        if let Some(execution_chain_id) = self.discovered_non_anvil_chain_id(*node_info_probe) {
807            return Self::non_anvil_fork_endpoint_identity(
808                fork_url,
809                execution_chain_id,
810                Some(self.endpoint_network_fallback()),
811            );
812        }
813        let cached_anvil = self.fork_endpoint.as_ref().is_some_and(|identity| {
814            identity.endpoint == fork_url && identity.reported_hardfork.is_some()
815        });
816        let node_info = node_info_probe.request(provider).await?;
817        let execution_chain_id = if cached_anvil && let Some(node_info) = &node_info {
818            node_info.environment.chain_id
819        } else {
820            provider
821                .get_chain_id()
822                .await
823                .wrap_err("failed to retrieve chain ID from fork endpoint")?
824        };
825        Self::resolve_fork_endpoint_identity(
826            provider,
827            fork_url,
828            execution_chain_id,
829            node_info,
830            Some(self.endpoint_network_fallback()),
831            hardfork_policy,
832        )
833        .await
834    }
835
836    /// Builds an identity from one observed chain ID and optional Anvil node-info response.
837    ///
838    /// Anvil metadata is consulted only after node info has positively identified the endpoint.
839    async fn resolve_fork_endpoint_identity<N: Network, P: Provider<N>>(
840        provider: &P,
841        endpoint: &str,
842        execution_chain_id: ChainId,
843        node_info: Option<NodeInfo>,
844        unknown_fallback: Option<NetworkConfigs>,
845        hardfork_policy: EndpointHardforkPolicy,
846    ) -> eyre::Result<ForkEndpointIdentity> {
847        match node_info {
848            Some(node_info) => {
849                let (
850                    source_chain_id,
851                    instance_id,
852                    source_fork_block_number,
853                    source_fork_block_hash,
854                ) = match provider.raw_request::<_, Metadata>("anvil_metadata".into(), ()).await {
855                    Ok(metadata) => {
856                        let forked_network = metadata.forked_network;
857                        (
858                            forked_network.map(|fork| fork.chain_id).unwrap_or(execution_chain_id),
859                            Some(metadata.instance_id),
860                            forked_network.map(|fork| fork.fork_block_number),
861                            forked_network.map(|fork| fork.fork_block_hash),
862                        )
863                    }
864                    Err(error) if is_rpc_method_not_found(&error) => {
865                        (execution_chain_id, None, None, None)
866                    }
867                    Err(error) => {
868                        return Err(error)
869                            .wrap_err("failed to retrieve Anvil fork source identity");
870                    }
871                };
872                let identity_chain_id =
873                    if node_info.network.is_some() { execution_chain_id } else { source_chain_id };
874                let network_profile = NetworkConfigs::from_rpc_identity_profile_with_fallback(
875                    identity_chain_id,
876                    Some(node_info.network.as_deref()),
877                    unknown_fallback,
878                )
879                .map_err(eyre::Report::msg)?
880                .ok_or_else(|| {
881                    eyre::eyre!("Anvil metadata did not identify an execution profile")
882                })?;
883                let network = network_profile.execution_network();
884                let hardfork = endpoint_hardfork(network, &node_info.hard_fork, hardfork_policy)?;
885
886                Ok(ForkEndpointIdentity {
887                    endpoint: endpoint.to_string(),
888                    execution_chain_id,
889                    source_chain_id,
890                    network,
891                    network_profile,
892                    reported_hardfork: Some(node_info.hard_fork),
893                    hardfork,
894                    instance_id,
895                    source_fork_block_number,
896                    source_fork_block_hash,
897                })
898            }
899            None => Self::non_anvil_fork_endpoint_identity(
900                endpoint,
901                execution_chain_id,
902                unknown_fallback,
903            ),
904        }
905    }
906
907    /// Builds the identity of an endpoint that exposes no Anvil node info from its chain ID.
908    fn non_anvil_fork_endpoint_identity(
909        endpoint: &str,
910        execution_chain_id: ChainId,
911        unknown_fallback: Option<NetworkConfigs>,
912    ) -> eyre::Result<ForkEndpointIdentity> {
913        let network_profile = NetworkConfigs::from_rpc_identity_profile_with_fallback(
914            execution_chain_id,
915            None,
916            unknown_fallback,
917        )
918        .map_err(eyre::Report::msg)?
919        .ok_or_else(|| {
920            eyre::eyre!(
921                "cannot determine network family for unknown chain ID \
922                 {execution_chain_id}: the fork endpoint does not expose `anvil_nodeInfo`"
923            )
924        })?;
925        Ok(ForkEndpointIdentity {
926            endpoint: endpoint.to_string(),
927            execution_chain_id,
928            source_chain_id: execution_chain_id,
929            network: network_profile.execution_network(),
930            network_profile,
931            reported_hardfork: None,
932            hardfork: None,
933            instance_id: None,
934            source_fork_block_number: None,
935            source_fork_block_hash: None,
936        })
937    }
938
939    /// Returns standalone execution environments and the remote source context, if any.
940    ///
941    /// The environment carries the network's default spec; resolve the execution spec with
942    /// [`resolve_execution_spec`]. The request holds the transaction defaults: sender, gas price,
943    /// gas limit and, when forking, the chain ID.
944    ///
945    /// Execution workflows with a backend use its selected block through `Backend::env`.
946    pub async fn env_with_fork_context<FEN: FoundryEvmNetwork>(
947        &self,
948    ) -> eyre::Result<(EvmEnvFor<FEN>, TransactionRequestFor<FEN>, Option<ForkContext>)> {
949        let Some(fork_url) = &self.fork_url else {
950            return Ok((self.local_evm_env::<FEN>(), self.local_tx_request::<FEN>(), None));
951        };
952        let provider = self.fork_provider_with_url::<AnyNetwork>(fork_url)?;
953        let target = self.fork_block_number.map_or(BlockNumberOrTag::Latest, Into::into);
954        let mut node_info_probe = self.anvil_node_info_probe();
955        for _ in 0..3 {
956            let (block, _, context) = self
957                .resolve_fork_block_with_context(&provider, target, &mut node_info_probe)
958                .await?;
959            let gas_price =
960                option_try_or_else(self.env.gas_price.map(|value| value as u128), async || {
961                    provider.get_gas_price().await
962                })
963                .await?;
964            let identity = self
965                .resolve_fork_endpoint_once(
966                    &provider,
967                    &mut node_info_probe,
968                    EndpointHardforkPolicy::Required,
969                )
970                .await?;
971            self.ensure_expected_fork_endpoint(&identity)?;
972            if context.matches_identity(&identity) {
973                let chain_id = self.chain_id_override().unwrap_or(context.execution_chain_id);
974                let env = self.fork_env_from_block::<FEN, AnyNetwork>(
975                    chain_id,
976                    context.source_chain_id,
977                    &block,
978                );
979                let tx = self.fork_tx_request::<FEN>(gas_price, chain_id);
980                return Ok((env, tx, Some(context)));
981            }
982        }
983        eyre::bail!(
984            "fork endpoint {} changed while its EVM and transaction environments were being \
985             resolved",
986            fork_endpoint_description(fork_url)
987        );
988    }
989
990    /// Returns the EVM environment and transaction defaults at an already resolved fork.
991    pub(crate) async fn env_at_fork<FEN: FoundryEvmNetwork>(
992        &self,
993        fork: Option<&Fork>,
994    ) -> eyre::Result<(EvmEnvFor<FEN>, TransactionRequestFor<FEN>)> {
995        let Some(_) = &self.fork_url else {
996            eyre::ensure!(fork.is_none(), "resolved fork provided without a configured fork");
997            return Ok((self.local_evm_env::<FEN>(), self.local_tx_request::<FEN>()));
998        };
999        let fork = fork.ok_or_else(|| eyre::eyre!("fork must be resolved"))?;
1000        let provider = self.provider_for_fork::<AnyNetwork>(fork)?;
1001        self.check_fork_endpoint(&provider, fork).await?;
1002        let context = fork.context();
1003        let chain_id = self.chain_id_override().unwrap_or(context.execution_chain_id);
1004        let env = self.fork_env_from_block::<FEN, AnyNetwork>(
1005            chain_id,
1006            context.source_chain_id,
1007            &fork.block,
1008        );
1009        let gas_price =
1010            option_try_or_else(self.env.gas_price.map(|value| value as u128), async || {
1011                provider.get_gas_price().await
1012            })
1013            .await?;
1014        self.check_fork_endpoint(&provider, fork).await?;
1015        Ok((env, self.fork_tx_request::<FEN>(gas_price, chain_id)))
1016    }
1017
1018    fn fork_env_error_context(&self) -> String {
1019        let mut message = "could not instantiate forked environment".to_string();
1020        if let Some(fork_url) = self.fork_url.as_deref()
1021            && let Ok(url) = Url::parse(fork_url)
1022            && let Some(host) = url.host()
1023        {
1024            write!(message, " with provider {host}").unwrap();
1025        }
1026        message
1027    }
1028
1029    async fn resolve_fork_block_with_context<N: Network, P: Provider<N>>(
1030        &self,
1031        provider: &P,
1032        target: BlockNumberOrTag,
1033        node_info_probe: &mut AnvilNodeInfoProbe,
1034    ) -> eyre::Result<(N::BlockResponse, BlockNumHash, ForkContext)> {
1035        let endpoint = self.fork_url.as_deref().unwrap_or_default();
1036        let mut stable = None;
1037        for _ in 0..3 {
1038            let before = self
1039                .resolve_fork_endpoint_once(
1040                    provider,
1041                    node_info_probe,
1042                    EndpointHardforkPolicy::Required,
1043                )
1044                .await
1045                .wrap_err_with(|| self.fork_env_error_context())?;
1046            let block = provider
1047                .get_block_by_number(target)
1048                .await
1049                .wrap_err_with(|| self.fork_env_error_context())?;
1050            let after = self
1051                .resolve_fork_endpoint_once(
1052                    provider,
1053                    node_info_probe,
1054                    EndpointHardforkPolicy::Required,
1055                )
1056                .await
1057                .wrap_err_with(|| self.fork_env_error_context())?;
1058            if before == after {
1059                stable = Some((before, block));
1060                break;
1061            }
1062        }
1063        let (identity, block) = stable.ok_or_else(|| {
1064            eyre::eyre!(
1065                "fork endpoint {} changed while its block and execution context were being \
1066                 resolved",
1067                fork_endpoint_description(endpoint)
1068            )
1069        })?;
1070        self.ensure_expected_fork_endpoint(&identity)?;
1071        self.ensure_inferred_execution_profile(&identity)?;
1072
1073        let block = if let Some(block) = block {
1074            block
1075        } else {
1076            let block_number_message = match target {
1077                BlockNumberOrTag::Number(block_number) => {
1078                    format!("block number: {block_number}")
1079                }
1080                block_number => format!("{block_number} block"),
1081            };
1082            let latest_message = if let Ok(latest_block) = provider.get_block_number().await {
1083                if let Some(block_number) = self.fork_block_number
1084                    && block_number <= latest_block
1085                {
1086                    error!("{NON_ARCHIVE_NODE_WARNING}");
1087                }
1088                format!("; latest block number: {latest_block}")
1089            } else {
1090                Default::default()
1091            };
1092            eyre::bail!("failed to get {block_number_message}{latest_message}");
1093        };
1094        let actual = BlockNumHash::new(block.header().number(), block.header().hash());
1095
1096        let context = ForkContext {
1097            execution_chain_id: identity.execution_chain_id,
1098            source_chain_id: identity.source_chain_id,
1099            network: identity.network,
1100            network_profile: identity.network_profile,
1101            block_number: actual.number,
1102            hardfork: identity.hardfork,
1103            instance_id: identity.instance_id,
1104            source_fork_block_number: identity.source_fork_block_number,
1105            source_fork_block_hash: identity.source_fork_block_hash,
1106        };
1107        Ok((block, actual, context))
1108    }
1109
1110    /// Returns the environment of a fork at `block`, with the network's default spec.
1111    pub(crate) fn fork_env_from_block<FEN: FoundryEvmNetwork, N: Network>(
1112        &self,
1113        chain_id: ChainId,
1114        source_chain_id: ChainId,
1115        block: &N::BlockResponse,
1116    ) -> EvmEnvFor<FEN> {
1117        let spec = SpecFor::<FEN>::default();
1118        let mut evm_env = EvmEnv::new(
1119            spec,
1120            self.version(EvmFactoryFor::<FEN>::default().version(spec, chain_id)),
1121            block_env_from_header::<TypesFor<FEN>>(block.header()),
1122        );
1123        apply_chain_and_block_specific_env_changes_for_chain::<N, _>(
1124            &mut evm_env,
1125            block,
1126            source_chain_id,
1127            self.networks,
1128        );
1129        evm_env
1130    }
1131
1132    /// Returns the environment configured with only local settings, with the network's default
1133    /// spec.
1134    pub fn local_evm_env<FEN: FoundryEvmNetwork>(&self) -> EvmEnvFor<FEN> {
1135        let spec = SpecFor::<FEN>::default();
1136        let chain_id = self.env.chain_id.unwrap_or(foundry_common::DEV_CHAIN_ID);
1137        let block = BlockEnv::<TypesFor<FEN>> {
1138            number: self.env.block_number,
1139            beneficiary: self.env.block_coinbase,
1140            timestamp: self.env.block_timestamp,
1141            difficulty: U256::from(self.env.block_difficulty),
1142            prevrandao: self.env.block_prevrandao.into(),
1143            basefee: U256::from(self.env.block_base_fee_per_gas),
1144            gas_limit: U256::from(self.gas_limit()),
1145            ..Default::default()
1146        };
1147        EvmEnv::new(
1148            spec,
1149            self.version(EvmFactoryFor::<FEN>::default().version(spec, chain_id)),
1150            block,
1151        )
1152    }
1153
1154    /// Returns the transaction defaults with gas price and chain ID from a stable fork snapshot.
1155    fn fork_tx_request<FEN: FoundryEvmNetwork>(
1156        &self,
1157        gas_price: u128,
1158        chain_id: ChainId,
1159    ) -> TransactionRequestFor<FEN> {
1160        let mut tx = TransactionRequestFor::<FEN>::default();
1161        tx.set_from(self.sender);
1162        tx.set_chain_id(chain_id);
1163        tx.set_gas_price(gas_price);
1164        tx.set_gas_limit(self.gas_limit());
1165        tx
1166    }
1167
1168    /// Returns the transaction defaults configured from local settings only.
1169    pub fn local_tx_request<FEN: FoundryEvmNetwork>(&self) -> TransactionRequestFor<FEN> {
1170        let mut tx = TransactionRequestFor::<FEN>::default();
1171        tx.set_from(self.sender);
1172        tx.set_gas_price(self.env.gas_price.unwrap_or_default().into());
1173        tx.set_gas_limit(self.gas_limit());
1174        tx
1175    }
1176
1177    /// Applies Foundry's execution policy to a network's default runtime `version`.
1178    pub fn version(&self, mut version: Version) -> Version {
1179        version.memory_limit = self.memory_limit;
1180        version.max_code_size = self.env.code_size_limit.unwrap_or(usize::MAX);
1181        version.max_initcode_size = version.max_code_size.saturating_mul(2);
1182        // EIP-3607 rejects transactions from senders with deployed code.
1183        // If EIP-3607 is enabled it can cause issues during fuzz/invariant tests if the caller
1184        // is a contract. So we disable the check by default.
1185        version.features.remove(EvmFeatures::EIP3607 | EvmFeatures::NONCE_CHECK);
1186        version.features.set(EvmFeatures::BLOCK_GAS_LIMIT_CHECK, !self.disable_block_gas_limit);
1187        // By default do not enforce transaction gas limits imposed by Osaka (EIP-7825) and
1188        // Amsterdam (EIP-8037).
1189        // Users can opt-in to enable these limits by setting `enable_tx_gas_limit` to true.
1190        if !self.enable_tx_gas_limit {
1191            version.tx_gas_limit_cap = u64::MAX;
1192            version.tx_total_gas_cap = u64::MAX;
1193        }
1194        version
1195    }
1196
1197    /// Helper function that returns the [CreateFork] to use, if any.
1198    ///
1199    /// storage caching for the [CreateFork] will be enabled if
1200    ///   - `fork_url` is present
1201    ///   - `fork_block_number` is present
1202    ///   - `StorageCachingConfig` allows the `fork_url` + source chain ID pair
1203    ///   - storage is allowed (`no_storage_caching = false`)
1204    ///
1205    /// If all these criteria are met, then storage caching is enabled and storage info will be
1206    /// written to `<Config::foundry_cache_dir()>/<str(chainid)>/<block>/storage.json`.
1207    ///
1208    /// for `mainnet` and `--fork-block-number 14435000` on mac the corresponding storage cache will
1209    /// be at `~/.foundry/cache/mainnet/14435000/storage.json`.
1210    /// `fork_block_number` is the actual block number to pin the fork to. This must be the
1211    /// real chain block number, not a remapped value. On some L2s (e.g., Arbitrum)
1212    /// `block_env.number` is remapped to the L1 block number, so callers must pass the
1213    /// block number in the context returned by [`EvmOpts::env_with_fork_context`] instead.
1214    ///
1215    /// RPC storage caching uses the source chain ID of the discovered fork endpoint. Discover the
1216    /// endpoint first, for example with [`EvmOpts::infer_network_from_fork`]. Without it,
1217    /// `chain_id` decides caching.
1218    pub fn get_fork(
1219        &self,
1220        config: &Config,
1221        chain_id: u64,
1222        fork_block_number: Option<BlockNumber>,
1223    ) -> Option<CreateFork> {
1224        let url = self.fork_url.clone()?;
1225        let source_chain_id =
1226            self.fork_endpoint.as_ref().map_or(chain_id, |identity| identity.source_chain_id);
1227        let enable_caching = config.enable_caching(&url, source_chain_id);
1228
1229        // A supplied RPC block number is part of this creation request.
1230        let mut evm_opts = self.clone();
1231        if evm_opts.fork_block_number.is_none() {
1232            evm_opts.fork_block_number = fork_block_number;
1233            evm_opts.fork_block_number_is_inferred = fork_block_number.is_some();
1234        }
1235
1236        Some(CreateFork { url, enable_caching, evm_opts })
1237    }
1238
1239    /// Returns the gas limit to use
1240    pub fn gas_limit(&self) -> u64 {
1241        self.env.block_gas_limit.unwrap_or(self.env.gas_limit).0
1242    }
1243
1244    /// Returns the available compute units per second, which will be
1245    /// - u64::MAX, if `no_rpc_rate_limit` if set (as rate limiting is disabled)
1246    /// - the assigned compute units, if `compute_units_per_second` is set
1247    /// - ALCHEMY_FREE_TIER_CUPS (330) otherwise
1248    const fn get_compute_units_per_second(&self) -> u64 {
1249        if self.no_rpc_rate_limit {
1250            u64::MAX
1251        } else if let Some(cups) = self.compute_units_per_second {
1252            cups
1253        } else {
1254            ALCHEMY_FREE_TIER_CUPS
1255        }
1256    }
1257
1258    /// Returns the chain ID from the RPC, if any.
1259    pub async fn get_remote_chain_id(&self) -> Option<Chain> {
1260        if let Some(url) = &self.fork_url
1261            && let Ok(provider) = self.fork_provider_with_url::<AnyNetwork>(url)
1262        {
1263            trace!(?url, "retrieving chain via eth_chainId");
1264
1265            if let Ok(id) = provider.get_chain_id().await {
1266                return Some(Chain::from(id));
1267            }
1268        }
1269
1270        None
1271    }
1272}
1273
1274/// Describes how an execution spec should use a source chain's hardfork schedule.
1275#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1276pub enum ExecutionSpecContext {
1277    /// Local execution without a fork.
1278    Local,
1279    /// Local execution backed by a fork.
1280    Fork {
1281        /// Underlying source chain ID.
1282        source_chain_id: ChainId,
1283        /// Exact hardfork reported by the endpoint.
1284        endpoint_hardfork: Option<FoundryHardfork>,
1285    },
1286    /// Local script execution backed by a fork whose transactions are sent to the source chain.
1287    Script {
1288        /// Underlying source chain ID.
1289        source_chain_id: ChainId,
1290        /// Exact hardfork reported by the endpoint.
1291        endpoint_hardfork: Option<FoundryHardfork>,
1292    },
1293    /// Historical execution whose semantics must match the source block.
1294    Historical {
1295        /// Underlying source chain ID.
1296        source_chain_id: ChainId,
1297        /// Exact hardfork reported by the endpoint.
1298        endpoint_hardfork: Option<FoundryHardfork>,
1299    },
1300}
1301
1302impl ExecutionSpecContext {
1303    /// Returns a local fork execution context.
1304    pub const fn fork(
1305        source_chain_id: ChainId,
1306        endpoint_hardfork: Option<FoundryHardfork>,
1307    ) -> Self {
1308        Self::Fork { source_chain_id, endpoint_hardfork }
1309    }
1310
1311    /// Returns the context for an optional local fork source.
1312    pub const fn local_or_fork(
1313        source_chain_id: Option<ChainId>,
1314        endpoint_hardfork: Option<FoundryHardfork>,
1315    ) -> Self {
1316        if let Some(source_chain_id) = source_chain_id {
1317            Self::Fork { source_chain_id, endpoint_hardfork }
1318        } else {
1319            Self::Local
1320        }
1321    }
1322
1323    /// Returns the context for script execution with an optional fork source.
1324    pub const fn local_or_script(
1325        source_chain_id: Option<ChainId>,
1326        endpoint_hardfork: Option<FoundryHardfork>,
1327    ) -> Self {
1328        if let Some(source_chain_id) = source_chain_id {
1329            Self::Script { source_chain_id, endpoint_hardfork }
1330        } else {
1331            Self::Local
1332        }
1333    }
1334
1335    /// Returns a historical execution context.
1336    pub const fn historical(
1337        source_chain_id: ChainId,
1338        endpoint_hardfork: Option<FoundryHardfork>,
1339    ) -> Self {
1340        Self::Historical { source_chain_id, endpoint_hardfork }
1341    }
1342
1343    fn hardfork<SPEC: ExecutionSpec>(
1344        self,
1345        timestamp: u64,
1346        configured: SPEC,
1347    ) -> Option<FoundryHardfork> {
1348        match self {
1349            Self::Local => None,
1350            Self::Fork { source_chain_id, endpoint_hardfork } => {
1351                SPEC::fork_hardfork(source_chain_id, timestamp, endpoint_hardfork)
1352            }
1353            Self::Script { source_chain_id, endpoint_hardfork } => SPEC::script_fork_hardfork(
1354                source_chain_id,
1355                timestamp,
1356                endpoint_hardfork,
1357                configured,
1358            ),
1359            Self::Historical { source_chain_id, endpoint_hardfork } => endpoint_hardfork
1360                .filter(|&hardfork| SPEC::from_foundry_hardfork(hardfork).is_some())
1361                .or_else(|| SPEC::historical_hardfork(source_chain_id, timestamp)),
1362        }
1363    }
1364}
1365
1366/// Resolves and applies the execution spec for an EVM environment.
1367///
1368/// A direct caller override takes precedence over a configured namespaced hardfork, followed by
1369/// exact endpoint metadata and the hardfork selected from the source schedule. Local Ethereum
1370/// forks retain Foundry's configured EVM version unless a script's source chain is ahead of it,
1371/// namespaced local networks follow their source identity, and historical execution always
1372/// follows the source block's identity.
1373///
1374/// Changing the spec keeps Foundry's execution policy (see
1375/// [`FoundryEvmFactory::env_with_spec`]).
1376///
1377/// Returns the exact namespaced hardfork, when applicable, so execution and trace decoding can use
1378/// the same hardfork.
1379pub fn resolve_execution_spec<F: FoundryEvmFactory>(
1380    evm_version: EvmVersion,
1381    configured_hardfork: Option<FoundryHardfork>,
1382    evm_env: &mut EvmEnv<F::Types>,
1383    context: ExecutionSpecContext,
1384    explicit_spec: Option<SpecOf<F>>,
1385) -> Option<FoundryHardfork> {
1386    let configured_spec = evm_spec_id::<SpecOf<F>>(evm_version);
1387    let (spec, hardfork) = if let Some(spec) = explicit_spec {
1388        (spec, spec.reported_hardfork())
1389    } else if let Some((hardfork, spec)) = configured_hardfork
1390        .filter(|&hardfork| SpecOf::<F>::from_foundry_hardfork(hardfork).is_some())
1391        .or_else(|| context.hardfork(evm_env.block.timestamp.saturating_to(), configured_spec))
1392        .and_then(|hardfork| {
1393            SpecOf::<F>::from_foundry_hardfork(hardfork).map(|spec| (hardfork, spec))
1394        })
1395    {
1396        (spec, Some(hardfork))
1397    } else {
1398        (configured_spec, configured_spec.reported_hardfork())
1399    };
1400    *evm_env = F::default().env_with_spec(*evm_env, spec);
1401    hardfork
1402}
1403
1404#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1405pub struct Env {
1406    /// The block gas limit.
1407    pub gas_limit: GasLimit,
1408
1409    /// The `CHAINID` opcode value.
1410    pub chain_id: Option<u64>,
1411
1412    /// the tx.gasprice value during EVM execution
1413    ///
1414    /// This is an Option, so we can determine in fork mode whether to use the config's gas price
1415    /// (if set by user) or the remote client's gas price.
1416    #[serde(default, skip_serializing_if = "Option::is_none")]
1417    pub gas_price: Option<u64>,
1418
1419    /// the base fee in a block
1420    pub block_base_fee_per_gas: u64,
1421
1422    /// the tx.origin value during EVM execution
1423    pub tx_origin: Address,
1424
1425    /// the block.coinbase value during EVM execution
1426    pub block_coinbase: Address,
1427
1428    /// the block.timestamp value during EVM execution
1429    #[serde(
1430        deserialize_with = "foundry_config::deserialize_u64_to_u256",
1431        serialize_with = "foundry_config::serialize_u64_or_u256"
1432    )]
1433    pub block_timestamp: U256,
1434
1435    /// the block.number value during EVM execution"
1436    #[serde(
1437        deserialize_with = "foundry_config::deserialize_u64_to_u256",
1438        serialize_with = "foundry_config::serialize_u64_or_u256"
1439    )]
1440    pub block_number: U256,
1441
1442    /// the block.difficulty value during EVM execution
1443    pub block_difficulty: u64,
1444
1445    /// Previous block beacon chain random value. Before merge this field is used for mix_hash
1446    pub block_prevrandao: B256,
1447
1448    /// the block.gaslimit value during EVM execution
1449    #[serde(default, skip_serializing_if = "Option::is_none")]
1450    pub block_gas_limit: Option<GasLimit>,
1451
1452    /// EIP-170: Contract code size limit in bytes. Useful to increase this because of tests.
1453    #[serde(default, skip_serializing_if = "Option::is_none")]
1454    pub code_size_limit: Option<usize>,
1455}
1456
1457fn fork_endpoint_description(endpoint: &str) -> String {
1458    Url::parse(endpoint)
1459        .ok()
1460        .and_then(|url| url.host_str().map(|host| format!("provider {host}")))
1461        .unwrap_or_else(|| "configured provider".to_string())
1462}
1463
1464async fn option_try_or_else<T, E>(
1465    option: Option<T>,
1466    f: impl AsyncFnOnce() -> Result<T, E>,
1467) -> Result<T, E> {
1468    if let Some(value) = option { Ok(value) } else { f().await }
1469}
1470
1471#[cfg(test)]
1472mod tests {
1473    use super::*;
1474    use crate::evm::EthEvmNetwork;
1475    use alloy_chains::NamedChain;
1476    use alloy_primitives::bytes;
1477    use alloy_rpc_types::TransactionRequest;
1478    use alloy_serde::WithOtherFields;
1479    use foundry_evm_hardforks::EthereumHardfork;
1480    use foundry_test_utils::rpc::{
1481        spawn_rpc_proxy_internal_error_after, spawn_rpc_proxy_method_not_found_before,
1482        spawn_rpc_proxy_recording_method, spawn_rpc_proxy_rejecting_method_after,
1483    };
1484
1485    #[cfg(feature = "base")]
1486    use foundry_evm_hardforks::BaseUpgrade;
1487
1488    #[cfg(feature = "monad")]
1489    use crate::evm::MonadEvmNetwork;
1490    #[cfg(feature = "optimism")]
1491    use crate::evm::OpEvmNetwork;
1492
1493    fn resolved_context(block_number: BlockNumber) -> ForkContext {
1494        ForkContext {
1495            execution_chain_id: 1,
1496            source_chain_id: 1,
1497            network: NetworkVariant::Ethereum,
1498            network_profile: NetworkConfigs::default(),
1499            block_number,
1500            hardfork: None,
1501            instance_id: None,
1502            source_fork_block_number: None,
1503            source_fork_block_hash: None,
1504        }
1505    }
1506
1507    #[test]
1508    fn fork_endpoint_description_redacts_credentials_and_paths() {
1509        let endpoint = "https://user:secret@example.com/v2/private-api-key?token=another-secret";
1510        let description = fork_endpoint_description(endpoint);
1511
1512        assert_eq!(description, "provider example.com");
1513        assert!(!description.contains("secret"));
1514        assert!(!description.contains("private-api-key"));
1515    }
1516
1517    #[test]
1518    fn endpoint_network_fallback_preserves_explicit_selection() {
1519        let default = EvmOpts::default().endpoint_network_fallback();
1520        assert!(!default.has_network_selection());
1521
1522        let explicit = EvmOpts { networks: NetworkConfigs::with_ethereum(), ..Default::default() }
1523            .endpoint_network_fallback();
1524        assert!(explicit.has_network_selection());
1525        assert_eq!(explicit.execution_network(), NetworkVariant::Ethereum);
1526    }
1527
1528    #[test]
1529    fn backend_target_matches_number_pinned_fork_identity() {
1530        let context = ForkContext {
1531            execution_chain_id: 1,
1532            source_chain_id: 1,
1533            network: NetworkVariant::Ethereum,
1534            network_profile: NetworkConfigs::default(),
1535            block_number: 10,
1536            hardfork: None,
1537            instance_id: None,
1538            source_fork_block_number: None,
1539            source_fork_block_hash: None,
1540        };
1541
1542        let mut different_number = context;
1543        different_number.block_number += 1;
1544        assert!(!context.has_same_backend_target(different_number));
1545
1546        let mut different_profile = context;
1547        different_profile.network_profile = NetworkConfigs::with_celo();
1548        assert!(!context.has_same_backend_target(different_profile));
1549
1550        let mut different_hardfork = context;
1551        different_hardfork.hardfork =
1552            Some(FoundryHardfork::Ethereum(foundry_evm_hardforks::EthereumHardfork::Prague));
1553        assert!(!context.has_same_backend_target(different_hardfork));
1554
1555        let mut different_instance = context;
1556        different_instance.instance_id = Some(B256::with_last_byte(3));
1557        assert!(!context.has_same_backend_target(different_instance));
1558    }
1559
1560    #[tokio::test]
1561    async fn expected_fork_endpoint_requires_exact_identity() {
1562        let identity = ForkEndpointIdentity {
1563            endpoint: "http://localhost:8545".to_string(),
1564            execution_chain_id: 1,
1565            source_chain_id: 1,
1566            network: NetworkVariant::Ethereum,
1567            network_profile: NetworkConfigs::default(),
1568            reported_hardfork: Some("Prague".to_string()),
1569            hardfork: Some(FoundryHardfork::Ethereum(
1570                foundry_evm_hardforks::EthereumHardfork::Prague,
1571            )),
1572            instance_id: Some(B256::with_last_byte(1)),
1573            source_fork_block_number: None,
1574            source_fork_block_hash: None,
1575        };
1576        let mut evm_opts = EvmOpts::default();
1577        evm_opts.expect_fork_endpoint(identity.clone(), true);
1578
1579        assert!(evm_opts.ensure_expected_fork_endpoint(&identity).is_ok());
1580        assert_eq!(evm_opts.fork_endpoint, Some(identity.clone()));
1581        assert_eq!(evm_opts.expected_fork_endpoint, Some(identity.clone()));
1582        assert!(evm_opts.fork_network_is_inferred);
1583
1584        let mut changed_instance = identity.clone();
1585        changed_instance.instance_id = Some(B256::with_last_byte(2));
1586        assert!(evm_opts.ensure_expected_fork_endpoint(&changed_instance).is_err());
1587
1588        let mut changed_unknown_hardfork = identity;
1589        changed_unknown_hardfork.reported_hardfork = Some("Future".to_string());
1590        changed_unknown_hardfork.hardfork = None;
1591        assert!(evm_opts.ensure_expected_fork_endpoint(&changed_unknown_hardfork).is_err());
1592
1593        evm_opts.infer_network_from_fork().await.unwrap();
1594        assert_eq!(evm_opts.fork_endpoint, None);
1595        assert_eq!(evm_opts.expected_fork_endpoint, None);
1596    }
1597
1598    #[test]
1599    fn fork_expected_anvil_identity_seeds_strict_node_info_probe() {
1600        let authoritative = ForkEndpointIdentity {
1601            endpoint: "http://localhost:8545".to_string(),
1602            execution_chain_id: 1,
1603            source_chain_id: 1,
1604            network: NetworkVariant::Ethereum,
1605            network_profile: NetworkConfigs::default(),
1606            reported_hardfork: Some("Prague".to_string()),
1607            hardfork: Some(FoundryHardfork::Ethereum(
1608                foundry_evm_hardforks::EthereumHardfork::Prague,
1609            )),
1610            instance_id: Some(B256::with_last_byte(1)),
1611            source_fork_block_number: None,
1612            source_fork_block_hash: None,
1613        };
1614        let mut anonymous = authoritative.clone();
1615        anonymous.reported_hardfork = None;
1616        anonymous.hardfork = None;
1617        anonymous.instance_id = None;
1618        let mut evm_opts = EvmOpts {
1619            fork_url: Some(authoritative.endpoint.clone()),
1620            fork_endpoint: Some(anonymous),
1621            expected_fork_endpoint: Some(authoritative),
1622            ..Default::default()
1623        };
1624
1625        assert!(evm_opts.anvil_node_info_probe().identified);
1626
1627        evm_opts.fork_url = Some("http://localhost:9545".to_string());
1628        assert!(!evm_opts.anvil_node_info_probe().identified);
1629    }
1630
1631    #[test]
1632    fn selecting_new_fork_url_clears_only_endpoint_derived_state() {
1633        let identity = ForkEndpointIdentity {
1634            endpoint: "http://localhost:8545".to_string(),
1635            execution_chain_id: 42,
1636            source_chain_id: 42,
1637            network: NetworkVariant::Ethereum,
1638            network_profile: NetworkConfigs::with_celo(),
1639            reported_hardfork: None,
1640            hardfork: None,
1641            instance_id: None,
1642            source_fork_block_number: None,
1643            source_fork_block_hash: None,
1644        };
1645        let mut inferred = EvmOpts {
1646            fork_url: Some(identity.endpoint.clone()),
1647            fork_block_number: Some(123),
1648            fork_endpoint: Some(identity.clone()),
1649            expected_fork_endpoint: Some(identity.clone()),
1650            networks: identity.network_profile,
1651            fork_network_is_inferred: true,
1652            fork_chain_id_is_inferred: true,
1653            fork_block_number_is_inferred: true,
1654            ..Default::default()
1655        };
1656        inferred.env.chain_id = Some(identity.execution_chain_id);
1657
1658        inferred.set_fork_url("http://localhost:9545".to_string());
1659
1660        assert_eq!(inferred.fork_url.as_deref(), Some("http://localhost:9545"));
1661        assert_eq!(inferred.fork_block_number, None);
1662        assert_eq!(inferred.fork_endpoint, None);
1663        assert_eq!(inferred.expected_fork_endpoint, None);
1664        assert_eq!(inferred.networks, NetworkConfigs::default());
1665        assert_eq!(inferred.env.chain_id, None);
1666        assert!(!inferred.fork_network_is_inferred);
1667        assert!(!inferred.fork_chain_id_is_inferred);
1668        assert!(!inferred.fork_block_number_is_inferred);
1669
1670        let mut explicit = EvmOpts {
1671            fork_url: Some(identity.endpoint.clone()),
1672            fork_block_number: Some(123),
1673            fork_endpoint: Some(identity.clone()),
1674            expected_fork_endpoint: Some(identity),
1675            networks: NetworkConfigs::with_celo(),
1676            ..Default::default()
1677        };
1678        explicit.env.chain_id = Some(42);
1679
1680        explicit.set_fork_url("http://localhost:9545".to_string());
1681
1682        assert_eq!(explicit.networks, NetworkConfigs::with_celo());
1683        assert_eq!(explicit.env.chain_id, Some(42));
1684        assert_eq!(explicit.fork_block_number, Some(123));
1685        assert_eq!(explicit.fork_endpoint, None);
1686        assert_eq!(explicit.expected_fork_endpoint, None);
1687        assert!(!explicit.fork_block_number_is_inferred);
1688    }
1689
1690    #[test]
1691    fn changed_fork_auth_clears_only_endpoint_derived_state() {
1692        let endpoint = "http://localhost:8545";
1693        let identity = ForkEndpointIdentity {
1694            endpoint: endpoint.to_string(),
1695            execution_chain_id: 42,
1696            source_chain_id: 42,
1697            network: NetworkVariant::Ethereum,
1698            network_profile: NetworkConfigs::with_celo(),
1699            reported_hardfork: None,
1700            hardfork: None,
1701            instance_id: Some(B256::with_last_byte(1)),
1702            source_fork_block_number: None,
1703            source_fork_block_hash: None,
1704        };
1705        let context = ForkContext {
1706            execution_chain_id: identity.execution_chain_id,
1707            source_chain_id: identity.source_chain_id,
1708            network: identity.network,
1709            network_profile: identity.network_profile,
1710            block_number: 123,
1711            hardfork: identity.hardfork,
1712            instance_id: identity.instance_id,
1713            source_fork_block_number: identity.source_fork_block_number,
1714            source_fork_block_hash: identity.source_fork_block_hash,
1715        };
1716        let mut evm_opts = EvmOpts {
1717            fork_url: Some(endpoint.to_string()),
1718            fork_block_number: Some(123),
1719            fork_headers: Some(vec!["Authorization: first".to_string()]),
1720            rpc_jwt: Some("first-jwt".to_string()),
1721            fork_endpoint: Some(identity.clone()),
1722            expected_fork_endpoint: Some(identity),
1723            networks: NetworkConfigs::with_celo(),
1724            ..Default::default()
1725        };
1726        evm_opts.env.chain_id = Some(42);
1727        let fork = evm_opts.test_fork(
1728            endpoint,
1729            BlockNumHash::new(context.block_number, B256::with_last_byte(2)),
1730            context,
1731        );
1732
1733        evm_opts.fork_headers = Some(vec!["Authorization: second".to_string()]);
1734        evm_opts.rpc_jwt = Some("second-jwt".to_string());
1735
1736        assert!(evm_opts.invalidate_fork_endpoint_if_source_changed(&fork));
1737        assert_eq!(evm_opts.fork_endpoint, None);
1738        assert_eq!(evm_opts.expected_fork_endpoint, None);
1739        assert_eq!(evm_opts.fork_block_number, Some(123));
1740        assert_eq!(evm_opts.networks, NetworkConfigs::with_celo());
1741        assert_eq!(evm_opts.env.chain_id, Some(42));
1742    }
1743
1744    #[test]
1745    fn changed_fork_selector_preserves_endpoint_identity() {
1746        let endpoint = "http://localhost:8545";
1747        let identity = ForkEndpointIdentity {
1748            endpoint: endpoint.to_string(),
1749            execution_chain_id: 1,
1750            source_chain_id: 1,
1751            network: NetworkVariant::Ethereum,
1752            network_profile: NetworkConfigs::default(),
1753            reported_hardfork: None,
1754            hardfork: None,
1755            instance_id: Some(B256::with_last_byte(1)),
1756            source_fork_block_number: None,
1757            source_fork_block_hash: None,
1758        };
1759        let mut evm_opts = EvmOpts {
1760            fork_url: Some(endpoint.to_string()),
1761            fork_headers: Some(vec!["x-source: stable".to_string()]),
1762            rpc_jwt: Some("stable-jwt".to_string()),
1763            fork_endpoint: Some(identity.clone()),
1764            expected_fork_endpoint: Some(identity.clone()),
1765            ..Default::default()
1766        };
1767        let fork = evm_opts.test_fork(
1768            endpoint,
1769            BlockNumHash::new(1, B256::with_last_byte(2)),
1770            resolved_context(1),
1771        );
1772
1773        evm_opts.fork_block_number = Some(1);
1774
1775        assert!(!evm_opts.invalidate_fork_endpoint_if_source_changed(&fork));
1776        assert_eq!(evm_opts.fork_endpoint, Some(identity.clone()));
1777        assert_eq!(evm_opts.expected_fork_endpoint, Some(identity));
1778    }
1779
1780    #[test]
1781    fn selecting_same_fork_url_preserves_pinned_state() {
1782        let mut evm_opts = EvmOpts {
1783            fork_url: Some("http://localhost:8545".to_string()),
1784            fork_block_number: Some(123),
1785            networks: NetworkConfigs::with_celo(),
1786            fork_network_is_inferred: true,
1787            fork_chain_id_is_inferred: true,
1788            fork_block_number_is_inferred: true,
1789            ..Default::default()
1790        };
1791        evm_opts.env.chain_id = Some(42);
1792
1793        evm_opts.set_fork_url("http://localhost:8545".to_string());
1794
1795        assert_eq!(evm_opts.fork_block_number, Some(123));
1796        assert_eq!(evm_opts.networks, NetworkConfigs::with_celo());
1797        assert_eq!(evm_opts.env.chain_id, Some(42));
1798        assert!(evm_opts.fork_network_is_inferred);
1799        assert!(evm_opts.fork_chain_id_is_inferred);
1800        assert!(evm_opts.fork_block_number_is_inferred);
1801    }
1802
1803    /// Returns a local environment of `FEN` on `chain_id` at `timestamp`.
1804    fn env_at<FEN: FoundryEvmNetwork>(chain_id: u64, timestamp: u64) -> EvmEnvFor<FEN> {
1805        let mut env = EvmOpts::default().local_evm_env::<FEN>();
1806        env.set_chain_id(chain_id);
1807        env.block.timestamp = U256::from(timestamp);
1808        env
1809    }
1810
1811    /// Returns the spec of `FEN` for `hardfork`.
1812    fn spec_of<FEN: FoundryEvmNetwork>(hardfork: FoundryHardfork) -> SpecFor<FEN> {
1813        SpecFor::<FEN>::from_foundry_hardfork(hardfork).unwrap()
1814    }
1815
1816    #[cfg(feature = "monad")]
1817    fn monad_env(timestamp: u64) -> EvmEnvFor<MonadEvmNetwork> {
1818        env_at::<MonadEvmNetwork>(NamedChain::Monad as u64, timestamp)
1819    }
1820
1821    #[cfg(feature = "monad")]
1822    fn monad_spec(hardfork: foundry_evm_hardforks::MonadHardfork) -> SpecFor<MonadEvmNetwork> {
1823        spec_of::<MonadEvmNetwork>(FoundryHardfork::Monad(hardfork))
1824    }
1825
1826    #[test]
1827    #[cfg(feature = "monad")]
1828    fn resolve_execution_spec_uses_monad_ten_activation_timestamp() {
1829        let config = Config::default();
1830        let activation =
1831            foundry_evm_hardforks::MonadHardfork::MonadTen.mainnet_activation_timestamp().unwrap();
1832
1833        let mut before = monad_env(activation - 1);
1834        assert_eq!(
1835            resolve_execution_spec::<EvmFactoryFor<MonadEvmNetwork>>(
1836                config.evm_version,
1837                config.hardfork,
1838                &mut before,
1839                ExecutionSpecContext::fork(NamedChain::Monad as u64, None),
1840                None,
1841            ),
1842            Some(FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadNine))
1843        );
1844        assert_eq!(before.spec, monad_spec(foundry_evm_hardforks::MonadHardfork::MonadNine));
1845
1846        let mut after = monad_env(activation);
1847        assert_eq!(
1848            resolve_execution_spec::<EvmFactoryFor<MonadEvmNetwork>>(
1849                config.evm_version,
1850                config.hardfork,
1851                &mut after,
1852                ExecutionSpecContext::fork(NamedChain::Monad as u64, None),
1853                None,
1854            ),
1855            Some(FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadTen))
1856        );
1857        assert_eq!(after.spec, monad_spec(foundry_evm_hardforks::MonadHardfork::MonadTen));
1858    }
1859
1860    #[test]
1861    #[cfg(feature = "monad")]
1862    fn resolve_execution_spec_prefers_exact_endpoint_hardfork() {
1863        let config = Config::default();
1864        let activation =
1865            foundry_evm_hardforks::MonadHardfork::MonadNine.mainnet_activation_timestamp().unwrap();
1866        let mut env = monad_env(activation);
1867        let endpoint_hardfork =
1868            FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadEight);
1869
1870        assert_eq!(
1871            resolve_execution_spec::<EvmFactoryFor<MonadEvmNetwork>>(
1872                config.evm_version,
1873                config.hardfork,
1874                &mut env,
1875                ExecutionSpecContext::fork(NamedChain::Monad as u64, Some(endpoint_hardfork),),
1876                None,
1877            ),
1878            Some(endpoint_hardfork)
1879        );
1880        assert_eq!(env.spec, monad_spec(foundry_evm_hardforks::MonadHardfork::MonadEight));
1881    }
1882
1883    #[test]
1884    #[cfg(feature = "monad")]
1885    fn resolve_execution_spec_ignores_schedule_for_local_env() {
1886        let config = Config::default();
1887        let activation =
1888            foundry_evm_hardforks::MonadHardfork::MonadTen.mainnet_activation_timestamp().unwrap();
1889        let mut env = monad_env(activation - 1);
1890
1891        assert_eq!(
1892            resolve_execution_spec::<EvmFactoryFor<MonadEvmNetwork>>(
1893                config.evm_version,
1894                config.hardfork,
1895                &mut env,
1896                ExecutionSpecContext::Local,
1897                None,
1898            ),
1899            Some(FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadTen))
1900        );
1901        assert_eq!(env.spec, monad_spec(foundry_evm_hardforks::MonadHardfork::MonadTen));
1902    }
1903
1904    #[test]
1905    fn resolve_execution_spec_preserves_ethereum_config_for_local_forks() {
1906        let config = Config::default();
1907        let mut env = env_at::<EthEvmNetwork>(NamedChain::Mainnet as u64, 1_500_000_000);
1908        env.spec = evm2::SpecId::LONDON;
1909
1910        assert_eq!(
1911            resolve_execution_spec::<EvmFactoryFor<EthEvmNetwork>>(
1912                config.evm_version,
1913                config.hardfork,
1914                &mut env,
1915                ExecutionSpecContext::fork(NamedChain::Mainnet as u64, None),
1916                None,
1917            ),
1918            None
1919        );
1920        assert_eq!(env.spec, config.evm_spec_id::<evm2::SpecId>());
1921
1922        let endpoint_hardfork =
1923            FoundryHardfork::Ethereum(foundry_evm_hardforks::EthereumHardfork::Frontier);
1924        assert_eq!(
1925            resolve_execution_spec::<EvmFactoryFor<EthEvmNetwork>>(
1926                config.evm_version,
1927                config.hardfork,
1928                &mut env,
1929                ExecutionSpecContext::fork(NamedChain::Mainnet as u64, Some(endpoint_hardfork),),
1930                None,
1931            ),
1932            None
1933        );
1934        assert_eq!(env.spec, config.evm_spec_id::<evm2::SpecId>());
1935    }
1936
1937    #[test]
1938    fn resolve_execution_spec_follows_ethereum_chain_ahead_for_scripts() {
1939        let amsterdam = EthereumHardfork::Amsterdam.sepolia_activation_timestamp().unwrap();
1940        let sepolia = NamedChain::Sepolia as u64;
1941        let resolve = |timestamp: u64, context| {
1942            let mut env = env_at::<EthEvmNetwork>(sepolia, timestamp);
1943            env.spec = evm2::SpecId::LONDON;
1944            let resolved = resolve_execution_spec::<EvmFactoryFor<EthEvmNetwork>>(
1945                EvmVersion::Prague,
1946                None,
1947                &mut env,
1948                context,
1949                None,
1950            );
1951            (resolved, env.spec)
1952        };
1953        let ethereum = |hardfork| Some(FoundryHardfork::Ethereum(hardfork));
1954
1955        // The source schedule applies once the chain is ahead of `evm_version`.
1956        assert_eq!(
1957            resolve(amsterdam, ExecutionSpecContext::local_or_script(Some(sepolia), None)),
1958            (ethereum(EthereumHardfork::Amsterdam), evm2::SpecId::AMSTERDAM)
1959        );
1960        assert_eq!(
1961            resolve(amsterdam - 1, ExecutionSpecContext::local_or_script(Some(sepolia), None)).1,
1962            evm2::SpecId::OSAKA
1963        );
1964        // Anvil reports its hardfork for chains without a known schedule.
1965        assert_eq!(
1966            resolve(
1967                amsterdam,
1968                ExecutionSpecContext::local_or_script(
1969                    Some(NamedChain::Dev as u64),
1970                    ethereum(EthereumHardfork::Amsterdam)
1971                )
1972            ),
1973            (ethereum(EthereumHardfork::Amsterdam), evm2::SpecId::AMSTERDAM)
1974        );
1975        // An endpoint that is not ahead keeps `evm_version` instead of the source schedule.
1976        assert_eq!(
1977            resolve(
1978                amsterdam,
1979                ExecutionSpecContext::local_or_script(
1980                    Some(sepolia),
1981                    ethereum(EthereumHardfork::Prague)
1982                )
1983            ),
1984            (None, evm2::SpecId::PRAGUE)
1985        );
1986    }
1987
1988    #[test]
1989    fn resolve_execution_spec_uses_ethereum_schedule_for_historical_execution() {
1990        let config = Config::default();
1991        let timestamp = 1_500_000_000u64;
1992        let expected =
1993            FoundryHardfork::from_chain_and_timestamp(NamedChain::Mainnet as u64, timestamp)
1994                .unwrap();
1995        let mut env = env_at::<EthEvmNetwork>(NamedChain::Mainnet as u64, timestamp);
1996        env.spec = evm2::SpecId::LONDON;
1997
1998        assert_eq!(
1999            resolve_execution_spec::<EvmFactoryFor<EthEvmNetwork>>(
2000                config.evm_version,
2001                config.hardfork,
2002                &mut env,
2003                ExecutionSpecContext::historical(NamedChain::Mainnet as u64, None),
2004                None,
2005            ),
2006            Some(expected)
2007        );
2008        assert_eq!(env.spec, spec_of::<EthEvmNetwork>(expected));
2009    }
2010
2011    #[test]
2012    #[cfg(feature = "optimism")]
2013    fn resolve_execution_spec_uses_optimism_schedule_for_local_forks() {
2014        let config =
2015            Config { hardfork: Some("ethereum:london".parse().unwrap()), ..Default::default() };
2016        let chain_id = NamedChain::Optimism as u64;
2017        let timestamp = u64::MAX;
2018        let expected = FoundryHardfork::from_chain_and_timestamp(chain_id, timestamp).unwrap();
2019        let mut env = env_at::<OpEvmNetwork>(chain_id, timestamp);
2020
2021        assert_eq!(
2022            resolve_execution_spec::<EvmFactoryFor<OpEvmNetwork>>(
2023                config.evm_version,
2024                config.hardfork,
2025                &mut env,
2026                ExecutionSpecContext::fork(chain_id, Some("tempo:T3".parse().unwrap())),
2027                None,
2028            ),
2029            Some(expected)
2030        );
2031        assert_eq!(env.spec, spec_of::<OpEvmNetwork>(expected));
2032    }
2033
2034    #[test]
2035    #[cfg(all(feature = "optimism", not(feature = "base")))]
2036    fn resolve_execution_spec_preserves_config_for_base_op_fallback() {
2037        let config = Config { evm_version: EvmVersion::Osaka, ..Default::default() };
2038        let mut env = env_at::<OpEvmNetwork>(NamedChain::Base as u64, u64::MAX);
2039
2040        assert_eq!(
2041            resolve_execution_spec::<EvmFactoryFor<OpEvmNetwork>>(
2042                config.evm_version,
2043                config.hardfork,
2044                &mut env,
2045                ExecutionSpecContext::fork(NamedChain::Base as u64, None),
2046                None,
2047            ),
2048            None
2049        );
2050        assert_eq!(env.spec, op_evm2::OpSpecId::KARST);
2051    }
2052
2053    #[test]
2054    #[cfg(feature = "monad")]
2055    fn resolve_execution_spec_honors_explicit_precedence() {
2056        let activation =
2057            foundry_evm_hardforks::MonadHardfork::MonadNine.mainnet_activation_timestamp().unwrap();
2058        let mut configured = Config {
2059            hardfork: Some(FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadNine)),
2060            ..Default::default()
2061        };
2062        let mut env = monad_env(activation - 1);
2063
2064        assert_eq!(
2065            resolve_execution_spec::<EvmFactoryFor<MonadEvmNetwork>>(
2066                configured.evm_version,
2067                configured.hardfork,
2068                &mut env,
2069                ExecutionSpecContext::fork(NamedChain::Monad as u64, None),
2070                None,
2071            ),
2072            configured.hardfork
2073        );
2074        assert_eq!(env.spec, monad_spec(foundry_evm_hardforks::MonadHardfork::MonadNine));
2075
2076        configured.hardfork = None;
2077        assert_eq!(
2078            resolve_execution_spec::<EvmFactoryFor<MonadEvmNetwork>>(
2079                configured.evm_version,
2080                configured.hardfork,
2081                &mut env,
2082                ExecutionSpecContext::fork(NamedChain::Monad as u64, None),
2083                Some(monad_spec(foundry_evm_hardforks::MonadHardfork::MonadEight)),
2084            ),
2085            Some(FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadEight))
2086        );
2087        assert_eq!(env.spec, monad_spec(foundry_evm_hardforks::MonadHardfork::MonadEight));
2088    }
2089
2090    #[tokio::test(flavor = "multi_thread")]
2091    async fn infer_network_preserves_explicit_ethereum() {
2092        let networks = NetworkConfigs::with_ethereum();
2093        let mut evm_opts = EvmOpts {
2094            fork_url: Some("http://127.0.0.1:1".to_string()),
2095            networks,
2096            ..Default::default()
2097        };
2098
2099        let error = evm_opts.infer_network_from_fork().await.unwrap_err();
2100
2101        assert!(error.to_string().contains("failed to retrieve chain ID"));
2102        assert_eq!(evm_opts.networks, networks);
2103        assert_eq!(evm_opts.env.chain_id, None);
2104    }
2105
2106    #[tokio::test]
2107    async fn clearing_fork_restores_inferred_network_defaults() {
2108        let mut profiles = vec![NetworkConfigs::with_celo(), NetworkConfigs::with_tempo()];
2109        #[cfg(feature = "optimism")]
2110        profiles.push(NetworkConfigs::with_optimism());
2111        #[cfg(feature = "monad")]
2112        profiles.push(NetworkConfigs::with_monad());
2113        #[cfg(feature = "base")]
2114        profiles.push(NetworkConfigs::with_base());
2115
2116        for networks in profiles {
2117            let mut evm_opts = EvmOpts {
2118                networks,
2119                fork_endpoint: Some(ForkEndpointIdentity {
2120                    endpoint: "http://localhost:8545".to_string(),
2121                    execution_chain_id: 1,
2122                    source_chain_id: 1,
2123                    network: networks.execution_network(),
2124                    network_profile: networks,
2125                    reported_hardfork: None,
2126                    hardfork: None,
2127                    instance_id: None,
2128                    source_fork_block_number: None,
2129                    source_fork_block_hash: None,
2130                }),
2131                fork_block_number: Some(123),
2132                fork_network_is_inferred: true,
2133                fork_chain_id_is_inferred: true,
2134                fork_block_number_is_inferred: true,
2135                ..Default::default()
2136            };
2137            evm_opts.env.chain_id = Some(1);
2138
2139            evm_opts.infer_network_from_fork().await.unwrap();
2140
2141            assert_eq!(evm_opts.networks, NetworkConfigs::default());
2142            assert_eq!(evm_opts.fork_endpoint, None);
2143            assert!(!evm_opts.fork_network_is_inferred);
2144            assert_eq!(evm_opts.env.chain_id, None);
2145            assert!(!evm_opts.fork_chain_id_is_inferred);
2146            assert_eq!(evm_opts.fork_block_number, None);
2147            assert!(!evm_opts.fork_block_number_is_inferred);
2148        }
2149    }
2150
2151    #[tokio::test]
2152    #[cfg(feature = "base")]
2153    async fn base_endpoint_identity_uses_generic_chain_profile() {
2154        let endpoint = "http://127.0.0.1:1";
2155        let provider = EvmOpts::default().fork_provider_with_url::<AnyNetwork>(endpoint).unwrap();
2156
2157        let identity = EvmOpts::resolve_fork_endpoint_identity(
2158            &provider,
2159            endpoint,
2160            NamedChain::Base as u64,
2161            None,
2162            None,
2163            EndpointHardforkPolicy::Optional,
2164        )
2165        .await
2166        .unwrap();
2167
2168        assert_eq!(identity.execution_chain_id, NamedChain::Base as u64);
2169        assert_eq!(identity.source_chain_id, NamedChain::Base as u64);
2170        assert_eq!(identity.network, NetworkVariant::Base);
2171        assert!(identity.network_profile.is_base());
2172        assert_eq!(identity.reported_hardfork, None);
2173        assert_eq!(identity.hardfork, None);
2174    }
2175
2176    #[tokio::test]
2177    async fn fork_remote_chain_id_does_not_guess_from_url() {
2178        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
2179        let address = listener.local_addr().unwrap();
2180        drop(listener);
2181        let evm_opts = EvmOpts {
2182            fork_url: Some(format!("http://{address}/arb-mainnet")),
2183            fork_retries: Some(0),
2184            ..Default::default()
2185        };
2186        assert_eq!(evm_opts.get_remote_chain_id().await, None);
2187    }
2188
2189    #[test]
2190    fn known_network_variant_does_not_guess_unknown_chain() {
2191        assert_eq!(NetworkVariant::from_known_chain_id(98_765_432).unwrap(), None);
2192    }
2193
2194    #[test]
2195    #[cfg(feature = "monad")]
2196    fn known_network_variant_classifies_monad() {
2197        assert_eq!(
2198            NetworkVariant::from_known_chain_id(NamedChain::Monad as u64).unwrap(),
2199            Some(NetworkVariant::Monad)
2200        );
2201    }
2202
2203    #[test]
2204    #[cfg(not(feature = "monad"))]
2205    fn known_network_variant_rejects_disabled_monad() {
2206        assert_eq!(
2207            NetworkVariant::from_known_chain_id(NamedChain::Monad as u64).unwrap_err(),
2208            "network family `monad` is not enabled in this build"
2209        );
2210    }
2211
2212    #[tokio::test(flavor = "multi_thread")]
2213    async fn infer_network_tempo_propagates_unavailable_rpc() {
2214        let config = Config::figment();
2215        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2216        evm_opts.fork_url = Some("http://127.0.0.1:1".to_string());
2217        evm_opts.networks = NetworkConfigs::with_tempo();
2218
2219        let error = evm_opts.infer_network_from_fork().await.unwrap_err();
2220
2221        assert!(error.to_string().contains("failed to retrieve chain ID"));
2222        assert!(evm_opts.networks.is_tempo());
2223    }
2224
2225    #[tokio::test]
2226    async fn create2_deployer_availability_requires_resolved_fork_block() {
2227        let evm_opts =
2228            EvmOpts { fork_url: Some("http://127.0.0.1:1".to_string()), ..Default::default() };
2229
2230        let err = evm_opts.can_use_create2_deployer_at(None).await.unwrap_err();
2231        assert!(err.to_string().contains("fork must be resolved"));
2232    }
2233
2234    #[test]
2235    fn resolved_fork_matches_source_headers_and_selector() {
2236        let headers = vec!["Authorization: one".to_string()];
2237        let fork = Fork::test(
2238            "http://127.0.0.1:1",
2239            Some(&headers),
2240            None,
2241            None,
2242            BlockNumHash::new(1, B256::ZERO),
2243            resolved_context(1),
2244        );
2245        let mut evm_opts = EvmOpts {
2246            fork_url: Some("http://127.0.0.1:1".to_string()),
2247            fork_headers: Some(headers),
2248            rpc_headers: Some(vec!["x-fallback: ignored".to_string()]),
2249            ..Default::default()
2250        };
2251
2252        assert!(fork.matches_request(&evm_opts));
2253        let debug = format!("{fork:?}");
2254        assert!(!debug.contains("127.0.0.1"));
2255        assert!(!debug.contains("Authorization"));
2256        assert!(!debug.contains("one"));
2257
2258        evm_opts.fork_headers = Some(vec!["Authorization: two".to_string()]);
2259        assert!(!fork.matches_request(&evm_opts));
2260
2261        evm_opts.fork_headers = Some(vec!["Authorization: one".to_string()]);
2262        evm_opts.fork_block_number = Some(1);
2263        assert!(!fork.matches_request(&evm_opts));
2264
2265        evm_opts.fork_block_number = None;
2266        evm_opts.fork_url = Some("http://127.0.0.1:2".to_string());
2267        assert!(!fork.matches_request(&evm_opts));
2268
2269        let fork = Fork::test(
2270            "http://127.0.0.1:1",
2271            None,
2272            None,
2273            None,
2274            BlockNumHash::new(1, B256::ZERO),
2275            resolved_context(1),
2276        );
2277        evm_opts.fork_url = Some("http://127.0.0.1:1".to_string());
2278        evm_opts.fork_headers = Some(Vec::new());
2279        evm_opts.rpc_headers = None;
2280        assert!(fork.matches_request(&evm_opts));
2281
2282        let rpc_headers = vec!["Authorization: fallback".to_string()];
2283        let fork = Fork::test(
2284            "http://127.0.0.1:1",
2285            Some(&rpc_headers),
2286            Some("secret-jwt"),
2287            None,
2288            BlockNumHash::new(1, B256::ZERO),
2289            resolved_context(1),
2290        );
2291        evm_opts.fork_headers = None;
2292        evm_opts.rpc_headers = Some(rpc_headers);
2293        evm_opts.rpc_jwt = Some("secret-jwt".to_string());
2294        assert!(fork.matches_request(&evm_opts));
2295        assert!(!format!("{fork:?}").contains("secret-jwt"));
2296
2297        evm_opts.rpc_jwt = Some("different-jwt".to_string());
2298        assert!(!fork.matches_request(&evm_opts));
2299    }
2300
2301    #[test]
2302    #[cfg(feature = "monad")]
2303    fn unknown_endpoint_hardfork_is_optional_only_for_remote_execution() {
2304        assert_eq!(NetworkVariant::from_node_info_name("monad").unwrap(), NetworkVariant::Monad);
2305        assert_eq!(
2306            endpoint_hardfork(
2307                NetworkVariant::Monad,
2308                "MonadFuture",
2309                EndpointHardforkPolicy::Optional
2310            )
2311            .unwrap(),
2312            None
2313        );
2314
2315        let error = endpoint_hardfork(
2316            NetworkVariant::Monad,
2317            "MonadFuture",
2318            EndpointHardforkPolicy::Required,
2319        )
2320        .unwrap_err();
2321        assert!(
2322            error.to_string().contains("unsupported hardfork `MonadFuture` reported for `monad`")
2323        );
2324        assert_eq!(
2325            endpoint_hardfork(NetworkVariant::Monad, "MonadNine", EndpointHardforkPolicy::Required)
2326                .unwrap(),
2327            Some(FoundryHardfork::Monad(foundry_evm_hardforks::MonadHardfork::MonadNine))
2328        );
2329    }
2330
2331    #[test]
2332    #[cfg(feature = "base")]
2333    fn unknown_base_endpoint_hardfork_is_optional_only_for_remote_execution() {
2334        assert_eq!(NetworkVariant::from_node_info_name("base").unwrap(), NetworkVariant::Base);
2335        assert_eq!(
2336            endpoint_hardfork(NetworkVariant::Base, "BaseFuture", EndpointHardforkPolicy::Optional)
2337                .unwrap(),
2338            None
2339        );
2340
2341        let error =
2342            endpoint_hardfork(NetworkVariant::Base, "BaseFuture", EndpointHardforkPolicy::Required)
2343                .unwrap_err();
2344        assert!(
2345            error.to_string().contains("unsupported hardfork `BaseFuture` reported for `base`")
2346        );
2347        assert_eq!(
2348            endpoint_hardfork(NetworkVariant::Base, "Beryl", EndpointHardforkPolicy::Required)
2349                .unwrap(),
2350            Some(FoundryHardfork::Base(BaseUpgrade::Beryl))
2351        );
2352    }
2353
2354    #[tokio::test(flavor = "multi_thread")]
2355    #[cfg(feature = "monad")]
2356    async fn infer_network_monad_propagates_unavailable_rpc() {
2357        let config = Config::figment();
2358        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2359        evm_opts.fork_url = Some("http://127.0.0.1:1".to_string());
2360        evm_opts.networks = NetworkConfigs::with_monad();
2361
2362        let error = evm_opts.infer_network_from_fork().await.unwrap_err();
2363
2364        assert!(error.to_string().contains("failed to retrieve chain ID"));
2365        assert!(evm_opts.networks.is_monad());
2366    }
2367
2368    #[tokio::test(flavor = "multi_thread")]
2369    #[cfg(feature = "base")]
2370    async fn infer_network_base_propagates_unavailable_rpc() {
2371        let mut evm_opts = EvmOpts {
2372            fork_url: Some("http://127.0.0.1:1".to_string()),
2373            networks: NetworkConfigs::with_base(),
2374            ..Default::default()
2375        };
2376
2377        let error = evm_opts.infer_network_from_fork().await.unwrap_err();
2378
2379        assert!(error.to_string().contains("failed to retrieve chain ID"));
2380        assert!(evm_opts.networks.is_base());
2381        assert_eq!(evm_opts.fork_endpoint, None);
2382    }
2383
2384    #[tokio::test(flavor = "multi_thread")]
2385    async fn flaky_infer_network_tempo_moderato_rpc() {
2386        let config = Config::figment();
2387        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2388        evm_opts.fork_url = Some("https://rpc.moderato.tempo.xyz".to_string());
2389        assert_eq!(evm_opts.networks, NetworkConfigs::default());
2390
2391        evm_opts.infer_network_from_fork().await.unwrap();
2392
2393        // Tempo Moderato has a known Tempo chain ID -> should be inferred via with_chain_id.
2394        assert!(evm_opts.networks.is_tempo(), "should detect tempo from Moderato chain ID");
2395    }
2396
2397    #[tokio::test(flavor = "multi_thread")]
2398    async fn get_fork_pins_block_number_from_env() {
2399        let endpoint = foundry_test_utils::rpc::next_http_rpc_endpoint();
2400
2401        let config = Config::figment();
2402        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2403        evm_opts.fork_url = Some(endpoint.clone());
2404        // Explicitly leave fork_block_number as None to simulate --fork-url without --block-number
2405        assert!(evm_opts.fork_block_number.is_none());
2406
2407        // Fetch the environment (this resolves "latest" to an actual block number)
2408        let (evm_env, _, fork) = evm_opts.env_with_fork_context::<EthEvmNetwork>().await.unwrap();
2409        let fork_block = fork.as_ref().map(|context| context.block_number);
2410        assert!(fork_block.is_some(), "should have resolved a fork block number");
2411        let resolved_block = fork_block.unwrap();
2412        assert!(resolved_block > 0, "should have resolved to a real block number");
2413
2414        // Create the fork - this should pin the block number
2415        let fork = evm_opts.get_fork(&Config::default(), evm_env.chain_id(), fork_block).unwrap();
2416
2417        // The fork's evm_opts should now have fork_block_number set to the resolved block
2418        assert_eq!(
2419            fork.evm_opts.fork_block_number,
2420            Some(resolved_block),
2421            "get_fork should pin fork_block_number to the block from env"
2422        );
2423        assert!(fork.evm_opts.fork_block_number_is_inferred);
2424    }
2425
2426    // Regression test for https://github.com/foundry-rs/foundry/issues/13576
2427    // On Arbitrum, `block_env.number` is remapped to the L1 block number by
2428    // `apply_chain_and_block_specific_env_changes_for_chain`. The fork block number returned
2429    // by `env_with_fork_context()` must be the actual L2 block number, not the remapped L1 value.
2430    #[tokio::test(flavor = "multi_thread")]
2431    async fn flaky_get_fork_uses_l2_block_number_on_arbitrum() {
2432        let endpoint =
2433            foundry_test_utils::rpc::next_rpc_endpoint(foundry_config::NamedChain::Arbitrum);
2434
2435        let config = Config::figment();
2436        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2437        evm_opts.fork_url = Some(endpoint.clone());
2438        assert!(evm_opts.fork_block_number.is_none());
2439
2440        let (evm_env, _, fork) = evm_opts.env_with_fork_context::<EthEvmNetwork>().await.unwrap();
2441        let fork_block = fork
2442            .as_ref()
2443            .map(|context| context.block_number)
2444            .expect("should have resolved a fork block number");
2445
2446        // On Arbitrum, block_env.number is the L1 block number (much smaller).
2447        // The fork_block should be the actual L2 block number (much larger).
2448        let block_env_number: u64 = evm_env.block.number.to();
2449        assert!(
2450            fork_block > block_env_number,
2451            "fork_block ({fork_block}) should be the L2 block, which is larger than \
2452             block_env.number ({block_env_number}) which is the L1 block on Arbitrum"
2453        );
2454
2455        // Verify get_fork pins to the correct L2 block number
2456        let fork =
2457            evm_opts.get_fork(&Config::default(), evm_env.chain_id(), Some(fork_block)).unwrap();
2458        assert_eq!(
2459            fork.evm_opts.fork_block_number,
2460            Some(fork_block),
2461            "get_fork should pin to the L2 block number, not the L1 block number"
2462        );
2463    }
2464
2465    #[tokio::test(flavor = "multi_thread")]
2466    async fn get_fork_preserves_explicit_block_number() {
2467        let endpoint = foundry_test_utils::rpc::next_http_rpc_endpoint();
2468
2469        let config = Config::figment();
2470        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2471        evm_opts.fork_url = Some(endpoint.clone());
2472        // Set an explicit block number
2473        evm_opts.fork_block_number = Some(12345678);
2474
2475        let (evm_env, _, fork) = evm_opts.env_with_fork_context::<EthEvmNetwork>().await.unwrap();
2476        let fork_block = fork.as_ref().map(|context| context.block_number);
2477
2478        let fork = evm_opts.get_fork(&Config::default(), evm_env.chain_id(), fork_block).unwrap();
2479
2480        // Should preserve the explicit block number, not override it
2481        assert_eq!(
2482            fork.evm_opts.fork_block_number,
2483            Some(12345678),
2484            "get_fork should preserve explicitly set fork_block_number"
2485        );
2486        assert!(!fork.evm_opts.fork_block_number_is_inferred);
2487    }
2488
2489    #[tokio::test(flavor = "multi_thread")]
2490    async fn fork_preflight_reads_send_hash_objects_without_canonical_flag() {
2491        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2492        let (endpoint, code_requests) =
2493            spawn_rpc_proxy_recording_method(handle.http_endpoint(), "eth_getCode").await;
2494        let (endpoint, nonce_requests) =
2495            spawn_rpc_proxy_recording_method(endpoint, "eth_getTransactionCount").await;
2496        let evm_opts = EvmOpts { fork_url: Some(endpoint), ..Default::default() };
2497        let fork = evm_opts.prepare_fork().await.unwrap().unwrap();
2498        let sender = handle.dev_accounts().next().unwrap();
2499
2500        evm_opts.can_use_create2_deployer_at(Some(&fork)).await.unwrap();
2501        assert_eq!(evm_opts.transaction_count_at_fork(sender, &fork).await.unwrap(), 0);
2502
2503        let expected = serde_json::json!({ "blockHash": fork.hash() });
2504        for requests in [code_requests, nonce_requests] {
2505            let requests = requests.lock().unwrap();
2506            assert!(!requests.is_empty());
2507            assert!(requests.iter().all(|params| params[1] == expected), "{requests:?}");
2508        }
2509    }
2510
2511    #[tokio::test(flavor = "multi_thread")]
2512    async fn create2_deployer_preflight_uses_exact_fork_hash() {
2513        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2514        let provider = handle.http_provider();
2515        let sender = handle.dev_accounts().next().unwrap();
2516
2517        let init_code = bytes!("6001600c60003960016000f300");
2518        let receipt = provider
2519            .send_transaction(WithOtherFields::new(
2520                TransactionRequest::default().from(sender).with_deploy_code(init_code),
2521            ))
2522            .await
2523            .unwrap()
2524            .get_receipt()
2525            .await
2526            .unwrap();
2527        let deployer = receipt.contract_address.unwrap();
2528        let block_number = receipt.block_number.unwrap();
2529
2530        let evm_opts = EvmOpts {
2531            fork_url: Some(handle.http_endpoint()),
2532            fork_block_number: Some(block_number),
2533            create2_deployer: deployer,
2534            ..Default::default()
2535        };
2536        let fork = evm_opts.prepare_fork().await.unwrap();
2537        let fork = fork.unwrap();
2538        assert!(evm_opts.can_use_create2_deployer_at(Some(&fork)).await.unwrap());
2539
2540        provider
2541            .raw_request::<_, ()>("anvil_reorg".into(), (1_u64, Vec::<serde_json::Value>::new()))
2542            .await
2543            .unwrap();
2544        let replacement = provider.get_block_by_number(block_number.into()).await.unwrap().unwrap();
2545        assert_ne!(replacement.header().hash(), fork.hash());
2546        assert!(
2547            provider.get_code_at(deployer).number(block_number).await.unwrap().is_empty(),
2548            "the replacement block must not contain the deployer"
2549        );
2550
2551        assert!(
2552            !matches!(evm_opts.can_use_create2_deployer_at(Some(&fork)).await, Ok(false)),
2553            "the exact lookup fell back to the replacement block"
2554        );
2555    }
2556
2557    #[tokio::test(flavor = "multi_thread")]
2558    async fn expected_fork_endpoint_detects_same_url_reset() {
2559        let (api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2560        let mut evm_opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2561        evm_opts.infer_network_from_fork().await.unwrap();
2562        let identity = evm_opts.fork_endpoint.clone().unwrap();
2563        let original_instance = identity.instance_id;
2564        let network_is_inferred = evm_opts.fork_network_is_inferred;
2565        evm_opts.expect_fork_endpoint(identity, network_is_inferred);
2566
2567        api.anvil_reset(None).await.unwrap();
2568
2569        assert_ne!(api.instance_id(), original_instance.unwrap());
2570        let error = evm_opts.env_with_fork_context::<EthEvmNetwork>().await.unwrap_err();
2571        assert!(
2572            error.to_string().contains("changed after its execution context was selected"),
2573            "{error}"
2574        );
2575    }
2576
2577    #[tokio::test(flavor = "multi_thread")]
2578    async fn fork_backend_rejects_changed_selected_endpoint() {
2579        let (api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2580        let mut opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2581        opts.infer_network_from_fork().await.unwrap();
2582        opts.expect_fork_endpoint(
2583            opts.fork_endpoint.clone().unwrap(),
2584            opts.fork_network_is_inferred,
2585        );
2586        let request = opts.get_fork(&Config::default(), 31337, None);
2587        api.anvil_reset(None).await.unwrap();
2588        let error = crate::backend::Backend::<EthEvmNetwork>::spawn(
2589            request,
2590            opts.local_evm_env::<EthEvmNetwork>(),
2591        )
2592        .unwrap_err();
2593        assert!(
2594            error.to_string().contains("changed after its execution context was selected"),
2595            "{error}"
2596        );
2597    }
2598
2599    #[tokio::test(flavor = "multi_thread")]
2600    async fn fork_network_detects_ethereum_anvil() {
2601        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2602        let evm_opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2603
2604        let identity = evm_opts.discover_fork_endpoint().await.unwrap();
2605        assert_eq!(
2606            (identity.execution_chain_id, identity.network),
2607            (NamedChain::AnvilHardhat as u64, NetworkVariant::Ethereum)
2608        );
2609    }
2610
2611    #[tokio::test(flavor = "multi_thread")]
2612    async fn fork_network_uses_anvil_metadata_for_unknown_chain() {
2613        let chain_id = 98_765_432;
2614        let (_api, handle) =
2615            anvil::spawn(anvil::NodeConfig::test().with_chain_id(Some(chain_id))).await;
2616        let evm_opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2617
2618        let identity = evm_opts.discover_fork_endpoint().await.unwrap();
2619        assert_eq!(
2620            (identity.execution_chain_id, identity.network),
2621            (chain_id, NetworkVariant::Ethereum)
2622        );
2623    }
2624
2625    #[tokio::test(flavor = "multi_thread")]
2626    async fn fork_non_anvil_node_info_rpc_error_is_optional() {
2627        let (_api, handle) =
2628            anvil::spawn(anvil::NodeConfig::test().with_chain_id(Some(NamedChain::Mainnet as u64)))
2629                .await;
2630        let fork_url =
2631            spawn_rpc_proxy_internal_error_after(handle.http_endpoint(), "anvil_nodeInfo", 0).await;
2632        let mut evm_opts = EvmOpts { fork_url: Some(fork_url), ..Default::default() };
2633
2634        evm_opts.infer_network_from_fork().await.unwrap();
2635
2636        assert_eq!(evm_opts.networks, NetworkConfigs::default());
2637        assert_eq!(evm_opts.env.chain_id, Some(NamedChain::Mainnet as u64));
2638    }
2639
2640    #[tokio::test(flavor = "multi_thread")]
2641    async fn fork_node_info_failure_is_strict_after_anvil_is_identified() {
2642        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2643        let fork_url =
2644            spawn_rpc_proxy_rejecting_method_after(handle.http_endpoint(), "anvil_nodeInfo", 1)
2645                .await;
2646        let evm_opts = EvmOpts { fork_url: Some(fork_url), ..Default::default() };
2647
2648        let error = evm_opts.discover_fork_endpoint().await.unwrap_err();
2649
2650        assert!(
2651            error.to_string().contains("failed to determine network family from endpoint"),
2652            "{error}"
2653        );
2654    }
2655
2656    #[tokio::test(flavor = "multi_thread")]
2657    async fn fork_node_info_probe_becomes_strict_after_initial_failure() {
2658        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2659        let fork_url =
2660            spawn_rpc_proxy_method_not_found_before(handle.http_endpoint(), "anvil_nodeInfo", 1)
2661                .await;
2662        let evm_opts = EvmOpts { fork_url: Some(fork_url), ..Default::default() };
2663
2664        let fork = evm_opts.prepare_fork().await.unwrap().unwrap();
2665
2666        assert!(fork.context().hardfork.is_some());
2667        assert!(fork.context().instance_id.is_some());
2668    }
2669
2670    #[tokio::test(flavor = "multi_thread")]
2671    async fn fork_cached_anvil_identity_keeps_node_info_probe_strict() {
2672        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2673        let fork_url =
2674            spawn_rpc_proxy_rejecting_method_after(handle.http_endpoint(), "anvil_nodeInfo", 2)
2675                .await;
2676        let mut evm_opts = EvmOpts { fork_url: Some(fork_url), ..Default::default() };
2677        evm_opts.infer_network_from_fork().await.unwrap();
2678        assert!(evm_opts.fork_endpoint.as_ref().unwrap().reported_hardfork.is_some());
2679
2680        let error = evm_opts.discover_fork_endpoint().await.unwrap_err();
2681
2682        assert!(
2683            error.to_string().contains("failed to determine network family from endpoint"),
2684            "{error}"
2685        );
2686    }
2687
2688    #[tokio::test(flavor = "multi_thread")]
2689    async fn fork_non_anvil_discovery_is_reused_by_resolution() {
2690        let (_api, handle) =
2691            anvil::spawn(anvil::NodeConfig::test().with_chain_id(Some(NamedChain::Mainnet as u64)))
2692                .await;
2693        let endpoint = spawn_rpc_proxy_method_not_found_before(
2694            handle.http_endpoint(),
2695            "anvil_nodeInfo",
2696            usize::MAX,
2697        )
2698        .await;
2699        let (endpoint, chain_ids) = spawn_rpc_proxy_recording_method(endpoint, "eth_chainId").await;
2700        let (endpoint, node_infos) =
2701            spawn_rpc_proxy_recording_method(endpoint, "anvil_nodeInfo").await;
2702        let (endpoint, blocks) =
2703            spawn_rpc_proxy_recording_method(endpoint, "eth_getBlockByNumber").await;
2704        let (endpoint, hashes) =
2705            spawn_rpc_proxy_recording_method(endpoint, "eth_getBlockByHash").await;
2706        let probes = || (chain_ids.lock().unwrap().len(), node_infos.lock().unwrap().len());
2707        let mut evm_opts = EvmOpts { fork_url: Some(endpoint), ..Default::default() };
2708
2709        evm_opts.infer_network_from_fork().await.unwrap();
2710        assert_eq!(probes(), (1, 1));
2711        assert_eq!(evm_opts.fork_endpoint.as_ref().unwrap().reported_hardfork, None);
2712
2713        evm_opts.infer_network_from_fork().await.unwrap();
2714        let backend = crate::backend::Backend::<EthEvmNetwork>::spawn(
2715            evm_opts.get_fork(&Config::default(), NamedChain::Mainnet as u64, None),
2716            evm_opts.local_evm_env::<EthEvmNetwork>(),
2717        )
2718        .unwrap();
2719        backend.env(&evm_opts).await.unwrap();
2720        backend.env(&evm_opts).await.unwrap();
2721        backend.can_use_create2_deployer(evm_opts.create2_deployer).await.unwrap();
2722        backend.transaction_count(evm_opts.sender).await.unwrap();
2723        assert_eq!(probes(), (1, 1));
2724        assert_eq!(blocks.lock().unwrap().len(), 1);
2725        assert!(hashes.lock().unwrap().is_empty());
2726        assert_eq!(evm_opts.fork_block_number, None);
2727
2728        // Explicit discovery always inspects the endpoint.
2729        evm_opts.discover_fork_endpoint().await.unwrap();
2730        assert_eq!(probes(), (2, 2));
2731    }
2732
2733    #[tokio::test(flavor = "multi_thread")]
2734    async fn infer_network_default_and_custom_anvil_selects_ethereum() {
2735        for chain_id in [NamedChain::Mainnet as u64, NamedChain::AnvilHardhat as u64, 98_765_432] {
2736            let (_api, handle) =
2737                anvil::spawn(anvil::NodeConfig::test().with_chain_id(Some(chain_id))).await;
2738
2739            let config = Config::figment();
2740            let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2741            evm_opts.fork_url = Some(handle.http_endpoint());
2742            assert_eq!(evm_opts.networks, NetworkConfigs::default());
2743
2744            evm_opts.infer_network_from_fork().await.unwrap();
2745
2746            assert_eq!(evm_opts.env.chain_id, Some(chain_id));
2747            assert!(!evm_opts.networks.is_tempo());
2748            #[cfg(feature = "optimism")]
2749            assert!(!evm_opts.networks.is_optimism());
2750            #[cfg(feature = "base")]
2751            assert!(!evm_opts.networks.is_base());
2752            assert!(!evm_opts.networks.is_celo());
2753            assert_eq!(evm_opts.networks, NetworkConfigs::default());
2754        }
2755    }
2756
2757    #[tokio::test(flavor = "multi_thread")]
2758    async fn infer_network_tempo_anvil_via_node_info() {
2759        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test_tempo()).await;
2760
2761        let config = Config::figment();
2762        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
2763        evm_opts.fork_url = Some(handle.http_endpoint());
2764        // Networks not set -> should query anvil_nodeInfo to discover tempo.
2765        assert_eq!(evm_opts.networks, NetworkConfigs::default());
2766
2767        evm_opts.infer_network_from_fork().await.unwrap();
2768
2769        assert!(evm_opts.networks.is_tempo(), "should detect tempo via anvil_nodeInfo");
2770    }
2771
2772    #[tokio::test(flavor = "multi_thread")]
2773    async fn prepared_fork_preserves_inferred_execution_profile_guard() {
2774        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2775        let mut opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2776        let fork = opts.prepare_fork().await.unwrap().unwrap();
2777        opts.networks = NetworkConfigs::with_tempo();
2778        opts.fork_network_is_inferred = true;
2779        let error = opts.env_at_fork::<EthEvmNetwork>(Some(&fork)).await.unwrap_err();
2780        assert!(error.to_string().contains("changed execution profile"), "{error}");
2781        opts.fork_network_is_inferred = false;
2782        opts.env_at_fork::<EthEvmNetwork>(Some(&fork)).await.unwrap();
2783    }
2784
2785    #[tokio::test(flavor = "multi_thread")]
2786    async fn prepared_fork_reconnects_after_runtime_shutdown() {
2787        let (_api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2788        for endpoint in [handle.http_endpoint(), handle.ws_endpoint()] {
2789            tokio::task::spawn_blocking(move || {
2790                let opts = EvmOpts { fork_url: Some(endpoint), ..Default::default() };
2791                let runtime =
2792                    || tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
2793                let fork = runtime().block_on(opts.prepare_fork()).unwrap().unwrap();
2794                let (env, _) =
2795                    runtime().block_on(opts.env_at_fork::<EthEvmNetwork>(Some(&fork))).unwrap();
2796                assert_eq!(env.block.number, U256::from(fork.number()));
2797            })
2798            .await
2799            .unwrap();
2800        }
2801    }
2802
2803    #[tokio::test(flavor = "multi_thread")]
2804    async fn resolved_fork_environment_retains_exact_block() {
2805        let (api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2806        let evm_opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2807        let fork = evm_opts.prepare_fork().await.unwrap().unwrap();
2808        let provider = handle.http_provider();
2809
2810        api.anvil_mine(Some(U256::ONE), None).await.unwrap();
2811        assert!(provider.get_block_number().await.unwrap() > fork.number());
2812
2813        let (evm_env, _) = evm_opts.env_at_fork::<EthEvmNetwork>(Some(&fork)).await.unwrap();
2814        let block = &fork.block;
2815
2816        assert_eq!(block.header().hash(), fork.hash());
2817        assert_eq!(block.header().number(), fork.number());
2818        assert_eq!(evm_env.block.number, U256::from(fork.number()));
2819        assert_eq!(evm_env.block.timestamp, U256::from(block.header().timestamp()));
2820    }
2821
2822    #[tokio::test(flavor = "multi_thread")]
2823    async fn resolved_fork_detects_same_url_reset_without_cached_expectation() {
2824        let (api, handle) = anvil::spawn(anvil::NodeConfig::test()).await;
2825        let evm_opts = EvmOpts { fork_url: Some(handle.http_endpoint()), ..Default::default() };
2826        let fork = evm_opts.prepare_fork().await.unwrap().unwrap();
2827        let original_instance = fork.context().instance_id;
2828
2829        api.anvil_reset(None).await.unwrap();
2830
2831        assert_ne!(api.instance_id(), original_instance.unwrap());
2832        let error = evm_opts.env_at_fork::<EthEvmNetwork>(Some(&fork)).await.unwrap_err();
2833        assert!(
2834            error
2835                .to_string()
2836                .contains("changed after its block and execution context were resolved"),
2837            "{error}"
2838        );
2839    }
2840}