Indexing Transactions
Tenderdash can index committed transaction results and block events for RPC
searches and subscriptions. Transaction events come from ExecTxResult.Events
in the proposal execution results. Block events come from
ResponseProcessProposal.Events. They are published after block finalization;
ResponseFinalizeBlock does not contain an events field.
Each event has a type and string-valued attributes. The search key combines the
event type and attribute key with a dot. An event of type transfer with an
attribute sender=Bob can therefore be queried as transfer.sender='Bob'.
Set an attribute's Index flag to true to include it in event indexes.
For the execution lifecycle, see commit and apply. The event publisher shows how committed proposal results become transaction and block events.
Configuration
Operators can configure indexing via the [tx-index] section. The indexer
field takes a series of supported indexers. If null is included, indexing will
be turned off. All configured indexer names must still be supported.
[tx-index]
# The backend database list to back the indexer.
# If list contains null, meaning no indexer service will be used.
#
# The application will set which txs to index. In some cases a node operator will be able
# to decide which txs to index based on configuration set in the application.
#
# Options:
# 1) "null" (default) - no indexer services.
# 2) "kv" - an indexer backed by key-value storage (see DBBackend).
# - When "kv" is chosen "tx.height" and "tx.hash" will always be indexed.
# indexer = []
Supported Indexers
KV
The kv indexer type is an embedded key-value store supported by the main
underlying Tenderdash database. Using the kv indexer type allows you to query
for block and transaction events directly against Tenderdash's RPC. However, the
query syntax is limited to the supported event-query operators.
Removed PostgreSQL indexer
The psql event indexer is no longer supported. Selecting it, including alongside
kv or null, returns a configuration error. Choose indexer = ["kv"] for local
indexing and RPC searches, or ["null"] to disable indexing. The obsolete
psql-conn key is ignored, so existing Dashmate configurations with an empty
value remain compatible.
Existing PostgreSQL data is not deleted or migrated, and SQL consumers no longer
receive new events. To populate KV indexes, explicitly run tenderdash reindex-event against the retained local blocks and results after selecting kv.
Pruned history cannot be reconstructed by this command.
Default Indexes
The Tenderdash tx and block event indexer indexes a few select reserved events by default.
Transactions
The following indexes are indexed by default:
tx.heighttx.hash
Blocks
The following indexes are indexed by default:
block.height
Adding Events
Return transaction events in the corresponding ExecTxResult in
ResponsePrepareProposal.TxResults / ResponseProcessProposal.TxResults.
For example, an individual transaction result can contain:
result := &abci.ExecTxResult{
Code: 0,
Events: []abci.Event{
{
Type: "transfer",
Attributes: []abci.EventAttribute{
{Key: "sender", Value: "Bob", Index: true},
{Key: "recipient", Value: "Alice", Index: true},
{Key: "note", Value: "payment", Index: false},
},
},
},
}
Here abci refers to github.com/dashpay/tenderdash/abci/types; append result
to the response's transaction results in the same order as the executed
transactions. The kv indexer indexes transfer.sender and
transfer.recipient; transfer.note is not indexed. An empty event type or
attribute key is not indexed. Avoid reserved keys such as tx.hash and
tx.height.
Querying Transactions Events
You can query for a paginated set of transaction by their events by calling the
/tx_search RPC endpoint:
curl "localhost:26657/tx_search?query=\"transfer.sender='Bob'\"&prove=true"
Check out API docs for more information on query syntax and other options.
Subscribing to Transactions
Clients can subscribe to transactions with the given tags via WebSocket by providing
a query to /subscribe RPC endpoint.
{
"jsonrpc": "2.0",
"method": "subscribe",
"id": "0",
"params": {
"query": "transfer.sender='Bob'"
}
}
Check out API docs for more information on query syntax and other options.
Querying Blocks Events
You can query for a paginated set of blocks by their events by calling the
/block_search RPC endpoint:
curl "localhost:26657/block_search?query=\"block.height > 10\""
Check out API docs for more information on query syntax and other options.