blockTag

BlockTag is a reference parameter used in blockchain APIs to designate a specific block in the chain for read operations. It identifies a point in time in the blockchain, either by explicit block height (a numeric block number) or by a relative label such as latest, earliest, or pending. The blockTag allows clients to query historical state or the current tentative state, depending on the label used.

In practice, Ethereum and other EVM-compatible networks expose a blockTag in methods like eth_getBalance, eth_getStorageAt, eth_getTransactionCount, and eth_getBlockByNumber (as well as similar wrappers in Web3 and Ethers libraries). The value can be a hex-encoded block number (for example 0x1A) or one of the predefined tokens like "latest" or "pending" (and sometimes "earliest"). The exact set of accepted values can vary by client implementation. Providing a numerical blockTag returns data as of the end of that block; using "latest" returns data as of the most recently mined block, while "pending" reflects the currently pending state, including unconfirmed transactions.

BlockTag is conceptually separate from specifying a block by its hash. Some operations require a blockTag, while others can target a specific block hash for historical queries.

Limitations and considerations include potential reorgs: a chain reorganization can invalidate data fetched with a blockTag if the referenced block is dropped. Performance can also be impacted when querying very old blocks, as the client may need to access archived state. BlockTag is a common, practical tool for point-in-time reads in blockchains and is widely supported by major clients and libraries.