Subscribing to Events

A Tenderdash node emits events about important state transitions during consensus. These events can be queried by clients via the RPC interface on nodes that enable it. The list of supported event types can be found in the github.com/dashpay/tenderdash/types Go package.

There are two APIs to query events:

  • The legacy streaming API, comprising the subscribe, unsubscribe, and unsubscribe_all RPC methods over websocket.

  • The event log API, comprising the events RPC method.

The event log API supports polling and pagination. Use the API supported by your node and client; the sections below describe both interfaces.

Filter Queries

Event requests take a filter query parameter. A filter query is a string that describes a subset of available event items to return. An empty query matches all events; otherwise a query comprises one or more terms comparing event metadata to target values.

For example, to select new block events, use the term:

tm.event = 'NewBlock'

Multiple terms can be combined with AND (case matters), for example to match the transaction event with a given hash, use the query:

tm.event = 'Tx' AND tx.hash = 'EA7B33F'

Operands may be strings in single quotes ('Tx'), numbers (45), dates, or timestamps.

The comparison operators include =, <, <=, >, >=, and CONTAINS (for substring match). In addition, the EXISTS operator checks for the presence of an attribute regardless of its value.

Attributes

Tenderdash implicitly defines a string-valued tm.event attribute for all event types. Transaction items (type Tx) are also assigned tx.hash (string), giving the hash of the transaction, and and tx.height (number) giving the height of the block containing the transaction. For NewBlock and NewBlockHeader events, Tenderdash defines a block.height attribute giving the height of the block.

Additional attributes can be provided by the application as ABCI Event records in ResponseProcessProposal.Events for block events and ExecTxResult.Events for transaction events. These events are published after finalization; ResponseFinalizeBlock has no events field. The full name of the attribute in the query is formed by combining the type and attribute key with a period.

For example, given the events

[]abci.Event{{
    Type: "reward",
    Attributes: []abci.EventAttribute{
        {Key: "address", Value: "example-address"},
        {Key: "amount", Value: "45.62"},
        {Key: "balance", Value: "100.390001"},
    },
}}

a query may refer to the names reward.address, reward.amount, and reward.balance, as in:

reward.address EXISTS AND reward.balance > 45

Certain application-specific metadata are also indexed for offline queries. See Indexing transactions for more details.

Event Log API

When the rpc.event-log-window-size configuration is enabled, the node maintains maintains a log of all events within this operator-defined time window. This API supersedes the websocket subscription API described below.

Clients can query these events can by long-polling the /events RPC method, which returns the most recent items from the log that match the request parameters. Each item returned includes a cursor that marks its location in the log. Cursors can be passed via the before and after parameters to fetch events earlier in the log.

For example, this request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events",
  "params": {
    "filter": {
      "query": "tm.event = 'Tx' AND app.key = 'applesauce'"
    },
    "maxItems": 1,
    "after": ""
  }
}

will return a result similar to the following:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "items": [
      {
        "cursor": "16ee3d5e65be53d8-03d5",
        "event": "Tx",
        "data": {
          "type": "tendermint/event/Tx",
          "value": {
            "height": 70,
            "tx": "YXBwbGVzYXVjZT1zeXJ1cA==",
            "result": {
              "events": [
                {
                  "type": "app",
                  "attributes": [
                    {
                      "key": "creator",
                      "value": "Example User",
                      "index": true
                    },
                    {
                      "key": "key",
                      "value": "applesauce",
                      "index": true
                    },
                    {
                      "key": "index_key",
                      "value": "index is working",
                      "index": true
                    },
                    {
                      "key": "noindex_key",
                      "value": "index is working",
                      "index": false
                    }
                  ]
                }
              ]
            }
          }
        }
      }
    ],
    "more": false,
    "oldest": "16ee3d4c471c3b00-0001",
    "newest": "16ee3d5f2e05a4e0-0400"
  }
}

The "items" array gives the matching items (up to the requested "maxResults") in decreasing time order (i.e., newest to oldest). In this case, there is only one result, but if there are additional results that were not returned, the "more" flag will be true. Calling /events again with the same query and "after" set to the cursor of the newest result (in this example, "16ee3d5e65be53d8-03d5") will fetch newer results.

Go clients can use the eventstream package to simplify the use of this method. The eventstream.Stream automatically handles polling for new events, updating the cursor, and reporting any missed events.

Legacy Streaming API

For a polling interface, use the event log API. See ADR 075 for design context.

To subscribe to events in the streaming API, you must connect to the node RPC service using a websocket. From the command line you can use a tool such as wscat, for example:

wscat ws://127.0.0.1:26657/websocket

To subscribe to events, call the subscribe JSON-RPC method method passing in a filter query for the events you wish to receive:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": 1,
  "params": {
    "query": "tm.event='NewBlock'"
  }
}

The subscribe method returns an initial response confirming the subscription, then sends additional JSON-RPC response messages containing the matching events as they are published. The subscription continues until either the client explicitly cancels the subscription (by calling unsubscribe or unsubscribe_all) or until the websocket connection is terminated.