feat(trace): Parity trace methods and output schemas

[banteg]

Proposal

Follow-up to #890: propose the nine Parity trace_* methods and their call-frame, stateDiff and vmTrace output schemas. This draft gives client teams a concrete contract to review; the choices below remain proposals, not agreed conformance requirements.

Start with src/trace/methods.yaml, src/schemas/trace.yaml and docs-api/docs/trace-profile.md. Most of the remaining diff is generated method documentation. Recursive VM traces also require schema-generation and documentation-rendering support; that tooling overlaps #855 and should be consolidated before merge.

Client impact and progress

trace-interop contains reproducible cases, pinned observations and proposed changes, with links into client sources:

Client report	Main review areas
Erigon	Filter composition and signed execution validation.
Reth	Tree-path lookup, filter composition, validation error codes and replay/VM metadata.
Nethermind	Tree-path lookup, error/output handling and stack-word encoding.
Besu	Individual replay scope, precompile visibility and trace-output correctness.

Independent reporting fixes are tracked here. The reports describe their pinned builds; a submitted or merged patch does not automatically update those observations or imply support for the wider proposal. An experimental Geth implementation is evaluated separately, without claiming upstream support.

Review requested

• Scope and support policy: all nine methods together or a staged subset; required implementation versus an explicitly agreed optional profile. This draft does not establish an optional-method policy.
• Incompatible contracts: trace_get tree paths and object-or-null results; AND between trace_filter address lists; signed transaction execution validation; and precompile-frame inclusion. The decision ledger links the alternatives, rationale and evidence. Compatibility and migration need agreement alongside the behavior.
• Testing path: adapt agreed cases to this repository's chain and .io fixtures, then establish the generator/Hive integration. No new trace_* .io fixtures or upstream Geth generator support are included yet; any CI exception needs explicit maintainer agreement.

Please comment on the specific requirements that affect your client. The working group is available for coordination; decisions and rationale should remain in public review.

Schema and tooling fixes

The VM resource now keeps its primitive definitions inside its own $id scope. Context-specific frame constraints require mined localization, reserve null transaction identity for block/filter rewards, and exclude localization and rewards from simulation/replay frames. Transaction-specific lookups exclude rewards. Unsigned calls reject conflicting legacy and dynamic fee fields.

The compatibility review now allows standard eth_call fields and ignores unknown call-object fields; null address filters mean unrestricted. Unknown selected blocks propose -32001, distinct from missing transactions (null) and pruned state (4444). Integer trace_get paths explicitly return -32602; callers convert output path integers to hex quantities. H29 distinguishes explicit CALL/CALLCODE value from inherited DELEGATECALL value and labels the latter a compatibility choice.

Review corrections and validation include independent pruning eligibility, explicit partial assessment, schema-driven input checks, and crossed-value precompile fixtures. The regenerated reports include 150 new responses from pinned native/Geth builds and pruning controls, while retaining earlier observations unchanged.

Generated trace documentation now retains array result types, shared CALL/CREATE fields, required localization, and success/failure descriptions. A versioned patch to the locked OpenRPC renderer also restores the required trace_callMany Calls parameter, its ordered tuple positions and per-tuple length constraint. The patch is applied by npm ci; a nonempty funding-then-spending example illustrates the input structure. The watch pipeline refreshes the display projection after rebuilding the spec; startup and release hooks preserve an already prepared spec.

The new nonempty tuple tests also exposed a checker defect: generated OpenRPC types changed JSON Schema items during reserialization. speccheck now preserves schema JSON. Validating every array element then exposed two existing eth_simulateV1 fixtures whose error messages conflicted with schema patterns. Those patterns were removed to match the existing contract that messages are suggestions; error codes remain enforced and both error branches require code/message.

Validation

• make build, make test (speccheck), go test ./... and go vet ./... pass with Go 1.26.1.
• Trace regressions build the actual YAML and test reference-preserving and expanded schemas under Draft 7 and Draft 2019-09, plus the actual speccheck parsing/validation path. Cases cover contextual localization/rewards, fee conflicts, success/failure frames, state changes, nonempty tuples/envelopes, invalid later array elements and deeply malformed VM children. The standalone VM resource is also compiled under its declared identity.
• All five documentation tests pass, including visibility and required status for every trace parameter, tuple order/cardinality, generated method rendering and watched rebuild/startup/release projection paths. The renderer patch was verified after a clean dependency install, and all trace examples pass schema validation. The documentation production build passes; affected generated method pages are refreshed.
• make lint completes with 117 warnings.
• Test filling and a fresh upstream-chain Hive run have not been performed for this PR. Existing schema checks and external differential results do not establish semantic conformance to the proposed namespace. Pending-state behavior, gas accounting, failure conventions and other open adoption questions still need client agreement.

H13 requires selected-state execution validation, including nonce, balance and sender-code rules with the EIP-7702 exception. This intentionally tightens legacy simulation without imposing local pool-admission policies; valid EVM halts still return traces. The proposed -32003 rejection code needs separate agreement. A fresh 560-response study distinguishes real execution from empty or malformed responses and demonstrates CREATE using the state nonce in Erigon/Nethermind. It also records the unchanged strict gist and Erigon feedback timing without assuming which revision was read.

The contract review keeps self-identifying replay envelopes, explicit failed-frame data and a genesis-to-latest filter default as intentional improvements over the legacy API. It clarifies net state changes, actual VM memory writes, frame-local outcomes and pre/post-commit response failures. Retention cannot silently narrow a filter range; unavailable history and resource limits must be explicit.

Failed CREATE results now reject successful creation addresses or deployed code. Two regression vectors fail before the change and pass afterward through referenced schemas, expanded schemas and speccheck; Go tests/vet, speccheck examples, all five documentation tests and the documentation production build pass. The linter remains at 117 warnings. No new client execution captures are claimed for these clarifications.

[banteg]

Could a maintainer approve the pending fork workflows (Test, Spellcheck and test deployment) on this draft? They are currently waiting for approval. The draft remains open for discussion; approving the checks would let us validate the proposal files independently of agreement on the behavioral recommendations.