npm package: @frequencyadvisors/freeq-bridge-sdk
Description: SDK and CLI tools for L2 Bridging
Author: Edoardo Ierina
Latest version: 1.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](https://nodejs.org/) (v20+)
- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/)
- 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:**

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

2. **Install dependencies:**

   ```bash
   npm install
   ```

3. **Configure environment variables:**

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

   ```bash
   cp .env.template.bera-altlayer .env
   ```

   Update the following variables in your `.env` file:

   ```env
   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)

```bash
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:**

```bash
# 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

```bash
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:**

```bash
# 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)

```bash
npm run deposit -- --amount <amount>
```

**Option:**

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

**Example:**

```bash
# 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)

```bash
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:**

```bash
# 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

```bash
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:**

```bash
# 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

```bash
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:**

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

---

### Deposit ERC20 (L1 -> L2)

```bash
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:**

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

---

### Withdraw ERC20 (L2 -> L1)

```bash
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:**

```bash
# 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](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.