EVM Lens

Fast and colorful EVM bytecode disassembler

EVM Lens is a high-performance Ethereum Virtual Machine (EVM) bytecode disassembler written in Rust. It provides both a library (evm-lens-core) and a beautiful command-line tool (evm-lens) for analyzing EVM bytecode.

📦 Crates

This workspace contains two crates:

`evm-lens-core` - The Core Library

Fast EVM bytecode disassembly using revm
Position-accurate opcode extraction
Result-based error handling
Zero-copy iteration where possible

`evm-lens` - The CLI Tool

Colorful terminal output with opcode categorization
Multiple input methods: direct hex, files, stdin, and blockchain
Support for hex strings with/without 0x prefix
On-chain bytecode fetching via Ethereum RPC
Beautiful error reporting

🚀 Quick Start

Install the CLI

cargo install evm-lens

Use as a Library

[dependencies]
evm-lens-core = "0.1.1"

Example Usage

CLI:

# From command line argument
evm-lens 60FF61ABCD00

# From file
evm-lens --file bytecode.txt

# From stdin
echo "0x60FF61ABCD00" | evm-lens --stdin

# From contract address (fetches from blockchain)
evm-lens --address 0x123... --rpc https://eth.llamarpc.com

Library:

use lens_core::disassemble;

let bytecode = hex::decode("60FF61ABCD00")?;
let ops = disassemble(&bytecode)?;
for (position, opcode) in ops {
    println!("{:04x}: {:?}", position, opcode);
}

🎨 Features

🚀 Fast: Built on revm's optimized EVM implementation
🎨 Beautiful: Color-coded output for different opcode categories
✅ Accurate: Proper handling of PUSH instruction immediates
📍 Precise: Exact position tracking for all opcodes
🔗 Versatile: Multiple input sources - hex strings, files, stdin, and blockchain
🌐 Connected: Fetch live contract bytecode from Ethereum networks

📥 Input Methods

EVM Lens supports multiple ways to provide bytecode for analysis:

Direct Hex Input

evm-lens 60FF61ABCD00         # Without 0x prefix
evm-lens 0x60FF61ABCD00       # With 0x prefix

File Input

evm-lens --file bytecode.txt  # Read from file

Standard Input

echo "0x60FF61ABCD00" | evm-lens --stdin
cat bytecode.txt | evm-lens --stdin

Blockchain Input

# Use default RPC (eth.llamarpc.com)
evm-lens --address 0x123...

# Use custom RPC endpoint
evm-lens --address 0x123... --rpc https://mainnet.infura.io/v3/YOUR_KEY
evm-lens --address 0x123... --rpc https://eth.llamarpc.com

🎯 Use Cases

Smart Contract Analysis: Understand deployed contract behavior
Security Research: Analyze suspicious or malicious contracts
Bytecode Debugging: Debug Solidity compilation issues
Education: Learn EVM opcodes and instruction structure
Development Tools: Build bytecode analysis into your workflow
Live Contract Inspection: Analyze contracts directly from the blockchain

📊 Example Output

EVM BYTECODE DISASSEMBLY
==================================================
0000 │ PUSH1     # Stack operation (green)
0002 │ PUSH2     # Stack operation (green)  
0005 │ ADD       # Arithmetic (yellow)
0006 │ MSTORE    # Memory operation (blue)
0007 │ RETURN    # Termination (white)
==================================================
5 opcodes total

🔧 Development

Prerequisites

Rust 1.85+ (2024 edition)
Cargo

Building

git clone https://github.com/andyrobert3/evm-lens
cd evm-lens
cargo build --release

Testing

cargo test --workspace

Running Examples

# Run the CLI with different input methods
cargo run -p evm-lens -- 60FF61ABCD00
cargo run -p evm-lens -- --file examples/bytecode.txt
echo "0x60FF61ABCD00" | cargo run -p evm-lens -- --stdin
cargo run -p evm-lens -- --address 0x... --rpc https://eth.llamarpc.com

# Test the library
cargo run --example basic -p evm-lens-core

📋 Supported Opcodes

All standard EVM opcodes are supported:

Category	Examples
Stack	PUSH1-PUSH32, POP, DUP1-DUP16, SWAP1-SWAP16
Arithmetic	ADD, SUB, MUL, DIV, MOD, ADDMOD, MULMOD
Comparison	LT, GT, SLT, SGT, EQ, ISZERO
Bitwise	AND, OR, XOR, NOT, BYTE, SHL, SHR, SAR
Memory	MLOAD, MSTORE, MSTORE8, MSIZE, MCOPY
Storage	SLOAD, SSTORE, TLOAD, TSTORE
Control	JUMP, JUMPI, JUMPDEST, PC, GAS
Block Info	BLOCKHASH, COINBASE, TIMESTAMP, NUMBER
Calls	CALL, CALLCODE, DELEGATECALL, STATICCALL
Create	CREATE, CREATE2
Termination	STOP, RETURN, REVERT, SELFDESTRUCT
Crypto	KECCAK256, ECRECOVER

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

revm - High-performance EVM implementation
The Ethereum community for EVM specifications

evm-lens-core 0.1.1