@continuumdao/ctm-mpc-defi 0.2.16 → 0.2.17

package/dist/protocols/evm/circle-cctp/index.js

@@ -0,0 +1,1026 @@
+import { parseAbi, getAddress, formatUnits, parseUnits, defineChain, createPublicClient, http, pad, encodeFunctionData, parseGwei, serializeTransaction, keccak256 } from 'viem';
+import { fetchChainFeeParams, gasLimitFromEstimateAndChainConfig, gweiToDecimalString, proposalTxParamsToFeeSnapshot, alignEip1559FeesWithLatestBase, getClientIdFromKeyGenResult } from '@continuumdao/continuum-node-sdk';
+
+// src/core/registry.ts
+var modules = [];
+function registerProtocolModule(mod) {
+  const existing = modules.findIndex((m) => m.id === mod.id);
+  if (existing >= 0) {
+    modules[existing] = mod;
+  } else {
+    modules.push(mod);
+  }
+}
+
+// src/protocols/evm/circle-cctp/constants.ts
+var CIRCLE_CCTP_PROTOCOL_ID = "circle-cctp";
+var IRIS_API_MAINNET = "https://iris-api.circle.com";
+var IRIS_API_SANDBOX = "https://iris-api-sandbox.circle.com";
+var TOKEN_MESSENGER_V2_MAINNET = "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d";
+var TOKEN_MESSENGER_V2_TESTNET = "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
+var FORWARDING_SERVICE_HOOK_DATA = "0x636374702d666f72776172640000000000000000000000000000000000000000";
+var CCTP_DEFAULT_MIN_FINALITY_THRESHOLD = 1e3;
+var CCTP_USDC_DECIMALS = 6;
+var CCTP_ERC20_APPROVE_FALLBACK_GAS = 100000n;
+var CCTP_DEPOSIT_FOR_BURN_FALLBACK_GAS = 350000n;
+var CCTP_EVM_CHAINS = [
+  {
+    chainId: 1,
+    domain: 0,
+    network: "mainnet",
+    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    tokenMessenger: TOKEN_MESSENGER_V2_MAINNET,
+    label: "Ethereum"
+  },
+  {
+    chainId: 43114,
+    domain: 1,
+    network: "mainnet",
+    usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+    tokenMessenger: TOKEN_MESSENGER_V2_MAINNET,
+    label: "Avalanche"
+  },
+  {
+    chainId: 10,
+    domain: 2,
+    network: "mainnet",
+    usdc: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+    tokenMessenger: TOKEN_MESSENGER_V2_MAINNET,
+    label: "OP Mainnet"
+  },
+  {
+    chainId: 42161,
+    domain: 3,
+    network: "mainnet",
+    usdc: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    tokenMessenger: TOKEN_MESSENGER_V2_MAINNET,
+    label: "Arbitrum"
+  },
+  {
+    chainId: 8453,
+    domain: 6,
+    network: "mainnet",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    tokenMessenger: TOKEN_MESSENGER_V2_MAINNET,
+    label: "Base"
+  },
+  {
+    chainId: 137,
+    domain: 7,
+    network: "mainnet",
+    usdc: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    tokenMessenger: TOKEN_MESSENGER_V2_MAINNET,
+    label: "Polygon PoS"
+  },
+  {
+    chainId: 11155111,
+    domain: 0,
+    network: "testnet",
+    usdc: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    tokenMessenger: TOKEN_MESSENGER_V2_TESTNET,
+    label: "Ethereum Sepolia"
+  },
+  {
+    chainId: 43113,
+    domain: 1,
+    network: "testnet",
+    usdc: "0x5425890298aed601595a70AB815c96711a31Bc65",
+    tokenMessenger: TOKEN_MESSENGER_V2_TESTNET,
+    label: "Avalanche Fuji"
+  },
+  {
+    chainId: 11155420,
+    domain: 2,
+    network: "testnet",
+    usdc: "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
+    tokenMessenger: TOKEN_MESSENGER_V2_TESTNET,
+    label: "OP Sepolia"
+  },
+  {
+    chainId: 421614,
+    domain: 3,
+    network: "testnet",
+    usdc: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
+    tokenMessenger: TOKEN_MESSENGER_V2_TESTNET,
+    label: "Arbitrum Sepolia"
+  },
+  {
+    chainId: 84532,
+    domain: 6,
+    network: "testnet",
+    usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    tokenMessenger: TOKEN_MESSENGER_V2_TESTNET,
+    label: "Base Sepolia"
+  },
+  {
+    chainId: 80002,
+    domain: 7,
+    network: "testnet",
+    usdc: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
+    tokenMessenger: TOKEN_MESSENGER_V2_TESTNET,
+    label: "Polygon Amoy"
+  }
+];
+function cctpChainConfig(chainId) {
+  return CCTP_EVM_CHAINS.find((c) => c.chainId === chainId) ?? null;
+}
+function parseCctpEvmChainId(chainId) {
+  if (typeof chainId === "number") {
+    return Number.isFinite(chainId) ? chainId : Number.NaN;
+  }
+  const t = String(chainId).trim();
+  if (!t) return Number.NaN;
+  const low = t.toLowerCase();
+  if (low.startsWith("eip155:")) {
+    const n2 = Number.parseInt(t.slice("eip155:".length).trim(), 10);
+    return Number.isFinite(n2) ? n2 : Number.NaN;
+  }
+  if (low.startsWith("0x")) {
+    const n2 = Number.parseInt(t, 16);
+    return Number.isFinite(n2) ? n2 : Number.NaN;
+  }
+  const n = Number.parseInt(t, 10);
+  return Number.isFinite(n) ? n : Number.NaN;
+}
+function isCctpSourceChainSupported(chainId) {
+  const n = parseCctpEvmChainId(chainId);
+  return Number.isFinite(n) && cctpChainConfig(n) != null;
+}
+function cctpCanonicalUsdcAddress(chainId) {
+  const n = parseCctpEvmChainId(chainId);
+  if (!Number.isFinite(n)) return null;
+  const raw = cctpChainConfig(n)?.usdc;
+  if (!raw) return null;
+  try {
+    return getAddress(raw);
+  } catch {
+    return null;
+  }
+}
+function isCctpCanonicalUsdcRow(chainId, contractAddress) {
+  const n = parseCctpEvmChainId(chainId);
+  if (!Number.isFinite(n)) return false;
+  const canonical = cctpCanonicalUsdcAddress(n);
+  if (!canonical) return false;
+  try {
+    return getAddress(contractAddress).toLowerCase() === canonical.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+function chainIdToDomain(chainId) {
+  return cctpChainConfig(chainId)?.domain ?? null;
+}
+function domainToChainId(domain, network) {
+  const row = CCTP_EVM_CHAINS.find((c) => c.domain === domain && c.network === network);
+  return row?.chainId ?? null;
+}
+function isCctpRouteSupported(sourceChainId, destChainId) {
+  const src = cctpChainConfig(sourceChainId);
+  const dst = cctpChainConfig(destChainId);
+  if (!src || !dst) return false;
+  if (src.network !== dst.network) return false;
+  if (src.chainId === dst.chainId) return false;
+  return true;
+}
+function irisApiBaseForChainId(chainId) {
+  const cfg = cctpChainConfig(chainId);
+  if (!cfg) throw new Error(`Chain ${chainId} is not a supported CCTP EVM chain.`);
+  return cfg.network === "mainnet" ? IRIS_API_MAINNET : IRIS_API_SANDBOX;
+}
+function cctpSupportedRoutes(network) {
+  const chains = network ? CCTP_EVM_CHAINS.filter((c) => c.network === network) : [...CCTP_EVM_CHAINS];
+  const out = [];
+  for (const src of chains) {
+    for (const dst of chains) {
+      if (src.chainId === dst.chainId) continue;
+      if (src.network !== dst.network) continue;
+      out.push({
+        sourceChainId: src.chainId,
+        destChainId: dst.chainId,
+        sourceDomain: src.domain,
+        destDomain: dst.domain,
+        sourceLabel: src.label,
+        destLabel: dst.label,
+        network: src.network
+      });
+    }
+  }
+  return out;
+}
+
+// src/protocols/evm/circle-cctp/fees.ts
+function pickForwardFeeTier(row, tier) {
+  const forwardFee = row.forwardFee;
+  if (forwardFee && typeof forwardFee === "object") {
+    const key = tier === "low" ? "low" : tier === "high" ? "high" : "med";
+    const v = forwardFee[key];
+    if (v != null) return BigInt(String(v));
+  }
+  const maxFee = row.maximumFee ?? row.maxFee ?? row.forwardFee;
+  if (maxFee != null) return BigInt(String(maxFee));
+  throw new Error("Iris fee response missing forwardFee tiers.");
+}
+async function fetchCctpBurnFees(args) {
+  const tier = args.feeTier ?? "med";
+  const base = irisApiBaseForChainId(args.sourceChainId);
+  const url = `${base}/v2/burn/USDC/fees/${args.sourceDomain}/${args.destDomain}?forward=true`;
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Iris fee quote failed (${res.status}): ${text.slice(0, 200)}`);
+  }
+  const json = await res.json();
+  const rows = Array.isArray(json) ? json : Array.isArray(json.data) ? json.data : [json];
+  const row = rows[0] ?? {};
+  const low = pickForwardFeeTier(row, "low");
+  const med = pickForwardFeeTier(row, "med");
+  const high = pickForwardFeeTier(row, "high");
+  const maxFee = tier === "low" ? low : tier === "high" ? high : med;
+  return {
+    sourceDomain: args.sourceDomain,
+    destDomain: args.destDomain,
+    maxFee,
+    forwardFeeLow: low,
+    forwardFeeMed: med,
+    forwardFeeHigh: high,
+    feeTierUsed: tier
+  };
+}
+function formatCctpUsdcHuman(wei) {
+  const raw = formatUnits(wei, CCTP_USDC_DECIMALS);
+  if (!raw.includes(".")) return raw;
+  return raw.replace(/\.?0+$/, "") || "0";
+}
+
+// src/core/purpose.ts
+function mergePurposeText(purposeText, purposeSuffix) {
+  const t = (purposeText ?? "").trim();
+  const suffix = (purposeSuffix ?? "").trim();
+  if (!suffix) return t;
+  return t ? `${t}
+
+${suffix}` : suffix;
+}
+
+// src/core/envelope.ts
+function finalizeMultisign(input) {
+  const { keyGen, destinationChainID, legs } = input;
+  if (legs.length === 0) {
+    throw new Error("finalizeMultisign requires at least one leg");
+  }
+  const ph = (keyGen.pubkeyhex ?? "").trim();
+  if (!ph) throw new Error("keyGen pubKey (pubkeyhex) is required");
+  const keyList = keyGen.keylist ?? [];
+  const clientId = getClientIdFromKeyGenResult(keyGen);
+  const first = legs[0];
+  const messageHashes = legs.map((l) => l.msgHash);
+  const messageRawBatch = legs.map((l) => l.msgRaw);
+  const batchMeta = legs.map((l) => ({
+    destinationAddress: l.destinationAddress,
+    signatureText: l.signatureText,
+    ...l.audit
+  }));
+  const proposalTxParams = legs.map((l) => l.proposalTxParams).filter((p) => p != null && typeof p === "object");
+  const extraPayload = {
+    batchMeta,
+    ...input.extraJSON ?? {}
+  };
+  const extraJSON = JSON.stringify(extraPayload);
+  const bodyForSign = {
+    keyList,
+    pubKey: ph,
+    msgHash: messageHashes[0],
+    msgRaw: first.msgRaw,
+    destinationChainID,
+    destinationAddress: input.destinationAddress ?? first.destinationAddress,
+    extraJSON,
+    signatureText: first.signatureText,
+    purpose: mergePurposeText(input.purposeText, input.purposeSuffix),
+    ...first.feeSnapshot
+  };
+  if (legs.length > 1) {
+    bodyForSign.messageHashes = messageHashes;
+    bodyForSign.messageRawBatch = messageRawBatch;
+  }
+  if (proposalTxParams.length > 0) {
+    bodyForSign.proposalTxParams = proposalTxParams;
+  }
+  const valueWei = first.valueWei;
+  if (valueWei != null && valueWei > 0n) {
+    bodyForSign.value = valueWei.toString();
+  }
+  if (clientId) bodyForSign.clientId = clientId;
+  return { bodyForSign, messageToSign: JSON.stringify(bodyForSign) };
+}
+function routerSwapGasLimitFromEstimate(estimatedGas, chainGasLimit) {
+  if (chainGasLimit != null && Number.isFinite(chainGasLimit) && chainGasLimit > 0) {
+    return gasLimitFromEstimateAndChainConfig(estimatedGas, chainGasLimit);
+  }
+  return (estimatedGas * 12n + 9n) / 10n;
+}
+
+// src/chains/evm/buildBatch.ts
+async function buildEvmMultisignBatch(args) {
+  const { context, steps } = args;
+  const {
+    chainId,
+    rpcUrl,
+    executorAddress,
+    chainDetail,
+    useCustomGas,
+    customGasChainDetails,
+    keyGen,
+    purposeText
+  } = context;
+  if (steps.length === 0) throw new Error("buildEvmMultisignBatch requires at least one step");
+  const ch = defineChain({
+    id: chainId,
+    name: "Destination",
+    nativeCurrency: { decimals: 18, name: "Ether", symbol: "ETH" },
+    rpcUrls: { default: { http: [rpcUrl] } }
+  });
+  const publicClient = createPublicClient({ chain: ch, transport: http(rpcUrl) });
+  const feeParams = await fetchChainFeeParams(rpcUrl, chainId);
+  const legacy = Boolean(chainDetail?.legacy) || !feeParams.isEip1559;
+  const latestBaseFeeWei = !legacy ? (await publicClient.getBlock({ blockTag: "latest" })).baseFeePerGas ?? 0n : 0n;
+  const gasLimitConfig = useCustomGas && chainDetail?.gasLimit != null ? Number(chainDetail.gasLimit) : void 0;
+  const chainGasLimitRouter = chainDetail?.gasLimit != null && Number.isFinite(Number(chainDetail.gasLimit)) && Number(chainDetail.gasLimit) > 0 ? Number(chainDetail.gasLimit) : void 0;
+  const gasFeeMultiplier = useCustomGas && chainDetail?.gasMultiplier != null ? Number(chainDetail.gasMultiplier) : void 0;
+  const executor = getAddress(executorAddress);
+  const baseNonce = await publicClient.getTransactionCount({ address: executor, blockTag: "pending" });
+  const legs = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const currentNonce = baseNonce + i;
+    let estimatedGas;
+    if (args.estimateGasForStep) {
+      estimatedGas = await args.estimateGasForStep({ step, index: i, publicClient, executor });
+    } else {
+      try {
+        estimatedGas = await publicClient.estimateGas({
+          to: step.to,
+          data: step.data,
+          value: step.value,
+          account: executor
+        });
+      } catch {
+        estimatedGas = step.fallbackGas ?? 100000n;
+      }
+    }
+    let gasLimitI;
+    if (args.resolveGasLimit) {
+      gasLimitI = await args.resolveGasLimit({ step, index: i, estimatedGas, publicClient });
+    } else if (step.routerSwap) {
+      gasLimitI = routerSwapGasLimitFromEstimate(estimatedGas, chainGasLimitRouter);
+    } else {
+      gasLimitI = useCustomGas ? gasLimitFromEstimateAndChainConfig(estimatedGas, gasLimitConfig) : estimatedGas;
+    }
+    let proposalTxParams;
+    let feeSnapshot;
+    let serialized;
+    if (legacy) {
+      let gasPriceWei = await publicClient.getGasPrice();
+      if (useCustomGas && gasFeeMultiplier != null && gasFeeMultiplier > 0) {
+        gasPriceWei = gasPriceWei * BigInt(100 + gasFeeMultiplier) / 100n;
+      }
+      if (useCustomGas && chainDetail?.gasPrice != null && chainDetail.gasPrice > 0) {
+        const configured = parseGwei(gweiToDecimalString(Number(chainDetail.gasPrice)));
+        if (configured > gasPriceWei) gasPriceWei = configured;
+      }
+      serialized = serializeTransaction({
+        type: "legacy",
+        to: step.to,
+        data: step.data,
+        value: step.value,
+        gas: gasLimitI,
+        gasPrice: gasPriceWei,
+        nonce: currentNonce,
+        chainId
+      });
+      proposalTxParams = {
+        nonce: currentNonce,
+        gasLimit: gasLimitI.toString(),
+        txType: "legacy",
+        gasPrice: gasPriceWei.toString()
+      };
+      feeSnapshot = proposalTxParamsToFeeSnapshot(proposalTxParams);
+    } else {
+      const fetchedBase = feeParams.baseFeeGwei ?? 0;
+      const fetchedPriority = feeParams.priorityFeeGwei ?? 0;
+      const configuredBase = useCustomGas && chainDetail?.baseFee != null ? Number(chainDetail.baseFee) : 0;
+      const configuredPriority = useCustomGas && chainDetail?.priorityFee != null ? Number(chainDetail.priorityFee) : 0;
+      const effectiveBaseFeeGwei = Math.max(fetchedBase, configuredBase);
+      const effectivePriorityFeeGwei = Math.max(fetchedPriority, configuredPriority);
+      const baseFeeMultiplierPct = useCustomGas && chainDetail?.baseFeeMultiplier != null ? Math.max(100, Number(chainDetail.baseFeeMultiplier)) : 100;
+      const baseComponentGwei = effectiveBaseFeeGwei * baseFeeMultiplierPct / 100;
+      const maxFeePerGasGwei = baseComponentGwei + effectivePriorityFeeGwei;
+      let maxPriorityFeePerGas = effectivePriorityFeeGwei > 0 ? parseGwei(gweiToDecimalString(effectivePriorityFeeGwei)) : parseGwei("1");
+      let maxFeePerGas = parseGwei(gweiToDecimalString(maxFeePerGasGwei));
+      if (useCustomGas && gasFeeMultiplier != null && gasFeeMultiplier > 0) {
+        maxPriorityFeePerGas = maxPriorityFeePerGas * BigInt(100 + gasFeeMultiplier) / 100n;
+        maxFeePerGas = maxFeePerGas * BigInt(100 + gasFeeMultiplier) / 100n;
+      }
+      ({ maxFeePerGas, maxPriorityFeePerGas } = alignEip1559FeesWithLatestBase(
+        maxFeePerGas,
+        maxPriorityFeePerGas,
+        latestBaseFeeWei
+      ));
+      serialized = serializeTransaction({
+        type: "eip1559",
+        to: step.to,
+        data: step.data,
+        value: step.value,
+        gas: gasLimitI,
+        maxFeePerGas,
+        maxPriorityFeePerGas,
+        nonce: currentNonce,
+        chainId
+      });
+      proposalTxParams = {
+        nonce: currentNonce,
+        gasLimit: gasLimitI.toString(),
+        txType: "eip1559",
+        maxFeePerGas: maxFeePerGas.toString(),
+        maxPriorityFeePerGas: maxPriorityFeePerGas.toString()
+      };
+      feeSnapshot = i === 0 ? proposalTxParamsToFeeSnapshot(proposalTxParams) : {};
+    }
+    const h = keccak256(serialized);
+    const msgHash = h.startsWith("0x") ? h.slice(2) : h;
+    const batchMetaExtra = args.buildBatchMeta({ step, index: i, gasLimit: gasLimitI });
+    legs.push({
+      msgHash,
+      msgRaw: i === 0 && args.firstMsgRawNo0x != null ? args.firstMsgRawNo0x : serialized,
+      destinationAddress: step.to,
+      signatureText: typeof batchMetaExtra.signatureText === "string" ? batchMetaExtra.signatureText : JSON.stringify(batchMetaExtra.signatureText ?? {}),
+      audit: batchMetaExtra,
+      feeSnapshot: i === 0 ? feeSnapshot : {},
+      proposalTxParams,
+      valueWei: i === 0 ? step.value : void 0
+    });
+    if (i === 0 && args.firstMsgRawNo0x != null) {
+      legs[0].msgRaw = args.firstMsgRawNo0x;
+    }
+  }
+  const extraJSON = {};
+  if (useCustomGas && customGasChainDetails && Object.keys(customGasChainDetails).length > 0) {
+    extraJSON.customGasChainDetails = customGasChainDetails;
+  }
+  const result = finalizeMultisign({
+    keyGen,
+    purposeText,
+    purposeSuffix: args.purposeSuffix,
+    destinationChainID: String(chainId),
+    destinationAddress: args.destinationAddress ?? steps[0].to,
+    legs,
+    extraJSON: Object.keys(extraJSON).length > 0 ? extraJSON : void 0
+  });
+  const pv = args.payableValueWei;
+  if (pv != null && pv > 0n) {
+    result.bodyForSign.value = pv.toString();
+  }
+  return result;
+}
+var erc20BalanceAbi = parseAbi(["function balanceOf(address account) view returns (uint256)"]);
+async function cctpAssertBurnPreconditions(args) {
+  if (!isCctpRouteSupported(args.sourceChainId, args.destChainId)) {
+    throw new Error("CCTP route is not supported for the selected source and destination chains.");
+  }
+  const src = cctpChainConfig(args.sourceChainId);
+  if (!src) throw new Error("Unsupported CCTP source chain.");
+  const transferAmount = parseUnits(args.transferAmountHuman.trim(), CCTP_USDC_DECIMALS);
+  if (transferAmount <= 0n) throw new Error("Transfer amount must be greater than zero.");
+  const totalBurn = transferAmount + args.maxFee;
+  const ch = defineChain({
+    id: args.sourceChainId,
+    name: src.label,
+    nativeCurrency: { decimals: 18, name: "Ether", symbol: "ETH" },
+    rpcUrls: { default: { http: [args.rpcUrl.trim()] } }
+  });
+  const client = createPublicClient({ chain: ch, transport: http(args.rpcUrl.trim()) });
+  const owner = getAddress(args.executorAddress);
+  const balance = await client.readContract({
+    address: getAddress(src.usdc),
+    abi: erc20BalanceAbi,
+    functionName: "balanceOf",
+    args: [owner]
+  });
+  if (balance < totalBurn) {
+    throw new Error(
+      `Insufficient USDC on source chain: need ${totalBurn.toString()} (transfer + maxFee), have ${balance.toString()}.`
+    );
+  }
+  return { transferAmount, totalBurn };
+}
+
+// src/protocols/evm/circle-cctp/multisign.ts
+var erc20ApproveAbi = parseAbi(["function approve(address spender, uint256 amount) returns (bool)"]);
+var tokenMessengerAbi = parseAbi([
+  "function depositForBurnWithHook(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold, bytes hookData)"
+]);
+function buildCctpBurnExtraJSON(args) {
+  return {
+    version: 1,
+    sourceChainId: args.sourceChainId,
+    sourceDomain: args.sourceDomain,
+    destDomain: args.destDomain,
+    destChainId: args.destChainId,
+    transferAmount: args.transferAmount.toString(),
+    mintRecipient: pad(args.mintRecipient, { size: 32 }),
+    burnToken: args.burnToken,
+    tokenMessenger: args.tokenMessenger,
+    useForwardingService: true,
+    forwardingHookData: FORWARDING_SERVICE_HOOK_DATA,
+    minFinalityThreshold: args.minFinalityThreshold,
+    proposalMaxFee: args.proposalMaxFee.toString(),
+    feeTier: args.feeTier
+  };
+}
+function buildCctpBurnSteps(args) {
+  const src = cctpChainConfig(args.sourceChainId);
+  const dst = cctpChainConfig(args.destChainId);
+  if (!src || !dst) throw new Error("Unsupported CCTP source or destination chain.");
+  const usdc = getAddress(src.usdc);
+  const tokenMessenger = getAddress(src.tokenMessenger);
+  const totalBurn = args.transferAmount + args.maxFee;
+  const mintRecipientBytes32 = pad(args.mintRecipient, { size: 32 });
+  const destinationCaller = pad("0x", { size: 32 });
+  const steps = [];
+  const allowance = args.currentAllowance ?? 0n;
+  if (allowance < totalBurn) {
+    if (allowance > 0n) {
+      steps.push({
+        kind: "approve",
+        to: usdc,
+        data: encodeFunctionData({ abi: erc20ApproveAbi, functionName: "approve", args: [tokenMessenger, 0n] }),
+        value: 0n,
+        fallbackGas: CCTP_ERC20_APPROVE_FALLBACK_GAS
+      });
+    }
+    steps.push({
+      kind: "approve",
+      to: usdc,
+      data: encodeFunctionData({
+        abi: erc20ApproveAbi,
+        functionName: "approve",
+        args: [tokenMessenger, totalBurn]
+      }),
+      value: 0n,
+      fallbackGas: CCTP_ERC20_APPROVE_FALLBACK_GAS
+    });
+  }
+  steps.push({
+    kind: "depositForBurnWithHook",
+    to: tokenMessenger,
+    data: encodeFunctionData({
+      abi: tokenMessengerAbi,
+      functionName: "depositForBurnWithHook",
+      args: [
+        totalBurn,
+        dst.domain,
+        mintRecipientBytes32,
+        usdc,
+        destinationCaller,
+        args.maxFee,
+        args.minFinalityThreshold,
+        FORWARDING_SERVICE_HOOK_DATA
+      ]
+    }),
+    value: 0n,
+    fallbackGas: CCTP_DEPOSIT_FOR_BURN_FALLBACK_GAS
+  });
+  return steps;
+}
+async function buildEvmMultisignBodyCctpBurnBatch(args) {
+  const src = cctpChainConfig(args.sourceChainId);
+  const dst = cctpChainConfig(args.destChainId);
+  if (!src || !dst) throw new Error("Unsupported CCTP source or destination chain.");
+  const executor = getAddress(args.executorAddress);
+  const mintRecipient = getAddress(args.mintRecipient ?? executor);
+  const minFinality = args.minFinalityThreshold ?? CCTP_DEFAULT_MIN_FINALITY_THRESHOLD;
+  let maxFee = args.maxFee;
+  let proposalMaxFee = args.proposalMaxFee ?? maxFee;
+  if (maxFee == null) {
+    const fees = await fetchCctpBurnFees({
+      sourceChainId: args.sourceChainId,
+      sourceDomain: src.domain,
+      destDomain: dst.domain,
+      feeTier: args.feeTier
+    });
+    maxFee = fees.maxFee;
+    proposalMaxFee = fees.maxFee;
+  } else if (proposalMaxFee == null) {
+    proposalMaxFee = maxFee;
+  }
+  const { transferAmount } = await cctpAssertBurnPreconditions({
+    sourceChainId: args.sourceChainId,
+    destChainId: args.destChainId,
+    transferAmountHuman: args.transferAmountHuman,
+    maxFee,
+    rpcUrl: args.rpcUrl,
+    executorAddress: executor
+  });
+  const steps = buildCctpBurnSteps({
+    sourceChainId: args.sourceChainId,
+    destChainId: args.destChainId,
+    mintRecipient,
+    transferAmount,
+    maxFee,
+    minFinalityThreshold: minFinality,
+    currentAllowance: 0n
+  });
+  const cctpBurn = buildCctpBurnExtraJSON({
+    sourceChainId: args.sourceChainId,
+    sourceDomain: src.domain,
+    destDomain: dst.domain,
+    destChainId: dst.chainId,
+    transferAmount,
+    mintRecipient,
+    burnToken: getAddress(src.usdc),
+    tokenMessenger: getAddress(src.tokenMessenger),
+    minFinalityThreshold: minFinality,
+    proposalMaxFee,
+    feeTier: args.feeTier ?? "med"
+  });
+  const transferHuman = args.transferAmountHuman.trim();
+  const totalBurn = transferAmount + maxFee;
+  const purposeSuffix = `CCTP (Forwarding Service): ${transferHuman} USDC ${src.label} \u2192 ${dst.label}.`;
+  const firstDataNo0x = steps[0].data.startsWith("0x") ? steps[0].data.slice(2) : steps[0].data;
+  const result = await buildEvmMultisignBatch({
+    context: {
+      chainCategory: "evm",
+      keyGen: args.keyGen,
+      purposeText: args.purposeText,
+      chainId: args.sourceChainId,
+      rpcUrl: args.rpcUrl,
+      executorAddress: executor,
+      chainDetail: args.chainDetail,
+      useCustomGas: args.useCustomGas,
+      customGasChainDetails: args.customGasChainDetails
+    },
+    steps,
+    purposeSuffix,
+    firstMsgRawNo0x: firstDataNo0x,
+    destinationAddress: steps[0].to,
+    buildBatchMeta: ({ step }) => {
+      const s = step;
+      if (s.kind === "approve") {
+        return {
+          signatureText: JSON.stringify({
+            kind: "CircleCCTP",
+            name: "USDC.approve",
+            spender: src.tokenMessenger,
+            amount: totalBurn.toString()
+          }),
+          evm: { type: "cctp_erc20_approve", version: 1, chainId: String(args.sourceChainId) }
+        };
+      }
+      return {
+        signatureText: JSON.stringify({
+          kind: "CircleCCTP",
+          name: "TokenMessengerV2.depositForBurnWithHook",
+          destDomain: dst.domain,
+          destChainId: dst.chainId,
+          mintRecipient,
+          transferAmount: transferAmount.toString(),
+          maxFee: maxFee.toString()
+        }),
+        evm: { type: "cctp_deposit_for_burn_forward", version: 1, chainId: String(args.sourceChainId) }
+      };
+    }
+  });
+  const body = result.bodyForSign;
+  const existingExtra = typeof body.extraJSON === "string" ? JSON.parse(body.extraJSON) : body.extraJSON ?? {};
+  body.extraJSON = JSON.stringify({ ...existingExtra, cctpBurn });
+  return result;
+}
+async function buildEvmMultisignBodyCctpBurnBatchFromMcp(args) {
+  let maxFee;
+  let proposalMaxFee;
+  if (args.feeSnapshot?.maxFee != null) {
+    maxFee = BigInt(String(args.feeSnapshot.maxFee));
+    proposalMaxFee = maxFee;
+  }
+  return buildEvmMultisignBodyCctpBurnBatch({
+    keyGen: args.keyGen,
+    sourceChainId: args.chainId,
+    destChainId: args.destChainId,
+    rpcUrl: args.rpcUrl,
+    chainDetail: args.chainDetail,
+    useCustomGas: args.useCustomGas,
+    customGasChainDetails: args.customGasChainDetails,
+    transferAmountHuman: args.transferAmountHuman,
+    mintRecipient: args.mintRecipient ? getAddress(args.mintRecipient) : void 0,
+    executorAddress: args.executorAddress,
+    purposeText: args.purposeText,
+    maxFee,
+    proposalMaxFee,
+    feeTier: args.feeTier,
+    minFinalityThreshold: args.minFinalityThreshold
+  });
+}
+
+// src/protocols/evm/circle-cctp/executeHelpers.ts
+function parseExtraJsonObject(detail) {
+  if (!detail) return null;
+  const raw = detail.ExtraJSON ?? detail.extraJSON;
+  if (raw == null) return null;
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
+  if (typeof raw === "string" && raw.trim()) {
+    try {
+      const p = JSON.parse(raw);
+      if (p && typeof p === "object" && !Array.isArray(p)) return p;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function parseCctpBurnExtraJSON(detail) {
+  const ex = parseExtraJsonObject(detail);
+  const raw = ex?.cctpBurn;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const c = raw;
+  if (c.useForwardingService !== true) return null;
+  const version = Number(c.version ?? 0);
+  if (version !== 1) return null;
+  return {
+    version: 1,
+    sourceChainId: Number(c.sourceChainId ?? 0),
+    sourceDomain: Number(c.sourceDomain),
+    destDomain: Number(c.destDomain),
+    destChainId: Number(c.destChainId),
+    transferAmount: String(c.transferAmount ?? ""),
+    mintRecipient: String(c.mintRecipient ?? ""),
+    burnToken: String(c.burnToken ?? ""),
+    tokenMessenger: String(c.tokenMessenger ?? ""),
+    useForwardingService: true,
+    forwardingHookData: String(c.forwardingHookData ?? FORWARDING_SERVICE_HOOK_DATA),
+    minFinalityThreshold: Number(c.minFinalityThreshold ?? 1e3),
+    proposalMaxFee: String(c.proposalMaxFee ?? "0"),
+    feeTier: c.feeTier === "low" || c.feeTier === "high" || c.feeTier === "med" ? c.feeTier : void 0
+  };
+}
+function isCctpBurnEvmSignRequest(detail, batchIndex) {
+  if (parseCctpBurnExtraJSON(detail)) return true;
+  const ex = parseExtraJsonObject(detail);
+  if (batchIndex != null && batchIndex >= 0 && ex) {
+    const bm = ex.batchMeta;
+    if (Array.isArray(bm) && bm[batchIndex] && typeof bm[batchIndex] === "object" && !Array.isArray(bm[batchIndex])) {
+      const evm0 = bm[batchIndex].evm;
+      if (evm0 && typeof evm0 === "object" && !Array.isArray(evm0)) {
+        const t2 = String(evm0.type ?? "");
+        return t2 === "cctp_deposit_for_burn_forward" || t2 === "cctp_erc20_approve";
+      }
+    }
+  }
+  const evm = ex?.evm;
+  if (!evm || typeof evm !== "object" || Array.isArray(evm)) return false;
+  const t = String(evm.type ?? "");
+  return t === "cctp_deposit_for_burn_forward";
+}
+function isCctpErc20ApproveEvmSignRequest(detail, batchIndex) {
+  const ex = parseExtraJsonObject(detail);
+  const index = batchIndex != null && batchIndex >= 0 ? batchIndex : 0;
+  const bm = ex?.batchMeta;
+  if (Array.isArray(bm) && bm[index] && typeof bm[index] === "object" && !Array.isArray(bm[index])) {
+    const evm0 = bm[index].evm;
+    if (evm0 && typeof evm0 === "object" && !Array.isArray(evm0)) {
+      return String(evm0.type ?? "") === "cctp_erc20_approve";
+    }
+  }
+  return false;
+}
+function resolveCctpBatchStepGasFromSignRequest(detail, batchIndex) {
+  const index = batchIndex != null && batchIndex >= 0 ? batchIndex : 0;
+  if (isCctpErc20ApproveEvmSignRequest(detail, index)) return CCTP_ERC20_APPROVE_FALLBACK_GAS;
+  if (isCctpBurnEvmSignRequest(detail, index)) return CCTP_DEPOSIT_FOR_BURN_FALLBACK_GAS;
+  return null;
+}
+function rebuildCctpBurnCalldataAtGetSig(args) {
+  const transferAmount = BigInt(args.cctpBurn.transferAmount);
+  const mintRecipient = cctpMintRecipientAddressFromExtra(args.cctpBurn);
+  const steps = buildCctpBurnSteps({
+    sourceChainId: args.cctpBurn.sourceChainId,
+    destChainId: args.cctpBurn.destChainId,
+    executorAddress: args.executorAddress,
+    mintRecipient,
+    transferAmount,
+    maxFee: args.freshMaxFee,
+    minFinalityThreshold: args.cctpBurn.minFinalityThreshold,
+    currentAllowance: args.forceApprove ? 0n : void 0
+  });
+  return steps.map((s) => ({ to: s.to, data: s.data }));
+}
+function cctpMintRecipientAddressFromExtra(cctpBurn) {
+  const hex = cctpBurn.mintRecipient.startsWith("0x") ? cctpBurn.mintRecipient.slice(2) : cctpBurn.mintRecipient;
+  return getAddress(`0x${hex.slice(-40)}`);
+}
+
+// src/protocols/evm/circle-cctp/reads.ts
+var erc20BalanceAbi2 = parseAbi(["function balanceOf(address account) view returns (uint256)"]);
+async function cctpFetchSupportedRoutes(args) {
+  return { routes: cctpSupportedRoutes(args?.network) };
+}
+function buildCctpMcpFeeFields(args) {
+  const { fees, transferAmount, transferAmountHuman } = args;
+  const maxFeeHuman = formatCctpUsdcHuman(fees.maxFee);
+  const forwardFeeLowHuman = formatCctpUsdcHuman(fees.forwardFeeLow);
+  const forwardFeeMedHuman = formatCctpUsdcHuman(fees.forwardFeeMed);
+  const forwardFeeHighHuman = formatCctpUsdcHuman(fees.forwardFeeHigh);
+  let totalBurn;
+  let totalBurnHuman;
+  if (transferAmount != null) {
+    totalBurn = transferAmount + fees.maxFee;
+    totalBurnHuman = formatCctpUsdcHuman(totalBurn);
+  }
+  const recipientPart = transferAmountHuman != null ? ` Recipient receives ${transferAmountHuman} USDC; wallet burns ${totalBurnHuman} USDC total (transfer + max fee).` : "";
+  const feeSummary = `Forwarding Service max fee (${fees.feeTierUsed} tier): ${maxFeeHuman} USDC.${recipientPart} Fee tiers \u2014 low: ${forwardFeeLowHuman}, med: ${forwardFeeMedHuman}, high: ${forwardFeeHighHuman} USDC. Fees refresh again at Get Sig.`;
+  return {
+    feeTierUsed: fees.feeTierUsed,
+    maxFee: fees.maxFee.toString(),
+    maxFeeHuman,
+    forwardFeeLow: fees.forwardFeeLow.toString(),
+    forwardFeeLowHuman,
+    forwardFeeMed: fees.forwardFeeMed.toString(),
+    forwardFeeMedHuman,
+    forwardFeeHigh: fees.forwardFeeHigh.toString(),
+    forwardFeeHighHuman,
+    ...transferAmount != null ? { transferAmount: transferAmount.toString() } : {},
+    ...transferAmountHuman != null ? { transferAmountHuman } : {},
+    ...totalBurn != null ? { totalBurn: totalBurn.toString() } : {},
+    ...totalBurnHuman != null ? { totalBurnHuman } : {},
+    feeSummary
+  };
+}
+function cctpFeeSummaryFromBodyForSign(bodyForSign) {
+  const cctpBurn = parseCctpBurnExtraJSON(bodyForSign);
+  if (!cctpBurn) return null;
+  const transferAmount = BigInt(cctpBurn.transferAmount);
+  const maxFee = BigInt(cctpBurn.proposalMaxFee);
+  const totalBurn = transferAmount + maxFee;
+  const transferAmountHuman = formatCctpUsdcHuman(transferAmount);
+  const maxFeeHuman = formatCctpUsdcHuman(maxFee);
+  const totalBurnHuman = formatCctpUsdcHuman(totalBurn);
+  const tier = cctpBurn.feeTier ?? "med";
+  const src = cctpChainConfig(cctpBurn.sourceChainId);
+  const dst = cctpChainConfig(cctpBurn.destChainId);
+  const routePart = src && dst ? ` Route: ${src.label} \u2192 ${dst.label}.` : "";
+  return {
+    feeTierUsed: tier,
+    maxFee: maxFee.toString(),
+    maxFeeHuman,
+    forwardFeeLow: maxFee.toString(),
+    forwardFeeLowHuman: maxFeeHuman,
+    forwardFeeMed: maxFee.toString(),
+    forwardFeeMedHuman: maxFeeHuman,
+    forwardFeeHigh: maxFee.toString(),
+    forwardFeeHighHuman: maxFeeHuman,
+    transferAmount: transferAmount.toString(),
+    transferAmountHuman,
+    totalBurn: totalBurn.toString(),
+    totalBurnHuman,
+    feeSummary: `Proposed CCTP burn.${routePart} Recipient receives ${transferAmountHuman} USDC; proposal max fee (${tier} tier): ${maxFeeHuman} USDC; total burn ${totalBurnHuman} USDC. Max fee refreshes at Get Sig.`
+  };
+}
+async function cctpFetchUsdcBalance(args) {
+  const cfg = cctpChainConfig(args.chainId);
+  if (!cfg) throw new Error(`Chain ${args.chainId} is not CCTP-supported.`);
+  const ch = defineChain({
+    id: args.chainId,
+    name: cfg.label,
+    nativeCurrency: { decimals: 18, name: "Ether", symbol: "ETH" },
+    rpcUrls: { default: { http: [args.rpcUrl.trim()] } }
+  });
+  const client = createPublicClient({ chain: ch, transport: http(args.rpcUrl.trim()) });
+  const owner = getAddress(args.executorAddress);
+  const balanceRaw = await client.readContract({
+    address: getAddress(cfg.usdc),
+    abi: erc20BalanceAbi2,
+    functionName: "balanceOf",
+    args: [owner]
+  });
+  const out = {
+    balanceRaw: balanceRaw.toString(),
+    balanceUsdcHuman: formatCctpUsdcHuman(balanceRaw),
+    usdcAddress: cfg.usdc
+  };
+  const transferHuman = args.transferAmountHuman?.trim();
+  const maxFeeRaw = args.feeSnapshot?.maxFee;
+  if (transferHuman && maxFeeRaw != null) {
+    const transferAmount = parseUnits(transferHuman, CCTP_USDC_DECIMALS);
+    const maxFee = BigInt(String(maxFeeRaw));
+    const totalRequired = transferAmount + maxFee;
+    out.requiredTotalBurnRaw = totalRequired.toString();
+    out.requiredTotalBurnHuman = formatCctpUsdcHuman(totalRequired);
+    out.sufficientForTransfer = balanceRaw >= totalRequired;
+    out.feeSummary = `Wallet holds ${out.balanceUsdcHuman} USDC; transfer requires ${formatCctpUsdcHuman(totalRequired)} USDC (${transferHuman} + ${formatCctpUsdcHuman(maxFee)} max fee).`;
+  }
+  return out;
+}
+async function cctpFetchTransferStatus(args) {
+  const base = irisApiBaseForChainId(args.sourceChainId);
+  const hash = args.burnTxHash.trim().replace(/^0x/, "");
+  const url = `${base}/v2/messages/${args.sourceDomain}?transactionHash=0x${hash}`;
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Iris message lookup failed (${res.status}): ${text.slice(0, 200)}`);
+  }
+  const json = await res.json();
+  const messages = json.messages ?? json.data ?? [];
+  const first = messages[0] ?? json;
+  return {
+    status: String(first.status ?? "unknown"),
+    attestation: typeof first.attestation === "string" ? first.attestation : void 0,
+    message: first.message,
+    eventNonce: first.eventNonce
+  };
+}
+async function cctpFetchBurnFeesForRoute(args) {
+  const src = cctpChainConfig(args.sourceChainId);
+  const dst = cctpChainConfig(args.destChainId);
+  if (!src || !dst) throw new Error("Unsupported source or destination chain for CCTP.");
+  if (src.network !== dst.network) throw new Error("Source and destination must be on the same network (mainnet or testnet).");
+  if (src.chainId === dst.chainId) throw new Error("Source and destination must differ.");
+  const fees = await fetchCctpBurnFees({
+    sourceChainId: args.sourceChainId,
+    sourceDomain: src.domain,
+    destDomain: dst.domain,
+    feeTier: args.feeTier
+  });
+  const transferHuman = args.transferAmountHuman?.trim();
+  const transferAmount = transferHuman ? parseUnits(transferHuman, CCTP_USDC_DECIMALS) : void 0;
+  const feeFields = buildCctpMcpFeeFields({
+    fees,
+    transferAmount,
+    transferAmountHuman: transferHuman || void 0
+  });
+  return {
+    sourceChainId: args.sourceChainId,
+    destChainId: args.destChainId,
+    sourceDomain: src.domain,
+    destDomain: dst.domain,
+    sourceLabel: src.label,
+    destLabel: dst.label,
+    network: src.network,
+    fees: feeFields,
+    ...feeFields
+  };
+}
+
+// src/protocols/evm/circle-cctp/index.ts
+var circleCctpProtocolModule = {
+  id: CIRCLE_CCTP_PROTOCOL_ID,
+  chainCategory: "evm",
+  isChainSupported(ctx) {
+    if (ctx.chainCategory !== "evm") return false;
+    return isCctpSourceChainSupported(ctx.chainId);
+  },
+  isTokenSupported(token) {
+    return token.category === "evm" && token.kind === "erc20";
+  },
+  actions: [
+    {
+      id: "circle-cctp.fetch-routes",
+      protocolId: CIRCLE_CCTP_PROTOCOL_ID,
+      chainCategory: "evm",
+      description: "List supported CCTP Forwarding Service routes (EVM)",
+      commonParams: [],
+      params: {
+        network: { type: "string", required: false, description: "mainnet | testnet" }
+      }
+    },
+    {
+      id: "circle-cctp.fetch-fees",
+      protocolId: CIRCLE_CCTP_PROTOCOL_ID,
+      chainCategory: "evm",
+      description: "Quote Iris Forwarding Service burn fees for a route",
+      commonParams: [],
+      params: {
+        sourceChainId: { type: "number", required: true, description: "Source EIP-155 chain id" },
+        destChainId: { type: "number", required: true, description: "Destination EIP-155 chain id" },
+        transferAmountHuman: { type: "string", required: true, description: "USDC amount recipient receives" }
+      }
+    },
+    {
+      id: "circle-cctp.burn-forward",
+      protocolId: CIRCLE_CCTP_PROTOCOL_ID,
+      chainCategory: "evm",
+      description: "Burn USDC on source chain via CCTP Forwarding Service (approve + depositForBurnWithHook batch)",
+      commonParams: ["keyGen", "purposeText", "useCustomGas"],
+      params: {
+        sourceChainId: { type: "number", required: true, description: "Source EIP-155 chain id" },
+        destChainId: { type: "number", required: true, description: "Destination EIP-155 chain id" },
+        transferAmountHuman: { type: "string", required: true, description: "USDC amount recipient receives" },
+        mintRecipient: { type: "address", required: false, description: "Destination mint recipient (default executor)" }
+      }
+    }
+  ]
+};
+registerProtocolModule(circleCctpProtocolModule);
+
+export { CCTP_DEFAULT_MIN_FINALITY_THRESHOLD, CCTP_DEPOSIT_FOR_BURN_FALLBACK_GAS, CCTP_ERC20_APPROVE_FALLBACK_GAS, CCTP_EVM_CHAINS, CCTP_USDC_DECIMALS, CIRCLE_CCTP_PROTOCOL_ID, FORWARDING_SERVICE_HOOK_DATA, IRIS_API_MAINNET, IRIS_API_SANDBOX, TOKEN_MESSENGER_V2_MAINNET, TOKEN_MESSENGER_V2_TESTNET, buildCctpBurnExtraJSON, buildCctpBurnSteps, buildEvmMultisignBodyCctpBurnBatch, buildEvmMultisignBodyCctpBurnBatchFromMcp, cctpAssertBurnPreconditions, cctpCanonicalUsdcAddress, cctpChainConfig, cctpFeeSummaryFromBodyForSign, cctpFetchBurnFeesForRoute, cctpFetchSupportedRoutes, cctpFetchTransferStatus, cctpFetchUsdcBalance, cctpMintRecipientAddressFromExtra, cctpSupportedRoutes, chainIdToDomain, circleCctpProtocolModule, domainToChainId, fetchCctpBurnFees, formatCctpUsdcHuman, irisApiBaseForChainId, isCctpBurnEvmSignRequest, isCctpCanonicalUsdcRow, isCctpErc20ApproveEvmSignRequest, isCctpRouteSupported, isCctpSourceChainSupported, parseCctpBurnExtraJSON, parseCctpEvmChainId, rebuildCctpBurnCalldataAtGetSig, resolveCctpBatchStepGasFromSignRequest };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map