diff --git a/docs/architecture/README.MD b/docs/architecture/README.MD index 99d8204b2..6b64c9c99 100644 --- a/docs/architecture/README.MD +++ b/docs/architecture/README.MD @@ -31,3 +31,4 @@ Please add a entry below in your Pull Request for an ADR. - [ADR 010: Modular AnteHandler](./adr-010-modular-antehandler.md) - [ADR 011: Generalize Genesis Accounts](./adr-011-generalize-genesis-accounts.md) - [ADR 012: State Accessors](./adr-012-state-accessors.md) +- [ADR 017: Historical Header Module](./adr-017-historical-header-module.md) diff --git a/docs/architecture/adr-017-historical-header-module.md b/docs/architecture/adr-017-historical-header-module.md new file mode 100644 index 000000000..0077ebb72 --- /dev/null +++ b/docs/architecture/adr-017-historical-header-module.md @@ -0,0 +1,61 @@ +# ADR 17: Historical Header Module + +## Changelog + +- 26 November 2019: Start of first version +- 2 December 2019: Final draft of first version + +## Context + +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. + +## Decision + +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. + +The application MUST store this information by storing new headers immediately when handling `abci.RequestBeginBlock`: + +```golang +func BeginBlock(ctx sdk.Context, keeper HistoricalHeaderKeeper, req abci.RequestBeginBlock) abci.ResponseBeginBlock { + info := HistoricalInfo{ + Header: ctx.BlockHeader(), + ValSet: keeper.StakingKeeper.GetAllValidators(ctx), // note that this must be stored in a canonical order + } + keeper.SetHistoricalInfo(ctx, ctx.BlockHeight(), info) + n := keeper.GetParamRecentHeadersToStore() + keeper.PruneHistoricalInfo(ctx, ctx.BlockHeight() - n) + // continue handling request +} +``` + +Alternatively, the application MAY store only the hash of the validator set. + +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`). + +`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. + +## Status + +Proposed. + +## Consequences + +Implementation of this ADR will require changes to the Cosmos SDK. It will not require changes to Tendermint. + +### Positive + +- Easy retrieval of headers & state roots for recent past heights by modules anywhere in the SDK. +- No RPC calls to Tendermint required. +- No ABCI alterations required. + +### Negative + +- 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. + +### Neutral + +(none known) + +## References + +- [ICS 2: "Consensus state introspection"](https://github.com/cosmos/ics/tree/master/spec/ics-024-host-requirements#consensus-state-introspection) diff --git a/docs/architecture/adt-template.md b/docs/architecture/adr-template.md similarity index 100% rename from docs/architecture/adt-template.md rename to docs/architecture/adr-template.md