✨ Feat: Add getBlockByTag to Chain package

.changeset/tall-phones-appear.md

@@ -0,0 +1,5 @@
+---
+"@tevm/blockchain": minor
+---
+
+Added new getBlockByTag method to Chain. It gets blocks by hash or number just like getBlock but also accepts a named tag such as 'latest', 'pending', or 'forked'

packages/blockchain/package.json

@@ -1,84 +1,86 @@
 {
-	"name": "@tevm/blockchain",
-	"version": "1.1.0-next.97",
-	"private": false,
-	"description": "A custom implementation of ethereumjs blockchain",
-	"keywords": [
-		"solidity",
-		"ethereumjs",
-		"typescript",
-		"web3",
-		"blockchain"
-	],
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/evmts/tevm-monorepo.git",
-		"directory": "packages/blockchain"
-	},
-	"license": "MIT",
-	"contributors": [
-		"Will Cory <[email protected]>"
-	],
-	"type": "module",
-	"exports": {
-		"./package.json": "./package.json",
-		".": {
-			"import": {
-				"types": "./types/index.d.ts",
-				"default": "./dist/index.js"
-			},
-			"require": {
-				"types": "./dist/index.d.cts",
-				"default": "./dist/index.cjs"
-			}
-		}
-	},
-	"main": "dist/index.cjs",
-	"module": "dist/index.js",
-	"types": "types/index.d.ts",
-	"files": [
-		"dist",
-		"types",
-		"src",
-		"!src/**/*.spec.ts"
-	],
-	"scripts": {
-		"all": "pnpm i  && bun run build && bun lint && bun format && bun test:run && bun generate:docs",
-		"build": "nx run-many --targets=build:dist,build:types --projects=@tevm/blockchain",
-		"build:dist": "tsup",
-		"build:types": "tsup --dts-only && tsc --emitDeclarationOnly --declaration",
-		"clean": "rm -rf node_modules && rm -rf artifacts && rm -rf dist && rm -rf cache",
-		"format": "biome format . --write",
-		"format:check": "biome format .",
-		"generate:docs": "typedoc",
-		"lint": "biome check . --write --unsafe",
-		"lint:check": "biome check . --verbose",
-		"lint:deps": "bunx depcheck",
-		"lint:package": "bunx publint --strict && attw --pack",
-		"package:up": "pnpm up --latest",
-		"test": "bun test --watch",
-		"test:coverage": "bun test --coverage",
-		"test:run": "bun test",
-		"typecheck": "tsc --noEmit"
-	},
-	"dependencies": {
-		"@ethereumjs/blockchain": "^7.2.0",
-		"@tevm/block": "workspace:^",
-		"@tevm/common": "workspace:^",
-		"@tevm/jsonrpc": "workspace:^",
-		"@tevm/logger": "workspace:^",
-		"@tevm/trie": "workspace:^",
-		"@tevm/utils": "workspace:^"
-	},
-	"devDependencies": {
-		"@tevm/tsconfig": "workspace:^",
-		"@tevm/tsupconfig": "workspace:^"
-	},
-	"peerDependencies": {
-		"viem": "^2.14.2"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"sideEffect": false
+  "name": "@tevm/blockchain",
+  "version": "1.1.0-next.97",
+  "private": false,
+  "description": "A custom implementation of ethereumjs blockchain",
+  "keywords": [
+    "solidity",
+    "ethereumjs",
+    "typescript",
+    "web3",
+    "blockchain"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evmts/tevm-monorepo.git",
+    "directory": "packages/blockchain"
+  },
+  "license": "MIT",
+  "contributors": [
+    "Will Cory <[email protected]>"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "types/index.d.ts",
+  "files": [
+    "dist",
+    "types",
+    "src",
+    "!src/**/*.spec.ts"
+  ],
+  "scripts": {
+    "all": "pnpm i  && bun run build && bun lint && bun format && bun test:run && bun generate:docs",
+    "build": "nx run-many --targets=build:dist,build:types --projects=@tevm/blockchain",
+    "build:dist": "tsup",
+    "build:types": "tsup --dts-only && tsc --emitDeclarationOnly --declaration",
+    "clean": "rm -rf node_modules && rm -rf artifacts && rm -rf dist && rm -rf cache",
+    "format": "biome format . --write",
+    "format:check": "biome format .",
+    "generate:docs": "typedoc",
+    "lint": "biome check . --write --unsafe",
+    "lint:check": "biome check . --verbose",
+    "lint:deps": "bunx depcheck",
+    "lint:package": "bunx publint --strict && attw --pack",
+    "package:up": "pnpm up --latest",
+    "test": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:run": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ethereumjs/blockchain": "^7.2.0",
+    "@tevm/block": "workspace:^",
+    "@tevm/common": "workspace:^",
+    "@tevm/errors": "workspace:^",
+    "@tevm/jsonrpc": "workspace:^",
+    "@tevm/logger": "workspace:^",
+    "@tevm/trie": "workspace:^",
+    "@tevm/utils": "workspace:^"
+  },
+  "devDependencies": {
+    "@tevm/test-utils": "workspace:^",
+    "@tevm/tsconfig": "workspace:^",
+    "@tevm/tsupconfig": "workspace:^"
+  },
+  "peerDependencies": {
+    "viem": "^2.14.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffect": false
 }

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/getBlock.js

@@ -38,6 +38,7 @@ export const getBlock = (baseChain) => async (blockId) => {
 	baseChain.logger.debug('Fetching block from remote rpc...')
 
 	const fetchedBlock = await getBlockFromRpc(
+		baseChain,
 		{
 			transport: baseChain.options.fork?.transport,
 			blockTag: blockId instanceof Uint8Array ? bytesToHex(blockId) : BigInt(blockId),

packages/blockchain/src/actions/getBlockByTag.js

@@ -0,0 +1,36 @@
+import { UnknownBlockError } from '@tevm/errors'
+import { hexToBytes, hexToNumber, isHex } from '@tevm/utils'
+import { getBlockFromRpc } from '../utils/getBlockFromRpc.js'
+import { getBlock } from './getBlock.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(
+			baseChain,
+			{
+				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/createBaseChain.js

@@ -68,7 +68,7 @@ export const createBaseChain = (options) => {
 	// Add genesis block and forked block to chain
 	const genesisBlockPromise = (async () => {
 		if (options.fork?.transport) {
-			const block = await getBlockFromRpc(options.fork, options.common)
+			const block = await getBlockFromRpc(chain, options.fork, options.common)
 			await putBlock(chain)(block)
 			chain.blocksByTag.set('forked', block)
 		} else {

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),