Ctrlk
x-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

replay

Fetch and re-execute an on-chain transaction with optional overrides and tracing.

Re-execute a historical transaction locally using an RPC endpoint or a previously captured fixture file. In online mode, mega-evme fetches the transaction, block environment, and pre-state from the RPC and re-executes locally. In offline mode (--rpc.replay-file), all data is served from a local fixture captured by an earlier run — no network access is required.

Usage

mega-evme replay [OPTIONS] <TX_HASH>

Arguments

TX_HASH

The transaction hash to replay (32-byte hex, required).

mega-evme re-executes the transaction locally using state and block context sourced from either an RPC endpoint or a local fixture file. This gives you a fully reproducible execution without needing a local archive node.

--rpc <URL>

Aliases: --rpc-url

The RPC endpoint to fetch the transaction and state from. Any standard Ethereum JSON-RPC provider works here. Required for online replay and capture mode; omit when using --rpc.replay-file.

mega-evme replay --rpc https://mainnet.megaeth.com/rpc <TX_HASH>

RPC Cache File

mega-evme replay supports a transport-level JSON-RPC fixture mechanism that records every request/response pair to a single file and serves them back on later runs without touching the network. It is useful for pinning a reproducible replay (e.g. for regression tests, debugging sessions, or offline review) and for running replay in environments that cannot reach the RPC endpoint.

Unlike the generic RPC Cache, which is keyed on a small allow-list of cacheable methods and stored per chain under the platform cache directory, the cache file covers every single (non-batch) JSON-RPC call issued during the replay and lives at a user-chosen path.

The mechanism has two modes, selected by two mutually exclusive flags.

--rpc.capture-file <PATH>

Capture mode. Requires --rpc.

On the first run, every JSON-RPC request and response issued while serving the replay is captured in memory and the complete envelope is written to <PATH> atomically on clean exit. On subsequent runs the existing file is loaded, its entries are merged into the in-memory transport cache, and only missing requests are fetched from the RPC endpoint. The updated set of entries is persisted back to the same file on clean exit.

The file also embeds an external-environment snapshot — currently the set of --bucket-capacity values in effect — so the captured fixture is self-contained. If --bucket-capacity is not passed on a subsequent run, the previous envelope's values are reused; passing --bucket-capacity overrides them.

--rpc.capture-file is mutually exclusive with --rpc.replay-file, --rpc.cache-dir, --rpc.clear-cache, --rpc.no-cache-file, and --rpc.cache-size.

--rpc.replay-file <PATH>

Replay mode. Requires neither --rpc nor network access.

The envelope at <PATH> is loaded and serves as the only source of JSON-RPC responses. Any request that is not present in the fixture aborts the run with a hard error — there is no fall-through to a live RPC endpoint.

Bucket-capacity data is read from the fixture envelope, so --bucket-capacity is neither required nor accepted with --rpc.replay-file. Passing --bucket-capacity together with --rpc.replay-file is rejected; to regenerate a fixture with new capacities, re-run in capture mode.

--rpc.replay-file is mutually exclusive with --rpc, --rpc.capture-file, --rpc.cache-dir, --rpc.clear-cache, --rpc.no-cache-file, and --rpc.cache-size.

Examples

Capture a transaction's RPC traffic to a fixture file (first run hits the endpoint, later runs with the same flag reuse and top up the file):

Replay the captured transaction fully offline:

Self-Validating Fixture Dump

--dump-fixture <FILE> turns a single replay into a self-validating regression fixture. The fixture is written in the same EEST state-test schema that the state-test runner consumes (TestUnit { env, pre, transaction, post, out }), so re-running it through state-test re-executes the transaction and checks the result — no RPC access required.

--dump-fixture <FILE>

Dump a self-validating fixture for the replayed transaction to <FILE>.

The fixture captures everything needed to deterministically re-execute the target transaction in isolation:

  • pre — the pre-state read closure (every account and storage slot the transaction touched), with their pre-transaction values.

  • env — the block environment (number, timestamp, coinbase, base fee, gas limit, prevrandao, excess blob gas).

  • transaction — the target transaction.

  • megaEnv — a MegaETH-specific extension carrying the SALT bucket capacities and oracle storage in effect, so dynamic storage-gas pricing reproduces exactly. Pure-Ethereum fixtures omit this field.

  • post — the expected result for the executed spec: state-root and logs-root, plus explicit megaGasUsed and megaStatus expectations that produce readable diffs on mismatch.

The post expectation is computed by the state-test runner itself — the exact code path that later validates the fixture — so a dumped fixture is self-consistent by construction.

Fidelity gate. Before building the fixture, the dump fetches the transaction's on-chain receipt and requires the local replay to reproduce the receipt's gasUsed, success status, and logs root exactly. Logs are compared explicitly rather than inferred from gas: LOG gas depends on topic count and data length, never content, so two executions can burn identical gas yet emit different log payloads. A mismatch aborts the dump (no file is written) with a clear error — this catches a wrong spec or hardfork config, which self-validation alone cannot, because the fixture is validated under the same spec it was dumped with. It then additionally cross-checks the isolated execution against the full replay (gas, status — including the exact halt reason for halted transactions — output, and logs root), so any gas-, output-, or log-visible divergence — including across the L1 data fee, which the isolated run zeroes but the full replay charges — aborts the dump. One channel stays open by construction: the isolated run's sender balance is shifted by the zeroed L1 fee, so a contract that stores a balance-derived value bakes that shifted value into post (and the sender's final balance in post likewise differs from the chain). The fixture still self-validates and reproduces gas exactly; only such balance-derived state values differ.

--dump-fixture cannot be combined with transaction overrides or --override.spec (a forced spec would record a what-if, not the on-chain transaction), and deposit transactions are not supported. A target transaction that reads a block hash via BLOCKHASH is also rejected: fixtures carry no historical block hashes, so the isolated re-execution could not reproduce the values the replay observed. Block hash reads by preceding transactions in the same block do not matter — only the target transaction's reads are checked. Because the fidelity gate reads the receipt, an offline dump (--rpc.replay-file) requires the receipt to be present in the capture — so capture and dump together in the online run, then re-dump offline reproducibly. When combined with --rpc.capture-file, the capture file is written even if execution or the fidelity gate fails, so the captured RPC responses remain available for debugging the failure offline.

Throughput Benchmark

To benchmark a replayed transaction, dump it to a fixture and time the fixture with the state-test runner — there is no replay-side benchmark flag:

state-test --bench reports min / median / mean time and throughput (Mgas/s), timing only the EVM transact call. A committed corpus of characteristic transactions and a base-vs-PR comparison driver build on this to track real-transaction throughput across changes; see bench/replay/ and the replay-bench CI workflow.

Spec Auto-Detection

The EVM spec controls which opcodes, gas rules, and MegaETH-specific behaviors are active during execution. replay auto-detects the spec from the chain ID and the block timestamp of the replayed transaction. Hardcoded hardfork configs exist for:

  • Chain 6343 — MegaETH testnet v2

  • Chain 4326 — MegaETH mainnet

For any other chain, replay enables all hardforks at genesis (currently equivalent to Rex5).

--override.spec <SPEC>

Override the auto-detected spec. Useful when you want to test how the transaction would behave under a different spec, or when replaying against a chain that isn't recognized.

Transaction Overrides

Override flags let you modify the transaction before re-executing it. The original on-chain transaction is unchanged; only the local replay is affected. This is useful for "what-if" testing: what happens with less gas, different calldata, or a different ETH value?

Flag
Aliases
Description

--override.gas-limit <GAS>

--override.gaslimit

Replace the transaction's gas limit

--override.value <VALUE>

Replace the ETH value sent (supports 1ether, 100gwei suffixes)

--override.input <HEX>

--override.data

Replace the calldata with a hex-encoded byte string

--override.input-file <FILE>

--override.data-file

Replace the calldata with the contents of a file

Note that replay does not accept --chain, block environment flags, or pre-state flags. All of that context comes from the RPC.

Options

replay supports the following shared option groups. See the linked pages for full details.

  • SALT buckets — Configure SALT bucket capacity for dynamic storage gas pricing. See SALT Buckets.

  • State dump — Dump or load pre/post-state snapshots. See State Management.

  • RPC cache file — Single-file JSON-RPC capture and offline replay via --rpc.capture-file / --rpc.replay-file. See RPC Cache File above.

  • RPC cache / retry — Per-chain response cache, retry, and rate-limit settings. See RPC Cache and Retry.

  • Tracing — Emit execution traces (call traces, opcode traces, gas profiles, etc.). See Tracing Overview.

  • Fixture dump — Write a self-validating EEST state-test fixture via --dump-fixture. See Self-Validating Fixture Dump above.

  • Throughput benchmark — Dump a fixture (--dump-fixture) and time it with state-test --bench. See Throughput Benchmark above.

Examples

In all examples below, replace 0xabc123... with a real transaction hash from MegaETH mainnet. Every replay invocation requires one of --rpc <URL>, --rpc.capture-file <PATH>, or --rpc.replay-file <PATH>.

Replay against a live RPC

Replay with call tracing

Replay with a tighter gas limit

Replay with different calldata

Replay under a specific spec

See Also

  • run — Execute raw EVM bytecode locally without fetching from RPC

  • tx — Send a new transaction against a local state

  • Tracing Overview

  • SALT Buckets

  • State Management

PrevioustxNextChain and Spec

Last updated