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