debug: specify callTracer output and add debug_traceCall

[MysticRyuujin]

Specifies the callTracer output (undefined until now) for debug_traceTransaction, debug_traceBlockByNumber/ByHash, and a new debug_traceCall. Same approach as the opcode tracer spec (#762); other named tracers keep the unconstrained branch.

Stacked on the Amsterdam chain bump (#867); the first three commits are that PR. Review the last four commits here.

What's in it

• CallFrame / CallLog / CallTracerConfig / CallTracerBlockEntry (src/schemas/call-tracer.yaml) with per-field presence and omission rules; recursion via an $id self-ref.
• debug_traceCall: GenericTransaction, optional block param (default latest), and TraceCallConfig (reuses the eth_simulateV1 overrides). A revert is a traced result, not a JSON-RPC error.
• Tooling: specgen passes absolute-URI $refs through so the recursive schema survives, and speccheck selects the anyOf branch for the tracer each fixture requests. Without that selection, trace-result validation was vacuous, including for the existing opcode branch. Negative tests prove both.
• 21 fixtures exercising nested call trees: inner reverts, STATICCALL write protection, DELEGATECALL logs, CALLCODE, precompile calls, and CREATE followed by SELFDESTRUCT. The scenarios come from the calltree contract in hivechain (cmd/hivechain: add calltree contract and tx mods for callTracer testing hive#1587, merged), so the fixtures regenerate from upstream. The set includes the omitted-block-param form of debug_traceCall, which fills now that eth/tracers: make debug_traceCall block parameter optional go-ethereum#35583 is merged.

Decisions already baked into the spec (raise it if you object, but the data settled these):

• error is exactly "execution reverted" for REVERT, free-form otherwise. That is the only string all clients agree on.
• root gasUsed equals receipt gasUsed (4/5 clients; besu to align).
• reverted-frame logs are cleared (receipt consistency; reth to align).

Conformance, original 18 fixtures (hive rpc-compat, glamsterdam-devnet-8 images, 2026-08-25). The three fixtures added later have their own table below. Every other debug_* failure these clients show also occurs on main's fixtures, so the rows below are the whole delta.

client	result	changes needed
go-ethereum	18/18	none; ethereum/go-ethereum#35583 (merged 2026-08-28) made the debug_traceCall block param optional
erigon	18/18	none
reth	17/18	return -32000 instead of -32001 for an out-of-range block in debug_traceCall
besu	15/18	honor onlyTopCall (still returns nested calls); accept a block hash as the block param
nethermind	13/18	stop base-fee validation of debug_traceCall calls that carry no fee fields; all five failures are max fee per gas less than block base fee errors where the reference traces
ethrex	1/18	debug_trace* not usable yet; tracked as not-yet-implemented, not a conformance gap

Conformance, fixtures added after that run (hive rpc-compat, ethpandaops master/main images, 2026-09-21). trace-call-omitted-block is speconly; the other two are exact-match. Side finding from the client builds: reth main and nethermind master add the EIP-8037 gas fields (regularGasUsed/executionGasUsed, stateGasUsed, gasRefund) to callTracer frames when tracing at the Amsterdam head, so the exact-match debug_traceCall/calltracer-only-top-call fixture fails on both before and after the index fixes. That is the #852 follow-up surfacing early, not an index issue.

client	trace-call-omitted-block	calltracer-with-log-index	calltracer-only-top-call-with-log	changes needed
go-ethereum	pass	pass	pass	none
erigon	pass	pass	pass	none since erigontech/erigon#23797 (merged 2026-09-09); the Sep 7 main image still returns transaction-local 0x0, current main built from source passes both
reth	pass	fail	fail	number logs[].index block-globally in debug_traceTransaction (0x0 for 0x3); report position 0 under onlyTopCall (returns 0x8). Draft fixes: paradigmxyz/revm-inspectors#512 + paradigmxyz/reth#27356, both fixtures pass on the patched build
nethermind	pass	fail	fail	emit logs[].index; the rest of both frames matches byte for byte. Draft fix: NethermindEth/nethermind#13636, both fixtures pass on the patched build
besu	pass	fail	fail	honor withLog (the logs array is missing entirely). Draft fix: besu-eth/besu#11342 implements withLog with position and index, both fixtures pass on the patched build
ethrex	not run	not run	not run	cannot import the test chain (lambdaclass/ethrex#6954), so hive cannot measure it. Its callTracer already numbers index block-globally; draft lambdaclass/ethrex#7294 fixes onlyTopCall log filtering and makes debug_traceCall start at zero, unit-tested

logs[].index is now defined (2026-09-21): required, block-global, equal to the receipt logIndex, as proposed by @bomanaps and agreed on the client call. This is geth's current behavior. erigon and reth number transaction-locally in debug_traceTransaction, and nethermind omits the field; the existing withLog fixtures did not catch this because they trace the first log-emitting transaction of a block or trace a whole block, where accumulation gives the same numbers. Two new exact-match fixtures enforce this and pair each trace with its receipt: calltracer-with-log-index traces the second log-emitting transaction of a block, so transaction-local numbering fails it, and calltracer-only-top-call-with-log traces the calltree root with onlyTopCall, where the root log keeps index 2 behind two unreported nested logs, so renumbering under onlyTopCall fails it. The second table above has the measured results. That run also exposed an ambiguity in position under onlyTopCall (geth 0, reth 8, nethermind 0): the spec now says position is 0 when onlyTopCall is set, since no subcall frames are collected.

EIP-8037 / #852: this PR specs the fork-independent frame shape only. CallFrame keeps additionalProperties open, so the regularGasUsed/stateGasUsed/gasRefund fields proposed in #852 drop in as optional fields on top, and the Amsterdam chain underneath already produces post-fork traces to generate fixtures against. Thanks @qu0b for the EIP-8037 groundwork and the client survey.

Known issue: hive replays the exact-match tracer fixtures correctly either way, but validates the speconly subset against the whole result schema, where the unconstrained named-tracer branch accepts anything. Until ethereum/hive#1588 adds the same tracer-aware branch selection speccheck uses here, that hive-side validation stays vacuous for trace methods. speccheck already enforces it when fixtures are generated, so this is a hive reporting gap, not a spec gap, and not a blocker.

Update 2026-08-28: rebased on the current #867, which is itself rebased on main and pins go-ethereum master. Added the omitted-block-param fixture that was waiting on ethereum/go-ethereum#35583. Fill, speccheck, lint, and the tools tests all pass.

[bomanaps]

The index should be block-global so to match receipt logIndex since that is the only semantics where it has real cross-reference value, and for debug_traceTransaction implementations would need to replay prior transactions to produce the correct value but debug_traceBlock gets it for free from accumulated state. I prefer we define it as block-global rather than leave it undefined and differ per client.

[MysticRyuujin]

I have opened draft PRs against the other clients to unify the index log behavior and hopefully put at least a couple more eyes on the decision.