Skip to main content

For debugger authors

You're building a debugger, transaction tracer, or analysis tool. Here's how ethdebug/format helps you understand smart contract execution.

What the format gives you​

With ethdebug/format data, your debugger can:

  • Decode raw bytes into meaningful values — Know that 32 bytes at a storage slot represent a uint256 balance or a mapping(address => uint)
  • Find variable values at runtime — Resolve pointers to locate data in storage, memory, or the stack, even when locations are computed dynamically
  • Map bytecode to source — Show users which line of source code corresponds to the current instruction
  • Display variables in scope — Know which variables exist at each point in execution

Quick example: Reading a type​

Type information tells you how to interpret bytes. Here's what a simple uint256 type looks like in ethdebug/format:

{
  "kind": "uint",
  "bits": 256
}

And a more complex struct:

{
  "kind": "struct",
  "name": "Position",
  "members": [
    { "name": "x", "type": { "kind": "int", "bits": 256 } },
    { "name": "y", "type": { "kind": "int", "bits": 256 } }
  ]
}

Your debugger reads these definitions and uses them to decode raw bytes from EVM state into values users can understand.

Quick example: Resolving a pointer​

Pointers describe where data lives. A simple storage variable pointer:

{
  "location": "storage",
  "slot": "0x0"
}

This says: "read from storage slot 0." But pointers can express complex, dynamic locations too — like array elements or mapping values whose locations depend on runtime state.

What you need to implement​

To consume ethdebug/format, your debugger needs:

  1. Schema parsing — Load and validate ethdebug/format JSON
  2. Type decoding — Convert bytes to values based on type definitions
  3. Pointer resolution — Evaluate pointer expressions against EVM state
  4. Program interpretation — Track context as execution progresses

Go deeper​

Understand the concepts

Learn the mental models behind types, pointers, and programs.

Concepts →

Implementation guide

Walk through a reference implementation of pointer dereferencing.

Dereferencing pointers →

Explore by topic​

  • Types — How the format describes data structures
  • Pointers — How the format describes data locations
  • Programs — How the format describes runtime context
  • Specification — Formal schema definitions