EIP-1898 Option to query state by block hash (Add `blockHash` to defaultBlock methods)

Final · Networking & nodes · EIP status Final · created 2019-04-01

Allows the block parameter of JSON-RPC methods that query balances or contract state to accept a block hash in addition to a block number. This removes ambiguity about which block a query is based on.

Why it is needed

Wallets and apps send JSON-RPC requests to a node to read state such as balances, contract code, and storage values. Previously, a block could only be specified by number or by a string like "latest". Because a chain reorganization (reorg) can make the same block number point to a different block, the reference block could change partway through a series of queries. For example, if a wallet queries the sender's and then the recipient's balance right after a transfer, a reorg occurring in between could leave the two balances inconsistent. Since a block hash is unique to each block, specifying by hash ensures that multiple queries always read the state of exactly the same block. This also means the node does not need to store per-client state or maintain a persistent connection.

What changes

Today

After EIP-1898

Who is affected

In depth

Methods affected

Six state-query methods that take a defaultBlock parameter are affected: eth_getBalance, eth_getStorageAt, eth_getTransactionCount, eth_getCode, eth_call, and eth_getProof. Previously, defaultBlock only accepted a hex block number (HEX String) or one of the strings "earliest", "latest", "pending", "safe", or "finalized".

New block parameter format: object

Since a block hash (DATA) and a block number (QUANTITY) are both hex strings, they cannot be distinguished by value alone. So instead of putting the hash directly into a string, a new OBJECT format is defined. The object contains either a blockNumber (QUANTITY) or blockHash (DATA) field. If the block cannot be found, a JSON-RPC error must be returned, with the recommended error code being -32001 (Resource not found).

requireCanonical flag

When using blockHash, an additional boolean field requireCanonical can be supplied, defaulting to false. If false, an error is returned only when the block cannot be found. If true, an error must also be returned when the block is not on the node's canonical chain, with the recommended code being -32000 (Invalid input). The two errors must use different codes so callers can distinguish them. The existence check is performed first: if the block does not exist, the error must be "block not found", not "not canonical".

Backward compatibility and equivalent representations

The existing format remains unchanged and the new object format is simply added, so this is backward compatible. A block number can be specified either as a hex string or in the new object format. The original text states that "earliest", "0x0", { "blockNumber": "0x0" }, { "blockHash": "0xd4e5..." } containing the genesis block hash, and variants with requireCanonical set to true or false, are all equivalent.

Limits of existing workaround strategies

Before this EIP, three strategies were used. First, fixing a block number and checking with eth_getBlockByNumber before every eth_call whether the hash had changed; this costs O(n) extra calls by default and another O(n) calls per retry, and fails to catch cases where a block is reorged out and then reorged back in before the check. Second, relying on logs that can be queried by blockHash, which does not work unless the contract emits an appropriate event. Third, nonstandard extensions such as parity_subscribe, which require a persistent connection, create tight coupling with the node, and cannot handle cases with dependencies between calls, such as traversing a linked list.

Behavior defined by the test cases

Behavior is defined in terms of eth_getStorageAt. For the genesis block, the same storage value is returned regardless of whether it is specified as blockNumber "0x0", by hash, or with requireCanonical true/false. A hash that does not exist always results in a "block not found" error, regardless of requireCanonical. For a non-canonical block hash, if requireCanonical is omitted or false, the storage value of that block is returned; if true, a "block not canonical" error is returned.

Relationship between status and EIP-234

This EIP is a standard finalized with Final status. It requires EIP-234 (requires: 234), which introduced the blockHash parameter for eth_getLogs, and the original text describes this proposal as a generalization of EIP-234: extending hash-based specification, previously only possible for log queries, to state queries in general. It explicitly states there are no security considerations.

Original EIP · ← EIPs