A robust, clean-room implementation of the Ethereum Virtual Machine (EVM) built from scratch in Rust, featuring a custom interactive Terminal UI (TUI) debugger.
Initial Setup
Bytecode sample selection
Bytecode manual writing
Gas setup
EVM Initial State
EVM Execution State
Success State
Failed State
(screenshots of rsevm in execution)
This project is a from-scratch implementation of the Ethereum Virtual Machine, built following the evm-from-scratch curriculum.
While the original guide focuses on passing tests, rsevm takes it a step further by focusing on software engineering best practices:
- Safety: Full usage of Rust's
Resulttypes for robust error handling (nounwrapin the core loop). - Modularity: Clean separation of concerns between Stack, Memory, Storage, and Opcode logic.
- Tooling: A built-in visual debugger to watch the EVM state change in real-time.
It supports most opcodes up to the Cancun hardfork.
├── src/
│ ├── lib.rs # Crate root
│ ├── evm.rs # Main EVM Execution Loop
│ ├── stack.rs # Stack Data Structure (U256)
│ ├── memory.rs # Volatile Memory Implementation
│ ├── storage.rs # Persistent Storage (HashMap)
│ ├── opcodes/ # Modular Opcode Logic
│ │ ├── arithmetic.rs
│ │ ├── bitwise.rs
│ │ └── ...
│ └── bin/
│ └── debug_tui.rs # The Interactive Debugger (Ratatui)
└── tests/ # Integration Tests- Stack Machine: Fully compliant 256-bit stack handling.
- Volatile Memory: Byte-addressable memory with proper expansion gas costs.
- Persistent Storage:
SSTOREandSLOADimplementation for contract state. - Gas Metering: Accurate tracking of gas usage per opcode.
Built with ratatui and crossterm, the debugger allows you to step through bytecode instruction-by-instruction.
- Bytecode Pane: Auto-scrolling view of instructions with current PC highlighting.
- Memory Viewer: 16-byte row hex dump to visualize memory expansion.
- Stack Visualizer: Real-time view of stack items (Top-down).
- Status Dashboard: Live tracking of Gas Used, Program Counter (Hex/Dec), and execution status.
- Error Modals: Graceful handling of
OutOfGas,StackOverflow,StackUnderflow, and other runtime errors.
Check src/opcodes/opcodes.rs for supported opcodes. This project supports EVM opcodes up to the Cancun Hardfork
- Rust & Cargo (Latest Stable)
git clone https://github.com/youngancient/rsevm.git
cd rsevmTo run the TUI with the default bytecode program:
cargo run --bin debug_tuiNote: Expand your terminal for the best experience (avoid truncation)
Controls:
n: Step forward (Execute next opcode)
q: Quit the debugger
The project includes a comprehensive integration test suite for individual opcodes and state logic.
cargo testContributions are welcome! The goal of rsevm is to be a robust educational tool that helps learners visualize and understand EVM bytecode execution.
There are two primary ways you can contribute:
If you encounter unexpected behavior or bugs, please raise an issue.
- Bugs: If the stack, memory, or storage isn't behaving as expected, let us know.
- Missing Opcodes: This project supports opcodes up to the Cancun hardfork, but not all logic has been fully implemented yet. If you try to run bytecode and encounter an
Unknown Opcodeerror, please open an issue specifying which opcode is missing.
Feel free to get your hands dirty and improve the codebase!
- Fork the repository.
- Create a new branch for your feature or fix.
- Implement the missing opcode or fix the bug (don't forget to add tests!).
- Submit a Pull Request detailing your changes.
evm-from-scratch for the learning roadmap.
alloy-primitives for Rust Ethereum types.
ratatui for the TUI framework.