feat: enable burn/mint (#2002)

Author: dohaki

api/_bridges/cctp/strategy.ts

@@ -1,4 +1,4 @@
-import { BigNumber, ethers, utils } from "ethers";
+import { BigNumber, utils } from "ethers";
 import * as sdk from "@across-protocol/sdk";
 import { TokenMessengerMinterV2Client } from "@across-protocol/contracts";
 import {
@@ -18,9 +18,8 @@ import {
   BridgeCapabilities,
   GetOutputBridgeQuoteParams,
 } from "../types";
-import { CrossSwap, CrossSwapQuotes } from "../../_dexes/types";
+import { CrossSwap, CrossSwapQuotes, Token } from "../../_dexes/types";
 import { AppFee, CROSS_SWAP_TYPE } from "../../_dexes/utils";
-import { Token } from "../../_dexes/types";
 import { InvalidParamError } from "../../_errors";
 import { ConvertDecimals } from "../../_utils";
 import {
@@ -34,12 +33,14 @@ import {
   CCTP_SUPPORTED_CHAINS,
   CCTP_SUPPORTED_TOKENS,
   CCTP_FINALITY_THRESHOLDS,
-  CCTP_FILL_TIME_ESTIMATES,
+  DEFAULT_CCTP_ACROSS_FINALIZER_ADDRESS,
   getCctpTokenMessengerAddress,
   getCctpMessageTransmitterAddress,
   getCctpDomainId,
   encodeDepositForBurn,
 } from "./utils/constants";
+import { getEstimatedFillTime, getTransferMode } from "./utils/fill-times";
+import { getCctpFees } from "./utils/fees";
 
 const name = "cctp";
 
@@ -59,12 +60,9 @@ const capabilities: BridgeCapabilities = {
  * CCTP (Cross-Chain Transfer Protocol) bridge strategy for native USDC transfers.
  * Supports Circle's CCTP for burning USDC on source chain.
  */
-export function getCctpBridgeStrategy(): BridgeStrategy {
-  const getEstimatedFillTime = (originChainId: number): number => {
-    // CCTP fill time is determined by the origin chain attestation process
-    return CCTP_FILL_TIME_ESTIMATES[originChainId] || 19 * 60; // Default to 19 minutes
-  };
-
+export function getCctpBridgeStrategy(
+  requestedTransferMode: "standard" | "fast" = "fast"
+): BridgeStrategy {
   const isRouteSupported = (params: {
     inputToken: Token;
     outputToken: Token;
@@ -91,7 +89,12 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
     const isDestinationChainSupported = CCTP_SUPPORTED_CHAINS.includes(
       params.outputToken.chainId
     );
-    if (!isOriginChainSupported || !isDestinationChainSupported) {
+    if (
+      !isOriginChainSupported ||
+      !isDestinationChainSupported ||
+      // NOTE: Our finalizer doesn't support destination Solana yet. Block the route until we do.
+      sdk.utils.chainIsSvm(params.outputToken.chainId)
+    ) {
       return false;
     }
 
@@ -149,10 +152,33 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
     }: GetExactInputBridgeQuoteParams) => {
       assertSupportedRoute({ inputToken, outputToken });
 
+      let maxFee = BigNumber.from(0);
+      const transferMode = await getTransferMode(
+        inputToken.chainId,
+        requestedTransferMode,
+        exactInputAmount,
+        inputToken.decimals
+      );
+
+      if (transferMode === "fast") {
+        const { transferFeeBps, forwardFee } = await getCctpFees({
+          inputToken,
+          outputToken,
+          transferMode,
+        });
+
+        // Calculate actual fee:
+        // transferFee = input * (bps / 10000)
+        // maxFee = transferFee + forwardFee
+        const transferFee = exactInputAmount.mul(transferFeeBps).div(10000);
+        maxFee = transferFee.add(forwardFee);
+      }
+
+      const remainingInputAmount = exactInputAmount.sub(maxFee);
       const outputAmount = ConvertDecimals(
         inputToken.decimals,
         outputToken.decimals
-      )(exactInputAmount);
+      )(remainingInputAmount);
 
       return {
         bridgeQuote: {
@@ -161,9 +187,16 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
           inputAmount: exactInputAmount,
           outputAmount,
           minOutputAmount: outputAmount,
-          estimatedFillTimeSec: getEstimatedFillTime(inputToken.chainId),
+          estimatedFillTimeSec: getEstimatedFillTime(
+            inputToken.chainId,
+            transferMode
+          ),
           provider: name,
-          fees: getCctpBridgeFees(inputToken),
+          fees: getCctpBridgeFees({
+            inputToken,
+            inputAmount: exactInputAmount,
+            maxFee,
+          }),
         },
       };
     },
@@ -178,10 +211,38 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
     }: GetOutputBridgeQuoteParams) => {
       assertSupportedRoute({ inputToken, outputToken });
 
-      const inputAmount = ConvertDecimals(
+      let inputAmount = ConvertDecimals(
         outputToken.decimals,
         inputToken.decimals
       )(minOutputAmount);
+      let maxFee = BigNumber.from(0);
+
+      const transferMode = await getTransferMode(
+        inputToken.chainId,
+        requestedTransferMode,
+        inputAmount,
+        inputToken.decimals
+      );
+
+      if (transferMode === "fast") {
+        const { transferFeeBps, forwardFee } = await getCctpFees({
+          inputToken,
+          outputToken,
+          transferMode,
+        });
+
+        // Solve for required input based on the following equation:
+        // inputAmount - (inputAmount * bps / 10000) - forwardFee = amountToArriveOnDestination
+        // Rearranging: inputAmount * (1 - bps/10000) = amountToArriveOnDestination + forwardFee
+        // Therefore: inputAmount = (amountToArriveOnDestination + forwardFee) * 10000 / (10000 - bps)
+        // Note: 10000 converts basis points to the same scale as amounts (1 bps = 1/10000 of the total)
+        const bpsFactor = BigNumber.from(10000).sub(transferFeeBps);
+        inputAmount = inputAmount.add(forwardFee).mul(10000).div(bpsFactor);
+
+        // Calculate total CCTP fee (transfer fee + forward fee)
+        const transferFee = inputAmount.mul(transferFeeBps).div(10000);
+        maxFee = transferFee.add(forwardFee);
+      }
 
       return {
         bridgeQuote: {
@@ -190,9 +251,16 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
           inputAmount,
           outputAmount: minOutputAmount,
           minOutputAmount,
-          estimatedFillTimeSec: getEstimatedFillTime(inputToken.chainId),
+          estimatedFillTimeSec: getEstimatedFillTime(
+            inputToken.chainId,
+            transferMode
+          ),
           provider: name,
-          fees: getCctpBridgeFees(inputToken),
+          fees: getCctpBridgeFees({
+            inputToken,
+            inputAmount,
+            maxFee,
+          }),
         },
       };
     },
@@ -227,15 +295,23 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
       const destinationChainId = crossSwap.outputToken.chainId;
       const destinationDomain = getCctpDomainId(destinationChainId);
       const tokenMessenger = getCctpTokenMessengerAddress(originChainId);
+      // Circle's API returns a minimum fee. Add 1 unit as buffer to ensure the transfer meets the threshold for fast mode eligibility.
+      const hasFastFee = bridgeQuote.fees.amount.gt(0);
+      const maxFee = hasFastFee
+        ? bridgeQuote.fees.amount.add(1)
+        : bridgeQuote.fees.amount;
+      const minFinalityThreshold = hasFastFee
+        ? CCTP_FINALITY_THRESHOLDS.fast
+        : CCTP_FINALITY_THRESHOLDS.standard;
 
       // depositForBurn input parameters
       const depositForBurnParams = {
         amount: bridgeQuote.inputAmount,
         destinationDomain,
         mintRecipient: crossSwap.recipient,
-        destinationCaller: ethers.constants.AddressZero, // Anyone can finalize the message on domain when this is set to bytes32(0)
-        maxFee: BigNumber.from(0), // maxFee set to 0 so this will be a "standard" speed transfer
-        minFinalityThreshold: CCTP_FINALITY_THRESHOLDS.standard, // Hardcoded minFinalityThreshold value for standard transfer
+        destinationCaller: DEFAULT_CCTP_ACROSS_FINALIZER_ADDRESS,
+        maxFee,
+        minFinalityThreshold,
       };
 
       if (crossSwap.isOriginSvm) {
@@ -263,15 +339,19 @@ export function getCctpBridgeStrategy(): BridgeStrategy {
   };
 }
 
-function getCctpBridgeFees(inputToken: Token) {
-  const zeroBN = BigNumber.from(0);
+function getCctpBridgeFees(params: {
+  inputToken: Token;
+  inputAmount: BigNumber;
+  maxFee?: BigNumber;
+}) {
+  const { inputToken, inputAmount, maxFee = BigNumber.from(0) } = params;
+  const pct = maxFee.mul(sdk.utils.fixedPointAdjustment).div(inputAmount);
   return {
-    pct: zeroBN,
-    amount: zeroBN,
+    pct,
+    amount: maxFee,
     token: inputToken,
   };
 }
-
 /**
  * Builds CCTP deposit transaction for EVM chains
  */

api/_bridges/cctp/utils/constants.ts

@@ -9,7 +9,8 @@ export const CCTP_SUPPORTED_CHAINS = [
   CHAIN_IDs.ARBITRUM,
   CHAIN_IDs.BASE,
   CHAIN_IDs.HYPEREVM,
-  CHAIN_IDs.INK,
+  CHAIN_IDs.LINEA,
+  CHAIN_IDs.MONAD,
   CHAIN_IDs.OPTIMISM,
   CHAIN_IDs.POLYGON,
   CHAIN_IDs.SOLANA,
@@ -34,6 +35,10 @@ export const CCTP_FINALITY_THRESHOLDS = {
   standard: 2000,
 };
 
+// CCTP Across Finalizer address
+export const DEFAULT_CCTP_ACROSS_FINALIZER_ADDRESS =
+  "0x72adB07A487f38321b6665c02D289C413610B081";
+
 // CCTP TokenMessenger contract addresses
 // Source: https://developers.circle.com/cctp/evm-smart-contracts
 const DEFAULT_CCTP_TOKEN_MESSENGER_ADDRESS =
@@ -133,18 +138,3 @@ export const encodeDepositForBurn = (params: {
     params.minFinalityThreshold,
   ]);
 };
-
-// CCTP estimated fill times in seconds
-// Soruce: https://developers.circle.com/cctp/required-block-confirmations
-export const CCTP_FILL_TIME_ESTIMATES: Record<number, number> = {
-  [CHAIN_IDs.MAINNET]: 19 * 60,
-  [CHAIN_IDs.ARBITRUM]: 19 * 60,
-  [CHAIN_IDs.BASE]: 19 * 60,
-  [CHAIN_IDs.HYPEREVM]: 5,
-  [CHAIN_IDs.INK]: 30 * 60,
-  [CHAIN_IDs.OPTIMISM]: 19 * 60,
-  [CHAIN_IDs.POLYGON]: 8,
-  [CHAIN_IDs.SOLANA]: 25,
-  [CHAIN_IDs.UNICHAIN]: 19 * 60,
-  [CHAIN_IDs.WORLD_CHAIN]: 19 * 60,
-};

api/_bridges/cctp/utils/fees.ts

@@ -0,0 +1,81 @@
+import { BigNumber } from "ethers";
+import axios from "axios";
+
+import { CCTP_FINALITY_THRESHOLDS, getCctpDomainId } from "./constants";
+import { Token } from "../../../_dexes/types";
+
+/**
+ * CCTP fee configuration type from Circle API
+ */
+type CctpFeeConfig = {
+  finalityThreshold: number;
+  minimumFee: number; // in bps
+  forwardFee: {
+    low: number; // in token units
+    med: number;
+    high: number;
+  };
+};
+
+/**
+ * Queries Circle API to fetch CCTP fees for the specified finality threshold.
+ *
+ * Transfer fee: Variable fee in basis points of the transfer amount, collected at minting time.
+ * - 0 bps for standard transfers (finality threshold > 1000)
+ * - Varies by origin chain for fast transfers (finality threshold ≤ 1000)
+ * - See: https://developers.circle.com/cctp/technical-guide#fees
+ *
+ * Forward fee: Fixed fee in token units charged when routing through CCTP forwarder (e.g., to HyperCore).
+ * - Applies only to forwarded transfers via depositForBurnWithHook
+ * - Returned in token decimals (e.g., 6 decimals for USDC)
+ *
+ * @param params.inputToken - Input token with chainId
+ * @param params.outputToken - Output token with chainId
+ * @param params.transferMode - Transfer mode: "standard" or "fast"
+ * @param params.useSandbox - Whether to use the sandbox environment
+ * @param params.useForwardFee - Whether to use the forward fee
+ * @returns transferFeeBps (basis points) and forwardFee (in token units)
+ */
+export async function getCctpFees(params: {
+  inputToken: Token;
+  outputToken: Token;
+  transferMode: "standard" | "fast";
+  useSandbox?: boolean;
+  useForwardFee?: boolean;
+}): Promise<{
+  transferFeeBps: number;
+  forwardFee: BigNumber;
+}> {
+  const { inputToken, outputToken, transferMode, useSandbox, useForwardFee } =
+    params;
+
+  // Get CCTP domain IDs
+  const sourceDomainId = getCctpDomainId(inputToken.chainId);
+  const destDomainId = getCctpDomainId(outputToken.chainId);
+
+  const endpoint = useSandbox ? "iris-api-sandbox" : "iris-api";
+  const url = `https://${endpoint}.circle.com/v2/burn/USDC/fees/${sourceDomainId}/${destDomainId}`;
+  const response = await axios.get<CctpFeeConfig[]>(url, {
+    params: useForwardFee ? { forward: true } : undefined,
+  });
+
+  const finalityThreshold = CCTP_FINALITY_THRESHOLDS[transferMode];
+
+  // Find config matching the requested finality threshold
+  const transferConfig = response.data.find(
+    (config) => config.finalityThreshold === finalityThreshold
+  );
+
+  if (!transferConfig) {
+    throw new Error(
+      `Fee configuration not found for finality threshold ${finalityThreshold} in CCTP fee response`
+    );
+  }
+
+  const forwardFee = useForwardFee ? transferConfig.forwardFee.med : 0;
+
+  return {
+    transferFeeBps: transferConfig.minimumFee,
+    forwardFee: BigNumber.from(forwardFee),
+  };
+}