feat: add --megaeth EVM mode

.github/workflows/megaeth-live-validate.yml

@@ -0,0 +1,92 @@
+name: MegaETH Live Cross-Validation
+
+# Runs the `megaeth_live_cross_validate` test, which installs the upstream
+# `mega-evme` binary from crates.io and executes the same bytecodes through
+# both engines, failing if forge's `--megaeth` output drifts from the library
+# reference.
+#
+# Not in the default Build & Test workflow because the first run compiles
+# mega-evme (revm + alloy, ~2 minutes) and requires network access.
+
+on:
+  schedule:
+    # Daily 00:00 UTC — catches mega-evm version/semantics drift quickly.
+    # With cache hits this runs in ~5 min.
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+  # Trigger on changes to the MegaETH integration code or the test itself.
+  # Errs on the side of over-triggering — the whole point of this workflow is
+  # consistency, so a broad filter is cheaper than missing a drift.
+  pull_request:
+    paths:
+      # Full EVM core + inspectors: backend, inspect_mega, result conversion,
+      # opts (validate_megaeth), inspector stack, etc.
+      - "crates/evm/core/src/**"
+      - "crates/evm/evm/src/**"
+      # Forge command plumbing: test / coverage / multi_runner / runner
+      - "crates/forge/src/cmd/**"
+      - "crates/forge/src/multi_runner.rs"
+      - "crates/forge/src/runner.rs"
+      # CLI flag + config definitions
+      - "crates/common/src/evm.rs"
+      - "crates/config/src/lib.rs"
+      # Tests + fixtures
+      - "crates/forge/tests/cli/megaeth.rs"
+      - "testdata/megaeth/**"
+      # Dependency pins
+      - "Cargo.toml"
+      - "Cargo.lock"
+      # Workflow itself
+      - ".github/workflows/megaeth-live-validate.yml"
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: full
+  RUST_MIN_STACK: 4194304
+  MEGA_EVME_VERSION: "1.5.1"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  live-validate:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install nextest
+        uses: taiki-e/install-action@nextest
+
+      # Cache the `cargo install mega-evme` output so only the first run
+      # (or a version bump) pays the ~2 minute compile cost.
+      - name: Cache mega-evme install
+        id: cache-mega-evme
+        uses: actions/cache@v4
+        with:
+          path: target/mega-evme-${{ env.MEGA_EVME_VERSION }}
+          key: mega-evme-${{ env.MEGA_EVME_VERSION }}-${{ runner.os }}
+
+      - name: Build forge tests
+        run: cargo build -p forge --tests
+
+      # Runs all 8 `megaeth_*` tests, including the normally-ignored
+      # `megaeth_live_cross_validate` (via --run-ignored=all). The live test
+      # installs mega-evme from crates.io on the first run; subsequent runs
+      # hit the cache above.
+      - name: Run megaeth tests (including live cross-validation)
+        run: >
+          cargo nextest run -p forge --test cli
+          -E 'test(~megaeth)'
+          --run-ignored=all
+          --no-fail-fast

.gitignore

@@ -10,4 +10,9 @@ out.json
 node_modules
 dist
 bin
-_
+_
+
+# testdata/megaeth installs forge-std via `forge install` — keep it untracked.
+/testdata/megaeth/lib/
+/testdata/megaeth/cache/
+/testdata/megaeth/out/

CLAUDE.md

@@ -113,3 +113,38 @@ When the agent is requested to implement a new feature or bug fix, it should con
   When writing markdown or similar format files, put each sentence in a separate line.
 - **Review guidelines are in `REVIEW.md`.**
   Refer to it for code review conventions and fork-specific review rules.
+
+## MegaETH Integration
+
+This fork adds `forge test --megaeth` and `forge coverage --megaeth`, routing execution through the [`mega-evm`](https://crates.io/crates/mega-evm) library instead of stock revm.
+
+### Where the integration lives
+
+| Concern | Path |
+| --- | --- |
+| EVM execution entry point | `crates/evm/core/src/backend/{mod,cow}.rs` (`inspect_mega`) |
+| MegaCtx inspector fan-out | `crates/evm/evm/src/inspectors/stack.rs` |
+| CLI flag validation | `crates/evm/core/src/opts.rs` (`EvmOpts::validate_megaeth`) |
+| Test / coverage command guards | `crates/forge/src/cmd/{test,coverage}/*` |
+| Builder + inline-config guards | `crates/forge/src/{multi_runner,runner}.rs` |
+| Result/state conversion | `crates/evm/core/src/evm.rs` (`convert_mega_result_and_state`) |
+| E2E tests | `crates/forge/tests/cli/megaeth.rs` |
+| Manual test fixtures | `testdata/megaeth/` (forge-std lib is gitignored) |
+| Live cross-validation CI | `.github/workflows/megaeth-live-validate.yml` (daily + on PR touching mega paths) |
+
+### Caveats when modifying MegaETH code
+
+- **`mega-evm` version is pinned.**
+  Bumping it requires updating the `MEGA_EVME_VERSION` constant in `crates/forge/tests/cli/megaeth.rs` AND the hardcoded reference values in `testdata/megaeth/test/CrossValidate.t.sol` (e.g. `MEGA_EVME_REFERENCE_GAS = 95086`).
+  Run `cargo nextest run -p forge --test cli megaeth_live_cross_validate --run-ignored=only` locally to regenerate.
+- **`--megaeth` + `--isolate` / `--fork-url` / `--gas-report` must stay rejected.**
+  Silent degradation is worse than a hard error.
+  Any new code path that builds a runner or executes tests under MegaETH must call `EvmOpts::validate_megaeth()` before any network request.
+- **Cheatcodes are skipped under `--megaeth`.**
+  Do not add `vm.*` calls to `testdata/megaeth/` tests — they appear to succeed but do nothing.
+- **System contract deployment must be idempotent.**
+  `Backend::ensure_system_contract` checks `code_hash` before writing and preserves existing `balance` / `nonce`.
+  Mirrors mega-evme's pattern — do not revert to `AccountInfo::default()`.
+- **`MegaCtx<'a, E>` is generic over the external-env provider.**
+  Defaults to `TestExternalEnvs` (empty oracle, `MIN_BUCKET_SIZE` SALT buckets).
+  A fork-backed implementation should plug in as `MegaCtx<'_, ForkExternalEnvs>` rather than replacing the alias — inspector impls are `impl<E: ExternalEnvTypes> Inspector<MegaCtx<'_, E>>`.