@coinbase/cdp-sdk 1.15.0 → 1.17.0

package/actions/evm/swap/createSwapQuote.ts

@@ -1,3 +1,4 @@
+import { sendSwapOperation } from "./sendSwapOperation.js";
 import { sendSwapTransaction } from "./sendSwapTransaction.js";
 import {
   CreateSwapQuoteOptions,
@@ -10,9 +11,12 @@ import {
   CdpOpenApiClientType,
   CreateSwapQuoteResponse,
   type SendEvmTransactionBodyNetwork,
+  type EvmUserOperationNetwork,
 } from "../../../openapi-client/index.js";
 import { Address, Hex } from "../../../types/misc.js";
 
+import type { EvmSmartAccount } from "../../../accounts/evm/types.js";
+
 /**
  * Creates a quote for a swap between two tokens on an EVM network.
  *
@@ -45,16 +49,19 @@ export async function createSwapQuote(
   const taker = options.taker as Address;
 
   // Call the createEvmSwapQuote function directly with the client's configured API
-  const response = await client.createEvmSwapQuote({
-    network: options.network,
-    toToken: options.toToken,
-    fromToken: options.fromToken,
-    fromAmount: options.fromAmount.toString(),
-    taker: taker,
-    signerAddress: options.signerAddress,
-    gasPrice: options.gasPrice?.toString(),
-    slippageBps: options.slippageBps,
-  });
+  const response = await client.createEvmSwapQuote(
+    {
+      network: options.network,
+      toToken: options.toToken,
+      fromToken: options.fromToken,
+      fromAmount: options.fromAmount.toString(),
+      taker: taker,
+      signerAddress: options.signerAddress,
+      gasPrice: options.gasPrice?.toString(),
+      slippageBps: options.slippageBps,
+    },
+    options.idempotencyKey,
+  );
 
   // Check if liquidity is unavailable
   if (!response.liquidityAvailable) {
@@ -134,13 +141,31 @@ export async function createSwapQuote(
     execute: async (
       executeOptions: ExecuteSwapQuoteOptions = {},
     ): Promise<ExecuteSwapQuoteResult> => {
-      const { transactionHash } = await sendSwapTransaction(client, {
-        address: options.signerAddress || taker, // Use signerAddress for smart accounts, taker for EOAs
-        network: result.network as SendEvmTransactionBodyNetwork,
-        swapQuote: result,
-        idempotencyKey: executeOptions.idempotencyKey,
-      });
-      return { transactionHash };
+      if (options.smartAccount) {
+        // Smart account execution - use sendSwapOperation
+        const userOpResult = await sendSwapOperation(client, {
+          smartAccount: options.smartAccount as EvmSmartAccount,
+          network: result.network as EvmUserOperationNetwork,
+          swapQuote: result,
+          idempotencyKey: executeOptions.idempotencyKey,
+        });
+
+        return {
+          userOpHash: userOpResult.userOpHash,
+          smartAccountAddress: userOpResult.smartAccountAddress,
+          status: userOpResult.status,
+        };
+      } else {
+        // EOA execution - use sendSwapTransaction
+        const { transactionHash } = await sendSwapTransaction(client, {
+          address: taker,
+          network: result.network as SendEvmTransactionBodyNetwork,
+          swapQuote: result,
+          idempotencyKey: executeOptions.idempotencyKey,
+        });
+
+        return { transactionHash };
+      }
     },
   };
 

package/actions/evm/swap/getSwapPrice.ts

@@ -21,7 +21,8 @@ import { Address } from "../../../types/misc.js";
  *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
  *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
  *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
- *   taker: "0x1234567890123456789012345678901234567890"
+ *   taker: "0x1234567890123456789012345678901234567890",
+ *   idempotencyKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // Optional: for request deduplication
  * });
  * ```
  */
@@ -30,16 +31,19 @@ export async function getSwapPrice(
   options: GetSwapPriceOptions,
 ): Promise<GetSwapPriceResult | SwapUnavailableResult> {
   // Call the getEvmSwapPrice function directly with the client's configured API
-  const response = await client.getEvmSwapPrice({
-    network: options.network,
-    toToken: options.toToken,
-    fromToken: options.fromToken,
-    fromAmount: options.fromAmount.toString(),
-    taker: options.taker,
-    signerAddress: options.signerAddress,
-    gasPrice: options.gasPrice?.toString(),
-    slippageBps: options.slippageBps,
-  });
+  const response = await client.getEvmSwapPrice(
+    {
+      network: options.network,
+      toToken: options.toToken,
+      fromToken: options.fromToken,
+      fromAmount: options.fromAmount.toString(),
+      taker: options.taker,
+      signerAddress: options.signerAddress,
+      gasPrice: options.gasPrice?.toString(),
+      slippageBps: options.slippageBps,
+    },
+    options.idempotencyKey,
+  );
 
   // Check if liquidity is unavailable
   if (!response.liquidityAvailable) {

package/actions/evm/swap/sendSwapOperation.ts

@@ -0,0 +1,182 @@
+import { concat, numberToHex, size } from "viem";
+
+import { createSwapQuote } from "./createSwapQuote.js";
+import { createDeterministicUuidV4 } from "../../../utils/uuidV4.js";
+import { sendUserOperation } from "../sendUserOperation.js";
+import { signAndWrapTypedDataForSmartAccount } from "../signAndWrapTypedDataForSmartAccount.js";
+
+import type { SendSwapOperationOptions, SendSwapOperationResult } from "./types.js";
+import type { EvmSmartAccount } from "../../../accounts/evm/types.js";
+import type {
+  CreateSwapQuoteResult,
+  CreateSwapQuoteOptions,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import type {
+  CdpOpenApiClientType,
+  EvmUserOperationNetwork,
+} from "../../../openapi-client/index.js";
+import type { Hex } from "../../../types/misc.js";
+
+/**
+ * Sends a swap operation to the blockchain via a smart account user operation.
+ * Handles any permit2 signatures required for the swap.
+ *
+ * If you encounter token allowance issues, you'll need to perform a token approval transaction first to allow
+ * the Permit2 contract to spend the appropriate amount of your fromToken.
+ * See examples for code on handling token approvals.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use for sending the swap operation.
+ * @param {SendSwapOperationOptions} options - The options for the swap submission.
+ *
+ * @returns {Promise<SendSwapOperationResult>} A promise that resolves to the user operation result.
+ *
+ * @throws {Error} If liquidity is not available for the swap.
+ * @throws {Error} If there are insufficient token allowances. In this case, you need to approve the
+ *                 Permit2 contract to spend your tokens before attempting the swap. The error message
+ *                 will include the current allowance and the spender address that needs approval.
+ * @throws {Error} If no transaction data is found in the swap result.
+ *
+ * @example **Sending a swap with pre-created swap quote object**
+ * ```ts
+ * // First create a swap quote
+ * const swapQuote = await cdp.evm.createSwapQuote({
+ *   network: "base",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: smartAccount.address
+ * });
+ *
+ * // Check if liquidity is available
+ * if (!swapQuote.liquidityAvailable) {
+ *   console.error("Insufficient liquidity for swap");
+ *   return;
+ * }
+ *
+ * // Send the swap operation
+ * const result = await sendSwapOperation(client, {
+ *   smartAccount: smartAccount,
+ *   swapQuote: swapQuote
+ * });
+ *
+ * console.log(`Swap operation sent with user op hash: ${result.userOpHash}`);
+ * ```
+ *
+ * @example **Sending a swap with inline options (all-in-one)**
+ * ```ts
+ * // Send swap operation in one call
+ * const result = await sendSwapOperation(client, {
+ *   smartAccount: smartAccount,
+ *   network: "base",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: smartAccount.address
+ * });
+ *
+ * console.log(`Swap operation sent with user op hash: ${result.userOpHash}`);
+ * ```
+ */
+export async function sendSwapOperation(
+  client: CdpOpenApiClientType,
+  options: SendSwapOperationOptions,
+): Promise<SendSwapOperationResult> {
+  const { smartAccount, paymasterUrl, idempotencyKey } = options;
+
+  let swapResult: CreateSwapQuoteResult | SwapUnavailableResult;
+
+  // Determine if we need to create the swap quote or use the provided one
+  if ("swapQuote" in options) {
+    // Use the provided swap quote
+    swapResult = options.swapQuote;
+  } else {
+    // Create the swap quote using the provided options (inline options)
+    /**
+     * Deterministically derive a new idempotency key from the provided idempotency key for swap quote creation to avoid key reuse.
+     */
+    const swapQuoteIdempotencyKey = idempotencyKey
+      ? createDeterministicUuidV4(idempotencyKey, "createSwapQuote")
+      : undefined;
+
+    swapResult = await createSwapQuote(client, {
+      network: options.network as CreateSwapQuoteOptions["network"],
+      toToken: options.toToken,
+      fromToken: options.fromToken,
+      fromAmount: options.fromAmount,
+      taker: options.taker,
+      signerAddress: options.signerAddress,
+      gasPrice: options.gasPrice,
+      slippageBps: options.slippageBps,
+      idempotencyKey: swapQuoteIdempotencyKey,
+    });
+  }
+
+  // Check if liquidity is available
+  if (!swapResult.liquidityAvailable) {
+    throw new Error("Insufficient liquidity for swap");
+  }
+
+  // At this point, we know that swapResult is CreateSwapQuoteResult
+  const swap = swapResult as CreateSwapQuoteResult;
+
+  // Check for allowance issues
+  if (swap.issues?.allowance) {
+    const { currentAllowance, spender } = swap.issues.allowance;
+    throw new Error(
+      `Insufficient token allowance for swap. Current allowance: ${currentAllowance}. ` +
+        `Please approve the Permit2 contract (${spender}) to spend your tokens.`,
+    );
+  }
+
+  // If the transaction doesn't exist, throw an error
+  if (!swap.transaction) {
+    throw new Error("No transaction data found in the swap");
+  }
+
+  // Get the transaction data and modify it if needed for Permit2
+  let txData = swap.transaction.data as Hex;
+
+  if (swap.permit2?.eip712) {
+    // Create the permit2 idempotency key
+    const permit2IdempotencyKey = idempotencyKey
+      ? createDeterministicUuidV4(idempotencyKey, "permit2")
+      : undefined;
+
+    // Sign and wrap the permit2 typed data according to the Coinbase Smart Wallet contract requirements for EIP-712 signatures
+    const { signature: wrappedSignature } = await signAndWrapTypedDataForSmartAccount(client, {
+      smartAccount,
+      chainId: BigInt(swap.permit2.eip712.domain.chainId || 1),
+      typedData: swap.permit2.eip712,
+      ownerIndex: 0n,
+      idempotencyKey: permit2IdempotencyKey,
+    });
+
+    // Calculate the Permit2 signature length as a 32-byte hex value
+    const permit2SignatureLengthInHex = numberToHex(size(wrappedSignature), {
+      signed: false,
+      size: 32,
+    });
+
+    // Append the Permit2 signature length and signature to the transaction data
+    txData = concat([txData, permit2SignatureLengthInHex, wrappedSignature]);
+  }
+
+  // Send the swap as a user operation
+  const result = await sendUserOperation(client, {
+    smartAccount: smartAccount as EvmSmartAccount,
+    network: swap.network as EvmUserOperationNetwork,
+    paymasterUrl,
+    idempotencyKey,
+    calls: [
+      {
+        to: swap.transaction.to,
+        data: txData,
+        // Only include value if it exists
+        ...(swap.transaction.value ? { value: BigInt(swap.transaction.value) } : {}),
+      },
+    ],
+  });
+
+  return result;
+}

package/actions/evm/swap/sendSwapTransaction.ts

@@ -1,6 +1,7 @@
 import { concat, numberToHex, size } from "viem";
 
 import { createSwapQuote } from "./createSwapQuote.js";
+import { createDeterministicUuidV4 } from "../../../utils/uuidV4.js";
 import { sendTransaction } from "../sendTransaction.js";
 
 import type { SendSwapTransactionOptions, SendSwapTransactionResult } from "./types.js";
@@ -90,6 +91,13 @@ export async function sendSwapTransaction(
     swapResult = options.swapQuote;
   } else {
     // Create the swap quote using the provided options (InlineSendSwapTransactionOptions)
+    /**
+     * Deterministically derive a new idempotency key from the provided idempotency key for swap quote creation to avoid key reuse.
+     */
+    const swapQuoteIdempotencyKey = idempotencyKey
+      ? createDeterministicUuidV4(idempotencyKey, "createSwapQuote")
+      : undefined;
+
     swapResult = await createSwapQuote(client, {
       network: options.network as CreateSwapQuoteOptions["network"],
       toToken: options.toToken,
@@ -99,6 +107,7 @@ export async function sendSwapTransaction(
       signerAddress: options.signerAddress,
       gasPrice: options.gasPrice,
       slippageBps: options.slippageBps,
+      idempotencyKey: swapQuoteIdempotencyKey,
     });
   }
 
@@ -128,7 +137,14 @@ export async function sendSwapTransaction(
   let txData = swap.transaction.data as Hex;
 
   if (swap.permit2?.eip712) {
-    // Sign the Permit2 EIP-712 message
+    /**
+     * Sign the Permit2 EIP-712 message.
+     * Deterministically derive a new idempotency key from the provided idempotency key for permit2 signing to avoid key reuse.
+     */
+    const permit2IdempotencyKey = idempotencyKey
+      ? createDeterministicUuidV4(idempotencyKey, "permit2")
+      : undefined;
+
     const signature = await client.signEvmTypedData(
       address,
       {
@@ -137,7 +153,7 @@ export async function sendSwapTransaction(
         primaryType: swap.permit2.eip712.primaryType,
         message: swap.permit2.eip712.message,
       },
-      idempotencyKey,
+      permit2IdempotencyKey,
     );
 
     // Calculate the signature length as a 32-byte hex value

package/actions/evm/swap/types.ts

@@ -1,9 +1,14 @@
+import type { EvmSmartAccount } from "../../../accounts/evm/types.js";
 import type {
   CreateSwapQuoteOptions,
   CreateSwapQuoteResult,
   SwapUnavailableResult,
 } from "../../../client/evm/evm.types.js";
-import type { SendEvmTransactionBodyNetwork } from "../../../openapi-client/index.js";
+import type {
+  SendEvmTransactionBodyNetwork,
+  EvmUserOperationNetwork,
+  EvmUserOperationStatus,
+} from "../../../openapi-client/index.js";
 import type { Address, Hex } from "../../../types/misc.js";
 
 /**
@@ -76,12 +81,12 @@ export interface SendSwapTransactionResult {
 /**
  * Options for creating a swap quote (account-level).
  */
-export type QuoteSwapOptions = Omit<CreateSwapQuoteOptions, "taker">;
+export type AccountQuoteSwapOptions = Omit<CreateSwapQuoteOptions, "taker">;
 
 /**
  * Result of creating a swap quote (account-level).
  */
-export type QuoteSwapResult = CreateSwapQuoteResult | SwapUnavailableResult;
+export type AccountQuoteSwapResult = CreateSwapQuoteResult | SwapUnavailableResult;
 
 /**
  * Options when providing an already created swap quote (account-level).
@@ -129,9 +134,153 @@ interface AccountInlineSwapOptions {
  * Options for executing a token swap (account-level).
  * The taker is automatically set to the account's address.
  */
-export type SwapOptions = AccountQuoteBasedSwapOptions | AccountInlineSwapOptions;
+export type AccountSwapOptions = AccountQuoteBasedSwapOptions | AccountInlineSwapOptions;
 
 /**
  * Result of executing a token swap (account-level).
  */
-export type SwapResult = SendSwapTransactionResult;
+export type AccountSwapResult = SendSwapTransactionResult;
+
+/**
+ * Options for creating a swap quote (smart account-level).
+ */
+export type SmartAccountQuoteSwapOptions = Omit<CreateSwapQuoteOptions, "taker">;
+
+/**
+ * Result of creating a swap quote (smart account-level).
+ */
+export type SmartAccountQuoteSwapResult = CreateSwapQuoteResult | SwapUnavailableResult;
+
+/**
+ * Options when providing an already created swap quote (smart account-level).
+ */
+interface SmartAccountQuoteBasedSwapOptions {
+  /**
+   * The swap quote returned by the createSwapQuote method.
+   */
+  swapQuote: CreateSwapQuoteResult;
+
+  /**
+   * Optional URL of the paymaster service to use for gas sponsorship.
+   */
+  paymasterUrl?: string;
+
+  /**
+   * Optional idempotency key for the request.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options when creating a swap quote inline (smart account-level).
+ */
+interface SmartAccountInlineSwapOptions {
+  /**
+   * The network to execute the swap on (e.g., "ethereum", "base").
+   */
+  network: SendEvmTransactionBodyNetwork;
+  /** The token to receive (destination token). */
+  toToken: Address;
+  /** The token to send (source token). */
+  fromToken: Address;
+  /** The amount to send in atomic units of the token. */
+  fromAmount: bigint;
+  /** The signer address (only needed if taker is a smart contract). */
+  signerAddress?: Address;
+  /** The gas price in Wei. */
+  gasPrice?: bigint;
+  /** The slippage tolerance in basis points (0-10000). */
+  slippageBps?: number;
+
+  /**
+   * Optional URL of the paymaster service to use for gas sponsorship.
+   */
+  paymasterUrl?: string;
+
+  /**
+   * Optional idempotency key for the request.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for executing a token swap (smart account-level).
+ * The taker is automatically set to the smart account's address.
+ */
+export type SmartAccountSwapOptions =
+  | SmartAccountQuoteBasedSwapOptions
+  | SmartAccountInlineSwapOptions;
+
+/**
+ * Result of executing a token swap (smart account-level).
+ */
+export type SmartAccountSwapResult = {
+  /** The address of the smart wallet. */
+  smartAccountAddress: Address;
+  /** The status of the user operation. */
+  status: string;
+  /** The hash of the user operation. */
+  userOpHash: Hex;
+};
+
+/**
+ * Base options for sending a swap operation via smart account.
+ */
+interface BaseSendSwapOperationOptions {
+  /** The smart account that will execute the swap. */
+  smartAccount: EvmSmartAccount;
+  /** Optional URL of the paymaster service to use for gas sponsorship. */
+  paymasterUrl?: string;
+  /** Optional idempotency key for the request. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options when providing an already created swap quote (for sendSwapOperation).
+ */
+interface QuoteBasedSendSwapOperationOptions extends BaseSendSwapOperationOptions {
+  /** The swap quote returned by the createSwapQuote method. */
+  swapQuote: CreateSwapQuoteResult;
+}
+
+/**
+ * Options when creating a swap quote inline (for sendSwapOperation).
+ */
+interface InlineSendSwapOperationOptions extends BaseSendSwapOperationOptions {
+  /** The network to execute the swap on. */
+  network: EvmUserOperationNetwork;
+  /** The token to receive (destination token). */
+  toToken: Address;
+  /** The token to send (source token). */
+  fromToken: Address;
+  /** The amount to send in atomic units of the token. */
+  fromAmount: bigint;
+  /** The address that will perform the swap. */
+  taker: Address;
+  /** The signer address (required since taker is a smart contract). */
+  signerAddress: Address;
+  /** The gas price in Wei. */
+  gasPrice?: bigint;
+  /** The slippage tolerance in basis points (0-10000). */
+  slippageBps?: number;
+}
+
+/**
+ * Options for sending a swap operation via smart account.
+ * Either provide a pre-created swap quote result or inline swap parameters.
+ */
+export type SendSwapOperationOptions =
+  | QuoteBasedSendSwapOperationOptions
+  | InlineSendSwapOperationOptions;
+
+/**
+ * Result of sending a swap operation via smart account.
+ */
+export type SendSwapOperationResult = {
+  /** The address of the smart wallet. */
+  smartAccountAddress: Address;
+  /** The status of the user operation. */
+  status: typeof EvmUserOperationStatus.broadcast;
+  /** The hash of the user operation. */
+  userOpHash: Hex;
+};