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

package/src/providers/wormhole/signers/solanaUtils.ts

@@ -0,0 +1,446 @@
+/**
+ * Shared utilities for Solana transaction handling.
+ * Used by both SolanaLocalSigner (server-side) and SolanaSigner (client-side).
+ */
+
+import {
+  ComputeBudgetProgram,
+  Connection,
+  LAMPORTS_PER_SOL,
+  RpcResponseAndContext,
+  SignatureResult,
+  SimulatedTransactionResponse,
+  Transaction,
+  TransactionInstruction,
+  VersionedTransaction,
+  type Commitment,
+} from "@solana/web3.js";
+import {
+  determinePriorityFee,
+  determinePriorityFeeTritonOne,
+} from "@wormhole-foundation/sdk-solana";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Configuration for priority fees */
+export interface PriorityFeeConfig {
+  /** Percentile of recent fees to use (default: 0.9) */
+  percentile?: number;
+  /** Multiplier for the percentile fee (default: 1) */
+  percentileMultiple?: number;
+  /** Minimum fee in microlamports (default: 100_000) */
+  min?: number;
+  /** Maximum fee in microlamports (default: 100_000_000) */
+  max?: number;
+}
+
+/** Configuration for sending and confirming transactions */
+export interface SendAndConfirmConfig {
+  connection: Connection;
+  commitment: Commitment;
+  retryIntervalMs?: number;
+  /** Enable verbose logging (default: false) */
+  verbose?: boolean;
+}
+
+/** RPC provider type for priority fee calculation */
+export type SolanaRpcProvider = "triton" | "helius" | "ankr" | "unknown";
+
+// ============================================================================
+// Transaction Confirmation
+// ============================================================================
+
+/**
+ * Sends a serialized transaction and waits for confirmation with automatic retries.
+ *
+ * @param serializedTx - The serialized transaction bytes
+ * @param blockhash - The recent blockhash used in the transaction
+ * @param lastValidBlockHeight - The last valid block height for the transaction
+ * @param config - Configuration for sending and confirming
+ * @returns The transaction signature
+ */
+export async function sendAndConfirmTransaction(
+  serializedTx: Buffer | Uint8Array,
+  blockhash: string,
+  lastValidBlockHeight: number,
+  config: SendAndConfirmConfig,
+): Promise<string> {
+  const { connection, commitment, retryIntervalMs = 5000, verbose = false } = config;
+
+  const sendOptions = {
+    skipPreflight: true,
+    maxRetries: 0,
+    preflightCommitment: commitment,
+  };
+
+  const signature = await connection.sendRawTransaction(serializedTx, sendOptions);
+
+  const confirmTransactionPromise = connection.confirmTransaction(
+    { signature, blockhash, lastValidBlockHeight },
+    commitment,
+  );
+
+  // Retry loop: resend if not confirmed after interval.
+  // The confirmation promise can reject with "block height exceeded" when the
+  // blockhash expires before confirmation completes. Because the transaction was
+  // already sent (sendRawTransaction succeeded), it may still land on-chain.
+  // In that case we return the signature so the caller can track it, rather than
+  // throwing and losing the transaction reference.
+  let confirmedTx: RpcResponseAndContext<SignatureResult> | null = null;
+  let txSendAttempts = 1;
+
+  try {
+    while (!confirmedTx) {
+      confirmedTx = await Promise.race([
+        confirmTransactionPromise,
+        new Promise<null>((resolve) =>
+          setTimeout(() => resolve(null), retryIntervalMs),
+        ),
+      ]);
+
+      if (confirmedTx) break;
+
+      if (verbose) {
+        console.log(
+          `Tx not confirmed after ${retryIntervalMs * txSendAttempts++}ms, resending`,
+        );
+      }
+
+      try {
+        await connection.sendRawTransaction(serializedTx, sendOptions);
+      } catch (e) {
+        if (verbose) {
+          console.error("Failed to resend transaction:", e);
+        }
+        // Ignore resend errors, confirmation will handle success/failure
+      }
+    }
+  } catch (e) {
+    const message = e instanceof Error ? e.message.toLowerCase() : "";
+    if (
+      message.includes("block height exceeded") ||
+      message.includes("blockheightexceeded")
+    ) {
+      if (verbose) {
+        console.warn(
+          "Block height exceeded but tx was already sent, returning signature:",
+          signature,
+        );
+      }
+      // Transaction was already sent — return the signature so the caller can
+      // track confirmation asynchronously instead of losing the tx reference.
+      return signature;
+    }
+    throw e;
+  }
+
+  if (confirmedTx.value.err) {
+    const errorMessage = formatTransactionError(confirmedTx.value.err);
+    throw new Error(errorMessage);
+  }
+
+  return signature;
+}
+
+/**
+ * Formats a transaction error into a readable string.
+ */
+export function formatTransactionError(err: unknown): string {
+  if (typeof err === "object" && err !== null) {
+    try {
+      return `Transaction failed: ${JSON.stringify(
+        err,
+        (_key, value) => (typeof value === "bigint" ? value.toString() : value),
+      )}`;
+    } catch {
+      // Circular reference or other stringify error
+      return "Transaction failed: Unknown error";
+    }
+  }
+  return `Transaction failed: ${err}`;
+}
+
+// ============================================================================
+// Priority Fees
+// ============================================================================
+
+/**
+ * Adds priority fee instructions to a transaction.
+ * Simulates the transaction to determine compute units and calculates optimal fees.
+ *
+ * @param connection - Solana RPC connection
+ * @param transaction - The transaction to add priority fees to
+ * @param priorityFeeConfig - Configuration for priority fees
+ * @param verbose - Enable verbose logging
+ * @returns The transaction with priority fee instructions added
+ */
+export async function addPriorityFeeInstructions(
+  connection: Connection,
+  transaction: Transaction,
+  priorityFeeConfig?: PriorityFeeConfig,
+  verbose: boolean = false,
+): Promise<Transaction> {
+  const computeBudgetIxFilter = (ix: TransactionInstruction) =>
+    ix.programId.toString() !== "ComputeBudget111111111111111111111111111111";
+
+  // Remove existing compute budget instructions if they were added by the SDK
+  transaction.instructions = transaction.instructions.filter(computeBudgetIxFilter);
+
+  const instructions = await createPriorityFeeInstructions(
+    connection,
+    transaction,
+    priorityFeeConfig,
+    verbose,
+  );
+
+  transaction.add(...instructions);
+
+  return transaction;
+}
+
+/**
+ * Creates priority fee instructions based on simulation and fee estimation.
+ */
+export async function createPriorityFeeInstructions(
+  connection: Connection,
+  transaction: Transaction | VersionedTransaction,
+  priorityFeeConfig?: PriorityFeeConfig,
+  verbose: boolean = false,
+): Promise<TransactionInstruction[]> {
+  // Simulate to get compute units
+  const unitsUsed = await simulateAndGetComputeUnits(connection, transaction);
+  const unitBudget = Math.floor(unitsUsed * 1.2); // Budget in 20% headroom
+
+  const instructions: TransactionInstruction[] = [];
+  instructions.push(
+    ComputeBudgetProgram.setComputeUnitLimit({
+      units: unitBudget,
+    }),
+  );
+
+  // Calculate priority fee
+  const {
+    percentile = 0.9,
+    percentileMultiple = 1,
+    min = 100_000,
+    max = 100_000_000,
+  } = priorityFeeConfig ?? {};
+
+  const rpcProvider = determineRpcProvider(connection.rpcEndpoint);
+  const { fee, methodUsed } = await calculatePriorityFee(
+    connection,
+    transaction,
+    rpcProvider,
+    { percentile, percentileMultiple, min, max },
+  );
+
+  if (verbose) {
+    const maxFeeInSol = (fee / 1e6 / LAMPORTS_PER_SOL) * unitBudget;
+    console.table({
+      "RPC Provider": rpcProvider,
+      "Method used": methodUsed,
+      "Percentile used": percentile,
+      "Multiple used": percentileMultiple,
+      "Compute budget": unitBudget,
+      "Priority fee": fee,
+      "Max fee in SOL": maxFeeInSol,
+    });
+  }
+
+  instructions.push(
+    ComputeBudgetProgram.setComputeUnitPrice({ microLamports: fee }),
+  );
+
+  return instructions;
+}
+
+/**
+ * Simulates a transaction and returns the compute units consumed.
+ */
+async function simulateAndGetComputeUnits(
+  connection: Connection,
+  transaction: Transaction | VersionedTransaction,
+): Promise<number> {
+  let unitsUsed = 200_000;
+  let simulationAttempts = 0;
+
+  simulationLoop: while (true) {
+    const response = await connection.simulateTransaction(transaction as Transaction);
+
+    if (response.value.err) {
+      if (checkKnownSimulationError(response.value)) {
+        // Number of attempts will be at most 5 for known errors
+        if (simulationAttempts < 5) {
+          simulationAttempts++;
+          await sleep(1000);
+          continue simulationLoop;
+        }
+      } else if (simulationAttempts < 3) {
+        // Number of attempts will be at most 3 for unknown errors
+        simulationAttempts++;
+        await sleep(1000);
+        continue simulationLoop;
+      }
+
+      // Still failing after multiple attempts
+      throw new Error(
+        `Simulation failed: ${JSON.stringify(response.value.err)}\nLogs:\n${(
+          response.value.logs || []
+        ).join("\n  ")}`,
+      );
+    } else {
+      // Simulation was successful
+      if (response.value.unitsConsumed) {
+        unitsUsed = response.value.unitsConsumed;
+      }
+      break;
+    }
+  }
+
+  return unitsUsed;
+}
+
+/**
+ * Calculates the priority fee based on RPC provider and configuration.
+ */
+async function calculatePriorityFee(
+  connection: Connection,
+  transaction: Transaction | VersionedTransaction,
+  rpcProvider: SolanaRpcProvider,
+  config: Required<PriorityFeeConfig>,
+): Promise<{ fee: number; methodUsed: "triton" | "default" | "minimum" }> {
+  const { percentile, percentileMultiple, min, max } = config;
+
+  if (rpcProvider === "triton") {
+    // Triton has an experimental RPC method that accepts a percentile parameter
+    // and usually gives more accurate fee numbers.
+    try {
+      const fee = await determinePriorityFeeTritonOne(
+        connection,
+        transaction,
+        percentile,
+        percentileMultiple,
+        min,
+        max,
+      );
+
+      return { fee, methodUsed: "triton" };
+    } catch (e) {
+      console.warn(`Failed to determine priority fee using Triton RPC:`, e);
+    }
+  }
+
+  try {
+    // By default, use generic Solana RPC method
+    const fee = await determinePriorityFee(
+      connection,
+      transaction,
+      percentile,
+      percentileMultiple,
+      min,
+      max,
+    );
+
+    return { fee, methodUsed: "default" };
+  } catch (e) {
+    console.warn(`Failed to determine priority fee:`, e);
+
+    return { fee: min, methodUsed: "minimum" };
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Checks response logs for known simulation errors that can be retried.
+ */
+function checkKnownSimulationError(response: SimulatedTransactionResponse): boolean {
+  const errors: Record<string, string> = {};
+
+  // This error occurs when the blockhash included in a transaction is not deemed to be valid
+  if (response.err === "BlockhashNotFound") {
+    errors["BlockhashNotFound"] =
+      "Blockhash not found during simulation. Trying again.";
+  }
+
+  // Check the response logs for any known errors
+  if (response.logs) {
+    for (const line of response.logs) {
+      if (line.includes("SlippageToleranceExceeded")) {
+        errors["SlippageToleranceExceeded"] =
+          "Slippage failure during simulation. Trying again.";
+      }
+
+      if (line.includes("RequireGteViolated")) {
+        errors["RequireGteViolated"] =
+          "Swap instruction failure during simulation. Trying again.";
+      }
+    }
+  }
+
+  if (Object.keys(errors).length === 0) {
+    return false;
+  }
+
+  console.table(errors);
+  return true;
+}
+
+/**
+ * Checks whether a hostname is exactly the given domain or a subdomain of it.
+ * e.g. isHostOrSubdomainOf("api.triton.one", "triton.one") => true
+ *      isHostOrSubdomainOf("not-triton.com", "triton.one") => false
+ */
+function isHostOrSubdomainOf(hostname: string, base: string): boolean {
+  return hostname === base || hostname.endsWith(`.${base}`);
+}
+
+/**
+ * Determines the RPC provider from the endpoint URL.
+ */
+export function determineRpcProvider(endpoint: string): SolanaRpcProvider {
+  try {
+    const url = new URL(endpoint);
+    const hostname = url.hostname;
+    if (isHostOrSubdomainOf(hostname, "rpcpool.com") || isHostOrSubdomainOf(hostname, "triton.one")) {
+      return "triton";
+    } else if (isHostOrSubdomainOf(hostname, "helius-rpc.com") || isHostOrSubdomainOf(hostname, "helius.xyz")) {
+      return "helius";
+    } else if (isHostOrSubdomainOf(hostname, "ankr.com")) {
+      return "ankr";
+    } else {
+      return "unknown";
+    }
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Sleep for a specified duration.
+ */
+export async function sleep(timeout: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, timeout));
+}
+
+/**
+ * Checks whether an object is empty.
+ */
+export const isEmptyObject = (value: object | null | undefined): boolean => {
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  for (const key in value) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      return false;
+    }
+  }
+
+  return true;
+};
+

package/src/providers/wormhole/types.ts

@@ -35,25 +35,60 @@ export interface WormholeTransferRequest {
   mainSigner: Account;
   amount?: string;
   sponsorAccount?: Account;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
 }
 
+export type WithdrawPhase =
+  | "initiating"  // User signing Aptos burn transaction
+  | "tracking"    // Waiting for Wormhole attestation (~60s)
+  | "claiming";   // Claiming on destination chain
+
+/**
+ * Callback fired before and after each individual transaction is signed
+ * and submitted during a bridge flow.
+ *
+ * @param description - A human-readable description of the transaction
+ *   (e.g. "Approving USDC transfer"). Comes from the Wormhole SDK's
+ *   `UnsignedTransaction.description`.
+ * @param txId - `null` when called *before* signing; the on-chain
+ *   transaction hash when called *after* signing.
+ */
+export type OnTransactionSigned = (description: string, txId: string | null) => void;
+
 export interface WormholeWithdrawRequest {
+  /**
+   * The non-Aptos chain involved in the withdrawal. For a withdrawal from
+   * Aptos → Solana, this is `"Solana"`.
+   *
+   * Note: despite the name, this is the *destination* of the bridge transfer
+   * (where USDC will be claimed), not the chain that burns USDC (which is
+   * always Aptos for withdrawals).
+   */
   sourceChain: Chain;
   wallet: AdapterWallet;
   destinationAddress: AccountAddressInput;
   sponsorAccount?: Account | GasStationApiKey;
+  /** Optional callback fired when the withdraw progresses to a new phase. */
+  onPhaseChange?: (phase: WithdrawPhase) => void;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
 }
 
 export interface WormholeSubmitTransferRequest {
   sourceChain: Chain;
   wallet: AdapterWallet;
   destinationAddress: AccountAddressInput;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
 }
 
 export interface WormholeClaimTransferRequest {
   receipt: routes.Receipt<AttestationReceipt>;
   mainSigner: AptosAccount;
   sponsorAccount?: AptosAccount | GasStationApiKey;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
 }
 
 export interface WormholeTransferResponse {
@@ -70,3 +105,135 @@ export interface WormholeStartTransferResponse {
   originChainTxnId: string;
   receipt: routes.Receipt<AttestationReceipt>;
 }
+
+// --- Split withdraw flow types ---
+
+export interface WormholeInitiateWithdrawRequest {
+  wallet: AdapterWallet;
+  destinationAddress: AccountAddressInput;
+  sponsorAccount?: Account | GasStationApiKey;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
+}
+
+export interface WormholeInitiateWithdrawResponse {
+  originChainTxnId: string;
+  receipt: routes.Receipt<AttestationReceipt>;
+}
+
+export interface WormholeClaimWithdrawRequest {
+  /**
+   * The chain on which the claim transaction will be executed (the destination
+   * chain of the withdrawal).
+   *
+   * For example, when withdrawing from Aptos → Solana, `claimChain` is
+   * `"Solana"` because that's where the USDC is minted/claimed.
+   */
+  claimChain: Chain;
+  destinationAddress: string;
+  receipt: routes.Receipt<AttestationReceipt>;
+  // Required for wallet-based claim (non-Solana chains, or Solana without serverClaimUrl).
+  // Not needed when the SDK uses the configured serverClaimUrl for Solana claims.
+  wallet?: AdapterWallet;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
+}
+
+export interface WormholeClaimWithdrawResponse {
+  destinationChainTxnId: string;
+}
+
+export interface RetryWithdrawClaimRequest extends WormholeClaimWithdrawRequest {
+  /** Maximum number of retry attempts (default: 5). */
+  maxRetries?: number;
+  /** Initial delay in ms before the first retry (default: 2000). */
+  initialDelayMs?: number;
+  /** Multiplier applied to the delay after each failed attempt (default: 2). */
+  backoffMultiplier?: number;
+}
+
+export interface RetryWithdrawClaimResponse extends WormholeClaimWithdrawResponse {
+  /** Number of retry attempts that were needed (0 means first attempt succeeded). */
+  retriesUsed: number;
+}
+
+/**
+ * Validates that a value returned by `getExpireTimestamp` is a non-negative
+ * integer suitable for use as an epoch-second expiration timestamp.
+ * Throws immediately for NaN, Infinity, negative values, or floats so that
+ * misconfigured callbacks fail fast instead of producing silent misbehaviour.
+ */
+export function validateExpireTimestamp(value: number): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `getExpireTimestamp returned an invalid value (${value}). ` +
+        "Expected a non-negative integer (epoch seconds).",
+    );
+  }
+}
+
+/**
+ * Error thrown when the transfer (deposit) flow fails *after* the source-chain
+ * burn transaction has already been submitted (i.e. during attestation tracking
+ * or Aptos claiming).
+ *
+ * Consumers should check `instanceof TransferError` in their catch block
+ * to recover the `originChainTxnId` and display an explorer link so the
+ * user can verify their burn on-chain.
+ */
+export class TransferError extends Error {
+  /** Source-chain burn transaction hash — available when the burn succeeded before the failure. */
+  readonly originChainTxnId: string;
+  /**
+   * The underlying error that caused this failure.
+   * Mirrors ES2022 Error.cause — declared explicitly because the project's
+   * TypeScript lib target does not include ES2022 ErrorOptions.
+   */
+  readonly cause?: unknown;
+
+  constructor(
+    message: string,
+    originChainTxnId: string,
+    cause?: unknown,
+  ) {
+    super(message);
+    this.name = "TransferError";
+    this.originChainTxnId = originChainTxnId;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Error thrown when the withdraw flow fails *after* the Aptos burn
+ * transaction has already been submitted (i.e. during attestation tracking
+ * or destination-chain claiming).
+ *
+ * Consumers should check `instanceof WithdrawError` in their catch block
+ * to recover the `originChainTxnId` and display an explorer link so the
+ * user can verify their burn on-chain.
+ */
+export class WithdrawError extends Error {
+  /** Aptos burn transaction hash — always available when this error is thrown. */
+  readonly originChainTxnId: string;
+  /** The withdraw phase that failed ("tracking" or "claiming"). */
+  readonly phase: WithdrawPhase;
+  /**
+   * The underlying error that caused this failure.
+   * Mirrors ES2022 Error.cause — declared explicitly because the project's
+   * TypeScript lib target does not include ES2022 ErrorOptions.
+   */
+  readonly cause?: unknown;
+
+  constructor(
+    message: string,
+    originChainTxnId: string,
+    phase: WithdrawPhase,
+    cause?: unknown,
+  ) {
+    super(message);
+    this.name = "WithdrawError";
+    this.originChainTxnId = originChainTxnId;
+    this.phase = phase;
+    this.cause = cause;
+  }
+}

package/src/providers/wormhole/utils.ts

@@ -0,0 +1,72 @@
+/**
+ * Utility functions for Wormhole CCTP route creation.
+ * These helpers can be used both by WormholeProvider and server-side claim endpoints.
+ */
+
+import {
+  chainToPlatform,
+  routes,
+  Wormhole,
+  TokenId,
+} from "@wormhole-foundation/sdk";
+import { Chain } from "../../CrossChainCore";
+import { TokenConfig } from "../../config";
+
+export interface CCTPRouteResult {
+  route: routes.ManualRoute<"Mainnet" | "Testnet">;
+  request: routes.RouteTransferRequest<"Mainnet" | "Testnet">;
+}
+
+/**
+ * Creates a CCTP route for transferring USDC between two chains.
+ *
+ * This is a standalone helper that can be used both by WormholeProvider
+ * (client-side) and server-side claim endpoints to avoid code duplication.
+ *
+ * @param wh - Initialized Wormhole context
+ * @param sourceChain - Source chain (e.g., "Aptos")
+ * @param destChain - Destination chain (e.g., "Solana")
+ * @param tokens - Token configuration mapping (mainnetTokens or testnetTokens)
+ * @returns The CCTP route and request for completing transfers
+ * @throws Error if no valid CCTP route is found
+ */
+export async function createCCTPRoute(
+  wh: Wormhole<"Mainnet" | "Testnet">,
+  sourceChain: Chain,
+  destChain: Chain,
+  tokens: Record<string, TokenConfig>,
+): Promise<CCTPRouteResult> {
+  const sourceToken: TokenId = Wormhole.tokenId(
+    sourceChain,
+    tokens[sourceChain].tokenId.address,
+  );
+  const destToken: TokenId = Wormhole.tokenId(
+    destChain,
+    tokens[destChain].tokenId.address,
+  );
+
+  const destContext = wh
+    .getPlatform(chainToPlatform(destChain))
+    .getChain(destChain);
+  const sourceContext = wh
+    .getPlatform(chainToPlatform(sourceChain))
+    .getChain(sourceChain);
+
+  const request = await routes.RouteTransferRequest.create(
+    wh,
+    { source: sourceToken, destination: destToken },
+    sourceContext,
+    destContext,
+  );
+
+  const resolver = wh.resolver([routes.CCTPRoute]);
+  const foundRoutes = await resolver.findRoutes(request);
+  const cctpRoute = foundRoutes[0];
+
+  if (!cctpRoute || !routes.isManual(cctpRoute)) {
+    throw new Error("Expected manual CCTP route");
+  }
+
+  return { route: cctpRoute, request };
+}
+