---

order: 2 title: 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
  lane_priorities	map<string, uint32>	Map of lane identifiers and their corresponding priorities	6	N/A
  default_lane	uint32	The identifier of the default lane	7	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.
  • The application does not have to define lane_priorities. In that case, CometBFT will assign all transactions to one lane.
  • lane_priorities is empty if and only if default_lane is empty.
  • default_lane has to be one of the identifiers defined in lane_priorities.
  • The lowest priority a lane can have is 1. The value 0 is reserved for when applications do not assign lanes (empty lane_id in ResponseCheckTx).

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][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
  lane_id	string	The id of the lane to which the transaction is assigned.	12	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.
  • If lane_id is an empty string, it means that the application did not set any lane in the response message, so the transaction will be assigned to the default lane.
  • The value of lane_id has to be in the range of lanes defined by the application in ResponseInfo.

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 |

Excerpt (19913 of 78205 characters). Read the whole page on CometBFT specification ↗