✨ Feat: Add getBlockByTag to Chain package

packages/blockchain/package.json

@@ -65,6 +65,7 @@
 		"@ethereumjs/blockchain": "^7.2.0",
 		"@tevm/block": "workspace:^",
 		"@tevm/common": "workspace:^",
+		"@tevm/errors": "workspace:^",
 		"@tevm/jsonrpc": "workspace:^",
 		"@tevm/logger": "workspace:^",
 		"@tevm/trie": "workspace:^",

packages/blockchain/src/Chain.ts

@@ -1,6 +1,6 @@
 import { type BlockchainEvents, type Consensus, type OnBlock } from '@ethereumjs/blockchain'
 import type { Block, BlockHeader } from '@tevm/block'
-import type { AsyncEventEmitter } from '@tevm/utils'
+import type { AsyncEventEmitter, BlockTag, Hex } from '@tevm/utils'
 import type { BaseChain } from './BaseChain.js'
 
 /**
@@ -41,6 +41,20 @@ export type Chain = {} & BaseChain & {
 		 */
 		getBlock(blockId: Uint8Array | number | bigint): Promise<Block>
 
+		/**
+		 * Gets block given one of the following inputs:
+		 * - Hex block hash
+		 * - Hex block number (if length is 32 bytes, it is treated as a hash)
+		 * - Uint8Array block hash
+		 * - Number block number
+		 * - BigInt block number
+		 * - BlockTag block tag
+		 * - Named block tag (e.g. 'latest', 'earliest', 'pending')
+		 * @throws {UnknownBlockError} - If the block is not found
+		 * @throw {InvalidBlockTagError} - If the block tag is invalid}
+		 */
+		getBlockByTag(blockTag: Hex | Uint8Array | number | bigint | BlockTag): Promise<Block>
+
 		/**
 		 * Iterates through blocks starting at the specified iterator head and calls
 		 * the onBlock function on each block.

packages/blockchain/src/actions/getBlockByTag.js

@@ -0,0 +1,35 @@
+import { hexToBytes, hexToNumber, isHex } from '@tevm/utils'
+import { getBlock } from './getBlock.js'
+import { UnknownBlockError } from '@tevm/errors'
+import { getBlockFromRpc } from '../utils/getBlockFromRpc.js'
+import { putBlock } from './putBlock.js'
+
+/**
+ * @param {import('../BaseChain.js').BaseChain} baseChain
+ * @returns {import('../Chain.js').Chain['getBlockByTag']}
+ */
+export const getBlockByTag = (baseChain) => async (blockId) => {
+	const _getBlock = getBlock(baseChain)
+	if (isHex(blockId)) {
+		return blockId.length === 66 ? _getBlock(hexToBytes(blockId)) : _getBlock(hexToNumber(blockId))
+	}
+	if (typeof blockId === 'number' || typeof blockId === 'bigint' || blockId instanceof Uint8Array) {
+		return _getBlock(blockId)
+	}
+	const block = baseChain.blocksByTag.get(blockId)
+	if (!block && baseChain.options.fork?.transport) {
+		const block = await getBlockFromRpc(
+			{
+				transport: baseChain.options.fork.transport,
+				blockTag: blockId,
+			},
+			baseChain.common,
+		)
+		await putBlock(baseChain)(block)
+		return block
+	}
+	if (!block) {
+		throw new UnknownBlockError(blockId)
+	}
+	return block
+}

packages/blockchain/src/createChain.js

@@ -1,6 +1,7 @@
 import { deepCopy } from './actions/deepCopy.js'
 import { delBlock } from './actions/delBlock.js'
 import { getBlock } from './actions/getBlock.js'
+import { getBlockByTag } from './actions/getBlockByTag.js'
 import { getCanonicalHeadBlock } from './actions/getCanonicalHeadBlock.js'
 import { getIteratorHead } from './actions/getIteratorHead.js'
 import { putBlock } from './actions/putBlock.js'
@@ -18,6 +19,7 @@ export const createChain = async (options) => {
 	 */
 	const decorate = (baseChain) => {
 		return Object.assign(baseChain, {
+			getBlockByTag: getBlockByTag(baseChain),
 			deepCopy: async () => decorate(await deepCopy(baseChain)()),
 			shallowCopy: () => decorate(shallowCopy(baseChain)()),
 			getBlock: getBlock(baseChain),