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