Skip to main content

Try it Live

Run Chain examples in the interactive playground

​
Chain Lookup

Methods and properties for looking up chain configurations by chain ID.

​
byId Record

​
Chain.byId

Record mapping chain IDs to chain configuration objects. Provides O(1) lookup of any registered chain. 
// Direct access by chain ID
const quai = Chain.byId[9]
console.log(quai?.name)      // "Quai Mainnet"
console.log(quai?.chainId)   // 9

const flare = Chain.byId[14]
console.log(flare?.name)     // "Flare Mainnet"
console.log(flare?.chainId)  // 14

// Unknown chain returns undefined
const unknown = Chain.byId[999999999]
console.log(unknown)         // undefined
Type: Record<number, Chain> Returns: Chain | undefined for any chain ID Defined in: primitives/Chain/Chain.js:36 Delegates to: primitives/Chain/BrandedChain/byId.js:14

​
Comparison: byId vs fromId

Both Chain.byId[id] and Chain.fromId(id) lookup chains by ID: 
// These are equivalent
const chain1 = Chain.byId[9]
const chain2 = Chain.fromId(9)

// Both return undefined for unknown chains
const unknown1 = Chain.byId[999999999]    // undefined
const unknown2 = Chain.fromId(999999999)  // undefined
Differences:
  • byId[id] - Direct record access (bracket notation)
  • fromId(id) - Function call, slightly more explicit
Use byId when:
  • You prefer bracket notation
  • You’re accessing multiple chains in a loop
  • You want the most direct syntax
Use fromId when:
  • You prefer function call syntax
  • You want explicit method calls
  • You’re chaining operations

​
Usage Examples

​
Basic Lookup

import { Chain } from 'tevm'

// Look up Quai by ID
const quai = Chain.byId[9]
if (quai) {
  console.log(quai.name)                      // "Quai Mainnet"
  console.log(quai.nativeCurrency.symbol)     // "QUAI"
  console.log(quai.rpc[0])                    // RPC endpoint
}

// Look up Flare by ID
const flare = Chain.byId[14]
if (flare) {
  console.log(flare.name)                     // "Flare Mainnet"
  console.log(flare.nativeCurrency.symbol)    // "FLR"
}

​
Iterating Over Multiple Chains

// Get multiple chains efficiently
const chainIds = [9, 14, 1776, 2020, 2288]
const chains = chainIds
  .map(id => Chain.byId[id])
  .filter((chain): chain is Chain => chain !== undefined)

chains.forEach(chain => {
  console.log(`${chain.name} (ID: ${chain.chainId})`)
})

​
Dynamic Chain Selection

function selectChain(chainId: number): Chain {
  const chain = Chain.byId[chainId]

  if (!chain) {
    throw new Error(`Chain ID ${chainId} not found in registry`)
  }

  return chain
}

try {
  const userChain = selectChain(9)
  console.log(`Selected: ${userChain.name}`)
} catch (error) {
  console.error(error.message)
}

​
Chain Validation

function isValidChainId(chainId: number): boolean {
  return Chain.byId[chainId] !== undefined
}

function requireValidChain(chainId: number): Chain {
  if (!isValidChainId(chainId)) {
    throw new Error(`Invalid chain ID: ${chainId}`)
  }

  return Chain.byId[chainId]
}

// Check chain existence
console.log(isValidChainId(9))         // true
console.log(isValidChainId(999999999)) // false

// Require valid chain
const quai = requireValidChain(9)      // ✓ returns chain
// requireValidChain(999999999)        // ✗ throws error

​
All Registered Chains

// Get all chain IDs
const allChainIds = Object.keys(Chain.byId).map(Number)
console.log(`Total chains: ${allChainIds.length}`)

// Get all chain objects
const allChains = Object.values(Chain.byId)
allChains.forEach(chain => {
  console.log(`${chain.chainId}: ${chain.name}`)
})

​
Common Chain IDs

// Popular networks
const MAINNET_ID = 1
const OPTIMISM_ID = 10
const ARBITRUM_ID = 42161
const BASE_ID = 8453
const POLYGON_ID = 137

// Look up popular chains
const mainnet = Chain.byId[MAINNET_ID]
const optimism = Chain.byId[OPTIMISM_ID]
const arbitrum = Chain.byId[ARBITRUM_ID]

console.log(mainnet?.name)   // Network names
console.log(optimism?.name)
console.log(arbitrum?.name)

​
Type-Safe Chain Map

// Create chain-specific configuration
const chainConfigs: Record<number, {
  name: string
  enabled: boolean
}> = {
  9: { name: 'Quai', enabled: true },
  14: { name: 'Flare', enabled: true },
  1776: { name: 'Injective', enabled: false },
}

// Match with chain data
Object.entries(chainConfigs).forEach(([id, config]) => {
  const chainId = Number(id)
  const chain = Chain.byId[chainId]

  if (chain && config.enabled) {
    console.log(`${config.name}: ${chain.nativeCurrency.symbol}`)
  }
})

​
Safe Chain Access

function getChainInfo(chainId: number): {
  name: string
  symbol: string
  rpc: string
} | null {
  const chain = Chain.byId[chainId]

  if (!chain) {
    return null
  }

  return {
    name: chain.name,
    symbol: chain.nativeCurrency.symbol,
    rpc: chain.rpc[0] || '',
  }
}

// Handle missing chains gracefully
const quaiInfo = getChainInfo(9)
if (quaiInfo) {
  console.log(`${quaiInfo.name} uses ${quaiInfo.symbol}`)
}

const unknownInfo = getChainInfo(999999999)
console.log(unknownInfo) // null

​
Network Switch Handler

async function handleNetworkSwitch(newChainId: number) {
  const chain = Chain.byId[newChainId]

  if (!chain) {
    console.error(`Unknown chain ID: ${newChainId}`)
    return false
  }

  console.log(`Switching to ${chain.name}...`)
  console.log(`RPC: ${chain.rpc[0]}`)
  console.log(`Native currency: ${chain.nativeCurrency.symbol}`)

  // Perform network switch...
  return true
}

// User initiates network switch
await handleNetworkSwitch(9) // Switch to Quai

​
Chain Registry Explorer

function exploreChainRegistry() {
  const chains = Object.values(Chain.byId)

  // Group by native currency
  const byCurrency = chains.reduce((acc, chain) => {
    const symbol = chain.nativeCurrency.symbol
    if (!acc[symbol]) acc[symbol] = []
    acc[symbol].push(chain)
    return acc
  }, {} as Record<string, Chain[]>)

  // Print summary
  Object.entries(byCurrency).forEach(([symbol, chains]) => {
    console.log(`${symbol}: ${chains.length} chains`)
  })
}

exploreChainRegistry()