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
Compilers are relentless optimizers. They inline functions, eliminate dead code, reorder instructions, and pack multiple values into single storage slots. The resulting bytecode bears little resemblance to the source code that produced it.
This creates a fundamental challenge for debugging. When a transaction fails, developers need to understand what happened — but the connection between bytecode and source has been obscured. Without standardized debug information, every debugger must reverse-engineer these transformations on its own, and each compiler-debugger pair requires custom integration work.
What this format provides
ethdebug/format defines schemas including:
- Types — Describe the structure of data (integers, structs, arrays, mappings) — what shape it takes and how its parts relate
- 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
- Info schema — Bundles all debug data for a compilation, including programs, shared types, sources, and compiler metadata
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.