You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

82 lines
3.5 KiB

  1. # ADR 078: Non-Zero Genesis
  2. ## Changelog
  3. - 2020-07-26: Initial draft (@erikgrinaker)
  4. - 2020-07-28: Use weak chain linking, i.e. `predecessor` field (@erikgrinaker)
  5. - 2020-07-31: Drop chain linking (@erikgrinaker)
  6. - 2020-08-03: Add `State.InitialHeight` (@erikgrinaker)
  7. - 2021-02-11: Migrate to tendermint repo (Originally [RFC 002](https://github.com/tendermint/spec/pull/119))
  8. ## Author(s)
  9. - Erik Grinaker (@erikgrinaker)
  10. ## Context
  11. The recommended upgrade path for block protocol-breaking upgrades is currently to hard fork the
  12. chain (see e.g. [`cosmoshub-3` upgrade](https://blog.cosmos.network/cosmos-hub-3-upgrade-announcement-39c9da941aee).
  13. This is done by halting all validators at a predetermined height, exporting the application
  14. state via application-specific tooling, and creating an entirely new chain using the exported
  15. application state.
  16. As far as Tendermint is concerned, the upgraded chain is a completely separate chain, with e.g.
  17. a new chain ID and genesis file. Notably, the new chain starts at height 1, and has none of the
  18. old chain's block history. This causes problems for integrators, e.g. coin exchanges and
  19. wallets, that assume a monotonically increasing height for a given blockchain. Users also find
  20. it confusing that a given height can now refer to distinct states depending on the chain
  21. version.
  22. An ideal solution would be to always retain block backwards compatibility in such a way that chain
  23. history is never lost on upgrades. However, this may require a significant amount of engineering
  24. work that is not viable for the planned Stargate release (Tendermint 0.34), and may prove too
  25. restrictive for future development.
  26. As a first step, allowing the new chain to start from an initial height specified in the genesis
  27. file would at least provide monotonically increasing heights. There was a proposal to include the
  28. last block header of the previous chain as well, but since the genesis file is not verified and
  29. hashed (only specific fields are) this would not be trustworthy.
  30. External tooling will be required to map historical heights onto e.g. archive nodes that contain
  31. blocks from previous chain version. Tendermint will not include any such functionality.
  32. ## Proposal
  33. Tendermint will allow chains to start from an arbitrary initial height:
  34. - A new field `initial_height` is added to the genesis file, defaulting to `1`. It can be set to any
  35. non-negative integer, and `0` is considered equivalent to `1`.
  36. - A new field `InitialHeight` is added to the ABCI `RequestInitChain` message, with the same value
  37. and semantics as the genesis field.
  38. - A new field `InitialHeight` is added to the `state.State` struct, where `0` is considered invalid.
  39. Including the field here simplifies implementation, since the genesis value does not have to be
  40. propagated throughout the code base separately, but it is not strictly necessary.
  41. ABCI applications may have to be updated to handle arbitrary initial heights, otherwise the initial
  42. block may fail.
  43. ## Status
  44. Accepted
  45. ## Consequences
  46. ### Positive
  47. - Heights can be unique throughout the history of a "logical" chain, across hard fork upgrades.
  48. ### Negative
  49. - Upgrades still cause loss of block history.
  50. - Integrators will have to map height ranges to specific archive nodes/networks to query history.
  51. ### Neutral
  52. - There is no explicit link to the last block of the previous chain.
  53. ## References
  54. - [#2543: Allow genesis file to start from non-zero height w/ prev block header](https://github.com/tendermint/tendermint/issues/2543)