Hanzo Skills Reference
Hanzo EVM - Rust Execution Engine for Post-Quantum Web3
Hanzo EVM is a Rust-based EVM execution engine — fork of paradigmxyz/reth v1.11.0, rebranded for the Hanzo ecosystem.
Overview
Hanzo EVM is a Rust-based EVM execution engine — fork of paradigmxyz/reth v1.11.0, rebranded for the Hanzo ecosystem. Designed as a modular toolkit for building post-quantum Web3 infrastructure, L2/L3 app chains, and high-performance blockchain nodes.
Why Hanzo EVM?
- Modular architecture: Plug-and-play components for custom chains
- Post-quantum ready: Integration with Hanzo PQC (ML-KEM, ML-DSA)
- High performance: Parallel EVM execution, optimized storage
- Clean abstractions: Neutral naming, beautiful API surface
- Full reth compatibility: All upstream features + Hanzo extensions
OSS Base
Fork of paradigmxyz/reth v1.11.0. Rust edition 2024, MSRV 1.93.
NOTE: Crate rename is in progress. The binary is hanzo-evm and bin/hanzo-evm/ exists, but most workspace dependency names still reference reth-* internally. The naming convention below describes the target state.
When to use
- Building blockchain nodes with EVM execution
- L2/L3 app chain development on Lux or standalone
- Post-quantum Web3 infrastructure
- High-performance transaction processing
- Custom consensus + EVM combinations
Hard requirements
- Rust 1.93+ (edition 2024)
- ~1300+ source files across workspace
- Build:
cargo build --release(~15-30 min first build)
Quick reference
| Item | Value |
|---|---|
| Binary | hanzo-evm |
| Repo | github.com/hanzoai/evm |
| Upstream | paradigmxyz/reth v1.11.0 |
| Rust edition | 2024 |
| MSRV | 1.93 |
| Build | cargo build --release |
| Test | cargo test |
| License | MIT OR Apache-2.0 |
Naming Convention
| Layer | Convention | Example |
|---|---|---|
| Crate names | hanzo-evm-* | hanzo-evm-execution |
| Module imports | hanzo_evm_* | hanzo_evm_execution |
| Internal modules | clean/neutral | mod evm; |
| Types | clean Evm* | EvmApi, EvmRpcModule |
| Env vars | EVM_* | neutral, no hanzo prefix |
| Config/data | neutral | evm.toml, evm/, evm.ipc |
| Binary | hanzo-evm | single binary |
Key Renames from reth
| reth | Hanzo EVM | Rationale |
|---|---|---|
reth (binary) | hanzo-evm | Brand identity |
reth-evm | hanzo-evm-execution | Avoid hanzo-evm-evm |
reth-evm-ethereum | hanzo-evm-eth-execution | Clean naming |
reth-ethereum | hanzo-evm-ethereum | Umbrella crate |
reth-nippy-jar | hanzo-evm-nippy-jar | Lib name = hanzo_evm_nippy_jar |
reth-primitives | hanzo-evm-primitives | Core types |
reth-db | hanzo-evm-db | Storage layer |
reth-rpc | hanzo-evm-rpc | JSON-RPC |
reth-network | hanzo-evm-network | P2P networking |
reth-consensus | hanzo-evm-consensus | Consensus interface |
reth-payload-builder | hanzo-evm-payload-builder | Block building |
reth-transaction-pool | hanzo-evm-transaction-pool | Mempool |
Workspace Crates (Key)
Core
| Crate | Purpose |
|---|---|
hanzo-evm | Main binary + CLI |
hanzo-evm-primitives | Core types (Block, Transaction, Receipt) |
hanzo-evm-execution | EVM execution engine |
hanzo-evm-ethereum | Ethereum umbrella (mainnet, sepolia, holesky) |
hanzo-evm-eth-execution | Ethereum-specific EVM rules |
Storage
| Crate | Purpose |
|---|---|
hanzo-evm-db | Database abstraction (MDBX) |
hanzo-evm-db-api | Database trait interfaces |
hanzo-evm-db-common | Shared DB utilities |
hanzo-evm-nippy-jar | Compressed static file storage |
hanzo-evm-stages | Sync pipeline stages |
hanzo-evm-static-file-types | Static file type definitions |
Networking
| Crate | Purpose |
|---|---|
hanzo-evm-network | P2P networking (devp2p) |
hanzo-evm-network-api | Network trait interfaces |
hanzo-evm-discv4 | Node discovery v4 |
hanzo-evm-discv5 | Node discovery v5 |
hanzo-evm-dns-discovery | DNS-based discovery |
hanzo-evm-eth-wire | Ethereum wire protocol |
RPC
| Crate | Purpose |
|---|---|
hanzo-evm-rpc | JSON-RPC server |
hanzo-evm-rpc-api | RPC trait interfaces |
hanzo-evm-rpc-eth-api | eth_* namespace |
hanzo-evm-rpc-engine-api | Engine API (consensus layer) |
Consensus
| Crate | Purpose |
|---|---|
hanzo-evm-consensus | Consensus trait + validators |
hanzo-evm-auto-seal | Dev mode auto-sealing |
hanzo-evm-beacon-consensus | Beacon chain consensus |
Block Building
| Crate | Purpose |
|---|---|
hanzo-evm-payload-builder | Block payload construction |
hanzo-evm-transaction-pool | Transaction mempool |
hanzo-evm-basic-payload-builder | Default payload builder |
One-file quickstart
# Build from source
git clone https://github.com/hanzoai/evm.git
cd evm
cargo build --release
# Run mainnet node
./target/release/hanzo-evm node --chain mainnet
# Run with HTTP + WS RPC
./target/release/hanzo-evm node \
--chain mainnet \
--http \
--http.port 8545 \
--http.api eth,net,web3,debug,trace \
--ws \
--ws.port 8546
# Run dev mode (auto-sealing)
./target/release/hanzo-evm node --dev
# Custom data directory
EVM_DATA_DIR=/data/evm ./target/release/hanzo-evm node --chain mainnetCLI Commands
hanzo-evm node # Run full node
hanzo-evm node --dev # Development mode
hanzo-evm init # Initialize database
hanzo-evm import <file> # Import blocks from file
hanzo-evm db stats # Database statistics
hanzo-evm db diff # Compare DB states
hanzo-evm p2p header <hash> # Fetch header via P2P
hanzo-evm p2p body <hash> # Fetch body via P2P
hanzo-evm stage run --stage <n> # Run specific sync stage
hanzo-evm recover storage-tries # Recover storage triesConfiguration (evm.toml)
[node]
chain = "mainnet"
datadir = "/data/evm"
instance = 1
[rpc]
http = true
http_addr = "0.0.0.0"
http_port = 8545
ws = true
ws_port = 8546
[network]
port = 30303
max_peers = 100
[stages.sync]
pipeline_batch_size = 10000Design Principles
- Crate names:
hanzo-evm-*(required for publishing) - Internal code: FREE of hanzo branding unless necessary
- No compound words:
EvmnotHanzoEvm - Neutral env/config:
EVM_*notHANZO_EVM_* - Clean, beautiful, simple to build a Hanzo node with
Architecture Vision
- Hanzo EVM = execution engine / toolkit for Post-Quantum Web3
- L2/L3 app chains on Lux consensus for verticals (commerce, AI compute)
- Eventual L1 capability; toolkit supports all layers
- Commerce chain: blockchain backend for Hanzo Commerce
- Fork alloy + revm for full post-quantum ZK EVM stack
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Build fails | Rust too old | Install Rust 1.93+ |
| MDBX error | Max readers | Increase EVM_DB_MAX_READERS |
| Sync stalls | Network issues | Check peers with hanzo-evm p2p info |
| OOM on build | Low memory | Use cargo build -j 2 to limit parallelism |
Related Skills
hanzo/hanzo-node.md- Distributed AI node (uses EVM plugin)hanzo/rust-sdk.md- Rust SDK (PQC crypto for EVM)hanzo/hanzo-contracts.md- Smart contracts deployed on EVM
How is this guide?
Last updated on
Hanzo Contracts - AI Infrastructure Smart Contracts
Hanzo Contracts is the smart contract repository for the Hanzo AI ecosystem. Built with Foundry and Solidity 0.8.31, it contains three core contracts for the AI token economy, faucet distribution, ...
Hanzo Explorer
Hanzo Explorer is an EVM blockchain explorer for inspecting and analyzing transactions, accounts, smart contracts, and tokens on Lux Network and other EVM-compatible chains. It is a fork of Blocksc...