cip35
titleHeader Pruning for Light Nodes
descriptionMechanism to retain a fixed range of headers instead of whole history
authorHlib Kanunnikov (@Wondertan)
discussions-tohttps://forum.celestia.org/t/cip-header-pruning-for-lns/1958
statusDraft
typeStandards Track
categoryData Availability
created2025-03-21

Abstract

Currently, every data availability (DA) node type synchronizes all historical headers starting from genesis (or other statically configured historical header) until the subjectively initialized head of the chain. We change that by adding a way to sync a fixed-duration window of headers instead of the whole history.

Motivation

Light nodes (LNs) currently store the entire history of ExtendedHeaders, including the ValidatorSet, Commit, and Data Availability Header (DAH). This started as technical debt but has now become a product issue. The goal is to reduce LN storage requirements by retaining only the most recent headers at least the number defined by PruningWindow in CIP-034.

Specification

In order to reference the last stored header, we introduce a notion of Tail header of the chain, complementing Head header. Tail header height is estimated with HeaderPruningWindow, block time and Head height.

  • On the first start of a node, the Tail is retrieved from trusted peers alongside with the Head, performing subjective initialization.
    • Once retrieved, Tail becomes the point of trust for the initializing node where everything beforehand assumed valid (unless syncing from genesis)
    • Head is cross-checked with the Tail and becomes a synchronization target for the node.
    • All the headers from Tail to Head are then retrieved and verified using signature-based forward verification.
  • As the chain progresses, nodes continuously re-estimate Tail and cut off stored headers beyond the new Tail, retaining roughly HeaderPruningWindow amount of headers.

The estimation of Tail is done as follows:

func estimateTail(head Header, blockTime, window time.Duration) (height uint64) {
    headersToRetain := window / blockTime
    tail := head.Height() - headersToRetain
    return tail
}

The window argument is used to define the length of time to retain headers and it can have two values: TrustingPeriod and HeaderPruningWindow. TrustingPeriod is used only during subjective initialization to prevent from long-range attacks. The HeaderPruningWindow on the other hand is used during normal operation to define how many verified headers to retain.

Parameters

ParameterProposed valueDescriptionChangeable via Governance
HeaderPruningWindow337 hoursDefines the length of time to retain headersNo

By default, HeaderPruningWindow (HPW) is equal to SamplingWindow (SW) from CIP-034. It can be modified per LN, but it must be more or equal to the SamplingWindow. As there is currently way to sync history beyond HPW, the HPW less than SW will fail sampling.

Rationale

Initially, we add pruning support only to LNs to ensure reliable header retrieval for historical headers. Otherwise, nodes configured with larger HeaderPruningWindow than in connected full nodes (FN)/bridge nodes (BNs) won’t be able to retrieve needed headers. We can revisit this consideration if header storage overhead ever becomes pressing for FN/BNs.

Backwards Compatibility

The proposed change is backwards compatible with the current implementation on the protocol. However, LN operators enabling pruning will lose the ability to retrieve historical headers beyond the HeaderPruningWindow. Therefore, we will keep pruning opt-in and keep the ability to initialize from genesis or any arbitrary header in the past. This way node operators can benefit from the storage savings if they know from which point they can safely prune. Future protocol upgrade will solve this limitation by introducing an efficient way to retrieve historical headers.

Security Considerations

This changes does not affect security of the protocol and its participants and is strictly an optimization for LN storage, assuming LN’s respect the constraint HeaderPruningWindow >= SamplingWindow.

Copyright and related rights waived via CC0.