Upgrades Taxonomy

CometBFT Taxonomy of Upgrades

CometBFT is going to change. It’s a fact of life like the sun always rising to the East. It’s important to us as core developers that we can continue to improve CometBFT else we’ll quickly have to find work elsewhere. Yet there’s no point in adding so many delightful features if everyone finds it incredibly annoying to upgrade. What we want from this upcoming work in “Soft Upgrades” is to be able to tick both of these boxes. Before getting started however, I would like to get us all on the same page and using the same terminology. This can help us dissect the many different ways that CometBFT can change and how we can deal with them.

• Semantic Versioning is a method of identifying sets of changes to the CometBFT Repo. Instead of using a single monotonically increasing number, we have three (x.x.x) which help to distinguish the nature of the change. The first number is the major version and indicates an incompatible change. The second number, the minor version, indicates backwards compatibility and the last, the patch version, indicates a backwards compatible security or bug fix. More can be found at https://semver.org/. As CometBFT is both a library and product and is used by various stakeholders, it’s helpful to further break down the types of versions.

• Block Version indicates a change to the protocol. This can be changing how nodes vote, propagate blocks, sign or verify votes or evidence. The block format is a reflection of the protocol. A Block Breaking change refers to an incompatible change to the protocol such that a node running v1 will not be able to make progress in a v2 network. The most common example of a block breaking change is when the hashes change. Bumping the block version is necessary if anything changes related to how CometBFT nodes compute a block, e.g. how the hashes are calculated or which ConsensusParams are included in the hash.

• Network Version indicates a change to the network layer referring, for example, to the p2p messages, serialization, and underlying transport. A Network Breaking change means that a node running v1 will not be able to parse and understand at least one message from a v2 node.

• ABCI Version indicates changes in the boundary between the application and CometBFT predominantly by changes to this interface abci/types/application.go. One needs to also consider that applications may run in process or over a socket. An ABCI Breaking change is when changes are needed by the application in order to function.

• App Version. CometBFT natively tracks the application version to ensure application compatibility, thus an App Breaking change is when the change affects the way the AppHash is derived.

• Go API’s are the set of public functions and structs that other repos can use. This is more specifically for the users of CometBFT as a library. It also overlaps with other forms of versioning (ABCI version for example).

• Backwards compatible means that a node running v2 can “understand” everything from a node running v1.

• Forwards compatible means that a node running v1 can “understand” everything from a node running v2.

• Rolling Upgrade refers to the process whereby nodes can freely upgrade at any time without any consequence to the network.

• Coordinated Upgrade refers to the process whereby all nodes must agree on a height to upgrade and all nodes must switch to the agreed version of software on that height.

• Soft Coordinated Upgrade is like Coordinate Upgrade, however, nodes can upgrade their binaries at a time before the agreed height. Thereby the binary can handle both versions.

• Migration Upgrade is when either application data or CometBFT data must go through a migration between heights. A node going through a migration will have a different app hash afterwards than a node that did not.

• Hard Fork Upgrade is when an entirely new chain is started with a different chain ID. This is usually avoided whenever possible, since it requires changes in front-ends (e.g., Mintscan) and can also pose problems to IBC light clients.

---

Original source for this was a document put together by a prior Tendermint Core team (source).