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

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

@@ -16,15 +16,17 @@ import {
   AptosChains,
   AptosUnsignedTransaction,
 } from "@wormhole-foundation/sdk-aptos";
-import { GasStationApiKey } from "..";
+import { GasStationApiKey, validateExpireTimestamp } from "..";
 import { UserResponseStatus } from "@aptos-labs/wallet-standard";
 import { GasStationClient, GasStationTransactionSubmitter } from "@aptos-labs/gas-station-client";
+import { CrossChainCore } from "../../../CrossChainCore";
 
 export async function signAndSendTransaction(
   request: AptosUnsignedTransaction<Network, AptosChains>,
   wallet: AdapterWallet,
   sponsorAccount: Account | GasStationApiKey | undefined,
   dappNetwork: AptosNetwork,
+  crossChainCore?: CrossChainCore,
 ) {
   if (!wallet) {
     throw new Error("wallet.sendTransaction is undefined");
@@ -90,12 +92,19 @@ export async function signAndSendTransaction(
     functionArguments,
   };
 
+  const expireTimestamp = crossChainCore?._dappConfig?.getExpireTimestamp?.();
+  if (typeof expireTimestamp !== "undefined") {
+    validateExpireTimestamp(expireTimestamp);
+  }
   const txnToSign = await aptos.transaction.build.simple({
     data: transactionData,
     sender: (
       await wallet.features["aptos:account"]?.account()
     ).address.toString(),
     withFeePayer: sponsorAccount ? true : false,
+    ...(typeof expireTimestamp !== "undefined"
+      ? { options: { expireTimestamp } }
+      : {}),
   });
 
   const response =

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

@@ -6,11 +6,11 @@ import { Network } from "@wormhole-foundation/sdk";
 import { ethers, getBigInt } from "ethers";
 import { AdapterWallet } from "@aptos-labs/wallet-adapter-core";
 import { EIP1193DerivedWallet } from "@aptos-labs/derived-wallet-ethereum";
+
 export async function signAndSendTransaction(
   request: EvmUnsignedTransaction<Network, EvmChains>,
   wallet: AdapterWallet,
   chainName: string,
-  options: any,
 ): Promise<string> {
   if (!wallet) {
     throw new Error("wallet.sendTransaction is undefined");
@@ -23,8 +23,7 @@ export async function signAndSendTransaction(
   });
   const actualChainId = parseInt(chainId, 16);
 
-  if (!actualChainId)
-    throw new Error("No signer found for chain" + chainName);
+  if (!actualChainId) throw new Error("No signer found for chain" + chainName);
   const expectedChainId = request.transaction.chainId
     ? getBigInt(request.transaction.chainId)
     : undefined;
@@ -42,8 +41,60 @@ export async function signAndSendTransaction(
     (wallet as EIP1193DerivedWallet).eip1193Provider,
   );
   const signer = await provider.getSigner();
-  const response = await signer.sendTransaction(request.transaction);
-  const receipt = await response.wait();
 
-  return receipt?.hash || "";
+  let response: ethers.TransactionResponse;
+  try {
+    response = await signer.sendTransaction(request.transaction);
+  } catch (e) {
+    // Some wallet providers (e.g. MetaMask via injected provider) can throw
+    // after the transaction is already broadcast. Try to extract the hash from
+    // the error so the caller can track the pending transaction.
+    const message = e instanceof Error ? e.message : String(e);
+    const hashMatch = message.match(/"hash":\s*"(0x[a-fA-F0-9]{64})"/);
+    if (hashMatch) {
+      console.warn("Extracted EVM tx hash from error:", hashMatch[1]);
+      return hashMatch[1];
+    }
+    throw e;
+  }
+
+  try {
+    const receipt = await response.wait();
+    return receipt?.hash || response.hash || "";
+  } catch (e: any) {
+    // When a user speeds up or cancels a transaction in their wallet, ethers
+    // throws a TRANSACTION_REPLACED error. We must handle this specifically
+    // to avoid returning the old (now-invalid) hash.
+    if (e?.code === "TRANSACTION_REPLACED") {
+      // "repriced" means the same transaction data was re-sent with higher
+      // gas — the bridge burn still went through with the replacement tx.
+      if (e.reason === "repriced") {
+        const replacementHash = e.receipt?.hash || e.replacement?.hash;
+        if (replacementHash) {
+          console.warn(
+            "EVM transaction was repriced. Using replacement hash:",
+            replacementHash,
+          );
+          return replacementHash;
+        }
+      }
+      // "cancelled" or "replaced" means the original burn was superseded by
+      // a different transaction (e.g. a 0-value self-transfer or an entirely
+      // different call). The bridge burn did not happen, so we must not
+      // return a hash that implies success.
+      throw e;
+    }
+
+    // wait() can fail due to network timeouts or RPC instability, but the
+    // transaction was already submitted (sendTransaction returned successfully).
+    // Return the hash so the caller can track confirmation asynchronously.
+    if (response.hash) {
+      console.warn(
+        "EVM transaction wait failed but tx was submitted:",
+        response.hash,
+      );
+      return response.hash;
+    }
+    throw e;
+  }
 }

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

@@ -25,7 +25,7 @@ import { ChainConfig } from "../../../config";
 import { CrossChainCore } from "../../../CrossChainCore";
 import { AptosChains } from "@wormhole-foundation/sdk-aptos/dist/cjs/types";
 import { AptosUnsignedTransaction } from "@wormhole-foundation/sdk-aptos/dist/cjs/unsignedTransaction";
-import { GasStationApiKey } from "../types";
+import { GasStationApiKey, OnTransactionSigned } from "../types";
 import { Account } from "@aptos-labs/ts-sdk";
 export class Signer<
   N extends Network,
@@ -37,7 +37,15 @@ export class Signer<
   _wallet: AdapterWallet;
   _crossChainCore: CrossChainCore;
   _sponsorAccount: Account | GasStationApiKey | undefined;
+  _onTransactionSigned: OnTransactionSigned | undefined;
   _claimedTransactionHashes: string[] = [];
+  /**
+   * When true, signed tx hashes are written to
+   * `_crossChainCore._lastSourceChainTxId` as a recovery side-channel.
+   * Set to false for destination-chain claim signers so they don't
+   * overwrite the source-chain burn hash.
+   */
+  _trackAsSourceChain: boolean;
 
   constructor(
     chain: ChainConfig,
@@ -46,6 +54,8 @@ export class Signer<
     wallet: AdapterWallet,
     crossChainCore: CrossChainCore,
     sponsorAccount?: Account | GasStationApiKey | undefined,
+    onTransactionSigned?: OnTransactionSigned,
+    trackAsSourceChain: boolean = true,
   ) {
     this._chain = chain;
     this._address = address;
@@ -53,6 +63,8 @@ export class Signer<
     this._wallet = wallet;
     this._crossChainCore = crossChainCore;
     this._sponsorAccount = sponsorAccount;
+    this._onTransactionSigned = onTransactionSigned;
+    this._trackAsSourceChain = trackAsSourceChain;
   }
 
   chain(): C {
@@ -71,6 +83,7 @@ export class Signer<
     this._claimedTransactionHashes = [];
 
     for (const tx of txs) {
+      this._onTransactionSigned?.(tx.description, null);
       const txId = await signAndSendTransaction(
         this._chain,
         tx,
@@ -79,6 +92,10 @@ export class Signer<
         this._crossChainCore,
         this._sponsorAccount,
       );
+      if (this._trackAsSourceChain) {
+        this._crossChainCore._lastSourceChainTxId = txId;
+      }
+      this._onTransactionSigned?.(tx.description, txId);
       txHashes.push(txId);
       this._claimedTransactionHashes.push(txId);
     }
@@ -113,7 +130,6 @@ export const signAndSendTransaction = async (
       request as EvmUnsignedTransaction<Network, EvmChains>,
       wallet,
       chain.displayName,
-      options,
     );
     return tx;
   } else if (chain.context === "Sui") {
@@ -128,6 +144,7 @@ export const signAndSendTransaction = async (
       wallet,
       sponsorAccount,
       dappNetwork,
+      crossChainCore,
     );
     return tx;
   } else {

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

@@ -16,6 +16,7 @@ import {
   PriorityFeeConfig,
   sendAndConfirmTransaction,
 } from "./solanaUtils";
+import { OnTransactionSigned } from "../types";
 
 export interface SolanaLocalSignerConfig {
   /** The Solana keypair to sign transactions with */
@@ -30,6 +31,8 @@ export interface SolanaLocalSignerConfig {
   priorityFeeConfig?: PriorityFeeConfig;
   /** Enable verbose logging (default: false) */
   verbose?: boolean;
+  /** Optional callback fired before and after each individual transaction is signed. */
+  onTransactionSigned?: OnTransactionSigned;
 }
 
 /**
@@ -68,6 +71,7 @@ export class SolanaLocalSigner<N extends Network, C extends Chain>
   private retryIntervalMs: number;
   private priorityFeeConfig?: PriorityFeeConfig;
   private verbose: boolean;
+  private _onTransactionSigned?: OnTransactionSigned;
   private _claimedTransactionHashes: string[] = [];
 
   constructor(config: SolanaLocalSignerConfig) {
@@ -77,6 +81,7 @@ export class SolanaLocalSigner<N extends Network, C extends Chain>
     this.retryIntervalMs = config.retryIntervalMs ?? 5000;
     this.priorityFeeConfig = config.priorityFeeConfig;
     this.verbose = config.verbose ?? false;
+    this._onTransactionSigned = config.onTransactionSigned;
   }
 
   chain(): C {
@@ -100,7 +105,9 @@ export class SolanaLocalSigner<N extends Network, C extends Chain>
     this._claimedTransactionHashes = [];
 
     for (const tx of txs) {
+      this._onTransactionSigned?.(tx.description, null);
       const txId = await this.signAndSendTransaction(tx);
+      this._onTransactionSigned?.(tx.description, txId);
       txHashes.push(txId);
       this._claimedTransactionHashes.push(txId);
     }

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

@@ -41,7 +41,10 @@ export async function signAndSendTransaction(
     throw new Error("Invalid wallet type or missing Solana wallet");
   }
 
-  const commitment = options?.commitment ?? "finalized";
+  const commitment =
+    options?.commitment ??
+    crossChainCore?._dappConfig?.solanaConfig?.commitment ??
+    "finalized";
   // Solana rpc should come from dapp config
   const connection = new Connection(
     crossChainCore?._dappConfig?.solanaConfig?.rpc ??

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

@@ -82,34 +82,58 @@ export async function sendAndConfirmTransaction(
     commitment,
   );
 
-  // Retry loop: resend if not confirmed after interval
+  // 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;
 
-  while (!confirmedTx) {
-    confirmedTx = await Promise.race([
-      confirmTransactionPromise,
-      new Promise<null>((resolve) =>
-        setTimeout(() => resolve(null), retryIntervalMs),
-      ),
-    ]);
+  try {
+    while (!confirmedTx) {
+      confirmedTx = await Promise.race([
+        confirmTransactionPromise,
+        new Promise<null>((resolve) =>
+          setTimeout(() => resolve(null), retryIntervalMs),
+        ),
+      ]);
 
-    if (confirmedTx) break;
+      if (confirmedTx) break;
 
-    if (verbose) {
-      console.log(
-        `Tx not confirmed after ${retryIntervalMs * txSendAttempts++}ms, resending`,
-      );
-    }
+      if (verbose) {
+        console.log(
+          `Tx not confirmed after ${retryIntervalMs * txSendAttempts++}ms, resending`,
+        );
+      }
 
-    try {
-      await connection.sendRawTransaction(serializedTx, sendOptions);
-    } catch (e) {
+      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.error("Failed to resend transaction:", e);
+        console.warn(
+          "Block height exceeded but tx was already sent, returning signature:",
+          signature,
+        );
       }
-      // Ignore resend errors, confirmation will handle success/failure
+      // 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) {

package/src/providers/wormhole/types.ts

@@ -35,6 +35,8 @@ 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 =
@@ -42,25 +44,51 @@ export type WithdrawPhase =
   | "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 {
@@ -84,6 +112,8 @@ 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 {
@@ -92,18 +122,87 @@ export interface WormholeInitiateWithdrawResponse {
 }
 
 export interface WormholeClaimWithdrawRequest {
-  sourceChain: Chain;
+  /**
+   * 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