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