github.com/fiagdao/tendermint@v0.32.11-0.20220824195748-2087fcc480c1/UPGRADING.md (about) 1 # Upgrading Tendermint Core 2 3 This guide provides steps to be followed when you upgrade your applications to 4 a newer version of Tendermint Core. 5 6 ## Unreleased 7 8 <Overview> 9 10 11 ## v0.33.4 12 13 ### Go API 14 15 - `rpc/client` HTTP and local clients have been moved into `http` and `local` subpackages, and their constructors have been renamed to `New()`. 16 17 ### Protobuf Changes 18 19 When upgrading to version 0.33.4 you will have to fetch the `third_party` directory along with the updated proto files. 20 21 ## v0.33.1 22 23 This release is compatible with the previous version. The only change that is required is if you are fetching the protobuf files for application use. 24 25 ### Protobuf Changes 26 27 When upgrading to version 0.33.1 you will have to fetch the `third_party` directory along with the updated proto files. 28 29 30 ## v0.33.0 31 32 This release is not compatible with previous blockchains due to commit becoming signatures only and fields in the header have been removed. 33 34 ### Config Changes 35 36 You will need to generate a new config if you have used a prior version of tendermint. 37 38 - Tags have been entirely renamed throughout the codebase to events and there keys are called [compositeKeys](https://github.com/tendermint/tendermint/blob/6d05c531f7efef6f0619155cf10ae8557dd7832f/docs/app-dev/indexing-transactions.md). 39 - Evidence Params has been changed to include duration. 40 - `consensus_params.evidence.max_age_duration`. 41 - Renamed `consensus_params.evidence.max_age` to `max_age_num_blocks`. 42 43 ### Go API 44 45 - `libs/common` has been removed in favor of specific pkgs. 46 - `async` 47 - `service` 48 - `rand` 49 - `net` 50 - `strings` 51 - `cmap` 52 - removal of `errors` pkg 53 54 ### RPC Changes 55 56 - `/validators` is now paginated (default: 30 vals per page) 57 - `/block_results` response format updated [see RPC docs for details](https://docs.tendermint.com/master/rpc/#/Info/block_results) 58 - Event suffix has been removed from the ID in event responses 59 - IDs are now integers not `json-client-XYZ` 60 61 ## v0.32.0 62 63 This release is compatible with previous blockchains, 64 however the new ABCI Events mechanism may create some complexity 65 for nodes wishing to continue operation with v0.32 from a previous version. 66 There are some minor breaking changes to the RPC. 67 68 ### Config Changes 69 70 If you have `db_backend` set to `leveldb` in your config file, please change it 71 to `goleveldb` or `cleveldb`. 72 73 ### RPC Changes 74 75 The default listen address for the RPC is now `127.0.0.1`. If you want to expose 76 it publicly, you have to explicitly configure it. Note exposing the RPC to the 77 public internet may not be safe - endpoints which return a lot of data may 78 enable resource exhaustion attacks on your node, causing the process to crash. 79 80 Any consumers of `/block_results` need to be mindful of the change in all field 81 names from CamelCase to Snake case, eg. `results.DeliverTx` is now `results.deliver_tx`. 82 This is a fix, but it's breaking. 83 84 ### ABCI Changes 85 86 ABCI responses which previously had a `Tags` field now have an `Events` field 87 instead. The original `Tags` field was simply a list of key-value pairs, where 88 each key effectively represented some attribute of an event occuring in the 89 blockchain, like `sender`, `receiver`, or `amount`. However, it was difficult to 90 represent the occurence of multiple events (for instance, multiple transfers) in a single list. 91 The new `Events` field contains a list of `Event`, where each `Event` is itself a list 92 of key-value pairs, allowing for more natural expression of multiple events in 93 eg. a single DeliverTx or EndBlock. Note each `Event` also includes a `Type`, which is meant to categorize the 94 event. 95 96 For transaction indexing, the index key is 97 prefixed with the event type: `{eventType}.{attributeKey}`. 98 If the same event type and attribute key appear multiple times, the values are 99 appended in a list. 100 101 To make queries, include the event type as a prefix. For instance if you 102 previously queried for `recipient = 'XYZ'`, and after the upgrade you name your event `transfer`, 103 the new query would be for `transfer.recipient = 'XYZ'`. 104 105 Note that transactions indexed on a node before upgrading to v0.32 will still be indexed 106 using the old scheme. For instance, if a node upgraded at height 100, 107 transactions before 100 would be queried with `recipient = 'XYZ'` and 108 transactions after 100 would be queried with `transfer.recipient = 'XYZ'`. 109 While this presents additional complexity to clients, it avoids the need to 110 reindex. Of course, you can reset the node and sync from scratch to re-index 111 entirely using the new scheme. 112 113 We illustrate further with a more complete example. 114 115 Prior to the update, suppose your `ResponseDeliverTx` look like: 116 117 ```go 118 abci.ResponseDeliverTx{ 119 Tags: []kv.Pair{ 120 {Key: []byte("sender"), Value: []byte("foo")}, 121 {Key: []byte("recipient"), Value: []byte("bar")}, 122 {Key: []byte("amount"), Value: []byte("35")}, 123 } 124 } 125 ``` 126 127 The following queries would match this transaction: 128 129 ```go 130 query.MustParse("tm.event = 'Tx' AND sender = 'foo'") 131 query.MustParse("tm.event = 'Tx' AND recipient = 'bar'") 132 query.MustParse("tm.event = 'Tx' AND sender = 'foo' AND recipient = 'bar'") 133 ``` 134 135 Following the upgrade, your `ResponseDeliverTx` would look something like: 136 the following `Events`: 137 138 ```go 139 abci.ResponseDeliverTx{ 140 Events: []abci.Event{ 141 { 142 Type: "transfer", 143 Attributes: kv.Pairs{ 144 {Key: []byte("sender"), Value: []byte("foo")}, 145 {Key: []byte("recipient"), Value: []byte("bar")}, 146 {Key: []byte("amount"), Value: []byte("35")}, 147 }, 148 } 149 } 150 ``` 151 152 Now the following queries would match this transaction: 153 154 ```go 155 query.MustParse("tm.event = 'Tx' AND transfer.sender = 'foo'") 156 query.MustParse("tm.event = 'Tx' AND transfer.recipient = 'bar'") 157 query.MustParse("tm.event = 'Tx' AND transfer.sender = 'foo' AND transfer.recipient = 'bar'") 158 ``` 159 160 For further documentation on `Events`, see the [docs](https://github.com/tendermint/tendermint/blob/60827f75623b92eff132dc0eff5b49d2025c591e/docs/spec/abci/abci.md#events). 161 162 ### Go Applications 163 164 The ABCI Application interface changed slightly so the CheckTx and DeliverTx 165 methods now take Request structs. The contents of these structs are just the raw 166 tx bytes, which were previously passed in as the argument. 167 168 ## v0.31.6 169 170 There are no breaking changes in this release except Go API of p2p and 171 mempool packages. Hovewer, if you're using cleveldb, you'll need to change 172 the compilation tag: 173 174 Use `cleveldb` tag instead of `gcc` to compile Tendermint with CLevelDB or 175 use `make build_c` / `make install_c` (full instructions can be found at 176 https://tendermint.com/docs/introduction/install.html#compile-with-cleveldb-support) 177 178 ## v0.31.0 179 180 This release contains a breaking change to the behaviour of the pubsub system. 181 It also contains some minor breaking changes in the Go API and ABCI. 182 There are no changes to the block or p2p protocols, so v0.31.0 should work fine 183 with blockchains created from the v0.30 series. 184 185 ### RPC 186 187 The pubsub no longer blocks on publishing. This may cause some WebSocket (WS) clients to stop working as expected. 188 If your WS client is not consuming events fast enough, Tendermint can terminate the subscription. 189 In this case, the WS client will receive an error with description: 190 191 ```json 192 { 193 "jsonrpc": "2.0", 194 "id": "{ID}#event", 195 "error": { 196 "code": -32000, 197 "msg": "Server error", 198 "data": "subscription was cancelled (reason: client is not pulling messages fast enough)" // or "subscription was cancelled (reason: Tendermint exited)" 199 } 200 } 201 202 Additionally, there are now limits on the number of subscribers and 203 subscriptions that can be active at once. See the new 204 `rpc.max_subscription_clients` and `rpc.max_subscriptions_per_client` values to 205 configure this. 206 ``` 207 208 ### Applications 209 210 Simple rename of `ConsensusParams.BlockSize` to `ConsensusParams.Block`. 211 212 The `ConsensusParams.Block.TimeIotaMS` field was also removed. It's configured 213 in the ConsensusParsm in genesis. 214 215 ### Go API 216 217 See the [CHANGELOG](CHANGELOG.md). These are relatively straight forward. 218 219 ## v0.30.0 220 221 This release contains a breaking change to both the block and p2p protocols, 222 however it may be compatible with blockchains created with v0.29.0 depending on 223 the chain history. If your blockchain has not included any pieces of evidence, 224 or no piece of evidence has been included in more than one block, 225 and if your application has never returned multiple updates 226 for the same validator in a single block, then v0.30.0 will work fine with 227 blockchains created with v0.29.0. 228 229 The p2p protocol change is to fix the proposer selection algorithm again. 230 Note that proposer selection is purely a p2p concern right 231 now since the algorithm is only relevant during real time consensus. 232 This change is thus compatible with v0.29.0, but 233 all nodes must be upgraded to avoid disagreements on the proposer. 234 235 ### Applications 236 237 Applications must ensure they do not return duplicates in 238 `ResponseEndBlock.ValidatorUpdates`. A pubkey must only appear once per set of 239 updates. Duplicates will cause irrecoverable failure. If you have a very good 240 reason why we shouldn't do this, please open an issue. 241 242 ## v0.29.0 243 244 This release contains some breaking changes to the block and p2p protocols, 245 and will not be compatible with any previous versions of the software, primarily 246 due to changes in how various data structures are hashed. 247 248 Any implementations of Tendermint blockchain verification, including lite clients, 249 will need to be updated. For specific details: 250 251 - [Merkle tree](https://github.com/tendermint/spec/blob/master/spec/blockchain/encoding.md#merkle-trees) 252 - [ConsensusParams](https://github.com/tendermint/spec/blob/master/spec/blockchain/state.md#consensusparams) 253 254 There was also a small change to field ordering in the vote struct. Any 255 implementations of an out-of-process validator (like a Key-Management Server) 256 will need to be updated. For specific details: 257 258 - [Vote](https://github.com/tendermint/spec/blob/master/spec/consensus/signing.md#votes) 259 260 Finally, the proposer selection algorithm continues to evolve. See the 261 [work-in-progress 262 specification](https://github.com/tendermint/tendermint/pull/3140). 263 264 For everything else, please see the [CHANGELOG](./CHANGELOG.md#v0.29.0). 265 266 ## v0.28.0 267 268 This release breaks the format for the `priv_validator.json` file 269 and the protocol used for the external validator process. 270 It is compatible with v0.27.0 blockchains (neither the BlockProtocol nor the 271 P2PProtocol have changed). 272 273 Please read carefully for details about upgrading. 274 275 **Note:** Backup your `config/priv_validator.json` 276 before proceeding. 277 278 ### `priv_validator.json` 279 280 The `config/priv_validator.json` is now two files: 281 `config/priv_validator_key.json` and `data/priv_validator_state.json`. 282 The former contains the key material, the later contains the details on the last 283 message signed. 284 285 When running v0.28.0 for the first time, it will back up any pre-existing 286 `priv_validator.json` file and proceed to split it into the two new files. 287 Upgrading should happen automatically without problem. 288 289 To upgrade manually, use the provided `privValUpgrade.go` script, with exact paths for the old 290 `priv_validator.json` and the locations for the two new files. It's recomended 291 to use the default paths, of `config/priv_validator_key.json` and 292 `data/priv_validator_state.json`, respectively: 293 294 ``` 295 go run scripts/privValUpgrade.go <old-path> <new-key-path> <new-state-path> 296 ``` 297 298 ### External validator signers 299 300 The Unix and TCP implementations of the remote signing validator 301 have been consolidated into a single implementation. 302 Thus in both cases, the external process is expected to dial 303 Tendermint. This is different from how Unix sockets used to work, where 304 Tendermint dialed the external process. 305 306 The `PubKeyMsg` was also split into separate `Request` and `Response` types 307 for consistency with other messages. 308 309 Note that the TCP sockets don't yet use a persistent key, 310 so while they're encrypted, they can't yet be properly authenticated. 311 See [#3105](https://github.com/tendermint/tendermint/issues/3105). 312 Note the Unix socket has neither encryption nor authentication, but will 313 add a shared-secret in [#3099](https://github.com/tendermint/tendermint/issues/3099). 314 315 ## v0.27.0 316 317 This release contains some breaking changes to the block and p2p protocols, 318 but does not change any core data structures, so it should be compatible with 319 existing blockchains from the v0.26 series that only used Ed25519 validator keys. 320 Blockchains using Secp256k1 for validators will not be compatible. This is due 321 to the fact that we now enforce which key types validators can use as a 322 consensus param. The default is Ed25519, and Secp256k1 must be activated 323 explicitly. 324 325 It is recommended to upgrade all nodes at once to avoid incompatibilities at the 326 peer layer - namely, the heartbeat consensus message has been removed (only 327 relevant if `create_empty_blocks=false` or `create_empty_blocks_interval > 0`), 328 and the proposer selection algorithm has changed. Since proposer information is 329 never included in the blockchain, this change only affects the peer layer. 330 331 ### Go API Changes 332 333 #### libs/db 334 335 The ReverseIterator API has changed the meaning of `start` and `end`. 336 Before, iteration was from `start` to `end`, where 337 `start > end`. Now, iteration is from `end` to `start`, where `start < end`. 338 The iterator also excludes `end`. This change allows a simplified and more 339 intuitive logic, aligning the semantic meaning of `start` and `end` in the 340 `Iterator` and `ReverseIterator`. 341 342 ### Applications 343 344 This release enforces a new consensus parameter, the 345 ValidatorParams.PubKeyTypes. Applications must ensure that they only return 346 validator updates with the allowed PubKeyTypes. If a validator update includes a 347 pubkey type that is not included in the ConsensusParams.Validator.PubKeyTypes, 348 block execution will fail and the consensus will halt. 349 350 By default, only Ed25519 pubkeys may be used for validators. Enabling 351 Secp256k1 requires explicit modification of the ConsensusParams. 352 Please update your application accordingly (ie. restrict validators to only be 353 able to use Ed25519 keys, or explicitly add additional key types to the genesis 354 file). 355 356 ## v0.26.0 357 358 This release contains a lot of changes to core data types and protocols. It is not 359 compatible to the old versions and there is no straight forward way to update 360 old data to be compatible with the new version. 361 362 To reset the state do: 363 364 ``` 365 $ tendermint unsafe_reset_all 366 ``` 367 368 Here we summarize some other notable changes to be mindful of. 369 370 ### Config Changes 371 372 All timeouts must be changed from integers to strings with their duration, for 373 instance `flush_throttle_timeout = 100` would be changed to 374 `flush_throttle_timeout = "100ms"` and `timeout_propose = 3000` would be changed 375 to `timeout_propose = "3s"`. 376 377 ### RPC Changes 378 379 The default behaviour of `/abci_query` has been changed to not return a proof, 380 and the name of the parameter that controls this has been changed from `trusted` 381 to `prove`. To get proofs with your queries, ensure you set `prove=true`. 382 383 Various version fields like `amino_version`, `p2p_version`, `consensus_version`, 384 and `rpc_version` have been removed from the `node_info.other` and are 385 consolidated under the tendermint semantic version (ie. `node_info.version`) and 386 the new `block` and `p2p` protocol versions under `node_info.protocol_version`. 387 388 ### ABCI Changes 389 390 Field numbers were bumped in the `Header` and `ResponseInfo` messages to make 391 room for new `version` fields. It should be straight forward to recompile the 392 protobuf file for these changes. 393 394 #### Proofs 395 396 The `ResponseQuery.Proof` field is now structured as a `[]ProofOp` to support 397 generalized Merkle tree constructions where the leaves of one Merkle tree are 398 the root of another. If you don't need this functionality, and you used to 399 return `<proof bytes>` here, you should instead return a single `ProofOp` with 400 just the `Data` field set: 401 402 ``` 403 []ProofOp{ 404 ProofOp{ 405 Data: <proof bytes>, 406 } 407 } 408 ``` 409 410 For more information, see: 411 412 - [ADR-026](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/architecture/adr-026-general-merkle-proof.md) 413 - [Relevant ABCI 414 documentation](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/spec/abci/apps.md#query-proofs) 415 - [Description of 416 keys](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/crypto/merkle/proof_key_path.go#L14) 417 418 ### Go API Changes 419 420 #### crypto/merkle 421 422 The `merkle.Hasher` interface was removed. Functions which used to take `Hasher` 423 now simply take `[]byte`. This means that any objects being Merklized should be 424 serialized before they are passed in. 425 426 #### node 427 428 The `node.RunForever` function was removed. Signal handling and running forever 429 should instead be explicitly configured by the caller. See how we do it 430 [here](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/cmd/tendermint/commands/run_node.go#L60). 431 432 ### Other 433 434 All hashes, except for public key addresses, are now 32-bytes. 435 436 ## v0.25.0 437 438 This release has minimal impact. 439 440 If you use GasWanted in ABCI and want to enforce it, set the MaxGas in the genesis file (default is no max). 441 442 ## v0.24.0 443 444 New 0.24.0 release contains a lot of changes to the state and types. It's not 445 compatible to the old versions and there is no straight forward way to update 446 old data to be compatible with the new version. 447 448 To reset the state do: 449 450 ``` 451 $ tendermint unsafe_reset_all 452 ``` 453 454 Here we summarize some other notable changes to be mindful of. 455 456 ### Config changes 457 458 `p2p.max_num_peers` was removed in favor of `p2p.max_num_inbound_peers` and 459 `p2p.max_num_outbound_peers`. 460 461 ``` 462 # Maximum number of inbound peers 463 max_num_inbound_peers = 40 464 465 # Maximum number of outbound peers to connect to, excluding persistent peers 466 max_num_outbound_peers = 10 467 ``` 468 469 As you can see, the default ratio of inbound/outbound peers is 4/1. The reason 470 is we want it to be easier for new nodes to connect to the network. You can 471 tweak these parameters to alter the network topology. 472 473 ### RPC Changes 474 475 The result of `/commit` used to contain `header` and `commit` fields at the top level. These are now contained under the `signed_header` field. 476 477 ### ABCI Changes 478 479 The header has been upgraded and contains new fields, but none of the existing 480 fields were changed, except their order. 481 482 The `Validator` type was split into two, one containing an `Address` and one 483 containing a `PubKey`. When processing `RequestBeginBlock`, use the `Validator` 484 type, which contains just the `Address`. When returning `ResponseEndBlock`, use 485 the `ValidatorUpdate` type, which contains just the `PubKey`. 486 487 ### Validator Set Updates 488 489 Validator set updates returned in ResponseEndBlock for height `H` used to take 490 effect immediately at height `H+1`. Now they will be delayed one block, to take 491 effect at height `H+2`. Note this means that the change will be seen by the ABCI 492 app in the `RequestBeginBlock.LastCommitInfo` at block `H+3`. Apps were already 493 required to maintain a map from validator addresses to pubkeys since v0.23 (when 494 pubkeys were removed from RequestBeginBlock), but now they may need to track 495 multiple validator sets at once to accomodate this delay. 496 497 ### Block Size 498 499 The `ConsensusParams.BlockSize.MaxTxs` was removed in favour of 500 `ConsensusParams.BlockSize.MaxBytes`, which is now enforced. This means blocks 501 are limitted only by byte-size, not by number of transactions.