HIP-775: Filter API in JSON-RPC Relay

Author	Georgi Lazarov
Working Group	Nana Essilfie-Conduah, Ivo Yankov, Stoyan Panayotov
Discussions-To	https://github.com/hashgraph/hedera-improvement-proposal/discussions/774
Status	Accepted ⓘ
Needs Council Approval	No ⓘ
Review period ends ⓘ	Wed, 20 Sep 2023 07:00:00 +0000
Type	Standards Track ⓘ
Category	Application ⓘ
Created	2023-08-02
Updated	2023-09-20

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:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_newFilter",
  "params": [
    {
      "address": [
        "0xb59f67a8bff5d8cd03f6ac17265c550ed8f33907"
      ],
      "fromBlock": "0x429d3b",
      "toBlock": "latest",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x00000000000000000000000000b46c2526e227482e2ebb8f4c69e4674d262e75",
        "0x00000000000000000000000054a2d42a40f51259dedd1978f6c118a0f0eff078"
      ]
    }
  ]
}

eth_newFilter success reponse:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x62440eb3b951769ef7cc8abb1d26fbaa"
}

eth_uninstallFilter request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_uninstallFilter",
  "params": [
    "0x62440eb3b951769ef7cc8abb1d26fbaa"
  ],
}

eth_uninstallFilter success reponse:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

eth_uninstallFilter failed reponse:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": false
}

eth_getFilterLogs request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getFilterLogs",
  "params": [
    "0x62440eb3b951769ef7cc8abb1d26fbaa"
  ]
}

eth_getFilterChanges request:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getFilterChanges",
  "params": [
    "0x62440eb3b951769ef7cc8abb1d26fbaa"
  ]
}

eth_getFilterLogs and eth_getFilterChanges success response:

{
  "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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Log response size exceeded."
  }
}

For non-existing filter:

{
  "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
• eth_newFilter in Alchemy
• Filter in ethers

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: