github.com/KYVENetwork/cometbft/v38@v38.0.3/UPGRADING.md (about) 1 # Upgrading CometBFT 2 3 This guide provides instructions for upgrading to specific versions of CometBFT. 4 5 ## v0.38.0 6 7 This release introduces state machine-breaking changes, as well as substantial changes 8 on the ABCI interface and indexing. It therefore requires a 9 coordinated upgrade. 10 11 ### Config Changes 12 13 * The field `Version` in the mempool section has been removed. The priority 14 mempool (what was called version `v1`) has been removed (see below), thus 15 there is only one implementation of the mempool available (what was called 16 `v0`). 17 * Config fields `TTLDuration` and `TTLNumBlocks`, which were only used by the 18 priority mempool, have been removed. 19 20 ### Mempool Changes 21 22 * The priority mempool (what was referred in the code as version `v1`) has been 23 removed. There is now only one mempool (what was called version `v0`), that 24 is, the default implementation as a queue of transactions. 25 * In the protobuf message `ResponseCheckTx`, fields `sender`, `priority`, and 26 `mempool_error`, which were only used by the priority mempool, were removed 27 but still kept in the message as "reserved". 28 29 ### ABCI Changes 30 31 * The `ABCIVersion` is now `2.0.0`. 32 * Added new ABCI methods `ExtendVote`, and `VerifyVoteExtension`. 33 Applications upgrading to v0.38.0 must implement these methods as described 34 [here](./spec/abci/abci%2B%2B_comet_expected_behavior.md#adapting-existing-applications-that-use-abci) 35 * Removed methods `BeginBlock`, `DeliverTx`, `EndBlock`, and replaced them by 36 method `FinalizeBlock`. Applications upgrading to `v0.38.0` must refactor 37 the logic handling the methods removed to handle `FinalizeBlock`. 38 * The Application's hash (or any data representing the Application's current state) 39 is known by the time `FinalizeBlock` finishes its execution. 40 Accordingly, the `app_hash` parameter has been moved from `ResponseCommit` 41 to `ResponseFinalizeBlock`. 42 * Field `signed_last_block` in structure `VoteInfo` has been replaced by the 43 more expressive `block_id_flag`. Applications willing to keep the semantics 44 of `signed_last_block` can now use the following predicate 45 * `voteInfo.block_id_flag != BlockIDFlagAbsent` 46 * For further details, please see the updated [specification](spec/abci/README.md) 47 48 ## v0.37.0 49 50 This release introduces state machine-breaking changes, and therefore requires a 51 coordinated upgrade. 52 53 ### Go API 54 55 When upgrading from the v0.34 release series, please note that the Go module has 56 now changed to `github.com/cometbft/cometbft`. 57 58 ### ABCI Changes 59 60 * The `ABCIVersion` is now `1.0.0`. 61 * Added new ABCI methods `PrepareProposal` and `ProcessProposal`. For details, 62 please see the [spec](spec/abci/README.md). Applications upgrading to 63 v0.37.0 must implement these methods, at the very minimum, as described 64 [here](./spec/abci/abci++_app_requirements.md) 65 * Deduplicated `ConsensusParams` and `BlockParams`. 66 In the v0.34 branch they are defined both in `abci/types.proto` and `types/params.proto`. 67 The definitions in `abci/types.proto` have been removed. 68 In-process applications should make sure they are not using the deleted 69 version of those structures. 70 * In v0.34, messages on the wire used to be length-delimited with `int64` varint 71 values, which was inconsistent with the `uint64` varint length delimiters used 72 in the P2P layer. Both now consistently use `uint64` varint length delimiters. 73 * Added `AbciVersion` to `RequestInfo`. 74 Applications should check that CometBFT's ABCI version matches the one they expect 75 in order to ensure compatibility. 76 * The `SetOption` method has been removed from the ABCI `Client` interface. 77 The corresponding Protobuf types have been deprecated. 78 * The `key` and `value` fields in the `EventAttribute` type have been changed 79 from type `bytes` to `string`. As per the [Protocol Buffers updating 80 guidelines](https://developers.google.com/protocol-buffers/docs/proto3#updating), 81 this should have no effect on the wire-level encoding for UTF8-encoded 82 strings. 83 84 ### RPC 85 86 If you rely on the `/tx_search` or `/block_search` endpoints for event querying, 87 please note that the default behaviour of these endpoints has changed in a way 88 that might break your queries. The original behaviour was poorly specified, 89 which did not respect event boundaries. 90 91 Please see 92 [tendermint/tendermint\#9712](https://github.com/tendermint/tendermint/issues/9712) 93 for context on the bug that was addressed that resulted in this behaviour 94 change. 95 96 ## v0.34.27 97 98 This is the first official release of CometBFT, forked originally from 99 [Tendermint Core v0.34.24][v03424] and subsequently updated in Informal Systems' 100 public fork of Tendermint Core for [v0.34.25][v03425] and [v0.34.26][v03426]. 101 102 ### Upgrading from Tendermint Core 103 104 If you already make use of Tendermint Core (either the original Tendermint Core 105 v0.34.24, or Informal Systems' public fork), you can upgrade to CometBFT 106 v0.34.27 by replacing your dependency in your `go.mod` file: 107 108 ```bash 109 go mod edit -replace github.com/tendermint/tendermint=github.com/cometbft/cometbft@v0.34.27 110 ``` 111 112 We make use of the original module URL in order to minimize the impact of 113 switching to CometBFT. This is only possible in our v0.34 release series, and we 114 will be switching our module URL to `github.com/cometbft/cometbft` in the next 115 major release. 116 117 ### Home directory 118 119 CometBFT, by default, will consider its home directory in `~/.cometbft` from now 120 on instead of `~/.tendermint`. 121 122 ### Environment variables 123 124 The environment variable prefixes have now changed from `TM` to `CMT`. For 125 example, `TMHOME` becomes `CMTHOME`. 126 127 We have implemented a fallback check in case `TMHOME` is still set and `CMTHOME` 128 is not, but you will start to see a warning message in the logs if the old 129 `TMHOME` variable is set. This fallback check will be removed entirely in a 130 subsequent major release of CometBFT. 131 132 ### Building CometBFT 133 134 CometBFT must be compiled using Go 1.19 or higher. The use of Go 1.18 is not 135 supported, since this version has reached end-of-life with the release of [Go 1.20][go120]. 136 137 ### Troubleshooting 138 139 If you run into any trouble with this upgrade, please [contact us][discussions]. 140 141 --- 142 143 For historical upgrading instructions for Tendermint Core v0.34.24 and earlier, 144 please see the [Tendermint Core upgrading instructions][tmupgrade]. 145 146 [v03424]: https://github.com/tendermint/tendermint/releases/tag/v0.34.24 147 [v03425]: https://github.com/informalsystems/tendermint/releases/tag/v0.34.25 148 [v03426]: https://github.com/informalsystems/tendermint/releases/tag/v0.34.26 149 [discussions]: https://github.com/KYVENetwork/cometbft/v38/discussions 150 [tmupgrade]: https://github.com/tendermint/tendermint/blob/35581cf54ec436b8c37fabb43fdaa3f48339a170/UPGRADING.md 151 [go120]: https://go.dev/blog/go1.20