State Management
Load prestate, override balances and storage, fork from RPC, and dump post-execution state.
mega-evme lets you control the EVM's initial account state, override balances and storage, fork live chain state, and capture the post-execution state for inspection or reuse. These options are available in the run and tx commands.
Loading Initial State
Prestate Files
A prestate file is a JSON document that seeds the EVM with account state before execution begins. Use --prestate (alias --pre-state) to load one:
mega-evme run --prestate ./state.json ...The file maps addresses to account objects. See State File Format for the exact schema.
Sender Balance
--sender.balance (alias --from.balance) sets the balance of the transaction sender directly, without needing a full prestate file. It accepts human-friendly suffixes:
mega-evme run --sender.balance 1ether ...
mega-evme run --sender.balance 100gwei ...
mega-evme run --sender.balance 1000wei ...This is a shortcut for the common case of funding the sender before a test run.
Faucet
--faucet adds ether on top of an address's existing balance. The format is ADDRESS+=VALUE:
mega-evme run --faucet 0x4200000000000000000000000000000000000006+=1ether ...The flag is repeatable, so you can fund multiple addresses at once:
Ether suffixes (ether, gwei, wei) are supported.
Balance Overrides
--balance sets (replaces) an address's balance to an exact value. The format is ADDRESS=VALUE:
Unlike --faucet, this overwrites whatever balance the address already has. The flag is repeatable and supports ether suffixes.
Faucet vs balance at a glance:
--faucet ADDRESS+=VALUE
Adds VALUE to existing balance
--balance ADDRESS=VALUE
Sets balance to exactly VALUE
Storage Overrides
--storage sets a specific storage slot on an address before execution. The format is ADDRESS:SLOT=VALUE:
The flag is repeatable, so you can override multiple slots across multiple contracts:
Block Hash Overrides
--block-hash (aliases --blockhash, --block-hashes, --blockhashes) controls what the BLOCKHASH opcode returns for a given block number. The format is BLOCK_NUMBER:BLOCK_HASH:
The flag is repeatable for multiple block numbers:
This is useful when testing contracts that branch on historical block hashes.
Fork Mode
Fork mode fetches account state from a live RPC endpoint instead of starting from an empty state. Enable it with --fork, which requires --rpc:
There is no default endpoint, and the RPC_URL environment variable is not consulted — --rpc must be passed explicitly. Set the endpoint with --rpc (aliases --rpc-url, --fork.rpc) and pin a specific block with --fork.block:
All local override flags (--prestate, --faucet, --balance, --storage) apply on top of the forked state. This lets you layer local modifications over a real chain snapshot without modifying the remote node.
Dumping State
--dump prints the full post-execution account state to stdout after the run completes. Use --dump.output to write it to a file instead:
The output uses the same JSON format as prestate files, so you can feed it directly back into --prestate.
State File Format
Fields
Each top-level key is a checksummed or lowercase hex address. The value is an account object with these fields:
balance
hex quantity
Account balance in wei
nonce
hex quantity
Transaction nonce
code
hex bytes
Deployed bytecode (0x for EOAs)
codeHash
hex bytes
Keccak256 hash of code
storage
object
Map of storage slot to value
Example:
Format Notes
All numeric values use Ethereum quantity encoding:
0xprefix is required.No leading zeros, except
0x0for zero.balanceis in wei.Storage keys and values are 32-byte hex strings (zero-padded to 64 hex characters).
RPC Cache and Retry
When using fork mode, mega-evme caches RPC responses to avoid redundant network calls and supports configurable retry behavior for resilience against transient failures.
These options take effect only when an RPC endpoint is actually contacted: on run and tx that requires --fork (without --fork they are accepted but silently ignored); on replay they apply to its --rpc fetches (an offline --rpc.replay-file run contacts no endpoint and does not use them).
Per-Chain Cache Files
Each chain gets its own cache file named rpc-cache-{chain_id}.json inside the cache directory. The per-chain filename makes cross-chain contamination impossible by construction: a cache populated from mainnet physically cannot be loaded during a testnet run.
The default cache directory is the platform cache directory:
Linux:
$XDG_CACHE_HOME/mega-evme/rpcmacOS:
~/Library/Caches/mega-evme/rpc
Cache Flags
--rpc.cache-size <N>
u32
10000
Maximum number of items in the in-memory RPC LRU cache. Set to 0 to disable the cache layer entirely.
--rpc.cache-dir <PATH>
path
Platform cache dir
Directory for per-chain cache files. Each chain's cache is stored as {cache_dir}/rpc-cache-{chain_id}.json.
--rpc.no-cache-file
flag
false
Disable on-disk cache persistence. The in-memory LRU cache still applies — use --rpc.cache-size 0 to disable that too.
--rpc.clear-cache
flag
false
Delete the current chain's cache file before loading it. Recovery path for a polluted or corrupt cache.
Retry Flags
--rpc.max-retries <N>
u32
5
Maximum retry attempts for failing RPC requests. Retries on HTTP 429/503, rate-limit errors, and transport failures. 0 to disable.
--rpc.backoff-ms <MS>
u64
1000
Fixed sleep duration in milliseconds between retry attempts (no exponential backoff).
--rpc.rate-limit <CU/s>
u64
660
Compute units per second budget for the retry layer's rate-limit accounting.
Examples
Replay a transaction with a local per-chain cache directory (a warm cache avoids redundant RPC calls on later runs):
The per-chain cache supplements --rpc; it does not replace it. For a fully offline replay, capture a single-file fixture and replay it with --rpc.replay-file (see replay).
Disable on-disk caching but keep the in-memory LRU:
Clear a corrupt cache before replaying:
Round-Trip Example
Dump state after a first run, tweak it, then replay with the modified state:
This pattern is useful for multi-step test scenarios where each run builds on the output of the previous one. Combine with --faucet or --balance to patch specific accounts without editing the JSON by hand.
Last updated