rex-evm

A minimal Ethereum Virtual Machine written in Rust, with a small CLI for executing raw bytecode.

Workspace layout

rex-evm/
├── bin/
│   └── evm-cli/      # `evm` CLI — runs bytecode from a hex string or file
└── crates/
    ├── core/         # EVM interpreter: dispatch loop, stack, memory, call frames
    └── lib/          # Shared primitives: types, constants, errors, storage

• crates/core/src/evm.rs — the interpreter and dispatch loop
• crates/core/src/opcodes.rs — opcode enum
• crates/core/src/frame.rs — call frames, execution status, halt reasons
• crates/core/src/stack.rs, memory.rs, substate.rs — per-frame and per-tx state
• crates/lib/src/types.rs — Address, Transaction, BlockEnv, etc.

Build from source

Prerequisites: a recent stable Rust toolchain (2024 edition — Rust 1.85+). Install via rustup if you don't have it.

Clone and build:

git clone <repo-url> rex-evm
cd rex-evm
cargo build --release

The compiled CLI will be at target/release/evm. You can either invoke it directly or install it onto your PATH:

# run the release binary directly
./target/release/evm run --code 0x6001600201

# or install to ~/.cargo/bin so `evm` is on PATH
cargo install --path bin/evm-cli
evm run --code 0x6001600201

During development, cargo run builds and runs in one step — no prior cargo build needed:

cargo run -p evm -- run --code 0x6001600201

CLI usage

The binary is named evm and lives at bin/evm-cli. The examples below use cargo run form; substitute ./target/release/evm or evm (if installed) as appropriate.

Run bytecode from a hex string:

cargo run -q -p evm -- run --code 0x6001600201

Run bytecode from a file (either hex text or raw bytes):

cargo run -q -p evm -- run --file contract.bin

Enable a per-opcode execution trace:

cargo run -q -p evm -- run --code 0x6001600201 --trace

Override the gas limit (default: 1,000,000):

cargo run -q -p evm -- run --code 0x6001600201 --gas 100

Output

Stack:    [0x3]
Return:   0x
Gas used: 9
Status:   STOP

• Stack — final stack at halt, top-of-stack first.
• Return — hex-encoded return data (empty for STOP).
• Gas used — gas_limit - gas_remaining.
• Status — halt reason: STOP, RETURN, REVERT, SELFDESTRUCT, or the error message on exceptional halt.

Testing

cargo test

• crates/core/tests/ — opcode-level and end-to-end program tests
• bin/evm-cli/tests/cli.rs — CLI integration tests

Run a single suite:

cargo test -p evm-core --test arithmetic
cargo test -p evm --test cli