Lib¶

Utility functions for the Arbitrum SDK.

This module provides common utility functions for: - Chain interaction (getting base fees, transaction receipts) - Block management (finding L1/L2 block correspondences) - Token decimals handling - General utilities (waiting, type checking)

arbitrum_py.utils.lib.wait(ms)[source]¶

Wait for the specified number of milliseconds.

Parameters:: ms (int) – Time in milliseconds to sleep
Return type:: None

Example

>>> wait(1000)  # Wait for 1 second

arbitrum_py.utils.lib.get_base_fee(provider)[source]¶

Retrieve the base fee per gas from the latest block.

Parameters:: provider (Web3) – A Web3 provider connected to an EIP-1559 chain
Return type:: NewType()(Wei, int)
Returns:: The base fee in Wei
Raises:: ArbSdkError – If baseFeePerGas is not found (e.g., non-EIP1559 chain)

Example

>>> base_fee = get_base_fee(web3)
>>> print(f"Current base fee: {Web3.from_wei(base_fee, 'gwei')} gwei")

arbitrum_py.utils.lib.get_transaction_receipt(provider, tx_hash, confirmations=None, timeout=None)[source]¶

Retrieve a transaction receipt with optional confirmation count or timeout.

This function can operate in two modes: 1. Immediate retrieval (no confirmations/timeout) 2. Wait for confirmations or timeout

Parameters:

provider (Web3) – Web3 provider instance
tx_hash (NewType()(HexStr, str)) – Transaction hash to fetch
confirmations (Optional[int]) – Number of block confirmations to wait for
timeout (Optional[int]) – Maximum time to wait in milliseconds

Return type:

Optional[TxReceipt]

Returns:

The transaction receipt if found and confirmed, None otherwise

Raises:

Exception – Any unexpected errors during receipt retrieval

Example

>>> # Wait for 2 confirmations with 30 second timeout
>>> receipt = get_transaction_receipt(
...     web3,
...     "0x...",
...     confirmations=2,
...     timeout=30000
... )

arbitrum_py.utils.lib.is_defined(value)[source]¶

Check if a value is defined (not None).

This is the Python equivalent of TypeScript’s isDefined type guard.

Parameters:: value (Optional[TypeVar(T)]) – Any value to check
Return type:: bool
Returns:: True if the value is not None, False otherwise

Example

>>> assert is_defined(0) is True
>>> assert is_defined(None) is False

arbitrum_py.utils.lib.is_arbitrum_chain(provider)[source]¶

Check if a provider is connected to an Arbitrum chain.

This function attempts to call arbOSVersion on the ArbSys precompile, which only exists on Arbitrum chains.

Parameters:: provider (Web3) – Web3 provider to check
Return type:: bool
Returns:: True if connected to an Arbitrum chain, False otherwise

Example

>>> # Check if connected to Arbitrum
>>> if is_arbitrum_chain(web3):
...     print("Connected to Arbitrum!")

arbitrum_py.utils.lib.get_first_block_for_l1_block(arbitrum_provider, for_l1_block, allow_greater=False, min_arbitrum_block=None, max_arbitrum_block='latest')[source]¶

Find the first Arbitrum (L2) block that corresponds to a given L1 block.

This function performs a binary search over the L2 chain to find the first block that references the given L1 block number. If allow_greater is True, it will return the first L2 block with an L1 block number >= the target.

Parameters:

arbitrum_provider (Web3) – Web3 provider connected to Arbitrum
for_l1_block (NewType()(BlockNumber, int)) – Target L1 block number to find correspondence for
allow_greater (bool) – If True, allow returning a block with higher L1 number
min_arbitrum_block (Optional[NewType()(BlockNumber, int)]) – Minimum L2 block to consider (defaults to Nitro genesis)
max_arbitrum_block (Union[NewType()(BlockNumber, int), str]) – Maximum L2 block or ‘latest’

Return type:

Optional[NewType()(BlockNumber, int)]

Returns:

The L2 block number if found, None otherwise

Raises:

ArbSdkError – If invalid block range or provider configuration

Example

>>> l2_block = get_first_block_for_l1_block(
...     web3,
...     for_l1_block=15000000,
...     allow_greater=True
... )

arbitrum_py.utils.lib.get_block_ranges_for_l1_block(arbitrum_provider, for_l1_block, allow_greater=False, min_arbitrum_block=None, max_arbitrum_block='latest')[source]¶

Find the range of Arbitrum blocks corresponding to an L1 block.

This function finds both the first and last L2 blocks that correspond to a given L1 block number.

Parameters:

arbitrum_provider (Web3) – Web3 provider connected to Arbitrum
for_l1_block (NewType()(BlockNumber, int)) – Target L1 block to find range for
allow_greater (bool) – If True, allow blocks with higher L1 numbers
min_arbitrum_block (Optional[NewType()(BlockNumber, int)]) – Minimum L2 block to consider
max_arbitrum_block (Union[NewType()(BlockNumber, int), str]) – Maximum L2 block or ‘latest’

Return type:

Tuple[Optional[NewType()(BlockNumber, int)], Optional[NewType()(BlockNumber, int)]]

Returns:

Tuple of (start_block, end_block), both None if not found

Example

>>> start, end = get_block_ranges_for_l1_block(
...     web3,
...     for_l1_block=15000000
... )
>>> if start and end:
...     print(f"L2 blocks {start} to {end} correspond to L1 block 15000000")

arbitrum_py.utils.lib.get_native_token_decimals(parent_provider, child_network)[source]¶

Get the number of decimals for the chain’s native token.

For ETH or zero address, returns 18. Otherwise queries the token contract.

Parameters:

parent_provider (Web3) – Web3 provider for parent chain
child_network (ArbitrumNetwork) – ArbitrumNetwork configuration

Return type:

int

Returns:

Number of decimals for the native token

Raises:

ArbSdkError – If unable to determine token decimals

Example

>>> decimals = get_native_token_decimals(web3, network)
>>> print(f"Native token has {decimals} decimals")

arbitrum_py.utils.lib.scale_from_18_decimals_to_native_token_decimals(amount, decimals)[source]¶

Scale an amount from 18 decimals to native token decimals.

Parameters:

amount (int) – The integer to scale (assumes 18 decimals).
decimals (int) – The chain’s native token decimals.

Return type:

int

Returns:

Scaled integer.

arbitrum_py.utils.lib.scale_from_native_token_decimals_to_18_decimals(amount, decimals)[source]¶

Scale an amount from native token decimals to 18 decimals.

Parameters:

amount (int) – Amount in native token decimals
decimals (int) – Current number of decimals

Return type:

int

Returns:

Scaled amount with 18 decimals

Example

>>> # Convert from 6 decimals to 18 decimals
>>> eth_amount = scale_from_native_token_decimals_to_18_decimals(
...     1_000_000,  # 1.0 in 6 decimals
...     6
... )