--persist.receipts.distance support

[AskAlexSharov]

Summary

#21306 step 5: skip downloading old receipt-cache (RCache) snapshots.

Current behavior:

• --persist.receipts does store --prune.distance.blocks amount of data

PR:
Adds --persist.receipts.distance=<N|keep-all> — keep the receipt cache only for the latest N blocks (or keep-all to keep it all): skip older rcache-history snapshots at download and retire them past the window. Empty or 0 (default) follows the state-history window (not keep-all); requires --persist.receipts.

Refs #21306.

[Copilot]

Pull request overview

Adds a receipts-specific retention window (--persist.receipts.distance) to the existing pruning/retention machinery so Erigon can skip downloading old receipt-cache (RCache) history snapshots and retire them outside the configured window.

Changes:

• Extend prune.Mode with a Receipts BlockAmount, including persistence (DatabaseInfo key), string rendering, CLI parsing, and retention-window change handling.
• Wire new CLI flag --persist.receipts.distance into pruning mode computation and apply it to snapshot download filtering and to retire cutoffs for RCacheDomain.
• Add/extend unit tests covering RCache download blacklisting, minimum-step cutoff calculation, and per-domain retire cutoffs when receipts retention is enabled.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
node/cli/flags.go	Reads --persist.receipts.distance and passes it into prune.FromCli; adds dependency check in urfave path (cobra path still needs parity).
node/cli/default_flags.go	Registers the new flag in the default urfave flag list.
cmd/utils/flags.go	Defines PersistReceiptsDistanceFlag and its help text.
db/kv/tables.go	Adds PruneReceipts database-info key for persisting receipts retention.
db/kv/prune/storage_mode.go	Adds Receipts to prune.Mode and wires parsing/persistence/string rendering/retention-change logic.
db/kv/prune/storage_mode_test.go	Adds tests for receipts defaults, parsing, string rendering, and legacy DB behavior.
db/kv/prune/distance_test.go	Updates FromCli call for new signature.
db/snapshotsync/snapshotsync.go	Adds RCache history download blacklist based on receipts retention; propagates receipts cutoff through minimum-block/step computation.
db/snapshotsync/snapshotsync_test.go	Adds tests for receipts-based blacklist behavior and minimum-step computation with three cutoffs.
execution/stagedsync/stage_execute.go	Makes RCacheDomain retire cutoff follow receipts retention window when set.
execution/stagedsync/stage_execute_prune_test.go	Adds coverage for retire cutoffs when receipts retention is enabled.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

db/snapshotsync/snapshotsync.go:540

• When ReceiptsFollowHistory() is true (no explicit --persist.receipts.distance), rcache segments are currently filtered via isReceiptsSegmentPruned, which uses the Blocks retention policy (blocksRetentionCutoff). This means configurations where Blocks and History differ (e.g. BlocksMode: Blocks=keep-all, History finite) will still download old rcache history segments even though pruning/retirement treats rcache as following the general History window (see historyRetireCutoffs and ReceiptsFollowHistory docs). That defeats the PR goal of skipping old rcache snapshots and creates inconsistent behavior between download-time filtering and runtime retirement.

			// rcache follows the block-data window here only under the
			// follow-history default; a finite --persist.receipts.distance uses
			// its own window (the receipts blacklist), and keep-all keeps it all.
			// Log indexes always follow the block-data window.
			isRcacheRelatedSegment := strings.Contains(p.Name, kv.LogAddrIdx.String()) ||
				strings.Contains(p.Name, kv.LogTopicIdx.String())
			if prune.ReceiptsFollowHistory() {
				isRcacheRelatedSegment = isRcacheRelatedSegment || strings.Contains(p.Name, kv.RCacheDomain.String())
			}

			if isRcacheRelatedSegment && isReceiptsSegmentPruned(ctx, tx, txNumsReader, cc, prune, frozenBlocks, p, stepSize) {
				continue
			}

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 4 comments.