github.com/okex/exchain@v1.8.0/libs/tendermint/docs/app-dev/indexing-transactions.md (about)

     1  ---
     2  order: 6
     3  ---
     4  
     5  # Indexing Transactions
     6  
     7  Tendermint allows you to index transactions and later query or subscribe
     8  to their results.
     9  
    10  Events can be used to index transactions and blocks according to what happened
    11  during their execution. Note that the set of events returned for a block from
    12  `BeginBlock` and `EndBlock` are merged. In case both methods return the same
    13  type, only the key-value pairs defined in `EndBlock` are used.
    14  
    15  Each event contains a type and a list of attributes, which are key-value pairs
    16  denoting something about what happened during the method's execution. For more
    17  details on `Events`, see the [ABCI]https://github.com/tendermint/spec/blob/master/spec/abci/abci.md#events) documentation.
    18  
    19  An Event has a composite key associated with it. A `compositeKey` is constructed by its type and key separated by a dot.
    20  For example:
    21  
    22  ```json
    23  "jack": [
    24    "account.number": 100
    25  ]
    26  ```
    27  
    28  would be equal to the composite key of `jack.account.number`.
    29  
    30  Let's take a look at the `[tx_index]` config section:
    31  
    32  ```toml
    33  ##### transactions indexer configuration options #####
    34  [tx_index]
    35  
    36  # What indexer to use for transactions
    37  #
    38  # Options:
    39  #   1) "null"
    40  #   2) "kv" (default) - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend).
    41  indexer = "kv"
    42  
    43  # Comma-separated list of composite keys to index (by default the only key is "tx.hash")
    44  #
    45  # You can also index transactions by height by adding "tx.height" key here.
    46  #
    47  # It's recommended to index only a subset of keys due to possible memory
    48  # bloat. This is, of course, depends on the indexer's DB and the volume of
    49  # transactions.
    50  index_keys = ""
    51  
    52  # When set to true, tells indexer to index all compositeKeys (predefined keys:
    53  # "tx.hash", "tx.height" and all keys from DeliverTx responses).
    54  #
    55  # Note this may be not desirable (see the comment above). Indexkeys has a
    56  # precedence over IndexAllKeys (i.e. when given both, IndexKeys will be
    57  # indexed).
    58  index_all_keys = false
    59  ```
    60  
    61  By default, Tendermint will index all transactions by their respective
    62  hashes using an embedded simple indexer. Note, we are planning to add
    63  more options in the future (e.g., PostgreSQL indexer).
    64  
    65  ## Adding Events
    66  
    67  In your application's `DeliverTx` method, add the `Events` field with pairs of
    68  UTF-8 encoded strings (e.g. "transfer.sender": "Bob", "transfer.recipient": "Alice",
    69  "transfer.balance": "100").
    70  
    71  Example:
    72  
    73  ```go
    74  func (app *KVStoreApplication) DeliverTx(req types.RequestDeliverTx) types.Result {
    75      //...
    76      events := []abci.Event{
    77          {
    78              Type: "transfer",
    79              Attributes: kv.Pairs{
    80                  kv.Pair{Key: []byte("sender"), Value: []byte("Bob")},
    81                  kv.Pair{Key: []byte("recipient"), Value: []byte("Alice")},
    82                  kv.Pair{Key: []byte("balance"), Value: []byte("100")},
    83              },
    84          },
    85      }
    86      return types.ResponseDeliverTx{Code: code.CodeTypeOK, Events: events}
    87  }
    88  ```
    89  
    90  If you want Tendermint to only index transactions by "transfer.sender" event type,
    91  in the config set `tx_index.index_tags="transfer.sender"`. If you to index all events,
    92  set `index_all_tags=true`
    93  
    94  Note, there are a few predefined event types:
    95  
    96  - `tx.hash` (transaction's hash)
    97  - `tx.height` (height of the block transaction was committed in)
    98  
    99  Tendermint will throw a warning if you try to use any of the above keys.
   100  
   101  ## Querying Transactions
   102  
   103  You can query the transaction results by calling `/tx_search` RPC endpoint:
   104  
   105  ```shell
   106  curl "localhost:26657/tx_search?query=\"account.name='igor'\"&prove=true"
   107  ```
   108  
   109  Check out [API docs](https://docs.tendermint.com/master/rpc/#/Info/tx_search) for more information
   110  on query syntax and other options.
   111  
   112  ## Subscribing to Transactions
   113  
   114  Clients can subscribe to transactions with the given tags via WebSocket by providing
   115  a query to `/subscribe` RPC endpoint.
   116  
   117  ```json
   118  {
   119    "jsonrpc": "2.0",
   120    "method": "subscribe",
   121    "id": "0",
   122    "params": {
   123      "query": "account.name='igor'"
   124    }
   125  }
   126  ```
   127  
   128  Check out [API docs](https://docs.tendermint.com/master/rpc/#subscribe) for more information
   129  on query syntax and other options.