ethdebug format

Because debugging on Ethereum is hard.

Problem statement

Smart contracts offer the fundamental promise that code execution is verifiably transparent. Not only is this necessary to ensure network liveness, but this ability to directly observe the step-by-step operation of the Ethereum Virtual Machine (EVM) affords a foundation for public trust amongst software developers, auditors, and end-users at large.

Unfortunately, direct observation of the EVM fails to connect low-level system behavior with any code authors' original framework of meaning. Humans usually write programs in high-level languages that they must compile to a form the machine can execute. It is extremely impractical to reason about the machine-code that compilers output and the system behavior that results upon executing this code.

Traditional computing platforms have largely solved this problem through the design, standardization, and use of debugging data formats¹, which allow compilers a mechanism to specify precisely how to translate a program as the machine runs it into a program as the human wrote it. Several such formats exist in use today, most notably DWARF², and these allow ubiquitous software integration between compilers, editors, and debuggers. Sadly, no existing format suffices to cover the intrinsic differences present in smart contract programming, let alone cover some of the architectural decisions that high-level languages have made in response to the EVM's constraints.

Although it's straightforward to observe and replay the EVM directly, understanding the EVM and the smart contracts running on it remains within the domain of experts. Without a mechanism for machine-to-human translation, smart contract software quality comes at a higher cost, and any promise of trust risks erosion.

Purpose of this repository

This repository serves as a home for the working group to design a standard debugging data format for smart contracts on Ethereum-compatible networks.

Contents

This repository contains a schemas/ directory with the formal JSON Schemas defined by this project (in YAML format).

This repository also contains a number of NPM packages (currently unpublished):

• @ethdebug/format: A Node.js-compatible distribution of these schemas
• @ethdebug/format-tests: Contains a test suite for validating schemas and testing examples/other constraints.
• @ethdebug/format-web: The docusaurus site source that powers this project's homepage.

Developing locally

To build and run the site locally, please ensure you have Node.js (LTS or better) and yarn installed globally.

First, clone this repo and install the Node.js dependencies:

git clone https://github.com/ethdebug/format.git
cd format
yarn

Then, run this command to start a watcher process which rebuilds and reloads on any changes. This will open your browser to http://localhost:3000/format:

yarn start

Footnotes

1. See Debugging data format - Wikipedia ↩

2. See DWARF - Wikipedia ↩