[r3.6] docs(site): document Erigon's JSON-RPC deviations from the standard eth API - #23595
Conversation
There was a problem hiding this comment.
Pull request overview
Documents Erigon-specific JSON-RPC deviations and extensions relative to the standard eth API (plus related tracing/filters behavior), and propagates those docs into the generated llms-full.txt bundles used by docs.erigon.tech.
Changes:
- Adds/updates
ethdocs for non-standard methods (eth_getWitness,eth_getTxWitness) and a spec-shape deviation (eth_fillTransaction), plus details on block-number parsing and filter eviction behavior. - Extends tracing docs to describe opt-in reporting of beacon-chain withdrawals via
IncludeWithdrawals, and documents thegasBailOut/settings parameters for relevant trace methods. - Updates RPC daemon flags documentation to include
--rpc.subscription.filters.timeout, and regeneratesllms-full.txtoutputs.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| llms-full.txt | Regenerated combined docs output reflecting new/updated RPC deviation documentation. |
| docs/site/static/llms-full.txt | Regenerated static combined docs output for the website. |
| docs/site/docs/interacting-with-erigon/trace.md | Documents withdrawal tracing behavior and new optional trace parameters/settings. |
| docs/site/docs/interacting-with-erigon/eth.md | Documents eth namespace deviations/extensions and related behavioral differences. |
| docs/site/docs/fundamentals/modules/rpc-daemon.md | Documents the new/previously-undocumented --rpc.subscription.filters.timeout flag. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.
Suppressed comments (3)
Previously missed (3) — in code that hasn't changed since the last review.
docs/site/docs/interacting-with-erigon/eth.md:44
- The
eth_getStorageValuescurl example uses an invalid JSON shape forstorageKeys(it is shown as a quoted string like "["0x…"]" rather than a JSON array). Clients copying the example will send malformed params.
`eth_getStorageValues` originated as an Erigon extension and has since been adopted into the execution-apis specification (April 2026). It retrieves multiple storage slots for a given account in a single call, reducing round-trips compared to multiple `eth_getStorageAt` calls.
llms-full.txt:4964
- The
eth_getStorageValuescurl example uses an invalid JSON shape forstorageKeys(it is shown as a quoted string like "["0x…"]" rather than a JSON array). Clients copying the example will send malformed params.
`eth_getStorageValues` originated as an Erigon extension and has since been adopted into the execution-apis specification (April 2026). It retrieves multiple storage slots for a given account in a single call, reducing round-trips compared to multiple `eth_getStorageAt` calls.
docs/site/static/llms-full.txt:4964
- The
eth_getStorageValuescurl example uses an invalid JSON shape forstorageKeys(it is shown as a quoted string like "["0x…"]" rather than a JSON array). Clients copying the example will send malformed params.
`eth_getStorageValues` originated as an Erigon extension and has since been adopted into the execution-apis specification (April 2026). It retrieves multiple storage slots for a given account in a single call, reducing round-trips compared to multiple `eth_getStorageAt` calls.
yperbasis
left a comment
There was a problem hiding this comment.
Requesting changes for the documentation-contract issues raised in the open review threads:
- qualify the witness requirements and
txIndexvalidation for genesis; - update the
trace_replayBlockTransactionsresponse contract for the extra synthetic withdrawal entry; - correct the block-selector rules, including the incomplete required-
BlockNumberOrHashexception list and the object-wrapped special tags noted inline.
The branch also conflicts with release/3.6 after #23582. Please preserve that PR's corrected eth_getStorageValues request/result documentation during the rebase and regenerate both llms-full.txt files. The title should use the release prefix: [r3.6] docs(site): ....
Documents only where Erigon differs from the execution-apis / ethereum.org JSON-RPC spec. eth.md: - eth_getWitness / eth_getTxWitness (Erigon-only): params, return, the --prune.include-commitment-history requirement, and that getTxWitness only bounds-checks txIndex. - eth_fillTransaction (Erigon-only, geth-compatible): what it fills, the raw + tx return, no KZG generation from raw blobs. - Block number parameter format: the forms Erigon accepts beyond the spec schema, and the v3.6 rejection of quoted decimals such as "3". - Filter lifetime: 5m idle eviction for polling filters, what counts as a poll, and --rpc.subscription.filters.timeout. trace.md: - IncludeWithdrawals trace setting on trace_block and trace_replayBlockTransactions, off by default, and the different shape it takes in each. rpc-daemon.md: - Adds the missing --rpc.subscription.filters.timeout line to the flag list.
- eth_fillTransaction was standardized in execution-apis (July 2026); the deviation is the extra 'raw' field the spec dropped, not the method's existence - eth_getStorageValues was adopted into execution-apis (April 2026) - JSON null is rejected, not treated as latest, by the methods whose block-or-hash parameter is required (eth_getBlockReceipts, eth_getBlockAccessList, eth_simulateV1, eth_getWitness, eth_getTxWitness) - regenerate stale llms-full.txt artifacts
The compliance sentence was absolute; the two eth_getWitness errors carry suffixes and name the alias rather than the canonical flag; and the trace settings object is positional, so the preceding parameters are now shown.
- getWitness returns the empty witness at block 0 before both the commitment-history check and the txIndex bounds check. - Required BlockNumberOrHash rejects top-level null by type, not by a special-cased method list; the list is now illustrative. - latestExecuted and "null" are rejected only as top-level strings — BlockNumberOrHash decodes the object form through BlockNumber, which accepts both. - trace_replayBlockTransactions appends one extra entry when withdrawals are requested, so the per-transaction index mapping does not hold.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Suppressed comments (1)
docs/site/docs/interacting-with-erigon/trace.md:564
- Naming
gasBailOutdoes not explain its observable behavior. When true, execution skips rejecting the trace because the sender cannot afford the gas charge; omitted/nil defaults to false (execution/protocol/txn_executor.go:173-175andtrace_filtering.go:190-192). Document that semantic so callers can choose the value correctly.
2. `Boolean` - Optional. `gasBailOut`.
yperbasis
left a comment
There was a problem hiding this comment.
Requesting changes for the three existing open threads and the three additional documentation-contract issues noted inline:
- handle or document oversized
eth_getTxWitnessindices; - explain
gasBailOut; - align the
trace_blockselector contract; - keep the shared withdrawal response fields consistent;
- correct the shared
nullselector rules; - scope the witness self-verification guarantee.
The earlier review feedback and rebase work look addressed. Please regenerate both llms-full.txt files after updating the source docs.
- eth_getTxWitness does not reject every oversized index: the bounds check narrows with int(txIndex), so a value from 0x8000000000000000 up wraps negative and passes. - Witness self-verification covers the normal path only. Genesis and an empty access set return the empty witness without decoding it. - The null rule depends on the parameter's type: a plain BlockNumber maps top-level null to latest even when required, an optional BlockNumberOrHash falls back to the method default, and only a required BlockNumberOrHash rejects it. - trace_block takes a plain block number, so it also accepts bare integers, safe, finalized, latestExecuted and null. - gasBailOut: when true a sender who cannot afford the gas charge is still traced instead of failing the call. - rewardType gains "withdrawal" in the shared reward-action table, so a schema-based consumer does not reject the opt-in entries.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Suppressed comments (1)
llms-full.txt:6106
- This summary overstates the condition for the synthetic entry. The implementation appends it only when
stateDiffis requested,IncludeWithdrawalsis enabled, and the block actually contains withdrawals; enablingIncludeWithdrawalswith other trace types adds nothing. Include those conditions here so this result-shape table remains accurate on its own.
| `trace_replayBlockTransactions` | `Array` — one per transaction; each entry adds `transactionHash`. One extra trailing entry when withdrawals are requested — see [trace_replayBlockTransactions](#trace_replayblocktransactions) |
|
All four points fixed in 626650c. Document it for every method that enables it. The section names all six that take it as a parameter — Value-transfer bailout. Listed as its own effect: the recipient is credited without the sender being debited, so a trace can show apparent balance creation. Scope the downstream statement. This was my error — I copied a [P3] trace_filter reward entries. Corrected — Both |
yperbasis
left a comment
There was a problem hiding this comment.
[P2] Document the burn-contract credit under gasBailOut.
The warning lists the producer tip and an underfunded value recipient as credits that still occur while sender deductions are skipped, but TxnExecutor also calls AddBalance for GetBurntContract(...) on London transactions when the chain config provides one. That credit is gasUsed * baseFee, plus the blob fee on Aura after Prague, and it has no matching sender debit under gasBailOut. Gnosis and Chiado configure such a contract, so their stateDiff can show this additional apparent balance creation. Please add this chain-specific effect so the shared warning is correct for all supported Erigon chains.
Where a chain configures a burntContract -- Gnosis and Chiado do -- a London transaction credits it gasUsed * baseFee, plus the blob fee on Aura from Prague, with no matching sender debit under gasBailOut.
|
Fixed in 0f02e6c. Confirmed the credit at The shared warning now carries it as a fourth bullet, scoped to those chains and noting that chains which simply burn the base fee are unaffected, so it reads correctly whichever chain the user is on. Both |
…t casing The two block-selector parameter lists claimed Quantity while the prose allowed a bare JSON integer, which is not a standard QUANTITY. The refund bullet cites the internal Go parameter gasBailout, distinct from the JSON-RPC gasBailOut; say so.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Suppressed comments (3)
docs/site/docs/interacting-with-erigon/trace.md:686
trace_filteralso accepts a third JSON-RPC parameter,traceConfig *config.TraceConfig, aftergasBailOut(rpc/jsonrpc/trace_api.go:47); it is consumed by the filter implementation. Add that optional trace-settings object to this parameter list and regenerate the aggregate docs.
2. `Boolean` - Optional, default `false`. `gasBailOut`. See [The gasBailOut option](#the-gasbailout-option).
docs/site/docs/interacting-with-erigon/trace.md:755
- The positional signature remains incomplete:
trace_getaccepts parameter 4 astraceConfig *config.TraceConfig(rpc/jsonrpc/trace_api.go:45) and forwards it throughTransaction. Please document the optional trace-settings object aftergasBailOutand regenerate the aggregate docs.
3. `Boolean` - Optional, default `false`. `gasBailOut`. See [The gasBailOut option](#the-gasbailout-option).
docs/site/docs/interacting-with-erigon/trace.md:818
trace_transactionaccepts an additional optionaltraceConfig *config.TraceConfigparameter aftergasBailOut(rpc/jsonrpc/trace_api.go:44), and uses it while tracing the transaction. Add parameter 3 to this list and regenerate both aggregate documentation files.
2. `Boolean` - Optional, default `false`. `gasBailOut`. See [The gasBailOut option](#the-gasbailout-option).
yperbasis
left a comment
There was a problem hiding this comment.
[P2] Preserve the free-service-transaction exception.
The new bullet says that a London transaction on Gnosis or Chiado credits the configured burn contract. Before execution, however, Aura can mark a zero-fee certified transaction as free, and the burn-contract path is explicitly guarded by !msg.IsFree(). Those service transactions do not credit the burn contract. Please change this to a non-free London transaction, matching the condition already identified in the response comment.
Also, "Chains that simply burn the base fee are unaffected" should say they do not receive this extra credit. gasBailOut still changes their sender and producer balances, so "unaffected" is too broad.
Current wording, service-transaction detection, burn-credit guard.
…redit trace_replayTransaction, trace_filter, trace_get and trace_transaction all take traceConfig after gasBailOut; their parameter lists stopped short of it. The burn contract is credited only for a non-free transaction -- Aura marks zero-fee certified service transactions free and the credit is guarded by !msg.IsFree(). Chains without a burnt contract miss this credit only; every other gasBailOut effect still applies to them.
|
Both points fixed in 7258cea. Free service transactions. Verified at "Unaffected" was too broad, agreed. It now reads that chains which simply burn the base fee never receive this extra credit, and that every other effect in the list still applies to them. Also folded in the Copilot finding from the same round: |
yperbasis
left a comment
There was a problem hiding this comment.
[P2] Document TraceConfig for trace_call and trace_callMany.
The update adds the trailing TraceConfig parameter to four methods, but the parameter lists for trace_call and trace_callMany still stop at the block selector. Both RPC signatures accept a trailing TraceConfig — parameter 4 for trace_call and parameter 3 for trace_callMany — and their implementations consume it for tracer, block, and state overrides. As written, API users cannot discover or correctly position these supported settings. Please add the object parameter to both lists and regenerate the aggregate documentation files.
trace_call documentation, trace_callMany documentation, RPC signatures.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Suppressed comments (6)
docs/site/docs/interacting-with-erigon/trace.md:279
- The positional signature is still incomplete:
TraceAPI.Callaccepts a trailing*TraceConfigafter the block selector. Add parameter 4 for the optional trace-settings object before this note so callers can discover state/block overrides and other supported settings.
This method takes no `gasBailOut` parameter — it always replays with the bailout enabled. See [The gasBailOut option](#the-gasbailout-option).
llms-full.txt:6346
- The generated
trace_callparameter list still omits the trailingTraceConfigaccepted after the block selector. Document parameter 4 in the source page and regenerate this aggregate.
This method takes no `gasBailOut` parameter — it always replays with the bailout enabled. See [The gasBailOut option](#the-gasbailout-option).
docs/site/static/llms-full.txt:6346
- The generated
trace_callparameter list still omits the trailingTraceConfigaccepted after the block selector. Document parameter 4 in the source page and regenerate this aggregate.
This method takes no `gasBailOut` parameter — it always replays with the bailout enabled. See [The gasBailOut option](#the-gasbailout-option).
docs/site/docs/interacting-with-erigon/trace.md:329
- The positional signature is still incomplete:
TraceAPI.CallManyaccepts a trailing*TraceConfigafter the block selector. Add parameter 3 for the optional trace-settings object before this note.
This method takes no `gasBailOut` parameter — it always replays with the bailout enabled. See [The gasBailOut option](#the-gasbailout-option).
llms-full.txt:6395
- The generated
trace_callManyparameter list still omits the trailingTraceConfigaccepted after the block selector. Document parameter 3 in the source page and regenerate this aggregate.
This method takes no `gasBailOut` parameter — it always replays with the bailout enabled. See [The gasBailOut option](#the-gasbailout-option).
docs/site/static/llms-full.txt:6395
- The generated
trace_callManyparameter list still omits the trailingTraceConfigaccepted after the block selector. Document parameter 3 in the source page and regenerate this aggregate.
This method takes no `gasBailOut` parameter — it always replays with the bailout enabled. See [The gasBailOut option](#the-gasbailout-option).
Completes the sweep: all nine TraceAPI methods now list every positional parameter their signature accepts. trace_rawTransaction is the only one that takes no TraceConfig.
|
Fixed in e030aab — Rather than patch the two you named, I swept all nine
Both |
… one Not just Gnosis and Chiado: polygon/chain/chainspecs also defines burntContract for bor-mainnet, amoy, mumbai and bor-devnet, and TxnExecutor credits whatever address the config returns. The Aura qualifier now covers only the extra blob fee.
|
Note on the six suppressed comments in the 13:12 review: they ask for the trailing |
…rigontech#23595, erigontech#23625 to main (erigontech#23676) Ports five docs PRs merged to `release/3.6` between 2026-08-20 and 08-28. Every claim was re-derived against `main`'s own source rather than copied across — three did not survive that check, and two needed adapting. | Ported | Brings | | --- | --- | | erigontech#23359 | The state-cache environment variables | | erigontech#23587 | Caplin block production since v3.6, and the disk-storage claim in the Caplin intro | | erigontech#23593 | Pruning Modes: receipt-cache stickiness, `keep-all`, snapshot reclaim | | erigontech#23595 | `eth.md` JSON-RPC deviations and `trace.md` withdrawals / `gasBailOut` | | erigontech#23625 | The `--externalcl` correction and the Layer 2 page description | ### Written differently here, because release/3.6 is wrong for main - **`eth_getFilterLogs` no longer resets a filter's eviction deadline.** erigontech#23296 rewrote it to read the stored criteria and serve them through the `eth_getLogs` path, dropping the `TouchSubscription` call `release/3.6` still makes. A client polling only with `eth_getFilterLogs` loses its filter after five idle minutes. This documents it as it is, but it reads like an unintended side effect of erigontech#23296 rather than a deliberate change. - **`BlockNumberOrHash.UnmarshalJSON` has a top-level `"latestExecuted"` case on `main`**, so the bare string works on `eth_call` and friends. On `release/3.6` only the object-wrapped form does. - **`eth_fillTransaction` rejects three inputs on `main`** that `release/3.6` accepts: `gasPrice` with `authorizationList`, an empty `authorizationList`, and a derived `maxFeePerGas` or `maxFeePerBlobGas` that overflows 256 bits. - **The state caches do not start at a flat 1024 entries.** Start is `max(1024, shards × 16)` bounded by the ceiling, with the shard count following `min(ceiling/64, GOMAXPROCS × 16)` rounded to powers of two. `minShardStart` does not exist on `release/3.6` at all. ### Adapted for the Polygon removal (erigontech#23497) The `gasBailOut` burn-contract note drops the Bor chains, and the replay-path note drops Bor state-sync transactions. ### Verified unchanged, then ported as written `eth_getWitness` / `eth_getTxWitness` including the genesis and empty-access-set early returns; the withdrawals `stateDiff` shapes; Caplin payload preparation, head publication and default graffiti (`payload_preparation.go` is byte-identical across the branches); the `--prune.include-receipts` stickiness warning; and the `STATE_CACHE_*` defaults, whose "new in v3.6" comparisons check out against `release/3.5`. The llms.txt cross-link on `why-using-erigon` is deliberately left out — it belongs to erigontech#23336. Follows erigontech#23675. Gate: `npm ci && npm run build` green, `generate-llms.py --check` OK (72 pages), `render-disk-sizes.py --check` OK, editorial scan and `sidebar_position` lint clean. --------- Co-authored-by: Bloxster <gianni.morselli@erigon.tech>
Documents where Erigon's
ethandtraceAPIs deviate from the standard spec, so callers meet these differences in the docs rather than in production. Rebased ontorelease/3.6after #23582, whoseeth_getStorageValuescorrections are preserved.eth— the two non-standard witness methods and the commitment history they need;eth_fillTransaction's geth-shaped result, its ignoredtypefield, which types carrygasPrice: nullor omitchainId, the unsignedhashthat changes once signed, and the unsupported blob sidecar; which block-number forms Erigon accepts and which it now rejects, quoted decimals being a v3.6 breaking change; and the five-minute filter timeout.trace— howIncludeWithdrawalssurfaces beacon-chain withdrawals, including the extra trailing entrytrace_replayBlockTransactionsappends that positional consumers must skip. A new shared section coversgasBailOutfor all nine methods that enable it: it never deducts gas or blob fees, skips refunds, still pays the producer, and credits an unaffordable value transfer without debiting its sender, and on any chain with a configured burn contract credits that contract on a non-free transaction. Also completes the positional signatures with the trailingTraceConfig, and corrects the block selector and thetrace_filterreward entries, which carry no transaction metadata.Flags — adds
--rpc.subscription.filters.timeoutto the RPC daemon page.An info card at the top of the
ethpage notes thatexecution-apisis still a moving specification, so part of what is listed is convergence rather than defects.