Skip to content

[r3.6] docs(site): document Erigon's JSON-RPC deviations from the standard eth API - #23595

Merged
bloxster merged 19 commits into
release/3.6from
docs/v36-rpc
Aug 28, 2026
Merged

bloxster merged 19 commits into
release/3.6from
docs/v36-rpc

Conversation

@bloxster

@bloxster bloxster commented Aug 26, 2026 •

Copy link
Copy Markdown
Collaborator

Documents where Erigon's eth and trace APIs deviate from the standard spec, so callers meet these differences in the docs rather than in production. Rebased onto release/3.6 after #23582, whose eth_getStorageValues corrections are preserved.

eth — the two non-standard witness methods and the commitment history they need; eth_fillTransaction's geth-shaped result, its ignored type field, which types carry gasPrice: null or omit chainId, the unsigned hash that 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 — how IncludeWithdrawals surfaces beacon-chain withdrawals, including the extra trailing entry trace_replayBlockTransactions appends that positional consumers must skip. A new shared section covers gasBailOut for 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 trailing TraceConfig, and corrects the block selector and the trace_filter reward entries, which carry no transaction metadata.

Flags — adds --rpc.subscription.filters.timeout to the RPC daemon page.

An info card at the top of the eth page notes that execution-apis is still a moving specification, so part of what is listed is convergence rather than defects.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 eth docs 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 the gasBailOut/settings parameters for relevant trace methods.
  • Updates RPC daemon flags documentation to include --rpc.subscription.filters.timeout, and regenerates llms-full.txt outputs.

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.

Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/trace.md

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_getStorageValues curl example uses an invalid JSON shape for storageKeys (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_getStorageValues curl example uses an invalid JSON shape for storageKeys (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_getStorageValues curl example uses an invalid JSON shape for storageKeys (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.

@bloxster
bloxster marked this pull request as ready for review August 26, 2026 11:50
@yperbasis
yperbasis requested review from awskii and lupin012 and a balanced review from Copilot August 26, 2026 14:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/trace.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated

@yperbasis yperbasis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes for the documentation-contract issues raised in the open review threads:

  • qualify the witness requirements and txIndex validation for genesis;
  • update the trace_replayBlockTransactions response contract for the extra synthetic withdrawal entry;
  • correct the block-selector rules, including the incomplete required-BlockNumberOrHash exception 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): ....

Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
@bloxster bloxster changed the title docs(site): document Erigon's JSON-RPC deviations from the standard eth API [r3.6] docs(site): document Erigon's JSON-RPC deviations from the standard eth API Aug 27, 2026
Bloxster added 4 commits August 27, 2026 08:54
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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 gasBailOut does 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-175 and trace_filtering.go:190-192). Document that semantic so callers can choose the value correctly.
2. `Boolean` - Optional. `gasBailOut`.

Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/trace.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/trace.md Outdated

@yperbasis yperbasis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes for the three existing open threads and the three additional documentation-contract issues noted inline:

  • handle or document oversized eth_getTxWitness indices;
  • explain gasBailOut;
  • align the trace_block selector contract;
  • keep the shared withdrawal response fields consistent;
  • correct the shared null selector 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.

Comment thread docs/site/docs/interacting-with-erigon/trace.md
Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
- 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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 stateDiff is requested, IncludeWithdrawals is enabled, and the block actually contains withdrawals; enabling IncludeWithdrawals with 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) |

Comment thread docs/site/docs/interacting-with-erigon/trace.md Outdated
Comment thread docs/site/docs/interacting-with-erigon/eth.md Outdated
Comment thread llms-full.txt Outdated
Comment thread docs/site/static/llms-full.txt Outdated
Comment thread docs/site/static/llms-full.txt Outdated
@bloxster

Copy link
Copy Markdown
Collaborator Author

All four points fixed in 626650c. gasBailOut now has one shared section, The gasBailOut option, rather than a warning copied per method.

Document it for every method that enables it. The section names all six that take it as a parameter — trace_replayBlockTransactions, trace_replayTransaction, trace_block, trace_transaction, trace_get, trace_filter — and the three that take no parameter and always enable it internally, trace_call, trace_callMany, trace_rawTransaction (confirmed at trace_adhoc.go:1223). The four methods that accepted it but never documented it now list it, and the three forcing methods say so in their own parameter lists. Nine references to the shared anchor.

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 trace_replayBlockTransactions warning onto trace_block, which returns trace entries and no stateDiff. The shared section drops the method-specific wording and scopes propagation correctly: a historical trace-only block takes the parallel path and replays each transaction against its own canonical pre-state, so nothing propagates; the sequential path applies when stateDiff or vmTrace is requested, for Bor state-sync transactions, and for single-transaction blocks (trace_filtering.go:904).

[P3] trace_filter reward entries. Corrected — newRewardTrace sets blockHash, blockNumber, type and traceAddress and no transaction fields, so the return description no longer claims every entry carries transactionHash and transactionPosition.

Both llms-full.txt files regenerated; --check and the site build are green.

@yperbasis
yperbasis requested a balanced review from Copilot August 28, 2026 11:27

@yperbasis yperbasis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

Current warning, credit logic, Gnosis configuration.

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.
@bloxster

Copy link
Copy Markdown
Collaborator Author

Fixed in 0f02e6c. Confirmed the credit at txn_executor.go:697-711 — GetBurntContract on a London, non-free transaction, AddBalance of gasUsed * baseFee, plus st.evm.BlobFee when IsAura && IsPrague — and that burntContract appears in only two chainspecs, gnosis.json and chiado.json.

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 llms-full.txt files regenerated.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Comment thread docs/site/docs/interacting-with-erigon/trace.md
Comment thread docs/site/docs/interacting-with-erigon/trace.md
Comment thread docs/site/docs/interacting-with-erigon/trace.md Outdated
…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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_filter also accepts a third JSON-RPC parameter, traceConfig *config.TraceConfig, after gasBailOut (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_get accepts parameter 4 as traceConfig *config.TraceConfig (rpc/jsonrpc/trace_api.go:45) and forwards it through Transaction. Please document the optional trace-settings object after gasBailOut and 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_transaction accepts an additional optional traceConfig *config.TraceConfig parameter after gasBailOut (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).

Comment thread docs/site/docs/interacting-with-erigon/trace.md

@yperbasis yperbasis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.
@bloxster

Copy link
Copy Markdown
Collaborator Author

Both points fixed in 7258cea.

Free service transactions. Verified at txn_executor.go:181-190 — applyMessage calls engine.IsServiceTransaction for a zero-feeCap transaction and marks it free, and the burn credit at 699-710 is guarded by !msg.IsFree(). The bullet now says a non-free London transaction and states the exclusion explicitly.

"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: trace_replayTransaction, trace_filter, trace_get and trace_transaction all take traceConfig after gasBailOut and their parameter lists stopped short of it. All four now document it.

@yperbasis yperbasis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.Call accepts a trailing *TraceConfig after 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_call parameter list still omits the trailing TraceConfig accepted 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_call parameter list still omits the trailing TraceConfig accepted 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.CallMany accepts a trailing *TraceConfig after 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_callMany parameter list still omits the trailing TraceConfig accepted 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_callMany parameter list still omits the trailing TraceConfig accepted 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).

Comment thread docs/site/docs/interacting-with-erigon/trace.md Outdated
Comment thread llms-full.txt Outdated
Comment thread docs/site/static/llms-full.txt Outdated
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.
@bloxster

Copy link
Copy Markdown
Collaborator Author

Fixed in e030aab — trace_call gains parameter 4 and trace_callMany parameter 3.

Rather than patch the two you named, I swept all nine TraceAPI methods against rpc/jsonrpc/trace_api.go:36-47 so this stops arriving a couple at a time. State after this commit:

Method Positional parameters Documented
trace_call call, types, blockNr, traceConfig ✓
trace_callMany calls, blockNr, traceConfig ✓
trace_rawTransaction encodedTx, traceTypes ✓ (takes no TraceConfig)
trace_replayBlockTransactions blockNr, traceTypes, gasBailOut, traceConfig ✓
trace_replayTransaction txHash, traceTypes, gasBailOut, traceConfig ✓
trace_block blockNr, gasBailOut, traceConfig ✓
trace_filter req, gasBailOut, traceConfig ✓ (stream is injected, not a JSON-RPC parameter)
trace_get txHash, txIndicies, gasBailOut, traceConfig ✓
trace_transaction txHash, gasBailOut, traceConfig ✓

trace_rawTransaction is the only method whose signature carries no TraceConfig, so its two-parameter list is correct as it stands.

Both llms-full.txt files regenerated; --check and the site build are green.

… 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.
@bloxster

Copy link
Copy Markdown
Collaborator Author

Note on the six suppressed comments in the 13:12 review: they ask for the trailing TraceConfig on trace_call (parameter 4) and trace_callMany (parameter 3). That was already fixed in e030aab, pushed at 13:13 — the review ran against 7258cea a minute earlier, so those are stale rather than outstanding. No action needed on them.

@bloxster
bloxster added this pull request to the merge queue Aug 28, 2026
Merged via the queue into release/3.6 with commit 257cf57 Aug 28, 2026
29 checks passed
@bloxster
bloxster deleted the docs/v36-rpc branch August 28, 2026 14:24
pull Bot pushed a commit to Dustin4444/erigon that referenced this pull request Sep 1, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants