github.com/aakash4dev/cometbft@v0.38.2/UPGRADING.md (about) 1 # Upgrading CometBFT 2 3 This guide provides instructions for upgrading to specific versions of CometBFT. 4 5 ## Unreleased 6 7 ### Config Changes 8 9 * The field `Version` in the mempool section has been removed. The priority 10 mempool (what was called version `v1`) has been removed (see below), thus 11 there is only one implementation of the mempool available (what was called 12 `v0`). 13 * Config fields `TTLDuration` and `TTLNumBlocks`, which were only used by the priority 14 mempool, have been removed. 15 16 ### Consensus Changes 17 18 * Removed the `consensus.State.ReplayFile` and `consensus.RunReplayFile` 19 methods, as these were exclusively used by the `replay` and `replay-console` 20 subcommands, which were also removed 21 ([\#1170](https://github.com/aakash4dev/cometbft/pull/1170)) 22 23 ### Mempool Changes 24 25 * The priority mempool (what was referred in the code as version `v1`) has been 26 removed. There is now only one mempool (what was called version `v0`), that 27 is, the default implementation as a queue of transactions. 28 * In the protobuf message `ResponseCheckTx`, fields `sender`, `priority`, and 29 `mempool_error`, which were only used by the priority mempool, were removed 30 but still kept in the message as "reserved". 31 * The `Mempool` interface was modified on the following methods. Note that this 32 interface is meant for internal use only, so you should be aware of these 33 changes only if you happen to call these methods directly. 34 - `CheckTx`'s signature changed from 35 `CheckTx(tx types.Tx, cb func(*abci.ResponseCheckTx), txInfo TxInfo) error` 36 to `CheckTx(tx types.Tx) (abcicli.ReqRes, error)`. 37 - The method used to take a callback function `cb` to be applied to the ABCI 38 `CheckTx` response. Now `CheckTx` returns the ABCI response of type 39 `abcicli.ReqRes`, on which the callback must be applied manually. For 40 example: 41 ```golang 42 reqRes, err := CheckTx(tx) 43 cb(reqRes.Response.GetCheckTx()) 44 ``` 45 - The second parameter was `txInfo`, which essentially contained information 46 about the sender of the transaction. Now that information is stored in the 47 mempool reactor instead of the data structure, so it is no longer needed in 48 this method. 49 50 ### Command Line Subcommands 51 52 * Removed the `replay` and `replay-console` subcommands 53 ([\#1170](https://github.com/aakash4dev/cometbft/pull/1170)) 54 55 ### `block_results` RPC endpoint - query result display change (breaking) 56 57 * When returning a block, all block events are displayed within the `finalize_block_events` field. 58 For blocks generated with older versions of CometBFT, that means that block results that appeared 59 as `begin_block_events` and `end_block_events` are merged into `finalize_block_events`. 60 For users who rely on the events to be grouped by the function they were generated by, this change 61 is breaking. 62 63 ### kvindexer changes to indexing block events 64 65 The changes described here are internal to the implementation of the kvindexer, and they are transparent to the 66 user. However, if you own a fork with a modified version of the indexer, you should be aware of these changes. 67 68 * Indexer key for block events will not contain information about the function that returned the event. 69 The events were indexed by their attributes, event type, the function that returned them, the height and 70 event sequence. The functions returning events in old (pre `v0.38.0`) versions of CometBFT were `BeginBlock` or `EndBlock`. 71 As events are returned now only via `FinalizeBlock`, the value of this field has no use, and has been removed. 72 The main motivation is the reduction of the storage footprint. 73 74 Events indexed with previous CometBFT or Tendermint Core versions, will still be transparently processed. 75 There is no need to re-index the events. This function field is not exposed to queries, and was not 76 visible to users. However, if you forked CometBFT and changed the indexer code directly to accomodate for this, 77 this will impact your code. 78 79 ## v0.37.0 80 81 This release introduces state machine-breaking changes, and therefore requires a 82 coordinated upgrade. 83 84 ### Go API 85 86 When upgrading from the v0.34 release series, please note that the Go module has 87 now changed to `github.com/aakash4dev/cometbft`. 88 89 ### ABCI Changes 90 91 * The `ABCIVersion` is now `2.0.0`. 92 * Added new ABCI methods `ExtendVote`, and `VerifyVoteExtension`. 93 Applications upgrading to v0.38.0 must implement these methods as described 94 [here](./spec/abci/abci%2B%2B_comet_expected_behavior.md#adapting-existing-applications-that-use-abci) 95 * Removed methods `BeginBlock`, `DeliverTx`, `EndBlock`, and replaced them by 96 method `FinalizeBlock`. Applications upgrading to v0.38.0 must refactor 97 the logic handling the methods removed to handle `FinalizeBlock`. 98 * The Application's hash (or any data representing the Application's current state) 99 is known by the time `FinalizeBlock` finishes its execution. 100 Accordingly, the `app_hash` parameter has been moved from `ResponseCommit` 101 to `ResponseFinalizeBlock`. 102 * For details, please see the updated [specification](spec/abci/README.md) 103 104 105 ### RPC 106 107 If you rely on the `/tx_search` or `/block_search` endpoints for event querying, 108 please note that the default behaviour of these endpoints has changed in a way 109 that might break your queries. The original behaviour was poorly specified, 110 which did not respect event boundaries. 111 112 Please see 113 [tendermint/tendermint\#9712](https://github.com/tendermint/tendermint/issues/9712) 114 for context on the bug that was addressed that resulted in this behaviour 115 change. 116 117 ## v0.34.27 118 119 This is the first official release of CometBFT, forked originally from 120 [Tendermint Core v0.34.24][v03424] and subsequently updated in Informal Systems' 121 public fork of Tendermint Core for [v0.34.25][v03425] and [v0.34.26][v03426]. 122 123 ### Upgrading from Tendermint Core 124 125 If you already make use of Tendermint Core (either the original Tendermint Core 126 v0.34.24, or Informal Systems' public fork), you can upgrade to CometBFT 127 v0.34.27 by replacing your dependency in your `go.mod` file: 128 129 ```bash 130 go mod edit -replace github.com/tendermint/tendermint=github.com/aakash4dev/cometbft@v0.34.27 131 ``` 132 133 We make use of the original module URL in order to minimize the impact of 134 switching to CometBFT. This is only possible in our v0.34 release series, and we 135 will be switching our module URL to `github.com/aakash4dev/cometbft` in the next 136 major release. 137 138 ### Home directory 139 140 CometBFT, by default, will consider its home directory in `~/.cometbft` from now 141 on instead of `~/.tendermint`. 142 143 ### Environment variables 144 145 The environment variable prefixes have now changed from `TM` to `CMT`. For 146 example, `TMHOME` becomes `CMTHOME`. 147 148 We have implemented a fallback check in case `TMHOME` is still set and `CMTHOME` 149 is not, but you will start to see a warning message in the logs if the old 150 `TMHOME` variable is set. This fallback check will be removed entirely in a 151 subsequent major release of CometBFT. 152 153 ### Building CometBFT 154 155 CometBFT must be compiled using Go 1.19 or higher. The use of Go 1.18 is not 156 supported, since this version has reached end-of-life with the release of [Go 1.20][go120]. 157 158 ### Troubleshooting 159 160 If you run into any trouble with this upgrade, please [contact us][discussions]. 161 162 --- 163 164 For historical upgrading instructions for Tendermint Core v0.34.24 and earlier, 165 please see the [Tendermint Core upgrading instructions][tmupgrade]. 166 167 [v03424]: https://github.com/tendermint/tendermint/releases/tag/v0.34.24 168 [v03425]: https://github.com/informalsystems/tendermint/releases/tag/v0.34.25 169 [v03426]: https://github.com/informalsystems/tendermint/releases/tag/v0.34.26 170 [discussions]: https://github.com/aakash4dev/cometbft/discussions 171 [tmupgrade]: https://github.com/tendermint/tendermint/blob/35581cf54ec436b8c37fabb43fdaa3f48339a170/UPGRADING.md 172 [go120]: https://go.dev/blog/go1.20