0xtrails 0.12.0 → 0.12.2

package/src/widget/widget.tsx

@@ -17,7 +17,7 @@ import {
 } from "./providers/WidgetProviderTree.js"
 import { createWagmiConfig } from "./utils/createWagmiConfig.js"
 import { ShadowPortal } from "./components/ShadowPortal.js"
-import type { Chain, WalletClient } from "viem"
+import type { Chain, WalletClient, EIP1193Provider } from "viem"
 import {
   createWalletClient,
   custom,
@@ -35,6 +35,22 @@ interface EIP6963Connector extends Connector {
     icon?: string
   }
 }
+/** Transfer result data returned by an onramp provider on completion.
+ * Shape based on @meshconnect/web-link-sdk TransferFinishedPayload. */
+interface OnrampTransferResult {
+  status: string
+  txId: string
+  fromAddress: string
+  toAddress: string
+  symbol: string
+  amount: number
+  networkId: string
+  amountInFiat?: number
+  totalAmountInFiat?: number
+  networkName?: string
+  txHash?: string
+  transferId?: string
+}
 import {
   createStorage,
   useAccount,
@@ -57,16 +73,19 @@ import {
   getIsUserRejectionError,
   getPrettifiedErrorMessage,
 } from "../error.js"
+import { removeStoredIntent } from "../intentStorage.js"
 import { logger } from "../logger.js"
 import type { Mode } from "../mode.js"
 import type { Pool } from "../pools.js"
 import { usePools } from "../pools.js"
-import type { PrepareSendQuote } from "../prepareSend.js"
-import { isValidInteger, isValidNumeric } from "../prices.js"
+// TODO: temporary ignore this Biome warning for now; do not refactor code in this pass.
+// biome-ignore lint/style/useImportType: Keep current import shape for now per requested temporary ignores.
+import { type PrepareSendQuote } from "../prepareSend.js"
+import { isValidInteger, isValidNumeric } from "../utils/validation.js"
 import type { Theme } from "../theme.js"
 import type { Token } from "../tokens.js"
 import { getWethAddress } from "../tokens.js"
-import type { IntentTransaction, FeeOption } from "@0xtrails/api"
+import type { IntentTransaction } from "@0xtrails/api"
 import type { TransactionState } from "../transactions.js"
 import {
   useQRCodeWallets,
@@ -118,7 +137,7 @@ import { FundWalletSelection } from "./components/FundWalletSelection.js"
 import { WalletList } from "./components/WalletList.js"
 import { useBack } from "./hooks/useBack.js"
 import { useCheckout } from "./hooks/useCheckout.js"
-import { useCurrentScreen } from "./hooks/useCurrentScreen.js"
+import { useCurrentScreen, type Screen } from "./hooks/useCurrentScreen.js"
 import { useDebugScreens } from "./hooks/useDebugScreens.js"
 import { useEarnPool } from "./hooks/useEarnPool.js"
 import { useInitialRedirect } from "./hooks/useInitialRedirect.js"
@@ -150,6 +169,14 @@ import {
   isNativeToken,
   normalizeAddress,
 } from "../utils/address.js"
+import type { SendOptions, SwapReturn } from "./hooks/useQuote.js"
+import { hasFailedOrAbortedTransaction } from "./utils/transactionFailure.js"
+
+export type FundMethodListOption =
+  | "connected-wallet"
+  | "crypto-transfer"
+  | "cc-onramp"
+  | "exchange-onramp"
 
 // Validate toToken - must be "ETH", "USDC", or a valid hex address
 const isValidToToToken = (toToken: string | null | undefined) => {
@@ -203,7 +230,10 @@ export type TrailsWidgetProps = {
     sessionId: string
   }) => void
   onCheckoutStart?: (data: { sessionId: string }) => void
-  onCheckoutQuote?: (data: { sessionId: string; quote: any }) => void
+  onCheckoutQuote?: (data: {
+    sessionId: string
+    quote: PrepareSendQuote
+  }) => void
   onCheckoutSignatureRequest?: (data: { sessionId: string }) => void
   onCheckoutSignatureConfirmed?: (data: { sessionId: string }) => void
   onCheckoutSignatureRejected?: (data: {
@@ -235,6 +265,8 @@ export type TrailsWidgetProps = {
   disableCss?: boolean
   swapProvider?: string
   bridgeProvider?: string
+  swapProviderFallback?: boolean
+  bridgeProviderFallback?: boolean
   slippageTolerance?: number | string
   priceImpactWarningThresholdBps?: number
   priceImpactWarningMessage?: string
@@ -250,6 +282,26 @@ export type TrailsWidgetProps = {
     hideSwap?: boolean
     /** Array of wallet addresses to hide from the funding wallet selection. */
     hideWallets?: string[]
+    /**
+     * Ordered list of funding methods to display.
+     *
+     * Supported readable values (mapped internally):
+     * - "connected-wallet"
+     * - "crypto-transfer"
+     * - "cc-onramp"
+     * - "exchange-onramp"
+     *
+     * @example ["connected-wallet", "crypto-transfer"]
+     */
+    fundMethodsList?: FundMethodListOption[]
+    /**
+     * If true, methods not in fundMethodsList are hidden.
+     *
+     * If false (default), unlisted methods are shown but disabled.
+     *
+     * Default: false.
+     */
+    hideUnlistedFundMethods?: boolean
   }
   toast?: boolean
   appName?: string
@@ -269,8 +321,8 @@ export type TrailsWidgetProps = {
    * ```
    */
   onramp?: (handlers: {
-    setCurrentScreen: (screen: string) => void
-    onComplete?: (transferData: any) => void
+    setCurrentScreen: (screen: Screen) => void
+    onComplete?: (transferData: OnrampTransferResult) => void
     onError?: (error: unknown) => void
     onBack?: () => void
     toTokenSymbol?: string
@@ -306,17 +358,14 @@ const useWalletManager = (
           return
         }
 
-        const activeProvider = await connector.getProvider()
+        const activeProvider =
+          (await connector.getProvider()) as EIP1193Provider
 
         if (activeProvider && address && chainId) {
           // Validate that the provider's accounts include the expected address
           // This helps detect EIP-6963 multi-wallet mismatches where the wrong provider is used
           try {
-            const providerAccounts = await (
-              activeProvider as {
-                request: (args: { method: string }) => Promise<string[]>
-              }
-            ).request({
+            const providerAccounts = await activeProvider.request({
               method: "eth_accounts",
             })
             const normalizedAddress = normalizeAddress(address)
@@ -378,7 +427,7 @@ const useWalletManager = (
           const client = createWalletClient({
             account: address as `0x${string}`,
             chain,
-            transport: custom(activeProvider as any),
+            transport: custom(activeProvider),
           })
 
           setWalletClient(client)
@@ -562,6 +611,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     buttonText,
     swapProvider,
     bridgeProvider,
+    swapProviderFallback,
+    bridgeProviderFallback,
     priceImpactWarningThresholdBps,
     priceImpactWarningMessage,
     priceImpactFallbackBridgeUrl,
@@ -637,13 +688,20 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     },
   })
 
-  // Handle fromAccount preselection
+  // Handle fromAccount preselection (one-time only)
+  // We use a ref to ensure this only runs once on mount.
+  // Without this guard, the effect re-fires on every render cycle
+  // and overrides the user's wallet selection (e.g. switching back
+  // from MetaMask to Privy embedded wallet).
+  const hasInitializedFromAccount = useRef(false)
   useEffect(() => {
+    if (hasInitializedFromAccount.current) return
     if (!fromAccount) return
     if (!connections.length) return
 
     // Check if fromAccount is already the active account
     if (address && addressEqual(address, fromAccount)) {
+      hasInitializedFromAccount.current = true
       return
     }
 
@@ -664,6 +722,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       switchAccount({
         connector: targetConnection.connector,
       })
+      hasInitializedFromAccount.current = true
     } else {
       logger.console.log(
         "[trails-sdk] [TrailsWidget] fromAccount not found in connected wallets:",
@@ -730,15 +789,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   const [onrampProviderQuote, setOnrampProviderQuote] =
     useState<OnrampQuote | null>(null)
   const [prepareSendFn, setPrepareSendFn] = useState<
-    | ((options?: {
-        selectedFeeOption?: FeeOption | null
-        onOriginSend?: () => void
-        depositTransactionHash?: string
-        skipCommit?: boolean
-        commitOnly?: boolean
-        skipIntentMonitoring?: boolean
-      }) => Promise<any>)
-    | null
+    ((options?: SendOptions) => Promise<SwapReturn | null>) | null
   >(null)
 
   // Store widget creation parameters for retry functionality
@@ -796,11 +847,12 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     }
   }, [])
 
-  // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally reacts to configuredMode prop changes
+  const prevConfiguredModeRef = useRef(configuredMode)
   useEffect(() => {
-    if (isConnected) {
-      setCurrentScreen("home")
-    }
+    if (!isConnected) return
+    if (configuredMode === prevConfiguredModeRef.current) return
+    prevConfiguredModeRef.current = configuredMode
+    setCurrentScreen("home")
   }, [configuredMode, isConnected, setCurrentScreen])
 
   const goHome = useCallback(() => {
@@ -821,10 +873,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     getInitialScreenForMode,
   )
 
-  // Global wallet connection check, redirect to connect screen when disconnected
-  // This ensures a wallet must be connected to use any part of the widget
+  // Keep screen and wallet-connection state in sync without bouncing between screens
   useEffect(() => {
-    // Screens that are exempt from the connection requirement (connection-related screens)
     const connectionExemptScreens = [
       "connect",
       "wallet-connect",
@@ -832,11 +882,21 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       "wallet-list",
     ]
 
-    // If not connected and not on a connection-related screen, redirect to connect
     if (!isConnected && !connectionExemptScreens.includes(currentScreen)) {
       setCurrentScreen("connect")
+      return
     }
-  }, [isConnected, currentScreen, setCurrentScreen])
+
+    if (isConnected && connectionExemptScreens.includes(currentScreen)) {
+      setCurrentScreen(getInitialScreenForMode(currentMode))
+    }
+  }, [
+    isConnected,
+    currentScreen,
+    currentMode,
+    setCurrentScreen,
+    getInitialScreenForMode,
+  ])
 
   const modeToButtonText: Record<string, string> = {
     fund: "Fund",
@@ -1094,7 +1154,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     if (!transactionStates || transactionStates.length === 0) return
 
     const firstTx = transactionStates[0]
-    if (firstTx?.state === "failed" || firstTx?.state === "aborted") {
+    if (firstTx && hasFailedOrAbortedTransaction(firstTx)) {
       logger.console.log(
         `[trails-sdk] First transaction state is ${firstTx.state}, navigating to receipt`,
       )
@@ -1287,7 +1347,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
   const handleConnectWallet = async (
     walletId: string,
-    providedConnector?: any,
+    providedConnector?: Connector,
   ) => {
     try {
       setError(null)
@@ -1299,9 +1359,9 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
       if (!walletConnector) {
         // First, try to find an EIP-6963 connector that matches this wallet ID
-        const eip6963Connector = connectors.find((c: any) => {
+        const eip6963Connector = connectors.find((c) => {
           if (c.type !== "injected") return false
-          const rdns = c.info?.rdns
+          const rdns = (c as EIP6963Connector).info?.rdns
           if (rdns && WALLET_RDNS_MAP[rdns] === walletId) {
             logger.console.log(
               `[trails-sdk] Found EIP-6963 connector for ${walletId} with rdns ${rdns}`,
@@ -1335,6 +1395,12 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
         }
       }
 
+      if (!walletConnector) {
+        setError(`No connector available for wallet: ${walletId}`)
+        setIsConnecting(false)
+        return
+      }
+
       logger.console.log(
         "[trails-sdk] Initiating connection to wallet",
         walletId,
@@ -1705,6 +1771,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
   }
 
   const handleSendAnother = () => {
+    invalidateTokenBalancesCache()
     const initialScreen = getInitialScreenForMode(currentMode)
     setCurrentScreen(initialScreen)
     resetState()
@@ -1780,7 +1847,18 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     onOpen?.()
   }, [openTrailsModal, onOpen])
 
+  const screensWithCommittedIntent: Screen[] = [
+    "wallet-confirmation",
+    "onramp-confirmation",
+  ]
+
   const handleCloseModal = useCallback(() => {
+    if (
+      prepareSendQuote?.intentId &&
+      screensWithCommittedIntent.includes(currentScreen)
+    ) {
+      removeStoredIntent(prepareSendQuote.intentId)
+    }
     if (pendingSelection) {
       logger.console.log(
         "[trails-sdk] handleCloseModal called, rejecting pending selection",
@@ -1804,6 +1882,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
     onClose,
     pendingSelection,
     setPendingSelection,
+    prepareSendQuote,
+    currentScreen,
   ])
 
   // Register handleCloseModal with TrailsModalProvider so ScreenHeader can use it
@@ -1863,10 +1943,14 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       setDestinationChainId(lastTransactionState?.chainId)
     }
 
+    // clear the stored intent from local storage
+    if (prepareSendQuote?.intentId) {
+      removeStoredIntent(prepareSendQuote.intentId)
+    }
     setCurrentScreen("receipt")
   }
 
-  async function handleOnrampComplete(transferData: any) {
+  async function handleOnrampComplete(transferData: OnrampTransferResult) {
     logger.console.log("[trails-sdk] Onramp transfer completed:", transferData)
     logger.console.log(
       "[trails-sdk] Using real transaction states from prepareSendQuote",
@@ -2150,16 +2234,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
 
   const handleWaitingForWalletConfirm = (
     quote: PrepareSendQuote,
-    sendFn?:
-      | ((options?: {
-          selectedFeeOption?: FeeOption | null
-          onOriginSend?: () => void
-          depositTransactionHash?: string
-          skipCommit?: boolean
-          commitOnly?: boolean
-          skipIntentMonitoring?: boolean
-        }) => Promise<any>)
-      | null,
+    sendFn?: ((options?: SendOptions) => Promise<SwapReturn | null>) | null,
   ) => {
     setShowWalletConfirmRetry(false)
     setPrepareSendQuote(quote ?? null)
@@ -2204,14 +2279,7 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
       paymentMethodType?: string
     },
     sessionId?: string,
-    sendFn?:
-      | ((options?: {
-          selectedFeeOption?: FeeOption | null
-          onOriginSend?: () => void
-          depositTransactionHash?: string
-          skipCommit?: boolean
-        }) => Promise<any>)
-      | null,
+    sendFn?: ((options?: SendOptions) => Promise<SwapReturn | null>) | null,
     popupWindowRef?: Window | null,
   ) => {
     logger.console.log(
@@ -2477,6 +2545,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             setWalletConfirmRetryHandler={setWalletConfirmRetryHandler}
             swapProvider={swapProvider}
             bridgeProvider={bridgeProvider}
+            swapProviderFallback={swapProviderFallback}
+            bridgeProviderFallback={bridgeProviderFallback}
             fundMethod={selectedFundMethod}
             onAmountUpdate={(amount: string) => {
               if (
@@ -2535,6 +2605,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             setWalletConfirmRetryHandler={setWalletConfirmRetryHandler}
             swapProvider={swapProvider}
             bridgeProvider={bridgeProvider}
+            swapProviderFallback={swapProviderFallback}
+            bridgeProviderFallback={bridgeProviderFallback}
             fundMethod={selectedFundMethod}
             checkoutOnHandlers={checkoutOnHandlers}
             recentTokens={recentTokens}
@@ -2716,8 +2788,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
           return (
             <div className="flex flex-col h-full">
               {onrampFactory({
-                setCurrentScreen: (screen: string) => {
-                  setCurrentScreen(screen as any)
+                setCurrentScreen: (screen) => {
+                  setCurrentScreen(screen)
                 },
                 onComplete: handleOnrampComplete,
                 onError: (error) => {
@@ -2837,6 +2909,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             setWalletConfirmRetryHandler={setWalletConfirmRetryHandler}
             swapProvider={swapProvider}
             bridgeProvider={bridgeProvider}
+            swapProviderFallback={swapProviderFallback}
+            bridgeProviderFallback={bridgeProviderFallback}
             fundMethod={selectedFundMethod}
             checkoutOnHandlers={checkoutOnHandlers}
             recentTokens={recentTokens}
@@ -2878,6 +2952,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             setWalletConfirmRetryHandler={setWalletConfirmRetryHandler}
             swapProvider={swapProvider}
             bridgeProvider={bridgeProvider}
+            swapProviderFallback={swapProviderFallback}
+            bridgeProviderFallback={bridgeProviderFallback}
             fundMethod={selectedFundMethod}
             onAmountUpdate={undefined}
             checkoutOnHandlers={checkoutOnHandlers}
@@ -2910,6 +2986,8 @@ const WidgetContent = forwardRef<TrailsWidgetRef>((_, ref) => {
             setWalletConfirmRetryHandler={setWalletConfirmRetryHandler}
             swapProvider={swapProvider}
             bridgeProvider={bridgeProvider}
+            swapProviderFallback={swapProviderFallback}
+            bridgeProviderFallback={bridgeProviderFallback}
             checkoutOnHandlers={checkoutOnHandlers}
             recentTokens={recentTokens}
             onTrackToken={handleTrackToken}

package/src/widget/workers/intentExecutionWorker.ts

@@ -253,7 +253,9 @@ export class IntentExecutionWorker {
           status === IntentStatus.SUCCEEDED ||
           status === IntentStatus.FAILED ||
           status === IntentStatus.REFUNDED ||
-          status === IntentStatus.ABORTED
+          status === IntentStatus.ABORTED ||
+          status === IntentStatus.INVALID ||
+          status === IntentStatus.EXECUTING
         ) {
           logger.console.log(
             `[trails-sdk][intent-worker] Removing intent ${storedIntent.intentId} with final status: ${status}`,

package/dist/widget/hooks/useExchangeRate.d.ts

@@ -1,31 +0,0 @@
-interface UseExchangeRateOptions {
-    fromCurrency?: string;
-    toCurrency?: string;
-    disabled?: boolean;
-}
-interface UseExchangeRateResult {
-    exchangeRate: number | undefined;
-    isLoading: boolean;
-    error: Error | null;
-}
-/**
- * Wrapper hook for exchange rate fetching that abstracts the underlying implementation
- * This allows us to easily swap out the exchange rate provider in the future
- */
-export declare function useExchangeRate(options?: UseExchangeRateOptions): UseExchangeRateResult;
-/**
- * Hook to get exchange rate from USD to user's preferred display currency
- */
-export declare function useUsdToDisplayCurrencyRate(): UseExchangeRateResult;
-/**
- * Hook to convert USD amount to user's preferred display currency
- */
-export declare function useConvertUsdToDisplayCurrency(): {
-    convert: (usdAmount: number) => number;
-    formatAmount: (usdAmount: number) => string;
-    displayCurrency: string;
-    exchangeRate: number | undefined;
-    isLoading: boolean;
-};
-export {};
-//# sourceMappingURL=useExchangeRate.d.ts.map

package/dist/widget/hooks/useExchangeRate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useExchangeRate.d.ts","sourceRoot":"","sources":["../../../src/widget/hooks/useExchangeRate.ts"],"names":[],"mappings":"AAMA,UAAU,sBAAsB;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,UAAU,qBAAqB;IAC7B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAgED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA6EvB;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,qBAAqB,CASnE;AAED;;GAEG;AACH,wBAAgB,8BAA8B,IAAI;IAChD,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;IAC3C,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,SAAS,EAAE,OAAO,CAAA;CACnB,CAiCA"}

package/dist/widget/hooks/useFiatCurrencyList.d.ts

@@ -1,3 +0,0 @@
-import { FiatCurrency } from '@0xtrails/api';
-export declare function useFiatCurrencyList(): import('@tanstack/react-query').UseQueryResult<FiatCurrency[], Error>;
-//# sourceMappingURL=useFiatCurrencyList.d.ts.map

package/dist/widget/hooks/useFiatCurrencyList.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useFiatCurrencyList.d.ts","sourceRoot":"","sources":["../../../src/widget/hooks/useFiatCurrencyList.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAyCjD,wBAAgB,mBAAmB,0EAoBlC"}