0xtrails 0.1.3 → 0.1.4

package/src/decoders.ts

@@ -0,0 +1,310 @@
+import type { TransactionReceipt, Log } from "viem"
+import { decodeEventLog, parseAbiItem } from "viem"
+
+// Corrected ABI items
+const CALL_SUCCEEDED_ABI = parseAbiItem(
+  "event CallSucceeded(bytes32 _opHash, uint256 _index)",
+)
+
+const CALL_FAILED_ABI = parseAbiItem(
+  "event CallFailed(bytes32 _opHash, uint256 _index, bytes _returnData)",
+)
+
+const CALL_ABORTED_ABI = parseAbiItem(
+  "event CallAborted(bytes32 _opHash, uint256 _index, bytes _returnData)",
+)
+
+// only `deploymentId` is indexed
+const CALL_SKIPPED_ABI = parseAbiItem(
+  "event CallSkipped(bytes32 indexed deploymentId, uint256 actionIndex)",
+)
+
+// Refund / Sweep events come from the Trails Token Sweeper contract.
+// Contract source and event definitions:
+// - https://github.com/0xsequence/trails-contracts/pull/28
+// - https://github.com/0xsequence/stack/pull/1249
+const REFUND_ABI = parseAbiItem(
+  "event Refund(address indexed token, address indexed recipient, uint256 amount)",
+)
+
+const SWEEP_ABI = parseAbiItem(
+  "event Sweep(address indexed token, address indexed recipient, uint256 amount)",
+)
+
+// Event types
+export interface CallSucceededEvent {
+  type: "CallSucceeded"
+  opHash: string
+  index: bigint
+  log: Log
+}
+
+export interface CallFailedEvent {
+  type: "CallFailed"
+  opHash: string
+  index: bigint
+  returnData: string
+  log: Log
+}
+
+export interface CallAbortedEvent {
+  type: "CallAborted"
+  opHash: string
+  index: bigint
+  returnData: string
+  log: Log
+}
+
+export interface CallSkippedEvent {
+  type: "CallSkipped"
+  deploymentId: string
+  actionIndex: bigint
+  log: Log
+}
+
+export interface RefundEvent {
+  type: "Refund"
+  token: string
+  recipient: string
+  amount: bigint
+  log: Log
+}
+
+export interface SweepEvent {
+  type: "Sweep"
+  token: string
+  recipient: string
+  amount: bigint
+  log: Log
+}
+
+export type GuestModuleEvent =
+  | CallSucceededEvent
+  | CallFailedEvent
+  | CallAbortedEvent
+  | CallSkippedEvent
+
+// Trails Token Sweeper events: see PR references above for canonical specs.
+export type TrailsTokenSweeperEvent = RefundEvent | SweepEvent
+
+// === Decoders ===
+
+export function decodeCallSucceeded(log: Log): CallSucceededEvent | null {
+  try {
+    const decoded = decodeEventLog({
+      abi: [CALL_SUCCEEDED_ABI],
+      data: log.data,
+      topics: log.topics,
+      strict: false,
+    }) as {
+      eventName: "CallSucceeded"
+      args: { _opHash: string; _index: bigint }
+    }
+
+    return {
+      type: "CallSucceeded",
+      opHash: decoded.args._opHash,
+      index: decoded.args._index,
+      log,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function decodeCallFailed(log: Log): CallFailedEvent | null {
+  try {
+    const decoded = decodeEventLog({
+      abi: [CALL_FAILED_ABI],
+      data: log.data,
+      topics: log.topics,
+      strict: false,
+    }) as {
+      eventName: "CallFailed"
+      args: { _opHash: string; _index: bigint; _returnData: string }
+    }
+
+    return {
+      type: "CallFailed",
+      opHash: decoded.args._opHash,
+      index: decoded.args._index,
+      returnData: decoded.args._returnData,
+      log,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function decodeCallAborted(log: Log): CallAbortedEvent | null {
+  try {
+    const decoded = decodeEventLog({
+      abi: [CALL_ABORTED_ABI],
+      data: log.data,
+      topics: log.topics,
+      strict: false,
+    }) as {
+      eventName: "CallAborted"
+      args: { _opHash: string; _index: bigint; _returnData: string }
+    }
+
+    return {
+      type: "CallAborted",
+      opHash: decoded.args._opHash,
+      index: decoded.args._index,
+      returnData: decoded.args._returnData,
+      log,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function decodeCallSkipped(log: Log): CallSkippedEvent | null {
+  try {
+    const decoded = decodeEventLog({
+      abi: [CALL_SKIPPED_ABI],
+      data: log.data,
+      topics: log.topics,
+      strict: false,
+    }) as {
+      eventName: "CallSkipped"
+      args: { deploymentId: string; actionIndex: bigint }
+    }
+
+    return {
+      type: "CallSkipped",
+      deploymentId: decoded.args.deploymentId,
+      actionIndex: decoded.args.actionIndex,
+      log,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function decodeRefund(log: Log): RefundEvent | null {
+  try {
+    const decoded = decodeEventLog({
+      abi: [REFUND_ABI],
+      data: log.data,
+      topics: log.topics,
+      strict: false,
+    }) as {
+      eventName: "Refund"
+      args: { token: string; recipient: string; amount: bigint }
+    }
+
+    return {
+      type: "Refund",
+      token: decoded.args.token,
+      recipient: decoded.args.recipient,
+      amount: decoded.args.amount,
+      log,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function decodeSweep(log: Log): SweepEvent | null {
+  try {
+    const decoded = decodeEventLog({
+      abi: [SWEEP_ABI],
+      data: log.data,
+      topics: log.topics,
+      strict: false,
+    }) as {
+      eventName: "Sweep"
+      args: { token: string; recipient: string; amount: bigint }
+    }
+
+    return {
+      type: "Sweep",
+      token: decoded.args.token,
+      recipient: decoded.args.recipient,
+      amount: decoded.args.amount,
+      log,
+    }
+  } catch {
+    return null
+  }
+}
+
+// === Main decoder ===
+
+export function decodeTrailsTokenSweeperEvents(
+  receipt: TransactionReceipt,
+): TrailsTokenSweeperEvent[] {
+  const events: TrailsTokenSweeperEvent[] = []
+
+  for (const log of receipt.logs) {
+    const refund = decodeRefund(log)
+    if (refund) {
+      events.push(refund)
+      continue
+    }
+
+    const sweep = decodeSweep(log)
+    if (sweep) {
+      events.push(sweep)
+    }
+  }
+
+  return events
+}
+
+export function decodeGuestModuleEvents(
+  receipt: TransactionReceipt,
+): GuestModuleEvent[] {
+  const events: GuestModuleEvent[] = []
+
+  for (const log of receipt.logs) {
+    const succeeded = decodeCallSucceeded(log)
+    if (succeeded) {
+      events.push(succeeded)
+      continue
+    }
+
+    const failed = decodeCallFailed(log)
+    if (failed) {
+      events.push(failed)
+      continue
+    }
+
+    const aborted = decodeCallAborted(log)
+    if (aborted) {
+      events.push(aborted)
+      continue
+    }
+
+    const skipped = decodeCallSkipped(log)
+    if (skipped) {
+      events.push(skipped)
+    }
+  }
+
+  return events
+}
+
+// === Utilities ===
+
+export function getEventsByType<T extends GuestModuleEvent["type"]>(
+  events: GuestModuleEvent[],
+  type: T,
+): Extract<GuestModuleEvent, { type: T }>[] {
+  return events.filter(
+    (event): event is Extract<GuestModuleEvent, { type: T }> =>
+      event.type === type,
+  )
+}
+
+export function getFirstEventByType<T extends GuestModuleEvent["type"]>(
+  events: GuestModuleEvent[],
+  type: T,
+): Extract<GuestModuleEvent, { type: T }> | undefined {
+  return events.find(
+    (event): event is Extract<GuestModuleEvent, { type: T }> =>
+      event.type === type,
+  )
+}

package/src/ens.ts

@@ -1,5 +1,5 @@
 import { mainnet } from "viem/chains"
-import { useEnsAddress } from "wagmi"
+import { useEnsAddress, useEnsName } from "wagmi"
 
 export function useResolveEnsAddress({ textInput }: { textInput: string }) {
   const { data: ensAddress, isLoading } = useEnsAddress({
@@ -15,3 +15,18 @@ export function useResolveEnsAddress({ textInput }: { textInput: string }) {
     isLoading,
   }
 }
+
+export function useResolveEnsName({ address }: { address: string }) {
+  const { data: ensName, isLoading } = useEnsName({
+    address: address?.startsWith("0x") ? (address as `0x${string}`) : undefined,
+    chainId: mainnet.id,
+    query: {
+      enabled: !!address && address.startsWith("0x"),
+    },
+  })
+
+  return {
+    ensName,
+    isLoading,
+  }
+}

package/src/error.ts

@@ -42,7 +42,9 @@ export class InsufficientBalanceError extends Error {
 }
 
 export function getIsApiError(err: unknown) {
-  const isApiError = /request aborted/gi.test(getErrorString(err).toLowerCase())
+  const isApiError = /request aborted|not deployed/gi.test(
+    getErrorString(err).toLowerCase(),
+  )
   return isApiError
 }
 
@@ -52,3 +54,86 @@ export function getIsRateLimitedError(err: unknown) {
   )
   return isRateLimited
 }
+
+export function getIsRequiredAmountNotMetError(err: unknown) {
+  // Example error:
+  // GetIntentsQuote failed: total required amount (196159816026182793237) exceeds user-specified maximum (21960919303474978846)
+  const isRequiredAmountNotMet = /exceeds user-specified maximum/gi.test(
+    getErrorString(err).toLowerCase(),
+  )
+  return isRequiredAmountNotMet
+}
+
+export function getIsNoAvailableQuoteError(err: unknown) {
+  const isNoAvailableQuote =
+    /no available quotes|failed to get quote from any provider/gi.test(
+      getErrorString(err).toLowerCase(),
+    )
+  return isNoAvailableQuote
+}
+
+export function getIsQuoteFailedError(err: unknown) {
+  const isQuoteFailed = /GetIntentsQuote failed/gi.test(
+    getErrorString(err).toLowerCase(),
+  )
+  return isQuoteFailed
+}
+
+export function getIsQuoteTokenError(err: unknown) {
+  const isQuoteTokenError =
+    /requires destination token to be USDC|Token or chain not found/gi.test(
+      getErrorString(err).toLowerCase(),
+    )
+  return isQuoteTokenError
+}
+
+export function getIsQuoteInputError(err: unknown) {
+  const isQuoteInputError =
+    /Invalid input or output currency|originTokenAmount must be greater than zero|trails fee is greater than the origin token amount/gi.test(
+      getErrorString(err).toLowerCase(),
+    )
+  return isQuoteInputError
+}
+
+export function getIsInsufficientLiquidityError(err: unknown) {
+  const isInsufficientLiquidity =
+    /insufficient liquidity|higher than the available liquidity/gi.test(
+      getErrorString(err).toLowerCase(),
+    )
+  return isInsufficientLiquidity
+}
+
+export function getPrettifiedErrorMessage(
+  err: unknown,
+  defaultMessage: string = "",
+) {
+  const isRequiredAmountNotMet = getIsRequiredAmountNotMetError(err)
+  if (isRequiredAmountNotMet) {
+    return "The requested amount is too low to retrieve a quote or the account has insufficient funds to meet the required amount. Try again with a higher amount or make sure you have enough funds."
+  }
+  const isInsufficientLiquidity = getIsInsufficientLiquidityError(err)
+  if (isInsufficientLiquidity) {
+    return "The requested amount is too high to retrieve a quote. Try again with a lower amount."
+  }
+  const isNoAvailableQuote = getIsNoAvailableQuoteError(err)
+  if (isNoAvailableQuote) {
+    return "No quote found for the selected pair and/or amount. Try again with a different pair and/or amount."
+  }
+  const isQuoteTokenError = getIsQuoteTokenError(err)
+  if (isQuoteTokenError) {
+    return "The selected token is not supported. Please try again with a different token."
+  }
+  const isQuoteInputError = getIsQuoteInputError(err)
+  if (isQuoteInputError) {
+    return "No quote found for the input amount. Try again with a higher amount."
+  }
+  const isQuoteFailed = getIsQuoteFailedError(err)
+  if (isQuoteFailed) {
+    return "No quote found for the selected pair and amount."
+  }
+  const isApiError = getIsApiError(err)
+  if (isApiError) {
+    return "An API error occurred. Please try again later."
+  }
+  return defaultMessage
+}

package/src/intents.ts

@@ -6,12 +6,12 @@ import type {
   IntentCallsPayload,
   IntentPrecondition,
   SequenceAPIClient,
-} from "@0xsequence/api"
+} from "@0xsequence/trails-api"
 
 export type {
   IntentCallsPayload,
   IntentPrecondition,
-} from "@0xsequence/api"
+} from "@0xsequence/trails-api"
 
 import { Config, type Context, Payload } from "@0xsequence/wallet-primitives"
 import {
@@ -116,6 +116,7 @@ export type SendOriginCallTxArgs = {
 export async function getIntentCallsPayloads(
   apiClient: SequenceAPIClient,
   args: GetIntentCallsPayloadsArgs,
+  additionalTrackingProps: Record<string, string> = {},
 ): Promise<GetIntentCallsPayloadsReturn> {
   const localApiIntent = getQueryParam("localapiintent") === "true"
   if (localApiIntent) {
@@ -133,6 +134,7 @@ export async function getIntentCallsPayloads(
     originTokenAddress: args.originTokenAddress,
     destinationTokenAddress: args.destinationTokenAddress,
     userAddress: args.userAddress,
+    ...additionalTrackingProps,
   })
 
   try {
@@ -162,6 +164,7 @@ export async function getIntentCallsPayloads(
       feeToken: result.trailsFee?.feeToken,
       userAddress: args.userAddress,
       intentAddress: result.originIntentAddress,
+      ...additionalTrackingProps,
     })
 
     return result
@@ -174,6 +177,7 @@ export async function getIntentCallsPayloads(
       destinationChainId: args.destinationChainId || 0,
       originTokenAddress: args.originTokenAddress,
       destinationTokenAddress: args.destinationTokenAddress,
+      ...additionalTrackingProps,
     })
     throw error
   }
@@ -259,6 +263,7 @@ export async function commitIntentConfig(
   mainSignerAddress: string,
   calls: Array<IntentCallsPayload>,
   preconditions: Array<IntentPrecondition>,
+  additionalTrackingProps: Record<string, string> = {},
 ): Promise<CommitIntentConfigReturn> {
   console.log("[trails-sdk] commitIntentConfig inputs:", {
     mainSignerAddress,
@@ -323,6 +328,7 @@ export async function commitIntentConfig(
       destinationChainId: destinationChainIdStr
         ? Number(destinationChainIdStr)
         : undefined,
+      ...additionalTrackingProps,
     })
 
     const result = await apiClient.commitIntentConfig({
@@ -338,6 +344,7 @@ export async function commitIntentConfig(
       destinationChainId: destinationChainIdStr
         ? Number(destinationChainIdStr)
         : undefined,
+      ...additionalTrackingProps,
     })
 
     return result
@@ -351,6 +358,7 @@ export async function commitIntentConfig(
       destinationChainId: destinationChainIdStr
         ? Number(destinationChainIdStr)
         : undefined,
+      ...additionalTrackingProps,
     })
     throw error
   }

package/src/metaTxns.ts

@@ -1,4 +1,4 @@
-import type { IntentPrecondition } from "@0xsequence/api"
+import type { IntentPrecondition } from "@0xsequence/trails-api"
 import type { Relayer } from "@0xsequence/wallet-core"
 import type { Hex } from "viem"
 import type { MetaTxn } from "./metaTxnMonitor.js"

package/src/mode.ts

@@ -1 +1 @@
-export type Mode = "pay" | "fund" | "earn" | "swap"
+export type Mode = "pay" | "fund" | "earn" | "swap" | "receive"

package/src/preconditions.ts

@@ -1,4 +1,4 @@
-import type { IntentPrecondition } from "@0xsequence/api"
+import type { IntentPrecondition } from "@0xsequence/trails-api"
 
 export function findPreconditionAddresses(
   preconditions: IntentPrecondition[],