docs: Arc Relay Bridge — CCTP V2 infrastructure tools reference

[osr21]

Summary

Adds a reference document for the Arc Relay Bridge — a cross-chain USDC relay bridge built on Circle's CCTP V2, deployable to Arc Testnet. The document covers six infrastructure tools, key CCTP V2 ABI findings from on-chain decoding, and Arc Testnet developer gotchas discovered during development.

Bridge repository: https://github.com/osr21/arc-relay-bridge

---

Tools documented

Tool A — USDC Transfer Indexer + REST API

Real-time background worker indexing all native USDC transfer events on Arc Testnet via the native USDC emitter (0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE). Exposes a paginated REST API with filtering by address, type, and tx hash.

Key finding: the native USDC emitter fires two logs per Transfer (native + ERC-20 mirror) — indexing both causes double-counting. Index only isNativeLog = true entries.

Tool B — Transaction Memo Indexer

Indexes Memo events from Arc's on-chain memo contract with UTF-8 decoding of raw payloads.

Tool C — The Graph Subgraph

AssemblyScript subgraph mapping for the same Arc events — decentralised alternative to the centralised indexer.

Tool D — Contract Compatibility Linter

CLI linter running 9 static bytecode checks for Arc Testnet compatibility:

Code	Check
ARC-001	PUSH0 opcode — requires evmVersion: paris
ARC-002	2-immutable constructor (0x60c0 init) silently reverts — use constant
ARC-003	nonReentrant on validatePaymasterUserOp — violates ERC-7562
ARC-004	CCTP V1 4-param depositForBurn selector — use V2 7-param
ARC-005	Missing onlyEntryPoint guard on paymaster functions
ARC-006	Constructor arity mismatch for known paymaster pattern
ARC-007	Stale gas price — requires ≥30% premium on Arc
ARC-008	eth_estimateGas reliance for complex calls
ARC-009	wallet_switchEthereumChain race condition

Tool E — CCTP Bridge Analytics (indexer + dashboard)

Indexes CCTP V2 DepositForBurn and MintAndWithdraw events with attestation status tracking, plus a React 19 + Recharts analytics dashboard showing real-time bridge activity across all CCTP domains.

CCTP V2 ABI facts confirmed from on-chain decoding (Arc-specific):

• DepositForBurn topic: 0x0c8c1cbdc5190613ebd485511d4e2812cfa45eecb79d845893331fedad5130a5
• burnToken is the 1st indexed param on Arc (differs from Circle standard where nonce is 1st indexed)
• Arc's depositForBurn adds uint32 minFinalityThreshold and bytes hookData params
• Full signature: DepositForBurn(address,uint256,address,bytes32,uint32,bytes32,bytes32,uint256,uint32,bytes)
• MintAndWithdraw (not MessageReceived) is the correct event for indexing mints on Arc
• minFinalityThreshold: Arc=2000 (finalized), Sepolia/Base Sepolia/Fuji=0 (fast testnet)

Tool G — APS SDK

TypeScript typed stubs for the Arc Privacy Sector — ready for integration when APS goes live.

---

Arc Testnet developer gotchas

Several non-obvious behaviours discovered during development that may not yet be in the official docs:

Issue	Detail
Primary RPC rate-limits eth_getLogs	rpc.testnet.arc.network returns −32011; use arc-testnet.drpc.org for indexer log fetching
drpc.org free-tier batch limit	Rejects JSON-RPC batches of >3 requests (code 31); set batchMaxCount: 1 on ethers.js provider
drpc.org getLogs range limit	Rejects ranges >10,000 blocks (code 35); keep history window ≤9,000 blocks
Double logs on USDC transfer	Native USDC emitter fires two logs per Transfer — index only native logs
CCTP V2 selector	V1 4-param selector (0x6fd3504e) silently reverts; always use V2 7-param (0x8e0250ee)
Arc USDC decimals	18-decimal native for gas, 6-decimal ERC-20 interface for amounts
Block time ~0.48 s	Use blockNumber not timestamp as ordering key — no reorgs
PUSH0 opcode	Arc Testnet rejects evmVersion >= shanghai; compile with evmVersion: "paris"
2-immutable constructor	0x60c0 init bytecode silently reverts on Arc; keep second variable as constant not immutable
Arc explorer URL	Use https://testnet.arcscan.app — previous URLs (explorer.testnet.arc.network, explorer.arc.io) are dead

---

Files changed

• docs/arc-relay-bridge-tools.md — full reference for all six tools, CCTP V2 ABI details, REST API schemas, contract addresses, and Arc Testnet gotchas