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