0xtrails 0.6.6 → 0.7.0

package/src/widget/hooks/useTrailsSendTransaction.ts

@@ -0,0 +1,949 @@
+import { useMutation } from "@tanstack/react-query"
+import { useCallback, useRef } from "react"
+import { useWalletClient, useAccount, useChainId } from "wagmi"
+import { logger } from "../../logger.js"
+import { getFullErrorMessage, getIsUserRejectionError } from "../../error.js"
+import type { UseQuoteProps, SwapReturn } from "./useQuote.js"
+import { prepareSend, TradeType } from "../../prepareSend.js"
+import { useTrailsClient } from "../../trailsClient.js"
+import { useTrails } from "../../widget/providers/TrailsProvider.js"
+import {
+  useTrailsModal,
+  type HostTransactionDetails,
+  type HostTransactionResultLinks,
+  type HostTransactionStatus,
+} from "../../widget/providers/TrailsModalProvider.js"
+import { useIndexerGatewayClient } from "../../indexerClient.js"
+import {
+  getTokenBalancesWithPrices,
+  getHasSufficientBalanceToken,
+} from "../../tokenBalances.js"
+import { useSupportedTokens } from "../../tokens.js"
+import { getChainInfo } from "../../chains.js"
+import { getTokenPrice } from "../../prices.js"
+import { zeroAddress, erc20Abi, type Address, type Hex } from "viem"
+import { useCommitIntent, useExecuteIntent } from "../../mutations.js"
+import { getExplorerUrl } from "../../explorer.js"
+import type { TransactionState } from "../../transactions.js"
+
+export type TrailsSendTransactionVariables = {
+  to?: Address
+  value?: bigint // Native token amount for ORIGIN (wagmi-compatible, sends ETH/native token)
+  data?: Hex
+  // Destination token requirements (e.g., AAVE deposit needs USDC on Base)
+  // Note: Destination can be ERC20 token, so value is NOT needed for destination
+  tokenAddress?: Address // Destination token address (ERC20 token required at destination)
+  tokenAmount?: string // Destination token amount (in token units, e.g., 3000000 for 3 USDC)
+  // Origin token parameters (if not provided, modal will open for selection)
+  // Use value for native token origin, OR fromTokenAddress/fromChainId/fromAmount for ERC20 origin
+  fromTokenAddress?: Address // Origin token address (ERC20 token to send from)
+  fromChainId?: number // Origin chain ID (required if fromTokenAddress is provided)
+  fromAmount?: string // Origin token amount (required if fromTokenAddress is provided)
+}
+
+export type UseTrailsSendTransactionParameters = Omit<
+  UseQuoteProps,
+  | "fromTokenAddress"
+  | "fromChainId"
+  | "toTokenAddress"
+  | "toChainId"
+  | "swapAmount"
+  | "toRecipient"
+  | "toCalldata"
+  | "tradeType"
+  | "selectedFeeOption"
+> & {
+  /**
+   * Callback fired when the mutation is successful
+   */
+  onSuccess?: (
+    data: SwapReturn,
+    variables: TrailsSendTransactionVariables,
+  ) => void
+  /**
+   * Callback fired when the mutation encounters an error
+   */
+  onError?: (error: Error, variables: TrailsSendTransactionVariables) => void
+  /**
+   * Callback fired when the mutation is either successfully fetched or encounters an error
+   */
+  onSettled?: (
+    data: SwapReturn | undefined,
+    error: Error | null,
+    variables: TrailsSendTransactionVariables,
+  ) => void
+  /**
+   * Custom text for the receipt action button (default: "Transact Again")
+   */
+  receiptActionButtonText?: string
+  /**
+   * Custom callback when receipt action button is clicked
+   */
+  onReceiptAction?: () => void
+}
+
+export type UseTrailsSendTransactionReturnType = {
+  sendTransaction: (
+    variables: TrailsSendTransactionVariables,
+    callbacks?: {
+      onSuccess?: (data: SwapReturn) => void
+      onError?: (error: Error) => void
+      onSettled?: (data: SwapReturn | undefined, error: Error | null) => void
+    },
+  ) => void
+  sendTransactionAsync: (
+    variables: TrailsSendTransactionVariables,
+    callbacks?: {
+      onSuccess?: (data: SwapReturn) => void
+      onError?: (error: Error) => void
+      onSettled?: (data: SwapReturn | undefined, error: Error | null) => void
+    },
+  ) => Promise<SwapReturn>
+  retry: () => void
+  data: SwapReturn | undefined
+  error: Error | null
+  isPending: boolean
+  isSuccess: boolean
+  isError: boolean
+  isIdle: boolean
+  status: "idle" | "pending" | "error" | "success"
+  reset: () => void
+  variables: TrailsSendTransactionVariables | undefined
+}
+
+/**
+ * Hook for creating, signing, and sending transactions to networks using Trails SDK.
+ * Provides a one-line replacement for wagmi's `useSendTransaction`.
+ *
+ * @example
+ * ```ts
+ * // Simple usage - one line replacement (wagmi-compatible API)
+ * const { sendTransaction } = useTrailsSendTransaction()
+ *
+ * // Send native token (same as wagmi)
+ * sendTransaction({
+ *   to: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+ *   value: parseEther('0.01'),
+ * })
+ *
+ * // Deposit 3 USDC to AAVE pool (Trails-specific)
+ * // Modal will open for user to select origin token/chain/amount
+ * sendTransaction({
+ *   to: '0xaavePoolAddress',
+ *   tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+ *   tokenAmount: '3000000', // 3 USDC (6 decimals)
+ *   data: '0x...', // AAVE deposit calldata
+ * })
+ * ```
+ */
+export function useTrailsSendTransaction(
+  params?: UseTrailsSendTransactionParameters,
+): UseTrailsSendTransactionReturnType {
+  const { data: walletClient } = useWalletClient()
+  const { chainId: connectedChainId } = useAccount()
+  const chainId = useChainId()
+  const trailsClient = useTrailsClient()
+  const { trailsApiKey, sequenceIndexerUrl } = useTrails()
+  const {
+    openModal,
+    setPendingSelection,
+    setHostTransactionState,
+    setHostTransactionQuote,
+    setHostTransactionStates,
+    setHostTransactionTimestamp,
+    hostTransactionState,
+    setReceiptActionButtonText,
+    setOnReceiptAction,
+    retryTransactionRef,
+  } = useTrailsModal()
+  const indexerGatewayClient = useIndexerGatewayClient()
+  const { supportedTokens } = useSupportedTokens()
+  const commitIntentMutation = useCommitIntent()
+  const executeIntentMutation = useExecuteIntent()
+
+  // Store last transaction variables for retry
+  const lastTransactionVariablesRef =
+    useRef<TrailsSendTransactionVariables | null>(null)
+
+  const mergeHostTransactionState = useCallback(
+    (update: {
+      status?: HostTransactionStatus
+      details?: HostTransactionDetails | null
+      error?: string | null
+      result?: HostTransactionResultLinks | null
+      retryEnabled?: boolean
+    }) => {
+      setHostTransactionState((prev) => ({
+        status: update.status ?? prev.status,
+        details:
+          update.details === null
+            ? undefined
+            : update.details
+              ? { ...prev.details, ...update.details }
+              : prev.details,
+        error:
+          update.error === null
+            ? undefined
+            : update.error !== undefined
+              ? update.error
+              : prev.error,
+        result:
+          update.result === null
+            ? undefined
+            : update.result
+              ? { ...prev.result, ...update.result }
+              : prev.result,
+        retryEnabled:
+          update.retryEnabled !== undefined
+            ? update.retryEnabled
+            : prev.retryEnabled,
+      }))
+    },
+    [setHostTransactionState],
+  )
+
+  // Extract transaction execution logic into a reusable function
+  const executeTransaction = async (
+    variables: TrailsSendTransactionVariables,
+    originSelection?: {
+      fromTokenAddress: string
+      fromChainId: number
+      fromAmount?: string
+    },
+    options?: { trackInWidget?: boolean },
+  ): Promise<SwapReturn> => {
+    logger.console.log(
+      "[trails-sdk] [useTrailsSendTransaction] Executing transaction",
+      { variables, originSelection },
+    )
+
+    // Validate required parameters
+    if (!walletClient || !walletClient.account) {
+      throw new Error(
+        "Wallet client not available. Please connect your wallet.",
+      )
+    }
+
+    if (!variables.to) {
+      throw new Error("Transaction 'to' address is required.")
+    }
+
+    // Determine origin parameters
+    let fromTokenAddress: string
+    let fromChainId: number
+    let fromAmount: string | undefined
+
+    if (originSelection) {
+      // Use user-selected origin parameters (from modal)
+      fromTokenAddress = originSelection.fromTokenAddress
+      fromChainId = originSelection.fromChainId
+      fromAmount = originSelection.fromAmount
+    } else if (
+      variables.fromTokenAddress &&
+      variables.fromChainId &&
+      variables.fromAmount
+    ) {
+      // Use explicitly provided ERC20 token origin parameters
+      fromTokenAddress = variables.fromTokenAddress
+      fromChainId = variables.fromChainId
+      fromAmount = variables.fromAmount
+    } else if (variables.to && variables.value !== undefined) {
+      // Simple native token send - use current chain
+      const currentChainId = connectedChainId || chainId
+      if (!currentChainId) {
+        throw new Error("Chain ID not available. Please connect your wallet.")
+      }
+      fromChainId = currentChainId
+      fromTokenAddress = zeroAddress
+      fromAmount = variables.value.toString()
+    } else {
+      throw new Error(
+        "Origin token parameters are required. Please provide 'value' (native token), or 'fromTokenAddress'/'fromChainId'/'fromAmount' (ERC20 token), or select via modal.",
+      )
+    }
+
+    // Determine destination parameters
+    const currentChainId = connectedChainId || chainId
+    if (!currentChainId) {
+      throw new Error("Chain ID not available. Please connect your wallet.")
+    }
+
+    // Use tokenAddress and tokenAmount if provided, otherwise infer from to/value
+    let toTokenAddress: string
+    let toChainId: number
+    let toAmount: string
+    let recipient: string
+
+    if (variables.tokenAddress && variables.tokenAmount) {
+      // Destination token requirements specified (e.g., AAVE deposit)
+      toTokenAddress = variables.tokenAddress
+      // Try to find the token's chainId from supportedTokens, fallback to current chain
+      const destToken = supportedTokens?.find(
+        (token) =>
+          token.contractAddress?.toLowerCase() ===
+          variables.tokenAddress?.toLowerCase(),
+      )
+      toChainId = destToken?.chainId ?? currentChainId
+      toAmount = variables.tokenAmount
+      recipient = variables.to
+    } else if (variables.to && variables.value !== undefined) {
+      // Simple native token send
+      toTokenAddress = zeroAddress
+      toChainId = currentChainId
+      toAmount = variables.value.toString()
+      recipient = variables.to
+    } else {
+      throw new Error(
+        "Either 'value' or 'tokenAddress'/'tokenAmount' must be provided.",
+      )
+    }
+
+    // Determine swap amount based on trade type
+    // If tokenAmount is provided, use EXACT_OUTPUT (we need exact amount of destination token)
+    // Otherwise, use EXACT_INPUT (we're sending exact amount from origin)
+    const tradeType =
+      variables.tokenAddress && variables.tokenAmount
+        ? TradeType.EXACT_OUTPUT
+        : TradeType.EXACT_INPUT
+    if (tradeType === TradeType.EXACT_INPUT && !fromAmount) {
+      throw new Error(
+        "Origin amount is required for this transaction. Please provide 'value' or 'fromAmount'.",
+      )
+    }
+
+    const swapAmount =
+      tradeType === TradeType.EXACT_OUTPUT ? toAmount : fromAmount!
+
+    // Get token balances
+    let balances: any[] = []
+    try {
+      const result = await getTokenBalancesWithPrices({
+        account: walletClient.account.address,
+        indexerGatewayClient,
+        trailsClient,
+      })
+      balances = result.balances
+    } catch (balanceError) {
+      logger.console.warn(
+        "[trails-sdk] [useTrailsSendTransaction] Error fetching balances, proceeding with zero balance",
+        balanceError,
+      )
+      balances = []
+    }
+
+    const originTokenBalance = balances.find(
+      (b) =>
+        b.chainId === fromChainId &&
+        (b.contractAddress?.toLowerCase() === fromTokenAddress?.toLowerCase() ||
+          (!b.contractAddress && fromTokenAddress === zeroAddress)),
+    )
+
+    const originTokenBalanceAmount = originTokenBalance?.balance ?? "0"
+
+    // Get native token price for origin chain
+    let originNativeTokenPriceUsd = 0
+    try {
+      const originChain = getChainInfo(fromChainId)
+      const nativeTokenSymbol = originChain?.nativeCurrency?.symbol ?? ""
+      if (nativeTokenSymbol) {
+        const nativePrice = await getTokenPrice(trailsClient, {
+          tokenSymbol: nativeTokenSymbol,
+          tokenAddress: zeroAddress,
+          chainId: fromChainId,
+        })
+        originNativeTokenPriceUsd = nativePrice?.priceUsd ?? 0
+      }
+    } catch (error) {
+      logger.console.warn(
+        "[trails-sdk] [useTrailsSendTransaction] Error getting native token price",
+        error,
+      )
+    }
+
+    // Get token info and decimals
+    const originToken = supportedTokens?.find(
+      (token) =>
+        token.contractAddress?.toLowerCase() ===
+          fromTokenAddress?.toLowerCase() && token.chainId === fromChainId,
+    )
+    const destinationToken = supportedTokens?.find(
+      (token) =>
+        token.contractAddress?.toLowerCase() ===
+          toTokenAddress?.toLowerCase() && token.chainId === toChainId,
+    )
+
+    // Get RPC clients - we need to get them dynamically since we don't know chainIds until mutation
+    const { getChainRpcClient } = await import("../../chains.js")
+    const originPublicClient = getChainRpcClient(fromChainId)
+    const destinationPublicClient = getChainRpcClient(toChainId)
+
+    // Fetch decimals on-chain if not found
+    const fetchDecimalsOnChain = async (
+      tokenAddress: string,
+      chainId: number,
+    ): Promise<number | null> => {
+      try {
+        const publicClient =
+          chainId === fromChainId
+            ? originPublicClient
+            : chainId === toChainId
+              ? destinationPublicClient
+              : getChainRpcClient(chainId)
+
+        if (!publicClient) {
+          return null
+        }
+
+        if (tokenAddress.toLowerCase() === zeroAddress.toLowerCase()) {
+          const chainInfo = getChainInfo(chainId)
+          return chainInfo?.nativeCurrency.decimals ?? 18
+        }
+
+        const decimals = await publicClient.readContract({
+          address: tokenAddress as `0x${string}`,
+          abi: erc20Abi,
+          functionName: "decimals",
+        })
+
+        return decimals
+      } catch (error) {
+        logger.console.error(
+          `[trails-sdk] Error fetching decimals on-chain for token ${tokenAddress} on chain ${chainId}:`,
+          error,
+        )
+        return null
+      }
+    }
+
+    let sourceTokenDecimals = originToken?.decimals
+    if (!sourceTokenDecimals && fromTokenAddress) {
+      const onChainDecimals = await fetchDecimalsOnChain(
+        fromTokenAddress,
+        fromChainId,
+      )
+      if (onChainDecimals !== null) {
+        sourceTokenDecimals = onChainDecimals
+      }
+    }
+    if (!sourceTokenDecimals) {
+      // Default to 18 for native/unknown
+      sourceTokenDecimals = 18
+    }
+
+    let destinationTokenDecimals = destinationToken?.decimals
+    if (!destinationTokenDecimals && toTokenAddress) {
+      const onChainDecimals = await fetchDecimalsOnChain(
+        toTokenAddress,
+        toChainId,
+      )
+      if (onChainDecimals !== null) {
+        destinationTokenDecimals = onChainDecimals
+      }
+    }
+    if (!destinationTokenDecimals) {
+      // Default to 18 for native/unknown
+      destinationTokenDecimals = 18
+    }
+
+    const destinationTokenSymbol = destinationToken?.symbol ?? ""
+    const originTokenSymbol = originToken?.symbol ?? ""
+
+    const handleTransactionStateChange = (states: TransactionState[]) => {
+      if (options?.trackInWidget) {
+        setHostTransactionStates(states)
+      }
+      params?.onStatusUpdate?.(states)
+    }
+
+    // Call prepareSend
+    const { send, quote } = await prepareSend({
+      account: walletClient.account,
+      originTokenAddress: fromTokenAddress,
+      originChainId: fromChainId,
+      originTokenBalance: originTokenBalanceAmount,
+      destinationChainId: toChainId,
+      recipient: recipient,
+      destinationTokenAddress: toTokenAddress,
+      swapAmount: swapAmount,
+      tradeType: tradeType,
+      originTokenSymbol: originTokenSymbol,
+      destinationTokenSymbol: destinationTokenSymbol,
+      fee: "0",
+      client: walletClient,
+      dryMode: false,
+      trailsClient,
+      destinationCalldata: variables.data
+        ? variables.data.toString()
+        : undefined,
+      onTransactionStateChange: handleTransactionStateChange,
+      sourceTokenDecimals,
+      destinationTokenDecimals,
+      paymasterUrl: params?.paymasterUrl,
+      slippageTolerance: params?.slippageTolerance?.toString(),
+      originNativeTokenPriceUsd,
+      quoteProvider: params?.quoteProvider,
+      commitIntentFn: commitIntentMutation.mutateAsync,
+      executeIntentFn: executeIntentMutation.mutateAsync,
+      checkoutOnHandlers: params?.checkoutOnHandlers,
+      sequenceIndexerUrl,
+      sequenceProjectAccessKey: trailsApiKey,
+      originPublicClient: originPublicClient ?? undefined,
+      destinationPublicClient: destinationPublicClient ?? undefined,
+      isSmartWallet: params?.isSmartWallet ?? undefined,
+    })
+
+    if (options?.trackInWidget) {
+      setHostTransactionQuote(quote ?? null)
+      if (!hostTransactionState.details) {
+        mergeHostTransactionState({
+          details: {
+            to: recipient,
+            tokenAddress: toTokenAddress,
+            tokenAmount:
+              tradeType === TradeType.EXACT_OUTPUT ? toAmount : undefined,
+            toChainId,
+            data: variables.data,
+          },
+        })
+      }
+      if (
+        !hostTransactionState.status ||
+        hostTransactionState.status === "idle"
+      ) {
+        setHostTransactionTimestamp(Date.now())
+      }
+    }
+
+    // Execute the swap
+    try {
+      // Reset retry flag when starting a new attempt
+      if (options?.trackInWidget) {
+        mergeHostTransactionState({ retryEnabled: false })
+      }
+      const {
+        depositUserTxnReceipt,
+        destinationIntentTransaction,
+        totalCompletionSeconds,
+      } = await send({
+        selectedFeeOption: null,
+        // Transition to "pending" when wallet signature is complete
+        onOriginSend: () => {
+          if (options?.trackInWidget) {
+            mergeHostTransactionState({ status: "pending", error: null })
+          }
+        },
+      })
+
+      if (options?.trackInWidget) {
+        mergeHostTransactionState({
+          status: "success",
+          result: {
+            originTxHash: depositUserTxnReceipt?.transactionHash,
+            originExplorerUrl: depositUserTxnReceipt?.transactionHash
+              ? getExplorerUrl({
+                  txHash: depositUserTxnReceipt.transactionHash,
+                  chainId: fromChainId,
+                })
+              : undefined,
+            destinationTxHash: destinationIntentTransaction?.txnHash,
+            destinationExplorerUrl: destinationIntentTransaction?.txnHash
+              ? getExplorerUrl({
+                  txHash: destinationIntentTransaction.txnHash,
+                  chainId: toChainId,
+                })
+              : undefined,
+          },
+        })
+      }
+
+      return {
+        originTransaction: {
+          transactionHash: depositUserTxnReceipt?.transactionHash,
+          explorerUrl: getExplorerUrl({
+            txHash: depositUserTxnReceipt?.transactionHash as string,
+            chainId: fromChainId,
+          }),
+          receipt: depositUserTxnReceipt,
+        },
+        destinationTransaction: {
+          transactionHash: destinationIntentTransaction?.txnHash,
+          explorerUrl: getExplorerUrl({
+            txHash: destinationIntentTransaction?.txnHash as string,
+            chainId: toChainId,
+          }),
+          receipt: destinationIntentTransaction,
+        },
+        totalCompletionSeconds,
+      }
+    } catch (error) {
+      if (options?.trackInWidget) {
+        // For user rejection errors, stay on confirmation screen with retry enabled
+        const isUserRejection = getIsUserRejectionError(error)
+        if (isUserRejection) {
+          mergeHostTransactionState({
+            status: "confirmation",
+            error: null,
+            retryEnabled: true,
+          })
+        } else {
+          mergeHostTransactionState({
+            status: "error",
+            error: getFullErrorMessage(error as Error),
+            retryEnabled: false,
+          })
+        }
+      }
+      throw error
+    }
+  }
+
+  const mutation = useMutation({
+    mutationFn: async (
+      variables: TrailsSendTransactionVariables,
+    ): Promise<SwapReturn> => {
+      logger.console.log(
+        "[trails-sdk] [useTrailsSendTransaction] Starting transaction",
+        variables,
+      )
+
+      // Set receipt customization from params
+      setReceiptActionButtonText(
+        params?.receiptActionButtonText ?? "Transact Again",
+      )
+      setOnReceiptAction(params?.onReceiptAction ?? null)
+
+      // Check if we have origin parameters specified
+      const hasNativeTokenOrigin = variables.value !== undefined
+      const hasERC20TokenOrigin =
+        variables.fromTokenAddress !== undefined &&
+        variables.fromChainId !== undefined
+      const hasOriginParams = hasNativeTokenOrigin || hasERC20TokenOrigin
+
+      // Determine destination chain ID
+      // Priority: token's chainId (from supportedTokens) > current chain
+      let destinationChainId: number | undefined
+      if (variables.tokenAddress && supportedTokens) {
+        // Find the token's chainId from supportedTokens
+        const destToken = supportedTokens.find(
+          (token) =>
+            token.contractAddress?.toLowerCase() ===
+            variables.tokenAddress?.toLowerCase(),
+        )
+        if (destToken) {
+          destinationChainId = destToken.chainId
+        }
+      }
+      if (!destinationChainId) {
+        destinationChainId = connectedChainId || chainId
+      }
+
+      // Check balances for origin and destination
+      let hasSufficientOriginBalance = true
+      let hasSufficientDestinationTokenBalance = true
+
+      if (walletClient?.account) {
+        try {
+          // Step 1: Check origin balance FIRST
+          // If origin is insufficient, user will need to select a different token via modal
+          if (hasOriginParams) {
+            let originTokenAddress: string | undefined
+            let originChainId: number | undefined
+            let originAmount: string | undefined
+
+            if (variables.value !== undefined) {
+              // Native token origin
+              originTokenAddress = zeroAddress
+              originChainId = connectedChainId || chainId || 1
+              originAmount = variables.value.toString()
+            } else if (variables.fromTokenAddress && variables.fromChainId) {
+              // ERC20 token origin (amount optional for EXACT_OUTPUT)
+              originTokenAddress = variables.fromTokenAddress
+              originChainId = variables.fromChainId
+              originAmount = variables.fromAmount
+            }
+
+            if (
+              originTokenAddress &&
+              originChainId &&
+              originAmount &&
+              originAmount !== "0"
+            ) {
+              hasSufficientOriginBalance = await getHasSufficientBalanceToken({
+                account: walletClient.account.address,
+                token: originTokenAddress,
+                amount: originAmount,
+                chainId: originChainId,
+                indexerGatewayClient,
+                trailsClient,
+              })
+              logger.console.log(
+                "[trails-sdk] [useTrailsSendTransaction] Origin token balance check:",
+                {
+                  tokenAddress: originTokenAddress,
+                  amount: originAmount,
+                  chainId: originChainId,
+                  hasSufficientBalance: hasSufficientOriginBalance,
+                },
+              )
+            }
+          }
+
+          // Step 2: Only check destination token balance if origin is sufficient
+          // (otherwise user will open modal to select a different origin token)
+          if (
+            hasSufficientOriginBalance &&
+            variables.tokenAddress &&
+            variables.tokenAmount
+          ) {
+            hasSufficientDestinationTokenBalance =
+              await getHasSufficientBalanceToken({
+                account: walletClient.account.address,
+                token: variables.tokenAddress,
+                amount: variables.tokenAmount,
+                chainId: destinationChainId,
+                indexerGatewayClient,
+                trailsClient,
+              })
+            logger.console.log(
+              "[trails-sdk] [useTrailsSendTransaction] Destination token balance check:",
+              {
+                tokenAddress: variables.tokenAddress,
+                tokenAmount: variables.tokenAmount,
+                chainId: destinationChainId,
+                hasSufficientBalance: hasSufficientDestinationTokenBalance,
+              },
+            )
+
+            // Step 3: Gas balance check will be done via QuoteIntent API in prepareSend
+            // The API provides comprehensive gas fee information including:
+            // - originGas: origin chain gas cost
+            // - destinationGas: destination chain gas cost (if applicable)
+            // - gasFeeOptions: fee options in different tokens
+            // If gas is insufficient, the system will fallback to gasless (handled in prepareSend)
+          }
+        } catch (balanceError) {
+          logger.console.warn(
+            "[trails-sdk] [useTrailsSendTransaction] Error checking balances, defaulting to origin selection:",
+            balanceError,
+          )
+          // If balance checks fail, default to opening modal (safe fallback)
+          hasSufficientOriginBalance = false
+          hasSufficientDestinationTokenBalance = false
+        }
+      }
+
+      // Determine if origin selection is needed
+      // Origin selection is needed when:
+      // 1. Origin parameters are not provided, OR
+      // 2. Origin balance is insufficient (user selected origin but doesn't have enough), OR
+      // 3. Destination token balance is insufficient (even if gas balance is sufficient)
+      // Note: Gas balance checks are done via QuoteIntent API after origin/destination are confirmed
+      const needsOriginSelection =
+        !hasOriginParams ||
+        !hasSufficientOriginBalance ||
+        !hasSufficientDestinationTokenBalance
+
+      logger.console.log(
+        "[trails-sdk] [useTrailsSendTransaction] Origin selection decision:",
+        {
+          hasOriginParams,
+          hasSufficientOriginBalance,
+          hasSufficientDestinationTokenBalance,
+          needsOriginSelection,
+        },
+      )
+
+      if (needsOriginSelection) {
+        const requireAmountInput = !(
+          variables.tokenAddress && variables.tokenAmount
+        )
+        const baseDetails: HostTransactionDetails = {
+          to: variables.to,
+          tokenAddress: variables.tokenAddress,
+          tokenAmount: variables.tokenAmount,
+          toChainId: destinationChainId,
+          data: variables.data,
+        }
+        mergeHostTransactionState({
+          status: "awaiting-origin",
+          details: baseDetails,
+          error: null,
+          result: null,
+        })
+        setHostTransactionQuote(null)
+        setHostTransactionStates([])
+        setHostTransactionTimestamp(Date.now())
+        // Open modal and wait for user selection
+        return new Promise<SwapReturn>((resolve, reject) => {
+          setPendingSelection({
+            resolve: async (selection) => {
+              try {
+                mergeHostTransactionState({ status: "confirmation" })
+                const result = await executeTransaction(variables, selection, {
+                  trackInWidget: true,
+                })
+                resolve(result)
+              } catch (error) {
+                // Don't override state for user rejections - they're handled in executeTransaction
+                // and stay on confirmation screen with retry enabled
+                const isUserRejection = getIsUserRejectionError(error)
+                if (!isUserRejection) {
+                  mergeHostTransactionState({
+                    status: "error",
+                    error: getFullErrorMessage(error as Error),
+                  })
+                }
+                reject(error as Error)
+              }
+            },
+            reject: (error) => {
+              const rejection =
+                error instanceof Error ? error : new Error(String(error))
+              mergeHostTransactionState({
+                status: "error",
+                error: getFullErrorMessage(rejection),
+              })
+              reject(rejection)
+            },
+            requireAmountInput,
+          })
+
+          // Open the modal after setting pending selection
+          // Use setTimeout to ensure state updates are processed
+          setTimeout(() => {
+            logger.console.log(
+              "[trails-sdk] [useTrailsSendTransaction] Calling openModal()",
+            )
+            openModal()
+          }, 0)
+        })
+      }
+
+      // Set up modal for wallet-confirmation, pending, and receipt screens
+      const baseDetails: HostTransactionDetails = {
+        to: variables.to,
+        tokenAddress: variables.tokenAddress,
+        tokenAmount: variables.tokenAmount,
+        toChainId: destinationChainId,
+        data: variables.data,
+      }
+      mergeHostTransactionState({
+        status: "confirmation",
+        details: baseDetails,
+        error: null,
+        result: null,
+      })
+      setHostTransactionQuote(null)
+      setHostTransactionStates([])
+      setHostTransactionTimestamp(Date.now())
+      openModal()
+
+      // Execute transaction directly with modal tracking
+      return executeTransaction(variables, undefined, { trackInWidget: true })
+    },
+    onSuccess: (data, variables) => {
+      logger.console.log(
+        "[trails-sdk] [useTrailsSendTransaction] Transaction successful",
+        { data, variables },
+      )
+      params?.onSuccess?.(data, variables)
+    },
+    onError: (error, variables) => {
+      logger.console.error(
+        "[trails-sdk] [useTrailsSendTransaction] Transaction error",
+        { error, variables },
+      )
+      const errorMessage = getFullErrorMessage(error)
+      // Don't override state for user rejections - they're handled in executeTransaction
+      // and stay on confirmation screen with retry enabled
+      const isUserRejection = getIsUserRejectionError(error)
+      if (hostTransactionState.status !== "idle" && !isUserRejection) {
+        mergeHostTransactionState({
+          status: "error",
+          error: errorMessage,
+        })
+      }
+      params?.onError?.(new Error(errorMessage), variables)
+    },
+    onSettled: (data, error, variables) => {
+      logger.console.log(
+        "[trails-sdk] [useTrailsSendTransaction] Transaction settled",
+        { data, error, variables },
+      )
+      params?.onSettled?.(data, error as Error | null, variables)
+    },
+  })
+
+  const sendTransaction = useCallback(
+    (
+      variables: TrailsSendTransactionVariables,
+      callbacks?: {
+        onSuccess?: (data: SwapReturn) => void
+        onError?: (error: Error) => void
+        onSettled?: (data: SwapReturn | undefined, error: Error | null) => void
+      },
+    ) => {
+      mutation.mutate(variables, {
+        onSuccess: (data) => {
+          callbacks?.onSuccess?.(data)
+        },
+        onError: (error) => {
+          callbacks?.onError?.(error as Error)
+        },
+        onSettled: (data, error) => {
+          callbacks?.onSettled?.(data, error as Error | null)
+        },
+      })
+    },
+    [mutation],
+  )
+
+  const sendTransactionAsync = useCallback(
+    async (
+      variables: TrailsSendTransactionVariables,
+      callbacks?: {
+        onSuccess?: (data: SwapReturn) => void
+        onError?: (error: Error) => void
+        onSettled?: (data: SwapReturn | undefined, error: Error | null) => void
+      },
+    ): Promise<SwapReturn> => {
+      return mutation.mutateAsync(variables, {
+        onSuccess: (data) => {
+          callbacks?.onSuccess?.(data)
+        },
+        onError: (error) => {
+          callbacks?.onError?.(error as Error)
+        },
+        onSettled: (data, error) => {
+          callbacks?.onSettled?.(data, error as Error | null)
+        },
+      })
+    },
+    [mutation],
+  )
+
+  // Retry function that re-executes with last variables
+  const retry = useCallback(() => {
+    if (lastTransactionVariablesRef.current) {
+      sendTransaction(lastTransactionVariablesRef.current)
+    }
+  }, [sendTransaction])
+
+  // Store retry function in ref so widget can call it (using ref to avoid re-renders)
+  retryTransactionRef.current = retry
+
+  return {
+    sendTransaction,
+    sendTransactionAsync,
+    retry,
+    data: mutation.data,
+    error: mutation.error as Error | null,
+    isPending: mutation.isPending,
+    isSuccess: mutation.isSuccess,
+    isError: mutation.isError,
+    isIdle: mutation.isIdle,
+    status: mutation.status,
+    reset: mutation.reset,
+    variables: mutation.variables,
+  }
+}