Message (string)
: A string to echo backMessage (string)
: The input stringRequest:
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:
app_version
will be included in the Header of every block.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.
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:
InitChainResponse.Validators
is empty, the initial validator set will be the InitChainRequest.Validators
InitChainResponse.Validators
is not empty, it will be the initial
validator set (regardless of what is in InitChainRequest.Validators
).InitChainRequest.Validators
and InitChainResponse.Validators
are ValidatorUpdate structs.
So, technically, they both are updating the set of validators from the empty set.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:
type
field to support many types
of Merkle trees and encoding formats.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:
CheckTx
before letting a
transaction into its local mempool.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.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.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:
Commit
.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.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:
Snapshot
data type for details.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:
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 |
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.
}
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.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.Snapshot
data type or the state sync section.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.
}
Snapshot.Metadata
and/or incrementally verifying contents against AppHash
.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.OfferSnapshot
.
The application should be prepared to reset and accept it or abort as appropriate.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.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
.
tx
be a transaction in txs
(set of transactions within PrepareProposalRequest
):
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.PrepareProposalResponse.txs
. CometBFT will not add
the transaction to the mempool.Consider the following example: the Application transforms a client-submitted transaction
t1
into a second transactiont2
, i.e., the Application asks CometBFT to removet1
from the block and addt2
to the block. If a client wants to eventually check what happened tot1
, it will discover thatt1
is not in a committed block (assuming a re-CheckTx evicted it from the mempool), getting the wrong idea thatt1
did not make it into a block. Note thatt2
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.
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.FinalizeBlockResponse
.PrepareProposalResponse
, CometBFT will assume the
Application is faulty and crash.PrepareProposal
MAY be non-deterministic.When a validator p enters consensus round r, height h, in which p is the proposer,
and p’s validValue is nil
:
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.PrepareProposalResponse.txs
.VerifyVoteExtension
, since extensions of votes included
in the commit info after the minimum of +2/3 had been reached are not verified.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
.
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:
FinalizeBlock
.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.ProcessProposalResponse.status
is REJECT
, consensus assumes the proposal received
is not valid.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).ProcessProposalResponse.status
to ACCEPT
,
unless they really know what the potential liveness implications of returning REJECT
are.When a node p enters consensus round r, height h, in which q is the proposer (possibly p = q):
ProposeTimeout
.nil
.ProcessProposal
with the block. The call is synchronous.ACCEPT
or REJECT
in the ProcessProposalResponse.status
field.
ProcessProposal
nil
afterwards.ACCEPT
, if p is not a validator
and the Application does not want non-validating nodes to handle ProcessProposal
ACCEPT
: p prevotes on this proposal for round r, height h.REJECT
: p prevotes nil
.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.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
.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
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
ExtendVote
with v (in ExtendVoteRequest
). The call is synchronous.ExtendVoteResponse.extension
, which is not interpreted by the consensus algorithm.ExtendVoteResponse.extension
as the value of the extension
field of type
CanonicalVoteExtension,
populates the other fields in CanonicalVoteExtension,
and signs the populated data structure.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.
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
.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.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).VerifyVoteExtensionResponse.status
to ACCEPT
,
unless they really know what the potential liveness implications of returning REJECT
are.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):
VerifyVoteExtension
.ACCEPT
or REJECT
via VerifyVoteExtensionResponse.status
.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.
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:
BeginBlock
, [DeliverTx
],
and EndBlock
in ABCI 1.0.FinalizeBlockRequest.decided_last_commit
and FinalizeBlockRequest.misbehavior
to determine rewards and punishments for the validators.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.FinalizeBlockResponse.app_hash
,
FinalizeBlockResponse.tx_results
, FinalizeBlockResponse.validator_updates
, and
FinalizeBlockResponse.consensus_param_updates
as a result of executing the block.
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:
H+1
: NextValidatorsHash
includes the new validator_updates
value.H+2
: The validator set change takes effect and ValidatorsHash
is updated.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.Query
can return proofs about the application state anchored
in this Merkle root hash.FinalizeBlock
MUST be deterministic, since it is
making the Application’s state evolve in the context of state machine replication.FinalizeBlockRequest
, even if they were
already passed on to the Application via PrepareProposalRequest
or ProcessProposalRequest
.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+.
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.FinalizeBlock
?When a node p is in consensus height h, and p receives
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
FinalizeBlock
with v’s data. The call is synchronous.CheckTx
on new transactions.Commit
to instruct the Application to persist its state.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:
Fields:
Name | Type | Description | Field Number |
---|---|---|---|
address | bytes | Address of validator | 1 |
power | int64 | Voting power of the validator | 3 |
Usage:
CommitInfo
(used in ProcessProposal
and FinalizeBlock
),
and ExtendedCommitInfo
(used in PrepareProposal
).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:
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 |
Fields
MisbehaviorType is an enum with the listed fields:
Name | Field Number |
---|---|
UNKNOWN | 0 |
DUPLICATE_VOTE | 1 |
LIGHT_CLIENT_ATTACK | 2 |
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 |
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 |
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 |
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:
Metadata
). Chunks may be retrieved from all nodes that have the same snapshot.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:
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:
vote_extension
contains the sending validator’s vote extension, which is signed by CometBFT. It can be emptyFields:
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
VoteInfo
in votes
are ordered by the voting power of the validators (descending order, highest to lowest voting power).votes
ordering through its logic to update the validator set in which, in the end, the validators are sorted (descending) by their voting power.CommitInfo
, ensuring order is maintained from the persisted validator set.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
ExtendedVoteInfo
in votes
are ordered by the voting power of the validators (descending order, highest to lowest voting power).votes
ordering through its logic to update the validator set in which, in the end, the validators are sorted (descending) by their voting power.ExtendedCommitInfo
, ensuring order is maintained from the persisted validator set.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 |
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.
}
Status
is UNKNOWN
, a problem happened in the Application. CometBFT will assume the application is faulty and crash.Status
is ACCEPT
, the consensus algorithm accepts the proposal and will issue a Prevote message for it.Status
is REJECT
, the consensus algorithm rejects the proposal and will issue a Prevote for nil
instead.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.
}
Status
is UNKNOWN
, a problem happened in the Application. CometBFT will assume the application is faulty and crash.Status
is ACCEPT
, the consensus algorithm will accept the vote as valid.Status
is REJECT
, the consensus algorithm will reject the vote as invalid.