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.

242 lines
9.2 KiB

  1. # Upgrading Tendermint Core
  2. This guide provides steps to be followed when you upgrade your applications to
  3. a newer version of Tendermint Core.
  4. ## v0.28.0
  5. This release breaks the format for the `priv_validator.json` file
  6. and the protocol used for the external validator process.
  7. It is compatible with v0.27.0 blockchains (neither the BlockProtocol nor the
  8. P2PProtocol have changed).
  9. Please read carefully for details about upgrading.
  10. **Note:** Backup your `config/priv_validator.json`
  11. before proceeding.
  12. ### `priv_validator.json`
  13. The `config/priv_validator.json` is now two files:
  14. `config/priv_validator_key.json` and `data/priv_validator_state.json`.
  15. The former contains the key material, the later contains the details on the last
  16. message signed.
  17. When running v0.28.0 for the first time, it will back up any pre-existing
  18. `priv_validator.json` file and proceed to split it into the two new files.
  19. Upgrading should happen automatically without problem.
  20. To upgrade manually, use the provided `privValUpgrade.go` script, with exact paths for the old
  21. `priv_validator.json` and the locations for the two new files. It's recomended
  22. to use the default paths, of `config/priv_validator_key.json` and
  23. `data/priv_validator_state.json`, respectively:
  24. ```
  25. go run scripts/privValUpgrade.go <old-path> <new-key-path> <new-state-path>
  26. ```
  27. ### External validator signers
  28. The Unix and TCP implementations of the remote signing validator
  29. have been consolidated into a single implementation.
  30. Thus in both cases, the external process is expected to dial
  31. Tendermint. This is different from how Unix sockets used to work, where
  32. Tendermint dialed the external process.
  33. The `PubKeyMsg` was also split into separate `Request` and `Response` types
  34. for consistency with other messages.
  35. Note that the TCP sockets don't yet use a persistent key,
  36. so while they're encrypted, they can't yet be properly authenticated.
  37. See [#3105](https://github.com/tendermint/tendermint/issues/3105).
  38. Note the Unix socket has neither encryption nor authentication, but will
  39. add a shared-secret in [#3099](https://github.com/tendermint/tendermint/issues/3099).
  40. ## v0.27.0
  41. This release contains some breaking changes to the block and p2p protocols,
  42. but does not change any core data structures, so it should be compatible with
  43. existing blockchains from the v0.26 series that only used Ed25519 validator keys.
  44. Blockchains using Secp256k1 for validators will not be compatible. This is due
  45. to the fact that we now enforce which key types validators can use as a
  46. consensus param. The default is Ed25519, and Secp256k1 must be activated
  47. explicitly.
  48. It is recommended to upgrade all nodes at once to avoid incompatibilities at the
  49. peer layer - namely, the heartbeat consensus message has been removed (only
  50. relevant if `create_empty_blocks=false` or `create_empty_blocks_interval > 0`),
  51. and the proposer selection algorithm has changed. Since proposer information is
  52. never included in the blockchain, this change only affects the peer layer.
  53. ### Go API Changes
  54. #### libs/db
  55. The ReverseIterator API has changed the meaning of `start` and `end`.
  56. Before, iteration was from `start` to `end`, where
  57. `start > end`. Now, iteration is from `end` to `start`, where `start < end`.
  58. The iterator also excludes `end`. This change allows a simplified and more
  59. intuitive logic, aligning the semantic meaning of `start` and `end` in the
  60. `Iterator` and `ReverseIterator`.
  61. ### Applications
  62. This release enforces a new consensus parameter, the
  63. ValidatorParams.PubKeyTypes. Applications must ensure that they only return
  64. validator updates with the allowed PubKeyTypes. If a validator update includes a
  65. pubkey type that is not included in the ConsensusParams.Validator.PubKeyTypes,
  66. block execution will fail and the consensus will halt.
  67. By default, only Ed25519 pubkeys may be used for validators. Enabling
  68. Secp256k1 requires explicit modification of the ConsensusParams.
  69. Please update your application accordingly (ie. restrict validators to only be
  70. able to use Ed25519 keys, or explicitly add additional key types to the genesis
  71. file).
  72. ## v0.26.0
  73. This release contains a lot of changes to core data types and protocols. It is not
  74. compatible to the old versions and there is no straight forward way to update
  75. old data to be compatible with the new version.
  76. To reset the state do:
  77. ```
  78. $ tendermint unsafe_reset_all
  79. ```
  80. Here we summarize some other notable changes to be mindful of.
  81. ### Config Changes
  82. All timeouts must be changed from integers to strings with their duration, for
  83. instance `flush_throttle_timeout = 100` would be changed to
  84. `flush_throttle_timeout = "100ms"` and `timeout_propose = 3000` would be changed
  85. to `timeout_propose = "3s"`.
  86. ### RPC Changes
  87. The default behaviour of `/abci_query` has been changed to not return a proof,
  88. and the name of the parameter that controls this has been changed from `trusted`
  89. to `prove`. To get proofs with your queries, ensure you set `prove=true`.
  90. Various version fields like `amino_version`, `p2p_version`, `consensus_version`,
  91. and `rpc_version` have been removed from the `node_info.other` and are
  92. consolidated under the tendermint semantic version (ie. `node_info.version`) and
  93. the new `block` and `p2p` protocol versions under `node_info.protocol_version`.
  94. ### ABCI Changes
  95. Field numbers were bumped in the `Header` and `ResponseInfo` messages to make
  96. room for new `version` fields. It should be straight forward to recompile the
  97. protobuf file for these changes.
  98. #### Proofs
  99. The `ResponseQuery.Proof` field is now structured as a `[]ProofOp` to support
  100. generalized Merkle tree constructions where the leaves of one Merkle tree are
  101. the root of another. If you don't need this functionality, and you used to
  102. return `<proof bytes>` here, you should instead return a single `ProofOp` with
  103. just the `Data` field set:
  104. ```
  105. []ProofOp{
  106. ProofOp{
  107. Data: <proof bytes>,
  108. }
  109. }
  110. ```
  111. For more information, see:
  112. - [ADR-026](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/architecture/adr-026-general-merkle-proof.md)
  113. - [Relevant ABCI
  114. documentation](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/spec/abci/apps.md#query-proofs)
  115. - [Description of
  116. keys](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/crypto/merkle/proof_key_path.go#L14)
  117. ### Go API Changes
  118. #### crypto/merkle
  119. The `merkle.Hasher` interface was removed. Functions which used to take `Hasher`
  120. now simply take `[]byte`. This means that any objects being Merklized should be
  121. serialized before they are passed in.
  122. #### node
  123. The `node.RunForever` function was removed. Signal handling and running forever
  124. should instead be explicitly configured by the caller. See how we do it
  125. [here](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/cmd/tendermint/commands/run_node.go#L60).
  126. ### Other
  127. All hashes, except for public key addresses, are now 32-bytes.
  128. ## v0.25.0
  129. This release has minimal impact.
  130. If you use GasWanted in ABCI and want to enforce it, set the MaxGas in the genesis file (default is no max).
  131. ## v0.24.0
  132. New 0.24.0 release contains a lot of changes to the state and types. It's not
  133. compatible to the old versions and there is no straight forward way to update
  134. old data to be compatible with the new version.
  135. To reset the state do:
  136. ```
  137. $ tendermint unsafe_reset_all
  138. ```
  139. Here we summarize some other notable changes to be mindful of.
  140. ### Config changes
  141. `p2p.max_num_peers` was removed in favor of `p2p.max_num_inbound_peers` and
  142. `p2p.max_num_outbound_peers`.
  143. ```
  144. # Maximum number of inbound peers
  145. max_num_inbound_peers = 40
  146. # Maximum number of outbound peers to connect to, excluding persistent peers
  147. max_num_outbound_peers = 10
  148. ```
  149. As you can see, the default ratio of inbound/outbound peers is 4/1. The reason
  150. is we want it to be easier for new nodes to connect to the network. You can
  151. tweak these parameters to alter the network topology.
  152. ### RPC Changes
  153. The result of `/commit` used to contain `header` and `commit` fields at the top level. These are now contained under the `signed_header` field.
  154. ### ABCI Changes
  155. The header has been upgraded and contains new fields, but none of the existing
  156. fields were changed, except their order.
  157. The `Validator` type was split into two, one containing an `Address` and one
  158. containing a `PubKey`. When processing `RequestBeginBlock`, use the `Validator`
  159. type, which contains just the `Address`. When returning `ResponseEndBlock`, use
  160. the `ValidatorUpdate` type, which contains just the `PubKey`.
  161. ### Validator Set Updates
  162. Validator set updates returned in ResponseEndBlock for height `H` used to take
  163. effect immediately at height `H+1`. Now they will be delayed one block, to take
  164. effect at height `H+2`. Note this means that the change will be seen by the ABCI
  165. app in the `RequestBeginBlock.LastCommitInfo` at block `H+3`. Apps were already
  166. required to maintain a map from validator addresses to pubkeys since v0.23 (when
  167. pubkeys were removed from RequestBeginBlock), but now they may need to track
  168. multiple validator sets at once to accomodate this delay.
  169. ### Block Size
  170. The `ConsensusParams.BlockSize.MaxTxs` was removed in favour of
  171. `ConsensusParams.BlockSize.MaxBytes`, which is now enforced. This means blocks
  172. are limitted only by byte-size, not by number of transactions.