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.

776 lines
30 KiB

  1. # Upgrading Tendermint Core
  2. This guide provides instructions for upgrading to specific versions of Tendermint Core.
  3. ## Unreleased
  4. ### ABCI Changes
  5. * Added `AbciVersion` to `RequestInfo`. Applications should check that the ABCI version they expect is being used in order to avoid unimplemented changes errors.
  6. * The method `SetOption` has been removed from the ABCI.Client interface. This feature was used in the early ABCI implementation's.
  7. * Messages are written to a byte stream using uin64 length delimiters instead of int64.
  8. ### Config Changes
  9. * `fast_sync = "v1"` is no longer supported. Please use `v2` instead.
  10. * All config parameters are now hyphen-case (also known as kebab-case) instead of snake_case. Before restarting the node make sure
  11. you have updated all the variables in your `config.toml` file.
  12. ### CLI Changes
  13. * If you had previously used `tendermint gen_node_key` to generate a new node
  14. key, keep in mind that it no longer saves the output to a file. You can use
  15. `tendermint init` or pipe the output of `tendermint gen_node_key` to
  16. `$TMHOME/config/node_key.json`:
  17. ```
  18. $ tendermint gen_node_key > $TMHOME/config/node_key.json
  19. ```
  20. * CLI commands and flags are all now hyphen-case instead of snake_case.
  21. Make sure to adjust any scripts that calls a cli command with snake_casing
  22. ## v0.34.0
  23. **Upgrading to Tendermint 0.34 requires a blockchain restart.**
  24. This release is not compatible with previous blockchains due to changes to
  25. the encoding format (see "Protocol Buffers," below) and the block header (see "Blockchain Protocol").
  26. Note also that Tendermint 0.34 also requires Go 1.15 or higher.
  27. ### ABCI Changes
  28. * The `ABCIVersion` is now `0.17.0`.
  29. * New ABCI methods (`ListSnapshots`, `LoadSnapshotChunk`, `OfferSnapshot`, and `ApplySnapshotChunk`)
  30. were added to support the new State Sync feature.
  31. Previously, syncing a new node to a preexisting network could take days; but with State Sync,
  32. new nodes are able to join a network in a matter of seconds.
  33. Read [the spec](https://docs.tendermint.com/master/spec/abci/apps.html#state-sync)
  34. if you want to learn more about State Sync, or if you'd like your application to use it.
  35. (If you don't want to support State Sync in your application, you can just implement these new
  36. ABCI methods as no-ops, leaving them empty.)
  37. * `KV.Pair` has been replaced with `abci.EventAttribute`. The `EventAttribute.Index` field
  38. allows ABCI applications to dictate which events should be indexed.
  39. * The blockchain can now start from an arbitrary initial height,
  40. provided to the application via `RequestInitChain.InitialHeight`.
  41. * ABCI evidence type is now an enum with two recognized types of evidence:
  42. `DUPLICATE_VOTE` and `LIGHT_CLIENT_ATTACK`.
  43. Applications should be able to handle these evidence types
  44. (i.e., through slashing or other accountability measures).
  45. * The [`PublicKey` type](https://github.com/tendermint/tendermint/blob/master/proto/tendermint/crypto/keys.proto#L13-L15)
  46. (used in ABCI as part of `ValidatorUpdate`) now uses a `oneof` protobuf type.
  47. Note that since Tendermint only supports ed25519 validator keys, there's only one
  48. option in the `oneof`. For more, see "Protocol Buffers," below.
  49. * The field `Proof`, on the ABCI type `ResponseQuery`, is now named `ProofOps`.
  50. For more, see "Crypto," below.
  51. * The method `SetOption` has been removed from the ABCI.Client interface. This feature was used in the early ABCI implementation's.
  52. ### P2P Protocol
  53. The default codec is now proto3, not amino. The schema files can be found in the `/proto`
  54. directory. For more, see "Protobuf," below.
  55. ### Blockchain Protocol
  56. * `Header#LastResultsHash`, which is the root hash of a Merkle tree built from
  57. `ResponseDeliverTx(Code, Data)` as of v0.34 also includes `GasWanted` and `GasUsed`
  58. fields.
  59. * Merkle hashes of empty trees previously returned nothing, but now return the hash of an empty input,
  60. to conform with [RFC-6962](https://tools.ietf.org/html/rfc6962).
  61. This mainly affects `Header#DataHash`, `Header#LastResultsHash`, and
  62. `Header#EvidenceHash`, which are often empty. Non-empty hashes can also be affected, e.g. if their
  63. inputs depend on other (empty) Merkle hashes, giving different results.
  64. ### Transaction Indexing
  65. Tendermint now relies on the application to tell it which transactions to index. This means that
  66. in the `config.toml`, generated by Tendermint, there is no longer a way to specify which
  67. transactions to index. `tx.height` and `tx.hash` will always be indexed when using the `kv` indexer.
  68. Applications must now choose to either a) enable indexing for all transactions, or
  69. b) allow node operators to decide which transactions to index.
  70. Applications can notify Tendermint to index a specific transaction by setting
  71. `Index: bool` to `true` in the Event Attribute:
  72. ```go
  73. []types.Event{
  74. {
  75. Type: "app",
  76. Attributes: []types.EventAttribute{
  77. {Key: []byte("creator"), Value: []byte("Cosmoshi Netowoko"), Index: true},
  78. },
  79. },
  80. }
  81. ```
  82. ### Protocol Buffers
  83. Tendermint 0.34 replaces Amino with Protocol Buffers for encoding.
  84. This migration is extensive and results in a number of changes, however,
  85. Tendermint only uses the types generated from Protocol Buffers for disk and
  86. wire serialization.
  87. **This means that these changes should not affect you as a Tendermint user.**
  88. However, Tendermint users and contributors may note the following changes:
  89. * Directory layout changes: All proto files have been moved under one directory, `/proto`.
  90. This is in line with the recommended file layout by [Buf](https://buf.build).
  91. For more, see the [Buf documentation](https://buf.build/docs/lint-checkers#file_layout).
  92. * ABCI Changes: As noted in the "ABCI Changes" section above, the `PublicKey` type now uses
  93. a `oneof` type.
  94. For more on the Protobuf changes, please see our [blog post on this migration](https://medium.com/tendermint/tendermint-0-34-protocol-buffers-and-you-8c40558939ae).
  95. ### Consensus Parameters
  96. Tendermint 0.34 includes new and updated consensus parameters.
  97. #### Version Parameters (New)
  98. * `AppVersion`, which is the version of the ABCI application.
  99. #### Evidence Parameters
  100. * `MaxBytes`, which caps the total amount of evidence. The default is 1048576 (1 MB).
  101. ### Crypto
  102. #### Keys
  103. * Keys no longer include a type prefix. For example, ed25519 pubkeys have been renamed from
  104. `PubKeyEd25519` to `PubKey`. This reduces stutter (e.g., `ed25519.PubKey`).
  105. * Keys are now byte slices (`[]byte`) instead of byte arrays (`[<size>]byte`).
  106. * The multisig functionality that was previously in Tendermint now has
  107. a new home within the Cosmos SDK:
  108. [`cosmos/cosmos-sdk/types/multisig`](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/types/multisig/multisignature.go).
  109. #### `merkle` Package
  110. * `SimpleHashFromMap()` and `SimpleProofsFromMap()` were removed.
  111. * The prefix `Simple` has been removed. (For example, `SimpleProof` is now called `Proof`.)
  112. * All protobuf messages have been moved to the `/proto` directory.
  113. * The protobuf message `Proof` that contained multiple ProofOp's has been renamed to `ProofOps`.
  114. As noted above, this affects the ABCI type `ResponseQuery`:
  115. The field that was named Proof is now named `ProofOps`.
  116. * `HashFromByteSlices` and `ProofsFromByteSlices` now return a hash for empty inputs, to conform with
  117. [RFC-6962](https://tools.ietf.org/html/rfc6962).
  118. ### `libs` Package
  119. The `bech32` package has moved to the Cosmos SDK:
  120. [`cosmos/cosmos-sdk/types/bech32`](https://github.com/cosmos/cosmos-sdk/tree/4173ea5ebad906dd9b45325bed69b9c655504867/types/bech32).
  121. ### CLI
  122. The `tendermint lite` command has been renamed to `tendermint light` and has a slightly different API.
  123. See [the docs](https://docs.tendermint.com/master/tendermint-core/light-client-protocol.html#http-proxy) for details.
  124. ### Light Client
  125. We have a new, rewritten light client! You can
  126. [read more](https://medium.com/tendermint/everything-you-need-to-know-about-the-tendermint-light-client-f80d03856f98)
  127. about the justifications and details behind this change.
  128. Other user-relevant changes include:
  129. * The old `lite` package was removed; the new light client uses the `light` package.
  130. * The `Verifier` was broken up into two pieces:
  131. * Core verification logic (pure `VerifyX` functions)
  132. * `Client` object, which represents the complete light client
  133. * The new light clients stores headers & validator sets as `LightBlock`s
  134. * The RPC client can be found in the `/rpc` directory.
  135. * The HTTP(S) proxy is located in the `/proxy` directory.
  136. ### `state` Package
  137. * A new field `State.InitialHeight` has been added to record the initial chain height, which must be `1`
  138. (not `0`) if starting from height `1`. This can be configured via the genesis field `initial_height`.
  139. * The `state` package now has a `Store` interface. All functions in
  140. [state/store.go](https://github.com/tendermint/tendermint/blob/56911ee35298191c95ef1c7d3d5ec508237aaff4/state/store.go#L42-L42)
  141. are now part of the interface. The interface returns errors on all methods and can be used by calling `state.NewStore(dbm.DB)`.
  142. ### `privval` Package
  143. All requests are now accompanied by the chain ID from the network.
  144. This is a optional field and can be ignored by key management systems;
  145. however, if you are using the same key management system for multiple different
  146. blockchains, we recommend that you check the chain ID.
  147. ### RPC
  148. * `/unsafe_start_cpu_profiler`, `/unsafe_stop_cpu_profiler` and
  149. `/unsafe_write_heap_profile` were removed.
  150. For profiling, please use the pprof server, which can
  151. be enabled through `--rpc.pprof_laddr=X` flag or `pprof_laddr=X` config setting
  152. in the rpc section.
  153. * The `Content-Type` header returned on RPC calls is now (correctly) set as `application/json`.
  154. ### Version
  155. Version is now set through Go linker flags `ld_flags`. Applications that are using tendermint as a library should set this at compile time.
  156. Example:
  157. ```sh
  158. go install -mod=readonly -ldflags "-X github.com/tendermint/tendermint/version.TMCoreSemVer=$(go list -m github.com/tendermint/tendermint | sed 's/ /\@/g') -s -w " -trimpath ./cmd
  159. ```
  160. Additionally, the exported constant `version.Version` is now `version.TMCoreSemVer`.
  161. ## v0.33.4
  162. ### Go API
  163. * `rpc/client` HTTP and local clients have been moved into `http` and `local`
  164. subpackages, and their constructors have been renamed to `New()`.
  165. ### Protobuf Changes
  166. When upgrading to version 0.33.4 you will have to fetch the `third_party`
  167. directory along with the updated proto files.
  168. ### Block Retention
  169. ResponseCommit added a field for block retention. The application can provide information to Tendermint on how to prune blocks.
  170. If an application would like to not prune any blocks pass a `0` in this field.
  171. ```proto
  172. message ResponseCommit {
  173. // reserve 1
  174. bytes data = 2; // the Merkle root hash
  175. ++ uint64 retain_height = 3; // the oldest block height to retain ++
  176. }
  177. ```
  178. ## v0.33.0
  179. This release is not compatible with previous blockchains due to commit becoming
  180. signatures only and fields in the header have been removed.
  181. ### Blockchain Protocol
  182. `TotalTxs` and `NumTxs` were removed from the header. `Commit` now consists
  183. mostly of just signatures.
  184. ```go
  185. type Commit struct {
  186. Height int64
  187. Round int
  188. BlockID BlockID
  189. Signatures []CommitSig
  190. }
  191. ```
  192. ```go
  193. type BlockIDFlag byte
  194. const (
  195. // BlockIDFlagAbsent - no vote was received from a validator.
  196. BlockIDFlagAbsent BlockIDFlag = 0x01
  197. // BlockIDFlagCommit - voted for the Commit.BlockID.
  198. BlockIDFlagCommit = 0x02
  199. // BlockIDFlagNil - voted for nil.
  200. BlockIDFlagNil = 0x03
  201. )
  202. type CommitSig struct {
  203. BlockIDFlag BlockIDFlag
  204. ValidatorAddress Address
  205. Timestamp time.Time
  206. Signature []byte
  207. }
  208. ```
  209. See [\#63](https://github.com/tendermint/spec/pull/63) for the complete spec
  210. change.
  211. ### P2P Protocol
  212. The secret connection now includes a transcript hashing. If you want to
  213. implement a handshake (or otherwise have an existing implementation), you'll
  214. need to make the same changes that were made
  215. [here](https://github.com/tendermint/tendermint/pull/3668).
  216. ### Config Changes
  217. You will need to generate a new config if you have used a prior version of tendermint.
  218. Tags have been entirely renamed throughout the codebase to events and there
  219. keys are called
  220. [compositeKeys](https://github.com/tendermint/tendermint/blob/6d05c531f7efef6f0619155cf10ae8557dd7832f/docs/app-dev/indexing-transactions.md).
  221. Evidence Params has been changed to include duration.
  222. * `consensus_params.evidence.max_age_duration`.
  223. * Renamed `consensus_params.evidence.max_age` to `max_age_num_blocks`.
  224. ### Go API
  225. * `libs/common` has been removed in favor of specific pkgs.
  226. * `async`
  227. * `service`
  228. * `rand`
  229. * `net`
  230. * `strings`
  231. * `cmap`
  232. * removal of `errors` pkg
  233. ### RPC Changes
  234. * `/validators` is now paginated (default: 30 vals per page)
  235. * `/block_results` response format updated [see RPC docs for details](https://docs.tendermint.com/master/rpc/#/Info/block_results)
  236. * Event suffix has been removed from the ID in event responses
  237. * IDs are now integers not `json-client-XYZ`
  238. ## v0.32.0
  239. This release is compatible with previous blockchains,
  240. however the new ABCI Events mechanism may create some complexity
  241. for nodes wishing to continue operation with v0.32 from a previous version.
  242. There are some minor breaking changes to the RPC.
  243. ### Config Changes
  244. If you have `db_backend` set to `leveldb` in your config file, please change it
  245. to `goleveldb` or `cleveldb`.
  246. ### RPC Changes
  247. The default listen address for the RPC is now `127.0.0.1`. If you want to expose
  248. it publicly, you have to explicitly configure it. Note exposing the RPC to the
  249. public internet may not be safe - endpoints which return a lot of data may
  250. enable resource exhaustion attacks on your node, causing the process to crash.
  251. Any consumers of `/block_results` need to be mindful of the change in all field
  252. names from CamelCase to Snake case, eg. `results.DeliverTx` is now `results.deliver_tx`.
  253. This is a fix, but it's breaking.
  254. ### ABCI Changes
  255. ABCI responses which previously had a `Tags` field now have an `Events` field
  256. instead. The original `Tags` field was simply a list of key-value pairs, where
  257. each key effectively represented some attribute of an event occuring in the
  258. blockchain, like `sender`, `receiver`, or `amount`. However, it was difficult to
  259. represent the occurence of multiple events (for instance, multiple transfers) in a single list.
  260. The new `Events` field contains a list of `Event`, where each `Event` is itself a list
  261. of key-value pairs, allowing for more natural expression of multiple events in
  262. eg. a single DeliverTx or EndBlock. Note each `Event` also includes a `Type`, which is meant to categorize the
  263. event.
  264. For transaction indexing, the index key is
  265. prefixed with the event type: `{eventType}.{attributeKey}`.
  266. If the same event type and attribute key appear multiple times, the values are
  267. appended in a list.
  268. To make queries, include the event type as a prefix. For instance if you
  269. previously queried for `recipient = 'XYZ'`, and after the upgrade you name your event `transfer`,
  270. the new query would be for `transfer.recipient = 'XYZ'`.
  271. Note that transactions indexed on a node before upgrading to v0.32 will still be indexed
  272. using the old scheme. For instance, if a node upgraded at height 100,
  273. transactions before 100 would be queried with `recipient = 'XYZ'` and
  274. transactions after 100 would be queried with `transfer.recipient = 'XYZ'`.
  275. While this presents additional complexity to clients, it avoids the need to
  276. reindex. Of course, you can reset the node and sync from scratch to re-index
  277. entirely using the new scheme.
  278. We illustrate further with a more complete example.
  279. Prior to the update, suppose your `ResponseDeliverTx` look like:
  280. ```go
  281. abci.ResponseDeliverTx{
  282. Tags: []kv.Pair{
  283. {Key: []byte("sender"), Value: []byte("foo")},
  284. {Key: []byte("recipient"), Value: []byte("bar")},
  285. {Key: []byte("amount"), Value: []byte("35")},
  286. }
  287. }
  288. ```
  289. The following queries would match this transaction:
  290. ```go
  291. query.MustParse("tm.event = 'Tx' AND sender = 'foo'")
  292. query.MustParse("tm.event = 'Tx' AND recipient = 'bar'")
  293. query.MustParse("tm.event = 'Tx' AND sender = 'foo' AND recipient = 'bar'")
  294. ```
  295. Following the upgrade, your `ResponseDeliverTx` would look something like:
  296. the following `Events`:
  297. ```go
  298. abci.ResponseDeliverTx{
  299. Events: []abci.Event{
  300. {
  301. Type: "transfer",
  302. Attributes: kv.Pairs{
  303. {Key: []byte("sender"), Value: []byte("foo")},
  304. {Key: []byte("recipient"), Value: []byte("bar")},
  305. {Key: []byte("amount"), Value: []byte("35")},
  306. },
  307. }
  308. }
  309. ```
  310. Now the following queries would match this transaction:
  311. ```go
  312. query.MustParse("tm.event = 'Tx' AND transfer.sender = 'foo'")
  313. query.MustParse("tm.event = 'Tx' AND transfer.recipient = 'bar'")
  314. query.MustParse("tm.event = 'Tx' AND transfer.sender = 'foo' AND transfer.recipient = 'bar'")
  315. ```
  316. For further documentation on `Events`, see the [docs](https://github.com/tendermint/tendermint/blob/60827f75623b92eff132dc0eff5b49d2025c591e/docs/spec/abci/abci.md#events).
  317. ### Go Applications
  318. The ABCI Application interface changed slightly so the CheckTx and DeliverTx
  319. methods now take Request structs. The contents of these structs are just the raw
  320. tx bytes, which were previously passed in as the argument.
  321. ## v0.31.6
  322. There are no breaking changes in this release except Go API of p2p and
  323. mempool packages. Hovewer, if you're using cleveldb, you'll need to change
  324. the compilation tag:
  325. Use `cleveldb` tag instead of `gcc` to compile Tendermint with CLevelDB or
  326. use `make build_c` / `make install_c` (full instructions can be found at
  327. <https://tendermint.com/docs/introduction/install.html#compile-with-cleveldb-support>)
  328. ## v0.31.0
  329. This release contains a breaking change to the behaviour of the pubsub system.
  330. It also contains some minor breaking changes in the Go API and ABCI.
  331. There are no changes to the block or p2p protocols, so v0.31.0 should work fine
  332. with blockchains created from the v0.30 series.
  333. ### RPC
  334. The pubsub no longer blocks on publishing. This may cause some WebSocket (WS) clients to stop working as expected.
  335. If your WS client is not consuming events fast enough, Tendermint can terminate the subscription.
  336. In this case, the WS client will receive an error with description:
  337. ```json
  338. {
  339. "jsonrpc": "2.0",
  340. "id": "{ID}#event",
  341. "error": {
  342. "code": -32000,
  343. "msg": "Server error",
  344. "data": "subscription was cancelled (reason: client is not pulling messages fast enough)" // or "subscription was cancelled (reason: Tendermint exited)"
  345. }
  346. }
  347. Additionally, there are now limits on the number of subscribers and
  348. subscriptions that can be active at once. See the new
  349. `rpc.max_subscription_clients` and `rpc.max_subscriptions_per_client` values to
  350. configure this.
  351. ```
  352. ### Applications
  353. Simple rename of `ConsensusParams.BlockSize` to `ConsensusParams.Block`.
  354. The `ConsensusParams.Block.TimeIotaMS` field was also removed. It's configured
  355. in the ConsensusParsm in genesis.
  356. ### Go API
  357. See the [CHANGELOG](CHANGELOG.md). These are relatively straight forward.
  358. ## v0.30.0
  359. This release contains a breaking change to both the block and p2p protocols,
  360. however it may be compatible with blockchains created with v0.29.0 depending on
  361. the chain history. If your blockchain has not included any pieces of evidence,
  362. or no piece of evidence has been included in more than one block,
  363. and if your application has never returned multiple updates
  364. for the same validator in a single block, then v0.30.0 will work fine with
  365. blockchains created with v0.29.0.
  366. The p2p protocol change is to fix the proposer selection algorithm again.
  367. Note that proposer selection is purely a p2p concern right
  368. now since the algorithm is only relevant during real time consensus.
  369. This change is thus compatible with v0.29.0, but
  370. all nodes must be upgraded to avoid disagreements on the proposer.
  371. ### Applications
  372. Applications must ensure they do not return duplicates in
  373. `ResponseEndBlock.ValidatorUpdates`. A pubkey must only appear once per set of
  374. updates. Duplicates will cause irrecoverable failure. If you have a very good
  375. reason why we shouldn't do this, please open an issue.
  376. ## v0.29.0
  377. This release contains some breaking changes to the block and p2p protocols,
  378. and will not be compatible with any previous versions of the software, primarily
  379. due to changes in how various data structures are hashed.
  380. Any implementations of Tendermint blockchain verification, including lite clients,
  381. will need to be updated. For specific details:
  382. * [Merkle tree](https://github.com/tendermint/spec/blob/master/spec/blockchain/encoding.md#merkle-trees)
  383. * [ConsensusParams](https://github.com/tendermint/spec/blob/master/spec/blockchain/state.md#consensusparams)
  384. There was also a small change to field ordering in the vote struct. Any
  385. implementations of an out-of-process validator (like a Key-Management Server)
  386. will need to be updated. For specific details:
  387. * [Vote](https://github.com/tendermint/spec/blob/master/spec/consensus/signing.md#votes)
  388. Finally, the proposer selection algorithm continues to evolve. See the
  389. [work-in-progress
  390. specification](https://github.com/tendermint/tendermint/pull/3140).
  391. For everything else, please see the [CHANGELOG](./CHANGELOG.md#v0.29.0).
  392. ## v0.28.0
  393. This release breaks the format for the `priv_validator.json` file
  394. and the protocol used for the external validator process.
  395. It is compatible with v0.27.0 blockchains (neither the BlockProtocol nor the
  396. P2PProtocol have changed).
  397. Please read carefully for details about upgrading.
  398. **Note:** Backup your `config/priv_validator.json`
  399. before proceeding.
  400. ### `priv_validator.json`
  401. The `config/priv_validator.json` is now two files:
  402. `config/priv_validator_key.json` and `data/priv_validator_state.json`.
  403. The former contains the key material, the later contains the details on the last
  404. message signed.
  405. When running v0.28.0 for the first time, it will back up any pre-existing
  406. `priv_validator.json` file and proceed to split it into the two new files.
  407. Upgrading should happen automatically without problem.
  408. To upgrade manually, use the provided `privValUpgrade.go` script, with exact paths for the old
  409. `priv_validator.json` and the locations for the two new files. It's recomended
  410. to use the default paths, of `config/priv_validator_key.json` and
  411. `data/priv_validator_state.json`, respectively:
  412. ```sh
  413. go run scripts/privValUpgrade.go <old-path> <new-key-path> <new-state-path>
  414. ```
  415. ### External validator signers
  416. The Unix and TCP implementations of the remote signing validator
  417. have been consolidated into a single implementation.
  418. Thus in both cases, the external process is expected to dial
  419. Tendermint. This is different from how Unix sockets used to work, where
  420. Tendermint dialed the external process.
  421. The `PubKeyMsg` was also split into separate `Request` and `Response` types
  422. for consistency with other messages.
  423. Note that the TCP sockets don't yet use a persistent key,
  424. so while they're encrypted, they can't yet be properly authenticated.
  425. See [#3105](https://github.com/tendermint/tendermint/issues/3105).
  426. Note the Unix socket has neither encryption nor authentication, but will
  427. add a shared-secret in [#3099](https://github.com/tendermint/tendermint/issues/3099).
  428. ## v0.27.0
  429. This release contains some breaking changes to the block and p2p protocols,
  430. but does not change any core data structures, so it should be compatible with
  431. existing blockchains from the v0.26 series that only used Ed25519 validator keys.
  432. Blockchains using Secp256k1 for validators will not be compatible. This is due
  433. to the fact that we now enforce which key types validators can use as a
  434. consensus param. The default is Ed25519, and Secp256k1 must be activated
  435. explicitly.
  436. It is recommended to upgrade all nodes at once to avoid incompatibilities at the
  437. peer layer - namely, the heartbeat consensus message has been removed (only
  438. relevant if `create_empty_blocks=false` or `create_empty_blocks_interval > 0`),
  439. and the proposer selection algorithm has changed. Since proposer information is
  440. never included in the blockchain, this change only affects the peer layer.
  441. ### Go API Changes
  442. #### libs/db
  443. The ReverseIterator API has changed the meaning of `start` and `end`.
  444. Before, iteration was from `start` to `end`, where
  445. `start > end`. Now, iteration is from `end` to `start`, where `start < end`.
  446. The iterator also excludes `end`. This change allows a simplified and more
  447. intuitive logic, aligning the semantic meaning of `start` and `end` in the
  448. `Iterator` and `ReverseIterator`.
  449. ### Applications
  450. This release enforces a new consensus parameter, the
  451. ValidatorParams.PubKeyTypes. Applications must ensure that they only return
  452. validator updates with the allowed PubKeyTypes. If a validator update includes a
  453. pubkey type that is not included in the ConsensusParams.Validator.PubKeyTypes,
  454. block execution will fail and the consensus will halt.
  455. By default, only Ed25519 pubkeys may be used for validators. Enabling
  456. Secp256k1 requires explicit modification of the ConsensusParams.
  457. Please update your application accordingly (ie. restrict validators to only be
  458. able to use Ed25519 keys, or explicitly add additional key types to the genesis
  459. file).
  460. ## v0.26.0
  461. This release contains a lot of changes to core data types and protocols. It is not
  462. compatible to the old versions and there is no straight forward way to update
  463. old data to be compatible with the new version.
  464. To reset the state do:
  465. ```sh
  466. tendermint unsafe_reset_all
  467. ```
  468. Here we summarize some other notable changes to be mindful of.
  469. ### Config Changes
  470. All timeouts must be changed from integers to strings with their duration, for
  471. instance `flush_throttle_timeout = 100` would be changed to
  472. `flush_throttle_timeout = "100ms"` and `timeout_propose = 3000` would be changed
  473. to `timeout_propose = "3s"`.
  474. ### RPC Changes
  475. The default behaviour of `/abci_query` has been changed to not return a proof,
  476. and the name of the parameter that controls this has been changed from `trusted`
  477. to `prove`. To get proofs with your queries, ensure you set `prove=true`.
  478. Various version fields like `amino_version`, `p2p_version`, `consensus_version`,
  479. and `rpc_version` have been removed from the `node_info.other` and are
  480. consolidated under the tendermint semantic version (ie. `node_info.version`) and
  481. the new `block` and `p2p` protocol versions under `node_info.protocol_version`.
  482. ### ABCI Changes
  483. Field numbers were bumped in the `Header` and `ResponseInfo` messages to make
  484. room for new `version` fields. It should be straight forward to recompile the
  485. protobuf file for these changes.
  486. #### Proofs
  487. The `ResponseQuery.Proof` field is now structured as a `[]ProofOp` to support
  488. generalized Merkle tree constructions where the leaves of one Merkle tree are
  489. the root of another. If you don't need this functionality, and you used to
  490. return `<proof bytes>` here, you should instead return a single `ProofOp` with
  491. just the `Data` field set:
  492. ```go
  493. []ProofOp{
  494. ProofOp{
  495. Data: <proof bytes>,
  496. }
  497. }
  498. ```
  499. For more information, see:
  500. * [ADR-026](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/architecture/adr-026-general-merkle-proof.md)
  501. * [Relevant ABCI
  502. documentation](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/spec/abci/apps.md#query-proofs)
  503. * [Description of
  504. keys](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/crypto/merkle/proof_key_path.go#L14)
  505. ### Go API Changes
  506. #### crypto/merkle
  507. The `merkle.Hasher` interface was removed. Functions which used to take `Hasher`
  508. now simply take `[]byte`. This means that any objects being Merklized should be
  509. serialized before they are passed in.
  510. #### node
  511. The `node.RunForever` function was removed. Signal handling and running forever
  512. should instead be explicitly configured by the caller. See how we do it
  513. [here](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/cmd/tendermint/commands/run_node.go#L60).
  514. ### Other
  515. All hashes, except for public key addresses, are now 32-bytes.
  516. ## v0.25.0
  517. This release has minimal impact.
  518. If you use GasWanted in ABCI and want to enforce it, set the MaxGas in the genesis file (default is no max).
  519. ## v0.24.0
  520. New 0.24.0 release contains a lot of changes to the state and types. It's not
  521. compatible to the old versions and there is no straight forward way to update
  522. old data to be compatible with the new version.
  523. To reset the state do:
  524. ```sh
  525. tendermint unsafe_reset_all
  526. ```
  527. Here we summarize some other notable changes to be mindful of.
  528. ### Config changes
  529. `p2p.max_num_peers` was removed in favor of `p2p.max_num_inbound_peers` and
  530. `p2p.max_num_outbound_peers`.
  531. ```toml
  532. # Maximum number of inbound peers
  533. max_num_inbound_peers = 40
  534. # Maximum number of outbound peers to connect to, excluding persistent peers
  535. max_num_outbound_peers = 10
  536. ```
  537. As you can see, the default ratio of inbound/outbound peers is 4/1. The reason
  538. is we want it to be easier for new nodes to connect to the network. You can
  539. tweak these parameters to alter the network topology.
  540. ### RPC Changes
  541. The result of `/commit` used to contain `header` and `commit` fields at the top level. These are now contained under the `signed_header` field.
  542. ### ABCI Changes
  543. The header has been upgraded and contains new fields, but none of the existing
  544. fields were changed, except their order.
  545. The `Validator` type was split into two, one containing an `Address` and one
  546. containing a `PubKey`. When processing `RequestBeginBlock`, use the `Validator`
  547. type, which contains just the `Address`. When returning `ResponseEndBlock`, use
  548. the `ValidatorUpdate` type, which contains just the `PubKey`.
  549. ### Validator Set Updates
  550. Validator set updates returned in ResponseEndBlock for height `H` used to take
  551. effect immediately at height `H+1`. Now they will be delayed one block, to take
  552. effect at height `H+2`. Note this means that the change will be seen by the ABCI
  553. app in the `RequestBeginBlock.LastCommitInfo` at block `H+3`. Apps were already
  554. required to maintain a map from validator addresses to pubkeys since v0.23 (when
  555. pubkeys were removed from RequestBeginBlock), but now they may need to track
  556. multiple validator sets at once to accomodate this delay.
  557. ### Block Size
  558. The `ConsensusParams.BlockSize.MaxTxs` was removed in favour of
  559. `ConsensusParams.BlockSize.MaxBytes`, which is now enforced. This means blocks
  560. are limitted only by byte-size, not by number of transactions.