Skip to content

Latest commit

 

History

History
925 lines (740 loc) · 72.1 KB

abci++_methods.md

File metadata and controls

925 lines (740 loc) · 72.1 KB
Raw
order title
2
Methods

Methods

Methods existing in ABCI

Echo

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

Flush

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

Info

  • Request:

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

  • Response:

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

  • Usage:

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

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

InitChain

  • Request:

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

  • Response:

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

  • Usage:

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

Query

  • Request:

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

  • Response:

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

  • Usage:

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

CheckTx

  • Request:

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

  • Response:

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

  • Usage:

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

Commit

Parameters and Types

  • Request:

    Commit signals the application to persist application state. It takes no parameters.

  • Response:

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

  • Usage:

    • Signal the Application to persist the application state. Application is expected to persist its state at the end of this call, before calling Commit.
    • Use CommitResponse.retain_height with caution! If all nodes in the network remove historical blocks then this data is permanently lost, and no new nodes will be able to join the network and bootstrap, unless state sync is enabled on the chain. Historical blocks may also be required for other purposes, e.g. auditing, replay of non-persisted heights, light client verification, and so on.

ListSnapshots

  • Request:

    Empty request asking the application for a list of snapshots.

  • Response:

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

  • Usage:

    • Used during state sync to discover available snapshots on peers.
    • See Snapshot data type for details.

LoadSnapshotChunk

  • Request:

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

  • Response:

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

  • Usage:

    • Used during state sync to retrieve snapshot chunks from peers.

OfferSnapshot

  • Request:

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

  • Response:

    Name Type Description Field Number Deterministic
    result Result The result of the snapshot offer. 1 N/A

Result

  enum Result {
    UNKNOWN       = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT        = 1;  // Snapshot is accepted, start applying chunks.
    ABORT         = 2;  // Abort snapshot restoration, and don't try any other snapshots.
    REJECT        = 3;  // Reject this specific snapshot, try others.
    REJECT_FORMAT = 4;  // Reject all snapshots with this `format`, try others.
    REJECT_SENDER = 5;  // Reject all snapshots from all senders of this snapshot, try others.
  }
  • Usage:
    • OfferSnapshot is called when bootstrapping a node using state sync. The application may accept or reject snapshots as appropriate. Upon accepting, CometBFT will retrieve and apply snapshot chunks via ApplySnapshotChunk. The application may also choose to reject a snapshot in the chunk response, in which case it should be prepared to accept further OfferSnapshot calls.
    • Only AppHash can be trusted, as it has been verified by the light client. Any other data can be spoofed by adversaries, so applications should employ additional verification schemes to avoid denial-of-service attacks. The verified AppHash is automatically checked against the restored application at the end of snapshot restoration.
    • For more information, see the Snapshot data type or the state sync section.

ApplySnapshotChunk

  • Request:

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

  • Response:

    Name Type Description Field Number Deterministic
    result Result (see below) The result of applying this chunk. 1 N/A
    refetch_chunks repeated uint32 Refetch and reapply the given chunks, regardless of result. Only the listed chunks will be refetched, and reapplied in sequential order. 2 N/A
    reject_senders repeated string Reject the given P2P senders, regardless of Result. Any chunks already applied will not be refetched unless explicitly requested, but queued chunks from these senders will be discarded, and new chunks or other snapshots rejected. 3 N/A 
  enum Result {
    UNKNOWN         = 0;  // Unknown result, abort all snapshot restoration
    ACCEPT          = 1;  // The chunk was accepted.
    ABORT           = 2;  // Abort snapshot restoration, and don't try any other snapshots.
    RETRY           = 3;  // Reapply this chunk, combine with `RefetchChunks` and `RejectSenders` as appropriate.
    RETRY_SNAPSHOT  = 4;  // Restart this snapshot from `OfferSnapshot`, reusing chunks unless instructed otherwise.
    REJECT_SNAPSHOT = 5;  // Reject this snapshot, try a different one.
  }
  • Usage:
    • The application can choose to refetch chunks and/or ban P2P peers as appropriate. CometBFT will not do this unless instructed by the application.
    • The application may want to verify each chunk, e.g. by attaching chunk hashes in Snapshot.Metadata and/or incrementally verifying contents against AppHash.
    • When all chunks have been accepted, CometBFT will make an ABCI Info call to verify that LastBlockAppHash and LastBlockHeight matches the expected values, and record the AppVersion in the node state. It then switches to block sync or consensus and joins the network.
    • If CometBFT is unable to retrieve the next chunk after some time (e.g. because no suitable peers are available), it will reject the snapshot and try a different one via OfferSnapshot. The application should be prepared to reset and accept it or abort as appropriate.

New methods introduced in ABCI 2.0

PrepareProposal

Parameters and Types

  • Request:

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

  • Response:

    Name Type Description Field Number Deterministic
    txs repeated bytes Possibly modified list of transactions that have been picked as part of the proposed block. 2 No

  • Usage:

    • PrepareProposalRequest's fields txs, misbehavior, height, time, next_validators_hash, and proposer_address are the same as in ProcessProposalRequest and FinalizeBlockRequest.
    • PrepareProposalRequest.local_last_commit is a set of the precommit votes for the previous height, including the ones that led to the decision of the previous block, together with their corresponding vote extensions.
    • The height, time, and proposer_address values match the values from the header of the proposed block.
    • PrepareProposalRequest contains a preliminary set of transactions txs that CometBFT retrieved from the mempool, called raw proposal. The Application can modify this set and return a modified set of transactions via PrepareProposalResponse.txs .
      • The Application can modify the raw proposal: it can reorder, remove or add transactions. Let tx be a transaction in txs (set of transactions within PrepareProposalRequest):
        • If the Application considers that tx should not be proposed in this block, e.g., there are other transactions with higher priority, then it should not include it in PrepareProposalResponse.txs. However, this will not remove tx from the mempool.
        • If the Application wants to add a new transaction to the proposed block, then the Application includes it in PrepareProposalResponse.txs. CometBFT will not add the transaction to the mempool.
      • The Application should be aware that removing and adding transactions may compromise traceability.

        Consider the following example: the Application transforms a client-submitted transaction t1 into a second transaction t2, i.e., the Application asks CometBFT to remove t1 from the block and add t2 to the block. If a client wants to eventually check what happened to t1, it will discover that t1 is not in a committed block (assuming a re-CheckTx evicted it from the mempool), getting the wrong idea that t1 did not make it into a block. Note that t2 will be in a committed block, but unless the Application tracks this information, no component will be aware of it. Thus, if the Application wants traceability, it is its responsibility's to support it. For instance, the Application could attach to a transformed transaction a list with the hashes of the transactions it derives from.

    • The Application MAY configure CometBFT to include a list of transactions in PrepareProposalRequest.txs whose total size in bytes exceeds PrepareProposalRequest.max_tx_bytes. If the Application sets ConsensusParams.Block.MaxBytes to -1, CometBFT will include all transactions currently in the mempool in PrepareProposalRequest.txs, which may not fit in PrepareProposalRequest.max_tx_bytes. Therefore, if the size of PrepareProposalRequest.txs is greater than PrepareProposalRequest.max_tx_bytes, the Application MUST remove transactions to ensure that the PrepareProposalRequest.max_tx_bytes limit is respected by those transactions returned in PrepareProposalResponse.txs. This is specified in Requirement 2.
    • As a result of executing the prepared proposal, the Application may produce block events or transaction events. The Application must keep those events until a block is decided and then pass them on to CometBFT via FinalizeBlockResponse.
    • CometBFT does NOT provide any additional validity checks (such as checking for duplicate transactions).
    • If CometBFT fails to validate the PrepareProposalResponse, CometBFT will assume the Application is faulty and crash.
    • The implementation of PrepareProposal MAY be non-deterministic.

When does CometBFT call "PrepareProposal" ?

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

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

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

ProcessProposal

Parameters and Types

  • Request:

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

  • Response:

    Name Type Description Field Number Deterministic
    status ProposalStatus enum that signals if the application finds the proposal valid. 1 Yes

  • Usage:

    • Contains all information on the proposed block needed to fully execute it.
      • The Application may fully execute the block as though it was handling FinalizeBlock.
      • However, any resulting state changes must be kept as candidate state, and the Application should be ready to discard it in case another block is decided.
    • ProcessProposal is also called at the proposer of a round. Normally the call to ProcessProposal occurs right after the call to PrepareProposal and ProcessProposalRequest matches the block produced based on PrepareProposalResponse (i.e., PrepareProposalRequest.txs equals ProcessProposalRequest.txs). However, no such guarantee is made since, in the presence of failures, ProcessProposalRequest may match PrepareProposalResponse from an earlier invocation or ProcessProposal may not be invoked at all.
    • The height and time values match the values from the header of the proposed block.
    • If ProcessProposalResponse.status is REJECT, consensus assumes the proposal received is not valid.
    • The Application MAY fully execute the block (immediate execution)
    • The implementation of ProcessProposal MUST be deterministic. Moreover, the value of ProcessProposalResponse.status MUST exclusively depend on the parameters passed in the ProcessProposalRequest, and the last committed Application state (see Requirements section).
    • Moreover, application implementers SHOULD always set ProcessProposalResponse.status to ACCEPT, unless they really know what the potential liveness implications of returning REJECT are.

When does CometBFT call "ProcessProposal" ?

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

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

ExtendVote

Parameters and Types

  • Request:

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

  • Response:

    Name Type Description Field Number Deterministic
    vote_extension bytes Information signed by CometBFT. Can have 0 length. 1 No

  • Usage:

    • ExtendVoteResponse.vote_extension is application-generated information that will be signed by CometBFT and attached to the Precommit message.
    • The Application may choose to use an empty vote extension (0 length).
    • The contents of ExtendVoteRequest correspond to the proposed block on which the consensus algorithm will send the Precommit message.
    • ExtendVoteResponse.vote_extension will only be attached to a non-nil Precommit message. If the consensus algorithm is to precommit nil, it will not call ExtendVote.
    • The Application logic that creates the extension can be non-deterministic.

When does CometBFT call ExtendVote?

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

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

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

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

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

VerifyVoteExtension

Parameters and Types

  • Request:

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

  • Response:

    Name Type Description Field Number Deterministic
    status VerifyStatus enum signaling if the application accepts the vote extension 1 Yes

  • Usage:

    • VerifyVoteExtensionRequest.vote_extension can be an empty byte array. The Application's interpretation of it should be that the Application running at the process that sent the vote chose not to extend it. CometBFT will always call VerifyVoteExtension, even for 0 length vote extensions.
    • VerifyVoteExtension is not called for precommit votes sent by the local process.
    • VerifyVoteExtensionRequest.hash refers to a proposed block. There is no guarantee that this proposed block has previously been exposed to the Application via ProcessProposal.
    • If VerifyVoteExtensionResponse.status is REJECT, the consensus algorithm will reject the whole received vote. See the Requirements section to understand the potential liveness implications of this.
    • The implementation of VerifyVoteExtension MUST be deterministic. Moreover, the value of VerifyVoteExtensionResponse.status MUST exclusively depend on the parameters passed in the VerifyVoteExtensionRequest, and the last committed Application state (see Requirements section).
    • Moreover, application implementers SHOULD always set VerifyVoteExtensionResponse.status to ACCEPT, unless they really know what the potential liveness implications of returning REJECT are.

When does CometBFT call VerifyVoteExtension?

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

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

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

FinalizeBlock

Parameters and Types

  • Request:

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

  • Response:

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

  • Usage:

    • Contains the fields of the newly decided block.
    • This method is equivalent to the call sequence BeginBlock, [DeliverTx], and EndBlock in ABCI 1.0.
    • The height and time values match the values from the header of the proposed block.
    • The Application can use FinalizeBlockRequest.decided_last_commit and FinalizeBlockRequest.misbehavior to determine rewards and punishments for the validators.
    • The Application executes the transactions in FinalizeBlockRequest.txs deterministically, according to the rules set up by the Application, before returning control to CometBFT. Alternatively, it can apply the candidate state corresponding to the same block previously executed via PrepareProposal or ProcessProposal.
    • FinalizeBlockResponse.tx_results[i].Code == 0 only if the i-th transaction is fully valid.
    • The Application must provide values for FinalizeBlockResponse.app_hash, FinalizeBlockResponse.tx_results, FinalizeBlockResponse.validator_updates, and FinalizeBlockResponse.consensus_param_updates as a result of executing the block.
      • The values for FinalizeBlockResponse.validator_updates, or FinalizeBlockResponse.consensus_param_updates may be empty. In this case, CometBFT will keep the current values.
      • FinalizeBlockResponse.validator_updates, triggered by block H, affect validation for blocks H+1, H+2, and H+3. Heights following a validator update are affected in the following way:
        • Height H+1: NextValidatorsHash includes the new validator_updates value.
        • Height H+2: The validator set change takes effect and ValidatorsHash is updated.
        • Height H+3: *_last_commit fields in PrepareProposal, ProcessProposal, and FinalizeBlock now include the altered validator set.
      • FinalizeBlockResponse.consensus_param_updates returned for block H apply to the consensus params for block H+1. For more information on the consensus parameters, see the consensus parameters section.
    • FinalizeBlockResponse.app_hash contains an (optional) Merkle root hash of the application state.
    • FinalizeBlockResponse.app_hash is included as the Header.AppHash in the next block.
      • FinalizeBlockResponse.app_hash may also be empty or hard-coded, but MUST be deterministic - it must not be a function of anything that did not come from the parameters of FinalizeBlockRequest and the previous committed state.
    • Later calls to Query can return proofs about the application state anchored in this Merkle root hash.
    • The implementation of FinalizeBlock MUST be deterministic, since it is making the Application's state evolve in the context of state machine replication.
    • Currently, CometBFT will fill up all fields in FinalizeBlockRequest, even if they were already passed on to the Application via PrepareProposalRequest or ProcessProposalRequest.
    • When calling FinalizeBlock with a block, the consensus algorithm run by CometBFT guarantees that at least one non-byzantine validator has run ProcessProposal on that block.
    • FinalizeBlockResponse.next_block_delay - how long CometBFT waits after committing a block, before starting the next height. This includes the time the application and CometBFT take for processing the committed block. In CometBFT terms, this interval gives the proposer a chance to receive some more precommits, even though it already has the required 2/3+.
      • Set to 0 if you want a proposer to make progress as soon as it has all the precommits and the block is processed by the application.
      • Previously timeout_commit in CometBFT config. Set to constant 1s to preserve the old (v0.34 - v1.0) behavior.
    • FinalizeBlockResponse.next_block_delay is a non-deterministic field. This means that each node MAY provide a different value, which is supposed to depend on how long processing is taking at the local node. It's reasonable to use real --wallclock-- time and mandate for the nodes to have synchronized clocks (NTP, or other; PBTS also requires this) for the variable delay to work properly.

When does CometBFT call FinalizeBlock?

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

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

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

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

Data Types (exist before ABCI 2.0)

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

Validator

  • Fields:

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

  • Usage:

    • Validator identified by address
    • Used as part of VoteInfo within CommitInfo (used in ProcessProposal and FinalizeBlock), and ExtendedCommitInfo (used in PrepareProposal).
    • Does not include PubKey to avoid sending potentially large quantum pubkeys over the ABCI

ValidatorUpdate

  • Fields:

    Name Type Description Field Number Deterministic
    power int64 Voting power 2 Yes
    pub_key_type string Public key's type (e.g. "tendermint/PubKeyEd25519") 3 Yes
    pub_key_bytes bytes Public key's bytes 4 Yes

  • Usage:

    • Validator identified by PubKeyType and PubKeyBytes
    • Used to tell CometBFT to update the validator set

Misbehavior

  • Fields:

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

MisbehaviorType

  • Fields

    MisbehaviorType is an enum with the listed fields:

    Name Field Number
    UNKNOWN 0
    DUPLICATE_VOTE 1
    LIGHT_CLIENT_ATTACK 2

ConsensusParams

  • Fields:

    Name Type Description Field Number Deterministic
    block BlockParams Parameters limiting the size of a block and time between consecutive blocks. 1 Yes
    evidence EvidenceParams Parameters limiting the validity of evidence of byzantine behaviour. 2 Yes
    validator ValidatorParams Parameters limiting the types of public keys validators can use. 3 Yes
    version VersionsParams The ABCI application version. 4 Yes
    abci ABCIParams ABCI-related parameters. 5 Yes
    synchrony SynchronyParams Parameters determining the validity bounds of a proposal timestamp. 6 Yes

ProofOps

  • Fields:

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

ProofOp

  • Fields:

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

Snapshot

  • Fields:

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

  • Usage:

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

Data types introduced or modified in ABCI 2.0

VoteInfo

  • Fields:

    Name Type Description Field Number
    validator Validator The validator that sent the vote. 1
    signed_last_block bool Indicates whether or not the validator signed the last block. 2

  • Usage:

    • Indicates whether a validator signed the last block, allowing for rewards based on validator availability.
    • This information is typically extracted from a proposed or decided block.

ExtendedVoteInfo

  • Fields:

    Name Type Description Field Number
    validator Validator The validator that sent the vote. 1
    signed_last_block bool Indicates whether or not the validator signed the last block. 2
    vote_extension bytes Non-deterministic extension provided by the sending validator's Application. 3

  • Usage:

    • Indicates whether a validator signed the last block, allowing for rewards based on validator availability.
    • This information is extracted from CometBFT's data structures in the local process.
    • vote_extension contains the sending validator's vote extension, which is signed by CometBFT. It can be empty

CommitInfo

  • Fields:

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

  • Notes

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

ExtendedCommitInfo

  • Fields:

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

  • Notes

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

ExecTxResult

  • Fields:

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

ProposalStatus

enum ProposalStatus {
  UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
  ACCEPT  = 1; // Status that signals that the application finds the proposal valid.
  REJECT  = 2; // Status that signals that the application finds the proposal invalid.
}
  • Usage:
    • Used within the ProcessProposal response.
      • If Status is UNKNOWN, a problem happened in the Application. CometBFT will assume the application is faulty and crash.
      • If Status is ACCEPT, the consensus algorithm accepts the proposal and will issue a Prevote message for it.
      • If Status is REJECT, the consensus algorithm rejects the proposal and will issue a Prevote for nil instead.

VerifyStatus

enum VerifyStatus {
  UNKNOWN = 0; // Unknown status. Returning this from the application is always an error.
  ACCEPT  = 1; // Status that signals that the application finds the vote extension valid.
  REJECT  = 2; // Status that signals that the application finds the vote extension invalid.
}
  • Usage:
    • Used within the VerifyVoteExtension response.
      • If Status is UNKNOWN, a problem happened in the Application. CometBFT will assume the application is faulty and crash.
      • If Status is ACCEPT, the consensus algorithm will accept the vote as valid.
      • If Status is REJECT, the consensus algorithm will reject the vote as invalid.