Skip to content

Latest commit

 

History

History
146 lines (106 loc) · 6.57 KB

UPGRADING.md

File metadata and controls

146 lines (106 loc) · 6.57 KB
Raw

Upgrading CometBFT

This guide provides instructions for upgrading to specific versions of CometBFT.

Unreleased

Config Changes

  • A new config field, BootstrapPeers has been introduced as a means of adding a list of addresses to the address book upon initializing a node. This is an alternative to PersistentPeers. PersistentPeers should be only used for nodes that you want to keep a constant connection with i.e. sentry nodes
  • The field Version in the mempool section has been removed. The priority mempool (what was called version v1) has been removed (see below), thus there is only one implementation of the mempool available (what was called v0).
  • Config fields TTLDuration and TTLNumBlocks, which were only used by the priority mempool, have been removed.

Mempool Changes

  • The priority mempool (what was referred in the code as version v1) has been removed. There is now only one mempool (what was called version v0), that is, the default implementation as a queue of transactions.
  • In the protobuf message ResponseCheckTx, fields sender, priority, and mempool_error, which were only used by the priority mempool, were removed but still kept in the message as "reserved".

block_results RPC endpoint - query result display change (breaking)

  • When returning a block, all block events are displayed within the finalize_block_events field. For blocks generated with older versions of CometBFT, that means that block results that appeared as begin_block_events and end_block_events are merged into finalize_block_events. For users who rely on the events to be grouped by the function they were generated by, this change is breaking.

kvindexer changes to indexing block events

The changes described here are internal to the implementation of the kvindexer, and they are transparent to the user. However, if you own a fork with a modified version of the indexer, you should be aware of these changes.

  • Indexer key for block events will not contain information about the function that returned the event. The events were indexed by their attributes, event type, the function that returned them, the height and event sequence. The functions returning events in old (pre v0.38.0) versions of CometBFT were BeginBlock or EndBlock. As events are returned now only via FinalizeBlock, the value of this field has no use, and has been removed. The main motivation is the reduction of the storage footprint.

Events indexed with previous CometBFT or Tendermint Core versions, will still be transparently processed. There is no need to re-index the events. This function field is not exposed to queries, and was not visible to users. However, if you forked CometBFT and changed the indexer code directly to accomodate for this, this will impact your code.

v0.37.0

This release introduces state machine-breaking changes, and therefore requires a coordinated upgrade.

Go API

When upgrading from the v0.34 release series, please note that the Go module has now changed to github.com/cometbft/cometbft.

ABCI Changes

  • The ABCIVersion is now 2.0.0.
  • Added new ABCI methods ExtendVote, and VerifyVoteExtension. Applications upgrading to v0.38.0 must implement these methods as described here
  • Removed methods BeginBlock, DeliverTx, EndBlock, and replaced them by method FinalizeBlock. Applications upgrading to v0.38.0 must refactor the logic handling the methods removed to handle FinalizeBlock.
  • The Application's hash (or any data representing the Application's current state) is known by the time FinalizeBlock finishes its execution. Accordingly, the app_hash parameter has been moved from ResponseCommit to ResponseFinalizeBlock.
  • For details, please see the updated specification

RPC

If you rely on the /tx_search or /block_search endpoints for event querying, please note that the default behaviour of these endpoints has changed in a way that might break your queries. The original behaviour was poorly specified, which did not respect event boundaries.

Please see tendermint/tendermint#9712 for context on the bug that was addressed that resulted in this behaviour change.

v0.34.27

This is the first official release of CometBFT, forked originally from Tendermint Core v0.34.24 and subsequently updated in Informal Systems' public fork of Tendermint Core for v0.34.25 and v0.34.26.

Upgrading from Tendermint Core

If you already make use of Tendermint Core (either the original Tendermint Core v0.34.24, or Informal Systems' public fork), you can upgrade to CometBFT v0.34.27 by replacing your dependency in your go.mod file:

go mod edit -replace github.com/tendermint/tendermint=github.com/cometbft/cometbft@v0.34.27

We make use of the original module URL in order to minimize the impact of switching to CometBFT. This is only possible in our v0.34 release series, and we will be switching our module URL to github.com/cometbft/cometbft in the next major release.

Home directory

CometBFT, by default, will consider its home directory in ~/.cometbft from now on instead of ~/.tendermint.

Environment variables

The environment variable prefixes have now changed from TM to CMT. For example, TMHOME becomes CMTHOME.

We have implemented a fallback check in case TMHOME is still set and CMTHOME is not, but you will start to see a warning message in the logs if the old TMHOME variable is set. This fallback check will be removed entirely in a subsequent major release of CometBFT.

Building CometBFT

CometBFT must be compiled using Go 1.19 or higher. The use of Go 1.18 is not supported, since this version has reached end-of-life with the release of Go 1.20.

Troubleshooting

If you run into any trouble with this upgrade, please contact us.

For historical upgrading instructions for Tendermint Core v0.34.24 and earlier, please see the Tendermint Core upgrading instructions.