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