0xtrails 0.2.5 → 0.3.0

package/src/transactionIntent/utils/balanceChecker.ts

@@ -0,0 +1,96 @@
+import type { Account, PublicClient } from "viem"
+import { erc20Abi, formatUnits, zeroAddress } from "viem"
+import { InsufficientBalanceError } from "../../error.js"
+import { formatAmount } from "../../tokenBalances.js"
+import { logger } from "../../logger.js"
+
+/**
+ * Check if the account has enough balance for the deposit amount
+ */
+export async function checkAccountBalance({
+  account,
+  tokenAddress,
+  depositAmount,
+  publicClient,
+}: {
+  account: Account
+  tokenAddress: string
+  depositAmount: string
+  publicClient: PublicClient
+}): Promise<{
+  hasEnoughBalance: boolean
+  balance: bigint
+  requiredAmount: bigint
+  balanceFormatted: string
+  requiredAmountFormatted: string
+  balanceError: Error | null
+}> {
+  try {
+    let balance: bigint
+
+    if (tokenAddress === zeroAddress) {
+      // Native token balance
+      balance = await publicClient.getBalance({ address: account.address })
+    } else {
+      // ERC20 token balance
+      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 (tokenAddress === zeroAddress) {
+      balanceFormatted = formatUnits(balance, 18)
+      requiredAmountFormatted = formatUnits(requiredAmount, 18)
+    } else {
+      // ERC20 token balance
+      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/index.ts

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

package/src/transactionIntent/utils/lifiHelpers.ts

@@ -0,0 +1,68 @@
+import { formatUnits, zeroAddress } from "viem"
+import { calcAmountUsdPrice } from "../../prices.js"
+import { logger } from "../../logger.js"
+
+// ETH fee required by some bridges for low token amounts
+// TODO: update backend API to return the native fee requirement, if any
+export function getNeedsLifiNativeFee({
+  originTokenAddress,
+  destinationTokenAmount,
+  destinationTokenDecimals,
+  sourceTokenDecimals,
+  sourceTokenPriceUsd,
+  destinationTokenPriceUsd,
+  depositAmount,
+}: {
+  originTokenAddress: string
+  destinationTokenAmount: string
+  destinationTokenDecimals: number
+  sourceTokenDecimals: number
+  sourceTokenPriceUsd: number | null
+  destinationTokenPriceUsd: number | null
+  depositAmount: string
+}): boolean {
+  let needsNativeFee = false
+  if (
+    originTokenAddress !== zeroAddress &&
+    sourceTokenPriceUsd &&
+    destinationTokenPriceUsd &&
+    depositAmount &&
+    destinationTokenDecimals !== undefined &&
+    sourceTokenDecimals !== undefined
+  ) {
+    // Convert from wei to token units using formatUnits
+    const destinationAmount = Number(
+      formatUnits(BigInt(destinationTokenAmount), destinationTokenDecimals),
+    )
+    const depositAmountFormatted = Number(
+      formatUnits(BigInt(depositAmount), sourceTokenDecimals),
+    )
+    logger.console.log("[trails-sdk] destinationAmount", destinationAmount)
+    logger.console.log(
+      "[trails-sdk] depositAmountFormatted",
+      depositAmountFormatted,
+    )
+    const destinationAmountUsd = calcAmountUsdPrice({
+      amount: destinationAmount,
+      usdPrice: destinationTokenPriceUsd,
+    })
+    const depositAmountUsd = calcAmountUsdPrice({
+      amount: depositAmountFormatted,
+      usdPrice: sourceTokenPriceUsd,
+    })
+    const diff = depositAmountUsd - destinationAmountUsd
+    logger.console.log(
+      "[trails-sdk] destinationAmountUsd",
+      destinationAmountUsd,
+      "[trails-sdk] depositAmountUsd",
+      depositAmountUsd,
+      "[trails-sdk] diff",
+      diff,
+    )
+    if (diff >= 0 && diff <= 0.02) {
+      needsNativeFee = true
+    }
+  }
+
+  return needsNativeFee
+}

package/src/transactionIntent/utils/testnetHelpers.ts

@@ -0,0 +1,10 @@
+import { getQueryParam } from "../../queryParams.js"
+import { getUSDCTokenAddress } from "../../cctp.js"
+
+export function isTestnetDebugMode(): boolean {
+  return getQueryParam("testnet") === "true"
+}
+
+export function getTestnetOriginTokenAddress(testnetChainId: number): string {
+  return getUSDCTokenAddress(testnetChainId)!
+}

package/src/transactionIntent/validators.ts

@@ -0,0 +1,57 @@
+import { getIsUsdcAddress } from "../cctp.js"
+
+export function isSameChain(
+  originChainId: number,
+  destinationChainId: number,
+): boolean {
+  return originChainId?.toString() === destinationChainId?.toString()
+}
+
+export function isSameToken(
+  originTokenAddress: string,
+  destinationTokenAddress: string,
+): boolean {
+  return (
+    originTokenAddress?.toLowerCase() === destinationTokenAddress?.toLowerCase()
+  )
+}
+
+export function isSameChainAndToken(
+  originChainId: number,
+  originTokenAddress: string,
+  destinationChainId: number,
+  destinationTokenAddress: string,
+): boolean {
+  return (
+    isSameChain(originChainId, destinationChainId) &&
+    isSameToken(originTokenAddress, destinationTokenAddress)
+  )
+}
+
+export function shouldUseCctp(
+  originTokenAddress: string,
+  destinationTokenAddress: string,
+  originChainId: number,
+  destinationChainId: number,
+) {
+  return (
+    getIsUsdcAddress(originTokenAddress, originChainId) &&
+    getIsUsdcAddress(destinationTokenAddress, destinationChainId)
+  )
+}
+
+export function validateCctpDestinationToken(
+  destinationTokenAddress: string,
+  destinationChainId: number,
+  quoteProvider?: string | null,
+): void {
+  // If CCTP provider is selected, destination token must be USDC
+  if (
+    quoteProvider === "cctp" &&
+    !getIsUsdcAddress(destinationTokenAddress, destinationChainId)
+  ) {
+    throw new Error(
+      `CCTP provider requires destination token to be USDC. Current destination token: ${destinationTokenAddress} on chain ${destinationChainId}. Please ensure the destination token is USDC as listed in the Circle CCTP documentation.`,
+    )
+  }
+}

package/src/transactions.ts

@@ -1,4 +1,3 @@
-import { createPublicClient, http } from "viem"
 import { useQuery } from "@tanstack/react-query"
 import { getChainInfo } from "./chains.js"
 import { getSequenceProjectAccessKey } from "./config.js"
@@ -9,6 +8,7 @@ import { bigintReplacer } from "./utils.js"
 import { getExplorerUrl } from "./explorer.js"
 import { SortOrder } from "@0xsequence/trails-api"
 import { getChainIndexerUrl } from "./indexerClient.js"
+import { abortControllerRegistry } from "./abortController.js"
 
 export type TransactionStateStatus =
   | "pending"
@@ -26,6 +26,7 @@ export type TransactionState = {
   decodedTrailsTokenSweeperEvents?: TrailsTokenSweeperEvent[]
   decodedGuestModuleEvents?: GuestModuleEvent[]
   refunded?: boolean
+  txnMinedAt?: string
 }
 
 export type TransferType = "SEND" | "RECEIVE"
@@ -99,6 +100,7 @@ export type GetAccountTransactionHistoryParams = {
   pageSize?: number
   includeMetadata?: boolean
   page?: number
+  abortSignal?: AbortSignal
 }
 
 // Standalone function to calculate time difference between two transactions
@@ -124,57 +126,25 @@ export async function getTxTimeDiff(
     return 0
   }
 
-  const firstChainInfo = getChainInfo(firstTx.chainId)
-  const lastChainInfo = getChainInfo(lastTx.chainId)
-  if (!firstChainInfo || !lastChainInfo) return 0
-
-  const firstClient = createPublicClient({
-    chain: firstChainInfo,
-    transport: http(),
-  })
-  const lastClient = createPublicClient({
-    chain: lastChainInfo,
-    transport: http(),
-  })
-
-  async function getBlockNumber(
-    client: ReturnType<typeof createPublicClient>,
-    tx: TransactionState,
-  ) {
-    if (tx.blockNumber) return BigInt(tx.blockNumber)
-    const receipt = await client.getTransactionReceipt({
-      hash: tx.transactionHash as `0x${string}`,
-    })
-    return receipt.blockNumber
-  }
-
-  async function getTimestamp(
-    client: ReturnType<typeof createPublicClient>,
-    blockNumber: bigint,
-  ) {
-    const block = await client.getBlock({ blockNumber })
-    return typeof block.timestamp === "bigint"
-      ? Number(block.timestamp)
-      : block.timestamp
-  }
-
   try {
-    const [firstBlockNumber, lastBlockNumber] = await Promise.all([
-      getBlockNumber(firstClient, firstTx),
-      getBlockNumber(lastClient, lastTx),
-    ])
-
-    const [firstTs, lastTs] = await Promise.all([
-      getTimestamp(firstClient, firstBlockNumber),
-      getTimestamp(lastClient, lastBlockNumber),
-    ])
-
-    const diff = lastTs - firstTs
-    if (diff < 1) {
-      return 1 // round up to 1 second
+    // Use txnMinedAt timestamps from API if available
+    if (firstTx.txnMinedAt && lastTx.txnMinedAt) {
+      const firstTs = new Date(firstTx.txnMinedAt).getTime() / 1000
+      const lastTs = new Date(lastTx.txnMinedAt).getTime() / 1000
+
+      const diff = lastTs - firstTs
+      if (diff < 1) {
+        return 1 // round up to 1 second
+      }
+
+      return diff
     }
 
-    return diff
+    // Fallback: return 0 if txnMinedAt is not available
+    logger.console.warn(
+      "[trails-sdk] txnMinedAt not available for transactions, cannot calculate time difference",
+    )
+    return 0
   } catch (error) {
     logger.console.error(
       "[trails-sdk] Error calculating transaction time difference:",
@@ -189,8 +159,8 @@ export async function getAccountTransactionHistory({
   accountAddress,
   pageSize = 10,
   page = 1,
-
   includeMetadata = true,
+  abortSignal,
 }: GetAccountTransactionHistoryParams): Promise<TransactionHistoryResponse> {
   const accessKey = getSequenceProjectAccessKey()
 
@@ -198,26 +168,51 @@ export async function getAccountTransactionHistory({
     throw new Error("Sequence project access key is required")
   }
 
-  // Get the chain-specific indexer URL
-  const chainIndexerUrl = getChainIndexerUrl(chainId)
-  if (!chainIndexerUrl) {
-    throw new Error(`Unsupported chain ID: ${chainId}`)
-  }
+  // Create a unique ID for this operation
+  const operationId = `account-tx-history-${chainId}-${accountAddress}-${page}-${Date.now()}`
 
-  const endpoint = `${chainIndexerUrl}/rpc/Indexer/GetTransactionHistory`
+  // Create an abort controller for this specific operation
+  const operationAbortController = new AbortController()
 
-  const requestBody = {
-    filter: {
-      accountAddress: accountAddress.toLowerCase(),
-    },
-    includeMetadata,
-    page: {
-      page,
-      pageSize,
-    },
-  }
+  // Register this operation with the global registry
+  abortControllerRegistry.register(operationId, operationAbortController)
 
   try {
+    // Check if we should abort before starting
+    if (abortSignal?.aborted || operationAbortController.signal.aborted) {
+      logger.console.log(
+        "[trails-sdk] Aborting account transaction history fetch",
+      )
+      throw new Error("Operation aborted")
+    }
+
+    // Get the chain-specific indexer URL
+    const chainIndexerUrl = getChainIndexerUrl(chainId)
+    if (!chainIndexerUrl) {
+      throw new Error(`Unsupported chain ID: ${chainId}`)
+    }
+
+    const endpoint = `${chainIndexerUrl}/rpc/Indexer/GetTransactionHistory`
+
+    const requestBody = {
+      filter: {
+        accountAddress: accountAddress.toLowerCase(),
+      },
+      includeMetadata,
+      page: {
+        page,
+        pageSize,
+      },
+    }
+
+    // Check abort signal before making the request
+    if (abortSignal?.aborted || operationAbortController.signal.aborted) {
+      logger.console.log(
+        "[trails-sdk] Aborting account transaction history fetch before request",
+      )
+      throw new Error("Operation aborted")
+    }
+
     const response = await fetch(endpoint, {
       method: "POST",
       headers: {
@@ -225,6 +220,7 @@ export async function getAccountTransactionHistory({
         "X-Access-Key": accessKey,
       },
       body: JSON.stringify(requestBody, bigintReplacer, 2),
+      signal: abortSignal || operationAbortController.signal,
     })
 
     if (!response.ok) {
@@ -246,11 +242,21 @@ export async function getAccountTransactionHistory({
       transactions,
     }
   } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      logger.console.log(
+        "[trails-sdk] Account transaction history fetch was aborted",
+      )
+      throw new Error("Operation aborted")
+    }
+
     logger.console.error(
       "[trails-sdk] Error fetching transaction history:",
       error,
     )
     throw error
+  } finally {
+    // Always unregister when operation completes or is aborted
+    abortControllerRegistry.unregister(operationId)
   }
 }
 
@@ -311,7 +317,7 @@ export type GetIntentTransactionHistoryParams = {
 }
 
 export async function getIntentTransactionHistory({
-  accountAddress,
+  accountAddress: _accountAddress,
   pageSize = 10,
   page = 1,
 }: GetIntentTransactionHistoryParams): Promise<IntentTransactionHistoryResponse> {
@@ -326,9 +332,7 @@ export async function getIntentTransactionHistory({
 
     // Use the hybrid client's getIntentTransactionHistory method which tries Trails API first, then Sequence API
     const result = await trailsClient.getIntentTransactionHistory({
-      accountAddress: accountAddress.toLowerCase(),
       page: {
-        page,
         pageSize,
         sort: [
           {
@@ -339,7 +343,24 @@ export async function getIntentTransactionHistory({
       },
     })
 
-    return result
+    // Note: The new API has a different IntentTransaction structure.
+    // We need to map the API response to our local type structure.
+    // For now, return an empty result as the API structure has changed significantly.
+    // TODO: Implement proper mapping from new API IntentTransaction to SDK IntentTransaction
+    return {
+      page: result.nextPage
+        ? {
+            page,
+            pageSize,
+            more: true,
+          }
+        : {
+            page,
+            pageSize,
+            more: false,
+          },
+      transactions: [], // TODO: Map result.transactions to SDK IntentTransaction format
+    }
   } catch (error) {
     logger.console.error(
       "[trails-sdk] Error fetching intent transaction history:",
@@ -355,6 +376,7 @@ export type UseAccountTransactionHistoryParams = {
   pageSize?: number
   page?: number
   includeMetadata?: boolean
+  abortSignal?: AbortSignal
 }
 
 export type UseAccountTransactionHistoryReturn = {
@@ -369,6 +391,7 @@ export function useAccountTransactionHistory({
   pageSize = 10,
   page = 1,
   includeMetadata = true,
+  abortSignal,
 }: UseAccountTransactionHistoryParams): UseAccountTransactionHistoryReturn {
   const { data, isLoading, error } = useQuery({
     queryKey: [
@@ -379,17 +402,21 @@ export function useAccountTransactionHistory({
       page,
       includeMetadata,
     ],
-    queryFn: async () => {
+    queryFn: async ({ signal }) => {
       if (!chainId || !accountAddress) {
         return undefined
       }
 
+      // Use the React Query signal if no external abort signal is provided
+      const effectiveSignal = abortSignal || signal
+
       return await getAccountTransactionHistory({
         chainId,
         accountAddress,
         pageSize,
         page,
         includeMetadata,
+        abortSignal: effectiveSignal,
       })
     },
     enabled: Boolean(chainId && accountAddress),