This runner compares FeVM's single-frame execution with revm-interpreter
31.1.0 with a pinned DUP/SWAP halt-classification correction,
explicitly configured for Osaka. Cargo.lock pins the reference and its
dependencies. The corpus includes 1,845 frames: arithmetic batches, all PUSH
widths and truncation positions, jumps, stack limits, memory/copy boundaries,
remaining gas, Keccak ranges/padding/gas, code/calldata beyond 4 KiB, and
returned/reverted bytes. A looping program checks gas exhaustion.
Specification-derived anchors also check the reference independently.
Use the compiler manifest and install its Rust version
with rustup. Both frame and state runners select that version explicitly; --toolchain selects another installed toolchain for a
diagnostic run. fevm_tools accept forwards its bootstrap record's Rust version
to both runners. Keep outputs outside temporary storage:
python3 native/differential/run.py --fe native/out/toolchain/bin/fe \
--out native/out/framesThe default builds and runs O0/O1/O2. --levels 0 selects a focused run. Each
output directory must be fresh. Both runners build the reference into
<out>/reference-target with an explicit Cargo --target-dir, overriding
CARGO_TARGET_DIR and build.target-dir. The result record includes
compiler/reference hashes, selected Rust toolchain, Rust/Cargo versions,
reference target directory, resolved reference package versions and Git sources, source hashes,
optimization levels and the first failure; generated
cases.jsonl retains every input and expected frame. Sources must remain unchanged
throughout a run. Compiler reports, IR, binaries and build logs are retained.
Run the harness regressions with
python3 -m unittest discover -s native/differential -p 'test_*.py'. They build
a small dependency-free Rust fixture using the pinned toolchain and retain
their temporary artifacts under /tmp.
The Fe driver takes <hex-bytecode> <hex-calldata> <u64-gas-limit> and emits
one JSON object:
{"outcome":"success","reason":null,"gas_remaining":97,"stack":["0x0000000000000000000000000000000000000000000000000000000000000001"],"memory":"0x","output":"0x"}Consensus outcomes are success, revert, and exceptional; remaining gas and
output must agree. Completed frames additionally compare the entire stack (bottom
to top) and word-rounded active memory. Exceptional frames consume all frame gas
and expose no output, stack or memory. Partial machine state after a fault depends
on engine fault ordering and is outside this comparison.
Reasons are retained separately in the reference record and each optimization
level's frames.jsonl. Only cases explicitly marked with simultaneous faults may
differ in reason, and both reasons must belong to that case's declared fault set.
The summary retains every such difference. Single-fault reasons, including the
independent DUP/SWAP anchors, remain checked. A bounds-plus-gas RETURNDATACOPY case
can therefore report bounds in revm and gas exhaustion in FeVM while agreeing on
the exceptional result and complete gas consumption.
Process errors, malformed JSON, unsupported instructions and host allocation failures fail the harness. They are not normalized into EVM halt codes. Each FeVM frame runs in its own process; arithmetic operations are batched within bounded EVM programs, preserving every arithmetic result on the stack.
Each case supplies its gas limit; the usual budget is 1,000,000. Code and calldata use growable owned buffers. The state wire format uses two-byte lengths for individual fields; it no longer imposes a 4 KiB total packet limit. The stateless corpus excludes external state and nested calls; the stateful corpus below covers state access, refunds and checkpoint rollback. Neither runs CALL or CREATE; the state tests cover those.
The specification pin is
c335bc4e9e99f7b91024d9033bdc89ce54394848.
The arithmetic anchors follow
Cancun arithmetic;
PUSH cases follow
stack instructions;
jump analysis follows
valid jump destinations.
These are local, specification-derived cases, not the Ethereum execution-spec
test distribution. The reference crate was released from revm commit
0d424ba11fd59d2a2a13988d61381e5b5cfccd22.
python3 native/differential/state_run.py --fe native/out/toolchain/bin/fe \
--out native/out/stateThe stateful corpus has 1,149 deterministic cases. Its reference uses the pinned revm Context and real Journal over InMemoryDB. Both engines run the same recursive sequence of frames and explicit checkpoint scopes. Snapshots after each frame or scope compare balances, persistent/current/original storage, transient storage, account/slot warmness, signed refund deltas, cumulative refunds and ordered logs. Transaction results also compare committed state, logs, capped refunds and net gas used. Repeated transactions share persistent state but start fresh transient/access/refund state. The reference observes its journal directly so inspection does not warm a key.
Cases include the EIP-2200 storage sequences adjusted to Osaka, cold/warm gas boundaries, upfront sender/destination/coinbase/precompile warming, duplicate access lists, high-bit BALANCE aliases, negative frame refund contributions, static writes, child commit/revert, parent rollback, transaction abort/reuse, and BLOCKHASH history-window/operand/gas boundaries. External-code cases distinguish absent, explicitly empty, storage-only, funded, nonce-bearing and code-bearing accounts; check static reads, high address bits, copy padding and full-width sources, exact gas, shared warming and rollback across frames and transactions. Log cases cover all topic counts, data copying and zero padding, exact gas, full-width empty offsets, static rejection, frame failure and nested rollback. Blob-hash cases cover transaction inputs, full-width bounds, static reads, gas, checkpoint persistence and transaction reuse. Reference transactions derive their EIP-4844 type when blob hashes are present, so the host BLOBHASH path is exercised. The Python contract checks field shapes, log encoding and accounting invariants; independent anchors check the reference's gas, refund and value results. Operational failures fail the comparison. Unlike the stateless simultaneous-fault controls, these state cases require exact diagnostic reasons as well as exact results.
The native state driver takes one versioned binary case encoded as hex. Integers
and lengths use big endian. Version 4 carries block history and explicit accounts:
address (20 bytes), balance (32), nonce (8), code length (2) and code bytes. Each
transaction's block number is followed by a blob-hash count (2 bytes) and that many
32-byte hashes, before its commit flag and access lists. Earlier wire versions
are rejected. The encoder lives in state_corpus.py. JSON lines remain the reference input
and retained corpus format. Each case starts a fresh native process, while all
frames and transactions in that case execute in that process. The scope models
journal boundaries directly, without CALL/CREATE, transaction signatures or
intrinsic gas.
Native acceptance runs this corpus as its own stage.