eth_networks

Ethereum Network Configuration Module

Provides built-in configurations for popular EVM-compatible networks with default public RPC endpoints. Supports custom network configuration.

class eth_networks.NetworkConfig(name, chain_id, rpc_url, native_symbol, native_decimals=18, explorer_url=None, is_testnet=False)[source]

Bases: object

Immutable description of a single EVM-compatible chain.

Bundles the connection and display metadata the wallet tooling needs to talk to one network: its human name, numeric chain_id, JSON-RPC endpoint, native-currency symbol/decimals, block-explorer URL, and a testnet flag. Every entry in the module-level NETWORKS registry is one of these, and custom user-supplied chains are built into the same shape by create_custom_network().

Instances are consumed by tools/eth_wallet_tools.py (via get_network() / create_custom_network()) to resolve which RPC URL and chain id to sign and broadcast transactions against; the dataclass is plain data and performs no I/O itself.

Parameters:

  • name (str)

  • chain_id (int)

  • rpc_url (str)

  • native_symbol (str)

  • native_decimals (int)

  • explorer_url (str | None)

  • is_testnet (bool)

name: str

Human-readable network name (e.g. Ethereum Mainnet).

chain_id: int

EIP-155 chain id used for transaction signing.

rpc_url: str

Default public JSON-RPC endpoint for the network.

native_symbol: str

Ticker of the gas/native token (e.g. ETH).

native_decimals: int = 18

Decimal places of the native token (18 for most EVM chains).

explorer_url: str | None = None

Base URL of the block explorer, if any.

is_testnet: bool = False

True for test networks, used to filter them out of list_networks() results.

to_dict()[source]

Flatten this config into a plain JSON-serializable dictionary.

Produces a one-to-one mapping of every field so the network can be embedded in tool responses or API payloads without exposing the dataclass type. Pure data transformation with no side effects; the keys mirror the attribute names exactly.

No callers were found in the repository (grep for .to_dict( on a network config returns only the definitions), so this is a convenience serializer available to tool handlers rather than something currently wired into a hot path.

Returns:

A dictionary with name, chain_id, rpc_url, native_symbol, native_decimals, explorer_url and is_testnet keys.

Return type:

Dict[str, Any]

eth_networks.get_network(network_name_or_id)[source]

Resolve a network by its name/alias or numeric chain id.

The primary lookup the wallet tooling uses to turn a user-supplied identifier into a concrete RPC target. It first tries a case-insensitive, whitespace-trimmed match against the NETWORKS registry keys (which include short aliases like eth or op); failing that, it treats the argument as a decimal chain id and scans NETWORKS for the first config with a matching chain_id. The registry is in-memory, so no network I/O happens here.

Called by tools/eth_wallet_tools.py (_resolve_network and related handlers) to pick the chain a transaction or balance query runs against; when it returns None the tool layer falls back to create_custom_network() or reports an unknown-network error.

Parameters:

network_name_or_id (str) – A registry key/alias (ethereum, base) or a decimal chain id rendered as a string ("1", "8453").

Returns:

The matching network config, or None if no name alias or chain id matches.

Return type:

Optional[NetworkConfig]

eth_networks.get_network_by_chain_id(chain_id)[source]

Look up a network config by its exact numeric chain id.

A narrower, integer-typed sibling of get_network() that skips the name-alias path and linearly scans the NETWORKS registry for the first config whose chain_id equals the argument. Because several aliases share a chain id, the first registry entry encountered wins. In-memory only, no I/O.

No callers were found in the repository outside this module’s own definition, so it is currently an unused public helper kept for symmetry with get_network() and for external/tool callers.

Parameters:

chain_id (int) – The EIP-155 chain id to match.

Returns:

The matching config, or None if no registered network uses that chain id.

Return type:

Optional[NetworkConfig]

eth_networks.create_custom_network(name, chain_id, rpc_url, native_symbol='ETH', native_decimals=18, explorer_url=None, is_testnet=False)[source]

Build an ad-hoc NetworkConfig from caller-supplied parameters.

Lets the wallet tooling target chains that are not in the built-in NETWORKS registry: the caller passes an explicit RPC URL and chain id and gets back a config of the same shape as the built-ins, so the rest of the signing/broadcast path is identical. This is a thin constructor wrapper that just forwards its arguments to NetworkConfig; it does not register the result, validate the RPC, or perform any I/O.

Called by tools/eth_wallet_tools.py (_resolve_network) when get_network() returns None for a chain id but the caller provided a custom RPC endpoint to use.

Parameters:

  • name (str) – Human-readable network name.

  • chain_id (int) – EIP-155 chain id for transaction signing.

  • rpc_url (str) – JSON-RPC endpoint to connect to.

  • native_symbol (str) – Native-token ticker; defaults to ETH.

  • native_decimals (int) – Native-token decimal places; defaults to 18.

  • explorer_url (Optional[str]) – Block-explorer base URL, if known.

  • is_testnet (bool) – Whether this should be treated as a test network.

Returns:

A freshly constructed config wrapping the given values.

Return type:

NetworkConfig

eth_networks.list_networks(include_testnets=True)[source]

Summarize the registered networks, one entry per unique chain.

Produces a de-duplicated, display-oriented listing of NETWORKS: it walks the registry, keeps only the first config seen for each chain_id (so the many name aliases collapse to a single row), optionally drops testnets, and returns lightweight summary dicts sorted with mainnets first and then alphabetically by name. Read-only over the in-memory registry.

Called by tools/eth_wallet_tools.py (the list_eth_networks tool handler at line 749) to present the available chains to the model/user.

Parameters:

include_testnets (bool) – When False, networks flagged is_testnet are omitted from the result.

Returns:

A list of dicts, each with name, chain_id, symbol and is_testnet keys, sorted mainnets-first then by name.

Return type:

list