State overrides for simulation RPC calls (eth_call and eth_estimateGas).

State overrides let a call run against a modified view of the chain state without sending any transaction: spoof an account's balance or nonce, replace the code at an address (e.g. run a contract that is not deployed), or rewrite individual storage slots. They are supported by all major execution clients (geth, reth, anvil, ...).

Pass them to Ethers.call/2, Ethers.estimate_gas/2 (and by extension any generated contract function piped into those) with the :state_overrides option:

MyToken.transfer(receiver, 1000)
|> Ethers.call(
  from: whale,
  state_overrides: %{
    whale => %{balance: Ethers.Utils.to_wei(100)},
    token_address => %{state_diff: %{balance_slot => balance_value}}
  }
)

Structure

A state override set is a map of address => account override. Following Ethers conventions, every value has exactly one accepted representation — native types, never hex strings:

• :balance - fake balance to set for the account (non_neg_integer)
• :nonce - fake nonce to set for the account (non_neg_integer)
• :code - fake EVM bytecode to inject into the account (raw binary, not hex encoded — hex decode first if you have "0x..." bytecode e.g. from eth_getCode)
• :state - fake key-value mapping to override all slots in the account storage
• :state_diff - fake key-value mapping to override individual slots in the account storage (all other slots keep their on-chain values)

:state and :state_diff are mutually exclusive per account. Their keys (storage slots) and values (storage words) accept a non_neg_integer or a raw 32-byte binary (e.g. a keccak-derived mapping slot), and are encoded as 32-byte hex words.

Addresses are hex strings ("0x..."), like everywhere else in Ethers.