Filter API in JSON-RPC Relay

HIP/hip-775.md

@@ -0,0 +1,273 @@
+---
+hip: 775
+title: Filter API in JSON-RPC Relay
+author: Georgi Lazarov <georgi.lazarov@limechain.tech>
+working-group: Nana Essilfie-Conduah<nana@swirldslabs.com>, Ivo Yankov <ivo.yankov@limechain.tech>, Stoyan Panayotov <stoyan.panayotov@limechain.tech>
+type: Standards Track
+category: Application
+needs-council-approval: No
+status: Last Call
+last-call-date-time: 2023-09-20T07:00:00Z
+created: 2023-08-02
+discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/774
+updated: 2023-09-06
+---
+
+## Abstract
+
+Provide a way for users to receive information when state changes (logs) occur, by specifying them with filter and later polling using the same filter.
+
+## Motivation
+
+The JSON-RPC Relay enables clients to query for particular events, but they have to provide new params on every request.
+
+Currently, in order to retrieve newly created contract logs developers need to constantly query the `eth_getLogs` method. This requires custom logic on developer side, to provide new parameters for this events on every poll.
+
+By adding Filter API in the JSON-RPC Relay, developers can provide a filter once, which can consist of multiple parameters, like `topics`, `blockHash`, `fromBlock`, `toBlock` and `address`. Then they'd need only to poll for new events by the given `filterId`.
+
+## Rationale
+
+This HIP proposes the implementation of addtional methods in the JSON-RPC Relay, like `eth_newFilter`, which will allow users to set a filter by which events will be provided using the associated `filterId`.
+Additionally, an `eth_uninstallFilter` method will be needed to be able to delete previously created filters.
+
+In order for user to recieve events using already created `filterId`, another methods needs to be implemented: `eth_getFilterChanges` and `eth_getFilterLogs`.
+
+`eth_getFilterChanges` is a polling method, which returns an array of logs which occurred since last poll.
+`eth_getFilterLogs` is a polling method, which returns an array of all logs matching filter with given id.
+
+Every filter will use up cache, so a limiting mechanism will be implemented, which will delete filter after some configurable time of inactivity.
+
+## User stories
+
+1. As a developer building applications on top of the Hedera Network, I want to be able to poll for events without using web socket service.
+2. As a developer building applications on top of the Hedera Network, I want to be able to poll for events without changing the parameters on every poll.
+3. As a developer I want to be able to create and delete filters.
+
+## Specification
+
+Creation of new filters is possible by calling the `eth_newBlockFilter` or `eth_newFilter` method with the filter parameters, like `address`, `topics`, `blockHash` or `toBlock` and/or `fromBlock`. When filter is created a unique `filterId` is generated and returned to the caller. This `filterId` alongside the filter parameters is saved in the cache.
+
+After the process of creating new filter is done, developers can use endpoints `eth_getFilterChanges` or `eth_getFilterLogs` to poll for new events depending on their already configured filters. Every poll will renew the inactivity duration of the filter.
+
+Developers will be able to remove filter by calling `eth_uninstallFilter` method, which will remove the filter from the cache and return true, if filter was not found will return false.
+
+Initially the Relay needs to support only the `logs` event.
+
+No parameters needed for `eth_newBlockFilter` method.
+
+Parameters accepted in the `eth_newFilter` method are:
+
+- blockHash - Using blockHash is equivalent to fromBlock = toBlock = the block number with hash blockHash. If blockHash is present in the filter criteria, then neither fromBlock nor toBlock are allowed.
+- address - Contract address or a list of addresses from which logs should originate.
+- fromBlock - Either the hex value of a block number OR block tags.
+- toBlock - Either the hex value of a block number OR block tags.
+- topics - Array of 32 Bytes DATA topics. Topics are order-dependent. Each topic can also be an array of DATA with "or" options.
+
+Parameters accepted in `eth_uninstallFilter`, `eth_getFilterChanges` and `eth_getFilterLogs` methods are:
+
+- hex formated `filterId`.
+
+### eth_newFilter request:
+
+```JSON
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_newFilter",
+  "params": [
+    {
+      "address": [
+        "0xb59f67a8bff5d8cd03f6ac17265c550ed8f33907"
+      ],
+      "fromBlock": "0x429d3b",
+      "toBlock": "latest",
+      "topics": [
+        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+        "0x00000000000000000000000000b46c2526e227482e2ebb8f4c69e4674d262e75",
+        "0x00000000000000000000000054a2d42a40f51259dedd1978f6c118a0f0eff078"
+      ]
+    }
+  ]
+}
+```
+
+### eth_newFilter success reponse:
+
+```JSON
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": "0x62440eb3b951769ef7cc8abb1d26fbaa"
+}
+
+```
+
+### eth_uninstallFilter request:
+
+```JSON
+
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_uninstallFilter",
+  "params": [
+    "0x62440eb3b951769ef7cc8abb1d26fbaa"
+  ],
+}
+
+```
+
+### eth_uninstallFilter success reponse:
+
+```JSON
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": true
+}
+
+```
+
+### eth_uninstallFilter failed reponse:
+
+```JSON
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": false
+}
+
+```
+
+### eth_getFilterLogs request:
+
+```JSON
+
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_getFilterLogs",
+  "params": [
+    "0x62440eb3b951769ef7cc8abb1d26fbaa"
+  ]
+}
+
+```
+
+### eth_getFilterChanges request:
+
+```JSON
+
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "eth_getFilterChanges",
+  "params": [
+    "0x62440eb3b951769ef7cc8abb1d26fbaa"
+  ]
+}
+
+```
+
+### eth_getFilterLogs and eth_getFilterChanges success response:
+
+```JSON
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": [
+    {
+      "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
+      "blockHash": "0x8243343df08b9751f5ca0c5f8c9c0460d8a9b6351066fae0acbd4d3e776de8bb",
+      "blockNumber": "0x429d3b",
+      "data": "0x00000000000000000000000000000000000000000000006194049f30f7200000",
+      "logIndex": "0x1",
+      "removed": false,
+      "topics": [
+        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+        "0x000000000000000000000000e4c8eb504eeeffb8a0468318a96d565d7521aef3",
+        "0x0000000000000000000000004a7a5c1f34c57b9d1e0993e83060b6736f6a42bd"
+      ],
+      "transactionHash": "0x78356eec0d6ed3087e277538811f604c329be8217c5b5e007e4eeb3dba973bff",
+      "transactionIndex": "0x2"
+    }
+  ]
+}
+
+```
+
+### eth_getFilterLogs and eth_getFilterChanges failed response:
+
+For existing filter:
+
+```JSON
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,
+    "message": "Log response size exceeded."
+  }
+}
+
+```
+
+For non-existing filter:
+
+```JSON
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32000,
+    "message": "filter not found"
+  }
+}
+
+```
+
+### eth_getFilterChanges success response:
+
+### Limits
+
+There will one main type of limitation. Value will be configurable via environment variables:
+
+- filter inactivity - Filters will be deleted after a certain duration for inactivity.
+- logs return size limitation on `eth_getFilterLogs` and `eth_getFilterChanges` is the same as `eth_getLogs`.
+- existing filter limitations.
+
+## Backwards Compatibility
+
+There are no sources of backward incompatibility as this HIP simply introduces new functionality to the JSON-RPC Relay.
+
+## Security Implications
+
+No security implications noted.
+
+## How to Teach This
+
+Describe the new methods in the JSON-RPC Relay documentation.
+
+## Reference Implementation
+
+## Rejected Ideas
+
+## Open Issues
+
+None.
+
+## References
+
+- [eth_newFilter in QuickNode](https://www.quicknode.com/docs/ethereum/eth_newFilter)
+- [eth_newFilter in Alchemy](https://docs.alchemy.com/reference/eth-newfilter)
+- [Filter in ethers](https://docs.ethers.org/v6/api/providers/#Filter)
+
+## Copyright/license
+
+This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)