Skip to content

feat(debug): align debug_trace* opcode tracer with execution-apis#762#12058

Closed
0xDevNinja wants to merge 1 commit into
NethermindEth:masterfrom
0xDevNinja:feat/12040-debug-trace-opcode-spec-align
Closed

feat(debug): align debug_trace* opcode tracer with execution-apis#762#12058
0xDevNinja wants to merge 1 commit into
NethermindEth:masterfrom
0xDevNinja:feat/12040-debug-trace-opcode-spec-align

Conversation

@0xDevNinja

Copy link
Copy Markdown
Contributor

Closes #12040

Changes

Aligns the default opcode (struct) logger output of debug_traceTransaction, debug_traceBlockByNumber and debug_traceBlockByHash with the standardized format from execution-apis#762. The same four fixes are applied to both struct loggers — the object-building GethLikeTxMemoryTracer and the direct-streaming GethLikeTxDirectStreamingTracer — so the streamed and in-memory responses stay identical:

  1. error absent when no error occurred — was always serialized as "error": null. The GethTxTraceEntry.Error attribute now uses WhenWritingNull, and the streaming logger no longer writes a null error.
  2. storage only on SLOAD/SSTORE entries, omitted when empty — previously a cumulative snapshot was copied onto every opcode entry, emitting "storage": {} on non-storage ops. The cumulative per-frame snapshot is now attached to an entry only when that opcode reads or writes storage, and omitted when there is nothing to report.
  3. memory words 0x-prefixed bytes32TraceMemory.ToHexWordList() and the streaming memory path (including the zero-word padding) now prefix each word with 0x.
  4. storage keys/values 0x-prefixed bytes32 — the storage snapshot keys and values are now 0x-prefixed.

Already compliant and unchanged: stack encoding, top-level field names (gas/failed/returnValue/structLogs), integer gas/gasCost, op opcode-name string, and the block-trace { txHash, result } pairing.

Verified the exact wire format against the conformance fixtures shipped in #762 (trace-block-memory-encoding, trace-block-storage-encoding, trace-block-storage-snapshot-timing).

Notes / scope

Types of changes

What types of changes does your code introduce?

  • Bugfix (a non-breaking change that fixes an issue)
  • New feature (a non-breaking change that adds functionality)
  • Breaking change (a change that causes existing functionality not to work as expected)
  • Optimization
  • Refactoring
  • Documentation update
  • Build-related changes
  • Other: Description

Testing

Requires testing

  • Yes
  • No

If yes, did you write tests?

  • Yes
  • No

Notes on testing

Updated the existing debug_trace* expectation fixtures (DebugRpcModuleTests) and the geth tracer unit tests (GethLikeTxMemoryTracerTests, GethLikeTxTraceConverterTests) to the new format. Added Streaming_tracer_emits_spec_aligned_wire_format, which drives the streaming struct logger over a real execution and asserts the absence of error/empty storage and 0x-prefixed memory words. All trace test suites pass.

Documentation

Requires documentation update

  • Yes
  • No

Requires explanation in Release Notes

  • Yes
  • No

The debug_trace* default struct-logger output now matches execution-apis#762: the error field is omitted when no error occurred, storage is emitted only on SLOAD/SSTORE entries (no more empty {}), and memory words and storage keys/values are 0x-prefixed.

Bring the default opcode (struct) logger output for debug_traceTransaction,
debug_traceBlockByNumber and debug_traceBlockByHash in line with the
standardized format from execution-apis#762, across both the object-building
and the direct-streaming struct loggers:

- omit the error field entirely when no error occurred (was always error: null)
- attach the storage snapshot only to SLOAD/SSTORE entries and omit it when
  empty, instead of copying a cumulative snapshot onto every opcode entry
- encode memory words as 0x-prefixed bytes32
- encode storage keys and values as 0x-prefixed bytes32

Closes NethermindEth#12040
@0xDevNinja

Copy link
Copy Markdown
Contributor Author

Closing in favor of #12056, which already covers the same execution-apis#762 wire-format alignment and additionally fixes the op-level storage capture gating. No need for a duplicate.

@0xDevNinja 0xDevNinja closed this Jun 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Align debug_trace* opcode tracer with execution-apis#762 spec

1 participant