Networks¶

Network data entities for Arbitrum SDK.

This module defines the data structures and functions for managing Arbitrum network configurations, including core bridge contracts, token bridges, and network metadata.

The module maintains a registry of known Arbitrum networks and provides utilities for network management and information retrieval.

class arbitrum_py.data_entities.networks.EthBridge(bridge, inbox, sequencerInbox, outbox, rollup, classicOutboxes=None)[source]¶

Bases: CaseDict

Core bridging contracts for an Arbitrum chain.

Contains addresses of the fundamental contracts that enable L1<->L2 communication and state verification.

Variables:

bridge – Main bridge contract for cross-chain messaging
inbox – Contract that accepts messages from L1 to L2
sequencerInbox – Contract for sequencer’s special inbox
outbox – Contract for L2->L1 message execution
rollup – Core rollup contract managing the chain
classicOutboxes – Optional mapping of old outbox addresses to version numbers

bridge: NewType()(HexAddress, NewType()(HexStr, str))¶

inbox: NewType()(HexAddress, NewType()(HexStr, str))¶

sequencerInbox: NewType()(HexAddress, NewType()(HexStr, str))¶

outbox: NewType()(HexAddress, NewType()(HexStr, str))¶

rollup: NewType()(HexAddress, NewType()(HexStr, str))¶

classicOutboxes: Optional[Dict[NewType()(HexAddress, NewType()(HexStr, str)), int]] = None¶

__init__(bridge, inbox, sequencerInbox, outbox, rollup, classicOutboxes=None)¶

class arbitrum_py.data_entities.networks.TokenBridge(parentGatewayRouter, childGatewayRouter, parentErc20Gateway, childErc20Gateway, parentCustomGateway, childCustomGateway, parentWethGateway, childWethGateway, parentWeth, childWeth, parentProxyAdmin=None, childProxyAdmin=None, parentMultiCall='0x0000000000000000000000000000000000000000', childMultiCall='0x0000000000000000000000000000000000000000')[source]¶

Bases: CaseDict

Token bridging contracts for an Arbitrum chain.

Contains addresses of contracts that enable bridging of various token types between parent and child chains.

Variables:

parentGatewayRouter – Router on parent chain for token gateway selection
childGatewayRouter – Router on child chain for token gateway selection
parentErc20Gateway – Standard ERC20 gateway on parent chain
childErc20Gateway – Standard ERC20 gateway on child chain
parentCustomGateway – Custom token gateway on parent chain
childCustomGateway – Custom token gateway on child chain
parentWethGateway – WETH gateway on parent chain
childWethGateway – WETH gateway on child chain
parentWeth – WETH token on parent chain
childWeth – WETH token on child chain
parentProxyAdmin – Optional proxy admin on parent chain
childProxyAdmin – Optional proxy admin on child chain
parentMultiCall – Multicall contract on parent chain
childMultiCall – Multicall contract on child chain

parentGatewayRouter: NewType()(HexAddress, NewType()(HexStr, str))¶

childGatewayRouter: NewType()(HexAddress, NewType()(HexStr, str))¶

parentErc20Gateway: NewType()(HexAddress, NewType()(HexStr, str))¶

childErc20Gateway: NewType()(HexAddress, NewType()(HexStr, str))¶

parentCustomGateway: NewType()(HexAddress, NewType()(HexStr, str))¶

childCustomGateway: NewType()(HexAddress, NewType()(HexStr, str))¶

parentWethGateway: NewType()(HexAddress, NewType()(HexStr, str))¶

childWethGateway: NewType()(HexAddress, NewType()(HexStr, str))¶

parentWeth: NewType()(HexAddress, NewType()(HexStr, str))¶

childWeth: NewType()(HexAddress, NewType()(HexStr, str))¶

parentProxyAdmin: Optional[NewType()(HexAddress, NewType()(HexStr, str))] = None¶

childProxyAdmin: Optional[NewType()(HexAddress, NewType()(HexStr, str))] = None¶

parentMultiCall: NewType()(HexAddress, NewType()(HexStr, str)) = '0x0000000000000000000000000000000000000000'¶

childMultiCall: NewType()(HexAddress, NewType()(HexStr, str)) = '0x0000000000000000000000000000000000000000'¶

__init__(parentGatewayRouter, childGatewayRouter, parentErc20Gateway, childErc20Gateway, parentCustomGateway, childCustomGateway, parentWethGateway, childWethGateway, parentWeth, childWeth, parentProxyAdmin=None, childProxyAdmin=None, parentMultiCall='0x0000000000000000000000000000000000000000', childMultiCall='0x0000000000000000000000000000000000000000')¶

class arbitrum_py.data_entities.networks.Teleporter(l1Teleporter, l2ForwarderFactory)[source]¶

Bases: CaseDict

Teleporter contracts for cross-chain message forwarding.

Contains addresses of contracts that enable direct message forwarding between chains in the Arbitrum ecosystem.

Variables:

l1Teleporter – Teleporter contract on L1/parent chain
l2ForwarderFactory – Factory for creating message forwarders on L2/child chain

l1Teleporter: NewType()(HexAddress, NewType()(HexStr, str))¶

l2ForwarderFactory: NewType()(HexAddress, NewType()(HexStr, str))¶

__init__(l1Teleporter, l2ForwarderFactory)¶

class arbitrum_py.data_entities.networks.ArbitrumNetwork(name, chainId, parentChainId, ethBridge, confirmPeriodBlocks, isCustom, tokenBridge=None, teleporter=None, isTestnet=True, explorerUrl=None, retryableLifetimeSeconds=None, nativeToken=None, isBold=None)[source]¶

Bases: CaseDict

Represents an Arbitrum chain configuration.

Contains all the information needed to interact with an Arbitrum chain, including bridge contracts, chain identifiers, and network metadata.

Variables:

name – Name of the chain
chainId – Chain ID of this network
parentChainId – Chain ID of the parent chain
ethBridge – Core bridging contract addresses
confirmPeriodBlocks – Challenge window in L1 blocks
isCustom – Whether this is a user-registered network
tokenBridge – Optional token bridging contract addresses
teleporter – Optional teleporter contract addresses
isTestnet – Whether this is a testnet
explorerUrl – Optional block explorer URL
retryableLifetimeSeconds – Optional retryable ticket lifetime
nativeToken – Optional native token address (None for ETH)
isBold – Optional flag for Bold upgrade status

name: str¶

chainId: int¶

parentChainId: int¶

ethBridge: EthBridge¶

confirmPeriodBlocks: int¶

isCustom: bool¶

tokenBridge: Optional[TokenBridge] = None¶

teleporter: Optional[Teleporter] = None¶

isTestnet: bool = True¶

explorerUrl: Optional[str] = None¶

retryableLifetimeSeconds: Optional[int] = None¶

nativeToken: Optional[NewType()(HexAddress, NewType()(HexStr, str))] = None¶

isBold: Optional[bool] = None¶

__init__(name, chainId, parentChainId, ethBridge, confirmPeriodBlocks, isCustom, tokenBridge=None, teleporter=None, isTestnet=True, explorerUrl=None, retryableLifetimeSeconds=None, nativeToken=None, isBold=None)¶

arbitrum_py.data_entities.networks.get_arbitrum_networks()[source]¶

Returns all registered Arbitrum networks.

Returns a list of all Arbitrum networks known to the SDK, including both default networks and any custom networks registered by the user.

Return type:: List[ArbitrumNetwork]
Returns:: List of ArbitrumNetwork objects

arbitrum_py.data_entities.networks.is_parent_network(parent_chain_or_chain_id)[source]¶

Determines if a chain is a parent of any other chain.

A chain is considered a parent if any other chain references it as its parentChainId. The chain could be an L1 or an L2 chain.

Parameters:: parent_chain_or_chain_id (Union[ArbitrumNetwork, int]) – Either an ArbitrumNetwork object or chain ID
Return type:: bool
Returns:: True if the chain is a parent of any other chain, False otherwise

arbitrum_py.data_entities.networks.get_children_for_network(parent_chain_or_chain_id)[source]¶

Returns all child chains for a given chain.

Finds all Arbitrum networks that have the specified chain as their parent.

Parameters:: parent_chain_or_chain_id (Union[ArbitrumNetwork, int]) – Either an ArbitrumNetwork object or chain ID
Return type:: List[ArbitrumNetwork]
Returns:: List of ArbitrumNetwork objects that are children of the given chain

arbitrum_py.data_entities.networks.get_arbitrum_network(provider_or_chain_id)[source]¶

Returns the Arbitrum network for a provider or chain ID.

If given a chain ID, looks up the network directly. If given a provider, gets the chain ID from the provider first.

Parameters:: provider_or_chain_id (Union[SignerOrProvider, Web3, int]) – Either a chain ID or a provider/signer
Return type:: Optional[ArbitrumNetwork]
Returns:: The matching ArbitrumNetwork or None if not found
Raises:: ArbSdkError – If the chain is not a recognized Arbitrum chain

arbitrum_py.data_entities.networks.get_arbitrum_network_by_chain_id(chain_id)[source]¶

Returns an Arbitrum network by its chain ID.

Parameters:: chain_id (int) – The chain ID to look up
Return type:: ArbitrumNetwork
Returns:: The matching ArbitrumNetwork
Raises:: ArbSdkError – If no network is found for the chain ID

arbitrum_py.data_entities.networks.get_arbitrum_network_by_provider(provider)[source]¶

Returns an Arbitrum network for a provider.

Gets the chain ID from the provider and looks up the corresponding network.

Parameters:: provider (Union[SignerOrProvider, Web3]) – A provider or signer connected to an Arbitrum chain
Return type:: ArbitrumNetwork
Returns:: The matching ArbitrumNetwork
Raises:: ArbSdkError – If the provider’s chain is not a recognized Arbitrum chain

arbitrum_py.data_entities.networks.get_native_token(bridge, provider)[source]¶

Gets the native token address from a bridge contract.

Attempts to call nativeToken() on the bridge contract. Returns ADDRESS_ZERO if the call fails or the contract doesn’t implement the method.

Parameters:

bridge (NewType()(HexAddress, NewType()(HexStr, str))) – Address of the bridge contract
provider (Union[SignerOrProvider, Web3]) – Provider for making the contract call

Return type:

NewType()(HexAddress, NewType()(HexStr, str))

Returns:

The native token address or ADDRESS_ZERO

arbitrum_py.data_entities.networks.get_arbitrum_network_information_from_rollup(rollup_address, parent_provider)[source]¶

Gets network information from a rollup contract.

Fetches core network information by calling various methods on the rollup contract deployed on the parent chain.

Parameters:

rollup_address (NewType()(HexAddress, NewType()(HexStr, str))) – Address of the rollup contract
parent_provider (Union[SignerOrProvider, Web3]) – Provider for the parent chain

Returns:

parentChainId (int)
confirmPeriodBlocks (int)
ethBridge (EthBridge)
nativeToken (str)

Return type:

Dict containing

arbitrum_py.data_entities.networks.register_custom_arbitrum_network(network, options=None)[source]¶

Registers a custom Arbitrum network.

Adds a user-defined network to the SDK’s network registry. The network must have isCustom=True.

Parameters:

network (ArbitrumNetwork) – The ArbitrumNetwork to register
options (Optional[Dict[str, bool]]) –
Optional dict with: - throwIfAlreadyRegistered (bool): If True, raises an error if the

network is already registered

Return type:

ArbitrumNetwork

Returns:

The registered ArbitrumNetwork

Raises:

ArbSdkError – If network.isCustom is False or if the network is already registered and throwIfAlreadyRegistered is True

arbitrum_py.data_entities.networks.dict_to_arbitrum_network_instance(data)[source]¶

Converts a dictionary to an ArbitrumNetwork instance.

Creates a properly typed ArbitrumNetwork instance from a dictionary, handling nested objects like EthBridge and TokenBridge.

Parameters:: data (Union[Dict[str, Any], CaseDict]) – Dict or CaseDict containing network data
Return type:: ArbitrumNetwork
Returns:: An ArbitrumNetwork instance with all fields properly typed

Example

>>> network = dict_to_arbitrum_network_instance({
...     'chainId': 42161,
...     'eth_bridge': {...},
...     'tokenBridge': existing_token_bridge_instance,
... })

arbitrum_py.data_entities.networks.create_network_state_handler()[source]¶

Creates a handler for managing network state.

Returns a dictionary containing functions to manage the network registry, particularly useful for testing and development.

Returns:

resetNetworksToDefault: Function to reset networks to initial state

Return type:

Dict with

arbitrum_py.data_entities.networks.get_nitro_genesis_block(arbitrum_chain_or_chain_id)[source]¶

Gets the Nitro genesis block for a chain.

Returns the block number where the Nitro upgrade was activated for a chain. For Arbitrum One this is ARB1_NITRO_GENESIS_L2_BLOCK, for others it’s 0.

Parameters:: arbitrum_chain_or_chain_id (Union[ArbitrumNetwork, int]) – Either an ArbitrumNetwork or chain ID
Return type:: int
Returns:: The Nitro genesis block number

arbitrum_py.data_entities.networks.get_multicall_address(provider_or_chain_id)[source]¶

Gets the multicall contract address for a chain.

Looks up the multicall address in the chain’s token bridge configuration. If not found, checks if any chain references this as a parent and returns that chain’s parent multicall address.

Parameters:: provider_or_chain_id (Union[SignerOrProvider, Web3, int]) – Either a chain ID or provider
Return type:: NewType()(HexAddress, NewType()(HexStr, str))
Returns:: The multicall contract address
Raises:: ValueError – If the chain is not recognized

arbitrum_py.data_entities.networks.map_l2_network_token_bridge_to_token_bridge(input_bridge)[source]¶

Maps the older L2Network.tokenBridge object (SDK v3) to the new v4 TokenBridge format.

Parameters:: input_bridge – The legacy object with fields like l1GatewayRouter, l2GatewayRouter, etc.
Return type:: TokenBridge
Returns:: A new TokenBridge dataclass instance reflecting the updated naming conventions.

arbitrum_py.data_entities.networks.map_l2_network_to_arbitrum_network(l2_network)[source]¶

Maps the old L2Network object (SDK v3) to a new ArbitrumNetwork (SDK v4). Retains other fields while renaming chainID -> chainId, partnerChainID -> parentChainId, etc.

Parameters:: l2_network (Dict[str, Any]) – The old L2Network object as a dictionary
Return type:: ArbitrumNetwork
Returns:: A new ArbitrumNetwork instance

arbitrum_py.data_entities.networks.assert_arbitrum_network_has_token_bridge(network)[source]¶

Asserts that a network has token bridge configuration.

Parameters:: network (ArbitrumNetwork) – The ArbitrumNetwork to check
Raises:: ArbSdkError – If the network does not have a token bridge configuration
Return type:: None

arbitrum_py.data_entities.networks.is_arbitrum_network_native_token_ether(network)[source]¶

Checks if a network uses ETH as its native token.

A network uses ETH as its native token if nativeToken is None or ADDRESS_ZERO. Otherwise, it uses an ERC20 token from the parent chain.

Parameters:: network (ArbitrumNetwork) – The ArbitrumNetwork to check
Return type:: bool
Returns:: True if the network uses ETH as its native token, False otherwise

arbitrum_py.data_entities.networks.reset_networks_to_default()¶

Return type:: None