@frequencyadvisors/freeq-bridge-sdk v1.0.2

Arbitrum Bridge Tools

A comprehensive command-line suite that streamlines both ETH and ERC20 bridging between an Arbitrum L2 network and an L1 chain. This set of tools allows you to:

• Deposit Assets: Seamlessly move ETH or tokens from L1 to L2 using Arbitrum’s standard gateway contracts.
• Initiate Withdrawals: Start an ETH or ERC20 withdrawal from L2 to L1, specifying the desired amount.
• Monitor Status: Check the progress of a pending withdrawal by its L2 transaction hash, including time remaining in the challenge period.
• Automate Execution: Optionally wait for the challenge period to conclude and then finalize (execute) the withdrawal on L1 automatically.
• Proof Generation: Transparently generate and utilize outbox proofs required for finalizing withdrawals on L1.
• Scan & Claim: Detect unclaimed withdrawals and optionally execute them if they are ready, reducing manual oversight.

By integrating directly with Arbitrum’s bridge contracts, these tools give developers and operators a reliable, scriptable workflow for managing cross-chain asset transfers in a safe, transparent manner.

Prerequisites

• Node.js (v20+)
• npm or yarn
• An Ethereum wallet private key with sufficient funds on the L2 network.
• Access to both L2 and L1 JSON-RPC endpoints.

Setup

1. Clone the repository:

   git clone https://github.com/your-org/arbitrum-bridge-withdrawal.git
   cd arbitrum-bridge-withdrawal

2. Install dependencies:

   npm install

3. Configure environment variables:

   Copy one of the provided environment templates to .env and fill in the required values:

   cp .env.template.bera-altlayer .env

   Update the following variables in your .env file:

   L2_PRIVATE_KEY=0x...
   L1_PRIVATE_KEY=0x...
   L2_RPC_URL=https://orbit-berachain-testnet.alt.technology
   L1_RPC_URL=https://bartio.rpc.berachain.com
   OUTBOX_ADDRESS=0x7dB9dD05961B6144d2270Ef6ADd875381BF6c363
   CHALLENGE_PERIOD_SECONDS=7200

Usage

Below is a summary of the main commands and their usage patterns. Each command reads settings from your .env file, so ensure the relevant environment variables are set before running.

Check Balances (L1 or L2)

npm run balance -- [options]

Options:

• -a, --address <address>: Address to query (default: will use the address derived from L1_PRIVATE_KEY if none provided).
• -l, --layer <layer>: Specify which layer(s) to check: 1, 2, or both (default is both).

Examples:

# Check both L1 and L2 for a specific address
npm run balance -- --address 0xabcd... --layer both

# Check only L2, default address from L1_PRIVATE_KEY
npm run balance -- --layer 2

Dump Block or Transaction Info

npm run dumpInfo -- [options]

Options:

• --block <blockRef>: A block number or block hash to inspect.
• --tx <txHash>: A transaction hash to inspect.
• --layer <layer>: Which layer to query (l1 or l2). Default is l2.

You must specify exactly one of --block or --tx.

Examples:

# Dump info for block 12345 on L2
npm run dumpInfo -- --block 12345 --layer l2

# Dump info for a particular transaction on L1
npm run dumpInfo -- --tx 0x123abc... --layer l1

Deposit ETH (L1 -> L2)

npm run deposit -- --amount <amount>

Option:

• --amount <amount>: Amount of ETH to deposit in "human-readable" form (e.g., 0.1).

Example:

# Deposit 0.32 ETH from L1 to L2
npm run deposit -- --amount 0.32

On success, it will display the final L1 balance and the expected L2 transaction hash for the deposit.

Withdraw ETH (L2 -> L1)

npm run withdraw -- [options]

Options (use exactly one of --amount or --tx-hash):

• --amount <amount>: Amount of ETH (in human-readable form) to withdraw from L2.
• --tx-hash <hash>: An existing L2 withdrawal transaction hash to finalize on L1.
• --wait: (Optional) Automatically wait until the challenge period ends and execute the withdrawal on L1.

Examples:

# Initiate a new 0.1 ETH withdrawal from L2 -> L1
npm run withdraw -- --amount 0.1

# Check/complete a previously initiated withdrawal
npm run withdraw -- --tx-hash 0x6fc845614339ce... --wait

Scan for Unclaimed Withdrawals

npm run scan-withdrawals -- [options]

Options:

• --from-block <block>: Start scanning at this L2 block (default: 0).
• --to-block <block>: End scanning at this L2 block (default: latest).
• --recipient <address>: Filter withdrawals by recipient (optional).
• --withdraw: Automatically attempt to execute any withdrawals that are ready_for_execution.
• --batch-size <number>: Number of blocks to fetch at a time (default: 2000).

Example:

# Scan from block 0 to the latest block for all unclaimed withdrawals, then attempt to execute them
npm run scan-withdrawals -- --from-block 0 --withdraw

Check Withdrawal Status

npm run checkWithdrawStatus -- --tx-hash <l2TxHash>

Option:

• --tx-hash <hash>: The L2 transaction hash of the withdrawal.

This will show whether the withdrawal is still in the challenge period, ready for execution, or already executed.

Example:

npm run checkWithdrawStatus -- --tx-hash 0x6fc845614339ce...

Deposit ERC20 (L1 -> L2)

npm run depositERC20 -- --token <address> --amount <amount> [options]

Required:

• --token <address>: The L1 ERC20 token address.
• --amount <amount>: The human-readable token amount (e.g. 100 for 100 tokens).

Optional:

• --recipient <address>: The L2 address to receive the tokens (defaults to the signer’s address).

Example:

# Deposit 16 tokens of contract 0xC5b6... to L2
npm run depositERC20 -- --token 0xC5b6EeF34404B74a43075e47bF93AaCb8FC5e9AD --amount 16

Withdraw ERC20 (L2 -> L1)

npm run withdrawERC20 -- --token <address> [options]

Required:

• --token <address>: The L2 ERC20 token address.

Options (use exactly one of --amount or --tx-hash):

• --amount <amount>: Amount to withdraw (human-readable form, e.g. 10).
• --tx-hash <hash>: Execute an already-initiated withdrawal via its L2 tx hash.
• --wait: If the withdrawal is still in-challenge, wait until the challenge period expires and execute automatically.

Example:

# Initiate a new withdrawal of 25 tokens from L2 -> L1
npm run withdrawERC20 -- --token 0x2aCce539A4c6... --amount 25

# Finalize a withdrawal after challenge period
npm run withdrawERC20 -- --token 0x2aCce539A4c6... --tx-hash 0xf66bff1c117c70... --wait

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your enhancements or bug fixes. Ensure your code follows the existing style guidelines and passes linting and formatting checks.

License

This project is open-source and distributed under the MIT License.

Disclaimer

This tool interacts with smart contracts on live networks. Use at your own risk. Make sure you understand the potential implications of sending transactions on mainnet environments.