> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokrypt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# evm-arbitrum

> Arbitrum L2 development with bridge messaging, token gateway, and mainnet forking.

## Overview

Arbitrum-focused template for L2 development. Includes L1-to-L2 and L2-to-L1 bridge messaging contracts, a bidirectional token gateway, and a gas-efficient ERC-20 token. Pre-configured to fork Arbitrum mainnet with Blockscout explorer.

|                |                                                |
| -------------- | ---------------------------------------------- |
| **Difficulty** | Intermediate                                   |
| **Category**   | L2                                             |
| **Chains**     | Arbitrum (fork)                                |
| **Services**   | Blockscout (port 4000), Prometheus (port 9090) |
| **License**    | Apache-2.0                                     |

## Quick Start

```bash theme={null}
dokrypt init my-arb --template evm-arbitrum
cd my-arb
dokrypt up
# arbitrum (anvil)   Ready  http://localhost:8545
# blockscout         Ready  http://localhost:4000
# prometheus         Ready  http://localhost:9090
```

## Generated Files

<Tree>
  <Tree.Folder name="my-arb" defaultOpen>
    <Tree.File name="dokrypt.yaml" />

    <Tree.File name="foundry.toml" />

    <Tree.File name="README.md" />

    <Tree.Folder name="contracts" defaultOpen>
      <Tree.Folder name="token" defaultOpen>
        <Tree.File name="ArbitrumToken.sol" />
      </Tree.Folder>

      <Tree.Folder name="bridge" defaultOpen>
        <Tree.File name="L1ToL2MessageSender.sol" />

        <Tree.File name="L2ToL1MessageSender.sol" />
      </Tree.Folder>

      <Tree.Folder name="gateway" defaultOpen>
        <Tree.File name="TokenGateway.sol" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="test" defaultOpen>
      <Tree.File name="ArbitrumToken.t.sol" />

      <Tree.File name="L1ToL2Message.t.sol" />

      <Tree.File name="TokenGateway.t.sol" />
    </Tree.Folder>

    <Tree.Folder name="scripts" defaultOpen>
      <Tree.File name="deploy.js" />

      <Tree.File name="bridge-tokens.js" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

## Contracts

### ArbitrumToken.sol

Gas-efficient ERC-20 optimized for Arbitrum. Includes batch transfers and gateway-authorized minting/burning for bridge operations.

| Function                                 | Access  | Description                                           |
| ---------------------------------------- | ------- | ----------------------------------------------------- |
| Standard ERC-20                          | Public  | `transfer`, `approve`, `transferFrom`                 |
| `batchTransfer(recipients[], amounts[])` | Public  | Send tokens to multiple addresses in one tx           |
| `mint(to, amount)`                       | Gateway | Mint tokens on L2 (called by gateway during bridging) |
| `burn(from, amount)`                     | Gateway | Burn tokens on L2 (called during withdrawal)          |
| `setGateway(gateway)`                    | Owner   | Authorize a gateway contract                          |

***

### Bridge Module

#### L1ToL2MessageSender.sol

Sends messages from L1 to L2 via Arbitrum's Delayed Inbox pattern. Creates retryable tickets with configurable gas parameters.

| Function                                         | Access | Description                     |
| ------------------------------------------------ | ------ | ------------------------------- |
| `sendMessage(target, data, maxGas, gasPriceBid)` | Public | Create a retryable ticket to L2 |
| `getTicket(ticketId)`                            | View   | Get ticket details              |
| `getTicketCount()`                               | View   | Total tickets created           |

#### L2ToL1MessageSender.sol

Sends messages from L2 to L1 via the ArbSys precompile (0x0000000000000000000000000000000000000064). Includes target allowlisting and nonce tracking.

| Function                      | Access | Description                       |
| ----------------------------- | ------ | --------------------------------- |
| `sendMessage(target, data)`   | Public | Send message to allowed L1 target |
| `addAllowedTarget(target)`    | Owner  | Add L1 address to allowlist       |
| `removeAllowedTarget(target)` | Owner  | Remove from allowlist             |
| `confirmMessage(nonce)`       | Owner  | Confirm message delivery          |

***

### TokenGateway.sol

Bidirectional token bridging using lock-and-mint (L1 to L2) and burn-and-release (L2 to L1) pattern.

| Function                                                | Access      | Description                      |
| ------------------------------------------------------- | ----------- | -------------------------------- |
| `deposit(l1Token, amount)`                              | Public      | Lock tokens on L1, mint on L2    |
| `withdraw(l2Token, amount)`                             | Public      | Burn tokens on L2, release on L1 |
| `finalizeDeposit(l1Token, to, amount, depositId)`       | Counterpart | Complete deposit on L2 side      |
| `finalizeWithdrawal(l2Token, to, amount, withdrawalId)` | Counterpart | Complete withdrawal on L1 side   |
| `mapToken(l1Token, l2Token)`                            | Owner       | Register L1/L2 token pair        |

## Deployment

### Deploy All Contracts

```bash theme={null}
npx hardhat run scripts/deploy.js --network localhost
```

Deploys ArbitrumToken, L1ToL2MessageSender, L2ToL1MessageSender, and TokenGateway. Configures gateway linking and token mappings.

### Bridge Token Flow

```bash theme={null}
npx hardhat run scripts/bridge-tokens.js --network localhost
```

Demonstrates a full L1-to-L2 deposit and L2-to-L1 withdrawal cycle.

## Testing Workflows

### Bridge Testing

```bash theme={null}
# Start Arbitrum fork environment
dokrypt up

# Deploy contracts
npx hardhat run scripts/deploy.js --network localhost

# Run bridge tests
dokrypt test run --filter "bridge"
```

### Token Gateway Testing

```bash theme={null}
# Test full deposit/withdrawal cycle
dokrypt test run --filter "gateway"

# Test with gas report
dokrypt test --gas-report
```

### Fork Testing

```bash theme={null}
# Fork Arbitrum at a specific block
dokrypt fork arbitrum --block 200000000

# Interact with existing Arbitrum contracts
dokrypt exec arbitrum "cast call 0x..."
```