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

> ## Agent Instructions
> Before reading these docs, install the Circle Skill for Arc to get pre-loaded context: use-arc (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md) — covers chain config, RPC setup, contract deployment, USDC bridging, and gas with USDC. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills.
> USDC is the gas token. Arc uses USDC for gas fees, not ETH. Configure gas payment in USDC when submitting transactions.
> Read EVM differences before writing Arc code. Arc targets the Osaka EVM baseline. Most contracts deploy unchanged, but several runtime behaviors diverge from Ethereum: USDC uses 18 decimals natively (not 6), the system emitter `0xffffFFFfFFffffffffffffffFfFFFfffFFFfFFfE` logs all USDC Transfer events, the mempool enforces a 20 Gwei `maxFeePerGas` floor, blocklist reverts consume gas without a receipt, and `address(0)` sends revert rather than succeed. https://docs.arc.io/arc/references/evm-differences.md is the canonical reference for all Arc-specific runtime behaviors. Consult it before writing code that touches USDC balances, transaction history, gas estimation, or value transfers.
> Sub-second finality. Transactions are final in under 1 second. No need to wait for multiple block confirmations.
> Use App Kits for multichain payment and liquidity capabilities. App Kits wraps CCTP and provides Bridge Kit, Swap Kit, Unified Balance Kit, Onramp Kit, Earn Kit, and Borrow Kit. Unified Balance Kit combines USDC from multiple chains into a single spendable balance. Earn Kit integrates earn opportunities into your app. Borrow Kit lets users borrow USDC against cirBTC collateral on Arc.
> Use Arc Foundry for contract development. Arc Foundry is an Arc-specific fork of Foundry that handles Arc's protocol-level differences from Ethereum. It provides arc-forge, arc-cast, and arc-anvil. Install it before deploying contracts: https://docs.arc.io/arc/tutorials/install-arc-foundry.md.
> Arc is available on both Testnet and Mainnet. See https://docs.arc.io/arc/references/connect-to-arc.md for RPC endpoints and https://faucet.circle.com for testnet tokens.
> Always check Contract Addresses: https://docs.arc.io/arc/references/contract-addresses.md
> Building beyond Arc? Circle offers skills for the full platform: use-usdc (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md), use-circle-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md), use-developer-controlled-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md), use-user-controlled-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md), use-modular-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md), use-gateway (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md), use-smart-contract-platform (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md). Full Circle developer docs: https://developers.circle.com/llms.txt.

# How-to: Add Arc to your bridge protocol

> Register Arc as a supported chain in your bridge or interoperability protocol, configure confirmation requirements, and deploy relay contracts.

Register Arc as a supported chain in your bridge or interoperability protocol.
Arc's deterministic finality, USDC-native gas model, and CCTP integration
require specific configuration choices that differ from probabilistic-finality
chains.

## Prerequisites

Before you begin, ensure that you've:

* Familiarized yourself with deploying contracts on EVM chains using Foundry or
  Hardhat
* Obtained an Arc RPC endpoint (`https://rpc.testnet.arc.io`)
* Funded a wallet on Arc with USDC for contract deployment (USDC is the gas
  token)
* Reviewed your protocol's chain registration and relay architecture

## Chain metadata

Register Arc with the following parameters:

| Property | Value |
| :- | :- |
| **Chain ID** | `5042002` (testnet) |
| **RPC (HTTPS)** | `https://rpc.testnet.arc.io` |
| **RPC (WebSocket)** | `wss://rpc.testnet.arc.io` |
| **Block explorer** | `https://explorer.testnet.arc.io` |
| **Native gas token** | USDC |
| **Native token decimals** | 18 (native), 6 (ERC-20 interface) |
| **EVM target** | Osaka hard fork |
| **Block time** | Sub-second |
| **Finality** | Deterministic (BFT consensus) |
| **CCTP domain** | `26` |

## Steps

### Step 1. Configure finality and confirmation requirements

Arc uses deterministic BFT finality. Once a block is committed, it is
irreversible. There are no reorgs.

Set your required confirmations to **1**. A single confirmation on Arc provides
the same settlement guarantee as 64+ confirmations on Ethereum or 20+ on other
L2s.

| Chain type | Typical confirmations | Arc confirmations |
| :- | :- | :- |
| Ethereum (PoS) | 64 blocks (\~13 min) | 1 block (\<1 s) |
| Optimistic rollups | 7 days (challenge period) | 1 block (\<1 s) |
| Other L2s | 10–20 blocks | 1 block (\<1 s) |

<Tip>
  If your protocol uses `safe` or `finalized` block tags in RPC calls, both
  resolve to the latest block on Arc. You do not need separate handling for
  pending vs. finalized states.
</Tip>

For your bridge configuration:

```typescript theme={null}
import { defineChain } from "viem";

export const arcTestnet = defineChain({
  id: 5042002,
  name: "Arc Testnet",
  nativeCurrency: {
    name: "USDC",
    symbol: "USDC",
    decimals: 18,
  },
  rpcUrls: {
    default: {
      http: ["https://rpc.testnet.arc.io"],
      webSocket: ["wss://rpc.testnet.arc.io"],
    },
  },
  blockExplorers: {
    default: {
      name: "Block Explorer",
      url: "https://explorer.testnet.arc.io",
    },
  },
});

// Bridge confirmation config
const arcBridgeConfig = {
  chainId: 5042002,
  requiredConfirmations: 1, // Deterministic finality—1 is sufficient
  finalityType: "deterministic" as const,
  avgBlockTimeMs: 500,
};
```

### Step 2. Route USDC and EURC with CCTP

Arc uses Circle's Cross-Chain Transfer Protocol (CCTP) as the canonical bridge
for USDC and EURC. CCTP uses a burn-and-mint model, meaning USDC and EURC on Arc
are always native and never wrapped or locked.

<Warning>
  Do not deploy wrapped USDC or EURC on Arc. Route all USDC and EURC transfers
  through CCTP to maintain fungibility with the native tokens. Wrapped variants
  create fragmented liquidity and user confusion.
</Warning>

| Contract | Address | Notes |
| :- | :- | :- |
| **TokenMessengerV2** | [`0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA`](https://explorer.testnet.arc.io/address/0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA) | Initiates crosschain burns |
| **MessageTransmitterV2** | [`0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275`](https://explorer.testnet.arc.io/address/0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275) | Receives and attests messages |
| **USDC** | [`0x3600000000000000000000000000000000000000`](https://explorer.testnet.arc.io/address/0x3600000000000000000000000000000000000000) | Native USDC (ERC-20 interface) |
| **EURC** | [`0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a`](https://explorer.testnet.arc.io/address/0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a) | Native EURC (ERC-20 interface) |
| **CCTP domain** | `26` | Use in `depositForBurn` calls |

If your bridge aggregates routes, prefer the CCTP path for USDC and EURC
transfers to and from Arc over any lock-and-mint or liquidity-pool approach.

### Step 3. Deploy relay and adapter contracts

Arc is EVM-compatible (Osaka hard fork target). Standard deployment tooling
works without modification:

```typescript theme={null}
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

// Deploy using standard viem workflow
const account = privateKeyToAccount(
  process.env.DEPLOYER_PRIVATE_KEY as `0x${string}`,
);

const walletClient = createWalletClient({
  account,
  chain: arcTestnet,
  transport: http("https://rpc.testnet.arc.io"),
});

// CREATE2 deterministic deployment works as expected
// Permit2 is available at the canonical address
const PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
```

**Key deployment considerations:**

* CREATE2 factory works at the standard address for deterministic deploys
* Permit2 is deployed at `0x000000000022D473030F116dDEE9F6B43aC78BA3`
* Multicall3 is available at the standard address
* No EIP-4844 blob transactions—use `type: 2` (EIP-1559) transactions
* `PREVRANDAO` always returns `0`—do not use it for randomness in relay
  selection

<Note>
  If your contracts reference `block.prevrandao` for relay shuffling or random
  selection, replace it with an external oracle or deterministic round-robin
  approach on Arc.
</Note>

### Step 4. Fund relayers with USDC for gas

Arc uses USDC as its gas token, not ETH. Your relay executors and watchers need
USDC balances to submit transactions.

```typescript theme={null}
import { parseUnits, formatUnits } from "viem";

// Check relayer gas balance (USDC with 18 decimals at native level)
const balance = await publicClient.getBalance({
  address: relayerAddress,
});

console.log(`Relayer balance: ${formatUnits(balance, 18)} USDC`);

// Fund relayer via ERC-20 transfer (6 decimals)
const USDC_ADDRESS = "0x3600000000000000000000000000000000000000";

const fundTx = await walletClient.writeContract({
  address: USDC_ADDRESS,
  abi: [
    {
      name: "transfer",
      type: "function",
      inputs: [
        { name: "to", type: "address" },
        { name: "amount", type: "uint256" },
      ],
      outputs: [{ type: "bool" }],
      stateMutability: "nonpayable",
    },
  ],
  functionName: "transfer",
  args: [relayerAddress, parseUnits("1000", 6)], // 1,000 USDC
});
```

<Warning>
  Do not send ETH to relayers on Arc. ETH has no function on the network.
  Relayers need only USDC to pay for gas.
</Warning>

**Gas cost estimation:**

Arc's fee model uses a smoothed moving average inspired by EIP-1559. Gas prices
are stable and predictable. A typical relay transaction costs well under \$0.01
in USDC gas fees.

### Step 5. Connect your relay infrastructure

For high-throughput relay operations, connect to Arc using WebSocket for
real-time block and event streaming:

```typescript theme={null}
import { createPublicClient, webSocket, http } from "viem";

// WebSocket for real-time event monitoring (relay watchers)
const wsClient = createPublicClient({
  chain: arcTestnet,
  transport: webSocket("wss://rpc.testnet.arc.io"),
});

// HTTP for transaction submission (relay executors)
const httpClient = createPublicClient({
  chain: arcTestnet,
  transport: http("https://rpc.testnet.arc.io"),
});

// Watch for bridge events with immediate finality
const unwatch = wsClient.watchContractEvent({
  address: YOUR_BRIDGE_CONTRACT,
  abi: bridgeAbi,
  eventName: "MessageSent",
  onLogs: (logs) => {
    // Each log is final on receipt—no need to wait for confirmations
    for (const log of logs) {
      processRelayMessage(log);
    }
  },
});
```

**Node provider options** for relay infrastructure:

| Provider | Notes |
| :- | :- |
| Alchemy | Managed RPC, WebSocket support |
| Blockdaemon | Enterprise-grade node infrastructure |
| dRPC | Decentralized RPC network |
| QuickNode | Managed endpoints with analytics |
| Self-hosted | Run your own Arc node for lowest latency |

<Tip>
  For latency-sensitive relay operations, run a dedicated Arc node. Arc's node
  software is lightweight and designed for high-throughput block production.
</Tip>

### Step 6. Integrate price feeds (optional)

If your bridge logic requires price oracles for fee estimation or value
validation, the following oracle providers are available on Arc:

| Provider | Use case |
| :- | :- |
| Chainlink | Price feeds, CCIP |
| Pyth | High-frequency price data |
| Redstone | Pull-based oracle model |
| Stork | Low-latency price feeds |

## Integration checklist

Use this checklist to verify your Arc integration is complete:

* [ ] Chain ID `5042002` registered in your chain registry
* [ ] Required confirmations set to `1`
* [ ] USDC routed via CCTP (domain `26`)—no wrapped variants
* [ ] Relay/adapter contracts deployed on Arc
* [ ] Relayer wallets funded with USDC (not ETH)
* [ ] WebSocket connection established for event monitoring
* [ ] Gas estimation logic accounts for USDC denomination
* [ ] No reliance on `PREVRANDAO` for randomness
* [ ] No EIP-4844 blob transaction usage
* [ ] Explorer links use `https://explorer.testnet.arc.io`

## Key differences from other EVM chains

| Consideration | Typical EVM chain | Arc |
| :- | :- | :- |
| **Confirmation safety** | Wait 12–64 blocks | 1 block is final |
| **Gas token** | ETH or chain-native token | USDC |
| **Reorg handling** | Required | Not needed |
| **USDC bridging** | Lock-and-mint or liquidity pools | CCTP burn-and-mint (native) |
| **Block time** | 2–12 seconds | Sub-second |
| **Fee volatility** | High (auction-based) | Low (smoothed moving average) |