How ethereum/hevm works
Project Type and Purpose
• hevm is a Haskell‐based CLI tool and library that implements the Ethereum Virtual Machine (EVM) for symbolic execution, equivalence checking, and unit testing of smart contracts. It exposes a command‐line interface (CLI) front end and a rich core library of modules under src/EVM, and it integrates external SMT solvers and a small C FFI module (ethjet) for fast hashing.
File Structure
• Top‐level directories:
• cli/ → CLI entrypoint (cli/cli.hs)
• src/EVM/ → Core Haskell modules implementing EVM functionality (assembler, symbolic execution, SMT interface, etc.)
• ethjet/ → C source and headers providing fast Blake2 & Keccak via Haskell FFI
• bench/ → Benchmark drivers measuring performance of EVM operations
• test/ → Test suite, including blockchain tests, CLI tests, contract tests
• .github/ → CI and release workflows
• Configuration/build:
• hevm.cabal → Cabal build instructions for library and hevm executable
• nix files → Nix flake and lock to pin dependencies
Read the README for Additional Insights
• Core capabilities: symbolic execution, equivalence checking, support for Forge test suites
• External dependencies at runtime: z3, cvc5, bitwuzla (invoked as external processes)
• Development: uses nix for reproducible env, cabal for building/testing
a. Main Components
• CLI Frontend (“hevm” binary)
• Core EVM Library (Haskell modules under src/EVM)
• Native FFI Module (ethjet C code)
• External Solvers (Z3, CVC5, Bitwuzla)
• Benchmark Harness (bench/)
• Test Harness (test/)
b. Relationships & Interactions
• CLI → Core Library: dispatches subcommands (symbolic‐exec, equivalence, fuzz, test)
• Core Library → Ethjet FFI: calls into C for Blake2/TinyKeccak hashing
• Core Library → SMT Solvers: spawns/protocol‐talk to external solver processes
• Bench & Test Suites → Core Library: import and drive APIs for performance and correctness tests
• Nix/Cabal → Builds all components and orchestrates development environment
c. Architectural Patterns & Design Principles
• Modular layering:
• Pure core (EVM semantics, assembler, state transitions)
• Effect abstraction (monadic layers for IO, SMT interaction)
• CLI as thin orchestration layer
• Plugin‐style solver integration: external processes called via generic SMT interface
• C FFI for hot code paths (hash functions)
• Test‐driven reliability: extensive test directory, contract fixtures
d. Key Technologies
• Haskell (GHC, Cabal, modules under src/EVM)
• Nix flakes for reproducible dev environment
• C (ethjet) linked via Haskell FFI
• External tools: z3, cvc5, bitwuzla