Inbox

class arbitrum_py.inbox.inbox.InboxTools(parent_signer, child_chain)

Bases: object

Tools for interacting with the Inbox and Bridge contracts on Arbitrum networks. Similar to the TypeScript ‘InboxTools’ class, includes methods for forced inclusion of delayed messages, sending child-signed transactions, etc.

__init__(parent_signer, child_chain)

Parameters:

• parent_signer (SignerOrProvider) – A Python ‘signer’ object that includes ‘account’ & ‘provider’

• child_chain (ArbitrumNetwork) – The ArbitrumNetwork object describing L2 chain config

find_first_block_below(block_number, block_timestamp)

Finds a block whose ‘timestamp’ is below a given timestamp, starting from ‘block_number’ and working backwards if needed.

Parameters:

• block_number (int) – A starting block number

• block_timestamp (int) – The target timestamp

Returns:

The block (dict) if found

Raises:

On failure to find a suitable block

is_contract_creation(child_transaction_request)

Check if the transaction is a contract creation (i.e. no ‘to’ address or zero address).

Return type:

bool

estimate_arbitrum_gas(child_tx_request, child_provider)

Estimate gas components for an Arbitrum transaction.

We should use nodeInterface to get the gas estimate because we are making a delayed inbox message which doesn’t need parent calldata gas fee part.

Parameters:

• child_tx_request (Dict[str, Any]) – Transaction parameters for the child chain

• child_provider (Web3) – Web3 provider for the child chain

Return type:

Dict[str, Any]

Returns:

Gas components including estimates for L1 and L2 portions

Raises:

ArbSdkError – If gas estimation fails

get_force_includable_block_range(block_number_range_size)

Get block range where delayed messages can be force-included.

Uses SequencerInbox.maxTimeVariation() to determine when messages become eligible for forced inclusion.

Parameters:

block_number_range_size (int) – Number of blocks to look back from the first eligible block

Return type:

Dict[str, int]

Returns:

Dict containing fromBlock and toBlock numbers

get_events_and_increase_range(bridge_contract, search_range_blocks, max_search_range_blocks, range_multiplier)

Recursively fetch MessageDelivered events.

Look for force includable events in the search range blocks. If no events are found, the search range is increased incrementally up to the max search range blocks.

Parameters:

• bridge_contract – Bridge contract instance

• search_range_blocks (int) – Initial block range to search

• max_search_range_blocks (int) – Maximum block range to search

• range_multiplier (int) – Factor to multiply range by on each iteration

Return type:

List[Dict[str, Any]]

Returns:

List of MessageDelivered events found

Raises:

ArbSdkError – If no events found within max range

get_force_includable_event(max_search_range_blocks=19635, start_search_range_blocks=100, range_multiplier=2)

Find the event of the latest message that can be force included.

Parameters:

• max_search_range_blocks (int) – Max blocks to look back (~3 days default)

• start_search_range_blocks (int) – Initial block range to search

• range_multiplier (int) – Factor to multiply range by on each iteration

Return type:

Optional[Dict[str, Any]]

Returns:

ForceInclusionParams if a forceable message is found, None otherwise

force_include(message_delivered_event=None, overrides=None)

Force includes all eligible messages in the delayed inbox.

The inbox contract doesn’t allow a message to be force-included until after a delay period has been completed.

Parameters:

• message_delivered_event (Optional[Dict[str, Any]]) – Event and accumulator from get_force_includable_event

• overrides (Optional[Dict[str, Any]]) – Optional transaction parameter overrides

Return type:

Optional[Dict[str, Any]]

Returns:

Transaction receipt if successful, None if no event to include

Raises:

ArbSdkError – If force inclusion fails

send_child_signed_tx(signed_tx)

Send a child-chain-signed transaction via the delayed inbox on L1.

The childChain user signs the transaction for L2 execution, and we embed it in an L1 transaction that is eventually replayed on L2. If it isn’t included within 24 hours, you can force include it.

Parameters:

signed_tx (Union[str, bytes]) – The child’s transaction raw signature data (hex or bytes)

Return type:

Dict[str, Any]

Returns:

Transaction receipt on L1 for sending the message

Example

>>> # Sign and send L2 transaction via L1
>>> tx = {'to': '0x1234...', 'value': 1000000000000000000}
>>> signed = inbox_tools.sign_child_tx(tx, l2_signer)
>>> receipt = inbox_tools.send_child_signed_tx(signed)

sign_child_tx(tx_request, child_signer)

Sign a transaction for the child chain (L2).

Typically, we then embed this signed Tx in the L1 delayed inbox message via send_child_signed_tx(…).

Parameters:

• tx_request (Dict[str, Any]) – A dict with fields like ‘to’, ‘data’, ‘value’, ‘nonce’, optional ‘gasPrice’ or EIP-1559 fields

• child_signer (SignerOrProvider) – The child’s local signer object with an account & provider (connected to L2)

Return type:

bytes

Returns:

Raw signed transaction bytes

Raises:

ArbSdkError – If gas estimation fails