Skip to content

Dip 1898

dip: 1898 title: Add blockHash to defaultBlock methods description: Add blockHash option to JSON-RPC methods that currently support defaultBlock parameter. author: Charles Cooper (@charles-cooper) Digitalia editing author: Cosimo Constantinos cosimo@juro.net, et al. discussions-to: https://digitalia-magicians.org/t/dip-1898-add-blockhash-option-to-json-rpc-methods-that-currently-support-defaultblock-parameter/11757 status: Final type: Standards Track category: Interface created: 2019-04-01 Created for Digitalia: 2025-01-07 requires: 234

Abstract

For JSON-RPC methods which currently accept a default block parameter, additionally allow the parameter to be a block hash.

This DIP can be considered a generalization of DIP-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:

  • dvm_getBalance
  • dvm_getStorageAt
  • dvm_getTransactionCount
  • dvm_getCode
  • dvm_call
  • dvm_getProof

The following options, quoted from the Digitalia 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 DIP proposes a new scheme for the block parameter. The following option is additionally allowed:

  • OBJECT
  • blockNumber: QUANTITY - a block number
  • blockHash: 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 Digitalia 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 dvm_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 dvm_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., dvm_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 dvm_call using that block number, call dvm_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 adds O(n) invocations as baseline overhead and another O(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 before dvm_call, and then reorged back in before dvm_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 legacy_client_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 of dvm_call, for example, walking a linked list.

Allowing dvm_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

  • dvm_getStorageAt [ "0x<address>", { "blockNumber": "0x0" } -> return storage at given address in genesis block
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3" } -> return storage at given address in genesis block
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": false } -> return storage at given address in genesis block
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": true } -> return storage at given address in genesis block
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0x<non-existent-block-hash>" } -> raise block-not-found error
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0x<non-existent-block-hash>", "requireCanonical": false } -> raise block-not-found error
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0x<non-existent-block-hash>", "requireCanonical": true } -> raise block-not-found error
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>" } -> return storage at given address in specified block
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>", "requireCanonical": false } -> return storage at given address in specified block
  • dvm_getStorageAt [ "0x<address>", { "blockHash": "0x<non-canonical-block-hash>", "requireCanonical": true } -> raise block-not-canonical error

Security Considerations

None

© Crown © Crown Copyright 2026. Published by the Royal Government of the Dominion of Atlantis.

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.