EIP-3155 EVM Trace Standard Format (EVM trace specification)

No call decision · EVM & execution · EIP status Last Call · created 2020-12-07

Standardizes the trace that Ethereum clients produce when recording EVM execution step by step into a common JSON format. All clients will log in the same format.

Why it is needed

Ethereum has multiple clients, such as Go-Ethereum, Besu, and Nethermind, and all of them must execute smart contracts under the same rules. To inspect the execution process, each client has already implemented a trace feature that records every instruction, but because the common format was never rigorously defined, outputs differed slightly between implementations. When formats differ, it becomes hard to build tools that automatically compare execution results across clients, which greatly reduces the usefulness of traces. This EIP moves the format to a prominent, official specification and rigorously defines corner cases that earlier versions did not address. Once all major clients implement it, differential fuzzing infrastructure can be built to compare EVM implementations across mainnet and upcoming hard forks, making it possible to find bugs hidden in clients or quickly pinpoint execution differences when a chain split occurs.

What changes

Today

After EIP-3155

Who is affected

In depth

Required Fields for Per-Operation Output

The CUT MUST output one JSON object for every operation. The required fields are pc (Number, program counter), op (Number, opcode), gas (Hex-Number, gas remaining before executing this operation), gasCost (Hex-Number, gas cost of this operation), memSize (Number, size of the memory array), stack (array of Hex-Number, all values on the stack), depth (Number, call stack depth), returnData (Hex-String, data returned by a function call), and refund (Number, the global gas refund amount). Data types are defined separately as Number, Hex-Number, String, Hex-String, Array, Key-Value, and Boolean.

Optional Fields and Omission Rules

opName (String, operation name), error (Hex-String, error description, including the revert reason if supported), memory (array of Hex-String), and storage (Key-Value) are optional fields. If the CUT does not output memory or storage values (tracing unsupported or disabled via configuration), the field itself is omitted. However, memSize MUST be present regardless of whether memory is supported. Because the state root already reflects all storage changes, clients SHOULD implement a way to turn off storage logging. Field output order SHOULD also follow the order given in the specification.

Timing of Values and Corner Cases

stack, memory, and memSize are the values before the operation is executed. Array properties (stack, memory) MUST be initialized as empty arrays ("stack":[]), not null. If an error occurs, a line for the STOP operation MUST NOT be output. Pinning down these details, which previously varied by implementation in earlier specifications, makes it possible to compare outputs across clients line by line.

Summary and Error Handling at Execution End

When execution finishes, the CUT MUST output the summary information as a single jsonl object. The required fields are stateRoot (Hex-String, the root of the state trie after the transaction executes), output (the function's return value), gasUsed (Hex-Number, total gas spent by the transaction), and pass (Boolean, whether the transaction succeeded). Optional fields include time (Number, execution time in nanoseconds) and fork (String, the name of the fork rules applied during execution).

Compatibility with Existing Clients

Because this EIP only adds optional tracing infrastructure, it is fully backwards compatible with the Ethereum protocol. It is already fully compatible with Go-Ethereum, while OpenEthereum (openethereum-evm), Besu (evmtool), and Nethermind (nethtest) need to slightly modify their JSON output to match the stricter specification. A new client must implement this format to join the differential fuzzing group. The original text includes a full trace example obtained by running sample code with Besu's evmtool, included as a test case.

Security considerations

Tracing is an expensive operation. Exposing the trace generation endpoint publicly could become a vector for denial-of-service (DoS) attacks. Clients should therefore consider placing the trace endpoint behind a separate flag from other endpoints.

Progress status

This EIP was created on December 7, 2020, and its current status is Last Call, with a last-call-deadline of March 1, 2025. Last Call is the final review stage before finalization, and details may still change based on feedback received during this period. Its category is Interface under the Standards Track, a standard concerning client interfaces rather than consensus rules.

Original EIP · ← EIPs