Plug Chain Documents

# Subscribe

Events are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions.

# Pre-requisite Readings

# SDK and Tendermint Events

It is possible to subscribe to Events via Tendermint's Websocket (opens new window). This is done by calling the subscribe RPC method via Websocket:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "id": "0",
    "params": {
        "query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'"
    }
}

The main eventCategory 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.

These events are triggered from the state package after a block is committed. You can get the full list of event categories here (opens new window).

The type and attribute value of the query allow you to filter the specific event you are looking for. For example, a MsgEthereumTx transaction 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 EIP-55 address (eg: 0x1122334455667788990011223344556677889900).

# Tendermint Websocket

To start a connection with the Tendermint websocket you need to define the address with the --rpc.laddr flag when starting the node (default tcp://127.0.0.1:26657):

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

Then, start a websocket subscription with ws (opens new window)

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

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

# List of Tendermint 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.

List of all Tendermint 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

# Ethereum JSON-RPC Events

Plug Chain also supports the Ethereum JSON-RPC (opens new window) filters calls to subscribe to state logs (opens new window), blocks (opens new window) or pending transactions (opens new window) changes.

Under the hood, it uses the Tendermint RPC client's event system to process subscriptions that are then formatted to Ethereum-compatible events.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545

{"jsonrpc":"2.0","id":1,"result":"0x3503de5f0c766c68f78a03a3b05036a5"}

Then you can check if the state changes with the eth_getFilterChanges (opens new window) call:

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x3503de5f0c766c68f78a03a3b05036a5"],"id":1}' -H "Content-Type: application/json" http://localhost:8545

{"jsonrpc":"2.0","id":1,"result":["0x7d44dceff05d5963b5bc81df7e9f79b27e777b0a03a6feca09f3447b99c6fa71","0x3961e4050c27ce0145d375255b3cb829a5b4e795ac475c05a219b3733723d376","0xd7a497f95167d63e6feca70f344d9f6e843d097b62729b8f43bdcd5febf142ab","0x55d80a4ba6ef54f2a8c0b99589d017b810ed13a1fda6a111e1b87725bc8ceb0e","0x9e8b92c17280dd05f2562af6eea3285181c562ebf41fc758527d4c30364bcbc4","0x7353a4b9d6b35c9eafeccaf9722dd293c46ae2ffd4093b2367165c3620a0c7c9","0x026d91bda61c8789c59632c349b38fd7e7557e6b598b94879654a644cfa75f30","0x73e3245d4ddc3bba48fa67633f9993c6e11728a36401fa1206437f8be94ef1d3"]}

# Ethereum Websocket

Since Plug Chain runs uses Tendermint Core as it's consensus Engine and it's built with the Cosmos SDK framework, it inherits the event format from them. However, in order to support the native Web3 compatibility for websockets of the Ethereum's PubSubAPI (opens new window), Plug Chain needs to cast the Tendermint responses retrieved into the Ethereum types.

You can start a connection with the Ethereum websocket using the --json-rpc.ws-address flag when starting the node (default "0.0.0.0:8546"):

plugchaind start  --json-rpc.address"0.0.0.0:8545" --json-rpc.ws-address="0.0.0.0:8546" --evm.rpc.api="eth,web3,net,txpool,debug" --json-rpc.enable

Then, start a websocket subscription with ws (opens new window)

# connect to tendermint websocet at port 8546 as defined above
ws ws://localhost:8546/

# subscribe to new Ethereum-formatted block Headers
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}
< {"jsonrpc":"2.0","result":"0x44e010cb2c3161e9c02207ff172166ef","id":1}

← Wallets →