|
| 1 | +[NB]: # ( |
| 2 | + Ensure that all hyperlinks in this doc are absolute URLs, not relative ones, |
| 3 | + as this doc gets published to the Buf registry and relative URLs will fail |
| 4 | + to resolve. |
| 5 | +) |
| 6 | + |
| 7 | +# CometBFT Protocol Buffers Definitions |
| 8 | + |
| 9 | +This is the set of [Protobuf][protobuf] definitions of types used by various |
| 10 | +parts of [CometBFT]: |
| 11 | + |
| 12 | +- The [Application Blockchain Interface][abci] (ABCI), especially in the context |
| 13 | + of _remote_ applications. |
| 14 | +- The P2P layer, in how CometBFT nodes interact with each other over the |
| 15 | + network. |
| 16 | +- In interaction with remote signers ("privval"). |
| 17 | +- The RPC, in that the native JSON serialization of certain Protobuf types is |
| 18 | + used when accepting and responding to RPC requests. |
| 19 | +- The storage layer, in how data is serialized to and deserialized from on-disk |
| 20 | + storage. |
| 21 | + |
| 22 | +The canonical Protobuf definitions live in the `proto` folder of the relevant |
| 23 | +release branch of CometBFT. These definitions are published to the [Buf |
| 24 | +registry][buf] for integrators' convenience. For detailed instructions on how to publish |
| 25 | +the files to the Buf registry, please refer to the [RELEASES.md](../RELEASES.md) document. |
| 26 | + |
| 27 | +The Protobuf files are organized under two domains: `cometbft` and `tendermint`. |
| 28 | +The `cometbft.*` packages use version suffixes to let application developers |
| 29 | +target versions of the protocols as they have evolved between CometBFT releases. |
| 30 | + |
| 31 | +## Which CometBFT release does each package belong to? |
| 32 | + |
| 33 | +By the 1.0.0 release, the entire set of Protobuf definitions used by CometBFT |
| 34 | +is published in packages suffixed with `.v1`. Earlier revisions of the |
| 35 | +definitions, where they differed, are provided alongside in `.v1beta`_N_ |
| 36 | +packages. The correspondence between package suffixes and releases is as follows: |
| 37 | + |
| 38 | +| Domain | 0.34 | 0.37 | 0.38 | 1.0 | |
| 39 | +|-----------------|-----------|-----------|-----------|------| |
| 40 | +| `abci` | `v1beta1` | `v1beta2` | `v1beta3` | `v1` | |
| 41 | +| `blocksync` | | `v1beta1` | `v1` | `v1` | |
| 42 | +| `consensus` | `v1beta1` | `v1beta1` | `v1beta1` | `v1` | |
| 43 | +| `crypto` | `v1` | `v1` | `v1` | `v1` | |
| 44 | +| `libs/bits` | `v1` | `v1` | `v1` | `v1` | |
| 45 | +| `mempool` | `v1` | `v1` | `v1` | `v1` | |
| 46 | +| `p2p` | `v1` | `v1` | `v1` | `v1` | |
| 47 | +| `privval` | `v1beta1` | `v1beta1` | `v1beta2` | `v1` | |
| 48 | +| `rpc/grpc`[^1] | `v1beta1` | `v1beta2` | `v1beta3` | | |
| 49 | +| `state` | `v1beta1` | `v1beta2` | `v1beta3` | `v1` | |
| 50 | +| `statesync` | `v1` | `v1` | `v1` | `v1` | |
| 51 | +| `types` | `v1beta1` | `v1beta2` | `v1` | `v1` | |
| 52 | +| `version` | `v1` | `v1` | `v1` | `v1` | |
| 53 | + |
| 54 | +[^1]: Retired in 1.0 |
| 55 | + |
| 56 | +## Why does CometBFT provide `tendermint` Protobuf definitions? |
| 57 | + |
| 58 | +This is as a result of CometBFT being a fork of [Tendermint Core][tmcore] and |
| 59 | +wanting to provide integrators with as painless a way as possible of |
| 60 | +transitioning from Tendermint Core to CometBFT. |
| 61 | + |
| 62 | +As of CometBFT v1, however, the project will transition to using and providing a |
| 63 | +`cometbft` package of Protobuf definitions (see [\#1330]). |
| 64 | + |
| 65 | +Protobuf definitions for each respective release are also, for convenience, |
| 66 | +published to a corresponding branch in the `tendermint/tendermint` Buf repository. |
| 67 | + |
| 68 | +| CometBFT version | Canonical Protobufs | Buf registry | |
| 69 | +|------------------|---------------------------------------------|-------------------------------------------| |
| 70 | +| v0.38.x | [v0.38.x Protobuf definitions][v038-protos] | [Buf repository v0.38.x branch][v038-buf] | |
| 71 | +| v0.37.x | [v0.37.x Protobuf definitions][v037-protos] | [Buf repository v0.37.x branch][v037-buf] | |
| 72 | +| v0.34.x | [v0.34.x Protobuf definitions][v034-protos] | [Buf repository v0.34.x branch][v034-buf] | |
| 73 | + |
| 74 | +[protobuf]: https://protobuf.dev/ |
| 75 | +[CometBFT]: https://github.com/cometbft/cometbft |
| 76 | +[abci]: https://github.com/cometbft/cometbft/tree/main/spec/abci |
| 77 | +[buf]: https://buf.build/tendermint/tendermint |
| 78 | +[tmcore]: https://github.com/tendermint/tendermint |
| 79 | +[\#1330]: https://github.com/cometbft/cometbft/issues/1330 |
| 80 | +[v034-protos]: https://github.com/cometbft/cometbft/tree/v0.34.x/proto |
| 81 | +[v034-buf]: https://buf.build/tendermint/tendermint/docs/v0.34.x |
| 82 | +[v037-protos]: https://github.com/cometbft/cometbft/tree/v0.37.x/proto |
| 83 | +[v037-buf]: https://buf.build/tendermint/tendermint/docs/v0.37.x |
| 84 | +[v038-protos]: https://github.com/cometbft/cometbft/tree/v0.38.x/proto |
| 85 | +[v038-buf]: https://buf.build/tendermint/tendermint/docs/v0.38.x |
0 commit comments