github.com/ari-anchor/sei-tendermint@v0.0.0-20230519144642-dc826b7b56bb/UPGRADING.md (about) 1 # Upgrading Tendermint Core 2 3 This guide provides instructions for upgrading to specific versions of Tendermint Core. 4 5 ## v0.36 6 7 ### ABCI Changes 8 9 ### ResponseCheckTx Parameter Change 10 11 `ResponseCheckTx` had fields that are not used by Tendermint, they are now removed. 12 In 0.36, we removed the following fields, from `ResponseCheckTx`: `Log`, `Info`, `Events`, 13 `GasUsed` and `MempoolError`. 14 `MempoolError` was used to signal to operators that a transaction was rejected from the mempool 15 by Tendermint itself. Right now, we return a regular error when this happens. 16 17 #### ABCI++ 18 19 For information on how ABCI++ works, see the 20 [Specification](https://github.com/tendermint/tendermint/blob/master/spec/abci%2B%2B/README.md). 21 In particular, the simplest way to upgrade your application is described 22 [here](https://github.com/tendermint/tendermint/blob/master/spec/abci%2B%2B/abci++_tmint_expected_behavior_002_draft.md#adapting-existing-applications-that-use-abci). 23 24 #### Moving the `app_hash` parameter 25 26 The Application's hash (or any data representing the Application's current 27 state) is known by the time `FinalizeBlock` finishes its execution. 28 Accordingly, the `app_hash` parameter has been moved from `ResponseCommit` to 29 `ResponseFinalizeBlock`, since it makes sense for the Application to return 30 this value as soon as is it known. 31 32 #### ABCI Mutex 33 34 In previous versions of ABCI, Tendermint was prevented from making 35 concurrent calls to ABCI implementations by virtue of mutexes in the 36 implementation of Tendermint's ABCI infrastructure. These mutexes have 37 been removed from the current implementation and applications will now 38 be responsible for managing their own concurrency control. 39 40 To replicate the prior semantics, ensure that ABCI applications have a 41 single mutex that protects all ABCI method calls from concurrent 42 access. You can relax these requirements if your application can 43 provide safe concurrent access via other means. This safety is an 44 application concern so be very sure to test the application thoroughly 45 using realistic workloads and the race detector to ensure your 46 applications remains correct. 47 48 ### Config Changes 49 50 - We have added a new, experimental tool to help operators migrate 51 configuration files created by previous versions of Tendermint. 52 To try this tool, run: 53 54 ```shell 55 # Install the tool. 56 go install github.com/tendermint/tendermint/scripts/confix@latest 57 58 # Run the tool with the old configuration file as input. 59 # Replace the -config argument with your path. 60 confix -config ~/.tendermint/config/config.toml -out updated.toml 61 ``` 62 63 This tool should be able to update configurations from v0.34 and v0.35. We 64 plan to extend it to handle older configuration files in the future. For now, 65 it will report an error (without making any changes) if it does not recognize 66 the version that created the file. 67 68 - The default configuration for a newly-created node now disables indexing for 69 ABCI event metadata. Existing node configurations that already have indexing 70 turned on are not affected. Operators who wish to enable indexing for a new 71 node, however, must now edit the `config.toml` explicitly. 72 73 - The function of seed nodes was modified in the past release. Now, seed nodes 74 are treated identically to any other peer, however they only run the PEX 75 reactor. Because of this `seeds` has been removed from the config. Users 76 should add any seed nodes in the list of `bootstrap-peers`. 77 78 ### RPC Changes 79 80 Tendermint v0.36 adds a new RPC event subscription API. The existing event 81 subscription API based on websockets is now deprecated. It will continue to 82 work throughout the v0.36 release, but the `subscribe`, `unsubscribe`, and 83 `unsubscribe_all` methods, along with websocket support, will be removed in 84 Tendermint v0.37. Callers currently using these features should migrate as 85 soon as is practical to the new API. 86 87 To enable the new API, node operators set a new `event-log-window-size` 88 parameter in the `[rpc]` section of the `config.toml` file. This defines a 89 duration of time during which the node will log all events published to the 90 event bus for use by RPC consumers. 91 92 Consumers use the new `events` JSON-RPC method to poll for events matching 93 their query in the log. Unlike the streaming API, events are not discarded if 94 the caller is slow, loses its connection, or crashes. As long as the client 95 recovers before its events expire from the log window, it will be able to 96 replay and catch up after recovering. Also unlike the streaming API, the client 97 can tell if it has truly missed events because they have expired from the log. 98 99 The `events` method is a normal JSON-RPC method, and does not require any 100 non-standard response processing (in contrast with the old `subscribe`). 101 Clients can modify their query at any time, and no longer need to coordinate 102 subscribe and unsubscribe calls to handle multiple queries. 103 104 The Go client implementations in the Tendermint Core repository have all been 105 updated to add a new `Events` method, including the light client proxy. 106 107 A new `rpc/client/eventstream` package has also been added to make it easier 108 for users to update existing use of the streaming API to use the polling API 109 The `eventstream` package handles polling and delivers matching events to a 110 callback. 111 112 For more detailed information, see [ADR 075](https://tinyurl.com/adr075) which 113 defines and describes the new API in detail. 114 115 #### BroadcastTx Methods 116 117 All callers should use the new `broadcast_tx` method, which has the 118 same semantics as the legacy `broadcast_tx_sync` method. The 119 `broadcast_tx_sync` and `broadcast_tx_async` methods are now 120 deprecated and will be removed in 0.37. 121 122 Additionally the `broadcast_tx_commit` method is *also* deprecated, 123 and will be removed in 0.37. Client code that submits a transaction 124 and needs to wait for it to be committed to the chain, should poll 125 the tendermint to observe the transaction in the committed state. 126 127 ### Timeout Parameter Changes 128 129 Tendermint v0.36 updates how the Tendermint consensus timing parameters are 130 configured. These parameters, `timeout-propose`, `timeout-propose-delta`, 131 `timeout-prevote`, `timeout-prevote-delta`, `timeout-precommit`, 132 `timeout-precommit-delta`, `timeout-commit`, and `skip-timeout-commit`, were 133 previously configured in `config.toml`. These timing parameters have moved and 134 are no longer configured in the `config.toml` file. These parameters have been 135 migrated into the `ConsensusParameters`. Nodes with these parameters set in the 136 local configuration file will see a warning logged on startup indicating that 137 these parameters are no longer used. 138 139 These parameters have also been pared-down. There are no longer separate 140 parameters for both the `prevote` and `precommit` phases of Tendermint. The 141 separate `timeout-prevote` and `timeout-precommit` parameters have been merged 142 into a single `timeout-vote` parameter that configures both of these similar 143 phases of the consensus protocol. 144 145 A set of reasonable defaults have been put in place for these new parameters 146 that will take effect when the node starts up in version v0.36. New chains 147 created using v0.36 and beyond will be able to configure these parameters in the 148 chain's `genesis.json` file. Chains that upgrade to v0.36 from a previous 149 compatible version of Tendermint will begin running with the default values. 150 Upgrading applications that wish to use different values from the defaults for 151 these parameters may do so by setting the `ConsensusParams.Timeout` field of the 152 `FinalizeBlock` `ABCI` response. 153 154 As a safety measure in case of unusual timing issues during the upgrade to 155 v0.36, an operator may override the consensus timeout values for a single node. 156 Note, however, that these overrides will be removed in Tendermint v0.37. See 157 [configuration](https://github.com/tendermint/tendermint/blob/master/docs/nodes/configuration.md) 158 for more information about these overrides. 159 160 For more discussion of this, see [ADR 074](https://tinyurl.com/adr074), which 161 lays out the reasoning for the changes as well as [RFC 162 009](https://tinyurl.com/rfc009) for a discussion of the complexities of 163 upgrading consensus parameters. 164 165 ### RecheckTx Parameter Change 166 167 `RecheckTx` was previously enabled by the `recheck` parameter in the mempool 168 section of the `config.toml`. 169 Setting it to true made Tendermint invoke another `CheckTx` ABCI call on 170 each transaction remaining in the mempool following the execution of a block. 171 Similar to the timeout parameter changes, this parameter makes more sense as a 172 network-wide coordinated variable so that applications can be written knowing 173 either all nodes agree on whether to run `RecheckTx`. 174 175 Applications can turn on `RecheckTx` by altering the `ConsensusParams` in the 176 `FinalizeBlock` ABCI response. 177 178 ### CLI Changes 179 180 The functionality around resetting a node has been extended to make it safer. The 181 `unsafe-reset-all` command has been replaced by a `reset` command with four 182 subcommands: `blockchain`, `peers`, `unsafe-signer` and `unsafe-all`. 183 184 - `tendermint reset blockchain`: Clears a node of all blocks, consensus state, evidence, 185 and indexed transactions. NOTE: This command does not reset application state. 186 If you need to rollback the last application state (to recover from application 187 nondeterminism), see instead the `tendermint rollback` command. 188 - `tendermint reset peers`: Clears the peer store, which persists information on peers used 189 by the networking layer. This can be used to get rid of stale addresses or to switch 190 to a predefined set of static peers. 191 - `tendermint reset unsafe-signer`: Resets the watermark level of the PrivVal File signer 192 allowing it to sign votes from the genesis height. This should only be used in testing as 193 it can lead to the node double signing. 194 - `tendermint reset unsafe-all`: A summation of the other three commands. This will delete 195 the entire `data` directory which may include application data as well. 196 197 ### Go API Changes 198 199 #### `crypto` Package Cleanup 200 201 The `github.com/tendermint/tendermint/crypto/tmhash` package was removed 202 to improve clarity. Users are encouraged to use the standard library 203 `crypto/sha256` package directly. However, as a convenience, some constants 204 and one function have moved to the Tendermint `crypto` package: 205 206 - The `crypto.Checksum` function returns the sha256 checksum of a 207 byteslice. This is a wrapper around `sha256.Sum265` from the 208 standard libary, but provided as a function to ease type 209 requirements (the library function returns a `[32]byte` rather than 210 a `[]byte`). 211 - `tmhash.TruncatedSize` is now `crypto.AddressSize` which was 212 previously an alias for the same value. 213 - `tmhash.Size` and `tmhash.BlockSize` are now `crypto.HashSize` and 214 `crypto.HashSize`. 215 - `tmhash.SumTruncated` is now available via `crypto.AddressHash` or by 216 `crypto.Checksum(<...>)[:crypto.AddressSize]` 217 218 ## v0.35 219 220 ### ABCI Changes 221 222 * Added `AbciVersion` to `RequestInfo`. Applications should check that the ABCI version they expect is being used in order to avoid unimplemented changes errors. 223 * The method `SetOption` has been removed from the ABCI.Client interface. This feature was used in the early ABCI implementation's. 224 * Messages are written to a byte stream using uin64 length delimiters instead of int64. 225 * When mempool `v1` is enabled, transactions broadcasted via `sync` mode may return a successful 226 response with a transaction hash indicating that the transaction was successfully inserted into 227 the mempool. While this is true for `v0`, the `v1` mempool reactor may at a later point in time 228 evict or even drop this transaction after a hash has been returned. Thus, the user or client must 229 query for that transaction to check if it is still in the mempool. 230 231 ### Config Changes 232 233 * The configuration file field `[fastsync]` has been renamed to `[blocksync]`. 234 235 * The top level configuration file field `fast-sync` has moved under the new `[blocksync]` 236 field as `blocksync.enable`. 237 238 * `blocksync.version = "v1"` and `blocksync.version = "v2"` (previously `fastsync`) 239 are no longer supported. Please use `v0` instead. During the v0.35 release cycle, `v0` was 240 determined to suit the existing needs and the cost of maintaining the `v1` and `v2` modules 241 was determined to be greater than necessary. 242 243 244 * All config parameters are now hyphen-case (also known as kebab-case) instead of snake_case. Before restarting the node make sure 245 you have updated all the variables in your `config.toml` file. 246 247 * Added `--mode` flag and `mode` config variable on `config.toml` for setting Mode of the Node: `full` | `validator` | `seed` (default: `full`) 248 [ADR-52](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-052-tendermint-mode.md) 249 250 * `BootstrapPeers` has been added as part of the new p2p stack. This will eventually replace 251 `Seeds`. Bootstrap peers are connected with on startup if needed for peer discovery. Unlike 252 persistent peers, there's no gaurantee that the node will remain connected with these peers. 253 254 * configuration values starting with `priv-validator-` have moved to the new 255 `priv-validator` section, without the `priv-validator-` prefix. 256 257 * The fast sync process as well as the blockchain package and service has all 258 been renamed to block sync 259 260 ### Database Key Format Changes 261 262 The format of all tendermint on-disk database keys changes in 263 0.35. Upgrading nodes must either re-sync all data or run a migration 264 script provided in this release. 265 266 The script located in 267 `github.com/tendermint/tendermint/scripts/keymigrate/migrate.go` provides the 268 function `Migrate(context.Context, db.DB)` which you can operationalize as 269 makes sense for your deployment. 270 271 For ease of use the `tendermint` command includes a CLI version of the 272 migration script, which you can invoke, as in: 273 274 tendermint key-migrate 275 276 This reads the configuration file as normal and allows the `--db-backend` and 277 `--db-dir` flags to override the database location as needed. 278 279 The migration operation is intended to be idempotent, and should be safe to 280 rerun on the same database multiple times. As a safety measure, however, we 281 recommend that operators test out the migration on a copy of the database 282 first, if it is practical to do so, before applying it to the production data. 283 284 ### CLI Changes 285 286 * You must now specify the node mode (validator|full|seed) in `tendermint init [mode]` 287 288 * The `--fast-sync` command line option has been renamed to `--blocksync.enable` 289 290 * If you had previously used `tendermint gen_node_key` to generate a new node 291 key, keep in mind that it no longer saves the output to a file. You can use 292 `tendermint init validator` or pipe the output of `tendermint gen_node_key` to 293 `$TMHOME/config/node_key.json`: 294 295 ``` 296 $ tendermint gen_node_key > $TMHOME/config/node_key.json 297 ``` 298 299 * CLI commands and flags are all now hyphen-case instead of snake_case. 300 Make sure to adjust any scripts that calls a cli command with snake_casing 301 302 ### API Changes 303 304 The p2p layer was reimplemented as part of the 0.35 release cycle and 305 all reactors were refactored to accomodate the change. As part of that work these 306 implementations moved into the `internal` package and are no longer 307 considered part of the public Go API of tendermint. These packages 308 are: 309 310 - `p2p` 311 - `mempool` 312 - `consensus` 313 - `statesync` 314 - `blockchain` 315 - `evidence` 316 317 Accordingly, the `node` package changed to reduce access to 318 tendermint internals: applications that use tendermint as a library 319 will need to change to accommodate these changes. Most notably: 320 321 - The `Node` type has become internal, and all constructors return a 322 `service.Service` implementation. 323 324 - The `node.DefaultNewNode` and `node.NewNode` constructors are no 325 longer exported and have been replaced with `node.New` and 326 `node.NewDefault` which provide more functional interfaces. 327 328 To access any of the functionality previously available via the 329 `node.Node` type, use the `*local.Local` "RPC" client, that exposes 330 the full RPC interface provided as direct function calls. Import the 331 `github.com/tendermint/tendermint/rpc/client/local` package and pass 332 the node service as in the following: 333 334 ```go 335 logger := log.NewNopLogger() 336 337 // Construct and start up a node with default settings. 338 node := node.NewDefault(logger) 339 340 // Construct a local (in-memory) RPC client to the node. 341 client := local.New(logger, node.(local.NodeService)) 342 ``` 343 344 ### gRPC Support 345 346 Mark gRPC in the RPC layer as deprecated and to be removed in 0.36. 347 348 ### Peer Management Interface 349 350 When running with the new P2P Layer, the methods `UnsafeDialSeeds` and 351 `UnsafeDialPeers` RPC methods will always return an error. They are 352 deprecated and will be removed in 0.36 when the legacy peer stack is 353 removed. 354 355 Additionally the format of the Peer list returned in the `NetInfo` 356 method changes in this release to accommodate the different way that 357 the new stack tracks data about peers. This change affects users of 358 both stacks. 359 360 ### Using the updated p2p library 361 362 The P2P library was reimplemented in this release. The new implementation is 363 enabled by default in this version of Tendermint. The legacy implementation is still 364 included in this version of Tendermint as a backstop to work around unforeseen 365 production issues. The new and legacy version are interoperable. If necessary, 366 you can enable the legacy implementation in the server configuration file. 367 368 To make use of the legacy P2P implemementation add or update the following field of 369 your server's configuration file under the `[p2p]` section: 370 371 ```toml 372 [p2p] 373 ... 374 use-legacy = true 375 ... 376 ``` 377 378 If you need to do this, please consider filing an issue in the Tendermint repository 379 to let us know why. We plan to remove the legacy P2P code in the next (v0.36) release. 380 381 #### New p2p queue types 382 383 The new p2p implementation enables selection of the queue type to be used for 384 passing messages between peers. 385 386 The following values may be used when selecting which queue type to use: 387 388 * `fifo`: (**default**) An unbuffered and lossless queue that passes messages through 389 in the order in which they were received. 390 391 * `priority`: A priority queue of messages. 392 393 * `wdrr`: A queue implementing the Weighted Deficit Round Robin algorithm. A 394 weighted deficit round robin queue is created per peer. Each queue contains a 395 separate 'flow' for each of the channels of communication that exist between any two 396 peers. Tendermint maintains a channel per message type between peers. Each WDRR 397 queue maintains a shared buffered with a fixed capacity through which messages on different 398 flows are passed. 399 For more information on WDRR scheduling, see: https://en.wikipedia.org/wiki/Deficit_round_robin 400 401 To select a queue type, add or update the following field under the `[p2p]` 402 section of your server's configuration file. 403 404 ```toml 405 [p2p] 406 ... 407 queue-type = wdrr 408 ... 409 ``` 410 411 412 ### Support for Custom Reactor and Mempool Implementations 413 414 The changes to p2p layer removed existing support for custom 415 reactors. Based on our understanding of how this functionality was 416 used, the introduction of the prioritized mempool covers nearly all of 417 the use cases for custom reactors. If you are currently running custom 418 reactors and mempools and are having trouble seeing the migration path 419 for your project please feel free to reach out to the Tendermint Core 420 development team directly. 421 422 ## v0.34.0 423 424 **Upgrading to Tendermint 0.34 requires a blockchain restart.** 425 This release is not compatible with previous blockchains due to changes to 426 the encoding format (see "Protocol Buffers," below) and the block header (see "Blockchain Protocol"). 427 428 Note also that Tendermint 0.34 also requires Go 1.16 or higher. 429 430 ### ABCI Changes 431 432 * The `ABCIVersion` is now `0.17.0`. 433 434 * New ABCI methods (`ListSnapshots`, `LoadSnapshotChunk`, `OfferSnapshot`, and `ApplySnapshotChunk`) 435 were added to support the new State Sync feature. 436 Previously, syncing a new node to a preexisting network could take days; but with State Sync, 437 new nodes are able to join a network in a matter of seconds. 438 Read [the spec](https://github.com/tendermint/tendermint/blob/master/spec/abci/apps.md) 439 if you want to learn more about State Sync, or if you'd like your application to use it. 440 (If you don't want to support State Sync in your application, you can just implement these new 441 ABCI methods as no-ops, leaving them empty.) 442 443 * `KV.Pair` has been replaced with `abci.EventAttribute`. The `EventAttribute.Index` field 444 allows ABCI applications to dictate which events should be indexed. 445 446 * The blockchain can now start from an arbitrary initial height, 447 provided to the application via `RequestInitChain.InitialHeight`. 448 449 * ABCI evidence type is now an enum with two recognized types of evidence: 450 `DUPLICATE_VOTE` and `LIGHT_CLIENT_ATTACK`. 451 Applications should be able to handle these evidence types 452 (i.e., through slashing or other accountability measures). 453 454 * The [`PublicKey` type](https://github.com/tendermint/tendermint/blob/master/proto/tendermint/crypto/keys.proto#L13-L15) 455 (used in ABCI as part of `ValidatorUpdate`) now uses a `oneof` protobuf type. 456 Note that since Tendermint only supports ed25519 validator keys, there's only one 457 option in the `oneof`. For more, see "Protocol Buffers," below. 458 459 * The field `Proof`, on the ABCI type `ResponseQuery`, is now named `ProofOps`. 460 For more, see "Crypto," below. 461 462 * The method `SetOption` has been removed from the ABCI.Client interface. This feature was used in the early ABCI implementation's. 463 464 ### P2P Protocol 465 466 The default codec is now proto3, not amino. The schema files can be found in the `/proto` 467 directory. For more, see "Protobuf," below. 468 469 ### Blockchain Protocol 470 471 * `Header#LastResultsHash`, which is the root hash of a Merkle tree built from 472 `ResponseDeliverTx(Code, Data)` as of v0.34 also includes `GasWanted` and `GasUsed` 473 fields. 474 475 * Merkle hashes of empty trees previously returned nothing, but now return the hash of an empty input, 476 to conform with [RFC-6962](https://tools.ietf.org/html/rfc6962). 477 This mainly affects `Header#DataHash`, `Header#LastResultsHash`, and 478 `Header#EvidenceHash`, which are often empty. Non-empty hashes can also be affected, e.g. if their 479 inputs depend on other (empty) Merkle hashes, giving different results. 480 481 ### Transaction Indexing 482 483 Tendermint now relies on the application to tell it which transactions to index. This means that 484 in the `config.toml`, generated by Tendermint, there is no longer a way to specify which 485 transactions to index. `tx.height` and `tx.hash` will always be indexed when using the `kv` indexer. 486 487 Applications must now choose to either a) enable indexing for all transactions, or 488 b) allow node operators to decide which transactions to index. 489 Applications can notify Tendermint to index a specific transaction by setting 490 `Index: bool` to `true` in the Event Attribute: 491 492 ```go 493 []types.Event{ 494 { 495 Type: "app", 496 Attributes: []types.EventAttribute{ 497 {Key: []byte("creator"), Value: []byte("Cosmoshi Netowoko"), Index: true}, 498 }, 499 }, 500 } 501 ``` 502 503 ### Protocol Buffers 504 505 Tendermint 0.34 replaces Amino with Protocol Buffers for encoding. 506 This migration is extensive and results in a number of changes, however, 507 Tendermint only uses the types generated from Protocol Buffers for disk and 508 wire serialization. 509 **This means that these changes should not affect you as a Tendermint user.** 510 511 However, Tendermint users and contributors may note the following changes: 512 513 * Directory layout changes: All proto files have been moved under one directory, `/proto`. 514 This is in line with the recommended file layout by [Buf](https://buf.build). 515 For more, see the [Buf documentation](https://buf.build/docs/lint-checkers#file_layout). 516 * ABCI Changes: As noted in the "ABCI Changes" section above, the `PublicKey` type now uses 517 a `oneof` type. 518 519 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). 520 521 ### Consensus Parameters 522 523 Tendermint 0.34 includes new and updated consensus parameters. 524 525 #### Version Parameters (New) 526 527 * `AppVersion`, which is the version of the ABCI application. 528 529 #### Evidence Parameters 530 531 * `MaxBytes`, which caps the total amount of evidence. The default is 1048576 (1 MB). 532 533 ### Crypto 534 535 #### Keys 536 537 * Keys no longer include a type prefix. For example, ed25519 pubkeys have been renamed from 538 `PubKeyEd25519` to `PubKey`. This reduces stutter (e.g., `ed25519.PubKey`). 539 * Keys are now byte slices (`[]byte`) instead of byte arrays (`[<size>]byte`). 540 * The multisig functionality that was previously in Tendermint now has 541 a new home within the Cosmos SDK: 542 [`cosmos/cosmos-sdk/types/multisig`](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/types/multisig/multisignature.go). 543 544 #### `merkle` Package 545 546 * `SimpleHashFromMap()` and `SimpleProofsFromMap()` were removed. 547 * The prefix `Simple` has been removed. (For example, `SimpleProof` is now called `Proof`.) 548 * All protobuf messages have been moved to the `/proto` directory. 549 * The protobuf message `Proof` that contained multiple ProofOp's has been renamed to `ProofOps`. 550 As noted above, this affects the ABCI type `ResponseQuery`: 551 The field that was named Proof is now named `ProofOps`. 552 * `HashFromByteSlices` and `ProofsFromByteSlices` now return a hash for empty inputs, to conform with 553 [RFC-6962](https://tools.ietf.org/html/rfc6962). 554 555 ### `libs` Package 556 557 The `bech32` package has moved to the Cosmos SDK: 558 [`cosmos/cosmos-sdk/types/bech32`](https://github.com/cosmos/cosmos-sdk/tree/4173ea5ebad906dd9b45325bed69b9c655504867/types/bech32). 559 560 ### CLI 561 562 The `tendermint lite` command has been renamed to `tendermint light` and has a slightly different API. 563 564 ### Light Client 565 566 We have a new, rewritten light client! You can 567 [read more](https://medium.com/tendermint/everything-you-need-to-know-about-the-tendermint-light-client-f80d03856f98) 568 about the justifications and details behind this change. 569 570 Other user-relevant changes include: 571 572 * The old `lite` package was removed; the new light client uses the `light` package. 573 * The `Verifier` was broken up into two pieces: 574 * Core verification logic (pure `VerifyX` functions) 575 * `Client` object, which represents the complete light client 576 * The new light clients stores headers & validator sets as `LightBlock`s 577 * The RPC client can be found in the `/rpc` directory. 578 * The HTTP(S) proxy is located in the `/proxy` directory. 579 580 ### `state` Package 581 582 * A new field `State.InitialHeight` has been added to record the initial chain height, which must be `1` 583 (not `0`) if starting from height `1`. This can be configured via the genesis field `initial_height`. 584 * The `state` package now has a `Store` interface. All functions in 585 [state/store.go](https://github.com/tendermint/tendermint/blob/56911ee35298191c95ef1c7d3d5ec508237aaff4/state/store.go#L42-L42) 586 are now part of the interface. The interface returns errors on all methods and can be used by calling `state.NewStore(dbm.DB)`. 587 588 ### `privval` Package 589 590 All requests are now accompanied by the chain ID from the network. 591 This is a optional field and can be ignored by key management systems; 592 however, if you are using the same key management system for multiple different 593 blockchains, we recommend that you check the chain ID. 594 595 596 ### RPC 597 598 * `/unsafe_start_cpu_profiler`, `/unsafe_stop_cpu_profiler` and 599 `/unsafe_write_heap_profile` were removed. 600 For profiling, please use the pprof server, which can 601 be enabled through `--rpc.pprof_laddr=X` flag or `pprof_laddr=X` config setting 602 in the rpc section. 603 * The `Content-Type` header returned on RPC calls is now (correctly) set as `application/json`. 604 605 ### Version 606 607 Version is now set through Go linker flags `ld_flags`. Applications that are using tendermint as a library should set this at compile time. 608 609 Example: 610 611 ```sh 612 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 613 ``` 614 615 Additionally, the exported constant `version.Version` is now `version.TMCoreSemVer`. 616 617 ## v0.33.4 618 619 ### Go API 620 621 * `rpc/client` HTTP and local clients have been moved into `http` and `local` 622 subpackages, and their constructors have been renamed to `New()`. 623 624 ### Protobuf Changes 625 626 When upgrading to version 0.33.4 you will have to fetch the `third_party` 627 directory along with the updated proto files. 628 629 ### Block Retention 630 631 ResponseCommit added a field for block retention. The application can provide information to Tendermint on how to prune blocks. 632 If an application would like to not prune any blocks pass a `0` in this field. 633 634 ```proto 635 message ResponseCommit { 636 // reserve 1 637 bytes data = 2; // the Merkle root hash 638 ++ uint64 retain_height = 3; // the oldest block height to retain ++ 639 } 640 ``` 641 642 ## v0.33.0 643 644 This release is not compatible with previous blockchains due to commit becoming 645 signatures only and fields in the header have been removed. 646 647 ### Blockchain Protocol 648 649 `TotalTxs` and `NumTxs` were removed from the header. `Commit` now consists 650 mostly of just signatures. 651 652 ```go 653 type Commit struct { 654 Height int64 655 Round int 656 BlockID BlockID 657 Signatures []CommitSig 658 } 659 ``` 660 661 ```go 662 type BlockIDFlag byte 663 664 const ( 665 // BlockIDFlagAbsent - no vote was received from a validator. 666 BlockIDFlagAbsent BlockIDFlag = 0x01 667 // BlockIDFlagCommit - voted for the Commit.BlockID. 668 BlockIDFlagCommit = 0x02 669 // BlockIDFlagNil - voted for nil. 670 BlockIDFlagNil = 0x03 671 ) 672 673 type CommitSig struct { 674 BlockIDFlag BlockIDFlag 675 ValidatorAddress Address 676 Timestamp time.Time 677 Signature []byte 678 } 679 ``` 680 681 See [\#63](https://github.com/tendermint/spec/pull/63) for the complete spec 682 change. 683 684 ### P2P Protocol 685 686 The secret connection now includes a transcript hashing. If you want to 687 implement a handshake (or otherwise have an existing implementation), you'll 688 need to make the same changes that were made 689 [here](https://github.com/tendermint/tendermint/pull/3668). 690 691 ### Config Changes 692 693 You will need to generate a new config if you have used a prior version of tendermint. 694 695 Tags have been entirely renamed throughout the codebase to events and there 696 keys are called 697 [compositeKeys](https://github.com/tendermint/tendermint/blob/6d05c531f7efef6f0619155cf10ae8557dd7832f/docs/app-dev/indexing-transactions.md). 698 699 Evidence Params has been changed to include duration. 700 701 * `consensus_params.evidence.max_age_duration`. 702 * Renamed `consensus_params.evidence.max_age` to `max_age_num_blocks`. 703 704 ### Go API 705 706 * `libs/common` has been removed in favor of specific pkgs. 707 * `async` 708 * `service` 709 * `rand` 710 * `net` 711 * `strings` 712 * `cmap` 713 * removal of `errors` pkg 714 715 ### RPC Changes 716 717 * `/validators` is now paginated (default: 30 vals per page) 718 * `/block_results` response format updated [see RPC docs for details](https://docs.tendermint.com/master/rpc/#/Info/block_results) 719 * Event suffix has been removed from the ID in event responses 720 * IDs are now integers not `json-client-XYZ` 721 722 ## v0.32.0 723 724 This release is compatible with previous blockchains, 725 however the new ABCI Events mechanism may create some complexity 726 for nodes wishing to continue operation with v0.32 from a previous version. 727 There are some minor breaking changes to the RPC. 728 729 ### Config Changes 730 731 If you have `db_backend` set to `leveldb` in your config file, please change it 732 to `goleveldb` or `cleveldb`. 733 734 ### RPC Changes 735 736 The default listen address for the RPC is now `127.0.0.1`. If you want to expose 737 it publicly, you have to explicitly configure it. Note exposing the RPC to the 738 public internet may not be safe - endpoints which return a lot of data may 739 enable resource exhaustion attacks on your node, causing the process to crash. 740 741 Any consumers of `/block_results` need to be mindful of the change in all field 742 names from CamelCase to Snake case, eg. `results.DeliverTx` is now `results.deliver_tx`. 743 This is a fix, but it's breaking. 744 745 ### ABCI Changes 746 747 ABCI responses which previously had a `Tags` field now have an `Events` field 748 instead. The original `Tags` field was simply a list of key-value pairs, where 749 each key effectively represented some attribute of an event occuring in the 750 blockchain, like `sender`, `receiver`, or `amount`. However, it was difficult to 751 represent the occurence of multiple events (for instance, multiple transfers) in a single list. 752 The new `Events` field contains a list of `Event`, where each `Event` is itself a list 753 of key-value pairs, allowing for more natural expression of multiple events in 754 eg. a single DeliverTx or EndBlock. Note each `Event` also includes a `Type`, which is meant to categorize the 755 event. 756 757 For transaction indexing, the index key is 758 prefixed with the event type: `{eventType}.{attributeKey}`. 759 If the same event type and attribute key appear multiple times, the values are 760 appended in a list. 761 762 To make queries, include the event type as a prefix. For instance if you 763 previously queried for `recipient = 'XYZ'`, and after the upgrade you name your event `transfer`, 764 the new query would be for `transfer.recipient = 'XYZ'`. 765 766 Note that transactions indexed on a node before upgrading to v0.32 will still be indexed 767 using the old scheme. For instance, if a node upgraded at height 100, 768 transactions before 100 would be queried with `recipient = 'XYZ'` and 769 transactions after 100 would be queried with `transfer.recipient = 'XYZ'`. 770 While this presents additional complexity to clients, it avoids the need to 771 reindex. Of course, you can reset the node and sync from scratch to re-index 772 entirely using the new scheme. 773 774 We illustrate further with a more complete example. 775 776 Prior to the update, suppose your `ResponseDeliverTx` look like: 777 778 ```go 779 abci.ResponseDeliverTx{ 780 Tags: []kv.Pair{ 781 {Key: []byte("sender"), Value: []byte("foo")}, 782 {Key: []byte("recipient"), Value: []byte("bar")}, 783 {Key: []byte("amount"), Value: []byte("35")}, 784 } 785 } 786 ``` 787 788 The following queries would match this transaction: 789 790 ```go 791 query.MustParse("tm.event = 'Tx' AND sender = 'foo'") 792 query.MustParse("tm.event = 'Tx' AND recipient = 'bar'") 793 query.MustParse("tm.event = 'Tx' AND sender = 'foo' AND recipient = 'bar'") 794 ``` 795 796 Following the upgrade, your `ResponseDeliverTx` would look something like: 797 the following `Events`: 798 799 ```go 800 abci.ResponseDeliverTx{ 801 Events: []abci.Event{ 802 { 803 Type: "transfer", 804 Attributes: kv.Pairs{ 805 {Key: []byte("sender"), Value: []byte("foo")}, 806 {Key: []byte("recipient"), Value: []byte("bar")}, 807 {Key: []byte("amount"), Value: []byte("35")}, 808 }, 809 } 810 } 811 ``` 812 813 Now the following queries would match this transaction: 814 815 ```go 816 query.MustParse("tm.event = 'Tx' AND transfer.sender = 'foo'") 817 query.MustParse("tm.event = 'Tx' AND transfer.recipient = 'bar'") 818 query.MustParse("tm.event = 'Tx' AND transfer.sender = 'foo' AND transfer.recipient = 'bar'") 819 ``` 820 821 For further documentation on `Events`, see the [docs](https://github.com/tendermint/tendermint/blob/60827f75623b92eff132dc0eff5b49d2025c591e/docs/spec/abci/abci.md#events). 822 823 ### Go Applications 824 825 The ABCI Application interface changed slightly so the CheckTx and DeliverTx 826 methods now take Request structs. The contents of these structs are just the raw 827 tx bytes, which were previously passed in as the argument. 828 829 ## v0.31.6 830 831 There are no breaking changes in this release except Go API of p2p and 832 mempool packages. Hovewer, if you're using cleveldb, you'll need to change 833 the compilation tag: 834 835 Use `cleveldb` tag instead of `gcc` to compile Tendermint with CLevelDB or 836 use `make build_c` / `make install_c` (full instructions can be found at 837 <https://docs.tendermint.com/v0.35/introduction/install.html) 838 839 ## v0.31.0 840 841 This release contains a breaking change to the behaviour of the pubsub system. 842 It also contains some minor breaking changes in the Go API and ABCI. 843 There are no changes to the block or p2p protocols, so v0.31.0 should work fine 844 with blockchains created from the v0.30 series. 845 846 ### RPC 847 848 The pubsub no longer blocks on publishing. This may cause some WebSocket (WS) clients to stop working as expected. 849 If your WS client is not consuming events fast enough, Tendermint can terminate the subscription. 850 In this case, the WS client will receive an error with description: 851 852 ```json 853 { 854 "jsonrpc": "2.0", 855 "id": "{ID}#event", 856 "error": { 857 "code": -32000, 858 "msg": "Server error", 859 "data": "subscription was canceled (reason: client is not pulling messages fast enough)" // or "subscription was canceled (reason: Tendermint exited)" 860 } 861 } 862 863 Additionally, there are now limits on the number of subscribers and 864 subscriptions that can be active at once. See the new 865 `rpc.max_subscription_clients` and `rpc.max_subscriptions_per_client` values to 866 configure this. 867 ``` 868 869 ### Applications 870 871 Simple rename of `ConsensusParams.BlockSize` to `ConsensusParams.Block`. 872 873 The `ConsensusParams.Block.TimeIotaMS` field was also removed. It's configured 874 in the ConsensusParsm in genesis. 875 876 ### Go API 877 878 See the [CHANGELOG](CHANGELOG.md). These are relatively straight forward. 879 880 ## v0.30.0 881 882 This release contains a breaking change to both the block and p2p protocols, 883 however it may be compatible with blockchains created with v0.29.0 depending on 884 the chain history. If your blockchain has not included any pieces of evidence, 885 or no piece of evidence has been included in more than one block, 886 and if your application has never returned multiple updates 887 for the same validator in a single block, then v0.30.0 will work fine with 888 blockchains created with v0.29.0. 889 890 The p2p protocol change is to fix the proposer selection algorithm again. 891 Note that proposer selection is purely a p2p concern right 892 now since the algorithm is only relevant during real time consensus. 893 This change is thus compatible with v0.29.0, but 894 all nodes must be upgraded to avoid disagreements on the proposer. 895 896 ### Applications 897 898 Applications must ensure they do not return duplicates in 899 `ResponseEndBlock.ValidatorUpdates`. A pubkey must only appear once per set of 900 updates. Duplicates will cause irrecoverable failure. If you have a very good 901 reason why we shouldn't do this, please open an issue. 902 903 ## v0.29.0 904 905 This release contains some breaking changes to the block and p2p protocols, 906 and will not be compatible with any previous versions of the software, primarily 907 due to changes in how various data structures are hashed. 908 909 Any implementations of Tendermint blockchain verification, including lite clients, 910 will need to be updated. For specific details: 911 912 * [Merkle tree](https://github.com/tendermint/spec/blob/master/spec/blockchain/encoding.md#merkle-trees) 913 * [ConsensusParams](https://github.com/tendermint/spec/blob/master/spec/blockchain/state.md#consensusparams) 914 915 There was also a small change to field ordering in the vote struct. Any 916 implementations of an out-of-process validator (like a Key-Management Server) 917 will need to be updated. For specific details: 918 919 * [Vote](https://github.com/tendermint/spec/blob/master/spec/consensus/signing.md#votes) 920 921 Finally, the proposer selection algorithm continues to evolve. See the 922 [work-in-progress 923 specification](https://github.com/tendermint/tendermint/pull/3140). 924 925 For everything else, please see the [CHANGELOG](./CHANGELOG.md#v0.29.0). 926 927 ## v0.28.0 928 929 This release breaks the format for the `priv_validator.json` file 930 and the protocol used for the external validator process. 931 It is compatible with v0.27.0 blockchains (neither the BlockProtocol nor the 932 P2PProtocol have changed). 933 934 Please read carefully for details about upgrading. 935 936 **Note:** Backup your `config/priv_validator.json` 937 before proceeding. 938 939 ### `priv_validator.json` 940 941 The `config/priv_validator.json` is now two files: 942 `config/priv_validator_key.json` and `data/priv_validator_state.json`. 943 The former contains the key material, the later contains the details on the last 944 message signed. 945 946 When running v0.28.0 for the first time, it will back up any pre-existing 947 `priv_validator.json` file and proceed to split it into the two new files. 948 Upgrading should happen automatically without problem. 949 950 To upgrade manually, use the provided `privValUpgrade.go` script, with exact paths for the old 951 `priv_validator.json` and the locations for the two new files. It's recomended 952 to use the default paths, of `config/priv_validator_key.json` and 953 `data/priv_validator_state.json`, respectively: 954 955 ```sh 956 go run scripts/privValUpgrade.go <old-path> <new-key-path> <new-state-path> 957 ``` 958 959 ### External validator signers 960 961 The Unix and TCP implementations of the remote signing validator 962 have been consolidated into a single implementation. 963 Thus in both cases, the external process is expected to dial 964 Tendermint. This is different from how Unix sockets used to work, where 965 Tendermint dialed the external process. 966 967 The `PubKeyMsg` was also split into separate `Request` and `Response` types 968 for consistency with other messages. 969 970 Note that the TCP sockets don't yet use a persistent key, 971 so while they're encrypted, they can't yet be properly authenticated. 972 See [#3105](https://github.com/tendermint/tendermint/issues/3105). 973 Note the Unix socket has neither encryption nor authentication, but will 974 add a shared-secret in [#3099](https://github.com/tendermint/tendermint/issues/3099). 975 976 ## v0.27.0 977 978 This release contains some breaking changes to the block and p2p protocols, 979 but does not change any core data structures, so it should be compatible with 980 existing blockchains from the v0.26 series that only used Ed25519 validator keys. 981 Blockchains using Secp256k1 for validators will not be compatible. This is due 982 to the fact that we now enforce which key types validators can use as a 983 consensus param. The default is Ed25519, and Secp256k1 must be activated 984 explicitly. 985 986 It is recommended to upgrade all nodes at once to avoid incompatibilities at the 987 peer layer - namely, the heartbeat consensus message has been removed (only 988 relevant if `create_empty_blocks=false` or `create_empty_blocks_interval > 0`), 989 and the proposer selection algorithm has changed. Since proposer information is 990 never included in the blockchain, this change only affects the peer layer. 991 992 ### Go API Changes 993 994 #### libs/db 995 996 The ReverseIterator API has changed the meaning of `start` and `end`. 997 Before, iteration was from `start` to `end`, where 998 `start > end`. Now, iteration is from `end` to `start`, where `start < end`. 999 The iterator also excludes `end`. This change allows a simplified and more 1000 intuitive logic, aligning the semantic meaning of `start` and `end` in the 1001 `Iterator` and `ReverseIterator`. 1002 1003 ### Applications 1004 1005 This release enforces a new consensus parameter, the 1006 ValidatorParams.PubKeyTypes. Applications must ensure that they only return 1007 validator updates with the allowed PubKeyTypes. If a validator update includes a 1008 pubkey type that is not included in the ConsensusParams.Validator.PubKeyTypes, 1009 block execution will fail and the consensus will halt. 1010 1011 By default, only Ed25519 pubkeys may be used for validators. Enabling 1012 Secp256k1 requires explicit modification of the ConsensusParams. 1013 Please update your application accordingly (ie. restrict validators to only be 1014 able to use Ed25519 keys, or explicitly add additional key types to the genesis 1015 file). 1016 1017 ## v0.26.0 1018 1019 This release contains a lot of changes to core data types and protocols. It is not 1020 compatible to the old versions and there is no straight forward way to update 1021 old data to be compatible with the new version. 1022 1023 To reset the state do: 1024 1025 ```sh 1026 tendermint unsafe_reset_all 1027 ``` 1028 1029 Here we summarize some other notable changes to be mindful of. 1030 1031 ### Config Changes 1032 1033 All timeouts must be changed from integers to strings with their duration, for 1034 instance `flush_throttle_timeout = 100` would be changed to 1035 `flush_throttle_timeout = "100ms"` and `timeout_propose = 3000` would be changed 1036 to `timeout_propose = "3s"`. 1037 1038 ### RPC Changes 1039 1040 The default behaviour of `/abci_query` has been changed to not return a proof, 1041 and the name of the parameter that controls this has been changed from `trusted` 1042 to `prove`. To get proofs with your queries, ensure you set `prove=true`. 1043 1044 Various version fields like `amino_version`, `p2p_version`, `consensus_version`, 1045 and `rpc_version` have been removed from the `node_info.other` and are 1046 consolidated under the tendermint semantic version (ie. `node_info.version`) and 1047 the new `block` and `p2p` protocol versions under `node_info.protocol_version`. 1048 1049 ### ABCI Changes 1050 1051 Field numbers were bumped in the `Header` and `ResponseInfo` messages to make 1052 room for new `version` fields. It should be straight forward to recompile the 1053 protobuf file for these changes. 1054 1055 #### Proofs 1056 1057 The `ResponseQuery.Proof` field is now structured as a `[]ProofOp` to support 1058 generalized Merkle tree constructions where the leaves of one Merkle tree are 1059 the root of another. If you don't need this functionality, and you used to 1060 return `<proof bytes>` here, you should instead return a single `ProofOp` with 1061 just the `Data` field set: 1062 1063 ```go 1064 []ProofOp{ 1065 ProofOp{ 1066 Data: <proof bytes>, 1067 } 1068 } 1069 ``` 1070 1071 For more information, see: 1072 1073 * [ADR-026](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/architecture/adr-026-general-merkle-proof.md) 1074 * [Relevant ABCI 1075 documentation](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/docs/spec/abci/apps.md#query-proofs) 1076 * [Description of 1077 keys](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/crypto/merkle/proof_key_path.go#L14) 1078 1079 ### Go API Changes 1080 1081 #### crypto/merkle 1082 1083 The `merkle.Hasher` interface was removed. Functions which used to take `Hasher` 1084 now simply take `[]byte`. This means that any objects being Merklized should be 1085 serialized before they are passed in. 1086 1087 #### node 1088 1089 The `node.RunForever` function was removed. Signal handling and running forever 1090 should instead be explicitly configured by the caller. See how we do it 1091 [here](https://github.com/tendermint/tendermint/blob/30519e8361c19f4bf320ef4d26288ebc621ad725/cmd/tendermint/commands/run_node.go#L60). 1092 1093 ### Other 1094 1095 All hashes, except for public key addresses, are now 32-bytes. 1096 1097 ## v0.25.0 1098 1099 This release has minimal impact. 1100 1101 If you use GasWanted in ABCI and want to enforce it, set the MaxGas in the genesis file (default is no max). 1102 1103 ## v0.24.0 1104 1105 New 0.24.0 release contains a lot of changes to the state and types. It's not 1106 compatible to the old versions and there is no straight forward way to update 1107 old data to be compatible with the new version. 1108 1109 To reset the state do: 1110 1111 ```sh 1112 tendermint unsafe_reset_all 1113 ``` 1114 1115 Here we summarize some other notable changes to be mindful of. 1116 1117 ### Config changes 1118 1119 `p2p.max_num_peers` was removed in favor of `p2p.max_num_inbound_peers` and 1120 `p2p.max_num_outbound_peers`. 1121 1122 ```toml 1123 # Maximum number of inbound peers 1124 max_num_inbound_peers = 40 1125 1126 # Maximum number of outbound peers to connect to, excluding persistent peers 1127 max_num_outbound_peers = 10 1128 ``` 1129 1130 As you can see, the default ratio of inbound/outbound peers is 4/1. The reason 1131 is we want it to be easier for new nodes to connect to the network. You can 1132 tweak these parameters to alter the network topology. 1133 1134 ### RPC Changes 1135 1136 The result of `/commit` used to contain `header` and `commit` fields at the top level. These are now contained under the `signed_header` field. 1137 1138 ### ABCI Changes 1139 1140 The header has been upgraded and contains new fields, but none of the existing 1141 fields were changed, except their order. 1142 1143 The `Validator` type was split into two, one containing an `Address` and one 1144 containing a `PubKey`. When processing `RequestBeginBlock`, use the `Validator` 1145 type, which contains just the `Address`. When returning `ResponseEndBlock`, use 1146 the `ValidatorUpdate` type, which contains just the `PubKey`. 1147 1148 ### Validator Set Updates 1149 1150 Validator set updates returned in ResponseEndBlock for height `H` used to take 1151 effect immediately at height `H+1`. Now they will be delayed one block, to take 1152 effect at height `H+2`. Note this means that the change will be seen by the ABCI 1153 app in the `RequestBeginBlock.LastCommitInfo` at block `H+3`. Apps were already 1154 required to maintain a map from validator addresses to pubkeys since v0.23 (when 1155 pubkeys were removed from RequestBeginBlock), but now they may need to track 1156 multiple validator sets at once to accomodate this delay. 1157 1158 ### Block Size 1159 1160 The `ConsensusParams.BlockSize.MaxTxs` was removed in favour of 1161 `ConsensusParams.BlockSize.MaxBytes`, which is now enforced. This means blocks 1162 are limitted only by byte-size, not by number of transactions.