docs: CCTP V2 integration on Arc Testnet — domain 26, minFinalityThreshold 2000, V1 selector incompatible

[osr21]

Summary

After building a full CCTP V2 bridge (Arc Testnet ↔ Ethereum Sepolia ↔ Base Sepolia ↔ Avalanche Fuji), three Arc-specific integration details were not documented anywhere and caused significant debugging time. Sharing them here so the docs or a dedicated integration guide can cover them.

---

1. Arc Testnet CCTP domain is 26

The CCTP V2 depositForBurn call requires a destinationDomain parameter. Arc Testnet's domain is 26. This is not listed in the Circle CCTP docs or the arc-node README. The only way to confirm it is empirically by inspecting a successful MessageSent event.

// Sending from Ethereum Sepolia → Arc Testnet
const destinationDomain = 26; // Arc Testnet — not in Circle's public docs

---

2. Arc Testnet requires minFinalityThreshold: 2000 (finalized), not 1000 (safe)

CCTP V2's depositForBurn accepts a minFinalityThreshold parameter that controls when the attestation is issued. All other testnets work with 1000 (safe finality, ~1–2 min). Arc Testnet requires 2000 (finalized) — using 1000 results in an attestation that never progresses past pending in the Circle Iris API.

// Arc Testnet source burns:
const minFinalityThreshold = 2000; // finalized — required for Arc

// All other chains (Sepolia, Base Sepolia, Fuji):
const minFinalityThreshold = 1000; // safe — works fine

---

3. All CCTP contracts on Arc use V2 — the V1 4-parameter selector will silently fail

The CCTP V2 depositForBurn function signature is:

function depositForBurn(
    uint256 amount,
    uint32 destinationDomain,
    bytes32 mintRecipient,
    address burnToken,
    bytes32 destinationCaller, // V2 addition
    uint256 maxFee,            // V2 addition
    uint32 minFinalityThreshold // V2 addition
) external returns (uint64 nonce);

The V1 version has only 4 parameters. If a DApp or library calls the V1 selector (0x6fd3504e) against Arc's TokenMessenger (0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA), the transaction will be accepted by the node but revert on-chain with no useful error data. This is a common mistake when copying integration examples from older Circle docs.

The correct V2 selector is 0x8e0250ee.

---

Suggested documentation additions

• Add Arc Testnet to the CCTP supported domains list (domain 26)
• Document minFinalityThreshold: 2000 as Arc-specific in the CCTP integration guide
• Add a warning that all Arc CCTP contracts are V2-only and the V1 ABI will silently fail
• Include Arc Testnet in the Circle Iris attestation API endpoint documentation

Context

Discovered while building arc-relay-bridge — a fully working CCTP V2 bridge across Arc Testnet, Ethereum Sepolia, Base Sepolia, and Avalanche Fuji.

[zkasuran]

Opened #127 with a docs/cctp-v2-integration.md guide covering these. I verified domain 26 and the contract addresses against Circle's CCTP references, computed both depositForBurn selectors (V2 0x8e0250ee, V1 0x6fd3504e), and confirmed the TokenMessenger has code on Arc Testnet via eth_getCode. The minFinalityThreshold 2000 guidance is documented as Arc behavior per your report.

[osr21]

Thanks for opening #127 — this will save a lot of debugging time.

Two additional Arc-specific gotchas from a working implementation that are worth adding if not already in the guide:

1. Gas limit override required on Arc Testnet

eth_estimateGas underestimates for both depositForBurn (on Arc as source) and receiveMessage (on Arc as destination). Without an explicit override both calls silently revert. A limit of 600_000 covers both:

// Arc Testnet: pass explicit gasLimit for burn and mint txs
const overrides = chainId === ARC_CHAIN_ID ? { gasLimit: 600_000n } : {};
await tokenMessenger.depositForBurn(...args, overrides);
await messageTransmitter.receiveMessage(message, attestation, overrides);

2. Arc Testnet USDC address is a system address

The USDC address on Arc Testnet is 0x3600000000000000000000000000000000000000. This is a special system address — some address validation libraries flag it as a zero-padded or precompile-style address. The ERC-20 interface behaves normally (6 decimals, standard approve/transferFrom), but it's worth calling out explicitly so integrators don't dismiss it as a misconfiguration.

[osr21]

Additional: gas padding for receiveMessage + explicit gas on depositForBurn

Great reference — these three Arc-specific values (#domain 26, #minFinalityThreshold 2000, #V2 selector) took us significant debugging time too.

One more Arc-specific integration detail to add for completeness:

4. receiveMessage() on destination chains needs maxFeePerGas padding

After the attestation is ready, calling MessageTransmitterV2.receiveMessage() on destination chains (Ethereum Sepolia, Base Sepolia, Arbitrum Sepolia) frequently fails with:

max fee per gas less than block base fee

This is the same timing issue described in #153 — viem estimates maxFeePerGas at T₀, but the base fee ticks up before the tx lands at T₁. The fix: pad by +30% on all three destination chains:

const feeData = await destinationClient.estimateFeesPerGas();

await walletClient.writeContract({
  address: MESSAGE_TRANSMITTER_V2,
  abi: MessageTransmitterV2ABI,
  functionName: "receiveMessage",
  args: [messageBytes, attestation],
  maxFeePerGas: (feeData.maxFeePerGas * 130n) / 100n,  // +30%
  maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
  gas: 500_000n, // explicit — estimateGas unreliable
});

5. depositForBurn on Arc Testnet also needs explicit gas

eth_estimateGas on the Arc Testnet origin side is unreliable too (see the gas estimation quirk documented broadly in the issues). We use 300_000n for depositForBurnWithHook:

await walletClient.writeContract({
  address: TOKEN_MESSENGER_V2,
  abi: TokenMessengerV2ABI,
  functionName: "depositForBurnWithHook",
  args: [amount, 0, mintRecipient, USDC_ADDRESS, destinationCaller, 0n, minFinalityThreshold, hookData],
  gas: 300_000n, // always explicit on Arc Testnet
});