Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

@tevm/blockchain

Tevm's block and chain-state implementation. Manages local blocks, fork-backed lookup, canonical heads, iterator heads, and chain validation using Tevm block types and ZEVM-compatible primitives.

Full API: packages/blockchain/docs.

Installation

npm install @tevm/blockchain

API Reference

Chain

Main blockchain interface. Methods:

  • putBlock(block) - add a block
  • delBlock(blockHash) - delete a block and its children
  • getBlock(blockId) - lookup by hash or number
  • getBlockByTag(blockTag) - lookup by tag (latest, earliest, etc.)
  • getCanonicalHeadBlock() - latest block on canonical chain
  • validateHeader(header) - header validation
  • iterator(name, onBlock, maxBlocks?) - iterate blocks
  • getIteratorHead(name) / setIteratorHead(name, hash) - iterator head management
  • deepCopy() / shallowCopy() - copy helpers for snapshots and simulations

ChainOptions

type ChainOptions = {
  common: Common
  loggingLevel?: LogLevel
  genesisBlock?: Block
  genesisStateRoot?: Uint8Array
  fork?: {
    transport: { request: EIP1193RequestFn }
    blockTag?: BlockTag | bigint | `0x${string}`
  }
}

Functions

  • createChain(options): Promise<Chain> - create a new chain.
  • createBaseChain(options): BaseChain - internal implementation used by createChain.

Errors

BlockNotFoundError, InvalidBlockError, InvalidHeaderError, InvalidChainError.

Usage Examples

import { createChain } from '@tevm/blockchain'
import { createCommon, mainnet } from '@tevm/common'
import { http } from 'viem'
 
const chain = await createChain({
  common: createCommon({ ...mainnet }),
  loggingLevel: 'debug',
  fork: {
    transport: { request: http('https://mainnet.infura.io/v3/YOUR-KEY') },
    blockTag: 'latest',
  },
})
 
await chain.putBlock(block)
const head = await chain.getCanonicalHeadBlock()
const byNumber = await chain.getBlock(1234n)
const latest = await chain.getBlockByTag('latest')
await chain.validateHeader(block.header)
await chain.delBlock(block.hash())
 
await chain.iterator('vm', async (block, reorg) => {
  if (reorg) console.log('reorg')
  console.log(block.header.number)
}, 1000)

See Also