From eec9f142b56739bccc94a6ecffb88f0b616b00ff Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 30 May 2018 13:10:04 +0400 Subject: [PATCH] [docs] indexing transactions and subscribing to events Refs #1643 --- docs/index.rst | 2 + docs/indexing-transactions.rst | 100 +++++++++++++++++++ docs/subscribing-to-events-via-websocket.rst | 28 ++++++ 3 files changed, 130 insertions(+) create mode 100644 docs/indexing-transactions.rst create mode 100644 docs/subscribing-to-events-via-websocket.rst diff --git a/docs/index.rst b/docs/index.rst index 2bed07446..a9b207a12 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -55,6 +55,8 @@ Tendermint 102 abci-spec.rst app-architecture.rst app-development.rst + subscribing-to-events-via-websocket.rst + indexing-transactions.rst how-to-read-logs.rst Tendermint 201 diff --git a/docs/indexing-transactions.rst b/docs/indexing-transactions.rst new file mode 100644 index 000000000..2487a771c --- /dev/null +++ b/docs/indexing-transactions.rst @@ -0,0 +1,100 @@ +Indexing Transactions +===================== + +Tendermint allows you to index transactions and later query or subscribe to +their results. + +Let's take a look at the ``[tx_index]`` config section: + +:: + + ##### transactions indexer configuration options ##### + [tx_index] + + # What indexer to use for transactions + # + # Options: + # 1) "null" (default) + # 2) "kv" - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend). + indexer = "kv" + + # Comma-separated list of tags to index (by default the only tag is tx hash) + # + # It's recommended to index only a subset of tags due to possible memory + # bloat. This is, of course, depends on the indexer's DB and the volume of + # transactions. + index_tags = "" + + # When set to true, tells indexer to index all tags. Note this may be not + # desirable (see the comment above). IndexTags has a precedence over + # IndexAllTags (i.e. when given both, IndexTags will be indexed). + index_all_tags = false + +By default, Tendermint will index all transactions by their respective hashes +using an embedded simple indexer. Note, we are planning to add more options in +the future (e.g., Postgresql indexer). + +Adding tags +----------- + +In your application's ``DeliverTx`` method, add the ``Tags`` field with the +pairs of UTF-8 encoded strings (e.g. "account.owner": "Bob", "balance": +"100.0", "date": "2018-01-02"). + +Example: + +:: + + func (app *KVStoreApplication) DeliverTx(tx []byte) types.Result { + ... + tags := []cmn.KVPair{ + {[]byte("account.name"), []byte("igor")}, + {[]byte("account.address"), []byte("0xdeadbeef")}, + {[]byte("tx.amount"), []byte("7")}, + } + return types.ResponseDeliverTx{Code: code.CodeTypeOK, Tags: tags} + } + +If you want Tendermint to only index transactions by "account.name" tag, in the +config set ``tx_index.index_tags="account.name"``. If you to index all tags, +set ``index_all_tags=true`` + +Note, there are a few predefined tags: + +- ``tm.event`` (event type) +- ``tx.hash`` (transaction's hash) +- ``tx.height`` (height of the block transaction was committed in) + +Tendermint will throw a warning if you try to use any of the above keys. + +Quering transactions +-------------------- + +You can query the transaction results by calling ``/tx_search`` RPC endpoint: + +:: + + curl "localhost:46657/tx_search?query=\"account.name='igor'\"&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": "account.name='igor'" + } + } + +Check out `API docs `__ for more +information on query syntax and other options. diff --git a/docs/subscribing-to-events-via-websocket.rst b/docs/subscribing-to-events-via-websocket.rst new file mode 100644 index 000000000..f99d94b66 --- /dev/null +++ b/docs/subscribing-to-events-via-websocket.rst @@ -0,0 +1,28 @@ +Subscribing to events via Websocket +=================================== + +Tendermint emits different events, to which you can subscribe via `Websocket +`__. This can be useful for +third-party applications (for analysys) or inspecting state. + +`List of events `__ + +You can subscribe to any of the events above by calling ``subscribe`` RPC method via Websocket. + +:: + + { + "jsonrpc": "2.0", + "method": "subscribe", + "id": "0", + "params": { + "query": "tm.event='NewBlock'" + } + } + +Check out `API docs `__ for more +information on query syntax and other options. + +You can also use tags, given you had included them into DeliverTx response, to +query transaction results. See `Indexing transactions +<./indexing-transactions.html>`__ for details.