github.com/ari-anchor/sei-tendermint@v0.0.0-20230519144642-dc826b7b56bb/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 blocks and later query or 8 subscribe to their results. Transactions are indexed by `TxResult.Events` and 9 blocks are indexed by `Response(Begin|End)Block.Events`. However, transactions 10 are also indexed by a primary key which includes the transaction hash and maps 11 to and stores the corresponding `TxResult`. Blocks are indexed by a primary key 12 which includes the block height and maps to and stores the block height, i.e. 13 the block itself is never stored. 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 18 [ABCI](https://github.com/tendermint/tendermint/blob/master/spec/abci/abci.md#events) 19 documentation. 20 21 An `Event` has a composite key associated with it. A `compositeKey` is 22 constructed by its type and key separated by a dot. 23 24 For example: 25 26 ```json 27 "jack": [ 28 "account.number": 100 29 ] 30 ``` 31 32 would be equal to the composite key of `jack.account.number`. 33 34 By default, Tendermint will index all transactions by their respective hashes 35 and height and blocks by their height. 36 37 ## Configuration 38 39 Operators can configure indexing via the `[tx_index]` section. The `indexer` 40 field takes a series of supported indexers. If `null` is included, indexing will 41 be turned off regardless of other values provided. 42 43 ```toml 44 [tx-index] 45 46 # The backend database list to back the indexer. 47 # If list contains null, meaning no indexer service will be used. 48 # 49 # The application will set which txs to index. In some cases a node operator will be able 50 # to decide which txs to index based on configuration set in the application. 51 # 52 # Options: 53 # 1) "null" 54 # 2) "kv" (default) - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend). 55 # - When "kv" is chosen "tx.height" and "tx.hash" will always be indexed. 56 # 3) "psql" - the indexer services backed by PostgreSQL. 57 # indexer = [] 58 ``` 59 60 ### Supported Indexers 61 62 #### KV 63 64 The `kv` indexer type is an embedded key-value store supported by the main 65 underlying Tendermint database. Using the `kv` indexer type allows you to query 66 for block and transaction events directly against Tendermint's RPC. However, the 67 query syntax is limited and so this indexer type might be deprecated or removed 68 entirely in the future. 69 70 #### PostgreSQL 71 72 The `psql` indexer type allows an operator to enable block and transaction event 73 indexing by proxying it to an external PostgreSQL instance allowing for the events 74 to be stored in relational models. Since the events are stored in a RDBMS, operators 75 can leverage SQL to perform a series of rich and complex queries that are not 76 supported by the `kv` indexer type. Since operators can leverage SQL directly, 77 searching is not enabled for the `psql` indexer type via Tendermint's RPC -- any 78 such query will fail. 79 80 Note, the SQL schema is stored in `state/indexer/sink/psql/schema.sql` and operators 81 must explicitly create the relations prior to starting Tendermint and enabling 82 the `psql` indexer type. 83 84 Example: 85 86 ```shell 87 $ psql ... -f state/indexer/sink/psql/schema.sql 88 ``` 89 90 ## Default Indexes 91 92 The Tendermint tx and block event indexer indexes a few select reserved events 93 by default. 94 95 ### Transactions 96 97 The following indexes are indexed by default: 98 99 - `tx.height` 100 - `tx.hash` 101 102 ### Blocks 103 104 The following indexes are indexed by default: 105 106 - `block.height` 107 108 ## Adding Events 109 110 Applications are free to define which events to index. Tendermint does not 111 expose functionality to define which events to index and which to ignore. In 112 your application's `DeliverTx` method, add the `Events` field with pairs of 113 UTF-8 encoded strings (e.g. "transfer.sender": "Bob", "transfer.recipient": 114 "Alice", "transfer.balance": "100"). 115 116 Example: 117 118 ```go 119 func (app *KVStoreApplication) DeliverTx(req types.RequestDeliverTx) types.Result { 120 //... 121 events := []abci.Event{ 122 { 123 Type: "transfer", 124 Attributes: []abci.EventAttribute{ 125 {Key: []byte("sender"), Value: []byte("Bob"), Index: true}, 126 {Key: []byte("recipient"), Value: []byte("Alice"), Index: true}, 127 {Key: []byte("balance"), Value: []byte("100"), Index: true}, 128 {Key: []byte("note"), Value: []byte("nothing"), Index: true}, 129 }, 130 }, 131 } 132 return types.ResponseDeliverTx{Code: code.CodeTypeOK, Events: events} 133 } 134 ``` 135 136 If the indexer is not `null`, the transaction will be indexed. Each event is 137 indexed using a composite key in the form of `{eventType}.{eventAttribute}={eventValue}`, 138 e.g. `transfer.sender=bob`. 139 140 ## Querying Transactions Events 141 142 You can query for a paginated set of transaction by their events by calling the 143 `/tx_search` RPC endpoint: 144 145 ```bash 146 curl "localhost:26657/tx_search?query=\"message.sender='cosmos1...'\"&prove=true" 147 ``` 148 149 Check out [API docs](https://docs.tendermint.com/master/rpc/#/Info/tx_search) 150 for more information on query syntax and other options. 151 152 ## Subscribing to Transactions 153 154 Clients can subscribe to transactions with the given tags via WebSocket by providing 155 a query to `/subscribe` RPC endpoint. 156 157 ```json 158 { 159 "jsonrpc": "2.0", 160 "method": "subscribe", 161 "id": "0", 162 "params": { 163 "query": "message.sender='cosmos1...'" 164 } 165 } 166 ``` 167 168 Check out [API docs](https://docs.tendermint.com/master/rpc/#subscribe) for more information 169 on query syntax and other options. 170 171 ## Querying Blocks Events 172 173 You can query for a paginated set of blocks by their events by calling the 174 `/block_search` RPC endpoint: 175 176 ```bash 177 curl "localhost:26657/block_search?query=\"block.height > 10 AND val_set.num_changed > 0\"" 178 ``` 179 180 Check out [API docs](https://docs.tendermint.com/master/rpc/#/Info/block_search) 181 for more information on query syntax and other options.