Subscribe for events via WebSocket.

To tell which events you want, you need to provide a query. query is a string, which has a form: "condition AND condition ..." (no OR at the moment). condition has a form: "key operation operand". key is a string with a restricted set of possible symbols ( \t\n\r\()"'=>< are not allowed). operation can be "=", "<", "<=", ">", ">=", "CONTAINS" AND "EXISTS". operand can be a string (escaped with single quotes), number, date or time.

Examples: tm.event = 'NewBlock' # new blocks tm.event = 'CompleteProposal' # node got a complete proposal tm.event = 'Tx' AND tx.hash = 'XYZ' # single transaction tm.event = 'Tx' AND tx.height = 5 # all txs of the fifth block tx.height = 5 # all txs of the fifth block

Tendermint provides a few predefined keys: tm.event, tx.hash and tx.height. Note for transactions, you can define additional keys by providing events with DeliverTx response.

import ( abci "github.com/tendermint/tendermint/abci/types" "github.com/tendermint/tendermint/libs/pubsub/query" )

abci.ResponseDeliverTx{ Events: []abci.Event{ { Type: "rewards.withdraw", Attributes: []abci.EventAttribute{ {Key: "address", Value: "AddrA", Index: true}, {Key: "source", Value: "SrcX", Index: true}, {Key: "amount", Value: "...", Index: true}, {Key: "balance", Value: "...", Index: true}, }, }, { Type: "rewards.withdraw", Attributes: []abci.EventAttribute{ {Key: "address", Value: "AddrB", Index: true}, {Key: "source", Value: "SrcY", Index: true}, {Key: "amount", Value: "...", Index: true}, {Key: "balance", Value: "...", Index: true}, }, }, { Type: "transfer", Attributes: []abci.EventAttribute{ {Key: "sender", Value: "AddrC", Index: true}, {Key: "recipient", Value: "AddrD", Index: true}, {Key: "amount", Value: "...", Index: true}, }, }, }, }

All events are indexed by a composite key of the form {eventType}.{evenAttrKey}. In the above examples, the following keys would be indexed:

• rewards.withdraw.address
• rewards.withdraw.source
• rewards.withdraw.amount
• rewards.withdraw.balance
• transfer.sender
• transfer.recipient
• transfer.amount

Multiple event types with duplicate keys are allowed and are meant to categorize unique and distinct events. In the above example, all events indexed under the key rewards.withdraw.address will have the following values stored and queryable:

• AddrA
• AddrB

To create a query for txs where address AddrA withdrew rewards: query.MustParse("tm.event = 'Tx' AND rewards.withdraw.address = 'AddrA'")

To create a query for txs where address AddrA withdrew rewards from source Y: query.MustParse("tm.event = 'Tx' AND rewards.withdraw.address = 'AddrA' AND rewards.withdraw.source = 'Y'")

To create a query for txs where AddrA transferred funds: query.MustParse("tm.event = 'Tx' AND transfer.sender = 'AddrA'")

The following queries would return no results: query.MustParse("tm.event = 'Tx' AND transfer.sender = 'AddrZ'") query.MustParse("tm.event = 'Tx' AND rewards.withdraw.address = 'AddrZ'") query.MustParse("tm.event = 'Tx' AND rewards.withdraw.source = 'W'")

import rpchttp "github.com/tendermint/rpc/client/http"
import "github.com/tendermint/tendermint/types"

client, err := rpchttp.New("tcp://0.0.0.0:26657", "/websocket")
if err != nil {
  // handle error
}

err = client.Start()
if err != nil {
  // handle error
}
defer client.Stop()
ctx, cancel := context.WithTimeout(context.Background(), 1 * time.Second)
defer cancel()
query := "tm.event = 'Tx' AND tx.height = 3"
txs, err := client.Subscribe(ctx, "test-client", query)
if err != nil {
  // handle error
}

go func() {
 for e := range txs {
   fmt.Println("got ", e.Data.(types.EventDataTx))
   }
}()

NOTE: if you're not reading events fast enough, Tendermint might terminate the subscription.