0xtrails 0.2.5 → 0.3.0

package/src/transactionIntent/deposits/gaslessDeposit.ts

@@ -0,0 +1,588 @@
+import type { Account, Chain, WalletClient } from "viem"
+import {
+  createPublicClient,
+  ethAddress,
+  http,
+  maxUint256,
+  zeroAddress,
+} from "viem"
+import type {
+  TrailsAPIClient,
+  GasFeeOptions,
+  FeeOption,
+  DepositSignature,
+  ExecuteIntentResponse,
+} from "@0xsequence/trails-api"
+import type { SelectedFeeToken } from "../types.js"
+import type { CheckoutOnHandlers } from "../../widget/hooks/useCheckout.js"
+import type { TransactionState } from "../../transactions.js"
+import { logger } from "../../logger.js"
+import { attemptSwitchChain } from "../../chainSwitch.js"
+import { getTransactionStateFromReceipt } from "../execution/transactionState.js"
+import {
+  getDelegatorSmartAccount,
+  getPaymasterGaslessTransaction,
+  sendPaymasterGaslessTransaction,
+} from "../../paymasterSend.js"
+import { TRAILS_INTENT_ENTRYPOINT_ADDRESS } from "../../constants.js"
+import {
+  getNeedsIntentEntrypointApproval,
+  getUserNonce,
+  signIntent,
+  getPermitSignature,
+} from "../../gasless.js"
+
+export async function attemptGaslessDeposit({
+  paymasterUrl,
+  depositTokenAddress,
+  depositTokenAmount,
+  depositRecipient,
+  onOriginSend,
+  walletClient,
+  chain,
+  account,
+  trailsClient,
+  feeOptions,
+  selectedFeeToken,
+  checkoutOnHandlers,
+  intentId,
+  onTransactionStateChange,
+  transactionStates,
+  executeIntentFn,
+}: {
+  paymasterUrl?: string
+  depositTokenAddress: string
+  depositTokenAmount: string
+  depositRecipient: string
+  onOriginSend?: () => void
+  walletClient: WalletClient
+  chain: Chain
+  account: Account
+  trailsClient: TrailsAPIClient
+  feeOptions?: GasFeeOptions
+  selectedFeeToken?: SelectedFeeToken
+  abortSignal?: AbortSignal
+  checkoutOnHandlers?: CheckoutOnHandlers
+  intentId?: string
+  onTransactionStateChange?: (transactionStates: TransactionState[]) => void
+  transactionStates?: TransactionState[]
+  executeIntentFn?: (params: {
+    intentId: string
+    depositTransactionHash?: string
+    depositSignature?: DepositSignature
+  }) => Promise<ExecuteIntentResponse>
+}): Promise<void> {
+  const originChainId = chain.id
+
+  logger.console.log(
+    "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] attemptGaslessDeposit called with:",
+    {
+      originChainId,
+      depositTokenAddress,
+      depositTokenAmount,
+      depositRecipient,
+      hasFeeOptions: !!feeOptions,
+      feeOptionsLength: feeOptions?.feeOptions?.length,
+      selectedFeeToken,
+      hasSelectedFeeToken: !!selectedFeeToken,
+      paymasterUrl,
+    },
+  )
+
+  const publicClient = createPublicClient({
+    chain,
+    transport: http(),
+  })
+
+  logger.console.log("[trails-sdk] [GASLESS-FLOW] Intent entrypoint check:", {
+    chainId: chain.id,
+    chainName: chain.name,
+    intentEntrypoint: TRAILS_INTENT_ENTRYPOINT_ADDRESS,
+  })
+
+  // NEW FLOW: Use Intent Entrypoint API with permit2 support
+  logger.console.log(
+    "[trails-sdk] Using Intent Entrypoint API flow with permit2 support for gasless deposit",
+  )
+
+  // Switch to correct chain before requesting signatures
+  logger.console.log(
+    "[trails-sdk] [GASLESS-FLOW] Switching to chain before permit/intent signatures",
+    { originChainId },
+  )
+  await attemptSwitchChain({
+    walletClient,
+    desiredChainId: originChainId,
+  })
+
+  try {
+    if (paymasterUrl) {
+      logger.console.log(
+        "[trails-sdk] [GASLESS-FLOW] doing gasless with paymaster",
+      )
+
+      // Switch to correct chain before requesting signatures
+      logger.console.log(
+        "[trails-sdk] [GASLESS-FLOW] Switching chain for paymaster flow",
+      )
+      await attemptSwitchChain({
+        walletClient,
+        desiredChainId: originChainId,
+      })
+
+      const delegatorSmartAccount = await getDelegatorSmartAccount({
+        publicClient,
+      })
+
+      const calls: Array<{
+        to: string
+        data: string
+        value: string
+      }> = await getPaymasterGaslessTransaction({
+        walletClient,
+        chain,
+        tokenAddress: depositTokenAddress as `0x${string}`,
+        amount: BigInt(depositTokenAmount),
+        recipient: depositRecipient as `0x${string}`,
+        delegatorSmartAccount,
+      })
+
+      logger.console.log("[trails-sdk] calls", calls)
+
+      // Trigger signature request callback before prompting wallet
+      if (checkoutOnHandlers?.triggerCheckoutSignatureRequest) {
+        checkoutOnHandlers.triggerCheckoutSignatureRequest()
+      }
+
+      const txHash = await sendPaymasterGaslessTransaction({
+        walletClient,
+        publicClient,
+        chain,
+        paymasterUrl,
+        delegatorSmartAccount,
+        calls,
+      })
+
+      // Trigger signature confirmed callback after successful signing
+      if (checkoutOnHandlers?.triggerCheckoutSignatureConfirmed) {
+        checkoutOnHandlers.triggerCheckoutSignatureConfirmed()
+      }
+
+      if (onOriginSend) {
+        onOriginSend()
+      }
+
+      // Update transaction state to pending with hash for paymaster flow
+      if (transactionStates?.[0] && onTransactionStateChange) {
+        transactionStates[0].state = "pending"
+        transactionStates[0].transactionHash = txHash
+
+        try {
+          onTransactionStateChange(transactionStates)
+        } catch (error) {
+          logger.console.error(
+            "[trails-sdk] Error calling onTransactionStateChange:",
+            error,
+          )
+        }
+      }
+
+      const receipt = await publicClient.waitForTransactionReceipt({
+        hash: txHash as `0x${string}`,
+      })
+      logger.console.log("[trails-sdk] receipt", receipt)
+
+      // Update transaction state to confirmed after receipt is obtained
+      if (transactionStates?.[0] && onTransactionStateChange && receipt) {
+        transactionStates[0] = getTransactionStateFromReceipt(
+          receipt,
+          chain.id,
+          transactionStates[0]?.label,
+        )
+
+        try {
+          onTransactionStateChange(transactionStates)
+        } catch (error) {
+          logger.console.error(
+            "[trails-sdk] Error calling onTransactionStateChange:",
+            error,
+          )
+        }
+      }
+
+      return
+    }
+
+    const deadline = Math.floor(Date.now() / 1000) + 3600 // 1 hour from now
+    const hasFeeOptions = Boolean(
+      feeOptions && feeOptions.feeOptions?.length > 0,
+    )
+
+    // 1. Check if we need approval - check if we have enough allowance for this transaction (deposit + fee if same token)
+    let requiredAmount = BigInt(depositTokenAmount)
+
+    // Match selectedFeeToken by tokenAddress to get the latest fee amount from feeOptions
+    let selectedFeeOption: FeeOption | null = null
+    if (selectedFeeToken && hasFeeOptions && feeOptions) {
+      // Find matching fee option by tokenAddress to get latest amount
+      selectedFeeOption =
+        feeOptions.feeOptions.find(
+          (opt) =>
+            opt.tokenAddress?.toLowerCase() ===
+            selectedFeeToken.tokenAddress?.toLowerCase(),
+        ) || null
+      logger.console.log(
+        "[trails-sdk] Matched selectedFeeToken to latest fee option:",
+        {
+          selectedFeeToken,
+          matchedOption: selectedFeeOption,
+        },
+      )
+    }
+
+    // Fallback to first fee option if no match or no selectedFeeToken
+    if (!selectedFeeOption && hasFeeOptions && feeOptions) {
+      selectedFeeOption = feeOptions.feeOptions[0] || null
+      logger.console.log(
+        "[trails-sdk] Using first fee option as fallback:",
+        selectedFeeOption,
+      )
+    }
+
+    // Only include fee in required amount if the fee token is the same as the deposit token
+    if (selectedFeeOption?.amount && selectedFeeOption?.tokenAddress) {
+      const feeTokenIsSameAsDepositToken =
+        selectedFeeOption.tokenAddress.toLowerCase() ===
+        depositTokenAddress.toLowerCase()
+
+      if (feeTokenIsSameAsDepositToken) {
+        requiredAmount = requiredAmount + BigInt(selectedFeeOption.amount)
+        logger.console.log(
+          "[trails-sdk] Fee token matches deposit token, including fee in required approval amount:",
+          {
+            depositAmount: depositTokenAmount,
+            feeAmount: selectedFeeOption.amount,
+            feeTokenAddress: selectedFeeOption.tokenAddress,
+            depositTokenAddress,
+            totalRequired: requiredAmount.toString(),
+          },
+        )
+      } else {
+        logger.console.log(
+          "[trails-sdk] Fee token differs from deposit token, separate approval will be needed:",
+          {
+            depositAmount: depositTokenAmount,
+            depositTokenAddress,
+            feeAmount: selectedFeeOption.amount,
+            feeTokenAddress: selectedFeeOption.tokenAddress,
+            depositTokenRequired: requiredAmount.toString(),
+          },
+        )
+      }
+    }
+
+    const needsApproval = await getNeedsIntentEntrypointApproval({
+      client: publicClient,
+      token: depositTokenAddress as `0x${string}`,
+      account: account.address,
+      entrypoint: TRAILS_INTENT_ENTRYPOINT_ADDRESS,
+      amount: requiredAmount, // Check if we have enough allowance for this specific transaction
+    })
+
+    logger.console.log(
+      "[trails-sdk] [GASLESS-FLOW] Checking permit requirements",
+      {
+        userAddress: account.address,
+        tokenAddress: depositTokenAddress,
+        depositAmount: depositTokenAmount,
+        requiredAmount: requiredAmount.toString(),
+        intentAddress: depositRecipient,
+        chainID: originChainId,
+        deadline,
+        needsApproval,
+      },
+    )
+
+    // 2. Get permit signature if approval needed for deposit token
+    // Note: Fee payment is handled by the backend/relayer, we only need permit for the deposit token
+    let permitSignature: string | undefined
+    let permitDeadline: number | undefined
+
+    if (needsApproval) {
+      logger.console.log(
+        "[trails-sdk] Getting permit signature for deposit token infinite approval",
+      )
+
+      // Use infinite approval (maxUint256) so user doesn't need to approve again
+      const permitAmount = maxUint256
+      logger.console.log(
+        "[trails-sdk] Using infinite approval for gasless deposits",
+        {
+          depositAmount: depositTokenAmount,
+          depositTokenAddress,
+          permitAmount: permitAmount.toString(),
+        },
+      )
+
+      const permitSig = await getPermitSignature({
+        publicClient,
+        walletClient,
+        signer: account.address,
+        spender: TRAILS_INTENT_ENTRYPOINT_ADDRESS,
+        tokenAddress: depositTokenAddress as `0x${string}`,
+        amount: permitAmount, // Infinite approval
+        chain,
+        deadline: BigInt(deadline),
+      })
+      permitSignature = permitSig.signature
+      permitDeadline = Number(permitSig.deadline)
+      logger.console.log(
+        "[trails-sdk] Deposit token permit signature obtained for infinite approval",
+      )
+    }
+
+    // 3. Get current nonce for the user
+    logger.console.log("[trails-sdk] Getting user nonce")
+    const nonce = await getUserNonce({
+      publicClient,
+      userAddress: account.address,
+      intentEntrypoint: TRAILS_INTENT_ENTRYPOINT_ADDRESS,
+    })
+    logger.console.log("[trails-sdk] User nonce:", nonce.toString())
+
+    // 4. Get intent signature
+    logger.console.log("[trails-sdk] Requesting intent signature via EIP-712")
+    // Get fee collector address from the new schema:
+    // Priority: selectedFeeOption.feeCollectorAddress > feeOptions.feeCollectorAddress
+    const feeCollectorAddress = (selectedFeeOption?.feeCollectorAddress ||
+      feeOptions?.feeCollectorAddress) as `0x${string}` | undefined
+
+    // Validate that we have a valid fee collector address
+    if (!feeCollectorAddress || feeCollectorAddress === zeroAddress) {
+      throw new Error(
+        "[trails-sdk] Fee collector address not provided by API. Cannot proceed with gasless deposit. " +
+          "Please ensure the API is returning feeCollectorAddress in the gasFeeOptions response.",
+      )
+    }
+
+    logger.console.log(
+      "[trails-sdk] Using fee collector address:",
+      feeCollectorAddress,
+    )
+
+    // Trigger signature request callback before prompting wallet
+    if (checkoutOnHandlers?.triggerCheckoutSignatureRequest) {
+      checkoutOnHandlers.triggerCheckoutSignatureRequest()
+    }
+
+    const { signature: intentSignature } = await signIntent({
+      client: walletClient,
+      intentParams: {
+        user: account.address,
+        token: depositTokenAddress as `0x${string}`,
+        amount: BigInt(depositTokenAmount),
+        intentAddress: depositRecipient as `0x${string}`,
+        deadline: BigInt(deadline),
+        chainId: originChainId,
+        contractAddress: TRAILS_INTENT_ENTRYPOINT_ADDRESS,
+        nonce,
+        feeAmount: BigInt(selectedFeeOption?.amount || "0"),
+        feeCollector: feeCollectorAddress,
+      },
+    })
+    logger.console.log("[trails-sdk] Intent signature received")
+
+    // Trigger signature confirmed callback after successful signing
+    if (checkoutOnHandlers?.triggerCheckoutSignatureConfirmed) {
+      checkoutOnHandlers.triggerCheckoutSignatureConfirmed()
+    }
+
+    // 5. Call the deposit endpoint with permit support and optional fee
+    logger.console.log(
+      "[trails-sdk] Calling executeIntent with depositSignature",
+      {
+        usePermit: needsApproval,
+        hasFee: !!feeOptions,
+        hasIntentId: !!intentId,
+      },
+    )
+
+    // Validate that we have the intentId
+    if (!intentId) {
+      throw new Error(
+        "[trails-sdk] intentId is required for gasless deposits. " +
+          "The calling code must commit the intent first using commitIntent() and pass the intentId.",
+      )
+    }
+
+    // Validate that we have a selected fee option
+    if (!selectedFeeOption) {
+      throw new Error(
+        "[trails-sdk] selectedFeeOption is required for gasless deposits",
+      )
+    }
+
+    // Build depositSignature for executeIntent with all required fields
+    const depositSignature = {
+      intentSignature,
+      permitSignature: needsApproval ? permitSignature : undefined,
+      permitDeadline: needsApproval ? permitDeadline : undefined,
+      permitAmount: needsApproval ? maxUint256 : undefined,
+      selectedGasFeeOption: selectedFeeOption,
+      userNonce: Number(nonce),
+      deadline,
+    }
+
+    logger.console.log(
+      "[trails-sdk] Executing intent with gasless deposit signature",
+      { intentId, depositSignature },
+    )
+
+    // executeIntent will handle submitting to the relayer
+    // The backend processes the deposit signature and relays the transaction
+    const executeIntentFnToUse =
+      executeIntentFn || trailsClient.executeIntent.bind(trailsClient)
+    await executeIntentFnToUse({
+      intentId,
+      depositSignature,
+    })
+
+    logger.console.log(
+      "[trails-sdk] Intent execution submitted to backend. Transaction monitoring should happen via intent status polling.",
+    )
+
+    if (onOriginSend) {
+      onOriginSend()
+    }
+
+    // Update transaction state to pending for non-paymaster gasless flow
+    // Hash will be filled in later by the poller when backend confirms transaction
+    if (transactionStates?.[0] && onTransactionStateChange) {
+      transactionStates[0].state = "pending"
+      // transactionHash remains empty - will be updated by onDepositTransactionFound callback
+
+      try {
+        onTransactionStateChange(transactionStates)
+      } catch (error) {
+        logger.console.error(
+          "[trails-sdk] Error calling onTransactionStateChange:",
+          error,
+        )
+      }
+    }
+  } catch (error) {
+    logger.console.error(
+      "[trails-sdk] Error in Intent Entrypoint gasless deposit with permit2:",
+      error,
+    )
+    throw error
+  }
+}
+
+export function getDoGasless(
+  originTokenAddress: string,
+  feeOptions?: GasFeeOptions,
+  selectedFeeToken?: SelectedFeeToken,
+  walletId?: string,
+): boolean {
+  // Don't use gasless flow for sequence-waas wallet
+  if (walletId === "sequence-waas") {
+    logger.console.log(
+      "[trails-sdk] [GASLESS-FLOW] getDoGasless: Skipping gasless flow for sequence-waas wallet",
+    )
+    return false
+  }
+
+  const hasFeeOptions = Boolean(feeOptions && feeOptions.feeOptions?.length > 0)
+
+  // Important: The UI passes selectedFeeToken in these states:
+  // - null: User explicitly chose "Pay with native gas"
+  // - {object}: User selected a fee token OR it was auto-selected
+  // - undefined: Should not happen (initial state auto-selects if options exist)
+
+  // If selectedFeeToken is null, user explicitly chose native gas
+  if (selectedFeeToken === null) {
+    logger.console.log(
+      "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] getDoGasless: User explicitly selected native gas (null)",
+    )
+    return false
+  }
+
+  // If selectedFeeToken is undefined and no fee options, can't do gasless
+  if (!selectedFeeToken && !hasFeeOptions) {
+    logger.console.log(
+      "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] getDoGasless: No fee token selected and no fee options available",
+    )
+    return false
+  }
+
+  // If selectedFeeToken is undefined but fee options exist, use first ERC20 option
+  let effectiveFeeToken = selectedFeeToken
+  if (!effectiveFeeToken && hasFeeOptions && feeOptions) {
+    const firstFeeOption = feeOptions.feeOptions[0]
+
+    // Check if first option is native gas
+    const isFirstOptionNative =
+      firstFeeOption?.tokenAddress === zeroAddress ||
+      firstFeeOption?.tokenAddress?.toLowerCase() === zeroAddress ||
+      firstFeeOption?.tokenAddress === ethAddress ||
+      firstFeeOption?.tokenAddress?.toLowerCase() === ethAddress.toLowerCase()
+
+    if (!isFirstOptionNative && firstFeeOption?.tokenAddress) {
+      // First fee option is ERC20, use it
+      effectiveFeeToken = firstFeeOption
+      logger.console.log(
+        "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] getDoGasless: No fee token selected, using first ERC20 fee option",
+        {
+          feeOption: effectiveFeeToken,
+        },
+      )
+    } else {
+      logger.console.log(
+        "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] getDoGasless: First fee option is native gas, skipping gasless",
+      )
+      return false
+    }
+  }
+
+  // Check if the effective fee token is native gas
+  const isNativeGasFee =
+    !effectiveFeeToken ||
+    effectiveFeeToken.tokenAddress === zeroAddress ||
+    effectiveFeeToken.tokenAddress?.toLowerCase() === zeroAddress ||
+    effectiveFeeToken.tokenAddress === ethAddress ||
+    effectiveFeeToken.tokenAddress?.toLowerCase() === ethAddress.toLowerCase()
+
+  // Don't use gasless if origin token is native (sending ETH)
+  if (originTokenAddress === zeroAddress) {
+    logger.console.log(
+      "[trails-sdk] [GASLESS-FLOW] getDoGasless: Origin token is native, skipping gasless",
+    )
+    return false
+  }
+
+  // Don't use gasless if fee token is native
+  if (isNativeGasFee) {
+    logger.console.log(
+      "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] getDoGasless: Fee token is native gas, skipping gasless",
+      {
+        effectiveFeeToken,
+      },
+    )
+    return false
+  }
+
+  // All conditions met, use gasless with ERC20 fee token
+  logger.console.log(
+    "[trails-sdk] [GASLESS-FLOW] [FEE-SELECT] getDoGasless decision: Using gasless",
+    {
+      originTokenAddress,
+      hasFeeOptions,
+      selectedFeeToken,
+      effectiveFeeToken,
+      feeOptionsCount: feeOptions?.feeOptions?.length || 0,
+    },
+  )
+
+  return true
+}

package/src/transactionIntent/deposits/index.ts

@@ -0,0 +1,3 @@
+export * from "./gaslessDeposit.js"
+export * from "./standardDeposit.js"
+export * from "./depositOrchestrator.js"