SDK API reference

interface ClientPair {
  publicClient: PublicClient;
  walletClient: WalletClient;
  /** Overrides the deployed CtrlArcZ address (tests, alternative deployments). */
  contractAddress?: Address;
}

import { deploymentFor, deployedChainIds, tokensFor, spendableTokensFor } from '@ctrl-arcz/sdk';

const deployment = deploymentFor(chainId);
// undefined on a chain this build knows nothing about, which is the honest answer
// and the thing to branch on before offering a feature.

deployment?.ctrlArcZ;     // the contract on that chain
deployment?.usdc;         // that chain's USDC, which is not Arc's
deployment?.rpcUrls;      // public endpoints for reads
deployment?.explorerApi;  // undefined where the chain publishes no readable history

deployedChainIds();       // every chain this build can work on
tokensFor(chainId);       // that chain's tokens: address, decimals, search names
spendableTokensFor(chainId); // the same list without the ones an allowlist refuses

import { arcTestnet as viemArcTestnet } from 'viem/chains';

const arcTestnet = viemArcTestnet;              // viem built-in (needs viem >= 2.38)
const ARC_TESTNET_CHAIN_ID = 5042002;

const RPC_URL = 'https://rpc.testnet.arc.network';
const WS_URL = 'wss://rpc.testnet.arc.network';
const EXPLORER_URL = 'https://testnet.arcscan.app';
const EXPLORER_API_URL = 'https://testnet.arcscan.app/api/v2';
const FAUCET_URL = 'https://faucet.circle.com';

function explorerTxUrl(hash: string): string;       // `${EXPLORER_URL}/tx/${hash}`
function explorerAddressUrl(address: string): string; // `${EXPLORER_URL}/address/${address}`

function getLogsChunked<TArgs = Record<string, unknown>>(
  client: PublicClient,
  params: ChunkedEventsParams,
): Promise<Array<DecodedLog<TArgs>>>;

interface ChunkedEventsParams {
  address: Address;
  abi: Abi;
  eventName: string;
  args?: Record<string, unknown>;
  fromBlock?: bigint; // defaults to CTRL_ARCZ_DEPLOY_BLOCK
}

function check(
  sender: Address,
  target: Address,
  options?: CheckOptions,
): Promise<RiskReport>;

interface CheckOptions {
  /** Defaults to ArcScan/Blockscout. */
  provider?: IDataProvider;
  /** Used to read `isVerifiedRecipient` from the contract. Optional. */
  client?: PublicClient;
  /** Overrides the deployed CtrlArcZ address. */
  contractAddress?: Address;
  /** Injected in tests to make the freshness rule deterministic. */
  now?: Date;
}

import { check } from '@ctrl-arcz/sdk';

const report = await check(sender, target, { client: publicClient });
if (report.level === 'block') refuseTheSend(report.reasons);

type RiskLevel = 'safe' | 'warning' | 'block';

type RiskRuleCode =
  | 'LOOKALIKE_ADDRESS'   // mimics an address you have paid
  | 'ZERO_VALUE_BAIT'     // target sent you a 0-value transfer
  | 'NEW_ADDRESS'         // no on-chain history
  | 'FRESH_ADDRESS'       // first activity < 24h ago
  | 'VERIFIED_RECIPIENT'  // a protected transfer here already settled
  | 'KNOWN_COUNTERPARTY'  // you have paid this exact address
  | 'DATA_UNAVAILABLE';   // a data source did not answer

interface RiskReason {
  code: RiskRuleCode;
  severity: RiskLevel;
  message: string;           // human-readable English fallback
  lookalikeOf?: Address;     // the counterparty a lookalike was matched against
  count?: number;            // number of 0-value baits (ZERO_VALUE_BAIT)
  sources?: string[];        // data sources that did not answer (DATA_UNAVAILABLE)
}

interface RiskReport {
  target: Address;
  sender: Address;
  level: RiskLevel;          // the worst severity across all reasons
  reasons: RiskReason[];
  complete: boolean;         // true only when every data source answered
  checkedAt: Date;           // a report is a snapshot in time
}

function evaluateRisk(input: RiskInput, now?: Date): RiskReport;
function isLookalike(candidate: Address, known: Address): boolean;
function craftLookalike(target: Address, randomBytes?: (length: number) => Uint8Array): Address;

const AFFIX_LENGTH = 4;                    // chars compared at each end of an address
const FRESH_ADDRESS_MAX_AGE_MS = 86400000; // 24h "fresh address" window

class BlockscoutDataProvider implements IDataProvider {
  constructor(options?: BlockscoutProviderOptions);
  getOutgoingCounterparties(sender: Address): Promise<CounterpartyScan>;
  getAddressActivity(address: Address): Promise<AddressActivity>;
  countZeroValueTransfers(from: Address, to: Address): Promise<number>;
}

interface CounterpartyScan {
  counterparties: Address[];
  /** False when the scan hit its page cap before exhausting history. */
  complete: boolean;
}

interface BlockscoutProviderOptions {
  apiUrl?: string;    // defaults to Arc Testnet's ArcScan
  timeoutMs?: number; // abort a slow explorer; default 15000 ms
  fetchFn?: typeof fetch;
}

class CachingDataProvider implements IDataProvider {
  constructor(inner: IDataProvider, options?: CachingProviderOptions);
}

interface CachingProviderOptions {
  ttlMs?: number;       // how long a successful, complete scan stays fresh. Default 60000
  now?: () => number;   // injectable clock, for tests
}

class VerifiedRecipientIndex {
  // Everyone a sender has completed a protected transfer to, read from events.
}

function acknowledgementCovers(
  acknowledgement: RiskAcknowledgement,
  actual: RiskReport,
  now?: number,
): boolean;

const MAX_ACKNOWLEDGEMENT_AGE_MS = 900000; // 15 minutes

interface RiskAcknowledgement {
  report: RiskReport;  // exactly what was on screen when they decided
  at: number;          // epoch ms of the decision itself
}

function buildDossier(report: RiskReport, opts: BuildDossierOptions): Promise<Dossier>;
function findNearMisses(target: Address, counterparties: Address[]): Array<{
  counterparty: Address;
  sharedPrefix: number;
  sharedSuffix: number;
}>;
function clampVerdict(ruleLevel: RiskLevel, advisory: Advisory): Advisory;

interface BuildDossierOptions {
  publicClient: PublicClient;
  provider: IDataProvider;
  usdcAddress: Address;
  counterparties?: Address[];  // if the caller already has them
  now?: Date;
}

interface Advisory {
  level: RiskLevel;
  headline: string;
  points: string[];
}

function generateClaimCode(): ClaimSecret;
function fromSecret(secret: string): ClaimSecret;   // rebuild from what a user typed
function normaliseSecret(input: string): string | null;
function formatSecret(secret: string): string;      // groups into fours for display
function saltFromSecret(secret: string): Hex;
function hashClaim(salt: Hex, code: string): Hex;

const CLAIM_SECRET_BITS = 80;  // 16 chars x 5 bits

interface ClaimSecret {
  secret: string;    // the one string a human carries: 'A4K7-9QMX-2PR6-TH8D'
  code: string;      // the same value normalised; what `claim` sends
  salt: Hex;         // derived from the secret, not separate entropy. Never transmitted
  claimHash: Hex;    // keccak256(abi.encodePacked(salt, code)) - the only on-chain part
}

function getAllowance(clients: ClientPair, owner: Address): Promise<bigint>;
function approveUsdc(clients: ClientPair, amount: bigint): Promise<Hash | null>;

function sendProtected(
  clients: ClientPair,
  params: SendProtectedParams,
  options?: SendProtectedOptions,
): Promise<SendProtectedResult>;

interface SendProtectedParams {
  configId: Hex;
  to: Address;
  amount: bigint;    // base units (6 decimals)
  claimHash: Hex;
  /** Wrap in Arc's Memo predeploy for reconcilable events. Default true. */
  memo?: boolean;
}

interface SendProtectedResult {
  transferId: bigint;
  txHash: Hash;
  deadline: Date;
}

interface SendProtectedOptions {
  skipRiskCheck?: boolean;       // removes the poisoning defense; use with care
  config?: IntegratorConfig;     // its onWarning policy decides what a warning does
  report?: RiskReport;           // reuse a report you already ran (see below)
  checkOptions?: CheckOptions;   // forwarded to check(); client/contract default from clients
  onReport?: (report: RiskReport) => void; // called when the scan does NOT block
}

const MAX_REPORT_AGE_MS = 120000; // a supplied report older than 2 min is re-scanned

function sendProtectedWithPermit(
  clients: ClientPair,
  params: SendProtectedParams,
  options?: SendProtectedOptions,
): Promise<SendProtectedResult>;

function claim(clients: ClientPair, transferId: bigint, code: string, salt: Hex): Promise<Hash>;
function cancel(clients: ClientPair, transferId: bigint): Promise<Hash>;
function reclaimExpired(clients: ClientPair, transferId: bigint): Promise<Hash>;

function encodeClaimCall(transferId: bigint, code: string, salt: Hex): Hex;
function interpretClaimReceipt(
  receiptLogs: Log[],
  contractAddress: Address,
  transferId: bigint,
  txHash: Hash,
): Hash; // returns txHash on success; throws the same typed errors as claim()

function getTransfer(
  clients: Pick<ClientPair, 'publicClient' | 'contractAddress'>,
  transferId: bigint,
): Promise<ProtectedTransfer>;

function watchTransfer(
  publicClient: PublicClient,
  transferId: bigint,
  options: WatchTransferOptions,
): () => void; // returns an unsubscribe function

interface WatchTransferOptions {
  onUpdate: (transfer: ProtectedTransfer) => void;
  contractAddress?: Address;
}

interface ProtectedTransfer {
  transferId: bigint;
  sender: Address;
  to: Address;
  amount: bigint;
  deadline: Date;
  attempts: number;
  status: TransferStatus;
  claimHash: Hex;
  configId: Hex;
}

type TransferStatus = 'NONE' | 'PENDING' | 'CLAIMED' | 'CANCELLED' | 'RECLAIMED' | 'LOCKED';

function getPermit2Allowance(clients: ClientPair, owner: Address): Promise<bigint>;
function approvePermit2(clients: ClientPair, amount?: bigint): Promise<Hex | null>; // defaults to maxUint256
function signPermit2Transfer(
  clients: ClientPair,
  amount: bigint,
  spender: Address,
  options?: { nonce?: bigint; deadlineSeconds?: number; now?: number },
): Promise<Permit2Signature>;

interface Permit2Signature {
  nonce: bigint;
  deadline: bigint;
  signature: Hex;
}

const TERMINAL_STATUSES: ReadonlySet<TransferStatus>; // CLAIMED, CANCELLED, RECLAIMED

function isTerminal(status: TransferStatus): boolean;
function isOpen(status: TransferStatus): boolean;      // PENDING or LOCKED
function statusBucket(status: TransferStatus): StatusBucket;

function isClaimable(
  transfer: Pick<ProtectedTransfer, 'status' | 'deadline'>,
  now?: number,
): boolean;   // PENDING and not past the deadline

function isReturnable(
  transfer: Pick<ProtectedTransfer, 'status' | 'deadline'>,
  now?: number,
): boolean;   // open and past the deadline

type StatusBucket = 'pending' | 'claimed' | 'cancelled' | 'expired';

function gasReserve(gasPrice: bigint, gasLimit?: bigint): bigint;
function readGasReserve(client: { getGasPrice(): Promise<bigint> }, gasLimit?: bigint): Promise<bigint>;
function spendableAfterGas(balance: bigint, reserve: bigint): bigint;

const SEND_GAS_LIMIT = 700000n;  // a protected send
const PAY_GAS_LIMIT = 900000n;   // deploy + fund + pay, the three a private payment sends
const MIN_GAS_RESERVE = 50000n;  // 0.05 USDC floor

function getCleanHistory(
  address: Address,
  options?: GetCleanHistoryOptions,
): Promise<CleanHistory>;

interface GetCleanHistoryOptions {
  apiUrl?: string;
  fetchFn?: typeof fetch;
  /** Tokens that may appear in the clean view. Defaults to Arc's USDC + EURC. */
  allowedTokens?: Address[];
}

interface CleanHistory {
  entries: HistoryEntry[];
  /** What was hidden, and why. Shown behind a "spam" toggle rather than destroyed. */
  filtered: FilteredEntry[];
}

interface HistoryEntry {
  txHash: `0x${string}`;
  direction: 'in' | 'out';
  /** `0x0000...0000` when `kind` is not `transfer`. Read `kind` first. */
  counterparty: Address;
  kind: EntryKind;      // 'transfer' | 'mint' | 'burn'
  amount: bigint;       // base units, in the token's own decimals
  decimals: number;
  tokenAddress: Address;
  tokenSymbol: string;
  timestamp: Date;
}

interface FilteredEntry extends HistoryEntry {
  reason: 'ZERO_VALUE' | 'UNKNOWN_TOKEN';
}

function defineConfig(input?: DefineConfigInput): IntegratorConfig;
function registerConfig(clients: ClientPair, config: IntegratorConfig): Promise<RegisterConfigResult>;
function recommendTransferMode(config: IntegratorConfig, amount: bigint): 'protected' | 'plain';
function shouldBlockSend(config: IntegratorConfig, level: RiskLevel): boolean;

const MAX_FEE_BPS = 100;               // max integrator fee: 1%
const MAX_RECALL_WINDOW_SECONDS = 604800; // 7 days

interface IntegratorConfig {
  recallWindow: number;        // seconds before an unclaimed transfer is refundable
  claimMode: ClaimMode;        // only 'CODE' ships in v1
  feeBps: number;              // 0..100 (max 1%)
  feeRecipient: Address;
  minProtectedAmount: bigint;  // below this, recommendTransferMode returns 'plain'
  onWarning: 'warn' | 'block'; // what a `warning` verdict does
}

type ClaimMode = 'CODE' | 'SIGNATURE' | 'REGISTERED';
type DefineConfigInput = Partial<IntegratorConfig>;

interface RegisterConfigResult {
  configId: Hex;
  txHash: Hash;
}

function predictEphemeral(
  publicClient: PublicClient,
  factory: Address,
  salt: Hex,
  policy: EphemeralPolicy,
): Promise<Address>;

function createEphemeral(
  clients: ShieldClients,
  factory: Address,
  salt: Hex,
  policy: EphemeralPolicy,
): Promise<{ account: Address; txHash: Hex }>;

function fundEphemeral(
  clients: ShieldClients,
  account: Address,
  amount: bigint,
  policy: EphemeralPolicy,
): Promise<Hex>;

function fundFromVault(
  clients: ShieldClients,
  vault: Address,
  account: Address,
  amount: bigint,
): Promise<Hex>;

interface EphemeralPolicy {
  token: Address;
  owner: Address;      // bound only as a hash (the salt); never written to the account
  cosigner: Address;
  vault: Address;      // bound only as a commitment; address revealed only at sweep
  target: Address;
  maxAmount: bigint;
  perPullMax?: bigint; // PULL only: max per single pull. 0 = no tighter cap than maxAmount
  expiry: number;      // unix seconds; no outbound payment after this
  interval: number;    // PULL only: min seconds between pulls. 0 for PUSH
  mode: SpendMode;
}

function readAccount(publicClient: PublicClient, account: Address): Promise<AccountState>;

interface AccountState {
  nonce: bigint;
  spent: bigint;
  remaining: bigint;
  target: Address;
  perPullMax: bigint;
  expiry: number;
  mode: SpendMode;
}

function submitPay(clients: ShieldClients, account: Address, amount: bigint, cosignerSig: Hex): Promise<Hex>;
function submitPull(clients: ShieldClients, account: Address, amount: bigint, cosignerSig: Hex): Promise<Hex>;
function sweepToVault(clients: ShieldClients, account: Address, vault: Address): Promise<Hex>;
function sweepExpired(clients: ShieldClients, account: Address, vault: Address): Promise<Hex>;

function settlePrivatePayment(
  clients: ShieldClients,
  account: Address,
  amount: bigint,
  cosigner: CoSigner,
  ctx: { owner: Address },
): Promise<PrivatePayOutcome>;

interface PrivatePayResult {
  account: Address;
  txHash: Hex;
}

type PrivatePayOutcome =
  | { ok: true; result: PrivatePayResult }
  | { ok: false; vetoed: true; reason: string; riskReasons?: string[] };

const outcome = await settlePrivatePayment(clients, account, amount, cosigner, { owner });
if (!outcome.ok) console.warn('Vetoed:', outcome.reason);
else console.log('Paid:', outcome.result.txHash);

interface CoSigner {
  precheck(req: PrecheckRequest): Promise<PrecheckResult>;
  authorize(req: AuthorizeRequest): Promise<AuthorizeResult>;
  readonly address: Address;
}

class LocalCoSigner implements CoSigner {
  constructor(privateKey: Hex, opts?: LocalCoSignerOptions);
}

class RemoteCoSigner implements CoSigner {
  constructor(endpoint: string, address: Address, fetchImpl?: typeof fetch);
}

interface LocalCoSignerOptions {
  riskCheck?: RiskCheck;         // if omitted, every target is vetoed (fail-closed)
  vetoOn?: 'block' | 'warning';  // veto threshold; default 'block'
}

type RiskCheck = (owner: Address, target: Address) => Promise<RiskVerdict | null>;

interface RiskVerdict {
  level: 'safe' | 'warning' | 'block';
  complete: boolean;
  reasons?: string[];
}

interface PrecheckRequest {
  owner: Address;
  target: Address;
  amount: bigint;
}
type PrecheckResult = { approved: true } | { approved: false; reason: string; riskReasons?: string[] };

interface SpendRequest {
  account: Address;
  owner: Address;
  amount: bigint;
  action: SpendAction;
}

interface AuthorizeRequest extends SpendRequest {
  target: Address;
  nonce: bigint;
  chainId: number;
  remaining: bigint;
  expiry: number;  // unix seconds
  now?: number;    // injectable for tests
}
type AuthorizeResult =
  | { approved: true; signature: Hex }
  | { approved: false; reason: string; riskReasons?: string[] };

class RemoteCoSigner implements CoSigner {
  constructor(
    endpoint: string,
    address: Address,
    fetchImpl?: typeof fetch,
    auth?: RemoteCoSignerAuth,
  );
}

interface RemoteCoSignerAuth {
  address: Address;
  sign: (message: string) => Promise<Hex>;
}

function cosignAuthMessage(owner: Address, ts: number, scope: CosignAuthScope): string;

interface CosignAuthScope {
  target?: Address;   // precheck binds the intended target (no account exists yet)
  account?: Address;  // authorize binds the account being spent from
  amount: bigint;
  action?: SpendAction; // authorize binds PAY vs PULL; precheck omits it
}

interface CounterfactualRequest {
  factory: Address;
  ownerHash: Hex;
  salt: Hex;
  policy: CounterfactualPolicy;
  box: Address;      // client-predicted; the server recomputes and must match
  owner: Address;
  amount: bigint;
  chainId: number;
}

function settlePrivatePaymentBatched(/* ... */): Promise<PrivatePayOutcome>;

function assertBoxFundable(publicClient: PublicClient, account: Address, policy: EphemeralPolicy): Promise<void>;
function fundBoxFromGateway(clients: { walletClient: WalletClient }, params: FundBoxParams): Promise<{ transferId?: string }>;
function awaitBoxFunded(
  publicClient: PublicClient,
  account: Address,
  amount: bigint,
  usdc: Address,
  opts?: { timeoutMs?: number; pollMs?: number; now?: () => number },
): Promise<boolean>;
function isBoxFunding(recipient: string | undefined, boxes: ReadonlySet<string>): boolean;

interface FundBoxParams {
  account: Address;
  amount: bigint;
  from: GatewayChain;  // which chain's Gateway balance pays
  to: GatewayChain;    // which chain the box is on, and where Circle mints
  onTransferId?: (id: string) => void;
  timeoutMs?: number;
}

class AnnouncementIndex { /* stealth announcements, cached and scanned in chunks */ }
class AccountOwnerIndex { /* boxes by ownerHash, across current and prior factories */ }

function explorerAnnouncements(/* ... */): Promise<IndexedAnnouncement[]>;
function explorerAccountsCreated(/* ... */): Promise<CreatedAccount[]>;
function explorerLogs(/* ... */): Promise<unknown[]>;
function explorerUsable(): ExplorerHealth;
function clearExplorerState(): void;

const EXPLORER_MAX_LAG_BLOCKS: bigint;

function spendTypedData(p: SpendDigestParams): {
  domain: TypedDataDomain;
  types: typeof SPEND_TYPES;
  primaryType: 'Spend';
  message: { target: Address; amount: bigint; nonce: bigint; action: SpendAction };
};
function spendDigest(p: SpendDigestParams): Hex; // the 32-byte digest; equals account.spendDigest(amount, action)
function ownerHash(owner: Address): Hex;          // keccak256(abi.encode(owner)) - the CREATE2 salt binding
function vaultHash(vault: Address): Hex;          // keccak256(abi.encode(vault)) - the return-address commitment

interface SpendDigestParams {
  account: Address;   // becomes the EIP-712 verifyingContract
  chainId: number;
  target: Address;
  amount: bigint;
  nonce: bigint;
  action: SpendAction;
}

const ACTION_PAY = 0;   // SpendAction
const ACTION_PULL = 1;  // SpendAction
const SPEND_DOMAIN_NAME = 'Ctrl+ArcZ SpendPolicy';
const SPEND_DOMAIN_VERSION = '1';
// SPEND_TYPES - the EIP-712 `Spend(address target,uint256 amount,uint256 nonce,uint8 action)` type

const STEALTH_SCHEME_ID = 1;
const STEALTH_KEY_MESSAGE: string;  // signed once; never retype it

function deriveStealthKeys(signature: Hex): StealthKeys;
function generateStealthAddress(meta: StealthMetaAddress, ephemeralKey?: Hex): StealthAnnouncement;
function checkStealthAddress(params: {
  viewingKey: Hex;
  spendingPub: Hex;
  ephemeralPubKey: Hex;
  viewTag?: number;
}): Address | null;
function computeStealthPrivateKey(params: {
  spendingKey: Hex;
  viewingKey: Hex;
  ephemeralPubKey: Hex;
}): Hex;

interface StealthMetaAddress {
  spendingPub: Hex;   // compressed secp256k1 point; funds derive against this
  viewingPub: Hex;    // compressed secp256k1 point; only this key scans
}
interface StealthKeys extends StealthMetaAddress {
  spendingKey: Hex;
  viewingKey: Hex;
}
interface StealthAnnouncement {
  stealthAddress: Address;
  ephemeralPubKey: Hex;
  viewTag: number;    // first byte of the shared secret; skips non-matches cheaply
}

function newStealthOwner(meta: StealthMetaAddress, ephemeralKey?: Hex): {
  stealthAddress: Address;
  ephemeralPubKey: Hex;
  viewTag: number;
};
function announceArgsFor(
  stealth: { stealthAddress: Address; ephemeralPubKey: Hex },
  box: Address,
  label?: string,
): readonly [bigint, Address, Hex, Hex];
function announceStealthBox(
  clients: { publicClient: PublicClient; walletClient: WalletClient },
  announcer: Address,
  announceArgs: readonly [bigint, Address, Hex, Hex],
): Promise<Hex>;
function discoverStealthBoxes(
  publicClient: PublicClient,
  announcer: Address,
  keys: Pick<StealthKeys, 'viewingKey' | 'spendingPub'>,
  opts?: { fromBlock?: bigint },
): Promise<StealthBox[]>;
function recognizeAnnouncements(
  keys: Pick<StealthKeys, 'viewingKey' | 'spendingPub'>,
  announcements: RawAnnouncement[],
): StealthBox[];

function encodeStealthMetadata(box: Address, label?: string): Hex;
function decodeStealthMetadata(metadata: Hex): StealthMetadata;

interface StealthBox {
  stealthAddress: Address;
  box: Address;       // the SpendPolicyAccount this announcement points at
  ephemeralPubKey: Hex;
  label: string;      // the announced name, or empty
}

function quoteBridge(params: {
  from: CctpChainName;
  to: CctpChainName;
  amount: bigint;
  fetchImpl?: typeof fetch;
}): Promise<BridgeQuote>;

function bridgeFromWallet(
  clients: { publicClient: PublicClient; walletClient: WalletClient },
  params: {
    from: CctpChainName;
    to: CctpChainName;
    amount: bigint;
    recipient?: Address;               // defaults to the sending wallet
    onQuote?: (quote: BridgeQuote) => void;
    onStep?: (step: CctpStep, txHash?: Hex) => void;
    timeoutMs?: number;
  },
): Promise<BridgeResult>;

function findForwardedMint(params: { sourceDomain: number; burnTxHash: Hex }): Promise<Hex | undefined>;
function waitForForwardedMint(params: {
  sourceDomain: number;
  burnTxHash: Hex;
  timeoutMs?: number;
}): Promise<Hex | undefined>;

function chainLabel(name: CctpChainName): string;
function chainExplorerTxUrl(chain: CctpChainName, txHash: string): string | undefined;
function cctpChainByChainId(chainId: number | undefined): CctpChainName | undefined;

const CCTP_CHAINS: Record<CctpChainName, CctpChain>;  // 20 testnets
const CCTP_TOKEN_MESSENGER: Address;
const IRIS_TESTNET: string;
const FORWARDING_HOOK: Hex;   // ascii 'cctp-forward', padded to 32 bytes

type CctpStep = 'quote' | 'approve' | 'burn' | 'attest' | 'forward';

interface BridgeQuote { amount: bigint; maxFee: bigint; total: bigint }
interface BridgeResult {          // exported as CctpBridgeResult
  approveTxHash?: Hex;
  burnTxHash: Hex;
  forwardTxHash?: Hex;
  quote: BridgeQuote;
}
interface CctpChain {
  domain: number;      // a CCTP domain, NOT a chain id
  chainId: number;
  usdc: Address;
  gasToken?: 'usdc';   // set only where gas is the same USDC being bridged (Arc)
}

function depositToGateway(
  clients: { publicClient: PublicClient; walletClient: WalletClient },
  params: { chain: GatewayChain; amount: bigint; onStep?: (s: GatewayStep, h?: Hex) => void },
): Promise<{ approveTxHash?: Hex; depositTxHash: Hex }>;

function gatewayBalance(params: {
  depositor: Address;
  chains?: readonly GatewayChain[];
}): Promise<GatewayBalance>;

function quoteGatewaySpend(params: {
  from: GatewayChain;
  to: GatewayChain;
  amount: bigint;
  depositor: Address;
  recipient?: Address;
}): Promise<GatewayQuote>;

function spendFromGateway(
  clients: { walletClient: WalletClient },
  params: {
    from: GatewayChain;
    to: GatewayChain;
    amount: bigint;
    recipient?: Address;
    onTransferId?: (transferId: string) => void;
    onStep?: (step: GatewayStep, txHash?: Hex) => void;
    timeoutMs?: number;
  },
): Promise<GatewaySpendResult>;

function findGatewayMint(params: { transferId: string }): Promise<GatewayTransferStatus>;
function waitForGatewayMint(params: {
  transferId: string;
  timeoutMs?: number;
}): Promise<GatewayTransferStatus>;
function isGatewayChain(name: string): name is GatewayChain;
function isGatewayWithdrawal(params: { from: GatewayChain; to: GatewayChain }): boolean;

const GATEWAY_CHAIN_NAMES: readonly GatewayChain[];  // 11 of the CCTP chains
const GATEWAY_WALLET: Address;
const GATEWAY_MINTER: Address;
const GATEWAY_API_TESTNET: string;
const DEPOSIT_CONFIRMATION_SECONDS: Record<GatewayChain, number>;

type GatewayStep = 'approve' | 'deposit' | 'quote' | 'sign' | 'transfer' | 'mint';

interface GatewayBalance {
  total: bigint;
  byChain: Partial<Record<GatewayChain, bigint>>;  // spend against THIS, not total
}
interface GatewayQuote {
  maxFee: bigint;      // what gets signed: Circle's quote plus headroom
  quotedFee: bigint;   // Circle's unpadded figure, for showing a real fee
  maxBlockHeight: bigint;
  total: bigint;
}
interface GatewaySpendResult { transferId: string; mintTxHash?: Hex; quote: GatewayQuote }
interface GatewayTransferStatus {
  /** `pending` covers every non-terminal state, including a poll that failed. */
  state: 'pending' | 'done' | 'failed';
  mintTxHash?: Hex;
  reason?: string;
}

function usdc(subunits: bigint, decimals?: number): string;
function percentOf(maxSpendable: bigint, fraction: number, decimals?: number): string;
function maxGatewaySpendable(here: bigint, feeCeiling: bigint): bigint;
function maxDepositable(walletBalance: bigint, gasReserve: bigint): bigint;
function gatewayShortfall(params: {
  here: bigint;              // the balance ON THE SOURCE CHAIN
  byChain: Record<string, bigint>;
  from: string;
  fromLabel: string;
  committed: bigint;         // amount + fee ceiling
  labelOf: (chain: string) => string;
}): Refusal | null;
function cctpShortfall(params: {
  usdcBalance: bigint;
  total: bigint;
  maxFee: bigint;
  gasCost: bigint;
  nativeBalance: bigint;
  chainLabel: string;
  gasInUsdc: boolean;        // true on Arc: transfer and gas share one balance
  nativePerUsdc?: bigint;
}): Refusal | null;

interface Refusal {
  code: 'gwNoBalanceHere' | 'gwEnoughOn' | 'gwShort' | 'shortWithFee' | 'shortWithGas' | 'noGas';
  params: Record<string, string>;  // already formatted for reading
  fix?: RefusalFix;
}
type RefusalFix =
  | { kind: 'switchSource'; chain: string; label: string }
  | { kind: 'deposit'; amount: bigint; display: string }
  | { kind: 'useMax'; amount: bigint; display: string };

import { spendPolicyAccountAbi, readAccount } from '@ctrl-arcz/sdk';
// use the ABI directly with viem, or prefer the typed wrappers like readAccount above