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
- When querying state, a block could only be specified by number or by a string like "latest"
- When a reorg occurs, the same block number can point to a different block, causing multiple queries to produce inconsistent results
- To preserve consistency, each query would need to re-verify the hash via eth_getBlockByNumber, or rely on nonstandard extensions
After EIP-1898
- A specific block can be pinpointed exactly by placing an object containing blockHash in the block parameter
- Even if a reorg occurs, multiple queries all read the state of the same block
- The requireCanonical option can also verify whether that block is on the node's current canonical chain
Who is affected
- Wallet & app developers: When splitting a query into multiple state lookups, there is no need to worry about inconsistencies caused by reorgs. Re-verification and retry logic become unnecessary.
- Client (node) teams: Six methods, including eth_getBalance, need to implement the new block parameter format and two kinds of error responses.
- Users: Information such as balances and order lists shown in wallet or exchange UIs will no longer become inconsistent during a chain reorganization.
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.