Struct EvmOpts 

pub struct EvmOpts {

    pub env: Env,
    pub fork_url: Option<String>,
    pub fork_block_number: Option<u64>,
    pub fork_state_by_number: bool,
    pub fork_retries: Option<u32>,
    pub fork_retry_backoff: Option<u64>,
    pub fork_headers: Option<Vec<String>>,
    pub rpc_jwt: Option<String>,
    pub rpc_headers: Option<Vec<String>>,
    pub rpc_timeout: Option<u64>,
    pub rpc_accept_invalid_certs: bool,
    pub rpc_no_proxy: bool,
    pub compute_units_per_second: Option<u64>,
    pub no_rpc_rate_limit: bool,
    pub no_storage_caching: bool,
    pub no_fork_bal: bool,
    pub initial_balance: U256,
    pub sender: Address,
    pub ffi: bool,
    pub always_use_create_2_factory: bool,
    pub verbosity: u8,
    pub memory_limit: u64,
    pub isolate: bool,
    pub disable_block_gas_limit: bool,
    pub enable_tx_gas_limit: bool,
    pub networks: NetworkConfigs,
    pub create2_deployer: Address,
    pub fork_endpoint: Option<ForkEndpointIdentity>,
    pub expected_fork_endpoint: Option<ForkEndpointIdentity>,
    pub fork_network_is_inferred: bool,
    pub fork_chain_id_is_inferred: bool,
    pub fork_block_number_is_inferred: bool,
}

EVM execution options, including the configured remote fork.

Fork handling separates two responsibilities. Endpoint discovery identifies and caches the execution family without selecting a block. Exact resolution binds the configured source and selector to a block number, hash, and endpoint context. Forge normally performs discovery before resolution, while callers that already know the network can resolve directly.

Resolution revalidates the endpoint identity around its remote reads. A cached discovery that found no Anvil identity has nothing to revalidate and is reused instead, so the chain ID and the anvil_nodeInfo probe of such an endpoint are requested once, by discovery.

An implicit latest selector remains unchanged in these options; only the returned Fork is pinned to the exact block observed during resolution.

Fields

env: Env

The EVM environment configuration.

fork_url: Option<String>

Fetch state over a remote instead of starting from empty state.

fork_block_number: Option<u64>

Pins the block number for the state fork.

fork_state_by_number: bool

Fetch fork state by block number for RPCs that cannot serve it by hash.

fork_retries: Option<u32>

The number of retries.

fork_retry_backoff: Option<u64>

Initial retry backoff.

fork_headers: Option<Vec<String>>

Headers to use with fork_url

rpc_jwt: Option<String>

JWT secret to use with the configured RPC endpoint.

rpc_headers: Option<Vec<String>>

Headers to use with the configured RPC endpoint.

rpc_timeout: Option<u64>

Request timeout to use with the configured RPC endpoint.

rpc_accept_invalid_certs: bool

Whether to accept invalid certificates from the configured RPC endpoint.

rpc_no_proxy: bool

Whether to disable automatic proxy detection for the configured RPC endpoint.

compute_units_per_second: Option<u64>

The available compute units per second.

See also https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second

no_rpc_rate_limit: bool

Disables RPC rate limiting entirely.

no_storage_caching: bool

Disables storage caching entirely.

no_fork_bal: bool

Disables parent-block BAL cache prewarming for transaction-hash forks.

initial_balance: U256

The initial balance of each deployed test contract.

sender: Address

The address which will be executing all tests.

ffi: bool

Enables the FFI cheatcode.

always_use_create_2_factory: bool

Use the create 2 factory in all cases including tests and non-broadcasting scripts.

verbosity: u8

Verbosity mode of EVM output as number of occurrences.

memory_limit: u64

The memory limit per EVM execution in bytes. If this limit is exceeded, a MemoryLimitOOG result is thrown.

isolate: bool

Whether to enable isolation of calls.

disable_block_gas_limit: bool

Whether to disable block gas limit checks.

enable_tx_gas_limit: bool

Whether to enable tx gas limit checks as imposed by Osaka (EIP-7825).

networks: NetworkConfigs

Networks with enabled features.

create2_deployer: Address

The CREATE2 deployer’s address.

fork_endpoint: Option<ForkEndpointIdentity>

Most recently discovered endpoint identity, cached for network dispatch and revalidation.

An identity without Anvil metadata also stands in for later identity snapshots of the same endpoint.

expected_fork_endpoint: Option<ForkEndpointIdentity>

Endpoint identity promoted to an invariant that later discovery must match.

fork_network_is_inferred: bool

Whether the active network selection was inferred from the fork endpoint.

fork_chain_id_is_inferred: bool

Whether env.chain_id was inferred from the fork endpoint.

fork_block_number_is_inferred: bool

Whether fork_block_number was pinned from the fork endpoint’s latest block.

Implementations

impl EvmOpts

fn clear_endpoint_derived_fork_state(&mut self)

Clears state derived from a fork endpoint while preserving explicit configuration.

pub fn set_fork_url(&mut self, fork_url: String)

Selects a new fork URL and clears endpoint-derived state from the previous source.

pub fn invalidate_fork_endpoint_if_source_changed( &mut self, fork: &Fork, ) -> bool

Invalidates endpoint-derived state when the effective RPC source changed since fork was resolved.

The effective source consists of the URL, active headers, and JWT. Explicit block, network, and chain-ID selections are retained so the new source is resolved under the same user configuration.

pub fn set_explicit_network(&mut self, network: NetworkVariant)

Applies an explicit network override, replacing any endpoint-inferred selection.

pub fn expect_fork_endpoint( &mut self, identity: ForkEndpointIdentity, network_is_inferred: bool, )

Requires subsequent local fork construction to use this exact endpoint identity.

fn ensure_expected_fork_endpoint( &self, identity: &ForkEndpointIdentity, ) -> Result<()>

fn ensure_inferred_execution_profile( &self, identity: &ForkEndpointIdentity, ) -> Result<()>

Rejects an inferred network whose endpoint now reports a different execution profile.

pub(crate) fn chain_id_override(&self) -> Option<ChainId>

fn endpoint_network_fallback(&self) -> NetworkConfigs

fn anvil_node_info_probe(&self) -> AnvilNodeInfoProbe

fn discovered_non_anvil_chain_id( &self, node_info_probe: AnvilNodeInfoProbe, ) -> Option<ChainId>

Returns the chain ID of the configured endpoint if its cached discovery found no Anvil identity.

Without Anvil node info the identity is derived from the chain ID alone: there is no instance, hardfork, or upstream fork that a reset could change between two reads. Later snapshots of the same endpoint therefore reuse the discovered chain ID instead of requesting eth_chainId and probing anvil_nodeInfo again. An endpoint that node_info_probe or a cached identity identifies as Anvil is never reused and keeps its strict revalidation.

pub(crate) fn fork_source_headers(&self) -> Option<&[String]>

pub async fn pin_fork_block(&mut self) -> Result<Option<BlockNumber>>

Converts an implicit latest selector into a block-number selector in place.

This only reads the endpoint’s current block number; it does not resolve a block hash or endpoint identity and is therefore not a reorg-safe fork snapshot. Create a Backend when preflight and execution must share an exact identity.

pub(crate) async fn prepare_fork(&self) -> Result<Option<Fork>>

Resolves the configured fork source and selector to an exact snapshot without changing self.

Endpoint identity is read before and after the target block and the operation is retried if it changes. The result binds the configured RPC source, configured selector, exact block number and hash, and ForkContext. When the selector is implicit latest, only the returned Fork is pinned.

pub(crate) async fn can_use_create2_deployer_at( &self, fork: Option<&Fork>, ) -> Result<bool>

Returns whether the configured CREATE2 deployer existed at the resolved fork block.

pub(crate) fn provider_for_fork<N: Network>( &self, fork: &Fork, ) -> Result<RootProvider<N>>

Returns a provider configured for an already resolved fork.

pub(crate) async fn check_fork_endpoint<N: Network, P: Provider<N>>( &self, provider: &P, fork: &Fork, ) -> Result<()>

pub(crate) async fn transaction_count_at_fork( &self, account: Address, fork: &Fork, ) -> Result<u64>

Returns an account nonce at the exact block and endpoint identity of fork.

pub fn fork_provider_with_url<N: Network>( &self, fork_url: &str, ) -> Result<RootProvider<N>>

Returns a RootProvider for the given fork URL configured with options in self and annotated Network type.

pub(crate) fn fork_rpc_client(&self, fork_url: &str) -> Result<RpcClient>

pub async fn infer_network_from_fork(&mut self) -> Result<()>

Discovers and caches the network configuration and endpoint identity for a fork.

This is the dispatch phase of fork setup: explicit network selections are preserved, while inferred chain and network settings are applied when no override exists. The method does not resolve or pin a fork block; block resolution happens during backend creation or through Self::env_with_fork_context. Repeated calls only inspect the endpoint again as described by Self::fork_endpoint_identity.

pub async fn discover_fork_endpoint(&self) -> Result<ForkEndpointIdentity>

Discovers a stable identity snapshot without selecting a fork block.

Each attempt reads eth_chainId and the optional Anvil identity methods before and after, and returns only when both snapshots agree. Before Anvil is positively identified, a failed anvil_nodeInfo probe is treated as absence of optional Anvil identity information: the identity then depends on the chain ID alone and is returned from the first snapshot without a confirming one. Later probe failures are strict. This method does not mutate or cache the returned identity in self.

pub async fn fork_endpoint_identity(&self) -> Result<ForkEndpointIdentity>

Returns the identity of the configured fork endpoint, inspecting it only when necessary.

A cached discovery that found no Anvil identity is returned without new requests. Anvil endpoints and endpoints without a cached discovery are inspected through Self::discover_fork_endpoint, so a reset or execution-profile change of an Anvil endpoint is still observed.

async fn resolve_fork_endpoint_once<N: Network, P: Provider<N>>( &self, provider: &P, node_info_probe: &mut AnvilNodeInfoProbe, hardfork_policy: EndpointHardforkPolicy, ) -> Result<ForkEndpointIdentity>

Reads one endpoint identity snapshot without performing a stability check.

The shared node-info probe starts permissive for endpoints that do not expose Anvil methods and becomes strict after Anvil is identified. Callers either bracket mutable remote reads with two snapshots or use this helper to revalidate an already resolved fork. No request is sent for an endpoint whose cached discovery found no Anvil identity.

async fn resolve_fork_endpoint_identity<N: Network, P: Provider<N>>( provider: &P, endpoint: &str, execution_chain_id: ChainId, node_info: Option<NodeInfo>, unknown_fallback: Option<NetworkConfigs>, hardfork_policy: EndpointHardforkPolicy, ) -> Result<ForkEndpointIdentity>

Builds an identity from one observed chain ID and optional Anvil node-info response.

Anvil metadata is consulted only after node info has positively identified the endpoint.

fn non_anvil_fork_endpoint_identity( endpoint: &str, execution_chain_id: ChainId, unknown_fallback: Option<NetworkConfigs>, ) -> Result<ForkEndpointIdentity>

Builds the identity of an endpoint that exposes no Anvil node info from its chain ID.

pub async fn env_with_fork_context<SPEC: Into<SpecId> + Default + Copy, BLOCK: FoundryBlock + Default, TX: FoundryTransaction + Default>( &self, ) -> Result<(EvmEnv<SPEC, BLOCK>, TX, Option<ForkContext>)>

Returns standalone execution environments and the remote source context, if any.

Execution workflows with a backend use its selected block through Backend::env.

pub(crate) async fn env_at_fork<SPEC: Into<SpecId> + Default + Copy, BLOCK: FoundryBlock + Default, TX: FoundryTransaction + Default>( &self, fork: Option<&Fork>, ) -> Result<(EvmEnv<SPEC, BLOCK>, TX)>

Returns the EVM and transaction environments at an already resolved fork.

fn fork_env_error_context(&self) -> String

async fn resolve_fork_block_with_context<N: Network, P: Provider<N>>( &self, provider: &P, target: BlockNumberOrTag, node_info_probe: &mut AnvilNodeInfoProbe, ) -> Result<(N::BlockResponse, BlockNumHash, ForkContext)>

pub(crate) fn fork_env_from_block<SPEC: Into<SpecId> + Default + Copy, BLOCK: FoundryBlock + Default, N: Network>( &self, chain_id: ChainId, source_chain_id: ChainId, block: &N::BlockResponse, ) -> EvmEnv<SPEC, BLOCK>

fn local_evm_env<SPEC: Into<SpecId> + Default + Clone, BLOCK: FoundryBlock + Default>( &self, ) -> EvmEnv<SPEC, BLOCK>

Returns the EvmEnv configured with only local settings.

fn fork_tx_env<TX: FoundryTransaction + Default>( &self, gas_price: u128, chain_id: ChainId, ) -> TX

Returns the TxEnv with gas price and chain ID from a stable fork snapshot.

fn local_tx_env<TX: FoundryTransaction + Default>(&self) -> TX

Returns the TxEnv configured from local settings only.

fn cfg_env<SPEC: Into<SpecId> + Default + Clone>( &self, chain_id: ChainId, ) -> CfgEnv<SPEC>

Builds a [CfgEnv] from the options, using the provided [ChainId].

pub fn get_fork( &self, config: &Config, chain_id: u64, fork_block_number: Option<BlockNumber>, ) -> Option<CreateFork>

Helper function that returns the CreateFork to use, if any.

storage caching for the CreateFork will be enabled if

• fork_url is present
• fork_block_number is present
• StorageCachingConfig allows the fork_url + source chain ID pair
• storage is allowed (no_storage_caching = false)

If all these criteria are met, then storage caching is enabled and storage info will be written to <Config::foundry_cache_dir()>/<str(chainid)>/<block>/storage.json.

for mainnet and --fork-block-number 14435000 on mac the corresponding storage cache will be at ~/.foundry/cache/mainnet/14435000/storage.json. fork_block_number is the actual block number to pin the fork to. This must be the real chain block number, not a remapped value. On some L2s (e.g., Arbitrum) block_env.number is remapped to the L1 block number, so callers must pass the block number in the context returned by EvmOpts::env_with_fork_context instead.

RPC storage caching uses the source chain ID of the discovered fork endpoint. Discover the endpoint first, for example with EvmOpts::infer_network_from_fork. Without it, chain_id decides caching.

pub fn gas_limit(&self) -> u64

Returns the gas limit to use

const fn get_compute_units_per_second(&self) -> u64

Returns the available compute units per second, which will be

• u64::MAX, if no_rpc_rate_limit if set (as rate limiting is disabled)
• the assigned compute units, if compute_units_per_second is set
• ALCHEMY_FREE_TIER_CUPS (330) otherwise

pub async fn get_remote_chain_id(&self) -> Option<Chain>

Returns the chain ID from the RPC, if any.

Trait Implementations

impl Clone for EvmOpts

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EvmOpts

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for EvmOpts

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for EvmOpts

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for EvmOpts

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 816 bytes