debug RPC endpoints standardization

[macfarla]

spec to standardise debug endpoints ethereum/execution-apis#762
adds OpenRPC method and schema definitions for:
• debug_traceTransaction
• debug_traceBlockByNumber

spec is still draft but stable, think we could start addressing the discrepancies

pandaops report on debug endpoints differences across clients https://investigations.ethpandaops.io/2026-01/trace-comparisons/

[macfarla]

Fixed by #10116

#	Change	Files
1	Fix returnValue — add 0x prefix (was stripping it with substring(2))	OpCodeLoggerTracerResult.java
3	Fix memory encoding — bytes32 (32-byte zero-padded) instead of compact hex	StructLog.java
5	Add refund field — gas refund counter, omitted when zero	StructLog.java

---

Fixed by #10117

#	Change	Files	Notes
2	Fix error field type: String[] → String	StructLogWithError.java	Spec requires a plain string; Besu emits a JSON array
4	Fix storage key/value encoding: add 0x prefix + bytes32 zero-padding	StructLog.formatStorage()	Keys and values should match memory format, not compact hex

---

Medium Priority (spec compliance, not crash-level bugs)

#	Change	Files	Notes
6	Genesis block (blockNumber=0) → return error response	DebugTraceBlockByNumber.java	Spec says genesis block is invalid input
7	Unknown transaction hash → return error response	DebugTraceTransaction.java	Spec says unknown tx returns error, not null result
8	Add enableMemory param — default false, omit memory field unless enabled	TransactionTraceParams.java, StructLog.java, DebugOperationTracer.java	Currently memory is always captured
9	Add enableReturnData param + returnData field in StructLog	TransactionTraceParams.java, StructLog.java, DebugOperationTracer.java	Spec exposes per-opcode return data
11	Add limit param — stop capturing trace after N steps	OpCodeTracerConfig.java, TransactionTraceParams.java, DebugOperationTracer.java	Useful for large contracts; spec-defined

---

Hard / High Effort

#	Change	Files	Notes
10	Fix storage snapshot timing — emit storage field only at SLOAD/SSTORE opcodes	DebugOperationTracer.java, TraceFrame.java	Currently captured at every post-execution step once any storage is written; requires opcode-aware capture logic

---

Out of Scope

#	Change	Notes
12	timeout param — abort tracing after N milliseconds	Requires cooperative interruption of the EVM execution loop; significant risk of leaving state mid-execution

[MysticRyuujin]

I don't think it will impact your work but we put debug_traceBlockByHash in scope for the spec too, I assume it's the same tracer code regardless.

[vivek-0509]

Hey @macfarla , I'd like to pick up Item 2 (fix error field type String[] -> String in StructLogWithError). Happy to open a PR for it, let me know if that works or if you're already planning to address it.

[macfarla]

@vivek-0509 2 and 4 should be addressed by #10117 per the linked PR

[macfarla]

6,7,8,9 still up for grabs at this stage. I will update this issue with any progress.
10,11 likely require more up-front thinking

[vivek-0509]

@macfarla Thanks, I’ll be making a PR for the 6th one.