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: Uint<256, 4>,
    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: Uint<256, 4>

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

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.

pub async fn pin_fork_block(&mut self) -> Result<Option<u64>, Report>

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 fn fork_provider_with_url<N>( &self, fork_url: &str, ) -> Result<RootProvider<N>, Report>

where N: Network,

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

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

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, Report>

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, Report>

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.

pub async fn env_with_fork_context<SPEC, BLOCK, TX>( &self, ) -> Result<(EvmEnv<SPEC, BLOCK>, TX, Option<ForkContext>), Report>

where SPEC: Into<SpecId> + Default + Copy, BLOCK: FoundryBlock + Default, TX: FoundryTransaction + Default,

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

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

pub fn get_fork( &self, config: &Config, chain_id: u64, fork_block_number: Option<u64>, ) -> 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

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) -> EvmOpts

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<(), Error>

Formats the value using the given formatter.

impl Default for EvmOpts

fn default() -> EvmOpts

Returns the “default value” for a type.

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

fn deserialize<__D>( __deserializer: __D, ) -> Result<EvmOpts, <__D as Deserializer<'de>>::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 as Serializer>::Ok, <__S as Serializer>::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