EIP-1898: Add `blockHash` to defaultBlock methods
Add `blockHash` option to JSON-RPC methods that currently support defaultBlock parameter.
Abstract
For JSON-RPC methods which currently accept a default block parameter, additionally allow the parameter to be a block hash.
This EIP can be considered a generalization of EIP-234. It would enable clients to unambiguously specify the block they want to query for certain JSON-RPC methods, even if the block is not in the canonical chain. This allows clients to maintain a coherent picture of blockchain state that they are interested in, even in the presence of reorgs, without requiring that the node maintain a persistent connection with the client or store any client-specific state.
Specification
The following JSON-RPC methods are affected:
eth_getBalance
eth_getStorageAt
eth_getTransactionCount
eth_getCode
eth_call
eth_getProof
The following options, quoted from the Ethereum JSON-RPC spec, are currently possible for the defaultBlock parameter:
- HEX String - an integer block number
- String "earliest" for the earliest/genesis block
- String "latest" - for the latest canonical block
- String "pending" - for the pending state/transactions
- String "safe" - for the most recent safe block
- String "finalized" - for the most recent finalized block
Since there is no way to clearly distinguish between a DATA parameter and a QUANTITY parameter, this EIP proposes a new scheme for the block parameter. The following option is additionally allowed:
- OBJECT
blockNumber
: QUANTITY - a block numberblockHash
: DATA - a block hash
If the block is not found, the callee SHOULD raise a JSON-RPC error (the recommended error code is -32001: Resource not found
).
If the tag is blockHash
, an additional boolean field may be supplied to the block parameter, requireCanonical
, which defaults to false
and defines whether the block must be a canonical block according to the callee. If requireCanonical
is false
, the callee should raise a JSON-RPC error only if the block is not found (as described above). If requireCanonical
is true
, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is -32000: Invalid input
and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.
To maintain backwards compatibility, the block number MAY be specified either as a hex string or using the new block parameter scheme. In other words, the following are equivalent for the default block parameter:
"earliest"
"0x0"
{ "blockNumber": "0x0" }
{ "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3" }
(hash of the genesis block on the Ethereum main chain){ "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": true }
{ "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": false }
Rationale
Currently, the state-querying JSON-RPC methods specified above have no option to unambiguously specify which block to query the state for. This can cause issues for applications which need to make multiple calls to the RPC. For instance, a wallet which just executed a transfer may want to display the balances of both the sender and recipient. If there is a re-org in between when the balance of the sender is queried via eth_getBalance
and when the balance of the recipient is queried, the balances may not reconcile. As a slightly more complicated example, the UI for a decentralized exchange (which hosts orders on-chain) may walk a list of orders by calling eth_call
for each of them to get the order data. Another type of use case is where an application needs to make a decision based on multiple pieces of state, e.g. a payout predicated on simultaneous ownership of two NFTs.
In order to ensure that the state is coherent (i.e., eth_call
was called with exactly the same block for every call), the application may currently use one of several strategies:
- Decide on a block number to use (e.g., the latest block number known to the application). After each
eth_call
using that block number, calleth_getBlockByNumber
, also with that block number. If the block hash does not match the known hash for that block number, rollback the current activity and retry from the beginning. This addsO(n)
invocations as baseline overhead and anotherO(n)
invocations for every retry needed. Moreover, there is no way to detect the (unlikely but possible) case that the relevant block was reorged out beforeeth_call
, and then reorged back in beforeeth_getBlockByNumber
. - Rely on logs, which can be queried unambiguously thanks to the
blockHash
parameter. However, this requires semantic support from the smart contract; if the smart contract does not emit appropriate events, the client will not be able to reconstruct the specific state it is interested in. - Rely on non-standard extensions like
parity_subscribe
. This requires a persistent connection between the client and node (via IPC or websockets), increases coupling between the client and the node, and cannot handle use cases where there are dependencies between invocations ofeth_call
, for example, walking a linked list.
Allowing eth_call
and friends to unambiguously specify the block to be queried give the application developer a robust and intuitive way to solve these problems. Multiple sequential queries will query the same state, enabling the application developer to not worry about inconsistencies in their view of the blockchain state.
Backwards Compatibility
Backwards compatible.
Test Cases
eth_getStorageAt [ "0x<address>", { "blockNumber": "0x0" }
-> return storage at given address in genesis blocketh_getStorageAt [ "0x<address>", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3" }
-> return storage at given address in genesis blocketh_getStorageAt [ "0x<address>", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": false }
-> return storage at given address in genesis blocketh_getStorageAt [ "0x<address>", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": true }
-> return storage at given address in genesis blocketh_getStorageAt [ "0x<address>", { "blockHash": "0x<non-existent-block-hash>" }
-> raise block-not-found erroreth_getStorageAt [ "0x<address>", { "blockHash": "0x<non-existent-block-hash>", "requireCanonical": false }
-> raise block-not-found erroreth_getStorageAt [ "0x<address>", { "blockHash": "0x<non-existent-block-hash>", "requireCanonical": true }
-> raise block-not-found erroreth_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>" }
-> return storage at given address in specified blocketh_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>", "requireCanonical": false }
-> return storage at given address in specified blocketh_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>", "requireCanonical": true }
-> raise block-not-canonical error
Security Considerations
None
Copyright
Copyright and related rights waived via CC0.