Mojo EVM

A high-performance Ethereum Virtual Machine (EVM) implementation in Mojo with reference-driven validation against py-evm.

🏗️ Architecture & Design

✅ Key Strengths

• Modular design: Clean separation between core VM (vm/computation.mojo), pure opcode functions (vm/logic/), and testing infrastructure
• Reference-driven development: Uses py-evm as ground truth for all implementations
• Pure functional opcodes: Arithmetic, comparison, and bitwise operations implemented as side-effect-free functions
• SIMD-optimized crypto: High-performance Keccak256 and SHA256 with 21-739x performance improvements
• Comprehensive test infrastructure: Multiple validators (run_official_tests.py, pyevm_validator.py, fork_validator.py)

🧪 Testing & Validation Status

Current VMTests Results (~75% pass rate)

✅ Passing Categories:

• Basic arithmetic (ADD, SUB, MUL, MOD, etc.)
• Comparison operations (LT, GT, EQ, etc.)
• Bitwise operations (AND, OR, XOR, etc.)
• Simple flow control (JUMP, JUMPI)
• Basic I/O operations
• EXP operations (with correct gas costs)

❌ Known Failing Tests:

• div.json: Gas mismatch (Mojo: 20744 vs py-evm: 5744)
• fib.json: Large gas discrepancy (Mojo: 203016 vs py-evm: 204916)
• twoOps.json: Massive gas difference (Mojo: 13904664 vs py-evm: 14681628)

⚙️ Implemented Functionality

✅ Working Opcodes

• Arithmetic: ADD, SUB, MUL, DIV, SDIV, MOD, SMOD, ADDMOD, MULMOD, EXP, SIGNEXTEND
• Comparison: LT, GT, SLT, SGT, EQ, ISZERO
• Bitwise: AND, OR, XOR, NOT, BYTE, SHL, SHR, SAR
• Stack: PUSH1-PUSH32, DUP1-DUP16, SWAP1-SWAP16, POP
• Memory: MLOAD, MSTORE
• Storage: SLOAD, SSTORE
• Flow: JUMP, JUMPI, JUMPDEST, STOP
• I/O: CALLDATALOAD, CALLDATASIZE, CALLDATACOPY, RETURN, REVERT
• Context: ADDRESS, CALLER, ORIGIN, GASPRICE, CODESIZE, COINBASE, TIMESTAMP, NUMBER, DIFFICULTY, GASLIMIT
• Logging: LOG0-LOG4
• Hashing: KECCAK256/SHA3

🚫 Major Missing Components

❌ Critical Gaps

1. Complex State Operations:

   • BALANCE, EXTCODESIZE, EXTCODEHASH, EXTCODECOPY (read-only state access)
   • No multi-account transaction simulation

2. CALL Family Operations:

   • CALL, DELEGATECALL, CALLCODE, STATICCALL
   • CREATE, CREATE2
   • No inter-contract interaction capability

3. Advanced Features:

   • Pre-compiled contracts
   • Error handling and exception propagation
   • Complete gas metering edge cases
   • Full transaction context simulation

4. Fork Compatibility:

   • Implementation exists but has execution issues
   • Multi-fork testing not fully operational

🚀 Quick Start

Prerequisites

• Mojo installed
• Pixi for Python environment management

Running Tests

# Test all VMTests (basic EVM operations)
pixi run python run_official_tests.py vm

# Test a specific bytecode against py-evm
pixi run python pyevm_validator.py 600160019001

# Multi-fork validation (when working)
pixi run python fork_validator.py 600160019001 Berlin

Project Structure

mojo_evm/
├── vm/                              # Mojo EVM implementation
│   ├── computation.mojo             # Main execution engine
│   ├── state.mojo                   # EVM state management
│   ├── execution_frame.mojo         # Execution context
│   ├── message.mojo                 # Message handling
│   ├── gas.mojo                     # Gas calculations
│   └── logic/                       # Pure function opcode implementations
│       ├── arithmetic.mojo          # ADD, SUB, MUL, DIV, MOD, EXP
│       ├── comparison.mojo          # LT, GT, EQ, ISZERO, SLT, SGT
│       ├── bitwise.mojo             # AND, OR, XOR, NOT, SHL, SHR, SAR
│       ├── keccak256.mojo           # Keccak256 hash function
│       ├── keccak256_optimized.mojo # SIMD-optimized Keccak256
│       ├── sha256.mojo              # SHA256 hash function
│       ├── sha256_optimized.mojo    # SIMD-optimized SHA256
│       ├── sha3.mojo                # SHA3/Keccak interface
│       ├── call.mojo                # Call operations
│       ├── context.mojo             # Context operations
│       └── system.mojo              # System operations
├── run_official_tests.py            # Main test runner with full state validation
├── single_test_runner.mojo          # Mojo helper for run_official_tests.py
├── pyevm_validator.py               # Standalone py-evm reference execution
├── fork_validator.py                # Multi-fork validation tool (needs fixes)
├── reference/                       # Reference implementations
│   ├── py-evm/                      # Complete py-evm source code
│   └── revm/                        # Rust EVM for optimization ideas
└── docs/                            # Detailed documentation

🎯 Development Status

Current Stage: Early Development

This project implements basic EVM opcodes with ~75% pass rate on VMTests. While core arithmetic, bitwise, and stack operations work correctly, significant gaps remain in:

• Complex state operations (BALANCE, EXTCODE*)
• Inter-contract calls (CALL, DELEGATECALL, CREATE)
• Gas accounting edge cases
• Complete transaction simulation

Known Issues

• Gas Discrepancies: Some tests show gas calculation differences with py-evm
• State Management: Limited to single-contract execution
• Fork Compatibility: Multi-fork testing infrastructure needs fixes

🤝 Contributing

This project follows reference-driven development:

1. Check py-evm implementation in reference/py-evm/eth/vm/logic/
2. Study exact behavior including gas costs and edge cases
3. Implement in Mojo following existing patterns
4. Validate against py-evm using the test infrastructure

📝 License

This project uses reference implementations with their respective licenses:

• py-evm components under MIT License
• Original Mojo implementation code follows the same MIT License

⚠️ Important Note

This is an experimental implementation in active development. It is not suitable for production use. The project serves as:

• A learning exercise for Mojo language capabilities
• A performance exploration of SIMD-optimized EVM operations
• A foundation for future high-performance EVM implementations

Credits

• py-evm: Python Implementation of the Ethereum protocol

• revm: Revm is a highly efficient and stable implementation of the Ethereum Virtual Machine (EVM) written in Rust.

• guillotine: Guillotine is a new EVM implementation built in Zig by @FUCORY, the creator of Tevm