You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

89 lines
2.7 KiB

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