> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Chain Lookup

> Looking up chains by ID using byId record

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/chain.ts">
  Run Chain examples in the interactive playground
</Card>

# 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.

```typescript theme={null}
// 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](https://github.com/evmts/voltaire/blob/main/src/primitives/Chain/Chain.js)

Delegates to: [primitives/Chain/BrandedChain/byId.js:14](https://github.com/evmts/voltaire/blob/main/src/primitives/Chain/BrandedChain/byId.js)

### Comparison: byId vs fromId

Both `Chain.byId[id]` and `Chain.fromId(id)` lookup chains by ID:

```typescript theme={null}
// 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

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/primitives/chain/constructors) - Creating Chain instances
* [Metadata](/primitives/chain/metadata) - Accessing chain properties
* [BrandedChain](/primitives/chain/branded-chain) - Functional API