0xtrails 0.13.2 → 0.15.0

package/src/transactionIntent/types.ts

@@ -1,241 +0,0 @@
-import type {
-  Account,
-  Chain,
-  PublicClient,
-  TransactionReceipt,
-  WalletClient,
-} from "viem"
-import {
-  TradeType,
-  FundMethod as ApiFundMethod,
-  type TrailsApi,
-  type Intent,
-  type CommitIntentResponse,
-  type DepositSignature,
-  type FeeOption,
-  type GasFeeOptions,
-  type IntentProtocolVersion,
-  type ExecuteIntentResponse,
-  type RouteProvider,
-  type PriceImpactDetails,
-} from "@0xtrails/api"
-import type { QueryClient } from "@tanstack/react-query"
-
-export { TradeType }
-import type { TransactionState } from "../transactions.js"
-import type { Token } from "../tokens.js"
-import type { CheckoutOnHandlers } from "../widget/hooks/useCheckout.js"
-import type { RouteProviderInfo } from "../widget/hooks/useQuote.js"
-import type { TrailsFeeBreakdown } from "../fees.js"
-import type { IntentTransaction } from "@0xtrails/api"
-import type { OnrampTrackingData } from "../widget/types/analytics.js"
-
-export type FundMethod =
-  | "wallet"
-  | "direct-transfer"
-  | "onramp-mesh"
-  | "onramp-meld"
-
-/**
- * Maps SDK FundMethod (kebab-case) to API FundMethod enum (UPPER_SNAKE_CASE)
- */
-export function toApiFundMethod(fundMethod: FundMethod): ApiFundMethod {
-  switch (fundMethod) {
-    case "wallet":
-      return ApiFundMethod.WALLET
-    case "direct-transfer":
-      return ApiFundMethod.DIRECT_TRANSFER
-    case "onramp-mesh":
-      return ApiFundMethod.ONRAMP_MESH
-    case "onramp-meld":
-      return ApiFundMethod.ONRAMP_MELD
-  }
-}
-
-export function isExternalFundingMethod(
-  fundMethod: FundMethod | null | undefined,
-): fundMethod is Extract<
-  FundMethod,
-  "direct-transfer" | "onramp-mesh" | "onramp-meld"
-> {
-  return (
-    fundMethod === "direct-transfer" ||
-    fundMethod === "onramp-mesh" ||
-    fundMethod === "onramp-meld"
-  )
-}
-
-export type PrepareSendOptions = {
-  account: Account
-  originTokenAddress: string
-  originChainId: number
-  originTokenBalance: string
-  destinationChainId: number
-  recipient: string
-  destinationTokenAddress: string
-  swapAmount: string
-  tradeType?: TradeType
-  originTokenSymbol: string
-  destinationTokenSymbol: string
-  sequenceProjectAccessKey?: string
-  sequenceIndexerUrl?: string
-  client?: WalletClient
-  trailsClient: TrailsApi
-  destinationApproveAddress?: string
-  destinationCalldata?: string
-  onTransactionStateChange: (transactionStates: TransactionState[]) => void
-  sourceTokenPriceUsd?: number | null
-  destinationTokenPriceUsd?: number | null
-  sourceTokenDecimals: number
-  destinationTokenDecimals: number
-  paymasterUrl?: string
-  slippageTolerance?: string
-  originNativeTokenPriceUsd?: number | null
-  swapProvider?: RouteProvider | null
-  bridgeProvider?: RouteProvider | null
-  swapProviderFallback?: boolean
-  bridgeProviderFallback?: boolean
-  fundMethod?: FundMethod
-  mode?: "pay" | "fund" | "earn" | "swap" | "withdraw"
-  originPublicClient?: PublicClient
-  destinationPublicClient?: PublicClient
-  checkoutOnHandlers?: Partial<CheckoutOnHandlers>
-  refundAddress?: string
-  selectedFeeOption?: FeeOption | null
-  walletId?: string
-  abortSignal?: AbortSignal
-  isSmartWallet?: boolean
-  isSenderContractOnOrigin?: boolean | null
-  trailsApiKey?: string
-  trailsApiUrl?: string
-  sequenceMetadataUrl?: string
-  onramp?: OnrampTrackingData | null
-  // Optional QueryClient to use instead of the singleton (for decoupled mode)
-  queryClient?: QueryClient
-  // Optional mutation callbacks for React Query integration
-  commitIntentFn?: (intent: Intent) => Promise<CommitIntentResponse>
-  executeIntentFn?: (params: {
-    intentId: string
-    depositTransactionHash?: string
-    depositSignature?: DepositSignature
-  }) => Promise<ExecuteIntentResponse>
-}
-
-export type PrepareSendFees = {
-  feeTokenAddress: string | null
-  totalFeeAmount: string | null
-  totalFeeAmountUsd: string | null
-  totalFeeAmountUsdDisplay: string | null
-  totalFeeAmountUsdLocaleDisplay?: string | null
-}
-
-export type PrepareSendQuote = {
-  intentProtocol: IntentProtocolVersion
-  originDepositAddress: string
-  destinationDepositAddress: string
-  destinationAddress: string
-  destinationApproveAddress?: string
-  destinationCalldata: string
-  intentId?: string | null
-  expiresAt?: string | null
-  originChain: Chain
-  destinationChain: Chain
-  originAmount: string
-  originAmountDisplay: string
-  originAmountMin: string
-  originAmountMinDisplay: string
-  originAmountMinUsdFormatted: string
-  originAmountMinUsdDisplay: string
-  destinationAmount: string
-  destinationAmountDisplay: string
-  destinationAmountMin: string
-  destinationAmountMinDisplay: string
-  destinationAmountMinUsdFormatted: string
-  destinationAmountMinUsdDisplay: string
-  originAmountFormatted: string
-  originAmountFormattedLocale?: string
-  originAmountUsd?: number
-  fromAmountUsd?: number
-  originAmountUsdFormatted: string
-  originAmountUsdDisplay: string
-  originAmountUsdLocaleDisplay?: string
-  destinationAmountFormatted: string
-  destinationAmountFormattedLocale?: string
-  destinationAmountUsd?: number
-  toAmountUsd?: number
-  destinationAmountUsdFormatted: string
-  destinationAmountUsdDisplay: string
-  destinationAmountUsdLocaleDisplay?: string
-  originToken: Token
-  destinationToken: Token
-  fees: PrepareSendFees
-  slippageTolerance: string
-  maxSlippage?: number | null // Backend-calculated slippage when AUTO mode is used
-  priceImpact: string
-  priceImpactUsd?: string
-  priceImpactUsdDisplay: string
-  completionEstimateSeconds: number
-  completionEstimateDisplay: string
-  transactionStates: TransactionState[]
-  passthroughTransactionStates?: TransactionState[]
-  passthroughEligible?: boolean
-  gasCostUsd: number
-  gasCostUsdDisplay: string
-  gasCost: string
-  gasCostFormatted: string
-  originTokenRate: string
-  destinationTokenRate: string
-  originTokenPriceUsd: number
-  destinationTokenPriceUsd: number
-  routeProviders?: RouteProviderInfo[]
-  noSufficientBalance: boolean
-  trailsFeeBreakdown?: TrailsFeeBreakdown | null
-  totalFeesUsd?: number
-  totalFeesUsdDisplay?: string
-  // Fee breakdown values from extractTrailsFeeBreakdown
-  originGasUsd?: number
-  destinationGasUsd?: number
-  totalGasUsd?: number
-  providerFeeUsd?: number
-  trailsFeeUsd?: number
-  // Display values
-  originGasUsdDisplay?: string
-  destinationGasUsdDisplay?: string
-  totalGasUsdDisplay?: string
-  providerFeeUsdDisplay?: string
-  trailsFeeUsdDisplay?: string
-  totalProviderFeesUsd?: number
-  totalProviderFeesUsdDisplay?: string
-  // Locale display values
-  originGasUsdLocaleDisplay?: string
-  destinationGasUsdLocaleDisplay?: string
-  totalGasUsdLocaleDisplay?: string
-  providerFeeUsdLocaleDisplay?: string
-  trailsFeeUsdLocaleDisplay?: string
-  totalProviderFeesUsdLocaleDisplay?: string
-  priceImpactUsdLocaleDisplay?: string
-  priceImpactDetails?: PriceImpactDetails | null
-}
-
-export type PrepareSendReturn = {
-  quote: PrepareSendQuote
-  feeOptions?: GasFeeOptions
-  send: ({
-    onOriginSend,
-    selectedFeeOption,
-    depositTransactionHash,
-    skipCommit,
-  }: {
-    onOriginSend?: () => void
-    selectedFeeOption?: FeeOption | null
-    depositTransactionHash?: string
-    skipCommit?: boolean
-  }) => Promise<SendReturn>
-}
-
-export type SendReturn = {
-  depositUserTxnReceipt: TransactionReceipt | null
-  originIntentTransaction: IntentTransaction | null
-  destinationIntentTransaction: IntentTransaction | null
-  totalCompletionSeconds?: number
-}

package/src/transactionIntent/utils/balanceChecker.ts

@@ -1,103 +0,0 @@
-import type { Account, PublicClient } from "viem"
-import { erc20Abi, formatUnits } from "viem"
-import { InsufficientBalanceError } from "../../error.js"
-import { formatAmount } from "../../utils/format.js"
-import { logger } from "../../logger.js"
-import { isNativeToken } from "../../utils/address.js"
-
-/**
- * Check if the account has enough balance for the deposit amount
- */
-export async function checkAccountBalance({
-  account,
-  tokenAddress,
-  depositAmount,
-  publicClient,
-  knownBalance,
-  decimals: knownDecimals,
-}: {
-  account: Account
-  tokenAddress: string
-  depositAmount: string
-  publicClient: PublicClient
-  knownBalance?: string
-  decimals?: number
-}): Promise<{
-  hasEnoughBalance: boolean
-  balance: bigint
-  requiredAmount: bigint
-  balanceFormatted: string
-  requiredAmountFormatted: string
-  balanceError: Error | null
-}> {
-  try {
-    let balance: bigint
-
-    if (knownBalance !== undefined) {
-      balance = BigInt(knownBalance)
-    } else if (isNativeToken(tokenAddress)) {
-      balance = await publicClient.getBalance({ address: account.address })
-    } else {
-      balance = await publicClient.readContract({
-        address: tokenAddress as `0x${string}`,
-        abi: erc20Abi,
-        functionName: "balanceOf",
-        args: [account.address],
-      })
-    }
-
-    const requiredAmount = BigInt(depositAmount)
-
-    logger.console.log("[trails-sdk] balance", balance)
-    logger.console.log("[trails-sdk] requiredAmount", requiredAmount)
-    const hasEnoughBalance = balance >= requiredAmount
-    logger.console.log("[trails-sdk] hasEnoughBalance", hasEnoughBalance)
-
-    let balanceFormatted = ""
-    let requiredAmountFormatted = ""
-    if (isNativeToken(tokenAddress)) {
-      balanceFormatted = formatUnits(balance, 18)
-      requiredAmountFormatted = formatUnits(requiredAmount, 18)
-    } else if (knownDecimals !== undefined) {
-      balanceFormatted = formatUnits(balance, knownDecimals)
-      requiredAmountFormatted = formatUnits(requiredAmount, knownDecimals)
-    } else {
-      const decimals = await publicClient.readContract({
-        address: tokenAddress as `0x${string}`,
-        abi: erc20Abi,
-        functionName: "decimals",
-      })
-      if (!decimals) {
-        throw new Error("Decimals not found")
-      }
-      balanceFormatted = formatUnits(balance, decimals)
-      requiredAmountFormatted = formatUnits(requiredAmount, decimals)
-    }
-
-    let balanceError = null
-    if (!hasEnoughBalance) {
-      balanceError = new InsufficientBalanceError(
-        `Insufficient balance: Need ${formatAmount(requiredAmountFormatted)} ${tokenAddress} for ${account.address} on ${publicClient.chain?.name} but only have ${formatAmount(balanceFormatted)} ${tokenAddress}`,
-      )
-    }
-
-    return {
-      hasEnoughBalance,
-      balance,
-      balanceFormatted,
-      requiredAmount,
-      requiredAmountFormatted,
-      balanceError,
-    }
-  } catch (error) {
-    logger.console.error("[trails-sdk] Error checking account balance:", error)
-    return {
-      hasEnoughBalance: false,
-      balance: BigInt(0),
-      balanceFormatted: "0",
-      requiredAmount: BigInt(0),
-      requiredAmountFormatted: "0",
-      balanceError: error instanceof Error ? error : null,
-    }
-  }
-}

package/src/transactionIntent/utils/erc20Approval.ts

@@ -1,171 +0,0 @@
-import type {
-  Account,
-  Chain,
-  PublicClient,
-  TransactionReceipt,
-  WalletClient,
-} from "viem"
-import { erc20Abi } from "viem"
-import { logger } from "../../logger.js"
-import { SECOND_MS } from "../../utils/time.js"
-import { sendOriginTransaction } from "../../intents.js"
-import { encodeApproveCalldata } from "../../abis/erc20.js"
-import { getIsUserRejectionError } from "../../error.js"
-import type { CheckoutOnHandlers } from "../../widget/hooks/useCheckout.js"
-
-export interface EnsureErc20ApprovalParams {
-  /** The ERC20 token address */
-  tokenAddress: string
-  /** The spender address that needs approval */
-  spender: string
-  /** The required approval amount */
-  requiredAmount: bigint
-  /** The user's account */
-  account: Account
-  /** Public client for reading allowance */
-  publicClient: PublicClient
-  /** Wallet client for sending transactions */
-  walletClient: WalletClient
-  /** Chain for the transaction */
-  chain: Chain
-  /** Optional USD amount for analytics */
-  depositAmountUsd?: number
-  /** Optional checkout callbacks */
-  checkoutOnHandlers?: Partial<CheckoutOnHandlers>
-  /** Optional label for logging */
-  logPrefix?: string
-}
-
-/**
- * Ensures the spender has sufficient ERC20 allowance, prompting for approval if needed.
- *
- * Used by both passthrough flow (S4c) and intent flow for ERC20 tokens with custom calldata.
- * See SPEC.md for flow decision details.
- *
- * @returns true if approval was sent, false if already had sufficient allowance
- */
-export async function ensureErc20Approval({
-  tokenAddress,
-  spender,
-  requiredAmount,
-  account,
-  publicClient,
-  walletClient,
-  chain,
-  depositAmountUsd,
-  checkoutOnHandlers,
-  logPrefix = "[trails-sdk]",
-}: EnsureErc20ApprovalParams): Promise<boolean> {
-  // Check current allowance
-  const currentAllowance = (await publicClient.readContract({
-    address: tokenAddress as `0x${string}`,
-    abi: erc20Abi,
-    functionName: "allowance",
-    args: [account.address, spender as `0x${string}`],
-  })) as bigint
-
-  logger.console.log(`${logPrefix} ERC20 approval check:`, {
-    currentAllowance: currentAllowance.toString(),
-    requiredAmount: requiredAmount.toString(),
-    needsApproval: currentAllowance < requiredAmount,
-    spender,
-  })
-
-  if (currentAllowance >= requiredAmount) {
-    logger.console.log(`${logPrefix} Sufficient allowance, skipping approve`)
-    return false
-  }
-
-  logger.console.log(
-    `${logPrefix} Insufficient allowance, sending approve transaction...`,
-  )
-
-  const approveData = encodeApproveCalldata({
-    spender: spender as `0x${string}`,
-    amount: requiredAmount,
-  })
-
-  // Trigger approval request callback before sending transaction
-  if (checkoutOnHandlers?.triggerCheckoutApprovalRequest) {
-    checkoutOnHandlers.triggerCheckoutApprovalRequest()
-  }
-
-  let approveHash: `0x${string}`
-  let approveReceipt: TransactionReceipt
-  try {
-    approveHash = await sendOriginTransaction(
-      account,
-      walletClient,
-      {
-        to: tokenAddress as `0x${string}`,
-        data: approveData,
-        value: 0n,
-        chain,
-      },
-      {
-        transactionType: "token_approve",
-        ...(depositAmountUsd !== undefined && {
-          depositTokenAmountUsd: depositAmountUsd.toString(),
-        }),
-      },
-    )
-
-    // Trigger approval confirmed callback after hash is received
-    if (checkoutOnHandlers?.triggerCheckoutApprovalConfirmed) {
-      checkoutOnHandlers.triggerCheckoutApprovalConfirmed(approveHash)
-    }
-
-    approveReceipt = await publicClient.waitForTransactionReceipt({
-      hash: approveHash,
-      retryCount: 10,
-    })
-  } catch (error) {
-    // Check if this is a user rejection error
-    if (getIsUserRejectionError(error)) {
-      if (checkoutOnHandlers?.triggerCheckoutApprovalRejected) {
-        checkoutOnHandlers.triggerCheckoutApprovalRejected(error)
-      }
-      if (checkoutOnHandlers?.triggerCheckoutSignatureRejected) {
-        checkoutOnHandlers.triggerCheckoutSignatureRejected(error)
-      }
-    }
-    throw error
-  }
-
-  logger.console.log(
-    `${logPrefix} Approve transaction confirmed:`,
-    approveReceipt,
-  )
-
-  // Poll to ensure allowance is updated on-chain before proceeding
-  let updatedAllowance = currentAllowance
-  const maxPollAttempts = 15 // 30 seconds at 2s intervals
-  let pollAttempts = 0
-
-  while (updatedAllowance < requiredAmount && pollAttempts < maxPollAttempts) {
-    await new Promise((resolve) => setTimeout(resolve, 2 * SECOND_MS)) // Wait 2 seconds
-    updatedAllowance = (await publicClient.readContract({
-      address: tokenAddress as `0x${string}`,
-      abi: erc20Abi,
-      functionName: "allowance",
-      args: [account.address, spender as `0x${string}`],
-    })) as bigint
-    pollAttempts++
-    logger.console.log(
-      `${logPrefix} Polling allowance (attempt ${pollAttempts}): ${updatedAllowance.toString()}`,
-    )
-  }
-
-  if (updatedAllowance < requiredAmount) {
-    throw new Error(
-      "Allowance not updated after approve transaction - RPC may be delayed or transaction failed",
-    )
-  }
-
-  logger.console.log(
-    `${logPrefix} Allowance confirmed updated:`,
-    updatedAllowance.toString(),
-  )
-
-  return true
-}

package/src/transactionIntent/utils/index.ts

@@ -1,2 +0,0 @@
-export * from "./testnetHelpers.js"
-export * from "./balanceChecker.js"

package/src/transactionIntent/utils/resilientDepositTracker.ts

@@ -1,171 +0,0 @@
-import type { PublicClient, TransactionReceipt } from "viem"
-import { logger } from "../../logger.js"
-import { POLLING_INTERVALS } from "../constants.js"
-
-export interface ResilientDepositTrackerOptions {
-  publicClient: PublicClient
-  originChainId: number
-  originIntentAddress: string
-  originTokenAddress: string
-  depositAmount: string
-  txHash?: `0x${string}` | null
-  abortSignal?: AbortSignal
-  sequenceProjectAccessKey?: string
-  sequenceIndexerUrl?: string
-  maxRetries?: number
-  onDepositDetected?: (
-    txHash: `0x${string}` | null,
-    receipt: TransactionReceipt | null,
-  ) => void
-}
-
-/**
- * Resilient deposit tracker that validates a known deposit transaction hash
- * via receipt polling, including replacement tx handling.
- */
-export async function trackDepositResilient({
-  publicClient,
-  depositAmount,
-  txHash,
-  abortSignal,
-  maxRetries = 60, // 60 attempts = ~3 minutes with 3s intervals
-  onDepositDetected,
-}: ResilientDepositTrackerOptions): Promise<TransactionReceipt | null> {
-  logger.console.log("[trails-sdk] Starting resilient deposit tracking", {
-    hasHash: !!txHash,
-    txHash,
-    depositAmount,
-  })
-
-  if (!txHash) {
-    logger.console.warn(
-      "[trails-sdk] Resilient deposit tracker requires a tx hash; skipping receipt wait",
-    )
-    return null
-  }
-
-  if (abortSignal?.aborted) {
-    logger.console.log("[trails-sdk] Deposit tracking aborted by signal")
-    return null
-  }
-
-  let resolvedHash: `0x${string}` = txHash
-  const timeoutMs = maxRetries * POLLING_INTERVALS.TRANSACTION_RECEIPT
-  let timeoutId: ReturnType<typeof setTimeout> | null = null
-
-  try {
-    const receiptPromise = publicClient.waitForTransactionReceipt({
-      hash: txHash,
-      retryCount: maxRetries,
-      retryDelay: POLLING_INTERVALS.TRANSACTION_RECEIPT,
-      onReplaced: (replacement) => {
-        resolvedHash = replacement.transaction.hash
-        logger.console.log(
-          "[trails-sdk] Deposit transaction replaced while waiting for receipt",
-          {
-            reason: replacement.reason,
-            replacedHash: replacement.replacedTransaction.hash,
-            replacementHash: replacement.transaction.hash,
-          },
-        )
-      },
-    })
-
-    const timeoutPromise = new Promise<never>((_, reject) => {
-      timeoutId = setTimeout(() => {
-        reject(new Error("Timed out waiting for transaction receipt"))
-      }, timeoutMs)
-    })
-
-    const abortPromise = new Promise<never>((_, reject) => {
-      if (!abortSignal) return
-      abortSignal.addEventListener(
-        "abort",
-        () =>
-          reject(new Error("Aborted while waiting for transaction receipt")),
-        { once: true },
-      )
-    })
-
-    const receipt = await Promise.race([
-      receiptPromise,
-      timeoutPromise,
-      abortPromise,
-    ])
-
-    logger.console.log("[trails-sdk] Deposit transaction receipt found", {
-      hash: receipt.transactionHash,
-      status: receipt.status,
-      blockNumber: receipt.blockNumber,
-    })
-
-    if (onDepositDetected) {
-      onDepositDetected(resolvedHash, receipt)
-    }
-
-    return receipt
-  } catch (error) {
-    logger.console.warn(
-      "[trails-sdk] Could not get receipt for known transaction hash",
-      {
-        txHash,
-        resolvedHash,
-        timeoutMs,
-        error: (error as Error)?.message,
-      },
-    )
-    return null
-  } finally {
-    if (timeoutId) {
-      clearTimeout(timeoutId)
-    }
-  }
-}
-
-/**
- * Helper to determine if an error is recoverable via polling
- */
-export function isRecoverableDepositError(error: unknown): boolean {
-  if (!error) return false
-
-  const errorMessage = (error as Error)?.message?.toLowerCase() || ""
-  const errorCode = (error as any)?.code
-  const errorCodeLower =
-    typeof errorCode === "string" ? errorCode.toLowerCase() : errorCode
-
-  // User rejections are not recoverable (case-insensitive)
-  if (
-    errorCode === 4001 ||
-    errorCodeLower === "action_rejected" ||
-    errorMessage.includes("user rejected") ||
-    errorMessage.includes("user denied") ||
-    errorMessage.includes("rejected by user")
-  ) {
-    return false
-  }
-
-  // Specific recoverable errors (case-insensitive)
-  if (
-    errorMessage.includes("wallet timeout") ||
-    errorMessage.includes("an unknown rpc error occurred")
-  ) {
-    return true
-  }
-
-  // Other network/RPC errors are also recoverable (case-insensitive)
-  if (
-    errorMessage.includes("network") ||
-    errorMessage.includes("timeout") ||
-    errorMessage.includes("rpc") ||
-    errorMessage.includes("connection") ||
-    errorMessage.includes("fetch") ||
-    errorCodeLower === "network_error" ||
-    errorCodeLower === "timeout" ||
-    errorCode === -32603 // Internal JSON-RPC error (numeric, no case)
-  ) {
-    return true
-  }
-
-  // Unknown errors - DON'T attempt recovery by default (safer)
-  return false
-}

package/src/transactionIntent/utils/testnetHelpers.ts

@@ -1,5 +0,0 @@
-import { getQueryParam } from "../../queryParams.js"
-
-export function isTestnetDebugMode(): boolean {
-  return getQueryParam("testnet") === "true"
-}