Motivation
Users running with --prune.include-commitment-history currently must download the full commitment history (commitment.*.kv + inverted-index files), which is the largest single state domain on disk. Several users have asked for a way to bound commitment-history disk usage by block distance without giving up eth_getProof for recent blocks.
This issue covers only the download-side half of that feature: skipping commitment-history snapshot files older than a configurable retention boundary at sync time. Local pruning of already-downloaded commitment-history files is tracked separately (see companion issue).
Why split it off
Download filtering is already implemented for other state domains in db/snapshotsync/snapshotsync.go — the same boundary-aware filter (keep segments overlapping the cutoff, skip segments fully older) can be reused for commitment history with minimal risk.
Pruning the already-downloaded files on disk is much harder because commitment-history .kv files are mmaped, frozen, and referenced by the state aggregator's reader lifecycle — see the companion issue for details. Shipping the download filter alone gives users the headline disk-saving benefit (fresh syncs only need recent commitment history) without taking on the aggregator lifecycle complexity.
Proposed scope
- A new flag (e.g.
--prune.commitment-history.distance.blocks=N) that is only valid together with --prune.include-commitment-history.
- Startup validation:
N <= --prune.distance (commitment history beyond the regular state-history retention is meaningless because eth_getProof falls back to state history).
- Pre-compute the minimum commitment step from
N and the current chain head once before the snapshot-download loop, then skip commitment-history segments whose end step is below that boundary.
- Persist the configured value in
kv.DatabaseInfo (e.g. CommitmentLayoutBlocksKey) and reject startup-time expansions that would require re-downloading filtered files. Legacy datadirs without the key should be tolerated.
Out of scope: removing commitment-history files that are already on disk. That requires the state-aggregator reader-cleanup path and is tracked separately.
Prior art
PR #21021 attempted to ship download-filtering + local pruning + persistence together. The download-filter portion is the cleanest part of that change and is a reasonable starting point if someone wants to revive just that half.
References
Motivation
Users running with
--prune.include-commitment-historycurrently must download the full commitment history (commitment.*.kv+ inverted-index files), which is the largest single state domain on disk. Several users have asked for a way to bound commitment-history disk usage by block distance without giving upeth_getProoffor recent blocks.This issue covers only the download-side half of that feature: skipping commitment-history snapshot files older than a configurable retention boundary at sync time. Local pruning of already-downloaded commitment-history files is tracked separately (see companion issue).
Why split it off
Download filtering is already implemented for other state domains in
db/snapshotsync/snapshotsync.go— the same boundary-aware filter (keep segments overlapping the cutoff, skip segments fully older) can be reused for commitment history with minimal risk.Pruning the already-downloaded files on disk is much harder because commitment-history
.kvfiles are mmaped, frozen, and referenced by the state aggregator's reader lifecycle — see the companion issue for details. Shipping the download filter alone gives users the headline disk-saving benefit (fresh syncs only need recent commitment history) without taking on the aggregator lifecycle complexity.Proposed scope
--prune.commitment-history.distance.blocks=N) that is only valid together with--prune.include-commitment-history.N <= --prune.distance(commitment history beyond the regular state-history retention is meaningless becauseeth_getProoffalls back to state history).Nand the current chain head once before the snapshot-download loop, then skip commitment-history segments whose end step is below that boundary.kv.DatabaseInfo(e.g.CommitmentLayoutBlocksKey) and reject startup-time expansions that would require re-downloading filtered files. Legacy datadirs without the key should be tolerated.Out of scope: removing commitment-history files that are already on disk. That requires the state-aggregator reader-cleanup path and is tracked separately.
Prior art
PR #21021 attempted to ship download-filtering + local pruning + persistence together. The download-filter portion is the cleanest part of that change and is a reasonable starting point if someone wants to revive just that half.
References
db/snapshotsync/snapshotsync.go— existing per-domain download filtering for comparison