0xtrails 0.2.5 → 0.3.0

package/src/transactionIntent/index.ts

@@ -0,0 +1,9 @@
+// Re-export all public APIs
+export * from "./types.js"
+export * from "./constants.js"
+export * from "./validators.js"
+export * from "./utils/index.js"
+export * from "./quote/index.js"
+export * from "./execution/index.js"
+export * from "./deposits/index.js"
+export * from "./handlers/index.js"

package/src/transactionIntent/quote/feeExtractors.ts

@@ -0,0 +1,81 @@
+import type { Intent } from "@0xsequence/trails-api"
+import type { RelayQuote } from "../../relaySdk.js"
+import { zeroAddress } from "viem"
+import { formatUsdAmountDisplay } from "../../tokenBalances.js"
+import { logger } from "../../logger.js"
+import type { TradeType, PrepareSendFees } from "../types.js"
+
+export function getFeesFromIntent(
+  intent: Intent,
+  {
+    tradeType,
+    fromAmountUsd,
+    toAmountUsd,
+  }: { tradeType: TradeType; fromAmountUsd: number; toAmountUsd: number },
+): PrepareSendFees {
+  const totalFeeAmountUsd = intent.fees?.totalFeeUsd || 0
+  const totalFeeAmountUsdDisplay = formatUsdAmountDisplay(totalFeeAmountUsd)
+
+  logger.console.log("[trails-sdk] getFeesFromIntent", {
+    tradeType,
+    fromAmountUsd,
+    toAmountUsd,
+    totalFeeAmountUsd,
+    totalFeeAmountUsdDisplay,
+  })
+
+  return {
+    feeTokenAddress: intent.fees?.feeTokenAddress ?? zeroAddress,
+    totalFeeAmount: intent.fees?.totalFeeAmount?.toString() ?? "0",
+    totalFeeAmountUsd: totalFeeAmountUsd.toString(),
+    totalFeeAmountUsdDisplay,
+  }
+}
+
+export function getSlippageToleranceFromIntent(intent: Intent): string {
+  return intent.quote?.maxSlippage?.toString() ?? "0"
+}
+
+export function getPriceImpactFromIntent(intent: Intent): string {
+  return intent?.quote?.priceImpact?.toString() ?? "0"
+}
+
+export function getPriceImpactUsdFromIntent(intent: Intent): string {
+  return intent?.quote?.priceImpactUsd?.toString() ?? "0"
+}
+
+export function getFeesFromRelaySdkQuote(quote: RelayQuote): PrepareSendFees {
+  const totalFeeAmountUsd = quote?.fees?.relayer?.amount ?? 0
+  const totalFeeAmountUsdDisplay = formatUsdAmountDisplay(totalFeeAmountUsd)
+  return {
+    feeTokenAddress: quote?.fees?.relayer?.currency?.address ?? zeroAddress,
+    totalFeeAmount: quote?.fees?.relayer?.amount ?? "0",
+    totalFeeAmountUsd: totalFeeAmountUsd.toString(),
+    totalFeeAmountUsdDisplay,
+  }
+}
+
+export function getSlippageToleranceFromRelaySdkQuote(
+  quote: RelayQuote,
+): string {
+  return (
+    Number(quote?.details?.slippageTolerance?.origin?.percent ?? "0") / 100
+  ).toString()
+}
+
+export function getPriceImpactFromRelaySdkQuote(quote: RelayQuote): string {
+  return (quote?.details?.swapImpact?.percent ?? 0).toString()
+}
+
+export function getPriceImpactUsdFromRelaySdkQuote(quote: RelayQuote): string {
+  return (quote?.details?.swapImpact?.usd ?? 0).toString()
+}
+
+export function getZeroFees(): PrepareSendFees {
+  return {
+    feeTokenAddress: zeroAddress,
+    totalFeeAmount: "0",
+    totalFeeAmountUsd: "0",
+    totalFeeAmountUsdDisplay: formatUsdAmountDisplay(0),
+  }
+}

package/src/transactionIntent/quote/index.ts

@@ -0,0 +1,3 @@
+export * from "./quoteHelpers.js"
+export * from "./feeExtractors.js"
+export * from "./normalizeQuote.js"

package/src/transactionIntent/quote/normalizeQuote.ts

@@ -0,0 +1,367 @@
+import type { Intent } from "@0xsequence/trails-api"
+import type { TransactionState } from "../../transactions.js"
+import type { PrepareSendQuote, PrepareSendFees } from "../types.js"
+import type { QuoteProviderInfo } from "../../widget/hooks/useQuote.js"
+import { createPublicClient, formatUnits, http } from "viem"
+import { mainnet } from "viem/chains"
+import { getTokenInfo } from "../../tokens.js"
+import { getChainInfo } from "../../chains.js"
+import { logger } from "../../logger.js"
+import {
+  formatRawAmount,
+  formatAmount,
+  formatAmountDisplay,
+  formatUsdAmountDisplay,
+} from "../../tokenBalances.js"
+import { calcAmountUsdPrice } from "../../prices.js"
+import { getIsCustomCalldata } from "../../contractUtils.js"
+import {
+  estimateGasCost,
+  estimateGasCostUsd,
+  DEFAULT_MIN_GASLIMIT,
+} from "../../estimate.js"
+import { extractTrailsFeeBreakdown } from "../../fees.js"
+import { getZeroFees } from "./feeExtractors.js"
+
+// TODO: make this dyanamic
+export function getCompletionEstimateSeconds({
+  originChainId,
+  destinationChainId,
+}: {
+  originChainId: number
+  destinationChainId: number
+}): number {
+  if (originChainId === mainnet.id && destinationChainId === mainnet.id) {
+    return 60
+  }
+
+  if (originChainId === mainnet.id || destinationChainId === mainnet.id) {
+    return 45
+  }
+
+  return 15
+}
+
+export async function getNormalizedQuoteObject({
+  originDepositAddress,
+  destinationDepositAddress,
+  destinationAddress,
+  destinationCalldata,
+  originChainId,
+  destinationChainId,
+  originAmount,
+  originAmountMin,
+  destinationAmount,
+  destinationAmountMin,
+  originTokenAddress,
+  destinationTokenAddress,
+  originTokenPriceUsd,
+  destinationTokenPriceUsd,
+  transactionStates,
+  fees,
+  slippageTolerance,
+  priceImpact,
+  priceImpactUsd,
+  originNativeTokenPriceUsd,
+  quoteProvider,
+  noSufficientBalance,
+  estimatedGasLimit,
+  intent,
+}: {
+  originDepositAddress?: string
+  destinationDepositAddress?: string
+  destinationAddress?: string
+  destinationCalldata?: string
+  originChainId: number
+  destinationChainId?: number
+  originAmount: string
+  originAmountMin?: string
+  destinationAmount: string
+  destinationAmountMin?: string
+  originTokenAddress: string
+  destinationTokenAddress?: string
+  originTokenPriceUsd?: string | null
+  destinationTokenPriceUsd?: string | null
+  transactionStates?: TransactionState[]
+  fees?: PrepareSendFees
+  slippageTolerance?: string
+  priceImpact?: string
+  priceImpactUsd?: string
+  originNativeTokenPriceUsd?: number | null
+  quoteProvider?: string
+  noSufficientBalance?: boolean
+  estimatedGasLimit?: bigint
+  intent?: Intent
+}): Promise<PrepareSendQuote> {
+  if (!destinationChainId) {
+    throw new Error("Destination chain id is required")
+  }
+
+  if (!destinationTokenAddress && originChainId === destinationChainId) {
+    destinationTokenAddress = originTokenAddress
+  }
+
+  if (!destinationTokenAddress && originChainId === destinationChainId) {
+    destinationTokenAddress = originTokenAddress
+  }
+
+  if (!destinationTokenAddress) {
+    throw new Error("Destination token address is required")
+  }
+
+  const originToken = await getTokenInfo(originChainId, originTokenAddress)
+  const destinationToken = await getTokenInfo(
+    destinationChainId,
+    destinationTokenAddress,
+  )
+
+  const originChain = getChainInfo(originChainId)
+  const destinationChain = getChainInfo(destinationChainId)
+
+  if (!originToken || !destinationToken || !originChain || !destinationChain) {
+    logger.console.error("[trails-sdk] Token or chain not found", {
+      originToken,
+      destinationToken,
+      originChain,
+      destinationChain,
+    })
+    throw new Error("Token or chain not found")
+  }
+
+  const originAmountMinFormatted = formatRawAmount(
+    originAmountMin || "0",
+    originToken.decimals,
+  )
+  const originAmountMinUsdFormatted = formatAmount(
+    calcAmountUsdPrice({
+      amount: originAmountMinFormatted,
+      usdPrice: originTokenPriceUsd,
+    }),
+  )
+  const originAmountMinUsdDisplay = formatUsdAmountDisplay(
+    originAmountMinUsdFormatted,
+  )
+
+  const destinationAmountMinFormatted = formatRawAmount(
+    destinationAmountMin || "0",
+    destinationToken.decimals,
+  )
+  const destinationAmountMinUsdFormatted = formatAmount(
+    calcAmountUsdPrice({
+      amount: destinationAmountMinFormatted,
+      usdPrice: destinationTokenPriceUsd,
+    }),
+  )
+  const destinationAmountMinUsdDisplay = formatUsdAmountDisplay(
+    destinationAmountMinUsdFormatted,
+  )
+
+  const originAmountFormatted = formatRawAmount(
+    originAmount,
+    originToken.decimals,
+  )
+  const originAmountUsdFormatted = formatAmount(
+    calcAmountUsdPrice({
+      amount: originAmountFormatted,
+      usdPrice: originTokenPriceUsd,
+    }),
+  )
+  const originAmountUsdDisplay = formatUsdAmountDisplay(
+    originAmountUsdFormatted,
+  )
+
+  const destinationAmountFormatted = formatRawAmount(
+    destinationAmount,
+    destinationToken.decimals,
+  )
+  const destinationAmountUsdFormatted = formatAmount(
+    calcAmountUsdPrice({
+      amount: destinationAmountFormatted,
+      usdPrice: destinationTokenPriceUsd,
+    }),
+  )
+  const destinationAmountUsdDisplay = formatUsdAmountDisplay(
+    destinationAmountUsdFormatted,
+  )
+
+  const hasCustomCalldata = getIsCustomCalldata(destinationCalldata)
+
+  const publicClient = createPublicClient({
+    chain: originChain,
+    transport: http(),
+  })
+
+  let gasCostUsd: number = 0
+  let gasCostUsdDisplay: string = "0"
+  let gasCost: string = "0"
+  let gasCostFormatted: string = "0"
+  try {
+    if (originNativeTokenPriceUsd) {
+      // Use the actual estimated gas limit if provided, otherwise use default
+      // This ensures the quote gas cost matches what will be used in the actual transaction
+      const gasLimitForCost = estimatedGasLimit || DEFAULT_MIN_GASLIMIT
+
+      logger.console.log(
+        "[trails-sdk][gas-estimation] Calculating gas cost for quote with gasLimit:",
+        gasLimitForCost,
+        "(estimated:",
+        estimatedGasLimit,
+        "default:",
+        DEFAULT_MIN_GASLIMIT,
+        ")",
+      )
+
+      const gasCostWei = await estimateGasCost(publicClient, gasLimitForCost)
+      gasCost = gasCostWei.toString()
+      gasCostFormatted = formatUnits(gasCostWei, 18) // Native tokens always use 18 decimals
+
+      // Calculate USD value
+      gasCostUsd = await estimateGasCostUsd(
+        publicClient,
+        originNativeTokenPriceUsd,
+        gasLimitForCost,
+      )
+      gasCostUsdDisplay = formatUsdAmountDisplay(gasCostUsd)
+
+      logger.console.log(
+        "[trails-sdk][gas-estimation] Quote gas cost calculated:",
+        {
+          gasCostWei,
+          gasCost,
+          gasCostFormatted,
+          gasCostUsd,
+          gasCostUsdDisplay,
+        },
+      )
+    }
+  } catch (error) {
+    logger.console.error(
+      "[trails-sdk][gas-estimation] Error estimating gas cost for quote display",
+      error,
+    )
+  }
+
+  // Calculate exchange rates
+  const originTokenPrice = originTokenPriceUsd ? Number(originTokenPriceUsd) : 0
+  const destinationTokenPrice = destinationTokenPriceUsd
+    ? Number(destinationTokenPriceUsd)
+    : 0
+  const exchangeRates = getTokenExchangeRates(
+    originTokenPrice,
+    destinationTokenPrice,
+    originToken.symbol,
+    destinationToken.symbol,
+  )
+
+  let quoteProviderUrl = ""
+  if (quoteProvider === "cctp") {
+    quoteProviderUrl = "https://www.circle.com/"
+  } else if (quoteProvider === "relay") {
+    quoteProviderUrl = "https://relay.link/"
+  } else if (quoteProvider === "lifi") {
+    quoteProviderUrl = "https://li.fi/"
+  }
+
+  const quoteProviderNames = {
+    cctp: "Circle CCTP",
+    relay: "Relay",
+    lifi: "LiFi",
+  }
+
+  const quoteProviderName =
+    quoteProviderNames[quoteProvider as keyof typeof quoteProviderNames] ||
+    quoteProvider ||
+    ""
+  const quoteProviderInfo: QuoteProviderInfo = {
+    id: quoteProvider || "",
+    name: quoteProviderName || "",
+    url: quoteProviderUrl || "",
+  }
+
+  const priceImpactUsdDisplay = formatUsdAmountDisplay(priceImpactUsd)
+
+  // Extract fee breakdown from intent if available
+  let trailsFeeBreakdown = null
+  if (intent) {
+    trailsFeeBreakdown = await extractTrailsFeeBreakdown(intent)
+  }
+
+  return {
+    originDepositAddress: originDepositAddress || "",
+    destinationDepositAddress: destinationDepositAddress || "",
+    destinationAddress: destinationAddress || "",
+    destinationCalldata: hasCustomCalldata ? destinationCalldata || "" : "",
+    originAmount: originAmount || "0",
+    originAmountMin: originAmountMin || originAmount || "0",
+    originAmountMinUsdFormatted: originAmountMinUsdFormatted || "0",
+    originAmountMinUsdDisplay: originAmountMinUsdDisplay || "0",
+    destinationAmount: destinationAmount || "0",
+    destinationAmountMin: destinationAmountMin || destinationAmount || "0",
+    destinationAmountMinUsdFormatted: destinationAmountMinUsdFormatted || "0",
+    destinationAmountMinUsdDisplay: destinationAmountMinUsdDisplay || "0",
+    originAmountFormatted,
+    originAmountUsdFormatted,
+    originAmountUsdDisplay,
+    destinationAmountFormatted,
+    destinationAmountUsdFormatted,
+    destinationAmountUsdDisplay,
+    originToken,
+    destinationToken,
+    fees: fees || getZeroFees(),
+    slippageTolerance: slippageTolerance || "0",
+    priceImpact: priceImpact || "0",
+    priceImpactUsdDisplay: priceImpactUsdDisplay || "0",
+    originChain,
+    destinationChain,
+    completionEstimateSeconds: getCompletionEstimateSeconds({
+      originChainId,
+      destinationChainId,
+    }),
+    transactionStates: transactionStates || [],
+    gasCostUsd,
+    gasCostUsdDisplay,
+    gasCost,
+    gasCostFormatted,
+    originTokenRate: exchangeRates.originTokenRate,
+    destinationTokenRate: exchangeRates.destinationTokenRate,
+    originAmountDisplay: formatAmountDisplay(originAmountFormatted),
+    destinationAmountDisplay: formatAmountDisplay(destinationAmountFormatted),
+    originAmountMinDisplay: formatAmountDisplay(originAmountMinFormatted),
+    destinationAmountMinDisplay: formatAmountDisplay(
+      destinationAmountMinFormatted,
+    ),
+    quoteProvider: quoteProviderInfo,
+    noSufficientBalance: noSufficientBalance || false,
+    trailsFeeBreakdown,
+  }
+}
+
+function getTokenExchangeRates(
+  originTokenPrice: number,
+  destinationTokenPrice: number,
+  originTokenSymbol: string,
+  destinationTokenSymbol: string,
+): { originTokenRate: string; destinationTokenRate: string } {
+  if (originTokenPrice === 0 || destinationTokenPrice === 0) {
+    return {
+      originTokenRate: "0",
+      destinationTokenRate: "0",
+    }
+  }
+
+  const originToDestination = originTokenPrice / destinationTokenPrice
+  const destinationToOrigin = destinationTokenPrice / originTokenPrice
+
+  // Format the rates with appropriate precision
+  const originTokenRate = formatAmountDisplay(originToDestination, {
+    maxFractionDigits: destinationTokenSymbol === "USDC" ? 2 : 7,
+  })
+  const destinationTokenRate = formatAmountDisplay(destinationToOrigin, {
+    maxFractionDigits: originTokenSymbol === "USDC" ? 2 : 7,
+  })
+
+  return {
+    originTokenRate: `1 ${originTokenSymbol} = ${originTokenRate} ${destinationTokenSymbol}`,
+    destinationTokenRate: `1 ${destinationTokenSymbol} = ${destinationTokenRate} ${originTokenSymbol}`,
+  }
+}

package/src/transactionIntent/quote/quoteHelpers.ts

@@ -0,0 +1,53 @@
+import type { QuoteIntentRequest } from "@0xsequence/trails-api"
+import { QuoteProviderType } from "@0xsequence/trails-api"
+import { getIsCustomCalldata } from "../../contractUtils.js"
+import type { TradeType } from "../types.js"
+
+export function getIntentArgs(
+  mainSignerAddress: string,
+  originChainId: number,
+  originTokenAddress: string,
+  originTokenAmount: string,
+  destinationChainId: number,
+  destinationTokenAddress: string,
+  destinationTokenAmount: string,
+  recipient: string,
+  destinationCalldata: string | undefined,
+  _destinationSalt: string = Date.now().toString(),
+  slippageTolerance: string, // 0.03 = 3%
+  tradeType: TradeType,
+  provider?: string | null,
+): QuoteIntentRequest {
+  const hasCustomCalldata = getIsCustomCalldata(destinationCalldata)
+
+  if (!provider || provider === "auto") {
+    provider = undefined
+  }
+
+  const intentArgs: QuoteIntentRequest = {
+    ownerAddress: mainSignerAddress,
+    originChainId,
+    originTokenAddress,
+    originTokenAmount: BigInt(originTokenAmount),
+    destinationChainId,
+    destinationToAddress: recipient,
+    destinationTokenAddress: destinationTokenAddress,
+    destinationTokenAmount: BigInt(destinationTokenAmount),
+    destinationCallData: hasCustomCalldata ? destinationCalldata : "0x",
+    destinationCallValue: "0",
+    options: {
+      slippageTolerance: Number(slippageTolerance),
+      quoteProvider:
+        provider === "relay"
+          ? QuoteProviderType.RELAY
+          : provider === "cctp"
+            ? QuoteProviderType.CCTPV2
+            : provider === "lifi"
+              ? QuoteProviderType.LIFI
+              : undefined,
+    },
+    tradeType,
+  }
+
+  return intentArgs
+}

package/src/transactionIntent/types.ts

@@ -0,0 +1,157 @@
+import type { Account, Chain, TransactionReceipt, WalletClient } from "viem"
+import type {
+  TrailsAPIClient,
+  Intent,
+  CommitIntentResponse,
+  DepositSignature,
+  FeeOption,
+  GasFeeOptions,
+  ExecuteIntentResponse,
+} from "@0xsequence/trails-api"
+import type { TransactionState } from "../transactions.js"
+import type { SupportedToken } from "../tokens.js"
+import type { CheckoutOnHandlers } from "../widget/hooks/useCheckout.js"
+import type { QuoteProviderInfo } from "../widget/hooks/useQuote.js"
+import type { TrailsFeeBreakdown } from "../fees.js"
+import type { IntentTransaction } from "@0xsequence/trails-api"
+
+// Use native IntentTransaction from trails-api instead of deprecated MetaTxnReceipt
+export type MetaTxnReceipt = IntentTransaction
+
+// Flexible fee token type that accepts both full FeeOption and minimal fee token objects
+// Also accepts objects with amountUSD for widget components
+export type SelectedFeeToken =
+  | FeeOption
+  | {
+      tokenAddress: string
+      tokenSymbol?: string
+    }
+  | {
+      tokenAddress: string
+      tokenSymbol: string
+      tokenDecimals: number
+      amount: string
+      amountUSD: number
+      notEnoughBalance?: boolean
+      tokenImageUrl?: string
+      chainId?: number
+    }
+
+export enum TradeType {
+  EXACT_INPUT = "EXACT_INPUT",
+  EXACT_OUTPUT = "EXACT_OUTPUT",
+}
+
+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
+  fee: string
+  client?: WalletClient
+  dryMode: boolean
+  trailsClient: TrailsAPIClient
+  destinationCalldata?: string
+  onTransactionStateChange: (transactionStates: TransactionState[]) => void
+  sourceTokenPriceUsd?: number | null
+  destinationTokenPriceUsd?: number | null
+  sourceTokenDecimals: number
+  destinationTokenDecimals: number
+  paymasterUrl?: string
+  gasless?: boolean
+  slippageTolerance?: string
+  originNativeTokenPriceUsd?: number | null
+  quoteProvider?: string | null
+  fundMethod?: string
+  mode?: "pay" | "fund" | "earn" | "swap" | "receive"
+  checkoutOnHandlers?: CheckoutOnHandlers
+  refundAddress?: string
+  selectedFeeToken?: SelectedFeeToken
+  walletId?: string
+  abortSignal?: AbortSignal
+  // 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
+}
+
+export type PrepareSendQuote = {
+  originDepositAddress: string
+  destinationDepositAddress: string
+  destinationAddress: string
+  destinationCalldata: string
+  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
+  originAmountUsdFormatted: string
+  originAmountUsdDisplay: string
+  destinationAmountFormatted: string
+  destinationAmountUsdFormatted: string
+  destinationAmountUsdDisplay: string
+  originToken: SupportedToken
+  destinationToken: SupportedToken
+  fees: PrepareSendFees
+  slippageTolerance: string
+  priceImpact: string
+  priceImpactUsdDisplay: string
+  completionEstimateSeconds: number
+  transactionStates: TransactionState[]
+  gasCostUsd: number
+  gasCostUsdDisplay: string
+  gasCost: string
+  gasCostFormatted: string
+  originTokenRate: string
+  destinationTokenRate: string
+  quoteProvider: QuoteProviderInfo | null
+  noSufficientBalance: boolean
+  trailsFeeBreakdown?: TrailsFeeBreakdown | null
+}
+
+export type PrepareSendReturn = {
+  quote: PrepareSendQuote
+  feeOptions?: GasFeeOptions
+  send: ({
+    onOriginSend,
+    selectedFeeToken,
+  }: {
+    onOriginSend?: () => void
+    selectedFeeToken?: SelectedFeeToken
+  }) => Promise<SendReturn>
+}
+
+export type SendReturn = {
+  depositUserTxnReceipt: TransactionReceipt | null
+  originMetaTxnReceipt: MetaTxnReceipt | null
+  destinationMetaTxnReceipt: MetaTxnReceipt | null
+  totalCompletionSeconds?: number
+}