Documentation
¶
Overview ¶
Package retention resolves how far below head a Full node MAY prune cached IPLD state (issue #92, part of the #87 epic).
The Full-node design (see docs/design/) keeps a small hot working set of state + messages + receipts near the head and drops anything older than a finality-driven cutoff. Anything pruned stays CID-verifiably re-fetchable via bitswap/gateway, so pruning is a cache policy, not data loss.
The cutoff comes from:
retentionEpoch = min(EC-finalized, F3-finalized) - safetyFinalities * ChainFinality
where EC-finalized comes from the FRC-0089 calculator (#96), F3-finalized comes from the latest F3 cert, and safetyFinalities is the number of ChainFinality-sized windows of extra safety we keep below finality. A safetyFinalities of 0 means "prune everything below finality"; a value of 2 means "keep an extra 2*900=1800 epochs of history for the archive role" (mainnet). Full nodes default to safetyFinalities=1.
The resolver reports a THRESHOLD, not a schedule: callers decide when to run the actual drop (a periodic tick, an idle sweep, a manual op). The resolver never returns a threshold above finality: below-finality pruning is only ever allowed for the "static-fallback" flavor of EC finality (head - ChainFinality); F3 and FRC-0089 are trusted to move forward safely on a healthy chain.
Index ¶
Constants ¶
const DefaultSafetyFinalities = 1
DefaultSafetyFinalities is the extra safety margin applied to the finality-derived retention epoch. 1 => keep an extra ChainFinality (~900 epochs, ~7.5h at 30s blocks) of history below finality. A Full node can lower this to 0 to prune more aggressively, or raise it for an archive role.
Variables ¶
This section is empty.
Functions ¶
func Depth ¶
func Depth( ctx context.Context, r selector.Resolver, safetyFinalities int, ) (retentionEpoch, safetyMarginEpochs abi.ChainEpoch, err error)
Depth reports how far below head a Full node MAY prune. Returns:
- retentionEpoch: the SHALLOWEST epoch that must be retained. Anything STRICTLY below this epoch is a candidate for pruning.
- safetyMarginEpochs: how many epochs below finality this policy keeps (safetyFinalities * ChainFinality).
When the FRC-0089 calculator has not yet reached threshold AND F3 is unavailable, retentionEpoch falls back to (head - ChainFinality - safetyMargin). This preserves the static-fallback semantics of finalized in chain/selector.
The returned retentionEpoch is always >= 0.
Types ¶
This section is empty.
Source Files