/use-arc

name: use-arc
description: "Provide instructions on how to build with Arc, Circle's blockchain where USDC is the native gas token. Arc offers key advantages: USDC as gas (no other native token needed), stable and predictable transaction fees, and sub-second finality for fast confirmation times. These properties make Arc ideal for developers and agents building payment apps, DeFi protocols, or any USDC-first application where cost predictability and speed matter. Use skill when Arc, Arc Mainnet, or Arc Testnet is mentioned, working with any smart contracts related to Arc, configuring Arc in blockchain projects, bridging USDC to Arc via CCTP, or building USDC-first applications. Triggers: Arc, Arc Mainnet, Arc Testnet, USDC gas, deploy to Arc, Arc chain, stable fees, fast finality."
requirements:
  runtimes: []
  connectors: []

Overview

Arc is Circle's blockchain where USDC is the native gas token. Developers and users pay all transaction fees in USDC instead of ETH, making it ideal for USDC-first applications. Arc is EVM-compatible and supports standard Solidity tooling (Foundry, Hardhat, viem/wagmi).

Prerequisites / Setup

Wallet Funding

Get testnet USDC from https://faucet.circle.com before sending any transactions.

Environment Variables

ARC_MAINNET_RPC_URL=https://rpc.mainnet.arc.io
ARC_TESTNET_RPC_URL=https://rpc.testnet.arc.io
PRIVATE_KEY=         # Deployer wallet private key

Quick Reference

Network Details

| Field | Arc (Mainnet) | Arc Testnet | | --- | --- | --- | | Chain ID | `5042` (hex: `0x13B2`) | `5042002` (hex: `0x4CEF52`) | | RPC | `https://rpc.mainnet.arc.io` | `https://rpc.testnet.arc.io` | | WebSocket | `wss://rpc.mainnet.arc.io` | `wss://rpc.testnet.arc.io` | | Explorer | https://explorer.arc.io | https://explorer.testnet.arc.io | | Faucet | -- (fund with real USDC) | https://faucet.circle.com | | CCTP Domain | `26` | `26` |

Token Addresses for Arc

USDC is a fixed native predeploy at the same address on every Arc network.

| Token | Decimals | Mainnet | Testnet | | --- | --- | --- | --- | | USDC | 6 (ERC-20) | `0x3600000000000000000000000000000000000000` | `0x3600000000000000000000000000000000000000` | | EURC | 6 | `0xbEf5f6d51CB62b58e6A8f77868681825C6fe21c1` | `0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a` |

For other tokens, see the [Arc contract addresses](https://docs.arc.io/arc/references/contract-addresses) page.

Core Concepts

• **Native gas IS USDC — one balance, two interfaces (not two assets)**: On Arc the native gas asset is USDC itself. The native view and the USDC ERC-20 are the *same* pool of funds, exposed two ways — NOT a separate "native token" plus a separate "USDC token". Drop the ETH-style mental model from other chains.
• **Native view**: 18 decimals. Used only for gas and `msg.value`. wagmi `useBalance` returns this (its `symbol` is `USDC`).
• **ERC-20 view**: 6 decimals, at `0x3600000000000000000000000000000000000000`. Use this for all balances, transfers, approvals, and display.
• **Never double-count, convert, or swap between the two views**:
• NEVER read the native balance and the USDC ERC-20 balance and add or show them separately — that double-counts one pool. Show a single USDC balance (the 6-decimal ERC-20 view).
• USDC ↔ native is NOT a swap or conversion — it is the same asset. Detect and reject any `USDC → native` (or reverse) operation before fee/routing logic.
• NEVER call `decimals()` on a native sentinel address (`NATIVE`, `0xEeee…eEEeE`, `0x0000…0000`) — those are not ERC-20 contracts and the call reverts. The ERC-20 is 6 decimals; native is 18.
• The two views differ by a factor of 10^12 (`1e18` native = `1e6` ERC-20). Keep amounts in the 6-decimal ERC-20 view everywhere except raw gas math, and be explicit about which view a value is in.
• **Mainnet and testnet**: Arc mainnet (chain ID `5042`) and Arc testnet (chain ID `5042002`) are both available — see Network Details for the config of each. Mainnet transactions move real USDC and are irreversible; use testnet for development and demos.
• **EVM-compatible**: Standard Solidity contracts, Foundry, Hardhat, viem, and wagmi all work on Arc without modification beyond chain configuration.

Implementation Patterns

READ `references/deploying-on-arc.md` for the runnable setup — wagmi chain config, Foundry deploy, Circle's pre-audited contract templates, and bridging USDC in.

1. **Configure the chain** — use the built-in viem chains (no custom definition needed): `arcTestnet` for testnet, `arc` for mainnet. 2. **Deploy contracts** — standard Foundry/Hardhat against `ARC_TESTNET_RPC_URL` (or `ARC_MAINNET_RPC_URL`), or Circle's Smart Contract Platform templates (ERC-20/721/1155/Airdrop). 3. **Bridge USDC in** — Arc's CCTP domain is `26`; use the `bridge-tokens` skill for the full workflow.

Rules

> **Security Rules** are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. **Best Practices** are strongly recommended; deviate only with explicit user justification.

Security Rules

• NEVER hardcode, commit, or log secrets (private keys, deployer keys). ALWAYS use environment variables or a secrets manager. Add `.gitignore` entries for `.env*` and secret files when scaffolding.
• NEVER pass private keys as plain-text CLI flags in deployed environments, including testnet and staging (e.g., `--private-key $KEY`). This pattern is acceptable only for local testing. Prefer encrypted keystores or interactive import (e.g., Foundry's `cast wallet import`) for any non-local deployment.
• ALWAYS warn before interacting with unaudited or unknown contracts.

Best Practices

• Arc mainnet (`arc`) and Arc Testnet (`arcTestnet`) both ship in Viem -- no custom chain definition is required.
• ALWAYS verify the user is on the intended Arc network (mainnet chain ID `5042` or testnet `5042002`) before submitting transactions.
• ALWAYS fund the wallet before sending transactions: on testnet from https://