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

> Creating Chain instances from chain objects and IDs

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

# Constructors

Methods for creating Chain instances from chain configuration objects and chain IDs.

## Universal Constructor

### `Chain(chain)`

Universal constructor creates Chain instance from chain object. Identity function that sets proper prototype.

```typescript theme={null}
import { mainnet, optimism } from 'tevm/chains'

const chain1 = Chain(mainnet)
const chain2 = Chain(optimism)

console.log(chain1.chainId)  // 1
console.log(chain2.chainId)  // 10
```

**Parameters:**

* `chain: Chain` - Chain configuration object

**Returns:** `Chain`

Defined in: [primitives/Chain/Chain.js:14](https://github.com/evmts/voltaire/blob/main/src/primitives/Chain/Chain.js)

## Static Constructors

### `Chain.from(chain)`

Creates Chain instance from chain configuration object. Identity function that sets proper prototype.

```typescript theme={null}
import { mainnet, optimism, arbitrum, base } from 'tevm/chains'

const chain = Chain(mainnet)
console.log(chain.name)      // "Ethereum Mainnet"
console.log(chain.chainId)   // 1

const op = Chain(optimism)
console.log(op.name)         // "OP Mainnet"
console.log(op.chainId)      // 10
```

**Parameters:**

* `chain: Chain` - Chain configuration object

**Returns:** `Chain`

**Use cases:**

* Wrapping chain objects from tevm/chains
* Adding prototype methods to plain chain objects
* Type conversion for libraries expecting Chain instances

Defined in: [primitives/Chain/Chain.js:21](https://github.com/evmts/voltaire/blob/main/src/primitives/Chain/Chain.js)

### `Chain.fromId(id)`

Look up chain by chain ID. Returns chain configuration or `undefined` if not found.

```typescript theme={null}
// Look up chains by ID
const quai = Chain.fromId(9)
console.log(quai?.name)      // "Quai Mainnet"
console.log(quai?.chainId)   // 9

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

// Unknown chain returns undefined
const unknown = Chain.fromId(999999999)
console.log(unknown)         // undefined
```

**Parameters:**

* `id: number` - Chain ID to lookup

**Returns:** `Chain | undefined` - Chain object or undefined if not found

**Common chain IDs:**

* `1` - Ethereum Mainnet
* `10` - OP Mainnet
* `42161` - Arbitrum One
* `8453` - Base
* `137` - Polygon
* `43114` - Avalanche C-Chain

**Use cases:**

* Dynamic chain selection based on user input
* Loading chain config from environment variables
* Validating chain IDs before operations
* Network switching in dApps

Defined in: [primitives/Chain/Chain.js:28](https://github.com/evmts/voltaire/blob/main/src/primitives/Chain/Chain.js)

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

## Usage Examples

### Basic Usage

```typescript theme={null}
import { Chain } from 'tevm'
import { mainnet, optimism } from 'tevm/chains'

// From chain object
const eth = Chain(mainnet)
console.log(eth.nativeCurrency.symbol) // "ETH"

// From chain ID
const op = Chain.fromId(10)
console.log(op?.shortName) // "oeth"
```

### Dynamic Chain Loading

```typescript theme={null}
import { ValidationError } from 'tevm/errors'

function getChainConfig(chainIdFromUser: number): Chain {
  const chain = Chain.fromId(chainIdFromUser)

  if (!chain) {
    throw new ValidationError(`Unknown chain ID: ${chainIdFromUser}`, {
      value: chainIdFromUser,
      expected: "Valid chain ID from registry",
      code: "UNKNOWN_CHAIN_ID"
    })
  }

  return chain
}

// User selects chain ID 9
const userChain = getChainConfig(9)
console.log(userChain.name) // "Quai Mainnet"
```

### Environment-Based Chain Selection

```typescript theme={null}
function loadChainFromEnv(): Chain {
  const chainId = parseInt(process.env.CHAIN_ID || '1', 10)
  const chain = Chain.fromId(chainId)

  if (!chain) {
    console.warn(`Unknown CHAIN_ID: ${chainId}, falling back to mainnet`)
    return Chain.fromId(1)!
  }

  return chain
}

const chain = loadChainFromEnv()
console.log(`Using ${chain.name} (Chain ID: ${chain.chainId})`)
```

### Safe Chain Lookup

```typescript theme={null}
function getSafeChain(chainId: number): Chain | null {
  const chain = Chain.fromId(chainId)

  if (!chain) {
    console.error(`Chain ID ${chainId} not found in registry`)
    return null
  }

  return chain
}

// Handle missing chains gracefully
const chain = getSafeChain(999999999)
if (chain) {
  console.log(chain.name)
} else {
  console.log("Chain not found")
}
```

### Multi-Chain Application

```typescript theme={null}
import { Chain } from 'tevm'

const SUPPORTED_CHAINS = [1, 10, 42161, 8453] as const

function getSupportedChains(): Chain[] {
  return SUPPORTED_CHAINS
    .map(id => Chain.fromId(id))
    .filter((chain): chain is Chain => chain !== undefined)
}

function isChainSupported(chainId: number): boolean {
  return SUPPORTED_CHAINS.includes(chainId as any)
}

// Get all supported chains
const chains = getSupportedChains()
chains.forEach(chain => {
  console.log(`${chain.name} (ID: ${chain.chainId})`)
})

// Check if chain is supported
if (isChainSupported(9)) {
  const quai = Chain.fromId(9)!
  console.log(`${quai.name} is supported`)
}
```

### Type-Safe Chain Handling

```typescript theme={null}
import { ValidationError } from 'tevm/errors'

function processChain(chainOrId: Chain | number): Chain {
  if (typeof chainOrId === 'number') {
    const chain = Chain.fromId(chainOrId)
    if (!chain) {
      throw new ValidationError(`Invalid chain ID: ${chainOrId}`, {
        value: chainOrId,
        expected: "Valid chain ID",
        code: "INVALID_CHAIN_ID"
      })
    }
    return chain
  }

  return Chain(chainOrId)
}

// Works with chain objects
import { mainnet } from 'tevm/chains'
const eth = processChain(mainnet)

// Works with chain IDs
const quai = processChain(9)
```

## Notes

* `from()` is an identity function - returns the same object with prototype set
* `fromId()` delegates to `getChainById` from tevm/chains
* All chain objects come from [tevm/chains](https://github.com/evmts/voltaire-monorepo/tree/main/packages/chains) registry
* Chain IDs are unique identifiers defined by [EIP-155](https://eips.ethereum.org/EIPS/eip-155)
* New chains are added to tevm/chains registry regularly