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