"""
Ethereum Network Configuration Module
Provides built-in configurations for popular EVM-compatible networks
with default public RPC endpoints. Supports custom network configuration.
"""
from typing import Dict, Any, Optional
from dataclasses import dataclass
[docs]
@dataclass
class NetworkConfig:
"""Configuration for an EVM-compatible network."""
name: str
chain_id: int
rpc_url: str
native_symbol: str
native_decimals: int = 18
explorer_url: Optional[str] = None
is_testnet: bool = False
[docs]
def to_dict(self) -> Dict[str, Any]:
"""Convert to dict representation.
Returns:
Dict[str, Any]: The result.
"""
return {
"name": self.name,
"chain_id": self.chain_id,
"rpc_url": self.rpc_url,
"native_symbol": self.native_symbol,
"native_decimals": self.native_decimals,
"explorer_url": self.explorer_url,
"is_testnet": self.is_testnet
}
NETWORKS: Dict[str, NetworkConfig] = {
"ethereum": NetworkConfig(
name="Ethereum Mainnet", chain_id=1,
rpc_url="https://eth.llamarpc.com", native_symbol="ETH",
explorer_url="https://etherscan.io"),
"eth": NetworkConfig(
name="Ethereum Mainnet", chain_id=1,
rpc_url="https://eth.llamarpc.com", native_symbol="ETH",
explorer_url="https://etherscan.io"),
"pulsechain": NetworkConfig(
name="PulseChain", chain_id=369,
rpc_url="https://rpc.pulsechain.com", native_symbol="PLS",
explorer_url="https://scan.pulsechain.com"),
"pls": NetworkConfig(
name="PulseChain", chain_id=369,
rpc_url="https://rpc.pulsechain.com", native_symbol="PLS",
explorer_url="https://scan.pulsechain.com"),
"polygon": NetworkConfig(
name="Polygon", chain_id=137,
rpc_url="https://polygon-rpc.com", native_symbol="MATIC",
explorer_url="https://polygonscan.com"),
"matic": NetworkConfig(
name="Polygon", chain_id=137,
rpc_url="https://polygon-rpc.com", native_symbol="MATIC",
explorer_url="https://polygonscan.com"),
"bsc": NetworkConfig(
name="BNB Smart Chain", chain_id=56,
rpc_url="https://bsc-dataseed.binance.org", native_symbol="BNB",
explorer_url="https://bscscan.com"),
"bnb": NetworkConfig(
name="BNB Smart Chain", chain_id=56,
rpc_url="https://bsc-dataseed.binance.org", native_symbol="BNB",
explorer_url="https://bscscan.com"),
"arbitrum": NetworkConfig(
name="Arbitrum One", chain_id=42161,
rpc_url="https://arb1.arbitrum.io/rpc", native_symbol="ETH",
explorer_url="https://arbiscan.io"),
"arb": NetworkConfig(
name="Arbitrum One", chain_id=42161,
rpc_url="https://arb1.arbitrum.io/rpc", native_symbol="ETH",
explorer_url="https://arbiscan.io"),
"optimism": NetworkConfig(
name="Optimism", chain_id=10,
rpc_url="https://mainnet.optimism.io", native_symbol="ETH",
explorer_url="https://optimistic.etherscan.io"),
"op": NetworkConfig(
name="Optimism", chain_id=10,
rpc_url="https://mainnet.optimism.io", native_symbol="ETH",
explorer_url="https://optimistic.etherscan.io"),
"avalanche": NetworkConfig(
name="Avalanche C-Chain", chain_id=43114,
rpc_url="https://api.avax.network/ext/bc/C/rpc", native_symbol="AVAX",
explorer_url="https://snowtrace.io"),
"avax": NetworkConfig(
name="Avalanche C-Chain", chain_id=43114,
rpc_url="https://api.avax.network/ext/bc/C/rpc", native_symbol="AVAX",
explorer_url="https://snowtrace.io"),
"base": NetworkConfig(
name="Base", chain_id=8453,
rpc_url="https://mainnet.base.org", native_symbol="ETH",
explorer_url="https://basescan.org"),
"fantom": NetworkConfig(
name="Fantom Opera", chain_id=250,
rpc_url="https://rpcapi.fantom.network", native_symbol="FTM",
explorer_url="https://ftmscan.com"),
"ftm": NetworkConfig(
name="Fantom Opera", chain_id=250,
rpc_url="https://rpcapi.fantom.network", native_symbol="FTM",
explorer_url="https://ftmscan.com"),
"gnosis": NetworkConfig(
name="Gnosis Chain", chain_id=100,
rpc_url="https://rpc.gnosischain.com", native_symbol="xDAI",
explorer_url="https://gnosisscan.io"),
"cronos": NetworkConfig(
name="Cronos", chain_id=25,
rpc_url="https://evm.cronos.org", native_symbol="CRO",
explorer_url="https://cronoscan.com"),
"zksync": NetworkConfig(
name="zkSync Era", chain_id=324,
rpc_url="https://mainnet.era.zksync.io", native_symbol="ETH",
explorer_url="https://explorer.zksync.io"),
"linea": NetworkConfig(
name="Linea", chain_id=59144,
rpc_url="https://rpc.linea.build", native_symbol="ETH",
explorer_url="https://lineascan.build"),
"scroll": NetworkConfig(
name="Scroll", chain_id=534352,
rpc_url="https://rpc.scroll.io", native_symbol="ETH",
explorer_url="https://scrollscan.com"),
"mantle": NetworkConfig(
name="Mantle", chain_id=5000,
rpc_url="https://rpc.mantle.xyz", native_symbol="MNT",
explorer_url="https://explorer.mantle.xyz"),
"celo": NetworkConfig(
name="Celo", chain_id=42220,
rpc_url="https://forno.celo.org", native_symbol="CELO",
explorer_url="https://celoscan.io"),
"polygon_zkevm": NetworkConfig(
name="Polygon zkEVM", chain_id=1101,
rpc_url="https://zkevm-rpc.com", native_symbol="ETH",
explorer_url="https://zkevm.polygonscan.com"),
"zkevm": NetworkConfig(
name="Polygon zkEVM", chain_id=1101,
rpc_url="https://zkevm-rpc.com", native_symbol="ETH",
explorer_url="https://zkevm.polygonscan.com"),
"blast": NetworkConfig(
name="Blast", chain_id=81457,
rpc_url="https://rpc.blast.io", native_symbol="ETH",
explorer_url="https://blastscan.io"),
"mode": NetworkConfig(
name="Mode", chain_id=34443,
rpc_url="https://mainnet.mode.network", native_symbol="ETH",
explorer_url="https://explorer.mode.network"),
"manta": NetworkConfig(
name="Manta Pacific", chain_id=169,
rpc_url="https://pacific-rpc.manta.network/http", native_symbol="ETH",
explorer_url="https://pacific-explorer.manta.network"),
"metis": NetworkConfig(
name="Metis Andromeda", chain_id=1088,
rpc_url="https://andromeda.metis.io/?owner=1088", native_symbol="METIS",
explorer_url="https://andromeda-explorer.metis.io"),
"aurora": NetworkConfig(
name="Aurora", chain_id=1313161554,
rpc_url="https://mainnet.aurora.dev", native_symbol="ETH",
explorer_url="https://explorer.aurora.dev"),
"moonbeam": NetworkConfig(
name="Moonbeam", chain_id=1284,
rpc_url="https://rpc.api.moonbeam.network", native_symbol="GLMR",
explorer_url="https://moonscan.io"),
"moonriver": NetworkConfig(
name="Moonriver", chain_id=1285,
rpc_url="https://rpc.api.moonriver.moonbeam.network", native_symbol="MOVR",
explorer_url="https://moonriver.moonscan.io"),
"harmony": NetworkConfig(
name="Harmony One", chain_id=1666600000,
rpc_url="https://api.harmony.one", native_symbol="ONE",
explorer_url="https://explorer.harmony.one"),
"one": NetworkConfig(
name="Harmony One", chain_id=1666600000,
rpc_url="https://api.harmony.one", native_symbol="ONE",
explorer_url="https://explorer.harmony.one"),
"kava": NetworkConfig(
name="Kava EVM", chain_id=2222,
rpc_url="https://evm.kava.io", native_symbol="KAVA",
explorer_url="https://kavascan.com"),
"opbnb": NetworkConfig(
name="opBNB", chain_id=204,
rpc_url="https://opbnb-mainnet-rpc.bnbchain.org", native_symbol="BNB",
explorer_url="https://opbnbscan.com"),
"fraxtal": NetworkConfig(
name="Fraxtal", chain_id=252,
rpc_url="https://rpc.frax.com", native_symbol="frxETH",
explorer_url="https://fraxscan.com"),
"worldchain": NetworkConfig(
name="World Chain", chain_id=480,
rpc_url="https://worldchain-mainnet.g.alchemy.com/public", native_symbol="ETH",
explorer_url="https://worldscan.org"),
"taiko": NetworkConfig(
name="Taiko", chain_id=167000,
rpc_url="https://rpc.taiko.xyz", native_symbol="ETH",
explorer_url="https://taikoscan.io"),
# Testnets
"sepolia": NetworkConfig(
name="Sepolia Testnet", chain_id=11155111,
rpc_url="https://ethereum-sepolia-rpc.publicnode.com", native_symbol="ETH",
explorer_url="https://sepolia.etherscan.io", is_testnet=True),
"holesky": NetworkConfig(
name="Holesky Testnet", chain_id=17000,
rpc_url="https://holesky.drpc.org", native_symbol="ETH",
explorer_url="https://holesky.etherscan.io", is_testnet=True),
"pulsechain_testnet": NetworkConfig(
name="PulseChain Testnet v4", chain_id=943,
rpc_url="https://rpc.v4.testnet.pulsechain.com", native_symbol="tPLS",
explorer_url="https://scan.v4.testnet.pulsechain.com", is_testnet=True),
"pls_testnet": NetworkConfig(
name="PulseChain Testnet v4", chain_id=943,
rpc_url="https://rpc.v4.testnet.pulsechain.com", native_symbol="tPLS",
explorer_url="https://scan.v4.testnet.pulsechain.com", is_testnet=True),
"polygon_amoy": NetworkConfig(
name="Polygon Amoy Testnet", chain_id=80002,
rpc_url="https://rpc-amoy.polygon.technology", native_symbol="MATIC",
explorer_url="https://amoy.polygonscan.com", is_testnet=True),
"amoy": NetworkConfig(
name="Polygon Amoy Testnet", chain_id=80002,
rpc_url="https://rpc-amoy.polygon.technology", native_symbol="MATIC",
explorer_url="https://amoy.polygonscan.com", is_testnet=True),
"bsc_testnet": NetworkConfig(
name="BSC Testnet", chain_id=97,
rpc_url="https://data-seed-prebsc-1-s1.binance.org:8545", native_symbol="tBNB",
explorer_url="https://testnet.bscscan.com", is_testnet=True),
"arbitrum_sepolia": NetworkConfig(
name="Arbitrum Sepolia", chain_id=421614,
rpc_url="https://sepolia-rollup.arbitrum.io/rpc", native_symbol="ETH",
explorer_url="https://sepolia.arbiscan.io", is_testnet=True),
"base_sepolia": NetworkConfig(
name="Base Sepolia", chain_id=84532,
rpc_url="https://sepolia.base.org", native_symbol="ETH",
explorer_url="https://sepolia.basescan.org", is_testnet=True),
}
CHAIN_ID_TO_NETWORK: Dict[int, str] = {
config.chain_id: name
for name, config in NETWORKS.items()
if name == name.lower() and not any(
other_name != name and
NETWORKS[other_name].chain_id == config.chain_id and
len(other_name) > len(name)
for other_name in NETWORKS
)
}
[docs]
def get_network(network_name_or_id: str) -> Optional[NetworkConfig]:
"""Retrieve the network.
Args:
network_name_or_id (str): The network name or id value.
Returns:
Optional[NetworkConfig]: The result.
"""
name_lower = network_name_or_id.lower().strip()
if name_lower in NETWORKS:
return NETWORKS[name_lower]
try:
chain_id = int(network_name_or_id)
for config in NETWORKS.values():
if config.chain_id == chain_id:
return config
except ValueError:
pass
return None
[docs]
def get_network_by_chain_id(chain_id: int) -> Optional[NetworkConfig]:
"""Retrieve the network by chain id.
Args:
chain_id (int): The chain id value.
Returns:
Optional[NetworkConfig]: The result.
"""
for config in NETWORKS.values():
if config.chain_id == chain_id:
return config
return None
[docs]
def create_custom_network(
name: str,
chain_id: int,
rpc_url: str,
native_symbol: str = "ETH",
native_decimals: int = 18,
explorer_url: Optional[str] = None,
is_testnet: bool = False
) -> NetworkConfig:
"""Create a new custom network.
Args:
name (str): Human-readable name.
chain_id (int): The chain id value.
rpc_url (str): The rpc url value.
native_symbol (str): The native symbol value.
native_decimals (int): The native decimals value.
explorer_url (Optional[str]): The explorer url value.
is_testnet (bool): The is testnet value.
Returns:
NetworkConfig: The result.
"""
return NetworkConfig(
name=name,
chain_id=chain_id,
rpc_url=rpc_url,
native_symbol=native_symbol,
native_decimals=native_decimals,
explorer_url=explorer_url,
is_testnet=is_testnet
)
[docs]
def list_networks(include_testnets: bool = True) -> list:
"""List networks.
Args:
include_testnets (bool): The include testnets value.
Returns:
list: List of results.
"""
seen_chain_ids = set()
networks = []
for name, config in NETWORKS.items():
if config.chain_id in seen_chain_ids:
continue
if not include_testnets and config.is_testnet:
continue
seen_chain_ids.add(config.chain_id)
networks.append({
"name": config.name,
"chain_id": config.chain_id,
"symbol": config.native_symbol,
"is_testnet": config.is_testnet
})
return sorted(networks, key=lambda n: (n["is_testnet"], n["name"]))