@aptos-labs/cross-chain-core 5.8.2 → 6.0.0

package/src/providers/wormhole/wormhole.ts

@@ -1,7 +1,5 @@
 import {
-  chainToPlatform,
   routes,
-  TokenId,
   Wormhole,
   wormhole,
   PlatformLoader,
@@ -17,11 +15,15 @@ import {
   Chain,
   CrossChainProvider,
   CrossChainCore,
+  EVM_CHAIN_NAMES,
 } from "../../CrossChainCore";
 import { logger } from "../../utils/logger";
+import { serializeReceipt } from "../../utils/receiptSerialization";
 import { AptosLocalSigner } from "./signers/AptosLocalSigner";
+import { isAccount } from "./signers/AptosSigner";
 import { Signer } from "./signers/Signer";
 import { ChainConfig } from "../../config";
+import { createCCTPRoute } from "./utils";
 import {
   WormholeQuoteRequest,
   WormholeQuoteResponse,
@@ -34,6 +36,14 @@ import {
   WormholeClaimTransferRequest,
   WormholeWithdrawRequest,
   WormholeWithdrawResponse,
+  WormholeInitiateWithdrawRequest,
+  WormholeInitiateWithdrawResponse,
+  WormholeClaimWithdrawRequest,
+  WormholeClaimWithdrawResponse,
+  RetryWithdrawClaimRequest,
+  RetryWithdrawClaimResponse,
+  WithdrawError,
+  TransferError,
 } from "./types";
 import { SolanaDerivedWallet } from "@aptos-labs/derived-wallet-solana";
 import { EIP1193DerivedWallet } from "@aptos-labs/derived-wallet-ethereum";
@@ -54,6 +64,7 @@ export class WormholeProvider implements CrossChainProvider<
   private wormholeRoute: WormholeRouteResponse | undefined;
   private wormholeRequest: WormholeRequest | undefined;
   private wormholeQuote: WormholeQuoteResponse | undefined;
+  private destinationChain?: Chain;
 
   constructor(core: CrossChainCore) {
     this.crossChainCore = core;
@@ -74,16 +85,31 @@ export class WormholeProvider implements CrossChainProvider<
     const isMainnet = dappNetwork === Network.MAINNET;
     const platforms: PlatformLoader<any>[] = [aptos, solana, evm, sui];
 
-    // Get custom RPC endpoints from config
+    // RPC resolution order per chain:
+    //  1. User-provided config (solanaConfig / suiConfig / evmConfig)
+    //  2. Built-in defaultRpc from CHAINS config
+    const dappConfig = this.crossChainCore._dappConfig;
+    const chains = this.crossChainCore.CHAINS;
+
     const solanaRpc =
-      this.crossChainCore._dappConfig?.solanaConfig?.rpc ??
-      this.crossChainCore.CHAINS["Solana"]?.defaultRpc;
+      dappConfig?.solanaConfig?.rpc ?? chains["Solana"]?.defaultRpc;
+
+    const suiRpc = dappConfig?.suiConfig?.rpc ?? chains["Sui"]?.defaultRpc;
+
+    const evmChainsConfig: Record<string, { rpc: string }> = {};
+    for (const name of EVM_CHAIN_NAMES) {
+      const rpc =
+        dappConfig?.evmConfig?.[name]?.rpc ?? chains[name]?.defaultRpc;
+      if (rpc) {
+        evmChainsConfig[name] = { rpc };
+      }
+    }
 
     const wh = await wormhole(isMainnet ? "Mainnet" : "Testnet", platforms, {
       chains: {
-        Solana: {
-          rpc: solanaRpc,
-        },
+        ...(solanaRpc ? { Solana: { rpc: solanaRpc } } : {}),
+        ...(suiRpc ? { Sui: { rpc: suiRpc } } : {}),
+        ...evmChainsConfig,
       },
     });
     this._wormholeContext = wh;
@@ -100,43 +126,16 @@ export class WormholeProvider implements CrossChainProvider<
       throw new Error("Wormhole context not initialized");
     }
 
-    const { sourceToken, destToken } = this.getTokenInfo(
+    const { route: cctpRoute, request } = await createCCTPRoute(
+      this._wormholeContext,
       sourceChain,
       destinationChain,
+      this.crossChainCore.TOKENS,
     );
 
-    const destContext = this._wormholeContext
-      .getPlatform(chainToPlatform(destinationChain))
-      .getChain(destinationChain);
-    const sourceContext = this._wormholeContext
-      .getPlatform(chainToPlatform(sourceChain))
-      .getChain(sourceChain);
-
-    logger.log("sourceContext", sourceContext);
-    logger.log("sourceToken", sourceToken);
-
-    logger.log("destContext", destContext);
-    logger.log("destToken", destToken);
-
-    const request = await routes.RouteTransferRequest.create(
-      this._wormholeContext,
-      {
-        source: sourceToken,
-        destination: destToken,
-      },
-      sourceContext,
-      destContext,
-    );
-
-    const resolver = this._wormholeContext.resolver([
-      routes.CCTPRoute, // manual CCTP
-    ]);
-
-    const route = await resolver.findRoutes(request);
-    const cctpRoute = route[0];
-
     this.wormholeRoute = cctpRoute;
     this.wormholeRequest = request;
+    this.destinationChain = destinationChain;
 
     return { route: cctpRoute, request };
   }
@@ -168,12 +167,12 @@ export class WormholeProvider implements CrossChainProvider<
     const validated = await route.validate(request, transferParams);
     if (!validated.valid) {
       logger.log("invalid", validated.valid);
-      throw new Error(`Invalid quote: ${validated.error}`).message;
+      throw new Error(`Invalid quote: ${validated.error}`);
     }
     const quote = await route.quote(request, validated.params);
     if (!quote.success) {
       logger.log("quote failed", quote.success);
-      throw new Error(`Invalid quote: ${quote.error}`).message;
+      throw new Error(`Invalid quote: ${quote.error}`);
     }
     this.wormholeQuote = quote;
     logger.log("quote", quote);
@@ -183,7 +182,8 @@ export class WormholeProvider implements CrossChainProvider<
   async submitCCTPTransfer(
     input: WormholeSubmitTransferRequest,
   ): Promise<WormholeStartTransferResponse> {
-    const { sourceChain, wallet, destinationAddress } = input;
+    const { sourceChain, wallet, destinationAddress, onTransactionSigned } =
+      input;
 
     if (!this._wormholeContext) {
       await this.setWormholeContext(sourceChain);
@@ -222,6 +222,8 @@ export class WormholeProvider implements CrossChainProvider<
       {},
       wallet,
       this.crossChainCore,
+      undefined,
+      onTransactionSigned,
     );
 
     logger.log("signer", signer);
@@ -246,10 +248,18 @@ export class WormholeProvider implements CrossChainProvider<
   async claimCCTPTransfer(
     input: WormholeClaimTransferRequest,
   ): Promise<{ destinationChainTxnId: string }> {
-    let { receipt, mainSigner, sponsorAccount } = input;
+    let { receipt, mainSigner, sponsorAccount, onTransactionSigned } = input;
     if (!this.wormholeRoute) {
       throw new Error("Wormhole route not initialized");
     }
+    if (sponsorAccount && !isAccount(sponsorAccount)) {
+      throw new Error(
+        "AptosLocalSigner does not support GasStationApiKey as a sponsor account. " +
+          "Wormhole claim transactions are script-based and cannot be submitted " +
+          "via the gas station. Please provide an Account instance as the sponsor, " +
+          "or omit the sponsor account.",
+      );
+    }
 
     logger.log("mainSigner", mainSigner.accountAddress.toString());
 
@@ -269,7 +279,8 @@ export class WormholeProvider implements CrossChainProvider<
                 {},
                 mainSigner, // the account that signs the "claim" transaction
                 sponsorAccount, // the fee payer account
-                this.crossChainCore._dappConfig?.aptosNetwork,
+                this.crossChainCore,
+                onTransactionSigned,
               );
 
               if (routes.isManual(this.wormholeRoute)) {
@@ -325,26 +336,36 @@ export class WormholeProvider implements CrossChainProvider<
     // Submit transfer transaction from origin chain
     let { originChainTxnId, receipt } = await this.submitCCTPTransfer(input);
     // Claim transfer transaction on destination chain
-    const { destinationChainTxnId } = await this.claimCCTPTransfer({
-      receipt,
-      mainSigner: input.mainSigner,
-      sponsorAccount: input.sponsorAccount,
-    });
-    return { originChainTxnId, destinationChainTxnId };
+    try {
+      const { destinationChainTxnId } = await this.claimCCTPTransfer({
+        receipt,
+        mainSigner: input.mainSigner,
+        sponsorAccount: input.sponsorAccount,
+        onTransactionSigned: input.onTransactionSigned,
+      });
+      return { originChainTxnId, destinationChainTxnId };
+    } catch (error: any) {
+      throw new TransferError(
+        error?.message ?? "Transfer claim failed after source-chain burn",
+        originChainTxnId,
+        error,
+      );
+    }
   }
 
-  async withdraw(
-    input: WormholeWithdrawRequest,
-  ): Promise<WormholeWithdrawResponse> {
-    const { sourceChain, wallet, destinationAddress, sponsorAccount } = input;
-    logger.log("sourceChain", sourceChain);
-    logger.log("wallet", wallet);
-    logger.log("destinationAddress", destinationAddress);
-    logger.log("sponsorAccount", sponsorAccount);
+  // --- Split withdraw flow: initiateWithdraw + trackWithdraw + claimWithdraw ---
+
+  /**
+   * Phase 1: Initiates a withdraw by burning USDC on Aptos.
+   * The user signs the Aptos burn transaction via their wallet.
+   * Returns a receipt that can be tracked and later claimed.
+   */
+  async initiateWithdraw(
+    input: WormholeInitiateWithdrawRequest,
+  ): Promise<WormholeInitiateWithdrawResponse> {
+    const { wallet, destinationAddress, sponsorAccount, onTransactionSigned } =
+      input;
 
-    if (!this._wormholeContext) {
-      await this.setWormholeContext(sourceChain);
-    }
     if (!this._wormholeContext) {
       throw new Error("Wormhole context not initialized");
     }
@@ -354,96 +375,267 @@ export class WormholeProvider implements CrossChainProvider<
 
     const signer = new Signer(
       this.getChainConfig("Aptos"),
-      (
-        await input.wallet.features["aptos:account"].account()
-      ).address.toString(),
+      (await wallet.features["aptos:account"].account()).address.toString(),
       {},
-      input.wallet,
+      wallet,
       this.crossChainCore,
       sponsorAccount,
+      onTransactionSigned,
     );
 
-    logger.log("signer", signer);
-    logger.log("wormholeRequest", this.wormholeRequest);
-    logger.log("wormholeQuote", this.wormholeQuote);
-    logger.log(
-      "Wormhole.chainAddress",
-      Wormhole.chainAddress(sourceChain, input.destinationAddress.toString()),
+    const wormholeDestAddress = Wormhole.chainAddress(
+      this.destinationChain!,
+      destinationAddress.toString(),
     );
 
-    let receipt = await this.wormholeRoute.initiate(
+    const receipt = await this.wormholeRoute.initiate(
       this.wormholeRequest,
       signer,
       this.wormholeQuote,
-      Wormhole.chainAddress(sourceChain, input.destinationAddress.toString()),
+      wormholeDestAddress,
     );
-    logger.log("receipt", receipt);
+    logger.log("initiateWithdraw receipt", receipt);
 
     const originChainTxnId =
       "originTxs" in receipt
         ? receipt.originTxs[receipt.originTxs.length - 1].txid
         : undefined;
 
+    return { originChainTxnId: originChainTxnId || "", receipt };
+  }
+
+  /**
+   * Phase 2: Tracks a withdraw receipt until attestation is ready.
+   * This polls Wormhole and returns once the receipt reaches the Attested state.
+   */
+  async trackWithdraw(receipt: routes.Receipt): Promise<routes.Receipt> {
+    if (!this.wormholeRoute) {
+      throw new Error("Wormhole route not initialized");
+    }
+
     let retries = 0;
     const maxRetries = 5;
-    const baseDelay = 1000; // Initial delay of 1 second
+    const baseDelay = 1000;
 
     while (retries < maxRetries) {
       try {
         for await (receipt of this.wormholeRoute.track(receipt, 120 * 1000)) {
-          if (receipt.state >= TransferState.SourceInitiated) {
-            logger.log("Receipt is on track ", receipt);
-
-            try {
-              const signer = new Signer(
-                this.getChainConfig(sourceChain),
-                destinationAddress.toString(),
-                {},
-                wallet,
-                this.crossChainCore,
-              );
-
-              if (routes.isManual(this.wormholeRoute)) {
-                const circleAttestationReceipt =
-                  await this.wormholeRoute.complete(signer, receipt);
-                logger.log("Claim receipt: ", circleAttestationReceipt);
-
-                const destinationChainTxnId = signer.claimedTransactionHashes();
-                return {
-                  originChainTxnId: originChainTxnId || "",
-                  destinationChainTxnId,
-                };
-              } else {
-                // Should be unreachable
-                return {
-                  originChainTxnId: originChainTxnId || "",
-                  destinationChainTxnId: "",
-                };
-              }
-            } catch (e) {
-              console.error("Failed to claim", e);
-              return {
-                originChainTxnId: originChainTxnId || "",
-                destinationChainTxnId: "",
-              };
-            }
+          if (receipt.state >= TransferState.Attested) {
+            logger.log("trackWithdraw: receipt attested", receipt);
+            return receipt;
           }
         }
       } catch (e) {
         console.error(
-          `Error tracking transfer (attempt ${retries + 1} / ${maxRetries}):`,
+          `Error tracking withdraw (attempt ${retries + 1} / ${maxRetries}):`,
           e,
         );
-        const delay = baseDelay * Math.pow(2, retries); // Exponential backoff
+        const delay = baseDelay * Math.pow(2, retries);
         await sleep(delay);
         retries++;
       }
     }
+    throw new Error("Failed to track withdraw to attested state");
+  }
 
-    return {
-      originChainTxnId: originChainTxnId || "",
-      destinationChainTxnId: "",
-    };
+  /**
+   * Phase 3: Claims the withdraw on the destination chain.
+   *
+   * If the destination is Solana and `solanaConfig.serverClaimUrl` is configured
+   * in the dapp config, the SDK automatically POSTs the attested receipt to that
+   * URL — no wallet popup required. The dapp's server endpoint handles signing
+   * and submitting the claim transaction.
+   *
+   * Otherwise falls back to the wallet-based Signer (triggers wallet popup).
+   */
+  async claimWithdraw(
+    input: WormholeClaimWithdrawRequest,
+  ): Promise<WormholeClaimWithdrawResponse> {
+    const { claimChain, destinationAddress, receipt } = input;
+
+    // Server-side claim path: Solana destination with configured serverClaimUrl
+    const serverClaimUrl =
+      this.crossChainCore._dappConfig?.solanaConfig?.serverClaimUrl;
+
+    if (claimChain === "Solana" && serverClaimUrl) {
+      logger.log("claimWithdraw: using server-side claim via", serverClaimUrl);
+
+      const response = await fetch(serverClaimUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          receipt: serializeReceipt(receipt),
+          destinationAddress,
+          claimChain,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(
+          errorData.error ||
+            `Server-side claim failed with status ${response.status}`,
+        );
+      }
+
+      const result = await response.json();
+      return { destinationChainTxnId: result.destinationChainTxnId };
+    }
+
+    // Wallet-based claim path
+    if (!this.wormholeRoute) {
+      throw new Error("Wormhole route not initialized");
+    }
+
+    if (!input.wallet) {
+      throw new Error(
+        "Wallet is required for claim when serverClaimUrl is not configured",
+      );
+    }
+
+    const claimSigner = new Signer(
+      this.getChainConfig(claimChain),
+      destinationAddress,
+      {},
+      input.wallet,
+      this.crossChainCore,
+      undefined,
+      input.onTransactionSigned,
+      false,
+    );
+
+    if (routes.isManual(this.wormholeRoute)) {
+      const circleAttestationReceipt = await this.wormholeRoute.complete(
+        claimSigner,
+        receipt,
+      );
+      logger.log("claimWithdraw receipt:", circleAttestationReceipt);
+      const destinationChainTxnId = claimSigner.claimedTransactionHashes();
+      return { destinationChainTxnId };
+    } else {
+      throw new Error("Automatic route not supported for manual claim");
+    }
+  }
+
+  /**
+   * Withdraws USDC from Aptos to a destination chain.
+   * Orchestrates all three phases internally:
+   *   1. Initiate — user signs the Aptos burn transaction
+   *   2. Track — wait for Wormhole attestation
+   *   3. Claim — if serverClaimUrl is configured for Solana, delegates to
+   *      the server; otherwise uses the wallet-based signer.
+   *
+   * The optional `onPhaseChange` callback lets the dapp update its UI
+   * as the flow progresses.
+   */
+  async withdraw(
+    input: WormholeWithdrawRequest,
+  ): Promise<WormholeWithdrawResponse> {
+    const {
+      sourceChain,
+      wallet,
+      destinationAddress,
+      sponsorAccount,
+      onPhaseChange,
+      onTransactionSigned,
+    } = input;
+
+    // Phase 1: Initiate — user signs Aptos burn
+    onPhaseChange?.("initiating");
+    const { originChainTxnId, receipt } = await this.initiateWithdraw({
+      wallet,
+      destinationAddress,
+      sponsorAccount,
+      onTransactionSigned,
+    });
+
+    // Phases 2 & 3 are wrapped so that, if they fail, the caller still
+    // receives the originChainTxnId (the irreversible Aptos burn).
+    let currentPhase: "tracking" | "claiming" = "tracking";
+    try {
+      // Phase 2: Track — wait for attestation
+      onPhaseChange?.("tracking");
+      const attestedReceipt = await this.trackWithdraw(receipt);
+
+      // Phase 3: Claim — server-side or wallet-based
+      currentPhase = "claiming";
+      onPhaseChange?.("claiming");
+      const { destinationChainTxnId } = await this.claimWithdraw({
+        claimChain: sourceChain,
+        destinationAddress: destinationAddress.toString(),
+        receipt: attestedReceipt,
+        wallet,
+        onTransactionSigned,
+      });
+
+      return { originChainTxnId, destinationChainTxnId };
+    } catch (error: any) {
+      throw new WithdrawError(
+        error?.message ?? "Withdraw failed after Aptos burn",
+        originChainTxnId,
+        currentPhase,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Retries a failed `claimWithdraw` call with configurable exponential backoff.
+   *
+   * Use this when the claim phase of a withdrawal fails (e.g., RPC instability,
+   * network congestion) but the Aptos burn transaction has already been submitted.
+   * The attested receipt can be recovered from the `WithdrawError` thrown by
+   * `withdraw()` and passed directly to this method.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await provider.withdraw({ ... });
+   * } catch (error) {
+   *   if (error instanceof WithdrawError && error.phase === "claiming") {
+   *     const result = await provider.retryWithdrawClaim({
+   *       sourceChain,
+   *       destinationAddress,
+   *       receipt: attestedReceipt,
+   *       wallet,
+   *       maxRetries: 5,
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  async retryWithdrawClaim(
+    input: RetryWithdrawClaimRequest,
+  ): Promise<RetryWithdrawClaimResponse> {
+    const {
+      maxRetries = 5,
+      initialDelayMs = 2000,
+      backoffMultiplier = 2,
+      ...claimInput
+    } = input;
+
+    let lastError: Error | undefined;
+    let delay = initialDelayMs;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const result = await this.claimWithdraw(claimInput);
+        return { ...result, retriesUsed: attempt };
+      } catch (error) {
+        lastError = error as Error;
+        logger.log(
+          `retryWithdrawClaim: attempt ${attempt + 1}/${maxRetries + 1} failed: ${lastError.message}`,
+        );
+        if (attempt < maxRetries) {
+          await sleep(delay);
+          delay *= backoffMultiplier;
+        }
+      }
+    }
+
+    throw new Error(
+      `Claim failed after ${maxRetries + 1} attempts: ${lastError?.message}`,
+    );
   }
 
   getChainConfig(chain: Chain): ChainConfig {
@@ -456,24 +648,4 @@ export class WormholeProvider implements CrossChainProvider<
     }
     return chainConfig;
   }
-
-  getTokenInfo(
-    sourceChain: Chain,
-    destinationChain: Chain,
-  ): {
-    sourceToken: TokenId;
-    destToken: TokenId;
-  } {
-    const sourceToken: TokenId = Wormhole.tokenId(
-      this.crossChainCore.TOKENS[sourceChain].tokenId.chain as Chain,
-      this.crossChainCore.TOKENS[sourceChain].tokenId.address,
-    );
-
-    const destToken: TokenId = Wormhole.tokenId(
-      this.crossChainCore.TOKENS[destinationChain].tokenId.chain as Chain,
-      this.crossChainCore.TOKENS[destinationChain].tokenId.address,
-    );
-
-    return { sourceToken, destToken };
-  }
 }