Project overview
ethdebug/format is an open specification for debugging information in EVM-based smart contracts. It provides a standard way for compilers to emit rich debug data that debuggers can use to help developers understand what their contracts are doing at runtime.
The problem
When a compiler optimizes source code into EVM bytecode, it transforms the original program structure in ways that make debugging difficult. Instructions get reordered, variables get eliminated, and the connection between bytecode and source code becomes obscured. Without standardized debug information, every debugger must reverse-engineer these transformations — or worse, each compiler-debugger pair requires custom integration.
What this format provides
The ethdebug/format specification defines schemas for:
- Types — Describe the structure of data (integers, structs, arrays, mappings) so debuggers can decode raw bytes into meaningful values
- Pointers — Describe where data lives at runtime, including dynamic locations that depend on execution state
- Programs — Describe the runtime context at each bytecode instruction, including which variables are in scope and what source code corresponds to each operation
Get started
Building a debugger?
Learn how to consume ethdebug/format data to build better debugging tools.
Building a compiler?
Learn how to emit ethdebug/format data from your compiler.
Or explore the concepts to understand the format's design, browse examples to see it in action, or dive into the specification for formal definitions.