Files
skills/public/hanzo-evm.md

7.4 KiB

Hanzo EVM - Rust Execution Engine for Post-Quantum Web3

Category: Hanzo Ecosystem Related Skills: hanzo/rust-sdk.md, hanzo/hanzo-node.md, hanzo/hanzo-contracts.md

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

  1. Rust 1.93+ (edition 2024)
  2. ~1300+ source files across workspace
  3. 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 mainnet

CLI 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 tries

Configuration (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 = 10000

Design Principles

  1. Crate names: hanzo-evm-* (required for publishing)
  2. Internal code: FREE of hanzo branding unless necessary
  3. No compound words: Evm not HanzoEvm
  4. Neutral env/config: EVM_* not HANZO_EVM_*
  5. 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
  • 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

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: evm, blockchain, rust, reth, execution-engine Prerequisites: Rust 1.93+, EVM concepts, blockchain fundamentals