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 = "3.0.0"

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

# Show bytecode statistics
evm-lens 60FF61ABCD00 --stats

# Decode function selectors with ABI resolution
evm-lens 63a9059cbb00 --abi

# Compare storage layouts (files only)
evm-lens storage-diff artifacts/old.hex artifacts/new.hex
evm-lens storage-diff old.hex new.hex --json target/storage.json --html target/storage.html
evm-lens storage-diff old.hex new.hex --ci

Library:

use lens_core::disassemble;

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

🎨 Features

Core Capabilities:

• 🔍 Disassemble EVM bytecode from multiple sources - hex strings, files, stdin, and live contract addresses

• 📊 Generate statistics summary including bytecode length, number of opcodes, and maximum stack depth

• 🎯 Decode function selectors - automatically resolve PUSH4 instructions to human-readable function signatures using 4byte.directory

• 🧮 Storage diff - compare two artifacts and flag storage layout changes with JSON/HTML reports and CI-friendly exit codes

📥 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

🎯 ABI Function Selector Decoding

EVM Lens can automatically decode 4-byte function selectors found in PUSH4 instructions to their human-readable function signatures:

# Decode function selectors using --abi flag
evm-lens 63a9059cbb00 --abi

# Works with any input method
evm-lens --file contract.hex --abi
echo "0x63a9059cbb00" | evm-lens --stdin --abi
evm-lens --address 0x123... --rpc https://eth.llamarpc.com --abi

# Combine with stats for comprehensive analysis
evm-lens 63a9059cbb00 --abi --stats

🧮 Storage Diff

Compare two compiled artifacts (files containing hex-encoded runtime bytecode) and flag storage layout risks.

evm-lens storage-diff <old.hex> <new.hex> [--json out.json] [--html out.html] [--ci]

• Inputs:
  • <old.hex>, <new.hex>: file paths containing hex-encoded runtime bytecode (with or without 0x).
• How it works:
  • Builds a StorageLayout for each input using a composite resolver:
    1. Compiler metadata (if available), 2) conservative bytecode heuristic (PUSH… then SLOAD/SSTORE).
  • Computes a per-slot diff with statuses: Same | Added | Removed | TypeChanged | PackingChanged.
  • Assigns grades: Ok | Risk | Break (Added=Ok, Removed/TypeChanged=Break, PackingChanged=Risk).
  • Records provenance per side: CompilerMetadata or HeuristicTrace.
• Outputs:
  • CLI one-line summary with counts and max grade.
  • Optional JSON (--json) and HTML (--html) reports.
• CI:
  • With --ci, exits non‑zero (code 2) if max_grade >= Risk.

Examples:

# Basic compare
evm-lens storage-diff artifacts/old.hex artifacts/new.hex

# Write JSON/HTML reports
evm-lens storage-diff old.hex new.hex --json target/storage.json --html target/storage.html

# CI policy (non-zero on Risk/Break)
evm-lens storage-diff old.hex new.hex --ci

📊 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

With --stats flag:

EVM BYTECODE DISASSEMBLY
==================================================
0000 │ PUSH1
0002 │ PUSH2
0005 │ STOP
==================================================
3 opcodes total
BYTECODE STATISTICS
==================================================
Byte length: 6
Number of opcodes: 3
Max stack depth: 2

With --abi flag (function selector decoding):

EVM BYTECODE DISASSEMBLY
==================================================
0000 │ PUSH4  # 0xa9059cbb → transfer(address,uint256)
0005 │ PUSH20
001a │ PUSH9
0024 │ BLOCKHASH
==================================================
4 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 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --rpc https://eth.llamarpc.com

# Test ABI function selector decoding
cargo run -p evm-lens -- 63a9059cbb00 --abi

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

📋 Supported Opcodes

All standard EVM opcodes are supported:

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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