github.com/aakash4dev/cometbft@v0.38.2/spec/abci/abci++_methods.md (about) 1 --- 2 order: 2 3 title: Methods 4 --- 5 6 # Methods 7 8 ## Methods existing in ABCI 9 10 ### Echo 11 12 * **Request**: 13 * `Message (string)`: A string to echo back 14 * **Response**: 15 * `Message (string)`: The input string 16 * **Usage**: 17 * Echo a string to test an abci client/server implementation 18 19 ### Flush 20 21 * **Usage**: 22 * Signals that messages queued on the client should be flushed to 23 the server. It is called periodically by the client 24 implementation to ensure asynchronous requests are actually 25 sent, and is called immediately to make a synchronous request, 26 which returns when the Flush response comes back. 27 28 ### Info 29 30 * **Request**: 31 32 | Name | Type | Description | Field Number | 33 |---------------|--------|------------------------------------------|--------------| 34 | version | string | The CometBFT software semantic version | 1 | 35 | block_version | uint64 | The CometBFT Block Protocol version | 2 | 36 | p2p_version | uint64 | The CometBFT P2P Protocol version | 3 | 37 | abci_version | string | The CometBFT ABCI semantic version | 4 | 38 39 * **Response**: 40 41 | Name | Type | Description | Field Number | 42 |---------------------|--------|-----------------------------------------------------|--------------| 43 | data | string | Some arbitrary information | 1 | 44 | version | string | The application software semantic version | 2 | 45 | app_version | uint64 | The application protocol version | 3 | 46 | last_block_height | int64 | Latest height for which the app persisted its state | 4 | 47 | last_block_app_hash | bytes | Latest AppHash returned by `FinalizeBlock` | 5 | 48 49 * **Usage**: 50 * Return information about the application state. 51 * Used to sync CometBFT with the application during a handshake 52 that happens on startup or on recovery. 53 * The returned `app_version` will be included in the Header of every block. 54 * CometBFT expects `last_block_app_hash` and `last_block_height` to 55 be updated and persisted during `Commit`. 56 57 > Note: Semantic version is a reference to [semantic versioning](https://semver.org/). Semantic versions in info will be displayed as X.X.x. 58 59 ### InitChain 60 61 * **Request**: 62 63 | Name | Type | Description | Field Number | 64 |------------------|-------------------------------------------------|-----------------------------------------------------|--------------| 65 | time | [google.protobuf.Timestamp][protobuf-timestamp] | Genesis time | 1 | 66 | chain_id | string | ID of the blockchain. | 2 | 67 | consensus_params | [ConsensusParams](#consensusparams) | Initial consensus-critical parameters. | 3 | 68 | validators | repeated [ValidatorUpdate](#validatorupdate) | Initial genesis validators, sorted by voting power. | 4 | 69 | app_state_bytes | bytes | Serialized initial application state. JSON bytes. | 5 | 70 | initial_height | int64 | Height of the initial block (typically `1`). | 6 | 71 72 * **Response**: 73 74 | Name | Type | Description | Field Number | 75 |------------------|----------------------------------------------|--------------------------------------------------|--------------| 76 | consensus_params | [ConsensusParams](#consensusparams) | Initial consensus-critical parameters (optional) | 1 | 77 | validators | repeated [ValidatorUpdate](#validatorupdate) | Initial validator set (optional). | 2 | 78 | app_hash | bytes | Initial application hash. | 3 | 79 80 * **Usage**: 81 * Called once upon genesis. 82 * If `ResponseInitChain.Validators` is empty, the initial validator set will be the `RequestInitChain.Validators` 83 * If `ResponseInitChain.Validators` is not empty, it will be the initial 84 validator set (regardless of what is in `RequestInitChain.Validators`). 85 * This allows the app to decide if it wants to accept the initial validator 86 set proposed by CometBFT (ie. in the genesis file), or if it wants to use 87 a different one (perhaps computed based on some application specific 88 information in the genesis file). 89 * Both `RequestInitChain.Validators` and `ResponseInitChain.Validators` are [ValidatorUpdate](#validatorupdate) structs. 90 So, technically, they both are _updating_ the set of validators from the empty set. 91 92 ### Query 93 94 * **Request**: 95 96 | Name | Type | Description | Field Number | 97 |--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 98 | data | bytes | Raw query bytes. Can be used with or in lieu of Path. | 1 | 99 | path | string | Path field of the request URI. Can be used with or in lieu of `data`. Apps MUST interpret `/store` as a query by key on the underlying store. The key SHOULD be specified in the `data` field. Apps SHOULD allow queries over specific types like `/accounts/...` or `/votes/...` | 2 | 100 | height | int64 | The block height for which you want the 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 | 101 | prove | bool | Return Merkle proof with response if possible | 4 | 102 103 * **Response**: 104 105 | Name | Type | Description | Field Number | 106 |-----------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 107 | code | uint32 | Response code. | 1 | 108 | log | string | The output of the application's logger. **May be non-deterministic.** | 3 | 109 | info | string | Additional information. **May be non-deterministic.** | 4 | 110 | index | int64 | The index of the key in the tree. | 5 | 111 | key | bytes | The key of the matching data. | 6 | 112 | value | bytes | The value of the matching data. | 7 | 113 | proof_ops | [ProofOps](#proofops) | Serialized proof for the value data, if requested, to be verified against the `app_hash` for the given Height. | 8 | 114 | 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 | 115 | codespace | string | Namespace for the `code`. | 10 | 116 117 * **Usage**: 118 * Query for data from the application at current or past height. 119 * Optionally return Merkle proof. 120 * Merkle proof includes self-describing `type` field to support many types 121 of Merkle trees and encoding formats. 122 123 ### CheckTx 124 125 * **Request**: 126 127 | Name | Type | Description | Field Number | 128 |------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 129 | tx | bytes | The request transaction bytes | 1 | 130 | 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 | 131 132 * **Response**: 133 134 | Name | Type | Description | Field Number | 135 |------------|-------------------------------------------------------------|-----------------------------------------------------------------------|--------------| 136 | code | uint32 | Response code. | 1 | 137 | data | bytes | Result bytes, if any. | 2 | 138 | gas_wanted | int64 | Amount of gas requested for transaction. | 5 | 139 | codespace | string | Namespace for the `code`. | 8 | 140 | sender | string | The transaction's sender (e.g. the signer) | 9 | 141 | priority | int64 | The transaction's priority (for mempool ordering) | 10 | 142 143 * **Usage**: 144 145 * Technically optional - not involved in processing blocks. 146 * Guardian of the mempool: every node runs `CheckTx` before letting a 147 transaction into its local mempool. 148 * The transaction may come from an external user or another node 149 * `CheckTx` validates the transaction against the current state of the application, 150 for example, checking signatures and account balances, but does not apply any 151 of the state changes described in the transaction. 152 * Transactions where `ResponseCheckTx.Code != 0` will be rejected - they will not be broadcast 153 to other nodes or included in a proposal block. 154 CometBFT attributes no other value to the response code. 155 156 ### Commit 157 158 #### Parameters and Types 159 160 * **Request**: 161 162 | Name | Type | Description | Field Number | 163 |--------|-------|------------------------------------|--------------| 164 165 Commit signals the application to persist application state. It takes no parameters. 166 167 * **Response**: 168 169 | Name | Type | Description | Field Number | 170 |---------------|-------|------------------------------------------------------------------------|--------------| 171 | retain_height | int64 | Blocks below this height may be removed. Defaults to `0` (retain all). | 3 | 172 173 * **Usage**: 174 175 * Signal the Application to persist the application state. 176 Application is expected to persist its state at the end of this call, before calling `ResponseCommit`. 177 * Use `ResponseCommit.retain_height` with caution! If all nodes in the network remove historical 178 blocks then this data is permanently lost, and no new nodes will be able to join the network and 179 bootstrap, unless state sync is enabled on the chain. Historical blocks may also be required for other purposes, e.g. auditing, replay of 180 non-persisted heights, light client verification, and so on. 181 182 ### ListSnapshots 183 184 * **Request**: 185 186 | Name | Type | Description | Field Number | 187 |--------|-------|------------------------------------|--------------| 188 189 Empty request asking the application for a list of snapshots. 190 191 * **Response**: 192 193 | Name | Type | Description | Field Number | 194 |-----------|--------------------------------|--------------------------------|--------------| 195 | snapshots | repeated [Snapshot](#snapshot) | List of local state snapshots. | 1 | 196 197 * **Usage**: 198 * Used during state sync to discover available snapshots on peers. 199 * See `Snapshot` data type for details. 200 201 ### LoadSnapshotChunk 202 203 * **Request**: 204 205 | Name | Type | Description | Field Number | 206 |--------|--------|-----------------------------------------------------------------------|--------------| 207 | height | uint64 | The height of the snapshot the chunk belongs to. | 1 | 208 | format | uint32 | The application-specific format of the snapshot the chunk belongs to. | 2 | 209 | chunk | uint32 | The chunk index, starting from `0` for the initial chunk. | 3 | 210 211 * **Response**: 212 213 | Name | Type | Description | Field Number | 214 |-------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 215 | 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 | 216 217 * **Usage**: 218 * Used during state sync to retrieve snapshot chunks from peers. 219 220 ### OfferSnapshot 221 222 * **Request**: 223 224 | Name | Type | Description | Field Number | 225 |----------|-----------------------|--------------------------------------------------------------------------|--------------| 226 | snapshot | [Snapshot](#snapshot) | The snapshot offered for restoration. | 1 | 227 | app_hash | bytes | The light client-verified app hash for this height, from the blockchain. | 2 | 228 229 * **Response**: 230 231 | Name | Type | Description | Field Number | 232 |--------|-------------------|-----------------------------------|--------------| 233 | result | [Result](#result) | The result of the snapshot offer. | 1 | 234 235 #### Result 236 237 ```protobuf 238 enum Result { 239 UNKNOWN = 0; // Unknown result, abort all snapshot restoration 240 ACCEPT = 1; // Snapshot is accepted, start applying chunks. 241 ABORT = 2; // Abort snapshot restoration, and don't try any other snapshots. 242 REJECT = 3; // Reject this specific snapshot, try others. 243 REJECT_FORMAT = 4; // Reject all snapshots with this `format`, try others. 244 REJECT_SENDER = 5; // Reject all snapshots from all senders of this snapshot, try others. 245 } 246 ``` 247 248 * **Usage**: 249 * `OfferSnapshot` is called when bootstrapping a node using state sync. The application may 250 accept or reject snapshots as appropriate. Upon accepting, CometBFT will retrieve and 251 apply snapshot chunks via `ApplySnapshotChunk`. The application may also choose to reject a 252 snapshot in the chunk response, in which case it should be prepared to accept further 253 `OfferSnapshot` calls. 254 * Only `AppHash` can be trusted, as it has been verified by the light client. Any other data 255 can be spoofed by adversaries, so applications should employ additional verification schemes 256 to avoid denial-of-service attacks. The verified `AppHash` is automatically checked against 257 the restored application at the end of snapshot restoration. 258 * For more information, see the `Snapshot` data type or the [state sync section](../p2p/legacy-docs/messages/state-sync.md). 259 260 ### ApplySnapshotChunk 261 262 * **Request**: 263 264 | Name | Type | Description | Field Number | 265 |--------|--------|-----------------------------------------------------------------------------|--------------| 266 | index | uint32 | The chunk index, starting from `0`. CometBFT applies chunks sequentially. | 1 | 267 | chunk | bytes | The binary chunk contents, as returned by `LoadSnapshotChunk`. | 2 | 268 | sender | string | The P2P ID of the node who sent this chunk. | 3 | 269 270 * **Response**: 271 272 | Name | Type | Description | Field Number | 273 |----------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 274 | result | Result (see below) | The result of applying this chunk. | 1 | 275 | 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 | 276 | 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 | 277 278 ```proto 279 enum Result { 280 UNKNOWN = 0; // Unknown result, abort all snapshot restoration 281 ACCEPT = 1; // The chunk was accepted. 282 ABORT = 2; // Abort snapshot restoration, and don't try any other snapshots. 283 RETRY = 3; // Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate. 284 RETRY_SNAPSHOT = 4; // Restart this snapshot from `OfferSnapshot`, reusing chunks unless instructed otherwise. 285 REJECT_SNAPSHOT = 5; // Reject this snapshot, try a different one. 286 } 287 ``` 288 289 * **Usage**: 290 * The application can choose to refetch chunks and/or ban P2P peers as appropriate. CometBFT 291 will not do this unless instructed by the application. 292 * The application may want to verify each chunk, e.g. by attaching chunk hashes in 293 `Snapshot.Metadata` and/or incrementally verifying contents against `AppHash`. 294 * When all chunks have been accepted, CometBFT will make an ABCI `Info` call to verify that 295 `LastBlockAppHash` and `LastBlockHeight` matches the expected values, and record the 296 `AppVersion` in the node state. It then switches to block sync or consensus and joins the 297 network. 298 * If CometBFT is unable to retrieve the next chunk after some time (e.g. because no suitable 299 peers are available), it will reject the snapshot and try a different one via `OfferSnapshot`. 300 The application should be prepared to reset and accept it or abort as appropriate. 301 302 ## New methods introduced in ABCI 2.0 303 304 ### PrepareProposal 305 306 #### Parameters and Types 307 308 * **Request**: 309 310 | Name | Type | Description | Field Number | 311 |----------------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------|--------------| 312 | max_tx_bytes | int64 | Currently configured maximum size in bytes taken by the modified transactions. | 1 | 313 | txs | repeated bytes | Preliminary list of transactions that have been picked as part of the block to propose. | 2 | 314 | local_last_commit | [ExtendedCommitInfo](#extendedcommitinfo) | Info about the last commit, obtained locally from CometBFT's data structures. | 3 | 315 | misbehavior | repeated [Misbehavior](#misbehavior) | List of information about validators that misbehaved. | 4 | 316 | height | int64 | The height of the block that will be proposed. | 5 | 317 | time | [google.protobuf.Timestamp][protobuf-timestamp] | Timestamp of the block that that will be proposed. | 6 | 318 | next_validators_hash | bytes | Merkle root of the next validator set. | 7 | 319 | proposer_address | bytes | [Address](../core/data_structures.md#address) of the validator that is creating the proposal. | 8 | 320 321 * **Response**: 322 323 | Name | Type | Description | Field Number | 324 |-------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------|--------------| 325 | txs | repeated bytes | Possibly modified list of transactions that have been picked as part of the proposed block. | 2 | 326 327 * **Usage**: 328 * `RequestPrepareProposal`'s parameters `txs`, `misbehavior`, `height`, `time`, 329 `next_validators_hash`, and `proposer_address` are the same as in `RequestProcessProposal` 330 and `RequestFinalizeBlock`. 331 * `RequestPrepareProposal.local_last_commit` is a set of the precommit votes that allowed the 332 decision of the previous block, together with their corresponding vote extensions. 333 * The `height`, `time`, and `proposer_address` values match the values from the header of the 334 proposed block. 335 * `RequestPrepareProposal` contains a preliminary set of transactions `txs` that CometBFT 336 retrieved from the mempool, called _raw proposal_. The Application can modify this 337 set and return a modified set of transactions via `ResponsePrepareProposal.txs` . 338 * The Application _can_ modify the raw proposal: it can reorder, remove or add transactions. 339 Let `tx` be a transaction in `txs` (set of transactions within `RequestPrepareProposal`): 340 * If the Application considers that `tx` should not be proposed in this block, e.g., 341 there are other transactions with higher priority, then it should not include it in 342 `ResponsePrepareProposal.txs`. However, this will not remove `tx` from the mempool. 343 * If the Application wants to add a new transaction to the proposed block, then the 344 Application includes it in `ResponsePrepareProposal.txs`. CometBFT will not add 345 the transaction to the mempool. 346 * The Application should be aware that removing and adding transactions may compromise 347 _traceability_. 348 > Consider the following example: the Application transforms a client-submitted 349 transaction `t1` into a second transaction `t2`, i.e., the Application asks CometBFT 350 to remove `t1` from the block and add `t2` to the block. If a client wants to eventually check what 351 happened to `t1`, it will discover that `t1` is not in a 352 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 353 that `t2` _will be_ in a committed block, but unless the Application tracks this 354 information, no component will be aware of it. Thus, if the Application wants 355 traceability, it is its responsibility's to support it. For instance, the Application 356 could attach to a transformed transaction a list with the hashes of the transactions it 357 derives from. 358 * The Application MAY configure CometBFT to include a list of transactions in `RequestPrepareProposal.txs` 359 whose total size in bytes exceeds `RequestPrepareProposal.max_tx_bytes`. 360 If the Application sets `ConsensusParams.Block.MaxBytes` to -1, CometBFT 361 will include _all_ transactions currently in the mempool in `RequestPrepareProposal.txs`, 362 which may not fit in `RequestPrepareProposal.max_tx_bytes`. 363 Therefore, if the size of `RequestPrepareProposal.txs` is greater than 364 `RequestPrepareProposal.max_tx_bytes`, the Application MUST remove transactions to ensure 365 that the `RequestPrepareProposal.max_tx_bytes` limit is respected by those transactions 366 returned in `ResponsePrepareProposal.txs`. 367 This is specified in [Requirement 2](./abci%2B%2B_app_requirements.md). 368 * As a result of executing the prepared proposal, the Application may produce block events or transaction events. 369 The Application must keep those events until a block is decided and then pass them on to CometBFT via 370 `ResponseFinalizeBlock`. 371 * CometBFT does NOT provide any additional validity checks (such as checking for duplicate 372 transactions). 373 <!-- 374 As a sanity check, CometBFT will check the returned parameters for validity if the Application modified them. 375 In particular, `ResponsePrepareProposal.txs` will be deemed invalid if there are duplicate transactions in the list. 376 --> 377 * If CometBFT fails to validate the `ResponsePrepareProposal`, CometBFT will assume the 378 Application is faulty and crash. 379 * The implementation of `PrepareProposal` can be non-deterministic. 380 381 382 #### When does CometBFT call "PrepareProposal" ? 383 384 385 When a validator _p_ enters consensus round _r_, height _h_, in which _p_ is the proposer, 386 and _p_'s _validValue_ is `nil`: 387 388 1. CometBFT collects outstanding transactions from _p_'s mempool 389 * the transactions will be collected in order of priority 390 * _p_'s CometBFT creates a block header. 391 2. _p_'s CometBFT calls `RequestPrepareProposal` with the newly generated block, the local 392 commit of the previous height (with vote extensions), and any outstanding evidence of 393 misbehavior. The call is synchronous: CometBFT's execution will block until the Application 394 returns from the call. 395 3. The Application uses the information received (transactions, commit info, misbehavior, time) to 396 (potentially) modify the proposal. 397 * the Application MAY fully execute the block and produce a candidate state (immediate execution) 398 * the Application can manipulate transactions: 399 * leave transactions untouched 400 * add new transactions (not present initially) to the proposal 401 * remove transactions from the proposal (but not from the mempool thus effectively _delaying_ them) - the 402 Application does not include the transaction in `ResponsePrepareProposal.txs`. 403 * modify transactions (e.g. aggregate them). As explained above, this compromises client traceability, unless 404 it is implemented at the Application level. 405 * reorder transactions - the Application reorders transactions in the list 406 4. The Application includes the transaction list (whether modified or not) in the return parameters 407 (see the rules in section _Usage_), and returns from the call. 408 5. _p_ uses the (possibly) modified block as _p_'s proposal in round _r_, height _h_. 409 410 Note that, if _p_ has a non-`nil` _validValue_ in round _r_, height _h_, 411 the consensus algorithm will use it as proposal and will not call `RequestPrepareProposal`. 412 413 ### ProcessProposal 414 415 #### Parameters and Types 416 417 * **Request**: 418 419 | Name | Type | Description | Field Number | 420 |----------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------|--------------| 421 | txs | repeated bytes | List of transactions of the proposed block. | 1 | 422 | proposed_last_commit | [CommitInfo](#commitinfo) | Info about the last commit, obtained from the information in the proposed block. | 2 | 423 | misbehavior | repeated [Misbehavior](#misbehavior) | List of information about validators that misbehaved. | 3 | 424 | hash | bytes | The hash of the proposed block. | 4 | 425 | height | int64 | The height of the proposed block. | 5 | 426 | time | [google.protobuf.Timestamp][protobuf-timestamp] | Timestamp of the proposed block. | 6 | 427 | next_validators_hash | bytes | Merkle root of the next validator set. | 7 | 428 | proposer_address | bytes | [Address](../core/data_structures.md#address) of the validator that created the proposal. | 8 | 429 430 * **Response**: 431 432 | Name | Type | Description | Field Number | 433 |-------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------|--------------| 434 | status | [ProposalStatus](#proposalstatus) | `enum` that signals if the application finds the proposal valid. | 1 | 435 436 * **Usage**: 437 * Contains all information on the proposed block needed to fully execute it. 438 * The Application may fully execute the block as though it was handling 439 `RequestFinalizeBlock`. 440 * However, any resulting state changes must be kept as _candidate state_, 441 and the Application should be ready to discard it in case another block is decided. 442 * `RequestProcessProposal` is also called at the proposer of a round. 443 Normally the call to `RequestProcessProposal` occurs right after the call to `RequestPrepareProposal` and 444 `RequestProcessProposal` matches the block produced based on `ResponsePrepareProposal` (i.e., 445 `RequestPrepareProposal.txs` equals `RequestProcessProposal.txs`). 446 However, no such guarantee is made since, in the presence of failures, `RequestProcessProposal` may match 447 `ResponsePrepareProposal` from an earlier invocation or `ProcessProposal` may not be invoked at all. 448 * The height and time values match the values from the header of the proposed block. 449 * If `ResponseProcessProposal.status` is `REJECT`, consensus assumes the proposal received 450 is not valid. 451 * The Application MAY fully execute the block — immediate execution 452 * The implementation of `ProcessProposal` MUST be deterministic. Moreover, the value of 453 `ResponseProcessProposal.status` MUST **exclusively** depend on the parameters passed in 454 the call to `RequestProcessProposal`, and the last committed Application state 455 (see [Requirements](./abci++_app_requirements.md) section). 456 * Moreover, application implementors SHOULD always set `ResponseProcessProposal.status` to `ACCEPT`, 457 unless they _really_ know what the potential liveness implications of returning `REJECT` are. 458 459 #### When does CometBFT call "ProcessProposal" ? 460 461 When a node _p_ enters consensus round _r_, height _h_, in which _q_ is the proposer (possibly _p_ = _q_): 462 463 1. _p_ sets up timer `ProposeTimeout`. 464 2. If _p_ is the proposer, _p_ executes steps 1-6 in [PrepareProposal](#prepareproposal). 465 3. Upon reception of Proposal message (which contains the header) for round _r_, height _h_ from 466 _q_, _p_ verifies the block header. 467 4. Upon reception of Proposal message, along with all the block parts, for round _r_, height _h_ 468 from _q_, _p_ follows the validators' algorithm to check whether it should prevote for the 469 proposed block, or `nil`. 470 5. If the validators' consensus algorithm indicates _p_ should prevote non-nil: 471 1. CometBFT calls `RequestProcessProposal` with the block. The call is synchronous. 472 2. The Application checks/processes the proposed block, which is read-only, and returns 473 `ACCEPT` or `REJECT` in the `ResponseProcessProposal.status` field. 474 * The Application, depending on its needs, may call `ResponseProcessProposal` 475 * either after it has completely processed the block (immediate execution), 476 * or after doing some basic checks, and process the block asynchronously. In this case the 477 Application will not be able to reject the block, or force prevote/precommit `nil` 478 afterwards. 479 * or immediately, returning `ACCEPT`, if _p_ is not a validator 480 and the Application does not want non-validating nodes to handle `ProcessProposal` 481 3. If _p_ is a validator and the returned value is 482 * `ACCEPT`: _p_ prevotes on this proposal for round _r_, height _h_. 483 * `REJECT`: _p_ prevotes `nil`. 484 * 485 486 ### ExtendVote 487 488 #### Parameters and Types 489 490 * **Request**: 491 492 | Name | Type | Description | Field Number | 493 |--------|-------|-------------------------------------------------------------------------------|--------------| 494 | hash | bytes | The header hash of the proposed block that the vote extension is to refer to. | 1 | 495 | height | int64 | Height of the proposed block (for sanity check). | 2 | 496 497 * **Response**: 498 499 | Name | Type | Description | Field Number | 500 |-------------------|-------|---------------------------------------------------------|--------------| 501 | vote_extension | bytes | Information signed by by CometBFT. Can have 0 length. | 1 | 502 503 * **Usage**: 504 * `ResponseExtendVote.vote_extension` is application-generated information that will be signed 505 by CometBFT and attached to the Precommit message. 506 * The Application may choose to use an empty vote extension (0 length). 507 * `RequestExtendVote.hash` corresponds to the hash of a proposed block that was made available 508 to the Application in a previous call to `ProcessProposal` for the current height. 509 * `ResponseExtendVote.vote_extension` will only be attached to a non-`nil` Precommit message. If the consensus algorithm is to 510 precommit `nil`, it will not call `RequestExtendVote`. 511 * The Application logic that creates the extension can be non-deterministic. 512 513 #### When does CometBFT call `ExtendVote`? 514 515 When a validator _p_ is in consensus state _prevote_ of round _r_, height _h_, in which _q_ is the proposer; and _p_ has received 516 517 * the Proposal message _v_ for round _r_, height _h_, along with all the block parts, from _q_, 518 * `Prevote` messages from _2f + 1_ validators' voting power for round _r_, height _h_, prevoting for the same block _id(v)_, 519 520 then _p_ locks _v_ and sends a Precommit message in the following way 521 522 1. _p_ sets _lockedValue_ and _validValue_ to _v_, and sets _lockedRound_ and _validRound_ to _r_ 523 2. _p_'s CometBFT calls `RequestExtendVote` with _id(v)_ (`RequestExtendVote.hash`). The call is synchronous. 524 3. The Application returns an array of bytes, `ResponseExtendVote.extension`, which is not interpreted by the consensus algorithm. 525 4. _p_ sets `ResponseExtendVote.extension` as the value of the `extension` field of type 526 [CanonicalVoteExtension](../core/data_structures.md#canonicalvoteextension), 527 populates the other fields in [CanonicalVoteExtension](../core/data_structures.md#canonicalvoteextension), 528 and signs the populated data structure. 529 5. _p_ constructs and signs the [CanonicalVote](../core/data_structures.md#canonicalvote) structure. 530 6. _p_ constructs the Precommit message (i.e. [Vote](../core/data_structures.md#vote) structure) 531 using [CanonicalVoteExtension](../core/data_structures.md#canonicalvoteextension) 532 and [CanonicalVote](../core/data_structures.md#canonicalvote). 533 7. _p_ broadcasts the Precommit message. 534 535 In the cases when _p_ is to broadcast `precommit nil` messages (either _2f+1_ `prevote nil` messages received, 536 or _timeoutPrevote_ triggered), _p_'s CometBFT does **not** call `RequestExtendVote` and will not include 537 a [CanonicalVoteExtension](../core/data_structures.md#canonicalvoteextension) field in the `precommit nil` message. 538 539 ### VerifyVoteExtension 540 541 #### Parameters and Types 542 543 * **Request**: 544 545 | Name | Type | Description | Field Number | 546 |-------------------|-------|-------------------------------------------------------------------------------------------|--------------| 547 | hash | bytes | The hash of the proposed block that the vote extension refers to. | 1 | 548 | validator_address | bytes | [Address](../core/data_structures.md#address) of the validator that signed the extension. | 2 | 549 | height | int64 | Height of the block (for sanity check). | 3 | 550 | vote_extension | bytes | Application-specific information signed by CometBFT. Can have 0 length. | 4 | 551 552 * **Response**: 553 554 | Name | Type | Description | Field Number | 555 |--------|-------------------------------|----------------------------------------------------------------|--------------| 556 | status | [VerifyStatus](#verifystatus) | `enum` signaling if the application accepts the vote extension | 1 | 557 558 * **Usage**: 559 * `RequestVerifyVoteExtension.vote_extension` can be an empty byte array. The Application's 560 interpretation of it should be 561 that the Application running at the process that sent the vote chose not to extend it. 562 CometBFT will always call `RequestVerifyVoteExtension`, even for 0 length vote extensions. 563 * `RequestVerifyVoteExtension` is not called for precommit votes sent by the local process. 564 * `RequestVerifyVoteExtension.hash` refers to a proposed block. There is not guarantee that 565 this proposed block has previously been exposed to the Application via `ProcessProposal`. 566 * If `ResponseVerifyVoteExtension.status` is `REJECT`, the consensus algorithm will reject the whole received vote. 567 See the [Requirements](./abci++_app_requirements.md) section to understand the potential 568 liveness implications of this. 569 * The implementation of `VerifyVoteExtension` MUST be deterministic. Moreover, the value of 570 `ResponseVerifyVoteExtension.status` MUST **exclusively** depend on the parameters passed in 571 the call to `RequestVerifyVoteExtension`, and the last committed Application state 572 (see [Requirements](./abci++_app_requirements.md) section). 573 * Moreover, application implementers SHOULD always set `ResponseVerifyVoteExtension.status` to `ACCEPT`, 574 unless they _really_ know what the potential liveness implications of returning `REJECT` are. 575 576 #### When does CometBFT call `VerifyVoteExtension`? 577 578 When a node _p_ is in consensus round _r_, height _h_, and _p_ receives a Precommit 579 message for round _r_, height _h_ from validator _q_ (_q_ ≠ _p_): 580 581 1. If the Precommit message does not contain a vote extension with a valid signature, _p_ 582 discards the Precommit message as invalid. 583 * a 0-length vote extension is valid as long as its accompanying signature is also valid. 584 2. Else, _p_'s CometBFT calls `RequestVerifyVoteExtension`. 585 3. The Application returns `ACCEPT` or `REJECT` via `ResponseVerifyVoteExtension.status`. 586 4. If the Application returns 587 * `ACCEPT`, _p_ will keep the received vote, together with its corresponding 588 vote extension in its internal data structures. It will be used to populate the [ExtendedCommitInfo](#extendedcommitinfo) 589 structure in calls to `RequestPrepareProposal`, in rounds of height _h + 1_ where _p_ is the proposer. 590 * `REJECT`, _p_ will deem the Precommit message invalid and discard it. 591 592 ### FinalizeBlock 593 594 #### Parameters and Types 595 596 * **Request**: 597 598 | Name | Type | Description | Field Number | 599 |----------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------|--------------| 600 | txs | repeated bytes | List of transactions committed as part of the block. | 1 | 601 | decided_last_commit | [CommitInfo](#commitinfo) | Info about the last commit, obtained from the block that was just decided. | 2 | 602 | misbehavior | repeated [Misbehavior](#misbehavior) | List of information about validators that misbehaved. | 3 | 603 | hash | bytes | The block's hash. | 4 | 604 | height | int64 | The height of the finalized block. | 5 | 605 | time | [google.protobuf.Timestamp][protobuf-timestamp] | Timestamp of the finalized block. | 6 | 606 | next_validators_hash | bytes | Merkle root of the next validator set. | 7 | 607 | proposer_address | bytes | [Address](../core/data_structures.md#address) of the validator that created the proposal. | 8 | 608 609 * **Response**: 610 611 | Name | Type | Description | Field Number | 612 |-------------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------|--------------| 613 | events | repeated [Event](abci++_basic_concepts.md#events) | Type & Key-Value events for indexing | 1 | 614 | tx_results | repeated [ExecTxResult](#exectxresult) | List of structures containing the data resulting from executing the transactions | 2 | 615 | validator_updates | repeated [ValidatorUpdate](#validatorupdate) | Changes to validator set (set voting power to 0 to remove). | 3 | 616 | consensus_param_updates | [ConsensusParams](#consensusparams) | Changes to gas, size, and other consensus-related parameters. | 4 | 617 | app_hash | bytes | The Merkle root hash of the application state. | 5 | 618 619 * **Usage**: 620 * Contains the fields of the newly decided block. 621 * This method is equivalent to the call sequence `BeginBlock`, [`DeliverTx`], 622 and `EndBlock` in the previous version of ABCI. 623 * The height and time values match the values from the header of the proposed block. 624 * The Application can use `RequestFinalizeBlock.decided_last_commit` and `RequestFinalizeBlock.misbehavior` 625 to determine rewards and punishments for the validators. 626 * The Application executes the transactions in `RequestFinalizeBlock.txs` deterministically, 627 according to the rules set up by the Application, before returning control to CometBFT. 628 Alternatively, it can apply the candidate state corresponding to the same block previously 629 executed via `PrepareProposal` or `ProcessProposal`. 630 * `ResponseFinalizeBlock.tx_results[i].Code == 0` only if the _i_-th transaction is fully valid. 631 * The Application must provide values for `ResponseFinalizeBlock.app_hash`, 632 `ResponseFinalizeBlock.tx_results`, `ResponseFinalizeBlock.validator_updates`, and 633 `ResponseFinalizeBlock.consensus_param_updates` as a result of executing the block. 634 * The values for `ResponseFinalizeBlock.validator_updates`, or 635 `ResponseFinalizeBlock.consensus_param_updates` may be empty. In this case, CometBFT will keep 636 the current values. 637 * `ResponseFinalizeBlock.validator_updates`, triggered by block `H`, affect validation 638 for blocks `H+1`, `H+2`, and `H+3`. Heights following a validator update are affected in the following way: 639 * Height `H+1`: `NextValidatorsHash` includes the new `validator_updates` value. 640 * Height `H+2`: The validator set change takes effect and `ValidatorsHash` is updated. 641 * Height `H+3`: `*_last_commit` fields in `PrepareProposal`, `ProcessProposal`, and 642 `FinalizeBlock` now include the altered validator set. 643 * `ResponseFinalizeBlock.consensus_param_updates` returned for block `H` apply to the consensus 644 params for block `H+1`. For more information on the consensus parameters, 645 see the [consensus parameters](./abci%2B%2B_app_requirements.md#consensus-parameters) 646 section. 647 * `ResponseFinalizeBlock.app_hash` contains an (optional) Merkle root hash of the application state. 648 * `ResponseFinalizeBlock.app_hash` is included as the `Header.AppHash` in the next block. 649 * `ResponseFinalizeBlock.app_hash` may also be empty or hard-coded, but MUST be 650 **deterministic** - it must not be a function of anything that did not come from the parameters 651 of `RequestFinalizeBlock` and the previous committed state. 652 * Later calls to `Query` can return proofs about the application state anchored 653 in this Merkle root hash. 654 * The implementation of `FinalizeBlock` MUST be deterministic, since it is 655 making the Application's state evolve in the context of state machine replication. 656 * Currently, CometBFT will fill up all fields in `RequestFinalizeBlock`, even if they were 657 already passed on to the Application via `RequestPrepareProposal` or `RequestProcessProposal`. 658 659 #### When does CometBFT call `FinalizeBlock`? 660 661 When a node _p_ is in consensus height _h_, and _p_ receives 662 663 * the Proposal message with block _v_ for a round _r_, along with all its block parts, from _q_, 664 which is the proposer of round _r_, height _h_, 665 * `Precommit` messages from _2f + 1_ validators' voting power for round _r_, height _h_, 666 precommitting the same block _id(v)_, 667 668 then _p_ decides block _v_ and finalizes consensus for height _h_ in the following way 669 670 1. _p_ persists _v_ as the decision for height _h_. 671 2. _p_'s CometBFT calls `RequestFinalizeBlock` with _v_'s data. The call is synchronous. 672 3. _p_'s Application executes block _v_. 673 4. _p_'s Application calculates and returns the _AppHash_, along with a list containing 674 the outputs of each of the transactions executed. 675 5. _p_'s CometBFT hashes all the transaction outputs and stores it in _ResultHash_. 676 6. _p_'s CometBFT persists the transaction outputs, _AppHash_, and _ResultsHash_. 677 7. _p_'s CometBFT locks the mempool — no calls to `CheckTx` on new transactions. 678 8. _p_'s CometBFT calls `RequestCommit` to instruct the Application to persist its state. 679 9. _p_'s CometBFT, optionally, re-checks all outstanding transactions in the mempool 680 against the newly persisted Application state. 681 10. _p_'s CometBFT unlocks the mempool — newly received transactions can now be checked. 682 11. _p_ starts consensus for height _h+1_, round 0 683 684 ## Data Types existing in ABCI 685 686 Most of the data structures used in ABCI are shared [common data structures](../core/data_structures.md). In certain cases, ABCI uses different data structures which are documented here: 687 688 ### Validator 689 690 * **Fields**: 691 692 | Name | Type | Description | Field Number | 693 |---------|-------|---------------------------------------------------------------------|--------------| 694 | address | bytes | [Address](../core/data_structures.md#address) of validator | 1 | 695 | power | int64 | Voting power of the validator | 3 | 696 697 * **Usage**: 698 * Validator identified by address 699 * Used as part of VoteInfo within `CommitInfo` (used in `ProcessProposal` and `FinalizeBlock`), 700 and `ExtendedCommitInfo` (used in `PrepareProposal`). 701 * Does not include PubKey to avoid sending potentially large quantum pubkeys 702 over the ABCI 703 704 ### ValidatorUpdate 705 706 * **Fields**: 707 708 | Name | Type | Description | Field Number | 709 |---------|--------------------------------------------------|-------------------------------|--------------| 710 | pub_key | [Public Key](../core/data_structures.md#pub_key) | Public key of the validator | 1 | 711 | power | int64 | Voting power of the validator | 2 | 712 713 * **Usage**: 714 * Validator identified by PubKey 715 * Used to tell CometBFT to update the validator set 716 717 ### Misbehavior 718 719 * **Fields**: 720 721 | Name | Type | Description | Field Number | 722 |--------------------|-------------------------------------------------|------------------------------------------------------------------------------|--------------| 723 | type | [MisbehaviorType](#misbehaviortype) | Type of the misbehavior. An enum of possible misbehaviors. | 1 | 724 | validator | [Validator](#validator) | The offending validator | 2 | 725 | height | int64 | Height when the offense occurred | 3 | 726 | time | [google.protobuf.Timestamp][protobuf-timestamp] | Timestamp of the block that was committed at height `height` | 4 | 727 | total_voting_power | int64 | Total voting power of the validator set at height `height` | 5 | 728 729 #### MisbehaviorType 730 731 * **Fields** 732 733 MisbehaviorType is an enum with the listed fields: 734 735 | Name | Field Number | 736 |---------------------|--------------| 737 | UNKNOWN | 0 | 738 | DUPLICATE_VOTE | 1 | 739 | LIGHT_CLIENT_ATTACK | 2 | 740 741 ### ConsensusParams 742 743 * **Fields**: 744 745 | Name | Type | Description | Field Number | 746 |-----------|---------------------------------------------------------------|------------------------------------------------------------------------------|--------------| 747 | block | [BlockParams](../core/data_structures.md#blockparams) | Parameters limiting the size of a block and time between consecutive blocks. | 1 | 748 | evidence | [EvidenceParams](../core/data_structures.md#evidenceparams) | Parameters limiting the validity of evidence of byzantine behaviour. | 2 | 749 | validator | [ValidatorParams](../core/data_structures.md#validatorparams) | Parameters limiting the types of public keys validators can use. | 3 | 750 | version | [VersionsParams](../core/data_structures.md#versionparams) | The ABCI application version. | 4 | 751 752 ### ProofOps 753 754 * **Fields**: 755 756 | Name | Type | Description | Field Number | 757 |------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 758 | ops | repeated [ProofOp](#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 | 759 760 ### ProofOp 761 762 * **Fields**: 763 764 | Name | Type | Description | Field Number | 765 |------|--------|------------------------------------------------|--------------| 766 | type | string | Type of Merkle proof and how it's encoded. | 1 | 767 | key | bytes | Key in the Merkle tree that this proof is for. | 2 | 768 | data | bytes | Encoded Merkle proof for the key. | 3 | 769 770 ### Snapshot 771 772 * **Fields**: 773 774 | Name | Type | Description | Field Number | 775 |----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| 776 | height | uint64 | The height at which the snapshot was taken (after commit). | 1 | 777 | 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 | 778 | chunks | uint32 | The number of chunks in the snapshot. Must be at least 1 (even if empty). | 3 | 779 | 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 | 780 | metadata | bytes | Arbitrary application metadata, for example chunk hashes or other verification data. | 5 | 781 782 * **Usage**: 783 * Used for state sync snapshots, see the [state sync section](../p2p/legacy-docs/messages/state-sync.md) for details. 784 * A snapshot is considered identical across nodes only if _all_ fields are equal (including 785 `Metadata`). Chunks may be retrieved from all nodes that have the same snapshot. 786 * When sent across the network, a snapshot message can be at most 4 MB. 787 788 ## Data types introduced or modified in ABCI++ 789 790 ### VoteInfo 791 792 * **Fields**: 793 794 | Name | Type | Description | Field Number | 795 |-----------------------------|-------------------------|----------------------------------------------------------------|--------------| 796 | validator | [Validator](#validator) | The validator that sent the vote. | 1 | 797 | signed_last_block | bool | Indicates whether or not the validator signed the last block. | 2 | 798 799 * **Usage**: 800 * Indicates whether a validator signed the last block, allowing for rewards based on validator availability. 801 * This information is typically extracted from a proposed or decided block. 802 803 ### ExtendedVoteInfo 804 805 * **Fields**: 806 807 | Name | Type | Description | Field Number | 808 |-------------------|-------------------------|------------------------------------------------------------------------------|--------------| 809 | validator | [Validator](#validator) | The validator that sent the vote. | 1 | 810 | signed_last_block | bool | Indicates whether or not the validator signed the last block. | 2 | 811 | vote_extension | bytes | Non-deterministic extension provided by the sending validator's Application. | 3 | 812 813 * **Usage**: 814 * Indicates whether a validator signed the last block, allowing for rewards based on validator availability. 815 * This information is extracted from CometBFT's data structures in the local process. 816 * `vote_extension` contains the sending validator's vote extension, which is signed by CometBFT. It can be empty 817 818 ### CommitInfo 819 820 * **Fields**: 821 822 | Name | Type | Description | Field Number | 823 |-------|--------------------------------|----------------------------------------------------------------------------------------------|--------------| 824 | round | int32 | Commit round. Reflects the round at which the block proposer decided in the previous height. | 1 | 825 | votes | repeated [VoteInfo](#voteinfo) | List of validators' addresses in the last validator set with their voting information. | 2 | 826 827 ### ExtendedCommitInfo 828 829 * **Fields**: 830 831 | Name | Type | Description | Field Number | 832 |-------|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------| 833 | round | int32 | Commit round. Reflects the round at which the block proposer decided in the previous height. | 1 | 834 | votes | repeated [ExtendedVoteInfo](#extendedvoteinfo) | List of validators' addresses in the last validator set with their voting information, including vote extensions. | 2 | 835 836 ### ExecTxResult 837 838 * **Fields**: 839 840 | Name | Type | Description | Field Number | 841 |------------|-------------------------------------------------------------|-----------------------------------------------------------------------|--------------| 842 | code | uint32 | Response code. | 1 | 843 | data | bytes | Result bytes, if any. | 2 | 844 | log | string | The output of the application's logger. **May be non-deterministic.** | 3 | 845 | info | string | Additional information. **May be non-deterministic.** | 4 | 846 | gas_wanted | int64 | Amount of gas requested for transaction. | 5 | 847 | gas_used | int64 | Amount of gas consumed by transaction. | 6 | 848 | events | repeated [Event](abci++_basic_concepts.md#events) | Type & Key-Value events for indexing transactions (e.g. by account). | 7 | 849 | codespace | string | Namespace for the `code`. | 8 | 850 851 ### ProposalStatus 852 853 ```proto 854 enum ProposalStatus { 855 UNKNOWN = 0; // Unknown status. Returning this from the application is always an error. 856 ACCEPT = 1; // Status that signals that the application finds the proposal valid. 857 REJECT = 2; // Status that signals that the application finds the proposal invalid. 858 } 859 ``` 860 861 * **Usage**: 862 * Used within the [ProcessProposal](#processproposal) response. 863 * If `Status` is `UNKNOWN`, a problem happened in the Application. CometBFT will assume the application is faulty and crash. 864 * If `Status` is `ACCEPT`, the consensus algorithm accepts the proposal and will issue a Prevote message for it. 865 * If `Status` is `REJECT`, the consensus algorithm rejects the proposal and will issue a Prevote for `nil` instead. 866 867 868 ### VerifyStatus 869 870 ```proto 871 enum VerifyStatus { 872 UNKNOWN = 0; // Unknown status. Returning this from the application is always an error. 873 ACCEPT = 1; // Status that signals that the application finds the vote extension valid. 874 REJECT = 2; // Status that signals that the application finds the vote extension invalid. 875 } 876 ``` 877 878 * **Usage**: 879 * Used within the [VerifyVoteExtension](#verifyvoteextension) response. 880 * If `Status` is `UNKNOWN`, a problem happened in the Application. CometBFT will assume the application is faulty and crash. 881 * If `Status` is `ACCEPT`, the consensus algorithm will accept the vote as valid. 882 * If `Status` is `REJECT`, the consensus algorithm will reject the vote as invalid. 883 884 [protobuf-timestamp]: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp