github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/docs/architecture/adr-017-historical-header-module.md (about)

     1  # ADR 17: Historical Header Module
     2  
     3  ## Changelog
     4  
     5  - 26 November 2019: Start of first version
     6  - 2 December 2019: Final draft of first version
     7  
     8  ## Context
     9  
    10  In order for the Cosmos SDK to implement the [IBC specification](https://github.com/cosmos/ics), modules within the SDK must have the ability to introspect recent consensus states (validator sets & commitment roots) as proofs of these values on other chains must be checked during the handshakes.
    11  
    12  ## Decision
    13  
    14  The application MUST store the most recent `n` headers in a persistent store. At first, this store MAY be the current Merklised store. A non-Merklised store MAY be used later as no proofs are necessary.
    15  
    16  The application MUST store this information by storing new headers immediately when handling `abci.RequestBeginBlock`:
    17  
    18  ```golang
    19  func BeginBlock(ctx sdk.Context, keeper HistoricalHeaderKeeper, req abci.RequestBeginBlock) abci.ResponseBeginBlock {
    20    info := HistoricalInfo{
    21      Header: ctx.BlockHeader(),
    22      ValSet: keeper.StakingKeeper.GetAllValidators(ctx), // note that this must be stored in a canonical order
    23    }
    24    keeper.SetHistoricalInfo(ctx, ctx.BlockHeight(), info)
    25    n := keeper.GetParamRecentHeadersToStore()
    26    keeper.PruneHistoricalInfo(ctx, ctx.BlockHeight() - n)
    27    // continue handling request
    28  }
    29  ```
    30  
    31  Alternatively, the application MAY store only the hash of the validator set.
    32  
    33  The application MUST make these past `n` committed headers available for querying by SDK modules through the `Keeper`'s `GetHistoricalInfo` function. This MAY be implemented in a new module, or it MAY also be integrated into an existing one (likely `x/staking` or `x/ibc`).
    34  
    35  `n` MAY be configured as a parameter store parameter, in which case it could be changed by `ParameterChangeProposal`s, although it will take some blocks for the stored information to catch up if `n` is increased.
    36  
    37  ## Status
    38  
    39  Proposed.
    40  
    41  ## Consequences
    42  
    43  Implementation of this ADR will require changes to the Cosmos SDK. It will not require changes to Tendermint.
    44  
    45  ### Positive
    46  
    47  - Easy retrieval of headers & state roots for recent past heights by modules anywhere in the SDK.
    48  - No RPC calls to Tendermint required.
    49  - No ABCI alterations required.
    50  
    51  ### Negative
    52  
    53  - Duplicates `n` headers data in Tendermint & the application (additional disk usage) - in the long term, an approach such as [this](https://github.com/tendermint/tendermint/issues/4210) might be preferable.
    54  
    55  ### Neutral
    56  
    57  (none known)
    58  
    59  ## References
    60  
    61  - [ICS 2: "Consensus state introspection"](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements#consensus-state-introspection)