CometBFT RPC

The CometBFT RPC allows you to query transactions, blocks, consensus state, broadcast transactions, etc.

The latest CometBFT RPC documentations can be found here. CometBFT supports the following RPC protocols:

URI over HTTP
JSON-RPC over HTTP
JSON-RPC over Websockets

The docs will contain an interactive Swagger interface.

URI/HTTP

A GET request with arguments encoded as query parameters:

curl localhost:26657/block?height=5

RPC/HTTP

JSONRPC requests can be POST'd to the root RPC endpoint via HTTP. See the list of supported CometBFT RPC endpoints using Swagger here.

RPC/Websocket

Cosmos and CometBFT Events

Events are objects that contain information about the execution of the application and are triggered after a block is committed. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions. You can get the full list of event categories and values here.

Subscribing to Events via Websocket

CometBFT Core provides a Websocket connection to subscribe or unsubscribe to CometBFT Events. To start a connection with the CometBFT websocket you need to define the address with the --rpc.laddr flag when starting the node (default tcp://127.0.0.1:26657):

haqqd start --rpc.laddr="tcp://127.0.0.1:26657"

Then, start a websocket subscription with ws

# connect to tendermint websocket at port 8080
ws ws://localhost:8080/websocket

# subscribe to new CometBFT block headers
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlockHeader'"], "id": 1 }

The type and attribute value of the query allow you to filter the specific event you are looking for. For example, an Ethereum transaction on HAQQ (MsgEthereumTx) triggers an event of type ethermint and has sender and recipient as attributes. Subscribing to this event would be done like so:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "id": "0",
    "params": {
        "query": "tm.event='Tx' AND ethereum.recipient='hexAddress'"
    }
}

where hexAddress is an Ethereum hex address (eg: 0x1122334455667788990011223344556677889900).

The generic syntax looks like this:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "id": "0",
    "params": {
        "query": "tm.event='<event_value>' AND eventType.eventAttribute='<attribute_value>'"
    }
}

List of CometBFT Events

The main events you can subscribe to are:

NewBlock: Contains events triggered during BeginBlock and EndBlock.
Tx: Contains events triggered during DeliverTx (i.e. transaction processing).
ValidatorSetUpdates: Contains validator set updates for the block.

tip

👉 The list of events types and values for each Cosmos SDK module can be found in the Modules Specification section. Check the Events page to obtain the event list of each supported module on HAQQ Network.

List of all CometBFT event keys:

	Event Type	Categories
Subscribe to a specific event	`"tm.event"`	`block`
Subscribe to a specific transaction	`"tx.hash"`	`block`
Subscribe to transactions at a specific block height	`"tx.height"`	`block`
Index `BeginBlock` and `Endblock` events	`"block.height"`	`block`
Subscribe to ABCI `BeginBlock` events	`"begin_block"`	`block`
Subscribe to ABCI `EndBlock` events	`"end_block"`	`consensus`

Below is a list of values that you can use to subscribe for the tm.event type:

	Event Value	Categories
New block	`"NewBlock"`	`block`
New block header	`"NewBlockHeader"`	`block`
New Byzantine Evidence	`"NewEvidence"`	`block`
New transaction	`"Tx"`	`block`
Validator set updated	`"ValidatorSetUpdates"`	`block`
Block sync status	`"BlockSyncStatus"`	`consensus`
lock	`"Lock"`	`consensus`
New consensus round	`"NewRound"`	`consensus`
Polka	`"Polka"`	`consensus`
Relock	`"Relock"`	`consensus`
State sync status	`"StateSyncStatus"`	`consensus`
Timeout propose	`"TimeoutPropose"`	`consensus`
Timeout wait	`"TimeoutWait"`	`consensus`
Unlock	`"Unlock"`	`consensus`
Block is valid	`"ValidBlock"`	`consensus`
Consensus vote	`"Vote"`	`consensus`

Example

ws ws://localhost:26657/websocket
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='ValidatorSetUpdates'"], "id": 1 }

Example response:

{
    "jsonrpc": "2.0",
    "id": 0,
    "result": {
        "query": "tm.event='ValidatorSetUpdates'",
        "data": {
            "type": "tendermint/event/ValidatorSetUpdates",
            "value": {
              "validator_updates": [
                {
                  "address": "09EAD022FD25DE3A02E64B0FE9610B1417183EE4",
                  "pub_key": {
                    "type": "tendermint/PubKeyEd25519",
                    "value": "ww0z4WaZ0Xg+YI10w43wTWbBmM3dpVza4mmSQYsd0ck="
                  },
                  "voting_power": "10",
                  "proposer_priority": "0"
                }
              ]
            }
        }
    }
}

tip

Note: When querying Ethereum transactions versus Cosmos transactions, the transaction hashes are different. When querying Ethereum transactions, users need to use event query. Here's an example with the CLI:

curl -X GET "http://localhost:26657/tx_search?query=ethereum_tx.ethereumTxHash%3D0x8d43464891fac6c113e809e14dff1a3e608eae124d629799e42ca0e36562d9d7&prove=false&page=1&per_page=30&order_by=asc" -H "accept: application/json"

CometBFT RPC

URI/HTTP​

RPC/HTTP​

RPC/Websocket​

Cosmos and CometBFT Events​

Subscribing to Events via Websocket​

List of CometBFT Events​

Example​