Ethers Networks

Ethers Networks provides comprehensive network definitions and configuration management for Ethereum and compatible blockchain networks. It serves as a foundational component of the ethers.js ecosystem, offering standardized network configurations with built-in provider fallback mechanisms for enhanced reliability.

Package Information

• Package Name: @ethersproject/networks
• Package Type: npm
• Language: TypeScript
• Installation: npm install @ethersproject/networks

Core Imports

import { getNetwork, Network, Networkish } from "@ethersproject/networks";

For CommonJS:

const { getNetwork, Network, Networkish } = require("@ethersproject/networks");

Basic Usage

import { getNetwork } from "@ethersproject/networks";

// Get network by name
const mainnet = getNetwork("homestead");
console.log(mainnet); // { name: "homestead", chainId: 1, ensAddress: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e", ... }

// Get network by chain ID
const polygon = getNetwork(137);
console.log(polygon); // { name: "matic", chainId: 137, ... }

// Get network by Network object (validation)
const goerli = getNetwork({ name: "goerli", chainId: 5 });
console.log(goerli); // Validated and standardized Network object

// Handle custom networks
const customNetwork = getNetwork({ name: "custom", chainId: 1337 });
console.log(customNetwork); // { name: "custom", chainId: 1337 }

Architecture

Ethers Networks is built around several key concepts:

• Network Standardization: Converts various network identifiers into standardized Network objects
• Provider Integration: Built-in default provider factories with automatic failover and quorum support
• Network Registry: Comprehensive database of 30+ predefined network configurations
• Validation System: Ensures network configurations are valid and consistent

Capabilities

Network Resolution

Converts network identifiers (names, chain IDs, or Network objects) into standardized Network configurations with validation and provider setup.

/**
 * Converts a named common networks or chain ID (network ID) to a Network
 * and verifies a network is a valid Network.
 * 
 * @param network - Network identifier (name, chain ID, or Network object)
 * @returns Network object with standardized configuration, or null for invalid input
 */
function getNetwork(network: Networkish): Network;

Examples:

// By network name (including aliases)
const mainnet = getNetwork("homestead");
const mainnetAlias = getNetwork("mainnet"); // Same as homestead
const testnet = getNetwork("sepolia");
const ropstenTestnet = getNetwork("testnet"); // Alias for ropsten

// By chain ID
const polygon = getNetwork(137);
const arbitrum = getNetwork(42161);
const bsc = getNetwork(56);

// Validation of Network objects
const validated = getNetwork({
  name: "goerli",
  chainId: 5,
  ensAddress: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
});

// Custom networks
const custom = getNetwork({ name: "local", chainId: 1337 });

Predefined Networks

The package includes comprehensive definitions for 30+ blockchain networks:

Ethereum Networks:

• homestead / mainnet (chainId: 1) - Ethereum mainnet with ENS support
• sepolia (chainId: 11155111) - Sepolia testnet with ENS support
• goerli (chainId: 5) - Goerli testnet with ENS support
• holesky (chainId: 17000) - Holesky testnet
• ropsten / testnet (chainId: 3) - Ropsten testnet with ENS support
• rinkeby (chainId: 4) - Rinkeby testnet with ENS support
• kovan (chainId: 42) - Kovan testnet
• morden (chainId: 2) - Morden testnet (legacy)
• kintsugi (chainId: 1337702) - Kintsugi testnet

Layer 2 Networks:

• matic (chainId: 137) - Polygon mainnet
• maticmum (chainId: 80001) - Polygon Mumbai testnet
• optimism (chainId: 10) - Optimism mainnet
• optimism-kovan (chainId: 69) - Optimism Kovan testnet
• optimism-goerli (chainId: 420) - Optimism Goerli testnet
• optimism-sepolia (chainId: 11155420) - Optimism Sepolia testnet
• arbitrum (chainId: 42161) - Arbitrum One mainnet
• arbitrum-rinkeby (chainId: 421611) - Arbitrum Rinkeby testnet
• arbitrum-goerli (chainId: 421613) - Arbitrum Goerli testnet
• arbitrum-sepolia (chainId: 421614) - Arbitrum Sepolia testnet

Ethereum Classic Networks:

• classic (chainId: 61) - Ethereum Classic mainnet
• classicMordor / classicTestnet (chainId: 63) - ETC Mordor testnet
• classicMorden (chainId: 62) - ETC Morden testnet
• classicKotti (chainId: 6) - ETC Kotti testnet

Other Compatible Networks:

• bnb (chainId: 56) - Binance Smart Chain mainnet
• bnbt (chainId: 97) - Binance Smart Chain testnet
• xdai (chainId: 100) - xDai/Gnosis Chain

Special Networks:

• unspecified (chainId: 0) - Unspecified network

Provider Integration

Networks include intelligent default provider configurations with automatic failover across multiple RPC providers including Infura, Etherscan, Alchemy, Pocket, Cloudflare, Ankr, and QuickNode.

// Networks with provider integration
const networkWithProviders = getNetwork("homestead");
// networkWithProviders._defaultProvider - Factory function for creating fallback providers

// Custom networks without providers
const customNetwork = getNetwork({ name: "custom", chainId: 1337 });
// customNetwork._defaultProvider - null (no default providers)

Types

/**
 * Network configuration object containing chain information and provider setup
 */
interface Network {
  /** Network name identifier (e.g., "homestead", "sepolia", "matic") */
  name: string;
  /** Unique blockchain network identifier (e.g., 1 for mainnet, 137 for Polygon) */
  chainId: number;
  /** Optional ENS registry contract address for networks supporting ENS */
  ensAddress?: string;
  /** Optional default provider factory function for automatic provider setup */
  _defaultProvider?: (providers: any, options?: any) => any;
}

/**
 * Union type accepting Network objects, string names, or numeric chain IDs
 * Provides flexible input format for network identification
 */
type Networkish = Network | string | number;

Error Handling

The getNetwork function handles various error conditions:

• Invalid network names: Returns null for unrecognized network names
• Invalid Network objects: Throws ArgumentError for objects with invalid chainId
• Chain ID mismatch: Throws ArgumentError when Network object's chainId doesn't match expected value for named networks
• Null input: Returns null for null or undefined input

// Error examples
try {
  const invalid = getNetwork({ name: "mainnet", chainId: "invalid" }); // Throws ArgumentError
} catch (error) {
  console.error(error.message); // "invalid network chainId"
}

const unknown = getNetwork("unknown-network"); // Returns null
const unknownChain = getNetwork(99999); // Returns { chainId: 99999, name: "unknown" }