Using CometBFT - Cosmos Docs

本文介绍如何通过命令行使用 cometbft 程序。它只假设你已经安装了 cometbft 二进制文件，并且对 CometBFT 和 ABCI 有一些基础了解。你可以使用 cometbft --help 查看帮助菜单，使用 cometbft version 查看版本号。

根目录

区块链数据的默认目录是 ~/.cometbft。你可以通过设置环境变量 CMTHOME 来覆盖它。

初始化

运行以下命令初始化根目录：

cometbft init

这会在 $CMTHOME/config 中创建一个新的私钥（priv_validator_key.json）和一个包含对应公钥的创世文件（genesis.json）。这些内容足以在本地运行一个仅含一个验证者的测试网。如需更复杂的初始化，请查看 testnet 命令：

cometbft testnet --help

创世

$CMTHOME/config/ 中的 genesis.json 文件定义了区块链创世时的初始 CometBFT 状态（参见定义）。

字段

genesis_time：区块链启动的正式时间。
chain_id：区块链的 ID。它对每条区块链都必须唯一。 如果你的测试网区块链没有唯一的 chain ID，会遇到很多问题。 ChainID 的长度必须少于 50 个字符。
initial_height：CometBFT 应开始运行的高度。如果区块链正在执行网络升级，从停止时的高度重新开始可以让此前的高度保持唯一性。
consensus_params（参见规范）
- block
  - max_bytes：区块最大大小，单位为字节。
  - max_gas：每个区块的最大 gas。
- evidence
  - max_age_num_blocks：证据的最大保留区块数。其基本计算公式为： MaxAgeDuration /（平均出块时间）。
  - max_age_duration：证据的最大保留时长。它应与应用的“解绑期” 或其他用于处理 Nothing-At-Stake 攻击的类似机制相对应。
  - max_bytes：设置单个区块中可提交证据的最大字节数，应明显小于区块最大字节数上限。
- validator
  - pub_key_types：验证者可使用的公钥类型。
- version
  - app_version：ABCI 应用版本。
validators：初始验证者列表。注意，这一项可能会被应用完全覆盖；也可以显式留空，以表明应用会在 InitChain 时初始化验证者集合。
- pub_key：第一个元素指定密钥类型，使用已采用密钥类型所声明的 PubKeyName。第二个元素是公钥字节。
- power：验证者的投票权重。
- name：验证者名称（可选）。
app_hash：创世时预期的应用哈希（由 ResponseInfo ABCI 消息返回）。如果应用返回的哈希不匹配，CometBFT 会 panic。
app_state：应用状态（例如代币的初始分配）。

:warning: ChainID 对每条区块链都必须唯一。重复使用旧的 chainID 可能导致问题

genesis.json 示例

{
  "genesis_time": "2023-01-21T11:17:42.341227868Z",
  "chain_id": "test-chain-ROp9KF",
  "initial_height": "0",
  "consensus_params": {
    "block": {
      "max_bytes": "22020096",
      "max_gas": "-1",
    },
    "evidence": {
      "max_age_num_blocks": "100000",
      "max_age_duration": "172800000000000",
      "max_bytes": 51200,
    },
    "validator": {
      "pub_key_types": [
        "ed25519"
      ]
    }
  },
  "validators": [
    {
      "address": "B547AB87E79F75A4A3198C57A8C2FDAF8628CB47",
      "pub_key": {
        "type": "tendermint/PubKeyEd25519",
        "value": "P/V6GHuZrb8rs/k1oBorxc6vyXMlnzhJmv7LmjELDys="
      },
      "power": "10",
      "name": ""
    }
  ],
  "app_hash": ""
}

运行

使用以下命令运行一个 CometBFT 节点：

cometbft node

默认情况下，CometBFT 会尝试连接到位于 tcp://127.0.0.1:26658 的 ABCI 应用。如果你已经安装了 kvstore ABCI 应用，请在另一个窗口中运行它。如果没有，请停止 CometBFT，然后运行 kvstore 应用的进程内版本：

cometbft node --proxy_app=kvstore

几秒后，你应该会看到区块开始持续产生。注意，即使没有交易，也会定期生成区块。要修改这个设置，请参见下文的禁用空区块。 CometBFT 支持 counter、kvstore 和 noop 应用的进程内版本，这些示例随 abci-cli 一起提供。如果你的应用是用 Go 编写的，将其以内嵌进程方式与 CometBFT 一起编译会很容易。如果你的应用不是用 Go 编写的，请在另一个进程中运行它，并使用 --proxy_app 标志指定它监听的 socket 地址，例如：

cometbft node --proxy_app=/var/run/abci.sock

你可以通过运行 cometbft node --help 查看支持哪些标志。

交易

要发送交易，请使用 curl 向 CometBFT RPC 服务器发起请求，例如：

curl http://localhost:26657/broadcast_tx_commit?tx=\"abcd\"

我们可以通过 /status 端点查看链的状态：

curl http://localhost:26657/status | json_pp

尤其可以查看 latest_app_hash：

curl http://localhost:26657/status | json_pp | grep latest_app_hash

在浏览器中访问 http://localhost:26657 可以查看其他端点列表。有些端点不需要参数（例如 /status），而另一些会指定参数名，并用 _ 作为占位符。

提示：RPC 文档见这里

格式化

发送/格式化交易时，需要注意以下细节：使用 GET：要发送 UTF8 字符串字节数组，请为 tx 参数的值加上引号：

curl 'http://localhost:26657/broadcast_tx_commit?tx="hello"'

这会发送一个 5 字节的交易：“h e l l o” [68 65 6c 6c 6f]。注意，URL 必须用单引号包裹，否则 bash 会忽略双引号。如果想避免使用单引号，请转义双引号：

curl http://localhost:26657/broadcast_tx_commit?tx=\"hello\"

使用特殊字符：

curl 'http://localhost:26657/broadcast_tx_commit?tx="€5"'

会发送一个 4 字节的交易：“€5”（UTF8）[e2 82 ac 35]。如果要按原始十六进制发送，请去掉引号，并在十六进制字符串前加上 0x：

curl http://localhost:26657/broadcast_tx_commit?tx=0x01020304

这会发送一个 4 字节的交易：[01 02 03 04]。使用 POST（通过 json）时，原始十六进制必须经过 base64 编码：

curl --data-binary '{"jsonrpc":"2.0","id":"anything","method":"broadcast_tx_commit","params": {"tx": "AQIDBA=="}}' -H 'content-type:text/plain;' http://localhost:26657

这会发送同样的 4 字节交易：[01 02 03 04]。注意，在 POST 交易中不能直接使用原始十六进制。

重置

:warning: 不安全 仅在开发环境中这样做，并且仅当你可以承担丢失全部区块链数据的后果时才这样做！

要重置区块链，请先停止节点，然后运行：

cometbft unsafe_reset_all

该命令会删除数据目录，并重置私有验证者文件和地址簿文件。

配置

CometBFT 使用 config.toml 进行配置。详情请参见配置规范。值得注意的选项包括应用的 socket 地址（proxy_app）、CometBFT 对等节点的监听地址（p2p.laddr），以及 RPC 服务器的监听地址（rpc.laddr）。配置文件中的某些字段可以通过标志覆盖。

禁用空区块

虽然 cometbft 的默认行为仍然是大约每秒创建一个区块，但你也可以禁用空区块，或者设置区块创建间隔。前一种情况下，只有在有新交易或 AppHash 发生变化时才会创建区块。如果你希望 CometBFT 仅在存在交易或应用哈希变化时才生成区块，请使用以下附加标志运行 CometBFT：

cometbft node --consensus.create_empty_blocks=false

或者在 config.toml 文件中设置：

[consensus]
create_empty_blocks = false

请记住：由于默认行为是_创建空区块_，要避免空区块，必须将该配置项设为 false。区块间隔设置允许你在每个新空区块创建之间增加延迟（使用 time.Duration 格式，参见 ParseDuration）。可以通过以下附加标志设置：

--consensus.create_empty_blocks_interval="5s"

或者在 config.toml 文件中设置：

[consensus]
create_empty_blocks_interval = "5s"

启用此设置后，如果没有以其他方式生成区块，则每隔 5 秒会生成一个空区块，而不受 create_empty_blocks 值的影响。

Broadcast API

前面我们使用了 broadcast_tx_commit 端点发送交易。当一笔交易被发送到 CometBFT 节点时，它会先通过应用执行 CheckTx。如果通过了 CheckTx，它就会被加入 mempool、广播给其他对等节点，并最终被打包进某个区块。由于交易处理分为多个阶段，我们提供了多个广播交易的端点：

/broadcast_tx_async
/broadcast_tx_sync
/broadcast_tx_commit

它们分别对应不等待处理、处理到 mempool，以及处理到区块提交。也就是说，broadcast_tx_async 会立即返回，而不会等待确认该交易是否有效；broadcast_tx_sync 会在交易通过 CheckTx 后返回对应结果。使用 broadcast_tx_commit 时，会一直等待到交易被提交进区块，或直到达到某个超时时间；但如果交易未通过 CheckTx，它会立即返回。 broadcast_tx_commit 的返回值包含两个字段：check_tx 和 deliver_tx，分别对应交易经过这些 ABCI 消息处理后的结果。使用 broadcast_tx_commit 的好处是，请求会在交易提交后（即被包含进区块后）返回，但这通常需要大约一秒。如果你想更快拿到结果，可以使用 broadcast_tx_sync，不过交易要稍后才会被提交，到那时它对状态的影响可能已经发生变化。请注意，mempool 不提供强保证。交易通过 CheckTx（即被 mempool 接收）并不意味着它一定会被提交，因为持有该交易的节点可能会在轮到自己提议区块前崩溃。更多信息请参见 mempool 预写日志。

CometBFT 网络

当运行 cometbft init 时，~/.cometbft/config 中会同时创建 genesis.json 和 priv_validator_key.json。 genesis.json 可能如下所示：

{
  "validators" : [
    {
      "pub_key" : {
        "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
        "type" : "tendermint/PubKeyEd25519"
      },
      "power" : 10,
      "name" : ""
    }
  ],
  "app_hash" : "",
  "chain_id" : "test-chain-rDlYSN",
  "genesis_time" : "0001-01-01T00:00:00Z"
}

而 priv_validator_key.json 如下：

{
  "last_step" : 0,
  "last_round" : "0",
  "address" : "B788DEDE4F50AD8BC9462DE76741CCAFF87D51E2",
  "pub_key" : {
    "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
    "type" : "tendermint/PubKeyEd25519"
  },
  "last_height" : "0",
  "priv_key" : {
    "value" : "JPivl82x+LfVkp8i3ztoTjY6c6GJ4pBxQexErOCyhwqHeGT5ATxzpAtPJKnxNx/NyUnD8Ebv3OIYH+kgD4N88Q==",
    "type" : "tendermint/PrivKeyEd25519"
  }
}

priv_validator_key.json 实际上包含私钥，因此必须绝对保密；这里只是暂时以明文形式讨论它。注意其中的 last_ 字段，它们用于防止我们对相互冲突的消息签名。还要注意，priv_validator_key.json 中的 pub_key （公钥）同样也存在于 genesis.json 中。创世文件包含允许参与共识的公钥列表，以及它们对应的投票权重。超过 2/3 的投票权重必须处于活跃状态（即对应私钥必须能够产生签名），共识才能继续推进。在我们的例子中，创世文件包含了 priv_validator_key.json 的公钥，因此使用默认根目录启动的 CometBFT 节点能够推进共识。投票权重使用 int64，但必须为正，因此范围是 0 到 9223372036854775807。由于当前提议者选择算法的实现方式，我们不建议将投票权重设置为大于 10^12（即 1 万亿）。如果我们想向网络中添加更多节点，有两种选择：可以添加新的验证者节点，它会通过提议区块和对区块投票来参与共识；也可以添加新的非验证者节点，它不会直接参与，但会验证并跟进共识协议。

对等节点

Seed

Seed 节点是会转发其所知道的其他对等节点地址的节点。这些节点会持续爬取网络以获取更多对等节点。Seed 节点转发的地址会被保存到本地地址簿中。一旦这些地址进入地址簿，你就会直接连接到这些地址。基本上，Seed 节点的职责只是转发所有人的地址。当你获取到足够多的地址后，就不会继续连接 Seed 节点了，因此通常只在第一次启动时需要它们。Seed 节点在向你发送一些地址后，会立即断开连接。

持久对等节点

持久对等节点是你希望始终保持连接的节点。如果连接断开，你会尝试直接重新连接它们，而不是使用地址簿中的其他地址。重启后，无论地址簿大小如何，你都会始终尝试连接这些对等节点。默认情况下，所有对等节点都会转发它们所知道的其他对等节点。这被称为对等交换协议（PEX）。有了 PEX，对等节点会持续传播已知的对等节点信息并形成网络，同时把对等节点地址存储在 addrbook 中。正因如此，如果你已经有一个在线的持久对等节点，就不一定还需要使用 Seed 节点。

连接到对等节点

要在启动时连接到对等节点，请在 $CMTHOME/config/config.toml 或命令行中指定它们。使用 seeds 指定 Seed 节点，使用 persistent_peers 指定你的节点要维持持久连接的对等节点。例如：

cometbft node --p2p.seeds "[email protected]:26656,[email protected]:26656"

另外，你也可以使用 RPC 的 /dial_seeds 端点，为正在运行的节点指定要连接的 Seed：

curl 'localhost:26657/dial_seeds?seeds=\["[email protected]:26656","[email protected]:26656"\]'

注意，在启用 PEX 的情况下，通常在首次启动后就不再需要 Seed。如果你希望 CometBFT 连接到一组固定地址，并与每个地址保持持久连接，可以使用 --p2p.persistent_peers 标志、config.toml 中对应的设置，或 /dial_peers RPC 端点，而无需停止 CometBFT 实例。

cometbft node --p2p.persistent_peers "[email protected]:26656,[email protected]:26656"

curl 'localhost:26657/dial_peers?persistent=true&peers=\["[email protected]:26656","[email protected]:26656"\]'

添加非验证者节点

添加非验证者节点很简单。只需将原始的 genesis.json 复制到新机器上的 ~/.cometbft/config，然后启动节点，并根据需要指定 Seed 或持久对等节点。如果未指定 Seed 或持久对等节点，该节点将不会生成任何区块，因为它不是验证者；同时它也收不到任何区块，因为它没有连接到其他对等节点。

添加验证者

添加新验证者最简单的方法是在网络启动前，直接在 genesis.json 中完成。例如，我们可以生成一个新的 priv_validator_key.json，并把其中的 pub_key 复制到上面的创世文件中。我们可以使用以下命令生成新的 priv_validator_key.json：

cometbft gen_validator

现在我们就可以更新创世文件了。例如，如果新的 priv_validator_key.json 如下所示：

{
  "address" : "5AF49D2A2D4F5AD4C7C8C4CC2FB020131E9C4902",
  "pub_key" : {
    "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
    "type" : "tendermint/PubKeyEd25519"
  },
  "priv_key" : {
    "value" : "EDJY9W6zlAw+su6ITgTKg2nTZcHAH1NMTW5iwlgmNDuX1f35+OR4HMN88ZtQzsAwhETq4k3vzM3n6WTk5ii16Q==",
    "type" : "tendermint/PrivKeyEd25519"
  },
  "last_step" : 0,
  "last_round" : "0",
  "last_height" : "0"
}

那么新的 genesis.json 将会是：

{
  "validators" : [
    {
      "pub_key" : {
        "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
        "type" : "tendermint/PubKeyEd25519"
      },
      "power" : 10,
      "name" : ""
    },
    {
      "pub_key" : {
        "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
        "type" : "cometbft/PubKeyEd25519"
      },
      "power" : 10,
      "name" : ""
    }
  ],
  "app_hash" : "",
  "chain_id" : "test-chain-rDlYSN",
  "genesis_time" : "0001-01-01T00:00:00Z"
}

更新 ~/.cometbft/config 中的 genesis.json。然后将该创世文件和新的 priv_validator_key.json 复制到新机器上的 ~/.cometbft/config。现在在两台机器上都运行 cometbft node，并使用 --p2p.persistent_peers 或 /dial_peers 让它们建立对等连接。它们应该会开始生成区块，并且只有在两台机器都在线时才会继续。如果你希望 CometBFT 网络在一个验证者失效时仍能容错，则至少需要四个验证者节点（例如满足 2/3）。支持在运行中的网络里更新验证者，但这必须由应用开发者显式编程实现。更多细节请参见应用开发者指南。

本地网络

如果要在本地运行一个网络，例如在单台机器上运行，你必须修改 config.toml 中的 _laddr 字段（或使用对应标志），以避免不同 socket 的监听地址发生冲突。此外，你还必须在 config.toml 中设置 addr_book_strict=false，否则 CometBFT 的 p2p 库会拒绝与具有相同 IP 地址的对等节点建立连接。

升级

请参见 UPGRADING.md 指南。在重大破坏性版本之间，你可能需要重置链。不过，我们预计未来 CometBFT 的破坏性版本会更少，尤其是在 1.0 发布之后。

This is a guide to using the cometbft program from the command line. It assumes only that you have the cometbft binary installed and have some rudimentary idea of what CometBFT and ABCI are. You can see the help menu with cometbft --help, and the version number with cometbft version.

Directory Root

The default directory for blockchain data is ~/.cometbft. Override this by setting the CMTHOME environment variable.

Initialize

Initialize the root directory by running:

cometbft init

This will create a new private key (priv_validator_key.json) and a genesis file (genesis.json) containing the associated public key in $CMTHOME/config. This is all that’s necessary to run a local testnet with one validator. For more elaborate initialization, see the testnet command:

cometbft testnet --help

Genesis

The genesis.json file in $CMTHOME/config/ defines the initial CometBFT state upon genesis of the blockchain (see definition).

Fields

genesis_time: Official time of blockchain start.
chain_id: ID of the blockchain. This must be unique for every blockchain. If your testnet blockchains do not have unique chain IDs, you will have a bad time. The ChainID must be less than 50 symbols.
initial_height: Height at which CometBFT should begin. If a blockchain is conducting a network upgrade, starting from the stopped height brings uniqueness to previous heights.
consensus_params (see spec)
- block
  - max_bytes: Max block size, in bytes.
  - max_gas: Max gas per block.
- evidence
  - max_age_num_blocks: Max age of evidence, in blocks. The basic formula for calculating this is: MaxAgeDuration / (average block time).
  - max_age_duration: Max age of evidence, in time. It should correspond with an app’s “unbonding period” or other similar mechanism for handling Nothing-At-Stake attacks.
  - max_bytes: This sets the maximum size in bytes of evidence that can be committed in a single block and should fall comfortably under the max block bytes.
- validator
  - pub_key_types: Public key types validators can use.
- version
  - app_version: ABCI application version.
validators: List of initial validators. Note this may be overridden entirely by the application, and may be left empty to make explicit that the application will initialize the validator set upon InitChain.
- pub_key: The first element specifies the key type, using the declared PubKeyName for the adopted key type. The second element are the pubkey bytes.
- power: The validator’s voting power.
- name: Name of the validator (optional).
app_hash: The expected application hash (as returned by the ResponseInfo ABCI message) upon genesis. If the app’s hash does not match, CometBFT will panic.
app_state: The application state (e.g., initial distribution of tokens).

:warning: ChainID must be unique to every blockchain. Reusing old chainID can cause issues

Sample genesis.json

{
  "genesis_time": "2023-01-21T11:17:42.341227868Z",
  "chain_id": "test-chain-ROp9KF",
  "initial_height": "0",
  "consensus_params": {
    "block": {
      "max_bytes": "22020096",
      "max_gas": "-1",
    },
    "evidence": {
      "max_age_num_blocks": "100000",
      "max_age_duration": "172800000000000",
      "max_bytes": 51200,
    },
    "validator": {
      "pub_key_types": [
        "ed25519"
      ]
    }
  },
  "validators": [
    {
      "address": "B547AB87E79F75A4A3198C57A8C2FDAF8628CB47",
      "pub_key": {
        "type": "tendermint/PubKeyEd25519",
        "value": "P/V6GHuZrb8rs/k1oBorxc6vyXMlnzhJmv7LmjELDys="
      },
      "power": "10",
      "name": ""
    }
  ],
  "app_hash": ""
}

Run

To run a CometBFT node, use:

cometbft node

By default, CometBFT will try to connect to an ABCI application on tcp://127.0.0.1:26658. If you have the kvstore ABCI app installed, run it in another window. If you don’t, kill CometBFT and run an in-process version of the kvstore app:

cometbft node --proxy_app=kvstore

After a few seconds, you should see blocks start streaming in. Note that blocks are produced regularly, even if there are no transactions. See No Empty Blocks below to modify this setting. CometBFT supports in-process versions of the counter, kvstore, and noop apps that ship as examples with abci-cli. It’s easy to compile your app in-process with CometBFT if it’s written in Go. If your app is not written in Go, run it in another process, and use the --proxy_app flag to specify the address of the socket it is listening on, for instance:

cometbft node --proxy_app=/var/run/abci.sock

You can find out what flags are supported by running cometbft node --help.

Transactions

To send a transaction, use curl to make requests to the CometBFT RPC server, for example:

curl http://localhost:26657/broadcast_tx_commit?tx=\"abcd\"

We can see the chain’s status at the /status endpoint:

curl http://localhost:26657/status | json_pp

and the latest_app_hash in particular:

curl http://localhost:26657/status | json_pp | grep latest_app_hash

Visit http://localhost:26657 in your browser to see the list of other endpoints. Some take no arguments (like /status), while others specify the argument name and use _ as a placeholder.

TIP: Find the RPC Documentation here

Formatting

The following nuances when sending/formatting transactions should be taken into account: With GET: To send a UTF8 string byte array, quote the value of the tx parameter:

curl 'http://localhost:26657/broadcast_tx_commit?tx="hello"'

which sends a 5 byte transaction: “h e l l o” [68 65 6c 6c 6f]. Note the URL must be wrapped with single quotes, else bash will ignore the double quotes. To avoid the single quotes, escape the double quotes:

curl http://localhost:26657/broadcast_tx_commit?tx=\"hello\"

Using a special character:

curl 'http://localhost:26657/broadcast_tx_commit?tx="€5"'

sends a 4 byte transaction: “€5” (UTF8) [e2 82 ac 35]. To send as raw hex, omit quotes AND prefix the hex string with 0x:

curl http://localhost:26657/broadcast_tx_commit?tx=0x01020304

which sends a 4 byte transaction: [01 02 03 04]. With POST (using json), the raw hex must be base64 encoded:

curl --data-binary '{"jsonrpc":"2.0","id":"anything","method":"broadcast_tx_commit","params": {"tx": "AQIDBA=="}}' -H 'content-type:text/plain;' http://localhost:26657

which sends the same 4 byte transaction: [01 02 03 04]. Note that raw hex cannot be used in POST transactions.

Reset

:warning: UNSAFE Only do this in development and only if you can afford to lose all blockchain data!

To reset a blockchain, stop the node and run:

cometbft unsafe_reset_all

This command will remove the data directory and reset private validator and address book files.

Configuration

CometBFT uses a config.toml for configuration. For details, see the config specification. Notable options include the socket address of the application (proxy_app), the listening address of the CometBFT peer (p2p.laddr), and the listening address of the RPC server (rpc.laddr). Some fields from the config file can be overwritten with flags.

No Empty Blocks

While the default behavior of cometbft is still to create blocks approximately once per second, it is possible to disable empty blocks or set a block creation interval. In the former case, blocks will be created when there are new transactions or when the AppHash changes. To configure CometBFT to not produce empty blocks unless there are transactions or the app hash changes, run CometBFT with this additional flag:

cometbft node --consensus.create_empty_blocks=false

or set the configuration via the config.toml file:

[consensus]
create_empty_blocks = false

Remember: because the default is to create empty blocks, avoiding empty blocks requires the config option to be set to false. The block interval setting allows for a delay (in time.Duration format ParseDuration) between the creation of each new empty block. It can be set with this additional flag:

--consensus.create_empty_blocks_interval="5s"

or set the configuration via the config.toml file:

[consensus]
create_empty_blocks_interval = "5s"

With this setting, empty blocks will be produced every 5s if no block has been produced otherwise, regardless of the value of create_empty_blocks.

Broadcast API

Earlier, we used the broadcast_tx_commit endpoint to send a transaction. When a transaction is sent to a CometBFT node, it will run via CheckTx against the application. If it passes CheckTx, it will be included in the mempool, broadcast to other peers, and eventually included in a block. Since there are multiple phases to processing a transaction, we offer multiple endpoints to broadcast a transaction:

/broadcast_tx_async
/broadcast_tx_sync
/broadcast_tx_commit

These correspond to no-processing, processing through the mempool, and processing through a block, respectively. That is, broadcast_tx_async will return right away without waiting to hear if the transaction is even valid, while broadcast_tx_sync will return with the result of running the transaction through CheckTx. Using broadcast_tx_commit will wait until the transaction is committed in a block or until some timeout is reached, but will return right away if the transaction does not pass CheckTx. The return value for broadcast_tx_commit includes two fields, check_tx and deliver_tx, pertaining to the result of running the transaction through those ABCI messages. The benefit of using broadcast_tx_commit is that the request returns after the transaction is committed (i.e., included in a block), but that can take on the order of a second. For a quick result, use broadcast_tx_sync, but the transaction will not be committed until later, and by that point its effect on the state may change. Note the mempool does not provide strong guarantees - just because a tx passed CheckTx (i.e., was accepted into the mempool) doesn’t mean it will be committed, as nodes with the tx in their mempool may crash before they get to propose. For more information, see the mempool write-ahead-log.

CometBFT Networks

When cometbft init is run, both a genesis.json and priv_validator_key.json are created in ~/.cometbft/config. The genesis.json might look like:

{
  "validators" : [
    {
      "pub_key" : {
        "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
        "type" : "tendermint/PubKeyEd25519"
      },
      "power" : 10,
      "name" : ""
    }
  ],
  "app_hash" : "",
  "chain_id" : "test-chain-rDlYSN",
  "genesis_time" : "0001-01-01T00:00:00Z"
}

And the priv_validator_key.json:

{
  "last_step" : 0,
  "last_round" : "0",
  "address" : "B788DEDE4F50AD8BC9462DE76741CCAFF87D51E2",
  "pub_key" : {
    "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
    "type" : "tendermint/PubKeyEd25519"
  },
  "last_height" : "0",
  "priv_key" : {
    "value" : "JPivl82x+LfVkp8i3ztoTjY6c6GJ4pBxQexErOCyhwqHeGT5ATxzpAtPJKnxNx/NyUnD8Ebv3OIYH+kgD4N88Q==",
    "type" : "tendermint/PrivKeyEd25519"
  }
}

The priv_validator_key.json actually contains a private key, and should thus be kept absolutely secret; for now we work with the plain text. Note the last_ fields, which are used to prevent us from signing conflicting messages. Note also that the pub_key (the public key) in the priv_validator_key.json is also present in the genesis.json. The genesis file contains the list of public keys which may participate in the consensus, and their corresponding voting power. Greater than 2/3 of the voting power must be active (i.e., the corresponding private keys must be producing signatures) for the consensus to make progress. In our case, the genesis file contains the public key of our priv_validator_key.json, so a CometBFT node started with the default root directory will be able to make progress. Voting power uses an int64 but must be positive, thus the range is 0 through 9223372036854775807. Because of how the current proposer selection algorithm works, we do not recommend having voting powers greater than 10^12 (i.e., 1 trillion). If we want to add more nodes to the network, we have two choices: we can add a new validator node, who will also participate in the consensus by proposing blocks and voting on them, or we can add a new non-validator node, who will not participate directly, but will verify and keep up with the consensus protocol.

Peers

Seed

A seed node is a node who relays the addresses of other peers which they know of. These nodes constantly crawl the network to try to get more peers. The addresses which the seed node relays get saved into a local address book. Once these are in the address book, you will connect to those addresses directly. Basically the seed node’s job is just to relay everyone’s addresses. You won’t connect to seed nodes once you have received enough addresses, so typically you only need them on the first start. The seed node will immediately disconnect from you after sending you some addresses.

Persistent Peer

Persistent peers are people you want to be constantly connected with. If you disconnect you will try to connect directly back to them as opposed to using another address from the address book. On restarts you will always try to connect to these peers regardless of the size of your address book. All peers relay peers they know of by default. This is called the peer exchange protocol (PEX). With PEX, peers will be gossiping about known peers and forming a network, storing peer addresses in the addrbook. Because of this, you don’t have to use a seed node if you have a live persistent peer.

Connecting to Peers

To connect to peers on start-up, specify them in the $CMTHOME/config/config.toml or on the command line. Use seeds to specify seed nodes, and persistent_peers to specify peers that your node will maintain persistent connections with. For example,

cometbft node --p2p.seeds "[email protected]:26656,[email protected]:26656"

Alternatively, you can use the /dial_seeds endpoint of the RPC to specify seeds for a running node to connect to:

curl 'localhost:26657/dial_seeds?seeds=\["[email protected]:26656","[email protected]:26656"\]'

Note, with PEX enabled, you should not need seeds after the first start. If you want CometBFT to connect to a specific set of addresses and maintain a persistent connection with each, you can use the --p2p.persistent_peers flag or the corresponding setting in the config.toml or the /dial_peers RPC endpoint to do it without stopping the CometBFT instance.

cometbft node --p2p.persistent_peers "[email protected]:26656,[email protected]:26656"

curl 'localhost:26657/dial_peers?persistent=true&peers=\["[email protected]:26656","[email protected]:26656"\]'

Adding a Non-Validator

Adding a non-validator is simple. Just copy the original genesis.json to ~/.cometbft/config on the new machine and start the node, specifying seeds or persistent peers as necessary. If no seeds or persistent peers are specified, the node won’t make any blocks, because it’s not a validator, and it won’t hear about any blocks, because it’s not connected to the other peer.

Adding a Validator

The easiest way to add new validators is to do it in the genesis.json before starting the network. For instance, we could make a new priv_validator_key.json and copy its pub_key into the above genesis. We can generate a new priv_validator_key.json with the command:

cometbft gen_validator

Now we can update our genesis file. For instance, if the new priv_validator_key.json looks like:

{
  "address" : "5AF49D2A2D4F5AD4C7C8C4CC2FB020131E9C4902",
  "pub_key" : {
    "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
    "type" : "tendermint/PubKeyEd25519"
  },
  "priv_key" : {
    "value" : "EDJY9W6zlAw+su6ITgTKg2nTZcHAH1NMTW5iwlgmNDuX1f35+OR4HMN88ZtQzsAwhETq4k3vzM3n6WTk5ii16Q==",
    "type" : "tendermint/PrivKeyEd25519"
  },
  "last_step" : 0,
  "last_round" : "0",
  "last_height" : "0"
}

then the new genesis.json will be:

{
  "validators" : [
    {
      "pub_key" : {
        "value" : "h3hk+QE8c6QLTySp8TcfzclJw/BG79ziGB/pIA+DfPE=",
        "type" : "tendermint/PubKeyEd25519"
      },
      "power" : 10,
      "name" : ""
    },
    {
      "pub_key" : {
        "value" : "l9X9+fjkeBzDfPGbUM7AMIRE6uJN78zN5+lk5OYotek=",
        "type" : "cometbft/PubKeyEd25519"
      },
      "power" : 10,
      "name" : ""
    }
  ],
  "app_hash" : "",
  "chain_id" : "test-chain-rDlYSN",
  "genesis_time" : "0001-01-01T00:00:00Z"
}

Update the genesis.json in ~/.cometbft/config. Copy the genesis file and the new priv_validator_key.json to the ~/.cometbft/config on a new machine. Now run cometbft node on both machines, and use either --p2p.persistent_peers or the /dial_peers to get them to peer up. They should start making blocks, and will only continue to do so as long as both of them are online. To make a CometBFT network that can tolerate one of the validators failing, you need at least four validator nodes (e.g., 2/3). Updating validators in a live network is supported but must be explicitly programmed by the application developer. See the application developers guide for more details.

Local Network

To run a network locally, say on a single machine, you must change the _laddr fields in the config.toml (or using the flags) so that the listening addresses of the various sockets don’t conflict. Additionally, you must set addr_book_strict=false in the config.toml, otherwise CometBFT’s p2p library will deny making connections to peers with the same IP address.

Upgrading

See the UPGRADING.md guide. You may need to reset your chain between major breaking releases. Although, we expect CometBFT to have fewer breaking releases in the future (especially after the 1.0 release).

​根目录

​初始化

​创世

​字段

​genesis.json 示例

​运行

​交易

​格式化

​重置

​配置

​禁用空区块

​Broadcast API

​CometBFT 网络

​对等节点

​Seed

​持久对等节点

​连接到对等节点

​添加非验证者节点

​添加验证者

​本地网络

​升级

​Directory Root

​Initialize

​Genesis

​Fields

​Sample genesis.json

​Run

​Transactions

​Formatting

​Reset

​Configuration

​No Empty Blocks

​Broadcast API

​CometBFT Networks

​Peers

​Seed

​Persistent Peer

​Connecting to Peers

​Adding a Non-Validator

​Adding a Validator

​Local Network

​Upgrading

根目录

初始化

创世

字段

genesis.json 示例

运行

交易

格式化

重置

配置

禁用空区块

Broadcast API

CometBFT 网络

对等节点

Seed

持久对等节点

连接到对等节点

添加非验证者节点

添加验证者

本地网络

升级

Directory Root

Initialize

Genesis

Fields

Sample genesis.json

Run

Transactions

Formatting

Reset

Configuration

No Empty Blocks

Broadcast API

CometBFT Networks

Peers

Seed

Persistent Peer

Connecting to Peers

Adding a Non-Validator

Adding a Validator

Local Network

Upgrading