github.com/pokt-network/tendermint@v0.32.11-0.20230426215212-59310158d3e9/docs/architecture/adr-002-event-subscription.md (about)

     1  # ADR 2: Event Subscription
     2  
     3  ## Context
     4  
     5  In the light client (or any other client), the user may want to **subscribe to
     6  a subset of transactions** (rather than all of them) using `/subscribe?event=X`. For
     7  example, I want to subscribe for all transactions associated with a particular
     8  account. Same for fetching. The user may want to **fetch transactions based on
     9  some filter** (rather than fetching all the blocks). For example, I want to get
    10  all transactions for a particular account in the last two weeks (`tx's block time >= '2017-06-05'`).
    11  
    12  Now you can't even subscribe to "all txs" in Tendermint.
    13  
    14  The goal is a simple and easy to use API for doing that.
    15  
    16  ![Tx Send Flow Diagram](img/tags1.png)
    17  
    18  ## Decision
    19  
    20  ABCI app return tags with a `DeliverTx` response inside the `data` field (_for
    21  now, later we may create a separate field_). Tags is a list of key-value pairs,
    22  protobuf encoded.
    23  
    24  Example data:
    25  
    26  ```json
    27  {
    28    "abci.account.name": "Igor",
    29    "abci.account.address": "0xdeadbeef",
    30    "tx.gas": 7
    31  }
    32  ```
    33  
    34  ### Subscribing for transactions events
    35  
    36  If the user wants to receive only a subset of transactions, ABCI-app must
    37  return a list of tags with a `DeliverTx` response. These tags will be parsed and
    38  matched with the current queries (subscribers). If the query matches the tags,
    39  subscriber will get the transaction event.
    40  
    41  ```
    42  /subscribe?query="tm.event = Tx AND tx.hash = AB0023433CF0334223212243BDD AND abci.account.invoice.number = 22"
    43  ```
    44  
    45  A new package must be developed to replace the current `events` package. It
    46  will allow clients to subscribe to a different types of events in the future:
    47  
    48  ```
    49  /subscribe?query="abci.account.invoice.number = 22"
    50  /subscribe?query="abci.account.invoice.owner CONTAINS Igor"
    51  ```
    52  
    53  ### Fetching transactions
    54  
    55  This is a bit tricky because a) we want to support a number of indexers, all of
    56  which have a different API b) we don't know whenever tags will be sufficient
    57  for the most apps (I guess we'll see).
    58  
    59  ```
    60  /txs/search?query="tx.hash = AB0023433CF0334223212243BDD AND abci.account.owner CONTAINS Igor"
    61  /txs/search?query="abci.account.owner = Igor"
    62  ```
    63  
    64  For historic queries we will need a indexing storage (Postgres, SQLite, ...).
    65  
    66  ### Issues
    67  
    68  - https://github.com/tendermint/tendermint/issues/376
    69  - https://github.com/tendermint/tendermint/issues/287
    70  - https://github.com/tendermint/tendermint/issues/525 (related)
    71  
    72  ## Status
    73  
    74  proposed
    75  
    76  ## Consequences
    77  
    78  ### Positive
    79  
    80  - same format for event notifications and search APIs
    81  - powerful enough query
    82  
    83  ### Negative
    84  
    85  - performance of the `match` function (where we have too many queries / subscribers)
    86  - there is an issue where there are too many txs in the DB
    87  
    88  ### Neutral