⛓️use-arc

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_TESTNET_RPC_URL=https://rpc.testnet.arc.network
PRIVATE_KEY=         # Deployer wallet private key

Quick Reference

Network Details

Token Addresses for Arc

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.
• Testnet only: Arc is currently in testnet. All addresses and configuration apply to testnet only.
• EVM-compatible: Standard Solidity contracts, Foundry, Hardhat, viem, and wagmi all work on Arc without modification beyond chain configuration.

Implementation Patterns

1. Frontend App (React + wagmi)

Use the arcTestnet chain definition from Prerequisites / Setup. Pass it to your wagmi config:

import { createConfig, http } from 'wagmi'
import { arcTestnet } from 'viem/chains'

const config = createConfig({
  chains: [arcTestnet],
  transports: { [arcTestnet.id]: http() },
})

2. Smart Contracts (Foundry)

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash && foundryup

# Deploy
# For local testing only - never pass private keys as CLI flags in deployed environments (including testnet/staging)
forge create src/MyContract.sol:MyContract \
  --rpc-url $ARC_TESTNET_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast

3. Circle Contracts (Pre-audited Templates)

Deploy via Circle's Smart Contract Platform API:

See: https://developers.circle.com/contracts

4. Bridge USDC to Arc

Use CCTP to bridge USDC from other chains. Arc's CCTP domain is 26. See the bridge-stablecoin skill for the complete bridging 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 Testnet is available by default in Viem -- a custom chain definition is NEVER required.
• ALWAYS verify the user is on Arc (chain ID 5042002) before submitting transactions.
• ALWAYS fund the wallet from https://faucet.circle.com before sending transactions.
• ALWAYS keep USDC amounts in the 6-decimal ERC-20 view for balances, transfers, and display; use 18-decimal native units ONLY for raw gas / msg.value math. Never sum the two views or treat native and USDC as separate assets.
• NEVER target mainnet -- Arc is testnet only.

Next Steps

Arc is natively supported across Circle's product suite. Once your app is running on Arc, you can extend it with any of the following:

Reference Links

• Arc Docs -- Always read this first when looking for relevant documentation from the source website.
• Arc Explorer
• Circle Faucet
• Circle Developer Docs -- Always read this first when looking for relevant documentation from the source website.

DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.