Methods - Cosmos Docs

ABCI 中现有的方法

Echo

请求:
- Message (string): 要回显的字符串
响应:
- Message (string): 输入字符串
用法:
- 回显一个字符串，以测试 ABCI 客户端/服务端实现

Flush

用法:
- 表示应将客户端中排队的消息刷新并发送到服务端。客户端实现会周期性调用它，以确保异步请求实际被发送；也会立即调用它来发起同步请求，该请求会在收到 Flush 响应后返回。

Info

请求:
名称类型描述字段编号
version string CometBFT 软件的语义版本 1
block_version uint64 CometBFT Block 版本 2
p2p_version uint64 CometBFT P2P 版本 3
abci_version string CometBFT ABCI 语义版本 4

名称	类型	描述	字段编号
version	string	CometBFT 软件的语义版本	1
block_version	uint64	CometBFT Block 版本	2
p2p_version	uint64	CometBFT P2P 版本	3
abci_version	string	CometBFT ABCI 语义版本	4

响应:

名称	类型	描述	字段编号	确定性
data	string	任意信息	1	N/A
version	string	应用软件的语义版本	2	N/A
app_version	uint64	应用版本	3	N/A
last_block_height	int64	应用持久化其状态时对应的最新高度	4	N/A
last_block_app_hash	bytes	`FinalizeBlock` 返回的最新 AppHash	5	N/A

用法:
- 返回有关应用状态的信息。
- 用于在启动或恢复时发生的握手过程中，将 CometBFT 与应用进行同步。
- 返回的 app_version 会包含在每个区块的 Header 中。
- CometBFT 期望在 Commit 期间更新并持久化 last_block_app_hash 和 last_block_height。

注意：语义版本指的是 semantic versioning。Info 中的语义版本会显示为 X.X.x。

InitChain

请求:

名称	类型	描述	字段编号
time	google.protobuf.Timestamp	创世时间	1
chain_id	string	区块链的 ID。	2
consensus_params	ConsensusParams	初始的共识关键参数。	3
validators	repeated ValidatorUpdate	初始创世验证者，按投票权排序。	4
app_state_bytes	bytes	序列化后的初始应用状态，JSON 字节。	5
initial_height	int64	初始区块高度（通常为 `1`）。	6

响应:

名称	类型	描述	字段编号	确定性
consensus_params	ConsensusParams	初始的共识关键参数（可选）	1	是
validators	repeated ValidatorUpdate	初始验证者集合（可选）。	2	是
app_hash	bytes	初始应用哈希。	3	是

用法:
- 在创世时调用一次。
- 如果 ResponseInitChain.Validators 为空，则初始验证者集合将采用 RequestInitChain.Validators。
- 如果 ResponseInitChain.Validators 非空，则它将作为初始验证者集合（无论 RequestInitChain.Validators 中是什么）。
- 这使应用能够决定是接受 CometBFT 提议的初始验证者集合（即创世文件中的集合），还是使用不同的集合（可能基于创世文件中的某些应用特定信息计算得到）。
- RequestInitChain.Validators 和 ResponseInitChain.Validators 都是 ValidatorUpdate 结构体。因此，从技术上讲，它们都是在从空集合开始对验证者集合进行“更新”。

Query

请求:

名称	类型	描述	字段编号
data	bytes	供应用解释的请求参数，其语义类似于 URI query component。可与 `path` 配合使用，或替代 `path`。	1
path	string	供应用解释的请求路径，其语义类似于例如路由中的 URI path component。可与 `data` 配合使用，或替代 `data`。应用 MUST 将 `"/store"` 或任何以 `"/store/"` 开头的路径解释为对底层存储按键查询，此时 SHOULD 在 `data` 中指定键。应用 SHOULD 允许对特定类型进行查询，例如 `/accounts/...` 或 `/votes/...`。	2
height	int64	要查询的区块高度（默认值 `0` 返回最新已提交区块的数据）。注意，这里的高度是包含应用 Merkle 根哈希的区块高度，它表示的是在提交 Height-1 区块之后的状态。	3
prove	bool	如果可能，在响应中返回 Merkle 证明。	4

响应:

名称	类型	描述	字段编号	确定性
code	uint32	响应码。	1	N/A
log	string	应用日志记录器的输出。	3	N/A
info	string	附加信息。	4	N/A
index	int64	该键在树中的索引。	5	N/A
key	bytes	匹配数据的键。	6	N/A
value	bytes	匹配数据的值。	7	N/A
proof_ops	ProofOps	如果请求了证明，则为值数据的序列化证明，可针对给定 Height 的 `app_hash` 进行验证。	8	N/A
height	int64	数据来源的区块高度。注意，这里的高度是包含应用 Merkle 根哈希的区块高度，它表示的是在提交 Height-1 区块之后的状态。	9	N/A
codespace	string	`code` 的命名空间。	10	N/A

用法:
- 在当前高度或历史高度向应用查询数据。
- 可选地返回 Merkle 证明。
- Merkle 证明包含自描述的 type 字段，以支持多种 Merkle 树类型和编码格式。

CheckTx

请求:

名称	类型	描述	字段编号
tx	bytes	请求中的交易字节	1
type	CheckTxType	`CheckTx_New` 或 `CheckTx_Recheck` 之一。`CheckTx_New` 是默认值，表示需要对交易进行完整检查。`CheckTx_Recheck` 用于内存池对交易发起常规重新检查时。	2

响应:

名称	类型	描述	字段编号	确定性
code	uint32	响应码。	1	N/A
data	bytes	结果字节（如果有）。	2	N/A
log	string	应用日志记录器的输出。	3	N/A
info	string	附加信息。	4	N/A
gas_wanted	int64	交易请求的 gas 数量。	5	N/A
gas_used	int64	交易消耗的 gas 数量。	6	N/A
events	repeated Event	用于索引交易的类型与键值事件（例如按账户索引）。	7	N/A
codespace	string	`code` 的命名空间。	8	N/A

用法:
- 从技术上讲是可选的，不参与区块处理。
- 内存池的守门人：每个节点都会在允许交易进入本地 mempool 之前运行 CheckTx。
- 交易可能来自外部用户，也可能来自其他节点。
- CheckTx 会根据应用当前状态验证交易，例如检查签名和账户余额，但不会应用交易描述的任何状态变更。
- 当 ResponseCheckTx.Code != 0 时，交易会被拒绝，不会广播给其他节点，也不会包含在提议区块中。 CometBFT 不对该响应码赋予其他含义。

Commit

参数与类型

请求: Commit 表示通知应用持久化应用状态。它不接收任何参数。
响应:
名称类型描述字段编号确定性
retain_height int64 低于该高度的区块可以被移除。默认值为 0（全部保留）。 3 否
用法:
- 通知应用持久化应用状态。预期应用会在此次调用结束时、调用 ResponseCommit 之前持久化其状态。
- 请谨慎使用 ResponseCommit.retain_height！如果网络中的所有节点都删除历史区块，那么这些数据将永久丢失，除非链上启用了状态同步，否则新节点将无法加入网络并完成引导。历史区块也可能用于其他目的，例如审计、重放未持久化高度、轻客户端验证等。

名称	类型	描述	字段编号	确定性
retain_height	int64	低于该高度的区块可以被移除。默认值为 `0`（全部保留）。	3	否

ListSnapshots

请求: 空请求，要求应用返回快照列表。
响应:
名称类型描述字段编号确定性
snapshots repeated Snapshot 本地状态快照列表。 1 N/A
用法:
- 在状态同步期间用于发现对等节点上可用的快照。
- 详情见 Snapshot 数据类型。

名称	类型	描述	字段编号	确定性
snapshots	repeated Snapshot	本地状态快照列表。	1	N/A

LoadSnapshotChunk

请求:
名称类型描述字段编号
height uint64 该分块所属快照的高度。 1
format uint32 该分块所属快照的应用特定格式。 2
chunk uint32 分块索引，从初始分块的 0 开始。 3
响应:
名称类型描述字段编号确定性
chunk bytes 任意格式的二进制分块内容。分块消息大小不能超过 16 MB（包括元数据），因此 10 MB 是一个不错的起点。 1 N/A
用法:
- 在状态同步期间用于从对等节点检索快照分块。

名称	类型	描述	字段编号
height	uint64	该分块所属快照的高度。	1
format	uint32	该分块所属快照的应用特定格式。	2
chunk	uint32	分块索引，从初始分块的 `0` 开始。	3

名称	类型	描述	字段编号	确定性
chunk	bytes	任意格式的二进制分块内容。分块消息大小不能超过 16 MB（包括元数据），因此 10 MB 是一个不错的起点。	1	N/A

OfferSnapshot

请求:
名称类型描述字段编号
snapshot Snapshot 提供用于恢复的快照。 1
app_hash bytes 该高度对应、来自区块链并经轻客户端验证的 app hash。 2
响应:
名称类型描述字段编号确定性
result Result 快照提供的处理结果。 1 N/A

名称	类型	描述	字段编号
snapshot	Snapshot	提供用于恢复的快照。	1
app_hash	bytes	该高度对应、来自区块链并经轻客户端验证的 app hash。	2

名称	类型	描述	字段编号	确定性
result	Result	快照提供的处理结果。	1	N/A

Result

  enum Result {
    UNKNOWN       = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT        = 1;  // Snapshot is accepted, start applying chunks.
    ABORT         = 2;  // Abort snapshot restoration, and don't try any other snapshots.
    REJECT        = 3;  // Reject this specific snapshot, try others.
    REJECT_FORMAT = 4;  // Reject all snapshots with this `format`, try others.
    REJECT_SENDER = 5;  // Reject all snapshots from all senders of this snapshot, try others.
  }

用法:
- 使用状态同步为节点引导时会调用 OfferSnapshot。应用可以按需接受或拒绝快照。接受后，CometBFT 将通过 ApplySnapshotChunk 获取并应用快照分块。应用也可以选择在分块响应阶段拒绝某个快照，此时它应准备好接受后续的 OfferSnapshot 调用。
- 只有 AppHash 可以被信任，因为它已经过轻客户端验证。其他任何数据都可能被对手伪造，因此应用应采用额外的校验机制，以避免拒绝服务攻击。已验证的 AppHash 会在快照恢复结束时自动与恢复后的应用进行校验。
- 更多信息请参见 Snapshot 数据类型或状态同步章节。

ApplySnapshotChunk

请求:

名称	类型	描述	字段编号
index	uint32	分块索引，从 `0` 开始。CometBFT 按顺序应用分块。	1
chunk	bytes	二进制分块内容，由 `LoadSnapshotChunk` 返回。	2
sender	string	发送该分块的节点的 P2P ID。	3

响应:

名称	类型	描述	字段编号	确定性
result	Result (see below)	应用该分块的结果。	1	N/A
refetch_chunks	repeated uint32	无论 `result` 如何，都重新获取并重新应用给定分块。只会重新获取列出的分块，并按顺序重新应用。	2	N/A
reject_senders	repeated string	无论 `Result` 如何，都拒绝给定的 P2P 发送者。已应用的分块不会被重新获取，除非显式请求；但来自这些发送者的排队分块会被丢弃，新的分块或其他快照也会被拒绝。	3	N/A

  enum Result {
    UNKNOWN         = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT          = 1;  // The chunk was accepted.
    ABORT           = 2;  // Abort snapshot restoration, and don't try any other snapshots.
    RETRY           = 3;  // Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate.
    RETRY_SNAPSHOT  = 4;  // Restart this snapshot from `OfferSnapshot`, reusing chunks unless instructed otherwise.
    REJECT_SNAPSHOT = 5;  // Reject this snapshot, try a different one.
  }

用法:
- 应用可以按需选择重新获取分块和/或封禁 P2P 对等节点。除非应用明确指示，否则 CometBFT 不会这样做。
- 应用可能希望验证每个分块，例如在 Snapshot.Metadata 中附加分块哈希，和/或针对 AppHash 增量校验内容。
- 当所有分块都被接受后，CometBFT 会发起一次 ABCI Info 调用，以验证 LastBlockAppHash 和 LastBlockHeight 是否与预期值一致，并将 AppVersion 记录到节点状态中。随后它会切换到区块同步或共识流程并加入网络。
- 如果 CometBFT 在一段时间后仍无法获取下一个分块（例如因为没有合适的对等节点可用），它会拒绝该快照，并通过 OfferSnapshot 尝试另一个快照。应用应准备好按需重置并接受它，或中止流程。

ABCI 2.0 中引入的新方法

PrepareProposal

参数与类型

请求:

名称	类型	描述	字段编号
max_tx_bytes	int64	当前配置下，修改后交易总共允许占用的最大字节数。	1
txs	repeated bytes	作为待提议区块一部分而初步选出的交易列表。	2
local_last_commit	ExtendedCommitInfo	从 CometBFT 本地数据结构中获取的上一轮提交信息。	3
misbehavior	repeated Misbehavior	关于作恶验证者的信息列表。	4
height	int64	将要被提议的区块高度。	5
time	google.protobuf.Timestamp	将要被提议的区块的时间戳。	6
next_validators_hash	bytes	下一验证者集合的 Merkle 根。	7
proposer_address	bytes	创建该提议的验证者的 Address。	8

响应:
名称类型描述字段编号确定性
txs repeated bytes 可能经过修改的交易列表，将作为提议区块的一部分。 2 否
用法:
- RequestPrepareProposal 的参数 txs、misbehavior、height、time、next_validators_hash 和 proposer_address 与 RequestProcessProposal 和 RequestFinalizeBlock 中相同。
- RequestPrepareProposal.local_last_commit 是前一高度的 precommit 投票集合，其中包括促成前一个区块决议的那些投票，以及它们对应的 vote extension。
- height、time 和 proposer_address 的值与提议区块头中的值一致。
- RequestPrepareProposal 包含一组由 CometBFT 从 mempool 中取出的初步交易 txs，称为 raw proposal。应用可以修改该集合，并通过 ResponsePrepareProposal.txs 返回修改后的交易集合。
  - 应用可以修改原始提议：可以重排、删除或新增交易。设 tx 为 txs（即 RequestPrepareProposal 中的交易集合）中的一笔交易：
    - 如果应用认为 tx 不应在该区块中被提议，例如存在优先级更高的其他交易，则不应在 ResponsePrepareProposal.txs 中包含它。但这不会将 tx 从 mempool 中移除。
    - 如果应用想向提议区块中新增一笔交易，则应将其包含在 ResponsePrepareProposal.txs 中。CometBFT 不会将该交易加入 mempool。
  - 应用应注意，删除和新增交易可能会破坏 traceability。
    考虑如下示例：应用将客户端提交的交易 t1 转换为第二笔交易 t2，也就是说，应用要求 CometBFT 将 t1 从区块中移除，并将 t2 加入区块。如果客户端最终想检查 t1 发生了什么，它会发现 t1 不在任何已提交区块中（假设一次 re-CheckTx 将其从 mempool 中驱逐），从而错误地认为 t1 没有进入区块。注意，t2 会出现在某个已提交区块中，但除非应用自行跟踪这一信息，否则没有任何组件会知道这一点。因此，如果应用希望具备可追踪性，支持它就是应用自身的责任。例如，应用可以在转换后的交易上附加一个列表，其中包含它所派生自的交易哈希。
- 应用 MAY 配置 CometBFT，使其在 RequestPrepareProposal.txs 中包含一组交易，这些交易的总字节大小可能超过 RequestPrepareProposal.max_tx_bytes。如果应用将 ConsensusParams.Block.MaxBytes 设为 -1，CometBFT 将把 mempool 中当前的所有交易都放入 RequestPrepareProposal.txs，这可能无法放入 RequestPrepareProposal.max_tx_bytes。因此，如果 RequestPrepareProposal.txs 的大小大于 RequestPrepareProposal.max_tx_bytes，应用 MUST 移除部分交易，以确保 ResponsePrepareProposal.txs 返回的交易满足 RequestPrepareProposal.max_tx_bytes 限制。这一点在 Requirement 2 中有说明。
- 作为执行已准备提议的结果，应用可能会生成区块事件或交易事件。应用必须保留这些事件，直到区块被决定，然后通过 ResponseFinalizeBlock 将它们传递给 CometBFT。
- CometBFT 不会提供任何额外的有效性检查（例如检查重复交易）。
- 如果 CometBFT 无法验证 ResponsePrepareProposal，它将认为应用有故障并崩溃。
- PrepareProposal 的实现 MAY 是非确定性的。

名称	类型	描述	字段编号	确定性
txs	repeated bytes	可能经过修改的交易列表，将作为提议区块的一部分。	2	否

CometBFT 在什么时候调用 `PrepareProposal`？

当验证者 p 进入共识轮次 r、高度 h，且在该轮中 p 是 proposer，并且 p 的 validValue 为 nil 时：

CometBFT 从 p 的 mempool 收集待处理交易
- 交易将按优先级顺序收集
- p 的 CometBFT 会创建一个区块头。
p 的 CometBFT 使用新生成的区块、前一高度的本地 commit（含 vote extension）以及任何待处理的作恶证据来调用 RequestPrepareProposal。该调用是同步的：CometBFT 的执行会阻塞，直到应用从调用中返回。
应用使用收到的信息（交易、commit 信息、作恶信息、时间）来（可能地）修改提议。
- 应用 MAY 完整执行该区块并生成候选状态（即时执行）
- 应用可以操作交易：
  - 保持交易不变
  - 向提议中添加新交易（最初不存在的交易）
  - 从提议中移除交易（但不从 mempool 中移除，因此实际上只是延后它们） - 应用不在 ResponsePrepareProposal.txs 中包含该交易。
  - 修改交易（例如聚合交易）。如上所述，这会破坏客户端可追踪性，除非在应用层实现了相应支持。
  - 重新排序交易 - 应用对列表中的交易重新排序
- 应用 MAY 使用 commit 信息中的 vote extension 来修改提议；在这种情况下，建议按 VerifyVoteExtension 中的方式验证这些 extension，因为在达到最小 +2/3 之后才包含进 commit 信息的投票 extension 并未被验证。
应用在返回参数中包含交易列表（无论是否修改，参见用法一节中的规则），并从调用中返回。
p 在轮次 r、高度 h 中将（可能已修改的）区块作为 p 的提议。

请注意，如果 p 在轮次 r、高度 h 中具有非 nil 的 validValue，则共识算法会直接将其用作提议，而不会调用 RequestPrepareProposal。

ProcessProposal

参数与类型

请求:

名称	类型	描述	字段编号
txs	repeated bytes	提议区块中的交易列表。	1
proposed_last_commit	CommitInfo	从提议区块中的信息获得的上一轮提交信息。	2
misbehavior	repeated Misbehavior	关于作恶验证者的信息列表。	3
hash	bytes	提议区块的哈希。	4
height	int64	提议区块的高度。	5
time	google.protobuf.Timestamp	提议区块的时间戳。	6
next_validators_hash	bytes	下一验证者集合的 Merkle 根。	7
proposer_address	bytes	创建该提议的验证者的 Address。	8

响应:
名称类型描述字段编号确定性
status ProposalStatus 用于表示应用是否认为该提议有效的 enum。 1 是
用法:
- 包含完整执行提议区块所需的全部信息。
  - 应用可以像处理 RequestFinalizeBlock 一样完整执行该区块。
  - 但是，任何由此产生的状态变更都必须保留为 candidate state，并且应用应准备好在最终决定的是其他区块时将其丢弃。
- RequestProcessProposal 也会在某一轮的 proposer 节点上被调用。通常，RequestProcessProposal 会在 RequestPrepareProposal 调用之后立刻发生，且 RequestProcessProposal 会与基于 ResponsePrepareProposal 生成的区块相匹配（即 RequestPrepareProposal.txs 等于 RequestProcessProposal.txs）。但是并不保证这一点，因为在存在故障时，RequestProcessProposal 可能匹配更早一次调用的 ResponsePrepareProposal，或者 ProcessProposal 可能根本不会被调用。
- 高度和时间值与提议区块头中的值一致。
- 如果 ResponseProcessProposal.status 为 REJECT，共识会认为收到的提议无效。
- 应用 MAY 完整执行该区块（即时执行）。
- ProcessProposal 的实现 MUST 是确定性的。此外，ResponseProcessProposal.status 的值 MUST 仅依赖于传入 RequestProcessProposal 调用的参数，以及最近一次已提交的应用状态（参见 Requirements 章节）。
- 此外，应用实现者 SHOULD 始终将 ResponseProcessProposal.status 设为 ACCEPT，除非他们确实清楚返回 REJECT 可能带来的活性影响。

名称	类型	描述	字段编号	确定性
status	ProposalStatus	用于表示应用是否认为该提议有效的 `enum`。	1	是

CometBFT 在什么时候调用 `ProcessProposal`？

当节点 p 进入共识轮次 r、高度 h，且在该轮中 q 是 proposer（可能 p = q）时：

p 设置定时器 ProposeTimeout。
如果 p 是 proposer，则 p 执行 PrepareProposal 中的步骤 1-6。
当收到来自 q 的轮次 r、高度 h 的 Proposal 消息（其中包含区块头）时，p 验证区块头。
当收到来自 q 的轮次 r、高度 h 的 Proposal 消息以及所有区块部分后，p 按照验证者算法检查自己应当为所提议区块还是 nil 投 prevote。
如果验证者的共识算法表明 p 应为非 nil 值投 prevote：
1. CometBFT 使用该区块调用 RequestProcessProposal。该调用是同步的。
2. 应用检查/处理该提议区块（只读），并在 ResponseProcessProposal.status 字段中返回 ACCEPT 或 REJECT。
  - 应用可根据自身需求调用 ResponseProcessProposal
    - 要么在完整处理完该区块后再返回（即时执行），
    - 要么只做一些基础检查后返回，并异步处理该区块。在这种情况下，应用之后将无法再拒绝该区块，或强制 prevote/precommit nil。
    - 或者如果 p 不是验证者且应用不希望非验证节点处理 ProcessProposal，则可以立即返回 ACCEPT。
3. 如果 p 是验证者，且返回值为
  - ACCEPT：p 在轮次 r、高度 h 为该提议投 prevote。
  - REJECT：p 投 nil 的 prevote。

ExtendVote

参数与类型

请求:

名称	类型	描述	字段编号
hash	bytes	vote extension 所引用的提议区块的头部哈希。	1
height	int64	提议区块的高度（用于健全性检查）。	2
time	google.protobuf.Timestamp	提议区块的时间戳（vote extension 将引用它）。	3
txs	repeated bytes	vote extension 将引用的区块交易列表。	4
proposed_last_commit	CommitInfo	上一个提议区块的上一轮提交信息。	5
misbehavior	repeated Misbehavior	提议区块中包含的关于作恶验证者的信息列表。	6
next_validators_hash	bytes	提议区块中包含的下一验证者集合的 Merkle 根。	7
proposer_address	bytes	创建该提议的验证者的 Address。	8

响应:
名称类型描述字段编号确定性
vote_extension bytes 由 CometBFT 签名的信息。长度可以为 0。 1 否
用法:
- ResponseExtendVote.vote_extension 是由应用生成的信息，会由 CometBFT 签名并附加到 Precommit 消息上。
- 应用可以选择使用空的 vote extension（长度为 0）。
- RequestExtendVote 的内容对应于共识算法将要发送 Precommit 消息的那个提议区块。
- ResponseExtendVote.vote_extension 只会附加到非 nil 的 Precommit 消息上。如果共识算法将要 precommit nil，则不会调用 RequestExtendVote。
- 生成该 extension 的应用逻辑可以是非确定性的。

名称	类型	描述	字段编号	确定性
vote_extension	bytes	由 CometBFT 签名的信息。长度可以为 0。	1	否

CometBFT 在什么时候调用 `ExtendVote`？

当验证者 p 处于轮次 r、高度 h 的共识状态 prevote，其中 q 是 proposer；且 p 已收到

来自 q 的轮次 r、高度 h 的 Proposal 消息 v 以及所有区块部分，
来自 2f + 1 个验证者投票权、针对轮次 r、高度 h、为同一区块 id(v) 投 prevote 的 Prevote 消息，

则 p 会锁定 v，并按如下方式发送 Precommit 消息

p 将 lockedValue 和 validValue 设为 v，并将 lockedRound 和 validRound 设为 r
p 的 CometBFT 使用 v（RequestExtendVote）调用 RequestExtendVote。该调用是同步的。
应用返回一个字节数组 ResponseExtendVote.extension，共识算法不会解释其内容。
p 将 ResponseExtendVote.extension 设为类型为 CanonicalVoteExtension 的 extension 字段值，填充 CanonicalVoteExtension 中的其他字段，并对填充后的数据结构进行签名。
p 构造并签名 CanonicalVote 结构。
p 使用 CanonicalVoteExtension 和 CanonicalVote 构造 Precommit 消息（即 Vote 结构）。
p 广播 Precommit 消息。

当 p 需要广播 precommit nil 消息时（无论是收到 2f+1 个 prevote nil 消息，还是触发了 timeoutPrevote），p 的 CometBFT 不会调用 RequestExtendVote，也不会在 precommit nil 消息中包含 CanonicalVoteExtension 字段。

VerifyVoteExtension

参数与类型

请求:

名称	类型	描述	字段编号
hash	bytes	vote extension 所引用的提议区块的哈希。	1
validator_address	bytes	对该 extension 进行签名的验证者的 Address。	2
height	int64	区块高度（用于健全性检查）。	3
vote_extension	bytes	由 CometBFT 签名的应用特定信息。长度可以为 0。	4

响应:
名称类型描述字段编号确定性
status VerifyStatus 用于表示应用是否接受该 vote extension 的 enum 1 是
用法:
- RequestVerifyVoteExtension.vote_extension 可以是空字节数组。应用对此的解释应是：发送该投票的进程上运行的应用选择不扩展它。即便 vote extension 长度为 0，CometBFT 仍然总会调用 RequestVerifyVoteExtension。
- RequestVerifyVoteExtension 不会针对本地进程发送的 precommit 投票被调用。
- RequestVerifyVoteExtension.hash 指向一个提议区块。不能保证该提议区块此前一定已通过 ProcessProposal 暴露给应用。
- 如果 ResponseVerifyVoteExtension.status 为 REJECT，共识算法将拒绝整个收到的投票。请参见 Requirements 章节，以了解这对活性的潜在影响。
- VerifyVoteExtension 的实现 MUST 是确定性的。此外，ResponseVerifyVoteExtension.status 的值 MUST 仅依赖于传入 RequestVerifyVoteExtension 调用的参数，以及最近一次已提交的应用状态（参见 Requirements 章节）。
- 此外，应用实现者 SHOULD 始终将 ResponseVerifyVoteExtension.status 设为 ACCEPT，除非他们确实清楚返回 REJECT 可能带来的活性影响。

名称	类型	描述	字段编号	确定性
status	VerifyStatus	用于表示应用是否接受该 vote extension 的 `enum`	1	是

CometBFT 在什么时候调用 `VerifyVoteExtension`？

当节点 p 处于共识轮次 r、高度 h，且 p 收到来自验证者 q（q ≠ p）的轮次 r、高度 h 的 Precommit 消息时：

如果 Precommit 消息不包含带有有效签名的 vote extension，p 会将该 Precommit 消息作为无效消息丢弃。
- 长度为 0 的 vote extension 只要其附带签名同样有效，就是有效的。
否则，p 的 CometBFT 调用 RequestVerifyVoteExtension。
应用通过 ResponseVerifyVoteExtension.status 返回 ACCEPT 或 REJECT。
如果应用返回
- ACCEPT，p 会保留收到的投票及其对应的 vote extension，并存入其内部数据结构。在高度 h + 1 的某些轮次中、当 p 是 proposer 时，这些信息会用于填充 RequestPrepareProposal 调用中的 ExtendedCommitInfo 结构。
- REJECT，p 会将该 Precommit 消息视为无效并丢弃。

当节点 p 处于共识轮次 0、高度 h，并且 p 收到来自验证者 q（q ≠ p）的高度 h-1、CommitRound r 的 Precommit 消息时，p MAY 在不调用 RequestVerifyVoteExtension 进行验证的情况下，将该 Precommit 消息及其关联 extension 添加到 ExtendedCommitInfo 中。

FinalizeBlock

参数与类型

请求:

名称	类型	描述	字段编号
txs	repeated bytes	作为该区块一部分被提交的交易列表。	1
decided_last_commit	CommitInfo	刚刚被决定的区块中获得的上一轮提交信息。	2
misbehavior	repeated Misbehavior	关于作恶验证者的信息列表。	3
hash	bytes	该区块的哈希。	4
height	int64	已完成最终确定的区块高度。	5
time	google.protobuf.Timestamp	已完成最终确定的区块时间戳。	6
next_validators_hash	bytes	下一验证者集合的 Merkle 根。	7
proposer_address	bytes	创建该提议的验证者的 Address。	8

响应:

名称	类型	描述	字段编号	确定性
events	repeated Event	用于索引的类型与键值事件	1	否
tx_results	repeated ExecTxResult	包含执行交易后结果数据的结构列表	2	是
validator_updates	repeated ValidatorUpdate	验证者集合的变更（将投票权设为 0 以移除）。	3	是
consensus_param_updates	ConsensusParams	对 gas、大小及其他共识相关参数的变更。	4	是
app_hash	bytes	应用状态的 Merkle 根哈希。	5	是

用法:
- 包含新近决定的区块字段。
- 该方法等价于 ABCI 1.0 中的调用序列 BeginBlock、[DeliverTx] 和 EndBlock。
- 高度和时间值与提议区块头中的值一致。
- 应用可以使用 RequestFinalizeBlock.decided_last_commit 和 RequestFinalizeBlock.misbehavior 来确定验证者的奖励和惩罚。
- 应用会按照自身设定的规则，以确定性的方式执行 RequestFinalizeBlock.txs 中的交易，然后再将控制权返回给 CometBFT。或者，它也可以应用先前通过 PrepareProposal 或 ProcessProposal 执行过的同一区块对应的候选状态。
- 仅当第 i 笔交易完全有效时，ResponseFinalizeBlock.tx_results[i].Code == 0。
- 应用必须基于区块执行结果，为 ResponseFinalizeBlock.app_hash、ResponseFinalizeBlock.tx_results、ResponseFinalizeBlock.validator_updates 和 ResponseFinalizeBlock.consensus_param_updates 提供值。
  - ResponseFinalizeBlock.validator_updates 或 ResponseFinalizeBlock.consensus_param_updates 的值可以为空。在这种情况下，CometBFT 将保留当前值。
  - 由区块 H 触发的 ResponseFinalizeBlock.validator_updates 会影响区块 H+1、H+2 和 H+3 的验证。验证者更新后的高度影响如下：
    - 高度 H+1：NextValidatorsHash 包含新的 validator_updates 值。
    - 高度 H+2：验证者集合变更生效，ValidatorsHash 被更新。
    - 高度 H+3：PrepareProposal、ProcessProposal 和 FinalizeBlock 中的 *_last_commit 字段现在包含变更后的验证者集合。
  - 为区块 H 返回的 ResponseFinalizeBlock.consensus_param_updates 会应用到区块 H+1 的共识参数。关于共识参数的更多信息，请参见共识参数章节。
- ResponseFinalizeBlock.app_hash 包含应用状态的（可选）Merkle 根哈希。
- ResponseFinalizeBlock.app_hash 会作为下一个区块中的 Header.AppHash 被包含进去。
  - ResponseFinalizeBlock.app_hash 也可以为空或写死，但 MUST 是 确定性的，即它不能依赖于 RequestFinalizeBlock 参数和先前已提交状态之外的任何内容。
- 后续对 Query 的调用可以返回以该 Merkle 根哈希为锚点的应用状态证明。
- FinalizeBlock 的实现 MUST 是确定性的，因为它会在状态机复制的上下文中推动应用状态演进。
- 目前，即便 RequestPrepareProposal 或 RequestProcessProposal 已将相关字段传给应用，CometBFT 仍会填充 RequestFinalizeBlock 的所有字段。
- 当对某个区块调用 FinalizeBlock 时，CometBFT 运行的共识算法保证至少有一个非拜占庭验证者已经对该区块运行过 ProcessProposal。

CometBFT 在什么时候调用 `FinalizeBlock`？

当节点 p 处于共识高度 h，且 p 收到

来自 q 的轮次 r、高度 h 的 Proposal 消息及其区块 v 的所有区块部分，其中 q 是该轮次的 proposer，
来自 2f + 1 个验证者投票权、针对轮次 r、高度 h、为同一区块 id(v) 投 precommit 的 Precommit 消息，

则 p 会决定区块 v，并按如下方式完成高度 h 的共识：

p 将 v 持久化为高度 h 的决议结果。
p 的 CometBFT 使用 v 的数据调用 RequestFinalizeBlock。该调用是同步的。
p 的应用执行区块 v。
p 的应用计算并返回 AppHash，以及一个包含每笔已执行交易输出的列表。
p 的 CometBFT 对所有交易输出进行哈希，并将其存储在 ResultHash 中。
p 的 CometBFT 持久化交易输出、AppHash 和 ResultsHash。
p 的 CometBFT 锁定 mempool — 不再对新交易调用 CheckTx。
p 的 CometBFT 调用 RequestCommit，指示应用持久化其状态。
p 的 CometBFT 可选地根据新持久化的应用状态，重新检查 mempool 中所有待处理交易。
p 的 CometBFT 解锁 mempool — 新收到的交易现在可以被检查。
p 在高度 h+1、轮次 0 开始新一轮共识

ABCI 中现有的数据类型

ABCI 中使用的大多数数据结构都是共享的通用数据结构。在某些情况下，ABCI 使用了不同的数据结构，这些结构在此处记录：

Validator

字段:
名称类型描述字段编号
address bytes 验证者的 Address 1
power int64 验证者的投票权 3
用法:
- 通过地址标识验证者
- 作为 CommitInfo 中 VoteInfo 的一部分使用（用于 ProcessProposal 和 FinalizeBlock），以及 ExtendedCommitInfo（用于 PrepareProposal）。
- 不包含 PubKey，以避免通过 ABCI 发送可能很大的量子公钥

名称	类型	描述	字段编号
address	bytes	验证者的 Address	1
power	int64	验证者的投票权	3

ValidatorUpdate

字段:
名称类型描述字段编号确定性
pub_key Public Key 验证者的公钥 1 是
power int64 验证者的投票权 2 是
用法:
- 通过 PubKey 标识验证者
- 用于告知 CometBFT 更新验证者集合

名称	类型	描述	字段编号	确定性
pub_key	Public Key	验证者的公钥	1	是
power	int64	验证者的投票权	2	是

Misbehavior

字段:

名称	类型	描述	字段编号
type	MisbehaviorType	作恶类型。一个可能作恶行为的枚举。	1
validator	Validator	违规的验证者	2
height	int64	违规发生时的高度	3
time	google.protobuf.Timestamp	在高度 `height` 提交的区块时间戳	4
total_voting_power	int64	在高度 `height` 时验证者集合的总投票权	5

MisbehaviorType

字段 MisbehaviorType 是一个枚举，包含以下字段：
名称字段编号
UNKNOWN 0
DUPLICATE_VOTE 1
LIGHT_CLIENT_ATTACK 2

名称	字段编号
UNKNOWN	0
DUPLICATE_VOTE	1
LIGHT_CLIENT_ATTACK	2

ConsensusParams

字段:

名称	类型	描述	字段编号	确定性
block	BlockParams	限制区块大小和相邻区块间时间的参数。	1	是
evidence	EvidenceParams	限制作恶行为证据有效性的参数。	2	是
validator	ValidatorParams	限制验证者可使用公钥类型的参数。	3	是
version	VersionsParams	ABCI 应用版本。	4	是

ProofOps

字段:

名称	类型	描述	字段编号	确定性
ops	repeated ProofOp	链式 Merkle 证明列表，可能包含不同类型。某个 op 的 Merkle 根是下一个 op 中被证明的值。最终 op 的 Merkle 根应等于要进行验证的最终根哈希。	1	N/A

ProofOp

字段:

名称	类型	描述	字段编号	确定性
type	string	Merkle 证明的类型及其编码方式。	1	N/A
key	bytes	该证明对应的 Merkle 树中的键。	2	N/A
data	bytes	该键对应的编码后 Merkle 证明。	3	N/A

Snapshot

字段:

名称	类型	描述	字段编号	确定性
height	uint64	生成快照时的高度（在 commit 之后）。	1	N/A
format	uint32	应用特定的快照格式，允许应用对快照数据格式进行版本化并进行不向后兼容的变更。CometBFT 不解释该值。	2	N/A
chunks	uint32	快照中的分块数。必须至少为 1（即便为空）。	3	N/A
hash	bytes	任意的快照哈希。只有当跨节点的快照完全相同时，它才必须相等。CometBFT 不解释该哈希，只做比较。	4	N/A
metadata	bytes	任意的应用元数据，例如分块哈希或其他校验数据。	5	N/A

用法:
- 用于状态同步快照，详情请参见状态同步章节。
- 只有当所有字段都相等（包括 Metadata）时，快照才会被视为跨节点相同。分块可以从所有拥有相同快照的节点获取。
- 在网络上传输时，快照消息最大不能超过 4 MB。

ABCI++ 中引入或修改的数据类型

VoteInfo

字段:
名称类型描述字段编号
validator Validator 发送投票的验证者。 1
block_id_flag BlockIDFlag 表示验证者是为上一个区块投票、为 nil 投票，还是其投票未被收到。 3
用法:
- 表示验证者是否签署了上一个区块，从而可以基于验证者可用性进行奖励。
- 该信息通常从提议区块或已决定区块中提取。

ExtendedVoteInfo

字段:

名称	类型	描述	字段编号
validator	Validator	发送投票的验证者。	1
vote_extension	bytes	由发送方验证者的应用提供的非确定性扩展。	3
extension_signature	bytes	由发送方验证者生成并经 CometBFT 验证的 vote extension 签名。	4
block_id_flag	BlockIDFlag	表示验证者是为上一个区块投票、为 nil 投票，还是其投票未被收到。	5

用法:
- 表示验证者是否签署了上一个区块，从而可以基于验证者可用性进行奖励。
- 该信息从本地进程中的 CometBFT 数据结构提取。
- vote_extension 包含发送方验证者的 vote extension，其签名已经过 CometBFT 验证。它可以为空。
- extension_signature 是 vote extension 的签名，该签名已经过 CometBFT 验证。这样应用便可以暴露该签名，以便进一步处理或验证。

CommitInfo

字段:

名称	类型	描述	字段编号
round	int32	提交轮次。反映区块 proposer 在上一高度作出决议时所在的轮次。	1
votes	repeated VoteInfo	上一个验证者集合中各验证者地址及其投票信息的列表。	2

说明
- votes 中的 VoteInfo 按验证者投票权排序（降序，从高到低）。
- CometBFT 通过其更新验证者集合的逻辑来保证 votes 的顺序；在该逻辑结束时，验证者会按投票权降序排列。
- 当验证者集合被保存到存储中时，这一顺序也会被持久化。
- 构建 CommitInfo 时，验证者集合会从存储中加载，从而确保沿用持久化验证者集合的顺序。

ExtendedCommitInfo

字段:

名称	类型	描述	字段编号
round	int32	提交轮次。反映区块 proposer 在上一高度作出决议时所在的轮次。	1
votes	repeated ExtendedVoteInfo	上一个验证者集合中各验证者地址及其投票信息的列表，包含 vote extension。	2

说明
- votes 中的 ExtendedVoteInfo 按验证者投票权排序（降序，从高到低）。
- CometBFT 通过其更新验证者集合的逻辑来保证 votes 的顺序；在该逻辑结束时，验证者会按投票权降序排列。
- 当验证者集合被保存到存储中时，这一顺序也会被持久化。
- 构建 ExtendedCommitInfo 时，验证者集合会从存储中加载，从而确保沿用持久化验证者集合的顺序。

ExecTxResult

字段:

名称	类型	描述	字段编号	确定性
code	uint32	响应码。	1	是
data	bytes	结果字节（如果有）。	2	是
log	string	应用日志记录器的输出。	3	否
info	string	附加信息。	4	否
gas_wanted	int64	交易请求的 gas 数量。	5	是
gas_used	int64	交易消耗的 gas 数量。	6	是
events	repeated Event	用于索引交易的类型与键值事件（例如按账户索引）。	7	否
codespace	string	`code` 的命名空间。	8	是

ProposalStatus

enum ProposalStatus {
  UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
  ACCEPT  = 1; // Status that signals that the application finds the proposal valid.
  REJECT  = 2; // Status that signals that the application finds the proposal invalid.
}

用法:
- 用于 ProcessProposal 的响应中。
  - 如果 Status 为 UNKNOWN，说明应用发生了问题。CometBFT 会认为应用有故障并崩溃。
  - 如果 Status 为 ACCEPT，共识算法会接受该提议，并为其发出 Prevote 消息。
  - 如果 Status 为 REJECT，共识算法会拒绝该提议，并改为为 nil 发出 Prevote。

VerifyStatus

enum VerifyStatus {
  UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
  ACCEPT  = 1; // Status that signals that the application finds the vote extension valid.
  REJECT  = 2; // Status that signals that the application finds the vote extension invalid.
}

用法:
- 用于 VerifyVoteExtension 的响应中。
  - 如果 Status 为 UNKNOWN，说明应用发生了问题。CometBFT 会认为应用有故障并崩溃。
  - 如果 Status 为 ACCEPT，共识算法会接受该投票并认为其有效。
  - 如果 Status 为 REJECT，共识算法会拒绝该投票并认为其无效。

Methods existing in ABCI

Echo

Request:
- Message (string): A string to echo back
Response:
- Message (string): The input string
Usage:
- Echo a string to test an ABCI client/server implementation

Flush

Usage:
- Signals that messages queued on the client should be flushed to the server. It is called periodically by the client implementation to ensure asynchronous requests are actually sent, and is called immediately to make a synchronous request, which returns when the Flush response comes back.

Info

Request:

Name	Type	Description	Field Number
version	string	The CometBFT software semantic version	1
block_version	uint64	The CometBFT Block version	2
p2p_version	uint64	The CometBFT P2P version	3
abci_version	string	The CometBFT ABCI semantic version	4

Response:

Name	Type	Description	Field Number	Deterministic
data	string	Some arbitrary information	1	N/A
version	string	The application software semantic version	2	N/A
app_version	uint64	The application version	3	N/A
last_block_height	int64	Latest height for which the app persisted its state	4	N/A
last_block_app_hash	bytes	Latest AppHash returned by `FinalizeBlock`	5	N/A

Usage:
- Return information about the application state.
- Used to sync CometBFT with the application during a handshake that happens on startup or on recovery.
- The returned app_version will be included in the Header of every block.
- CometBFT expects last_block_app_hash and last_block_height to be updated and persisted during Commit.

Note: Semantic version is a reference to semantic versioning. Semantic versions in info will be displayed as X.X.x.

InitChain

Request:

Name	Type	Description	Field Number
time	google.protobuf.Timestamp	Genesis time	1
chain_id	string	ID of the blockchain.	2
consensus_params	ConsensusParams	Initial consensus-critical parameters.	3
validators	repeated ValidatorUpdate	Initial genesis validators, sorted by voting power.	4
app_state_bytes	bytes	Serialized initial application state. JSON bytes.	5
initial_height	int64	Height of the initial block (typically `1`).	6

Response:

Name	Type	Description	Field Number	Deterministic
consensus_params	ConsensusParams	Initial consensus-critical parameters (optional)	1	Yes
validators	repeated ValidatorUpdate	Initial validator set (optional).	2	Yes
app_hash	bytes	Initial application hash.	3	Yes

Usage:
- Called once upon genesis.
- If ResponseInitChain.Validators is empty, the initial validator set will be the RequestInitChain.Validators
- If ResponseInitChain.Validators is not empty, it will be the initial validator set (regardless of what is in RequestInitChain.Validators).
- This allows the app to decide if it wants to accept the initial validator set proposed by CometBFT (ie. in the genesis file), or if it wants to use a different one (perhaps computed based on some application specific information in the genesis file).
- Both RequestInitChain.Validators and ResponseInitChain.Validators are ValidatorUpdate structs. So, technically, they both are updating the set of validators from the empty set.

Query

Request:

Name	Type	Description	Field Number
data	bytes	Request parameters for the application to interpret analogously to a URI query component. Can be used with or in lieu of `path`.	1
path	string	A request path for the application to interpret analogously to a URI path component in e.g. routing. Can be used with or in lieu of `data`. Applications MUST interpret “/store” or any path starting with “/store/” as a query by key on the underlying store, in which case a key SHOULD be specified in `data`. Applications SHOULD allow queries over specific types like `/accounts/...` or `/votes/...`.	2
height	int64	The block height against which to query (default=0 returns data for the latest committed block). Note that this is the height of the block containing the application’s Merkle root hash, which represents the state as it was after committing the block at Height-1.	3
prove	bool	Return Merkle proof with response if possible.	4

Response:

Name	Type	Description	Field Number	Deterministic
code	uint32	Response code.	1	N/A
log	string	The output of the application’s logger.	3	N/A
info	string	Additional information.	4	N/A
index	int64	The index of the key in the tree.	5	N/A
key	bytes	The key of the matching data.	6	N/A
value	bytes	The value of the matching data.	7	N/A
proof_ops	ProofOps	Serialized proof for the value data, if requested, to be verified against the `app_hash` for the given Height.	8	N/A
height	int64	The block height from which data was derived. Note that this is the height of the block containing the application’s Merkle root hash, which represents the state as it was after committing the block at Height-1	9	N/A
codespace	string	Namespace for the `code`.	10	N/A

Usage:
- Query for data from the application at current or past height.
- Optionally return Merkle proof.
- Merkle proof includes self-describing type field to support many types of Merkle trees and encoding formats.

CheckTx

Request:

Name	Type	Description	Field Number
tx	bytes	The request transaction bytes	1
type	CheckTxType	One of `CheckTx_New` or `CheckTx_Recheck`. `CheckTx_New` is the default and means that a full check of the tranasaction is required. `CheckTx_Recheck` types are used when the mempool is initiating a normal recheck of a transaction.	2

Response:

Name	Type	Description	Field Number	Deterministic
code	uint32	Response code.	1	N/A
data	bytes	Result bytes, if any.	2	N/A
log	string	The output of the application’s logger.	3	N/A
info	string	Additional information.	4	N/A
gas_wanted	int64	Amount of gas requested for transaction.	5	N/A
gas_used	int64	Amount of gas consumed by transaction.	6	N/A
events	repeated Event	Type & Key-Value events for indexing transactions (e.g. by account).	7	N/A
codespace	string	Namespace for the `code`.	8	N/A

Usage:
- Technically optional - not involved in processing blocks.
- Guardian of the mempool: every node runs CheckTx before letting a transaction into its local mempool.
- The transaction may come from an external user or another node
- CheckTx validates the transaction against the current state of the application, for example, checking signatures and account balances, but does not apply any of the state changes described in the transaction.
- Transactions where ResponseCheckTx.Code != 0 will be rejected - they will not be broadcast to other nodes or included in a proposal block. CometBFT attributes no other value to the response code.

Commit

Parameters and Types

Request: Commit signals the application to persist application state. It takes no parameters.
Response:
Name Type Description Field Number Deterministic
retain_height int64 Blocks below this height may be removed. Defaults to 0 (retain all). 3 No
Usage:
- Signal the Application to persist the application state. Application is expected to persist its state at the end of this call, before calling ResponseCommit.
- Use ResponseCommit.retain_height with caution! If all nodes in the network remove historical blocks then this data is permanently lost, and no new nodes will be able to join the network and bootstrap, unless state sync is enabled on the chain. Historical blocks may also be required for other purposes, e.g. auditing, replay of non-persisted heights, light client verification, and so on.

Name	Type	Description	Field Number	Deterministic
retain_height	int64	Blocks below this height may be removed. Defaults to `0` (retain all).	3	No

ListSnapshots

Request: Empty request asking the application for a list of snapshots.
Response:
Name Type Description Field Number Deterministic
snapshots repeated Snapshot List of local state snapshots. 1 N/A
Usage:
- Used during state sync to discover available snapshots on peers.
- See Snapshot data type for details.

Name	Type	Description	Field Number	Deterministic
snapshots	repeated Snapshot	List of local state snapshots.	1	N/A

LoadSnapshotChunk

Request:

Name	Type	Description	Field Number
height	uint64	The height of the snapshot the chunk belongs to.	1
format	uint32	The application-specific format of the snapshot the chunk belongs to.	2
chunk	uint32	The chunk index, starting from `0` for the initial chunk.	3

Response:

Name	Type	Description	Field Number	Deterministic
chunk	bytes	The binary chunk contents, in an arbitrary format. Chunk messages cannot be larger than 16 MB including metadata, so 10 MB is a good starting point.	1	N/A

Usage:
- Used during state sync to retrieve snapshot chunks from peers.

OfferSnapshot

Request:
Name Type Description Field Number
snapshot Snapshot The snapshot offered for restoration. 1
app_hash bytes The light client-verified app hash for this height, from the blockchain. 2
Response:
Name Type Description Field Number Deterministic
result Result The result of the snapshot offer. 1 N/A

Result

  enum Result {
    UNKNOWN       = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT        = 1;  // Snapshot is accepted, start applying chunks.
    ABORT         = 2;  // Abort snapshot restoration, and don't try any other snapshots.
    REJECT        = 3;  // Reject this specific snapshot, try others.
    REJECT_FORMAT = 4;  // Reject all snapshots with this `format`, try others.
    REJECT_SENDER = 5;  // Reject all snapshots from all senders of this snapshot, try others.
  }

Usage:
- OfferSnapshot is called when bootstrapping a node using state sync. The application may accept or reject snapshots as appropriate. Upon accepting, CometBFT will retrieve and apply snapshot chunks via ApplySnapshotChunk. The application may also choose to reject a snapshot in the chunk response, in which case it should be prepared to accept further OfferSnapshot calls.
- Only AppHash can be trusted, as it has been verified by the light client. Any other data can be spoofed by adversaries, so applications should employ additional verification schemes to avoid denial-of-service attacks. The verified AppHash is automatically checked against the restored application at the end of snapshot restoration.
- For more information, see the Snapshot data type or the state sync section.

ApplySnapshotChunk

Request:

Name	Type	Description	Field Number
index	uint32	The chunk index, starting from `0`. CometBFT applies chunks sequentially.	1
chunk	bytes	The binary chunk contents, as returned by `LoadSnapshotChunk`.	2
sender	string	The P2P ID of the node who sent this chunk.	3

Response:

Name	Type	Description	Field Number	Deterministic
result	Result (see below)	The result of applying this chunk.	1	N/A
refetch_chunks	repeated uint32	Refetch and reapply the given chunks, regardless of `result`. Only the listed chunks will be refetched, and reapplied in sequential order.	2	N/A
reject_senders	repeated string	Reject the given P2P senders, regardless of `Result`. Any chunks already applied will not be refetched unless explicitly requested, but queued chunks from these senders will be discarded, and new chunks or other snapshots rejected.	3	N/A

  enum Result {
    UNKNOWN         = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT          = 1;  // The chunk was accepted.
    ABORT           = 2;  // Abort snapshot restoration, and don't try any other snapshots.
    RETRY           = 3;  // Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate.
    RETRY_SNAPSHOT  = 4;  // Restart this snapshot from `OfferSnapshot`, reusing chunks unless instructed otherwise.
    REJECT_SNAPSHOT = 5;  // Reject this snapshot, try a different one.
  }

Usage:
- The application can choose to refetch chunks and/or ban P2P peers as appropriate. CometBFT will not do this unless instructed by the application.
- The application may want to verify each chunk, e.g. by attaching chunk hashes in Snapshot.Metadata and/or incrementally verifying contents against AppHash.
- When all chunks have been accepted, CometBFT will make an ABCI Info call to verify that LastBlockAppHash and LastBlockHeight matches the expected values, and record the AppVersion in the node state. It then switches to block sync or consensus and joins the network.
- If CometBFT is unable to retrieve the next chunk after some time (e.g. because no suitable peers are available), it will reject the snapshot and try a different one via OfferSnapshot. The application should be prepared to reset and accept it or abort as appropriate.

New methods introduced in ABCI 2.0

PrepareProposal

Parameters and Types

Request:

Name	Type	Description	Field Number
max_tx_bytes	int64	Currently configured maximum size in bytes taken by the modified transactions.	1
txs	repeated bytes	Preliminary list of transactions that have been picked as part of the block to propose.	2
local_last_commit	ExtendedCommitInfo	Info about the last commit, obtained locally from CometBFT’s data structures.	3
misbehavior	repeated Misbehavior	List of information about validators that misbehaved.	4
height	int64	The height of the block that will be proposed.	5
time	google.protobuf.Timestamp	Timestamp of the block that that will be proposed.	6
next_validators_hash	bytes	Merkle root of the next validator set.	7
proposer_address	bytes	Address of the validator that is creating the proposal.	8

Response:
Name Type Description Field Number Deterministic
txs repeated bytes Possibly modified list of transactions that have been picked as part of the proposed block. 2 No
Usage:
- RequestPrepareProposal’s parameters txs, misbehavior, height, time, next_validators_hash, and proposer_address are the same as in RequestProcessProposal and RequestFinalizeBlock.
- RequestPrepareProposal.local_last_commit is a set of the precommit votes for the previous height, including the ones that led to the decision of the previous block, together with their corresponding vote extensions.
- The height, time, and proposer_address values match the values from the header of the proposed block.
- RequestPrepareProposal contains a preliminary set of transactions txs that CometBFT retrieved from the mempool, called raw proposal. The Application can modify this set and return a modified set of transactions via ResponsePrepareProposal.txs .
  - The Application can modify the raw proposal: it can reorder, remove or add transactions. Let tx be a transaction in txs (set of transactions within RequestPrepareProposal):
    - If the Application considers that tx should not be proposed in this block, e.g., there are other transactions with higher priority, then it should not include it in ResponsePrepareProposal.txs. However, this will not remove tx from the mempool.
    - If the Application wants to add a new transaction to the proposed block, then the Application includes it in ResponsePrepareProposal.txs. CometBFT will not add the transaction to the mempool.
  - The Application should be aware that removing and adding transactions may compromise traceability.
    Consider the following example: the Application transforms a client-submitted transaction t1 into a second transaction t2, i.e., the Application asks CometBFT to remove t1 from the block and add t2 to the block. If a client wants to eventually check what happened to t1, it will discover that t1 is not in a committed block (assuming a re-CheckTx evicted it from the mempool), getting the wrong idea that t1 did not make it into a block. Note that t2 will be in a committed block, but unless the Application tracks this information, no component will be aware of it. Thus, if the Application wants traceability, it is its responsibility’s to support it. For instance, the Application could attach to a transformed transaction a list with the hashes of the transactions it derives from.
- The Application MAY configure CometBFT to include a list of transactions in RequestPrepareProposal.txs whose total size in bytes exceeds RequestPrepareProposal.max_tx_bytes. If the Application sets ConsensusParams.Block.MaxBytes to -1, CometBFT will include all transactions currently in the mempool in RequestPrepareProposal.txs, which may not fit in RequestPrepareProposal.max_tx_bytes. Therefore, if the size of RequestPrepareProposal.txs is greater than RequestPrepareProposal.max_tx_bytes, the Application MUST remove transactions to ensure that the RequestPrepareProposal.max_tx_bytes limit is respected by those transactions returned in ResponsePrepareProposal.txs. This is specified in Requirement 2.
- As a result of executing the prepared proposal, the Application may produce block events or transaction events. The Application must keep those events until a block is decided and then pass them on to CometBFT via ResponseFinalizeBlock.
- CometBFT does NOT provide any additional validity checks (such as checking for duplicate transactions).
- If CometBFT fails to validate the ResponsePrepareProposal, CometBFT will assume the Application is faulty and crash.
- The implementation of PrepareProposal MAY be non-deterministic.

When does CometBFT call “PrepareProposal” ?

When a validator p enters consensus round r, height h, in which p is the proposer, and p’s validValue is nil:

CometBFT collects outstanding transactions from p’s mempool
- the transactions will be collected in order of priority
- p’s CometBFT creates a block header.
p’s CometBFT calls RequestPrepareProposal with the newly generated block, the local commit of the previous height (with vote extensions), and any outstanding evidence of misbehavior. The call is synchronous: CometBFT’s execution will block until the Application returns from the call.
The Application uses the information received (transactions, commit info, misbehavior, time) to (potentially) modify the proposal.
- the Application MAY fully execute the block and produce a candidate state (immediate execution)
- the Application can manipulate transactions:
  - leave transactions untouched
  - add new transactions (not present initially) to the proposal
  - remove transactions from the proposal (but not from the mempool thus effectively delaying them) - the Application does not include the transaction in ResponsePrepareProposal.txs.
  - modify transactions (e.g. aggregate them). As explained above, this compromises client traceability, unless it is implemented at the Application level.
  - reorder transactions - the Application reorders transactions in the list
- the Application MAY use the vote extensions in the commit info to modify the proposal, in which case it is suggested that extensions be validated in the same maner as done in VerifyVoteExtension, since extensions of votes included in the commit info after the minimum of +2/3 had been reached are not verified.
The Application includes the transaction list (whether modified or not) in the return parameters (see the rules in section Usage), and returns from the call.
p uses the (possibly) modified block as p’s proposal in round r, height h.

Note that, if p has a non-nil validValue in round r, height h, the consensus algorithm will use it as proposal and will not call RequestPrepareProposal.

ProcessProposal

Parameters and Types

Request:

Name	Type	Description	Field Number
txs	repeated bytes	List of transactions of the proposed block.	1
proposed_last_commit	CommitInfo	Info about the last commit, obtained from the information in the proposed block.	2
misbehavior	repeated Misbehavior	List of information about validators that misbehaved.	3
hash	bytes	The hash of the proposed block.	4
height	int64	The height of the proposed block.	5
time	google.protobuf.Timestamp	Timestamp of the proposed block.	6
next_validators_hash	bytes	Merkle root of the next validator set.	7
proposer_address	bytes	Address of the validator that created the proposal.	8

Response:
Name Type Description Field Number Deterministic
status ProposalStatus enum that signals if the application finds the proposal valid. 1 Yes
Usage:
- Contains all information on the proposed block needed to fully execute it.
  - The Application may fully execute the block as though it was handling RequestFinalizeBlock.
  - However, any resulting state changes must be kept as candidate state, and the Application should be ready to discard it in case another block is decided.
- RequestProcessProposal is also called at the proposer of a round. Normally the call to RequestProcessProposal occurs right after the call to RequestPrepareProposal and RequestProcessProposal matches the block produced based on ResponsePrepareProposal (i.e., RequestPrepareProposal.txs equals RequestProcessProposal.txs). However, no such guarantee is made since, in the presence of failures, RequestProcessProposal may match ResponsePrepareProposal from an earlier invocation or ProcessProposal may not be invoked at all.
- The height and time values match the values from the header of the proposed block.
- If ResponseProcessProposal.status is REJECT, consensus assumes the proposal received is not valid.
- The Application MAY fully execute the block (immediate execution)
- The implementation of ProcessProposal MUST be deterministic. Moreover, the value of ResponseProcessProposal.status MUST exclusively depend on the parameters passed in the call to RequestProcessProposal, and the last committed Application state (see Requirements section).
- Moreover, application implementors SHOULD always set ResponseProcessProposal.status to ACCEPT, unless they really know what the potential liveness implications of returning REJECT are.

When does CometBFT call “ProcessProposal” ?

When a node p enters consensus round r, height h, in which q is the proposer (possibly p = q):

p sets up timer ProposeTimeout.
If p is the proposer, p executes steps 1-6 in PrepareProposal.
Upon reception of Proposal message (which contains the header) for round r, height h from q, p verifies the block header.
Upon reception of Proposal message, along with all the block parts, for round r, height h from q, p follows the validators’ algorithm to check whether it should prevote for the proposed block, or nil.
If the validators’ consensus algorithm indicates p should prevote non-nil:
1. CometBFT calls RequestProcessProposal with the block. The call is synchronous.
2. The Application checks/processes the proposed block, which is read-only, and returns ACCEPT or REJECT in the ResponseProcessProposal.status field.
  - The Application, depending on its needs, may call ResponseProcessProposal
    - either after it has completely processed the block (immediate execution),
    - or after doing some basic checks, and process the block asynchronously. In this case the Application will not be able to reject the block, or force prevote/precommit nil afterwards.
    - or immediately, returning ACCEPT, if p is not a validator and the Application does not want non-validating nodes to handle ProcessProposal
3. If p is a validator and the returned value is
  - ACCEPT: p prevotes on this proposal for round r, height h.
  - REJECT: p prevotes nil.

ExtendVote

Parameters and Types

Request:

Name	Type	Description	Field Number
hash	bytes	The header hash of the proposed block that the vote extension is to refer to.	1
height	int64	Height of the proposed block (for sanity check).	2
time	google.protobuf.Timestamp	Timestamp of the proposed block (that the extension is to refer to).	3
txs	repeated bytes	List of transactions of the block that the extension is to refer to.	4
proposed_last_commit	CommitInfo	Info about the last proposed block’s last commit.	5
misbehavior	repeated Misbehavior	List of information about validators that misbehaved contained in the proposed block.	6
next_validators_hash	bytes	Merkle root of the next validator set contained in the proposed block.	7
proposer_address	bytes	Address of the validator that created the proposal.	8

Response:
Name Type Description Field Number Deterministic
vote_extension bytes Information signed by by CometBFT. Can have 0 length. 1 No
Usage:
- ResponseExtendVote.vote_extension is application-generated information that will be signed by CometBFT and attached to the Precommit message.
- The Application may choose to use an empty vote extension (0 length).
- The contents of RequestExtendVote correspond to the proposed block on which the consensus algorithm will send the Precommit message.
- ResponseExtendVote.vote_extension will only be attached to a non-nil Precommit message. If the consensus algorithm is to precommit nil, it will not call RequestExtendVote.
- The Application logic that creates the extension can be non-deterministic.

When does CometBFT call `ExtendVote`?

When a validator p is in consensus state prevote of round r, height h, in which q is the proposer; and p has received

the Proposal message v for round r, height h, along with all the block parts, from q,
Prevote messages from 2f + 1 validators’ voting power for round r, height h, prevoting for the same block id(v),

then p locks v and sends a Precommit message in the following way

p sets lockedValue and validValue to v, and sets lockedRound and validRound to r
p’s CometBFT calls RequestExtendVote with v (RequestExtendVote). The call is synchronous.
The Application returns an array of bytes, ResponseExtendVote.extension, which is not interpreted by the consensus algorithm.
p sets ResponseExtendVote.extension as the value of the extension field of type CanonicalVoteExtension, populates the other fields in CanonicalVoteExtension, and signs the populated data structure.
p constructs and signs the CanonicalVote structure.
p constructs the Precommit message (i.e. Vote structure) using CanonicalVoteExtension and CanonicalVote.
p broadcasts the Precommit message.

In the cases when p is to broadcast precommit nil messages (either 2f+1 prevote nil messages received, or timeoutPrevote triggered), p’s CometBFT does not call RequestExtendVote and will not include a CanonicalVoteExtension field in the precommit nil message.

VerifyVoteExtension

Parameters and Types

Request:

Name	Type	Description	Field Number
hash	bytes	The hash of the proposed block that the vote extension refers to.	1
validator_address	bytes	Address of the validator that signed the extension.	2
height	int64	Height of the block (for sanity check).	3
vote_extension	bytes	Application-specific information signed by CometBFT. Can have 0 length.	4

Response:
Name Type Description Field Number Deterministic
status VerifyStatus enum signaling if the application accepts the vote extension 1 Yes
Usage:
- RequestVerifyVoteExtension.vote_extension can be an empty byte array. The Application’s interpretation of it should be that the Application running at the process that sent the vote chose not to extend it. CometBFT will always call RequestVerifyVoteExtension, even for 0 length vote extensions.
- RequestVerifyVoteExtension is not called for precommit votes sent by the local process.
- RequestVerifyVoteExtension.hash refers to a proposed block. There is not guarantee that this proposed block has previously been exposed to the Application via ProcessProposal.
- If ResponseVerifyVoteExtension.status is REJECT, the consensus algorithm will reject the whole received vote. See the Requirements section to understand the potential liveness implications of this.
- The implementation of VerifyVoteExtension MUST be deterministic. Moreover, the value of ResponseVerifyVoteExtension.status MUST exclusively depend on the parameters passed in the call to RequestVerifyVoteExtension, and the last committed Application state (see Requirements section).
- Moreover, application implementers SHOULD always set ResponseVerifyVoteExtension.status to ACCEPT, unless they really know what the potential liveness implications of returning REJECT are.

When does CometBFT call `VerifyVoteExtension`?

When a node p is in consensus round r, height h, and p receives a Precommit message for round r, height h from validator q (q ≠ p):

If the Precommit message does not contain a vote extension with a valid signature, p discards the Precommit message as invalid.
- a 0-length vote extension is valid as long as its accompanying signature is also valid.
Else, p’s CometBFT calls RequestVerifyVoteExtension.
The Application returns ACCEPT or REJECT via ResponseVerifyVoteExtension.status.
If the Application returns
- ACCEPT, p will keep the received vote, together with its corresponding vote extension in its internal data structures. It will be used to populate the ExtendedCommitInfo structure in calls to RequestPrepareProposal, in rounds of height h + 1 where p is the proposer.
- REJECT, p will deem the Precommit message invalid and discard it.

When a node p is in consensus round 0, height h, and p receives a Precommit message for CommitRound r, height h-1 from validator q (q ≠ p), p MAY add the Precommit message and associated extension to ExtendedCommitInfo without calling RequestVerifyVoteExtension to verify it.

FinalizeBlock

Parameters and Types

Request:

Name	Type	Description	Field Number
txs	repeated bytes	List of transactions committed as part of the block.	1
decided_last_commit	CommitInfo	Info about the last commit, obtained from the block that was just decided.	2
misbehavior	repeated Misbehavior	List of information about validators that misbehaved.	3
hash	bytes	The block’s hash.	4
height	int64	The height of the finalized block.	5
time	google.protobuf.Timestamp	Timestamp of the finalized block.	6
next_validators_hash	bytes	Merkle root of the next validator set.	7
proposer_address	bytes	Address of the validator that created the proposal.	8

Response:

Name	Type	Description	Field Number	Deterministic
events	repeated Event	Type & Key-Value events for indexing	1	No
tx_results	repeated ExecTxResult	List of structures containing the data resulting from executing the transactions	2	Yes
validator_updates	repeated ValidatorUpdate	Changes to validator set (set voting power to 0 to remove).	3	Yes
consensus_param_updates	ConsensusParams	Changes to gas, size, and other consensus-related parameters.	4	Yes
app_hash	bytes	The Merkle root hash of the application state.	5	Yes

Usage:
- Contains the fields of the newly decided block.
- This method is equivalent to the call sequence BeginBlock, [DeliverTx], and EndBlock in ABCI 1.0.
- The height and time values match the values from the header of the proposed block.
- The Application can use RequestFinalizeBlock.decided_last_commit and RequestFinalizeBlock.misbehavior to determine rewards and punishments for the validators.
- The Application executes the transactions in RequestFinalizeBlock.txs deterministically, according to the rules set up by the Application, before returning control to CometBFT. Alternatively, it can apply the candidate state corresponding to the same block previously executed via PrepareProposal or ProcessProposal.
- ResponseFinalizeBlock.tx_results[i].Code == 0 only if the i-th transaction is fully valid.
- The Application must provide values for ResponseFinalizeBlock.app_hash, ResponseFinalizeBlock.tx_results, ResponseFinalizeBlock.validator_updates, and ResponseFinalizeBlock.consensus_param_updates as a result of executing the block.
  - The values for ResponseFinalizeBlock.validator_updates, or ResponseFinalizeBlock.consensus_param_updates may be empty. In this case, CometBFT will keep the current values.
  - ResponseFinalizeBlock.validator_updates, triggered by block H, affect validation for blocks H+1, H+2, and H+3. Heights following a validator update are affected in the following way:
    - Height H+1: NextValidatorsHash includes the new validator_updates value.
    - Height H+2: The validator set change takes effect and ValidatorsHash is updated.
    - Height H+3: *_last_commit fields in PrepareProposal, ProcessProposal, and FinalizeBlock now include the altered validator set.
  - ResponseFinalizeBlock.consensus_param_updates returned for block H apply to the consensus params for block H+1. For more information on the consensus parameters, see the consensus parameters section.
- ResponseFinalizeBlock.app_hash contains an (optional) Merkle root hash of the application state.
- ResponseFinalizeBlock.app_hash is included as the Header.AppHash in the next block.
  - ResponseFinalizeBlock.app_hash may also be empty or hard-coded, but MUST be deterministic - it must not be a function of anything that did not come from the parameters of RequestFinalizeBlock and the previous committed state.
- Later calls to Query can return proofs about the application state anchored in this Merkle root hash.
- The implementation of FinalizeBlock MUST be deterministic, since it is making the Application’s state evolve in the context of state machine replication.
- Currently, CometBFT will fill up all fields in RequestFinalizeBlock, even if they were already passed on to the Application via RequestPrepareProposal or RequestProcessProposal.
- When calling FinalizeBlock with a block, the consensus algorithm run by CometBFT guarantees that at least one non-byzantine validator has run ProcessProposal on that block.

When does CometBFT call `FinalizeBlock`?

When a node p is in consensus height h, and p receives

the Proposal message with block v for a round r, along with all its block parts, from q, which is the proposer of round r, height h,
Precommit messages from 2f + 1 validators’ voting power for round r, height h, precommitting the same block id(v),

then p decides block v and finalizes consensus for height h in the following way

p persists v as the decision for height h.
p’s CometBFT calls RequestFinalizeBlock with v’s data. The call is synchronous.
p’s Application executes block v.
p’s Application calculates and returns the AppHash, along with a list containing the outputs of each of the transactions executed.
p’s CometBFT hashes all the transaction outputs and stores it in ResultHash.
p’s CometBFT persists the transaction outputs, AppHash, and ResultsHash.
p’s CometBFT locks the mempool — no calls to CheckTx on new transactions.
p’s CometBFT calls RequestCommit to instruct the Application to persist its state.
p’s CometBFT, optionally, re-checks all outstanding transactions in the mempool against the newly persisted Application state.
p’s CometBFT unlocks the mempool — newly received transactions can now be checked.
p starts consensus for height h+1, round 0

Data Types existing in ABCI

Most of the data structures used in ABCI are shared common data structures. In certain cases, ABCI uses different data structures which are documented here:

Validator

Fields:
Name Type Description Field Number
address bytes Address of validator 1
power int64 Voting power of the validator 3
Usage:
- Validator identified by address
- Used as part of VoteInfo within CommitInfo (used in ProcessProposal and FinalizeBlock), and ExtendedCommitInfo (used in PrepareProposal).
- Does not include PubKey to avoid sending potentially large quantum pubkeys over the ABCI

ValidatorUpdate

Fields:
Name Type Description Field Number Deterministic
pub_key Public Key Public key of the validator 1 Yes
power int64 Voting power of the validator 2 Yes
Usage:
- Validator identified by PubKey
- Used to tell CometBFT to update the validator set

Misbehavior

Fields:

Name	Type	Description	Field Number
type	MisbehaviorType	Type of the misbehavior. An enum of possible misbehaviors.	1
validator	Validator	The offending validator	2
height	int64	Height when the offense occurred	3
time	google.protobuf.Timestamp	Timestamp of the block that was committed at height `height`	4
total_voting_power	int64	Total voting power of the validator set at height `height`	5

MisbehaviorType

Fields MisbehaviorType is an enum with the listed fields:
Name Field Number
UNKNOWN 0
DUPLICATE_VOTE 1
LIGHT_CLIENT_ATTACK 2

ConsensusParams

Fields:

Name	Type	Description	Field Number	Deterministic
block	BlockParams	Parameters limiting the size of a block and time between consecutive blocks.	1	Yes
evidence	EvidenceParams	Parameters limiting the validity of evidence of byzantine behaviour.	2	Yes
validator	ValidatorParams	Parameters limiting the types of public keys validators can use.	3	Yes
version	VersionsParams	The ABCI application version.	4	Yes

ProofOps

Fields:

Name	Type	Description	Field Number	Deterministic
ops	repeated ProofOp	List of chained Merkle proofs, of possibly different types. The Merkle root of one op is the value being proven in the next op. The Merkle root of the final op should equal the ultimate root hash being verified against..	1	N/A

ProofOp

Fields:

Name	Type	Description	Field Number	Deterministic
type	string	Type of Merkle proof and how it’s encoded.	1	N/A
key	bytes	Key in the Merkle tree that this proof is for.	2	N/A
data	bytes	Encoded Merkle proof for the key.	3	N/A

Snapshot

Fields:

Name	Type	Description	Field Number	Deterministic
height	uint64	The height at which the snapshot was taken (after commit).	1	N/A
format	uint32	An application-specific snapshot format, allowing applications to version their snapshot data format and make backwards-incompatible changes. CometBFT does not interpret this.	2	N/A
chunks	uint32	The number of chunks in the snapshot. Must be at least 1 (even if empty).	3	N/A
hash	bytes	An arbitrary snapshot hash. Must be equal only for identical snapshots across nodes. CometBFT does not interpret the hash, it only compares them.	4	N/A
metadata	bytes	Arbitrary application metadata, for example chunk hashes or other verification data.	5	N/A

Usage:
- Used for state sync snapshots, see the state sync section for details.
- A snapshot is considered identical across nodes only if all fields are equal (including Metadata). Chunks may be retrieved from all nodes that have the same snapshot.
- When sent across the network, a snapshot message can be at most 4 MB.

Data types introduced or modified in ABCI++

VoteInfo

Fields:
Name Type Description Field Number
validator Validator The validator that sent the vote. 1
block_id_flag BlockIDFlag Indicates whether the validator voted the last block, nil, or its vote was not received. 3
Usage:
- Indicates whether a validator signed the last block, allowing for rewards based on validator availability.
- This information is typically extracted from a proposed or decided block.

ExtendedVoteInfo

Fields:

Name	Type	Description	Field Number
validator	Validator	The validator that sent the vote.	1
vote_extension	bytes	Non-deterministic extension provided by the sending validator’s Application.	3
extension_signature	bytes	Signature of the vote extension produced by the sending validator and verified by CometBFT.	4
block_id_flag	BlockIDFlag	Indicates whether the validator voted the last block, nil, or its vote was not received.	5

Usage:
- Indicates whether a validator signed the last block, allowing for rewards based on validator availability.
- This information is extracted from CometBFT’s data structures in the local process.
- vote_extension contains the sending validator’s vote extension, whose signature was verified by CometBFT. It can be empty.
- extension_signature is the signature of the vote extension, which was verified verified by CometBFT. This way, we expose the signature to the application for further processing or verification.

CommitInfo

Fields:

Name	Type	Description	Field Number
round	int32	Commit round. Reflects the round at which the block proposer decided in the previous height.	1
votes	repeated VoteInfo	List of validators’ addresses in the last validator set with their voting information.	2

Notes
- The VoteInfo in votes are ordered by the voting power of the validators (descending order, highest to lowest voting power).
- CometBFT guarantees the votes ordering through its logic to update the validator set in which, in the end, the validators are sorted (descending) by their voting power.
- The ordering is also persisted when a validator set is saved in the store.
- The validator set is loaded from the store when building the CommitInfo, ensuring order is maintained from the persisted validator set.

ExtendedCommitInfo

Fields:

Name	Type	Description	Field Number
round	int32	Commit round. Reflects the round at which the block proposer decided in the previous height.	1
votes	repeated ExtendedVoteInfo	List of validators’ addresses in the last validator set with their voting information, including vote extensions.	2

Notes
- The ExtendedVoteInfo in votes are ordered by the voting power of the validators (descending order, highest to lowest voting power).
- CometBFT guarantees the votes ordering through its logic to update the validator set in which, in the end, the validators are sorted (descending) by their voting power.
- The ordering is also persisted when a validator set is saved in the store.
- The validator set is loaded from the store when building the ExtendedCommitInfo, ensuring order is maintained from the persisted validator set.

ExecTxResult

Fields:

Name	Type	Description	Field Number	Deterministic
code	uint32	Response code.	1	Yes
data	bytes	Result bytes, if any.	2	Yes
log	string	The output of the application’s logger.	3	No
info	string	Additional information.	4	No
gas_wanted	int64	Amount of gas requested for transaction.	5	Yes
gas_used	int64	Amount of gas consumed by transaction.	6	Yes
events	repeated Event	Type & Key-Value events for indexing transactions (e.g. by account).	7	No
codespace	string	Namespace for the `code`.	8	Yes

ProposalStatus

enum ProposalStatus {
  UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
  ACCEPT  = 1; // Status that signals that the application finds the proposal valid.
  REJECT  = 2; // Status that signals that the application finds the proposal invalid.
}

Usage:
- Used within the ProcessProposal response.
  - If Status is UNKNOWN, a problem happened in the Application. CometBFT will assume the application is faulty and crash.
  - If Status is ACCEPT, the consensus algorithm accepts the proposal and will issue a Prevote message for it.
  - If Status is REJECT, the consensus algorithm rejects the proposal and will issue a Prevote for nil instead.

VerifyStatus

enum VerifyStatus {
  UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
  ACCEPT  = 1; // Status that signals that the application finds the vote extension valid.
  REJECT  = 2; // Status that signals that the application finds the vote extension invalid.
}

Usage:
- Used within the VerifyVoteExtension response.
  - If Status is UNKNOWN, a problem happened in the Application. CometBFT will assume the application is faulty and crash.
  - If Status is ACCEPT, the consensus algorithm will accept the vote as valid.
  - If Status is REJECT, the consensus algorithm will reject the vote as invalid.

Name	Type	Description	Field Number
snapshot	Snapshot	The snapshot offered for restoration.	1
app_hash	bytes	The light client-verified app hash for this height, from the blockchain.	2

Name	Type	Description	Field Number
address	bytes	Address of validator	1
power	int64	Voting power of the validator	3

Name	Type	Description	Field Number	Deterministic
pub_key	Public Key	Public key of the validator	1	Yes
power	int64	Voting power of the validator	2	Yes

​ABCI 中现有的方法

​Echo

​Flush

​Info

​InitChain

​Query

​CheckTx

​Commit

​参数与类型

​ListSnapshots

​LoadSnapshotChunk

​OfferSnapshot

​Result

​ApplySnapshotChunk

​ABCI 2.0 中引入的新方法

​PrepareProposal

​参数与类型

​CometBFT 在什么时候调用 PrepareProposal？

​ProcessProposal

​参数与类型

​CometBFT 在什么时候调用 ProcessProposal？

​ExtendVote

​参数与类型

​CometBFT 在什么时候调用 ExtendVote？

​VerifyVoteExtension

​参数与类型

​CometBFT 在什么时候调用 VerifyVoteExtension？

​FinalizeBlock

​参数与类型

​CometBFT 在什么时候调用 FinalizeBlock？

​ABCI 中现有的数据类型

​Validator

​ValidatorUpdate

​Misbehavior

​MisbehaviorType

​ConsensusParams

​ProofOps

​ProofOp

​Snapshot

​ABCI++ 中引入或修改的数据类型

​VoteInfo

​ExtendedVoteInfo

​CommitInfo

​ExtendedCommitInfo

​ExecTxResult

​ProposalStatus

​VerifyStatus

​Methods existing in ABCI

​Echo

​Flush

​Info

​InitChain

​Query

​CheckTx

​Commit

​Parameters and Types

​ListSnapshots

​LoadSnapshotChunk

​OfferSnapshot

​Result

​ApplySnapshotChunk

​New methods introduced in ABCI 2.0

​PrepareProposal

​Parameters and Types

​When does CometBFT call “PrepareProposal” ?

​ProcessProposal

​Parameters and Types

​When does CometBFT call “ProcessProposal” ?

​ExtendVote

​Parameters and Types

​When does CometBFT call ExtendVote?

​VerifyVoteExtension

​Parameters and Types

​When does CometBFT call VerifyVoteExtension?

​FinalizeBlock

​Parameters and Types

​When does CometBFT call FinalizeBlock?

​Data Types existing in ABCI

​Validator

​ValidatorUpdate

ABCI 中现有的方法

Echo

Flush

Info

InitChain

Query

CheckTx

Commit

参数与类型

ListSnapshots

LoadSnapshotChunk

OfferSnapshot

Result

ApplySnapshotChunk

ABCI 2.0 中引入的新方法

PrepareProposal

参数与类型

CometBFT 在什么时候调用 `PrepareProposal`？

ProcessProposal

参数与类型

CometBFT 在什么时候调用 `ProcessProposal`？

ExtendVote

参数与类型

CometBFT 在什么时候调用 `ExtendVote`？

VerifyVoteExtension

参数与类型

CometBFT 在什么时候调用 `VerifyVoteExtension`？

FinalizeBlock

参数与类型

CometBFT 在什么时候调用 `FinalizeBlock`？

ABCI 中现有的数据类型

Validator

ValidatorUpdate

Misbehavior

MisbehaviorType

ConsensusParams

ProofOps

ProofOp

Snapshot

ABCI++ 中引入或修改的数据类型

VoteInfo

ExtendedVoteInfo

CommitInfo

ExtendedCommitInfo

ExecTxResult

ProposalStatus

VerifyStatus

Methods existing in ABCI

Echo

Flush

Info

InitChain

Query

CheckTx

Commit

Parameters and Types

ListSnapshots

LoadSnapshotChunk

OfferSnapshot

Result

ApplySnapshotChunk

New methods introduced in ABCI 2.0

PrepareProposal

Parameters and Types

When does CometBFT call “PrepareProposal” ?

ProcessProposal

Parameters and Types

When does CometBFT call “ProcessProposal” ?

ExtendVote

Parameters and Types

When does CometBFT call `ExtendVote`?

VerifyVoteExtension

Parameters and Types

When does CometBFT call `VerifyVoteExtension`?

FinalizeBlock

Parameters and Types

When does CometBFT call `FinalizeBlock`?

Data Types existing in ABCI

Validator

ValidatorUpdate