EDB: Source-Level Time-Travel Debugger for Ethereum Smart Contracts

Introduction

EDB, the Ethereum Project Debugger, is a cutting-edge tool that provides source-level time-travel debugging for Ethereum smart contracts. It aims to simplify the complex process of debugging Solidity code by offering a clear view into execution at the source level, rather than relying on low-level EVM operations. EDB introduces four crucial debugging features previously missing from the Ethereum ecosystem: step-by-step execution at the source code level, local variable value inspection, custom expression evaluation during debug execution, and breakpoints & watchpoints for fine-grained control.

Installation

To get started with EDB, you'll need an Ethereum RPC endpoint, which can be a public service like Infura/Alchemy or a local node.

There are two primary ways to install EDB:

One-line Install

For a quick setup, use the provided one-line installation script:

curl -sSL https://install.edb.sh | bash

Build from Source

Alternatively, you can build EDB directly from its source code:

# Clone the repository
git clone https://github.com/edb-rs/edb
cd edb

# Build all components
cargo build --release

# Install binaries
cargo install --path crates/edb
cargo install --path crates/rpc-proxy
cargo install --path crates/tui

Examples

EDB allows you to debug on-chain transactions with ease.

Debug an On-Chain Transaction

You can debug any transaction from mainnet or testnets using the following command:

edb --rpc-urls <RPC_ENDPOINTS> replay 0x5bedd885ff628e935fe47dacb6065c6ac80514a85ec6444578fd1ba092904096

Replace <RPC_ENDPOINTS> with a comma-separated list of your RPC endpoint URLs. EDB uses these endpoints to obtain on-chain states for transaction replay. Providing more endpoints can speed up the replay process. If no endpoints are specified, EDB defaults to ten popular public RPC endpoints, which might be slower or less reliable.

By default, EDB launches a Terminal UI (TUI) debugger, providing an interactive experience. Type ? within the TUI to access the help page.

Why Use EDB?

Traditional Ethereum debugging tools often operate at the bytecode level, making it challenging to understand the corresponding Solidity code. Tools like Remix IDE's debugger, Foundry's forge debug, and Hardhat's console debugger provide opcode-by-opcode execution, stack traces, and raw memory dumps. While powerful, these require developers to manually map between high-level Solidity constructs and low-level EVM operations, a complex and error-prone task.

The core issue is that while Solidity compilers generate source maps to link bytecode back to source code, these mappings are often fragile and imprecise, especially with optimized contracts. Existing debuggers rely on these source maps but struggle to reliably reconstruct high-level variable values, function call contexts, or complex data structures from raw EVM state. Source maps frequently point to incorrect lines or become unreliable when compiler optimizations are enabled.

EDB's innovative solution involves instrumenting Solidity contracts at the source code level. By inserting strategic debugging hooks during compilation, EDB creates contracts that can report their own state in terms of your original high-level constructs.

What makes EDB different:

True source-level debugging: Step through your actual Solidity code, not disassembled bytecode.
Reliable variable inspection: Access any local variable, struct field, or array element with confidence.
Expression evaluation: Evaluate arbitrary Solidity expressions against the current execution state.
Time-travel capabilities: Navigate backward and forward through execution history.
Breakpoints & watchpoints: Set conditional and unconditional breakpoints, and watchpoints on expressions.