[r3.6] docs(site): correct the Pruning Modes page for v3.6 - #23593
[r3.6] docs(site): correct the Pruning Modes page for v3.6#23593bloxster wants to merge 4 commits into
Conversation
Verified the page against release/3.6 code: - The receipt cache is off by default in every prune mode only on *fresh* datadirs; an existing datadir keeps its stored setting and Erigon warns when the flag disagrees (node/eth/backend.go:286-292, db/kv/kvcfg/accessors_config.go). Say so. - `--prune.include-receipts` alone does not extend receipts and logs back to genesis on a Historical Blocks node — the cache follows the state-history window unless `--prune.receipts.distance=keep-all` is set (db/kv/prune/storage_mode.go:479-500, execution/stagedsync/stage_execute.go:621-632, db/snapshotsync/snapshotsync.go:347-355). The tip contradicted the Blocks node section, which was already right. - Document that frozen state-history and inverted-index files below the retention cutoff are now retired, new in v3.6 (db/state/retire_history.go). - Minimal mode does retain state history, for the last 100,000 blocks (db/kv/prune/storage_mode.go:54-59, db/config3/config3.go:51-56), which the mode table already said.
- The "New in v3.6" disk-reclaim note implied the download-time skip of expired state-history/inverted-index files is new; v3.5 already blacklisted them at download time (buildBlackListForPruning). What is new in v3.6 is deleting files already on disk. - The v3.5 breaking-change card recommends --prune.distance.blocks=keep-post-merge to be set before upgrading, but the named alias only parses on v3.6+ (v3.5 uses a plain Uint64 flag); documented the numeric sentinel a v3.5 binary accepts.
There was a problem hiding this comment.
Pull request overview
This PR updates Erigon’s Pruning Modes documentation to reflect v3.6 behavior, primarily around receipt-cache defaults/retention, v3.5→v3.6 upgrade guidance, and new snapshot-file disk reclaim behavior.
Changes:
- Document that
--prune.include-receipts(aka--persist.receipts) is off-by-default on fresh datadirs in v3.6, and that existing datadirs keep the persisted setting. - Clarify how receipt/log availability relates to the state-history window vs
--prune.receipts.distance, and improve v3.5 upgrade advice for--prune.distance.blocks. - Add v3.6 note about reclaiming disk by deleting retired snapshot/history files under prune cutoffs, and correct Minimal mode retention wording.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| llms-full.txt | Mirrors the updated pruning-mode narrative for LLM packaging/static consumption. |
| docs/site/static/llms-full.txt | Same content as llms-full.txt, under the docs static site assets. |
| docs/site/docs/fundamentals/pruning-modes.md | Primary user-facing pruning-modes documentation updates for v3.6 behavior. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…ndows The receipt cache follows the general state-history window unless --prune.receipts.distance is set explicitly; only commitment history is retired against its own window by default. The previous wording asserted the same behaviour for both, contradicting the follow-history default documented earlier on the page.
yperbasis
left a comment
yperbasis
left a comment
There was a problem hiding this comment.
Requesting changes for one correctness issue:
The Blocks-node section says --prune.include-receipts --prune.receipts.distance=keep-all provides eth_getLogs back to genesis. In release/3.6, historyRetireCutoffs leaves standalone indexes on the default state-history cutoff, and AggregatorRoTx.Retire applies that cutoff to LogAddrIdx and LogTopicIdx. Filtered eth_getLogs depends on those indexes, so after retirement an address/topic query can silently omit matches older than 262,144 blocks even though RCache is retained.
Please either narrow the docs to what is currently guaranteed, such as full-range eth_getBlockReceipts, or change log-index retirement and add coverage before documenting full-range eth_getLogs.
Also, because this targets release/3.6, please prefix the title with [r3.6].
bloxster
changed the title
keep-all overrides the retire cutoff for RCacheDomain only. LogAddrIdx and LogTopicIdx are standalone inverted indexes, and AggregatorRoTx.Retire applies RetireCutoffs.Default to them, so a filtered eth_getLogs can still miss matches older than the state-history window.
Corrects the Pruning Modes page for v3.6. Every default and sentinel is traced to
db/kv/prune,db/config3, and the two flag-parse paths incmd/utilsandnode/cli.--prune.receipts.distancefollows the state-history window rather than keeping everything. Existing datadirs keep whatever they were created with; there is no supported migration.--persist.receiptsis documented as an alias of the current name,--prune.include-receipts.--prune.receipts.distance=keep-allis scoped to what it actually retains. It overrides the retire cutoff for the receipt-cache domain only.LogAddrIdxandLogTopicIdxare standalone inverted indexes andAggregatorRoTx.Retireapplies the general history cutoff to them, so an address- or topic-filteredeth_getLogscan still miss matches older than the state-history window. Full-range reads areeth_getBlockReceipts; an unfiltered range query is unaffected, because with no address or topic setapplyFiltersV3consults no bitmap and scans the retained cache instead.--prune.distance.blocks=keep-post-mergebefore upgrading, but that alias only parses on v3.6; the numeric equivalent is given.