Bridge USDC

import { quoteBridge, bridgeFromWallet } from '@ctrl-arcz/sdk';
import { parseUnits } from 'viem';

const amount = parseUnits('5', 6);

// Price it first if you want to show the fee before anything is signed.
const quote = await quoteBridge({ from: 'Base_Sepolia', to: 'Arc_Testnet', amount });
// { amount, maxFee, total } - total is what leaves the wallet

const result = await bridgeFromWallet(
  { publicClient, walletClient },
  {
    from: 'Base_Sepolia',
    to: 'Arc_Testnet',
    amount,
    onQuote: (q) => showFee(q.maxFee),
    onStep: (step, txHash) => showProgress(step, txHash),
  },
);
// { approveTxHash?, burnTxHash, forwardTxHash?, quote }

import { findForwardedMint, waitForForwardedMint, CCTP_CHAINS } from '@ctrl-arcz/sdk';

// One shot: has Circle minted yet?
const mint = await findForwardedMint({
  sourceDomain: CCTP_CHAINS.Base_Sepolia.domain,
  burnTxHash,
});

// Or keep watching, up to timeoutMs (default 180000).
const mint2 = await waitForForwardedMint({ sourceDomain, burnTxHash, timeoutMs: 60_000 });

import {
  depositToGateway,
  gatewayBalance,
  quoteGatewaySpend,
  spendFromGateway,
} from '@ctrl-arcz/sdk';

// 1. Deposit, once, on whichever chain the USDC is on today.
await depositToGateway({ publicClient, walletClient }, {
  chain: 'Base_Sepolia',
  amount: parseUnits('20', 6),
  onStep: (step, txHash) => showProgress(step, txHash),
});

// 2. Read what is actually spendable.
const balance = await gatewayBalance({ depositor: address });
// { total, byChain: { Base_Sepolia: 20000000n, ... } }

// 3. Spend it anywhere. A signature, no source-chain transaction, no gas.
const spend = await spendFromGateway({ walletClient }, {
  from: 'Base_Sepolia',
  to: 'Arc_Testnet',
  amount: parseUnits('5', 6),
  onTransferId: (id) => persist(id),
});
// { transferId, mintTxHash?, quote }

import { allocate, maxDeliverable, spendFromGateway, gatewayBalance } from '@ctrl-arcz/sdk';

const { byChain } = await gatewayBalance({ depositor: address });
const balances = Object.entries(byChain).map(([chain, balance]) => ({ chain, balance }));

// Which chains to draw from, and how much from each. Pure, no network calls.
const plan = allocate({ amount: parseUnits('12', 6), balances, forwarding: quote.forwardingFee });
if (plan.shortfall > 0n) return tellTheUser(plan.shortfall);

await spendFromGateway({ walletClient }, {
  sources: plan.legs,        // [{ chain, value }, ...]
  to: 'Arc_Testnet',
  onTransferId: (id) => persist(id),
});

import {
  CCTP_CHAINS,
  GATEWAY_CHAIN_NAMES,
  cctpChainByChainId,
  chainExplorerTxUrl,
  chainLabel,
} from '@ctrl-arcz/sdk';

CCTP_CHAINS.Arc_Testnet;              // { domain: 26, chainId: 5042002, usdc, gasToken: 'usdc' }
cctpChainByChainId(await walletClient.getChainId()); // which chain the wallet is on
chainLabel('Base_Sepolia');           // 'Base Sepolia'
chainExplorerTxUrl('Base_Sepolia', burnTxHash); // undefined where no explorer is known

import {
  gatewayShortfall,
  cctpShortfall,
  maxGatewaySpendable,
  maxDepositable,
  usdc,
} from '@ctrl-arcz/sdk';

const refusal = gatewayShortfall({
  here: balance.byChain[from] ?? 0n,  // the balance ON THE SOURCE CHAIN
  byChain: balance.byChain,
  from,
  fromLabel: chainLabel(from),
  committed: amount + quote.maxFee,
  labelOf: chainLabel,
});

if (refusal) {
  // refusal.code is a string key, so the SDK holds no English.
  // refusal.fix is the action: switchSource | deposit | useMax
  render(t(refusal.code, refusal.params), refusal.fix);
  return;
}

const res = await fetch('https://api.ctrlarcz.xyz/api/gasless-claim', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ transferId: '42', code: 'A4K79QMX2PR6TH8D', salt: '0x...' }),
});
const result = await res.json();
// { ok: true, txHash } | { ok: false, error: { kind, attemptsRemaining?, reason?, message? } }