@tevm/common

The @tevm/common package provides chain-specific configuration and utilities for Tevm clients. It extends the functionality of ethereumjs/common and integrates with Viem's chain definitions.

Generated API Documentation: View the full API documentation in the evmts/tevm-monorepo/packages/common/docs folder.

Installation

npm install @tevm/common

Overview

The @tevm/common package provides:

Chain configuration management
Hardfork settings and EIP support
Consensus algorithm configuration
Network-specific settings
Extensive chain definitions

API Reference

Enumerations

ConsensusAlgorithm - Supported consensus algorithms
ConsensusType - Types of consensus mechanisms

Interfaces

CustomCrypto - Custom cryptographic implementations
EvmStateManagerInterface - EVM state manager interface
StorageDump - Storage dump format
StorageRange - Storage range specification

Type Aliases

AccountFields - Account field definitions
CliqueConfig - Clique consensus configuration
Common - Main chain configuration type
CommonOptions - Configuration options
Hardfork - Supported hardforks
MockKzg - Mock KZG implementation

Functions

createCommon - Create a new Common instance
createMockKzg - Create a mock KZG implementation

Supported Networks

The package includes configurations for numerous networks, including:

Layer 1 Networks

mainnet - Ethereum Mainnet
sepolia - Sepolia Testnet
goerli - Goerli Testnet
holesky - Holesky Testnet

Layer 2 Networks

arbitrum - Arbitrum One
optimism - Optimism
base - Base
zksync - zkSync Era
polygon - Polygon PoS
polygonZkEvm - Polygon zkEVM

Alternative Networks

bsc - BNB Smart Chain
avalanche - Avalanche C-Chain
fantom - Fantom Opera
gnosis - Gnosis Chain

Development Networks

hardhat - Hardhat Network
foundry - Foundry Network
anvil - Anvil Network
localhost - Local Network

Usage Examples

Basic Configuration

import { createCommon } from '@tevm/common'
import { mainnet } from '@tevm/common'
 
const common = createCommon({
  ...mainnet,
  hardfork: 'shanghai'
})

Custom Chain Configuration

import { createCommon } from '@tevm/common'
 
const common = createCommon({
  name: 'Custom Chain',
  chainId: 1337,
  networkId: 1337,
  defaultHardfork: 'shanghai',
  consensus: {
    type: 'poa',
    algorithm: 'clique',
    clique: {
      period: 15,
      epoch: 30000
    }
  }
})

Using with Custom Crypto

import { createCommon, createMockKzg } from '@tevm/common'
 
const common = createCommon({
  ...mainnet,
  customCrypto: {
    kzg: createMockKzg()
  }
})

Network-Specific Configuration

import { createCommon, optimism, arbitrum } from '@tevm/common'
 
// Optimism configuration
const optimismCommon = createCommon({
  ...optimism,
  hardfork: 'bedrock'
})
 
// Arbitrum configuration
const arbitrumCommon = createCommon({
  ...arbitrum,
  hardfork: 'nitro'
})

Error Handling

The package throws specific errors for invalid configurations:

try {
  const common = createCommon({
    chainId: -1 // Invalid chain ID
  })
} catch (error) {
  if (error.code === 'INVALID_CHAIN_ID') {
    console.error('Invalid chain ID provided')
  }
}