Block Number vs Block Hash in Ethereum Queries
Learn when to use a block number or hash, how reorganisations change a height, and how to pin related Ethereum reads to one block.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A block number identifies a position; a block hash identifies a particular block. That distinction matters when an application combines balances, receipts and logs into a single result. The same height can refer to a different block after a reorganisation.
Choose a position or an identity
Use a height when asking for the block currently accepted at a position. Use a hash when reproducing an observation of a specific block. A timestamp describes neither identity nor finality. Keep the network identifier with either reference: block 100 on one chain has no relationship to block 100 on another.
Worked example: a changing height
A service reads balance 12 at height 900, hash A. Before it retrieves logs, the accepted block at 900 becomes hash B. Combining the first balance with the second set of logs produces an inconsistent answer. Capture A first, use supported hash-based state queries, and verify that fetched receipts belong to A.
An implementation checklist
Persist chain ID, height, hash and observation time. Where supported, EIP-1898 allows an object containing blockHash for state queries; requireCanonical can request a canonicality check. Handle a rejected or unavailable block explicitly. Hash pinning improves consistency, but does not itself promise that the block will remain canonical.
A practical acceptance test
Create a fixture in which height 900 changes from hash A to hash B between calls. Assert that the aggregate either uses A consistently or fails its canonicality policy. It must never silently combine a balance from A with logs from B. Repeat the test with the same height on another chain to catch cache-namespace collisions.
Questions about the topic
Frequently asked questions
Is a block number unique?
Only as a height within a specified chain, not as an immutable block identity across reorganisations.
Should every request use a hash?
Use one when consistency or reproducibility requires a particular block; ordinary latest-state views may accept a changing head.
Standards & technical documentation
