ethereum / ethereum/execution-apis
Standardizing the Parity trace_* APIs and their output formats
- Dominant language
- Io
- Stars
- 1.1k
- Forks
- 530
- Avg merge
- 5d 8h
- Merged PRs (30d)
- 9
Description
Several execution clients implement the Parity `trace_*` namespace, but differences in behavior make it difficult for tooling to consume traces consistently.
While investigating [evm-trace’s conversion of compressed `vmTrace` output into full execution traces](https://github.com/ApeWorX/evm-trace/pull/84), we found discrepancies that led to fixes proposed across multiple client implementations. This raised a broader question: would execution-apis be the right place to specify these methods and establish shared conformance tests?
The traditional namespace comprises:
- Execution and replay: `trace_call`, `trace_callMany`, `trace_rawTransaction`, `trace_replayTransaction`, `trace_replayBlockTransactions`.
- Historical call traces: `trace_block`, `trace_transaction`, `trace_get`, `trace_filter`.
Our source survey found all nine methods in Erigon, Reth, and Nethermind. Besu implements eight, excluding `trace_replayTransaction`. Geth exposes related functionality through `debug_*`, including `flatCallTracer`, but does not implement this namespace.
Method availability does not necessarily imply compatible behavior. For example, the implementations differ in how `trace_get` interprets its position argument and whether it returns an object or an array. The compressed `vmTrace` format also needs precise semantics and test vectors if consumers are to reconstruct execution state reliably.
There are two questions we would like to clarify before preparing a specification:
1. **Is there interest in standardizing the existing `trace_*` methods and output formats here**, including resolving implementation differences and adding cross-client tests?
2. **Would Geth be interested in implementing an agreed specification? Alternatively, would this repository accept an optional tracing profile**, with conformance required from clients that expose it?
The [contributors guide](https://github.com/ethereum/execution-apis/blob/main/docs-api/docs/contributors-guide.md) describes specified APIs as canonical requirements for RPC compatibility, so we would like to understand whether an optional profile fits the repository’s intended scope.
It may also make sense to separate execution/replay from historical search. `trace_filter` does not inherently require an address index: some clients replay blocks, while Erigon uses indexes to narrow the work. A specification could define observable behavior, query limits, and unavailable-history errors without prescribing storage architecture or requiring archive retention.
We can contribute concrete discrepancy reports and regression cases from the evm-trace investigation. Feedback on scope and the appropriate standardization path would help guide that work.
Contributor guide
Research direction
Read docs-api/docs/contributors-guide.md first, then compare the listed trace_* methods and their behavior across the execution clients named in the issue. The work is complete when the scope and optional-profile question are resolved into an agreed specification, with defined output semantics and shared conformance tests.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100