EIP-234 Adding the blockHash Option to JSON-RPC Filters (Add `blockHash` to JSON-RPC filter options.)

Final · Networking & nodes · EIP status Final · created 2017-03-24

This adds a blockHash option to the filter options used for log queries (eth_getLogs, eth_newFilter), allowing logs for a specific block to be queried precisely by block hash instead of block number.

Why it is needed

Decentralized apps set filters on nodes to receive new logs. However, if the connection drops or the node restarts, the filter state is lost, and if a chain reorganization (reorg, where recent blocks are replaced by other blocks) occurs in the meantime, the app never learns about the deleted logs. To avoid this, an app can keep track of recent blocks itself and query logs by block number, but if a reorg happens at the moment of the query, it will receive logs from a different block with the same number. In particular, if the result is an empty array, there is no way to tell whether the original block simply had no logs or whether the wrong block was queried, so recovery cannot be guaranteed. This EIP removes this uncertainty by allowing logs to be queried by block hash.

What changes

Today

After EIP-234

Who is affected

In depth

Specification of the blockHash Parameter

This adds an optional parameter, blockHash, to the filter options used by eth_newFilter (eth_getLogs uses the same options). Its value is a single block hash. If the node receiving the request cannot find a block with that hash, it returns an error; if it finds one, it returns the logs matching the filter conditions as usual, restricted to that single block. The source explains that internally, this is expected to behave similarly to the fromBlock and toBlock options.

Mutual Exclusivity with fromBlock/toBlock

Specifying a block hash together with a block number range has no meaning. The source therefore states that blockHash should be mutually exclusive with fromBlock and toBlock and cannot be used together with them. Since this adds an option without changing existing fields, this is the full extent of the backward compatibility concern.

Limitations of Number-Based Queries

Relying solely on subscriptions and filters cannot reliably capture both log additions and removals. If a reorganization occurs while a WebSocket connection is down, removal notifications cannot be received, and the same problem occurs with HTTP polling if the node restarts and a reorganization overlaps between polls. Querying logs by number can return logs from a different block that was reorganized in the meantime; if logs are present, they can at least be filtered by the block hash inside the logs, but if an empty array is returned, there is no way to distinguish whether it is genuinely empty or an empty result from an unknown block due to a bloom filter false positive. The source's core argument is that neither assumption offers a choice that guarantees recovery.

Recommended Client Design

The robust design the source proposes is as follows. The client keeps the most recent n blocks internally and subscribes to or polls only for new blocks. When a new block arrives, it compares it against its internal model to fill in parents or roll back blocks, keeping itself in sync. This approach can handle any combination of disconnections, reorganizations, and failures. It also has the side benefit of not being tied to a single node and can round-robin across multiple nodes. Combined with hash-based log queries, a returned result is guaranteed to belong to that block, and if an error is returned, the client can respond clearly by rolling back that block and fetching the latest one again.

Error Response Format

If no block with the requested hash exists, an error is returned with code -32000, message "Block not found.", and data set to the requested block hash. If the block exists, all of that block's logs are returned, and adding topics to the filter options returns only logs filtered to match the condition.

Status and Implementation

This EIP was created on March 24, 2017, and its status is confirmed as Final. It is a standard in the Interface category and requires EIP-1474. The source indicates that Geth has completed the implementation.

Original EIP · ← EIPs