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
- Each client's trace JSON format differs slightly
- How corner cases are handled is not defined
- Because formats vary, it is hard to build tools that automatically compare execution results across clients
After EIP-3155
- All clients log execution steps in the same JSON format
- Corner cases such as empty-array initialization and output rules on error become clear
- Differential fuzzing that checks client implementations against each other becomes possible
- When a chain split occurs, the execution step where the difference arose can be found quickly
Who is affected
- Client teams: Go-Ethereum already follows this format, while OpenEthereum, Besu, and Nethermind need to slightly modify the JSON output of their existing trace tools.
- Test and security infrastructure developers: Differential fuzzers and debugging tools that compare traces from multiple clients line by line can be built on top of the common format.
- Smart contract developers: Debugging becomes easier because the same format of execution log is obtained regardless of which client produced the trace.
- Ordinary users: Since protocol rules remain unchanged, nothing changes directly; the indirect effect is that client bugs are found faster.
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.