ERC20Bridger¶

class arbitrum_py.asset_bridger.erc20_bridger.Erc20Bridger(child_network)[source]¶

Bases: AssetBridger[DepositParams, WithdrawParams]

Bridger for moving ERC20 tokens between parent and child chains.

This class provides functionality for bridging ERC20 tokens between a parent chain (typically Ethereum mainnet) and a child chain (an Arbitrum chain). It handles token approvals, deposits, withdrawals, and gateway interactions.

Variables:

MAX_APPROVAL (int) – Maximum approval amount (2^256 - 1)
MIN_CUSTOM_DEPOSIT_GAS_LIMIT (int) – Minimum gas limit for custom token deposits
child_network (ArbitrumNetwork) – Network configuration for the child chain
tokenBridge (TokenBridge) – Token bridge configuration

MAX_APPROVAL: int = 115792089237316195423570985008687907853269984665640564039457584007913129639935¶

MIN_CUSTOM_DEPOSIT_GAS_LIMIT: int = 275000¶

__init__(child_network)[source]¶

Initialize the ERC20 bridger.

Parameters:: child_network (ArbitrumNetwork) – ArbitrumNetwork instance containing chain configuration including chain IDs and token bridge details.
Raises:: ArbSdkError – If child_network lacks token bridge configuration

classmethod from_provider(child_provider)[source]¶

Create an Erc20Bridger instance from a child chain provider.

Parameters:: child_provider (Web3) – Web3 provider connected to the child chain
Returns:: New bridger instance configured for the detected network
Return type:: Erc20Bridger
Raises:: ArbSdkError – If network detection fails or network is not supported

get_parent_gateway_address(erc20_parent_address, parent_provider)[source]¶

Get the parent chain gateway address for a token.

Parameters:

erc20_parent_address (NewType()(Address, bytes)) – Address of the ERC20 token on parent chain
parent_provider (Web3) – Web3 provider for parent chain

Returns:

Gateway contract address that handles this token

Return type:

Address

Raises:

ArbSdkError – If network validation fails or gateway lookup fails

get_child_gateway_address(erc20_parent_address, child_provider)[source]¶

Get the child chain gateway address for a token.

Parameters:

erc20_parent_address (NewType()(Address, bytes)) – Address of the ERC20 token on parent chain
child_provider (Web3) – Web3 provider for child chain

Returns:

Gateway contract address that handles this token

Return type:

Address

Raises:

ArbSdkError – If network validation fails or gateway lookup fails

get_approve_gas_token_request(params)[source]¶

Creates a transaction request for approving the custom gas token to be spent by the relevant gateway on the parent chain. If the chain uses ETH natively, this is unnecessary and will error.

Parameters:: params (Dict[str, Any]) – A dict with ‘erc20ParentAddress’, ‘parentProvider’, ‘amount’ (optional), etc.
Return type:: TxParams
Returns:: dict representing a transaction request with ‘to’, ‘data’, and ‘value’
Raises:: ValueError – If chain uses ETH as its native/gas token

approve_gas_token(params)[source]¶

Approves the custom gas token to be spent by the relevant gateway on the parent chain. This only applies if the chain does NOT use ETH natively.

Parameters:: params (Dict[str, Any]) – Dictionary that can either be: 1) ApproveParams with ‘erc20ParentAddress’ and ‘parentSigner’ 2) Or a transaction request dict with ‘txRequest’, ‘parentSigner’
Return type:: ParentTransactionReceipt
Returns:: Transaction receipt object from the parent chain
Raises:: ValueError – If chain uses ETH as its native/gas token

get_approve_token_request(params)[source]¶

Creates a transaction request to approve an ERC20 token for deposit. The tokens will be approved for whichever gateway the router returns.

Parameters:: params (Dict[str, Any]) – A dict with ‘erc20ParentAddress’, ‘parentProvider’, optional ‘amount’, etc.
Return type:: TxParams
Returns:: A transaction request dict with ‘to’, ‘data’, ‘value’ = 0

is_approve_params(params)[source]¶

Helper to check whether ‘params’ is a standard ‘ApproveParams’ (which includes ‘erc20ParentAddress’) vs. a custom txRequest.

Return type:: bool

approve_token(params)[source]¶

Approves the ERC20 token on the parent chain for bridging.

Parameters:: params (Dict[str, Any]) – A dictionary that can either be standard ‘ApproveParams’ or contain a pre-built ‘txRequest’
Return type:: ParentTransactionReceipt
Returns:: Transaction receipt from the parent chain

get_withdrawal_events(child_provider, gateway_address, filter_dict, parent_token_address=None, from_address=None, to_address=None)[source]¶

Get the child network events (WithdrawalInitiated) created by a token withdrawal.

Parameters:

child_provider (Web3) – Web3 provider for the child chain
gateway_address (NewType()(Address, bytes)) – Address of the child gateway
filter_dict (Dict[str, Any]) – {‘fromBlock’: X, ‘toBlock’: Y}, specifying the block range
parent_token_address (Optional[NewType()(Address, bytes)]) – Optional filter for a specific parent token
from_address (Optional[NewType()(Address, bytes)]) – Optional filter for the “from” address
to_address (Optional[NewType()(Address, bytes)]) – Optional filter for the “to” address

Return type:

List[Dict[str, Any]]

Returns:

A list of event objects including ‘txHash’ for each withdrawal event

looks_like_weth_gateway(potential_weth_gateway_address, parent_provider)[source]¶

Ad-hoc check to see if the given address is a WETH gateway. We attempt to read the ‘l1Weth()’ method. If that fails with a call exception, it’s not WETH.

Return type:: bool

is_weth_gateway(gateway_address, parent_provider)[source]¶

Check if a provided gateway address is the WETH gateway.

Parameters:

gateway_address (NewType()(Address, bytes)) – The suspected WETH gateway address
parent_provider (Web3) – Web3 provider for the parent chain

Return type:

bool

Returns:

bool

get_child_token_contract(child_provider, child_token_addr)[source]¶

Returns a contract object pointing to the child ERC20 token. Does not validate the contract code to confirm it’s indeed an ERC20.

Return type:: Contract

get_parent_token_contract(parent_provider, parent_token_addr)[source]¶

Returns a contract object pointing to the parent ERC20 token.

Return type:: Contract

get_child_erc20_address(erc20_parent_address, parent_provider)[source]¶

Given a parent chain token address, compute the corresponding child chain ERC20 token address.

Parameters:

erc20_parent_address (NewType()(Address, bytes)) – The parent chain token address
parent_provider (Web3) – A Web3 provider for the parent chain

Return type:

NewType()(Address, bytes)

Returns:

The corresponding child chain address

get_parent_erc20_address(erc20_child_chain_address, child_provider)[source]¶

Given a child chain ERC20 token address, compute the corresponding parent chain token address. Also verify that the child chain router agrees on this mapping.

Parameters:

erc20_child_chain_address (NewType()(Address, bytes)) – The address of the token on the child chain
child_provider (Web3) – Web3 provider for the child chain

Return type:

NewType()(Address, bytes)

Returns:

The corresponding address on the parent chain

Raises:

ArbSdkError if the child token does not match the computed parent token –

is_deposit_disabled(parent_token_address, parent_provider)[source]¶

Whether the deposit for this token has been disabled on the parent router.

Parameters:

parent_token_address (NewType()(Address, bytes)) – The parent’s ERC20 address
parent_provider (Web3) – Parent chain provider

Return type:

bool

Returns:

True if the token is disabled, False otherwise

apply_defaults(params)[source]¶

Ensures default addresses for ‘excessFeeRefundAddress’, ‘callValueRefundAddress’, ‘destinationAddress’ are set to ‘from’ if not otherwise specified.

Return type:: Dict[str, Any]

get_deposit_request_call_value(deposit_params)[source]¶

Compute the ETH callValue needed for a deposit, if the chain uses ETH as its gas token. Otherwise, returns 0 because fees are handled differently.

Return type:: NewType()(Wei, int)

get_deposit_request_outbound_transfer_inner_data(deposit_params, decimals)[source]¶

Builds the ‘innerData’ argument for the gateway’s outboundTransfer/outboundTransferCustomRefund calls. If the chain uses ETH natively, we pass [maxSubmissionCost, ‘0x’]. Otherwise, also pack the fee inside.

Return type:: NewType()(HexStr, str)

get_deposit_request(params)[source]¶

Constructs the deposit (parent->child) bridging transaction data.

Parameters:

params (Dict[str, Any]) –
{ ‘from’, ‘parentProvider’, ‘childProvider’, ‘erc20ParentAddress’, ‘amount’, optional ‘excessFeeRefundAddress’, ‘callValueRefundAddress’, ‘destinationAddress’, ‘maxSubmissionCost’, ‘retryableGasOverrides’, …
} –

Return type:

ParentToChildTransactionRequest

Returns:

A ParentToChildTransactionRequest dict with ‘txRequest’, ‘retryableData’, ‘isValid()’

deposit(params)[source]¶

Execute a token deposit from the parent chain to the child chain. If the user has not provided a prebuilt transaction, we build it via get_deposit_request().

Parameters:: params (Dict[str, Any]) – Erc20DepositParams (with ‘parentSigner’, ‘childProvider’, ‘erc20ParentAddress’, etc.) OR a pre-built ParentToChildTxReqAndSignerProvider
Return type:: ParentTransactionReceipt
Returns:: A ParentContractCallTransaction receipt-like object

get_withdrawal_request(params)[source]¶

Get the arguments for calling the token withdrawal function from the child chain.

Parameters:: params (Dict[str, Any]) – Erc20WithdrawParams + ‘from’
Return type:: ChildToParentTransactionRequest
Returns:: ChildToParentTransactionRequest dict with ‘txRequest’ + optional ‘estimateParentGasLimit’

withdraw(params)[source]¶

Withdraw tokens from the child network back to the parent chain.

Parameters:

childSigner (- Erc20WithdrawParams +) –
ChildToParentTxReqAndSigner (- OR) –

Return type:

ChildTransactionReceipt

Returns:

A ChildContractTransaction receipt-like object

is_registered(params)[source]¶

Checks if the token has been properly registered on both the parent and child gateways. Useful for tokens using a custom gateway.

Parameters:

params (Dict[str, Any]) –
{ “erc20ParentAddress”: str, “parentProvider”: Web3, “childProvider”: Web3
} –

Return type:

bool

Returns:

bool - True if the token is fully registered, False otherwise

_solidity_encode(types, values)[source]¶

Helper for ABI-encoding arbitrary fields for calls like outboundTransfer. Using eth_abi.encode(…) under the hood.

Return type:: NewType()(HexStr, str)

class arbitrum_py.asset_bridger.erc20_bridger.AdminErc20Bridger(child_network)[source]¶

Bases: Erc20Bridger

Extended bridging class with admin functionality for registering custom tokens, setting gateways, etc.

percent_increase(num, increase)[source]¶

Return type:: int

get_approve_gas_token_for_custom_token_registration_request(params)[source]¶

Similar to get_approve_gas_token_request, but used specifically for custom token registration. The difference is that we approve the parent token address itself to spend the gas token.

Return type:: TxParams

approve_gas_token_for_custom_token_registration(params)[source]¶

Approves the custom gas token for the given custom token’s registration transaction. This is needed so we can pay fees using the custom gas token if the chain doesn’t use ETH natively.

Return type:: ParentTransactionReceipt

register_custom_token(parent_token_address, child_token_address, parent_signer, child_provider)[source]¶

Register a custom (non-standard) token on Arbitrum. The token must already be deployed on both parent & child. The parent token must implement ICustomToken, and the child token must implement IArbToken.

Parameters:

parent_token_address (NewType()(Address, bytes)) – Address of the parent token contract on the parent chain
child_token_address (NewType()(Address, bytes)) – Address of the child token contract on the child chain
parent_signer (Any) – The signer object on the parent chain with permission to call registerTokenOnL2
child_provider (Web3) – A Web3 provider connected to the child chain

Return type:

ParentTransactionReceipt

Returns:

A ParentTransactionReceipt object for the transaction

get_parent_gateway_set_events(parent_provider, filter_dict)[source]¶

Get all the GatewaySet events on the parent chain’s L1GatewayRouter within a given block range.

Parameters:

parent_provider (Web3) – Web3 provider for parent chain
filter_dict (Dict[str, Any]) – {‘fromBlock’: X, ‘toBlock’: Y}

Return type:

List[Dict[str, Any]]

Returns:

List of the GatewaySet events

get_child_gateway_set_events(child_provider, filter_dict, custom_network_child_gateway_router=None)[source]¶

Get all the GatewaySet events on the child chain’s L2GatewayRouter within a given block range.

Parameters:

child_provider (Web3) – Web3 provider for child chain
filter_dict (Dict[str, Any]) – {‘fromBlock’: X, ‘toBlock’: Y}
custom_network_child_gateway_router (Optional[NewType()(Address, bytes)]) – If the network is custom, we must pass the child router address

Return type:

List[Dict[str, Any]]

Returns:

List of the GatewaySet events

Raises:

ArbSdkError if the network is custom but the router address is not provided –

set_gateways(parent_signer, child_provider, token_gateways, options=None)[source]¶

Registers or updates multiple token->gateway mappings on the parent gateway router at once (admin call).

Parameters:

parent_signer (Any) – The signer on the parent chain
child_provider (Web3) – Web3 provider for the child chain
token_gateways (List[Dict[str, NewType()(Address, bytes)]]) – A list of dicts with {“tokenAddr”: X, “gatewayAddr”: Y}
options (Optional[GasOverrides]) – Optional GasOverrides

Return type:

ParentTransactionReceipt

Returns:

A ParentContractCallTransaction receipt

native_token: Optional[str]¶