feat(evm): support optional revmc JIT execution (#227)

* feat(evm): support optional revmc JIT execution

Pin revmc to the exact revision the reth pin locks (incl. the revmc#394
and #400 compiled-vs-interpreter divergence fixes) and wire it into the
Taiko EVM factory behind a workspace `jit` feature, on by default in the
binary. Compiled code runs only behind four AND-ed gates: the `jit`
build feature, the runtime `--jit`/`reth_jit` switch, the local
`with_jit_support()` opt-in (engine tree and payload builder only; RPC
execution stays interpreter-only), and an exhaustive fork allowlist that
keeps Unzen's zk-gas metering on per-opcode interpreter hooks. Inspected
execution always uses the disabled backend, and the wrapper drives the
JitEvm through TaikoEvmHandler so anchor and fee-share semantics are
preserved. `--jit.blocking` without `--jit` is gated off and now warns,
and the differential tests cover the LOG-memory and SELFDESTRUCT
builtin-forwarding classes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(repo): provision LLVM 22 and cover interpreter-only builds

Install LLVM 22 through a sha256-pinned apt.llvm.org helper in the test
and clippy jobs and in the Docker build (bookworm has no arm64 LLVM 22,
so both image stages move to trixie). New jobs prove the
`--no-default-features` build stays LLVM-free and compile the
`cfg(not(feature = "jit"))` test targets, and an arm64 job runs the
installer inside the Docker base distribution. check_reth_pin.sh now
also fails on multiple revmc revisions, and the `.github/**`
paths-ignore is dropped so changes to these scripts run CI.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(repo): document revmc JIT usage and pin invariants

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(repo): steer developers away from the CI-only LLVM installer

The build section pointed developers at install_llvm.sh, whose own
header marks it CI/Docker-only because it force-overwrites the
/usr/bin LLVM symlinks. Document the versioned-package route (distro
llvm-22 or apt.llvm.org, then PATH) instead and say explicitly not to
run the helper on a developer machine.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(repo): verify the revmc pin matches reth's locked revision

Counting revmc revisions only guards against a split graph; the
documented invariant is stronger — Alethia's revmc rev must equal the
one reth's own Cargo.lock pins at our reth revision, which nothing
enforces at build time because reth tracks revmc by branch. Fetch
reth's lockfile at the pinned rev and compare, failing closed on
mismatch, a missing revmc entry, or an unfetchable lockfile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(evm): design beacon root override integration

* docs(evm): plan beacon root override integration

* fix(evm): honor beacon root overrides

* chore(docs): remove superpowers planning artifacts

* fix(rpc): reject non-zero parent beacon block roots in attributes

A non-zero root from forkchoiceUpdated attributes was committed into
the built Unzen header, but getPayload's V1 payload + sidecar carry no
beacon-root field and convert_payload_to_block rebuilds Unzen headers
with the zero root, so the block failed every newPayload re-import
with a block-hash mismatch. Nothing filtered the field on the V2
route. Fail closed instead, at engine attribute validation and again
in TaikoPayloadBuilderAttributes::try_new (the constructor every
payload job passes through); zero and absent roots keep round-tripping
and the pending-block BlockOverrides.beacon_root path is unaffected.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: David <cai@Davids-MacBook-Pro.local>

Author: 3 people

.github/scripts/check_reth_pin.sh

@@ -5,15 +5,54 @@
 # coherent while Alethia's reth pin references the exact commit OP pins (see the
 # reth-optimism-trie note in Cargo.toml); a drifted pin splits the workspace into two
 # incompatible reth copies.
+#
+# Also fails on multiple paradigmxyz/revmc revisions: Alethia pins revmc by rev while reth's
+# own (unused) `jit` feature declares it by branch, so re-enabling that reth feature would
+# otherwise split the graph into two revmc copies silently.
+#
+# Finally, verifies Alethia's revmc revision equals the one reth's own Cargo.lock pins at our
+# reth revision. reth tracks revmc by branch in its manifest, so nothing enforces this at
+# build time — a reth bump that forgets to move Alethia's revmc rev would build fine while
+# compiled-code semantics silently drift from what upstream tested against.
 set -euo pipefail
 
-revs=$(grep -oE 'github\.com/paradigmxyz/reth\?[^"]*#[0-9a-f]{40}' Cargo.lock | sed 's/.*#//' | sort -u)
-count=$(printf '%s' "$revs" | grep -c . || true)
+single_rev() {
+    local repo=$1
+    local revs count
+    revs=$(grep -oE "github\.com/paradigmxyz/${repo}(\.git)?\?[^\"]*#[0-9a-f]{40}" Cargo.lock | sed 's/.*#//' | sort -u)
+    count=$(printf '%s' "$revs" | grep -c . || true)
+
+    if [ "$count" -ne 1 ]; then
+        echo "Error: expected exactly one paradigmxyz/${repo} revision in Cargo.lock, found $count:" >&2
+        printf '%s\n' "$revs" >&2
+        exit 1
+    fi
+
+    printf '%s' "$revs"
+}
+
+reth_rev=$(single_rev reth)
+echo "single reth revision in Cargo.lock: $reth_rev"
+revmc_rev=$(single_rev revmc)
+echo "single revmc revision in Cargo.lock: $revmc_rev"
+
+reth_lock_url="https://raw.githubusercontent.com/paradigmxyz/reth/${reth_rev}/Cargo.lock"
+if ! reth_lock=$(curl -fsSL --retry 5 "$reth_lock_url"); then
+    echo "Error: failed to fetch reth's lockfile from $reth_lock_url" >&2
+    exit 1
+fi
+
+reth_locked_revmc=$(grep -oE 'github\.com/paradigmxyz/revmc(\.git)?\?[^"]*#[0-9a-f]{40}' <<< "$reth_lock" | sed 's/.*#//' | sort -u)
+if [ -z "$reth_locked_revmc" ]; then
+    echo "Error: found no locked revmc revision in $reth_lock_url" >&2
+    exit 1
+fi
 
-if [ "$count" -ne 1 ]; then
-    echo "Error: expected exactly one paradigmxyz/reth revision in Cargo.lock, found $count:" >&2
-    printf '%s\n' "$revs" >&2
+if [ "$revmc_rev" != "$reth_locked_revmc" ]; then
+    echo "Error: Cargo.lock pins revmc $revmc_rev, but reth $reth_rev locks:" >&2
+    printf '%s\n' "$reth_locked_revmc" >&2
+    echo "Keep the revmc rev in Cargo.toml matched to the reth pin's locked revmc." >&2
     exit 1
 fi
 
-echo "single reth revision in Cargo.lock: $revs"
+echo "revmc revision matches reth's locked revmc"

.github/scripts/install_llvm.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+os=${1:?usage: install_llvm.sh <ubuntu> [version]}
+version=${2:-22}
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+case "$os" in
+    ubuntu)
+        sudo "$script_dir/install_llvm_ubuntu.sh" "$version"
+        ;;
+    *)
+        echo "unsupported OS: $os" >&2
+        exit 1
+        ;;
+esac

.github/scripts/install_llvm_ubuntu.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# CI/Docker provisioning ONLY. This installs apt.llvm.org packages system-wide and
+# force-overwrites the /usr/bin/{clang,llvm-config,lld,ld.lld,FileCheck} symlinks, so it must
+# not be run on a developer machine: install your distribution's llvm-22 package instead
+# (Homebrew `llvm@22` on macOS) and put its bin directory on PATH.
+set -eo pipefail
+
+version=${1:-22}
+bins=(clang llvm-config lld ld.lld FileCheck)
+
+# The official installer needs this package on Debian bookworm but not on newer distributions.
+apt-get update -qq
+apt-get install -y --no-install-recommends \
+    lsb-release wget gnupg ca-certificates
+apt-get install -y --no-install-recommends software-properties-common 2>/dev/null || true
+
+llvm_installer=$(mktemp)
+wget -qO "$llvm_installer" https://apt.llvm.org/llvm.sh
+# Pin the upstream installer so CI and Docker builds fail loudly when it changes; review the new
+# script before updating this hash.
+echo "9474ecd78b52aba6e923976b1e9773f5613027cc7e237b9956986cb536e02a36  $llvm_installer" | sha256sum -c -
+chmod +x "$llvm_installer"
+"$llvm_installer" "$version" all
+rm -f "$llvm_installer"
+
+for bin in "${bins[@]}"; do
+    if ! command -v "$bin-$version" &>/dev/null; then
+        echo "Error: $bin-$version not found after install" >&2
+        exit 1
+    fi
+    ln -fs "$(command -v "$bin-$version")" "/usr/bin/$bin"
+done
+
+echo "LLVM $version installed:"
+llvm-config --version

.github/workflows/ci.yml

@@ -3,8 +3,6 @@ name: CI
 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
-    paths-ignore:
-      - ".github/**"
     branches-ignore:
       - release-please--branches--**
 
@@ -17,9 +15,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - name: Verify a single reth revision in Cargo.lock
+      - name: Verify reth and revmc pins in Cargo.lock
         run: .github/scripts/check_reth_pin.sh
       - uses: rui314/setup-mold@v1
+      - run: .github/scripts/install_llvm.sh ubuntu
       - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: 1.95.0
@@ -56,6 +55,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: rui314/setup-mold@v1
+      - run: .github/scripts/install_llvm.sh ubuntu
       - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: 1.95.0
@@ -67,3 +67,34 @@ jobs:
         with:
           just-version: 1.5.0
       - run: just clippy
+
+  check-no-jit:
+    name: check (no default features)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+      - uses: rui314/setup-mold@v1
+      # LLVM is deliberately not installed: this proves the interpreter-only build stays free
+      # of the LLVM toolchain dependency.
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: 1.95.0
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - run: cargo check --locked -p alethia-reth-bin --no-default-features
+      # Compiles the `cfg(not(feature = "jit"))` test targets, which no `--all-features` job
+      # can reach (the node crate never enables `jit` by default).
+      - run: cargo check --locked -p alethia-reth-node --all-targets
+
+  llvm-arm64:
+    name: llvm install (linux/arm64)
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+      # Guards the Docker build on ARM64 hosts: apt.llvm.org omits arm64 packages for some
+      # Debian releases (bookworm has no arm64 LLVM 22), which only surfaces when installing
+      # on an ARM64 machine. Runs the same installer inside the Docker base distribution.
+      - run: docker run --rm -v "$PWD/.github/scripts:/scripts:ro" debian:trixie /scripts/install_llvm_ubuntu.sh

CLAUDE.md

@@ -10,6 +10,7 @@ Alethia-Reth is a Rust execution client for the Taiko protocol, built atop Parad
 
 - Language: Rust (`1.95.0` toolchain via `rust-toolchain.toml` / `justfile`)
 - Framework: Reth v2.4.x APIs (`reth_node_builder`, `reth_rpc`, `reth_engine_primitives`, etc.)
+- Optional revmc JIT execution (`jit` feature, on by default in the binary; needs LLVM 22)
 - Target protocol: Taiko rollup networks
 - Build & dependency manager: Cargo + `just`
 
@@ -25,7 +26,7 @@ Alethia-Reth is a Rust execution client for the Taiko protocol, built atop Parad
     ├── cli            CLI wrapper (`TaikoCli`)
     ├── consensus      Beacon consensus extensions
     ├── db             Taiko-specific tables & codecs
-    ├── evm            EVM config, handlers, execution helpers
+    ├── evm            EVM config, handlers, execution helpers, revmc JIT integration
     ├── payload        Payload builder service
     ├── primitives     Shared types (engine, payload attributes)
     ├── rpc            Taiko RPC (eth / engine / auth)