Methods

    Methods existing in ABCI

    Echo

    Flush

    Info

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

    InitChain

    Query

    CheckTx

    Commit

    Parameters and Types

    ListSnapshots

    LoadSnapshotChunk

    OfferSnapshot

    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.
  }

    ApplySnapshotChunk

      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.
  }

    New methods introduced in ABCI 2.0

    PrepareProposal

    Parameters and Types

    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 RequestPrepareProposal with the newly generated block, the local commit of the previous height (with vote extensions), and any outstanding evidence of misbehavior. The call is synchronous: CometBFT’s execution will block until the Application returns from the call.
    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 ResponsePrepareProposal.txs.
        • modify transactions (e.g. aggregate them). As explained above, this compromises client traceability, unless it is implemented at the Application level.
        • reorder transactions - the Application reorders transactions in the list
      • the Application MAY use the vote extensions in the commit info to modify the proposal, in which case it is suggested that extensions be validated in the same maner as done in VerifyVoteExtension, since extensions of votes included in the commit info after the minimum of +2/3 had been reached are not verified.
    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 RequestPrepareProposal.

    ProcessProposal

    Parameters and Types

    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-6 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 RequestProcessProposal with the block. The call is synchronous.
      2. The Application checks/processes the proposed block, which is read-only, and returns ACCEPT or REJECT in the ResponseProcessProposal.status field.
        • The Application, depending on its needs, may call ResponseProcessProposal
          • either after it has completely processed the block (immediate execution),
          • or after doing some basic checks, and process the block asynchronously. In this case the Application will not be able to reject the block, or force prevote/precommit nil afterwards.
          • or immediately, returning ACCEPT, if p is not a validator and the Application does not want non-validating nodes to handle ProcessProposal
      3. If p is a validator and the returned value is
        • ACCEPT: p prevotes on this proposal for round r, height h.
        • REJECT: p prevotes nil. *

    ExtendVote

    Parameters and Types

    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

    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 RequestExtendVote with v (RequestExtendVote). The call is synchronous.
    3. The Application returns an array of bytes, ResponseExtendVote.extension, which is not interpreted by the consensus algorithm.
    4. p sets ResponseExtendVote.extension as the value of the extension field of type CanonicalVoteExtension, populates the other fields in CanonicalVoteExtension, and signs the populated data structure.
    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 RequestExtendVote and will not include a CanonicalVoteExtension field in the precommit nil message.

    VerifyVoteExtension

    Parameters and Types

    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 RequestVerifyVoteExtension.
    3. The Application returns ACCEPT or REJECT via ResponseVerifyVoteExtension.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 RequestPrepareProposal, in rounds of height h + 1 where p is the proposer.
      • REJECT, p will deem the Precommit message invalid and discard it.

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

    FinalizeBlock

    Parameters and Types

    When does CometBFT call FinalizeBlock?

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

    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 RequestFinalizeBlock 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 RequestCommit 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 existing in ABCI

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

    Validator

    ValidatorUpdate

    Misbehavior

    MisbehaviorType

    ConsensusParams

    ProofOps

    ProofOp

    Snapshot

    Data types introduced or modified in ABCI++

    VoteInfo

    ExtendedVoteInfo

    CommitInfo

    ExtendedCommitInfo

    ExecTxResult

    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.
}

    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.
}
    Decorative Orb