EVM Debug MCP

Deterministic EVM execution trace indexing engine built on top of Anvil's debug_traceTransaction / debug_traceCall. Structures, indexes, caches, and queries opcode-level traces — it does not implement an EVM.

Workspace

crates/
  types/    — shared types, error enum, Opcode enum (evm-debug-types)
  rpc/      — AnvilManager, TraceFetcher, capability check (evm-debug-rpc)
  core/     — normalizer, call tree, jump graph, indexer, cache, diffs (evm-debug-core)
  query/    — PC resolver, stack/memory/frame/call-tree/address queries (evm-debug-query)
  adapter/  — FoundryAdapter, HTTP interface scaffold (evm-debug-adapter)

Build & Test

cargo build
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo bench -p evm-debug-core

Fuzz

cargo install cargo-fuzz
cd fuzz && cargo fuzz run normalize

Three targets: normalize, opcode_from_name, hex_parse.

Key Features

• Immutable, versioned TraceSnapshot with schema migration support
• O(n) linear-time indexing (PC index, address index, call tree, jump graph)
• Bidirectional jump graph with dynamic target resolution
• Stack/memory/storage diff engine
• StateQuery trait with unified TraceQueryEngine implementation
• Address-scoped queries via AddressQuerier
• LRU frame cache with explicit invalidation
• 72 unit + property tests, criterion benchmarks at 10k/100k/1M steps
• CI: fmt, clippy, test, cargo-deny, cargo-audit

Architecture

Client-agnostic — works with Anvil, Geth, Erigon or any RPC endpoint supporting debug_trace*. Core indexing never depends on the adapter or RPC layer. All indices are deterministic and rebuildable from the raw trace.