Chain Lookup

Looking up chains by ID using byId record

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

Related

• Constructors - Creating Chain instances
• Metadata - Accessing chain properties
• BrandedChain - Functional API