foundry_evm_core/
opts.rs

1use super::fork::environment;
2use crate::{
3    EvmEnv,
4    constants::DEFAULT_CREATE2_DEPLOYER,
5    fork::{CreateFork, configure_env},
6};
7use alloy_network::Network;
8use alloy_primitives::{Address, B256, U256};
9use alloy_provider::{Provider, network::AnyRpcBlock};
10use eyre::WrapErr;
11use foundry_common::{
12    ALCHEMY_FREE_TIER_CUPS,
13    provider::{ProviderBuilder, RetryProvider},
14};
15use foundry_config::{Chain, Config, GasLimit};
16use foundry_evm_networks::NetworkConfigs;
17use revm::context::{BlockEnv, TxEnv};
18use serde::{Deserialize, Serialize};
19use std::fmt::Write;
20use url::Url;
21
22#[derive(Clone, Debug, Serialize, Deserialize)]
23pub struct EvmOpts {
24    /// The EVM environment configuration.
25    #[serde(flatten)]
26    pub env: Env,
27
28    /// Fetch state over a remote instead of starting from empty state.
29    #[serde(rename = "eth_rpc_url")]
30    pub fork_url: Option<String>,
31
32    /// Pins the block number for the state fork.
33    pub fork_block_number: Option<u64>,
34
35    /// The number of retries.
36    pub fork_retries: Option<u32>,
37
38    /// Initial retry backoff.
39    pub fork_retry_backoff: Option<u64>,
40
41    /// Headers to use with `fork_url`
42    pub fork_headers: Option<Vec<String>>,
43
44    /// The available compute units per second.
45    ///
46    /// See also <https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second>
47    pub compute_units_per_second: Option<u64>,
48
49    /// Disables RPC rate limiting entirely.
50    pub no_rpc_rate_limit: bool,
51
52    /// Disables storage caching entirely.
53    pub no_storage_caching: bool,
54
55    /// The initial balance of each deployed test contract.
56    pub initial_balance: U256,
57
58    /// The address which will be executing all tests.
59    pub sender: Address,
60
61    /// Enables the FFI cheatcode.
62    pub ffi: bool,
63
64    /// Use the create 2 factory in all cases including tests and non-broadcasting scripts.
65    pub always_use_create_2_factory: bool,
66
67    /// Verbosity mode of EVM output as number of occurrences.
68    pub verbosity: u8,
69
70    /// The memory limit per EVM execution in bytes.
71    /// If this limit is exceeded, a `MemoryLimitOOG` result is thrown.
72    pub memory_limit: u64,
73
74    /// Whether to enable isolation of calls.
75    pub isolate: bool,
76
77    /// Whether to disable block gas limit checks.
78    pub disable_block_gas_limit: bool,
79
80    /// Whether to enable tx gas limit checks as imposed by Osaka (EIP-7825).
81    pub enable_tx_gas_limit: bool,
82
83    #[serde(flatten)]
84    /// Networks with enabled features.
85    pub networks: NetworkConfigs,
86
87    /// The CREATE2 deployer's address.
88    pub create2_deployer: Address,
89}
90
91impl Default for EvmOpts {
92    fn default() -> Self {
93        Self {
94            env: Env::default(),
95            fork_url: None,
96            fork_block_number: None,
97            fork_retries: None,
98            fork_retry_backoff: None,
99            fork_headers: None,
100            compute_units_per_second: None,
101            no_rpc_rate_limit: false,
102            no_storage_caching: false,
103            initial_balance: U256::default(),
104            sender: Address::default(),
105            ffi: false,
106            always_use_create_2_factory: false,
107            verbosity: 0,
108            memory_limit: 0,
109            isolate: false,
110            disable_block_gas_limit: false,
111            enable_tx_gas_limit: false,
112            networks: NetworkConfigs::default(),
113            create2_deployer: DEFAULT_CREATE2_DEPLOYER,
114        }
115    }
116}
117
118impl EvmOpts {
119    /// Returns a `RetryProvider` for the given fork URL configured with options in `self`.
120    pub fn fork_provider_with_url(&self, fork_url: &str) -> eyre::Result<RetryProvider> {
121        ProviderBuilder::new(fork_url)
122            .maybe_max_retry(self.fork_retries)
123            .maybe_initial_backoff(self.fork_retry_backoff)
124            .maybe_headers(self.fork_headers.clone())
125            .compute_units_per_second(self.get_compute_units_per_second())
126            .build()
127    }
128
129    /// Configures a new `revm::Env`
130    ///
131    /// If a `fork_url` is set, it gets configured with settings fetched from the endpoint (chain
132    /// id, )
133    pub async fn evm_env(&self) -> eyre::Result<crate::Env> {
134        if let Some(ref fork_url) = self.fork_url {
135            Ok(self.fork_evm_env(fork_url).await?.0)
136        } else {
137            Ok(self.local_evm_env())
138        }
139    }
140
141    /// Returns the `revm::Env` that is configured with settings retrieved from the endpoint,
142    /// and the block that was used to configure the environment.
143    pub async fn fork_evm_env(&self, fork_url: &str) -> eyre::Result<(crate::Env, AnyRpcBlock)> {
144        let provider = self.fork_provider_with_url(fork_url)?;
145        self.fork_evm_env_with_provider(fork_url, &provider).await
146    }
147
148    /// Returns the `revm::Env` that is configured with settings retrieved from the provider,
149    /// and the block that was used to configure the environment.
150    pub async fn fork_evm_env_with_provider<P: Provider<N>, N: Network>(
151        &self,
152        fork_url: &str,
153        provider: &P,
154    ) -> eyre::Result<(crate::Env, N::BlockResponse)> {
155        environment(
156            provider,
157            self.memory_limit,
158            self.env.gas_price.map(|v| v as u128),
159            self.env.chain_id,
160            self.fork_block_number,
161            self.sender,
162            self.disable_block_gas_limit,
163            self.enable_tx_gas_limit,
164            self.networks,
165        )
166        .await
167        .wrap_err_with(|| {
168            let mut msg = "could not instantiate forked environment".to_string();
169            if let Ok(url) = Url::parse(fork_url)
170                && let Some(provider) = url.host()
171            {
172                write!(msg, " with provider {provider}").unwrap();
173            }
174            msg
175        })
176    }
177
178    /// Returns the `revm::Env` configured with only local settings
179    fn local_evm_env(&self) -> crate::Env {
180        let cfg = configure_env(
181            self.env.chain_id.unwrap_or(foundry_common::DEV_CHAIN_ID),
182            self.memory_limit,
183            self.disable_block_gas_limit,
184            self.enable_tx_gas_limit,
185        );
186
187        crate::Env {
188            evm_env: EvmEnv {
189                cfg_env: cfg,
190                block_env: BlockEnv {
191                    number: self.env.block_number,
192                    beneficiary: self.env.block_coinbase,
193                    timestamp: self.env.block_timestamp,
194                    difficulty: U256::from(self.env.block_difficulty),
195                    prevrandao: Some(self.env.block_prevrandao),
196                    basefee: self.env.block_base_fee_per_gas,
197                    gas_limit: self.gas_limit(),
198                    ..Default::default()
199                },
200            },
201            tx: TxEnv {
202                gas_price: self.env.gas_price.unwrap_or_default().into(),
203                gas_limit: self.gas_limit(),
204                caller: self.sender,
205                ..Default::default()
206            },
207        }
208    }
209
210    /// Helper function that returns the [CreateFork] to use, if any.
211    ///
212    /// storage caching for the [CreateFork] will be enabled if
213    ///   - `fork_url` is present
214    ///   - `fork_block_number` is present
215    ///   - `StorageCachingConfig` allows the `fork_url` + chain ID pair
216    ///   - storage is allowed (`no_storage_caching = false`)
217    ///
218    /// If all these criteria are met, then storage caching is enabled and storage info will be
219    /// written to `<Config::foundry_cache_dir()>/<str(chainid)>/<block>/storage.json`.
220    ///
221    /// for `mainnet` and `--fork-block-number 14435000` on mac the corresponding storage cache will
222    /// be at `~/.foundry/cache/mainnet/14435000/storage.json`.
223    pub fn get_fork(&self, config: &Config, env: crate::Env) -> Option<CreateFork> {
224        let url = self.fork_url.clone()?;
225        let enable_caching = config.enable_caching(&url, env.evm_env.cfg_env.chain_id);
226
227        // Pin fork_block_number to the block that was already fetched in env, so subsequent
228        // fork operations use the same block. This prevents inconsistencies when forking at
229        // "latest" where the chain could advance between calls.
230        let mut evm_opts = self.clone();
231        if evm_opts.fork_block_number.is_none() {
232            evm_opts.fork_block_number = Some(env.evm_env.block_env.number.to());
233        }
234
235        Some(CreateFork { url, enable_caching, env, evm_opts })
236    }
237
238    /// Returns the gas limit to use
239    pub fn gas_limit(&self) -> u64 {
240        self.env.block_gas_limit.unwrap_or(self.env.gas_limit).0
241    }
242
243    /// Returns the available compute units per second, which will be
244    /// - u64::MAX, if `no_rpc_rate_limit` if set (as rate limiting is disabled)
245    /// - the assigned compute units, if `compute_units_per_second` is set
246    /// - ALCHEMY_FREE_TIER_CUPS (330) otherwise
247    fn get_compute_units_per_second(&self) -> u64 {
248        if self.no_rpc_rate_limit {
249            u64::MAX
250        } else if let Some(cups) = self.compute_units_per_second {
251            cups
252        } else {
253            ALCHEMY_FREE_TIER_CUPS
254        }
255    }
256
257    /// Returns the chain ID from the RPC, if any.
258    pub async fn get_remote_chain_id(&self) -> Option<Chain> {
259        if let Some(url) = &self.fork_url
260            && let Ok(provider) = self.fork_provider_with_url(url)
261        {
262            trace!(?url, "retrieving chain via eth_chainId");
263
264            if let Ok(id) = provider.get_chain_id().await {
265                return Some(Chain::from(id));
266            }
267
268            // Provider URLs could be of the format `{CHAIN_IDENTIFIER}-mainnet`
269            // (e.g. Alchemy `opt-mainnet`, `arb-mainnet`), fallback to this method only
270            // if we're not able to retrieve chain id from `RetryProvider`.
271            if url.contains("mainnet") {
272                trace!(?url, "auto detected mainnet chain");
273                return Some(Chain::mainnet());
274            }
275        }
276
277        None
278    }
279}
280
281#[derive(Clone, Debug, Default, Serialize, Deserialize)]
282pub struct Env {
283    /// The block gas limit.
284    pub gas_limit: GasLimit,
285
286    /// The `CHAINID` opcode value.
287    pub chain_id: Option<u64>,
288
289    /// the tx.gasprice value during EVM execution
290    ///
291    /// This is an Option, so we can determine in fork mode whether to use the config's gas price
292    /// (if set by user) or the remote client's gas price.
293    #[serde(default, skip_serializing_if = "Option::is_none")]
294    pub gas_price: Option<u64>,
295
296    /// the base fee in a block
297    pub block_base_fee_per_gas: u64,
298
299    /// the tx.origin value during EVM execution
300    pub tx_origin: Address,
301
302    /// the block.coinbase value during EVM execution
303    pub block_coinbase: Address,
304
305    /// the block.timestamp value during EVM execution
306    #[serde(
307        deserialize_with = "foundry_config::deserialize_u64_to_u256",
308        serialize_with = "foundry_config::serialize_u64_or_u256"
309    )]
310    pub block_timestamp: U256,
311
312    /// the block.number value during EVM execution"
313    #[serde(
314        deserialize_with = "foundry_config::deserialize_u64_to_u256",
315        serialize_with = "foundry_config::serialize_u64_or_u256"
316    )]
317    pub block_number: U256,
318
319    /// the block.difficulty value during EVM execution
320    pub block_difficulty: u64,
321
322    /// Previous block beacon chain random value. Before merge this field is used for mix_hash
323    pub block_prevrandao: B256,
324
325    /// the block.gaslimit value during EVM execution
326    #[serde(default, skip_serializing_if = "Option::is_none")]
327    pub block_gas_limit: Option<GasLimit>,
328
329    /// EIP-170: Contract code size limit in bytes. Useful to increase this because of tests.
330    #[serde(default, skip_serializing_if = "Option::is_none")]
331    pub code_size_limit: Option<usize>,
332}
333
334#[cfg(test)]
335mod tests {
336    use super::*;
337
338    #[tokio::test(flavor = "multi_thread")]
339    async fn get_fork_pins_block_number_from_env() {
340        let endpoint = foundry_test_utils::rpc::next_http_rpc_endpoint();
341
342        let config = Config::figment();
343        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
344        evm_opts.fork_url = Some(endpoint.clone());
345        // Explicitly leave fork_block_number as None to simulate --fork-url without --block-number
346        assert!(evm_opts.fork_block_number.is_none());
347
348        // Fetch the environment (this resolves "latest" to an actual block number)
349        let env = evm_opts.evm_env().await.unwrap();
350        let resolved_block = env.evm_env.block_env.number;
351        assert!(resolved_block > U256::ZERO, "should have resolved to a real block number");
352
353        // Create the fork - this should pin the block number
354        let fork = evm_opts.get_fork(&Config::default(), env).unwrap();
355
356        // The fork's evm_opts should now have fork_block_number set to the resolved block
357        assert_eq!(
358            fork.evm_opts.fork_block_number,
359            Some(resolved_block.to::<u64>()),
360            "get_fork should pin fork_block_number to the block from env"
361        );
362    }
363
364    #[tokio::test(flavor = "multi_thread")]
365    async fn get_fork_preserves_explicit_block_number() {
366        let endpoint = foundry_test_utils::rpc::next_http_rpc_endpoint();
367
368        let config = Config::figment();
369        let mut evm_opts = config.extract::<EvmOpts>().unwrap();
370        evm_opts.fork_url = Some(endpoint.clone());
371        // Set an explicit block number
372        evm_opts.fork_block_number = Some(12345678);
373
374        let env = evm_opts.evm_env().await.unwrap();
375
376        let fork = evm_opts.get_fork(&Config::default(), env).unwrap();
377
378        // Should preserve the explicit block number, not override it
379        assert_eq!(
380            fork.evm_opts.fork_block_number,
381            Some(12345678),
382            "get_fork should preserve explicitly set fork_block_number"
383        );
384    }
385}
foundry_evm_core/opts.rs

foundry_evm_core/
opts.rs
