@coinbase/cdp-sdk 1.10.0 → 1.12.0

package/actions/evm/fund/waitForFundOperationReceipt.ts

@@ -0,0 +1,118 @@
+import { CdpOpenApiClientType, Transfer, TransferStatus } from "../../../openapi-client/index.js";
+import { wait, WaitOptions } from "../../../utils/wait.js";
+
+/**
+ * Options for waiting for a fund operation.
+ */
+export type WaitForFundOperationOptions = {
+  /** The ID of the transfer to wait for. */
+  transferId: string;
+  /** Optional options for the wait operation. */
+  waitOptions?: WaitOptions;
+};
+
+/**
+ * Represents a failed fund operation.
+ */
+export type FailedFundOperation = {
+  /** The ID of the transfer. */
+  id: string;
+  /** The network that the transfer was created on. */
+  network: string;
+  /** The target amount that will be received. */
+  targetAmount: string;
+  /** The currency that will be received. */
+  targetCurrency: string;
+  /** The status of the transfer. */
+  status: typeof TransferStatus.failed;
+};
+
+/**
+ * Represents a completed fund operation.
+ */
+export type CompletedFundOperation = {
+  /** The ID of the transfer. */
+  id: string;
+  /** The network that the transfer was created on. */
+  network: string;
+  /** The target amount that will be received. */
+  targetAmount: string;
+  /** The currency that will be received. */
+  targetCurrency: string;
+  /** The status of the transfer. */
+  status: typeof TransferStatus.completed;
+  /** The transaction hash of the transfer. */
+  transactionHash: string;
+};
+
+/**
+ * Represents the return type of the waitForFundOperation function.
+ */
+export type WaitForFundOperationResult = FailedFundOperation | CompletedFundOperation;
+
+/**
+ * Waits for a fund operation to complete or fail.
+ *
+ * @example
+ * ```ts
+ * import { waitForFundOperation } from "@coinbase/cdp-sdk";
+ *
+ * const result = await waitForFundOperation(client, {
+ *   transferId: "0x1234567890123456789012345678901234567890",
+ *   waitOptions: {
+ *     timeoutSeconds: 30,
+ *   },
+ * });
+ * ```
+ *
+ * @param {CdpOpenApiClientType} client - The client to use to wait for the fund operation.
+ * @param {WaitForFundOperationOptions} options - The options for the wait operation.
+ * @returns {Promise<WaitForFundOperationResult>} The result of the fund operation.
+ */
+export async function waitForFundOperationReceipt(
+  client: CdpOpenApiClientType,
+  options: WaitForFundOperationOptions,
+): Promise<WaitForFundOperationResult> {
+  const { transferId } = options;
+
+  const reload = async () => {
+    const response = await client.getPaymentTransfer(transferId);
+    return response;
+  };
+
+  const transform = (operation: Transfer): WaitForFundOperationResult => {
+    if (operation.status === TransferStatus.failed) {
+      return {
+        id: operation.id,
+        network: operation.target.network,
+        targetAmount: operation.targetAmount,
+        targetCurrency: operation.targetCurrency,
+        status: operation.status,
+      } satisfies FailedFundOperation;
+    } else if (operation.status === TransferStatus.completed) {
+      return {
+        id: operation.id,
+        network: operation.target.network,
+        targetAmount: operation.targetAmount,
+        targetCurrency: operation.targetCurrency,
+        status: operation.status,
+        transactionHash: operation.transactionHash!,
+      } satisfies CompletedFundOperation;
+    } else {
+      throw new Error("Transfer is not terminal");
+    }
+  };
+
+  const waitOptions = options.waitOptions || {
+    timeoutSeconds: 900,
+    intervalSeconds: 1,
+  };
+
+  return await wait(reload, isTerminal, transform, waitOptions);
+}
+
+const isTerminal = (operation: Transfer): boolean => {
+  return (
+    operation.status === TransferStatus.completed || operation.status === TransferStatus.failed
+  );
+};

package/actions/evm/swap/createSwapQuote.ts

@@ -0,0 +1,148 @@
+import { sendSwapTransaction } from "./sendSwapTransaction.js";
+import {
+  CreateSwapQuoteOptions,
+  CreateSwapQuoteResult,
+  ExecuteSwapQuoteOptions,
+  ExecuteSwapQuoteResult,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import {
+  CdpOpenApiClientType,
+  CreateSwapQuoteResponse,
+  type SendEvmTransactionBodyNetwork,
+} from "../../../openapi-client/index.js";
+import { Address, Hex } from "../../../types/misc.js";
+
+/**
+ * Creates a quote for a swap between two tokens on an EVM network.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use to create the swap quote.
+ * @param {CreateSwapQuoteOptions} options - The options for creating a swap quote.
+ *
+ * @returns {Promise<CreateSwapQuoteResult | SwapUnavailableResult>} A promise that resolves to the swap quote result or a response indicating that liquidity is unavailable.
+ *
+ * @example **Creating a swap quote**
+ * ```ts
+ * const swapQuote = await createSwapQuote(client, {
+ *   network: "ethereum",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: "0x1234567890123456789012345678901234567890"
+ * });
+ * ```
+ */
+export async function createSwapQuote(
+  client: CdpOpenApiClientType,
+  options: CreateSwapQuoteOptions,
+): Promise<CreateSwapQuoteResult | SwapUnavailableResult> {
+  // Validate required parameters
+  if (!options.taker) {
+    throw new Error("taker is required for createSwapQuote");
+  }
+
+  // Store validated taker for type safety
+  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,
+  });
+
+  // Check if liquidity is unavailable
+  if (!response.liquidityAvailable) {
+    // Return the SwapUnavailableResult
+    return {
+      liquidityAvailable: false,
+    };
+  }
+
+  // At this point we know it's a CreateSwapQuoteResponse with liquidityAvailable as true
+  const swapResponse = response as CreateSwapQuoteResponse;
+  const result: CreateSwapQuoteResult = {
+    liquidityAvailable: true,
+    network: options.network,
+    toToken: swapResponse.toToken as Address,
+    fromToken: swapResponse.fromToken as Address,
+    fromAmount: BigInt(swapResponse.fromAmount),
+    toAmount: BigInt(swapResponse.toAmount),
+    minToAmount: BigInt(swapResponse.minToAmount),
+    blockNumber: BigInt(swapResponse.blockNumber),
+    fees: {
+      gasFee: swapResponse.fees.gasFee
+        ? {
+            amount: BigInt(swapResponse.fees.gasFee.amount),
+            token: swapResponse.fees.gasFee.token as Address,
+          }
+        : undefined,
+      protocolFee: swapResponse.fees.protocolFee
+        ? {
+            amount: BigInt(swapResponse.fees.protocolFee.amount),
+            token: swapResponse.fees.protocolFee.token as Address,
+          }
+        : undefined,
+    },
+    issues: {
+      allowance: swapResponse.issues.allowance
+        ? {
+            currentAllowance: BigInt(swapResponse.issues.allowance.currentAllowance),
+            spender: swapResponse.issues.allowance.spender as Address,
+          }
+        : undefined,
+      balance: swapResponse.issues.balance
+        ? {
+            token: swapResponse.issues.balance.token as Address,
+            currentBalance: BigInt(swapResponse.issues.balance.currentBalance),
+            requiredBalance: BigInt(swapResponse.issues.balance.requiredBalance),
+          }
+        : undefined,
+      simulationIncomplete: swapResponse.issues.simulationIncomplete,
+    },
+    transaction: swapResponse.transaction
+      ? {
+          to: swapResponse.transaction.to as Address,
+          data: swapResponse.transaction.data as Hex,
+          value: BigInt(swapResponse.transaction.value),
+          gas: BigInt(swapResponse.transaction.gas),
+          gasPrice: BigInt(swapResponse.transaction.gasPrice),
+        }
+      : undefined,
+    permit2: swapResponse.permit2
+      ? {
+          eip712: {
+            domain: {
+              ...swapResponse.permit2.eip712.domain,
+              verifyingContract: swapResponse.permit2.eip712.domain.verifyingContract as
+                | Address
+                | undefined,
+              salt: swapResponse.permit2.eip712.domain.salt as Hex | undefined,
+            },
+            types: swapResponse.permit2.eip712.types,
+            primaryType: swapResponse.permit2.eip712.primaryType,
+            message: swapResponse.permit2.eip712.message,
+          },
+        }
+      : undefined,
+    // Add the execute method
+    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 };
+    },
+  };
+
+  return result;
+}

package/actions/evm/swap/getSwapPrice.ts

@@ -0,0 +1,95 @@
+import {
+  GetSwapPriceOptions,
+  GetSwapPriceResult,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import { CdpOpenApiClientType, GetSwapPriceResponse } from "../../../openapi-client/index.js";
+import { Address } from "../../../types/misc.js";
+
+/**
+ * Gets the price for a swap between two tokens on an EVM network.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use to get the swap price.
+ * @param {GetSwapPriceOptions} options - The options for getting a swap price.
+ *
+ * @returns {Promise<GetSwapPriceResult | SwapUnavailableResult>} A promise that resolves to the swap price result or a response indicating that liquidity is unavailable.
+ *
+ * @example **Getting a swap price**
+ * ```ts
+ * const price = await getSwapPrice(client, {
+ *   network: "ethereum-mainnet",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: "0x1234567890123456789012345678901234567890"
+ * });
+ * ```
+ */
+export async function getSwapPrice(
+  client: CdpOpenApiClientType,
+  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,
+  });
+
+  // Check if liquidity is unavailable
+  if (!response.liquidityAvailable) {
+    // Return the SwapUnavailableResult
+    return {
+      liquidityAvailable: false,
+    };
+  }
+
+  // At this point we know it's a GetSwapPriceResponse with liquidityAvailable as true
+  const quoteResponse = response as GetSwapPriceResponse;
+  return {
+    blockNumber: BigInt(quoteResponse.blockNumber),
+    toAmount: BigInt(quoteResponse.toAmount),
+    toToken: quoteResponse.toToken as Address,
+    fees: {
+      gasFee: quoteResponse.fees.gasFee
+        ? {
+            amount: BigInt(quoteResponse.fees.gasFee.amount),
+            token: quoteResponse.fees.gasFee.token as Address,
+          }
+        : undefined,
+      protocolFee: quoteResponse.fees.protocolFee
+        ? {
+            amount: BigInt(quoteResponse.fees.protocolFee.amount),
+            token: quoteResponse.fees.protocolFee.token as Address,
+          }
+        : undefined,
+    },
+    issues: {
+      allowance: quoteResponse.issues.allowance
+        ? {
+            currentAllowance: BigInt(quoteResponse.issues.allowance.currentAllowance),
+            spender: quoteResponse.issues.allowance.spender as Address,
+          }
+        : undefined,
+      balance: quoteResponse.issues.balance
+        ? {
+            token: quoteResponse.issues.balance.token as Address,
+            currentBalance: BigInt(quoteResponse.issues.balance.currentBalance),
+            requiredBalance: BigInt(quoteResponse.issues.balance.requiredBalance),
+          }
+        : undefined,
+      simulationIncomplete: quoteResponse.issues.simulationIncomplete,
+    },
+    liquidityAvailable: true,
+    minToAmount: BigInt(quoteResponse.minToAmount),
+    fromAmount: BigInt(quoteResponse.fromAmount),
+    fromToken: quoteResponse.fromToken as Address,
+    gas: quoteResponse.gas ? BigInt(quoteResponse.gas) : undefined,
+    gasPrice: quoteResponse.gasPrice ? BigInt(quoteResponse.gasPrice) : undefined,
+  };
+}

package/actions/evm/swap/sendSwapTransaction.ts

@@ -0,0 +1,173 @@
+import { concat, numberToHex, size } from "viem";
+
+import { createSwapQuote } from "./createSwapQuote.js";
+import { sendTransaction } from "../sendTransaction.js";
+
+import type { SendSwapTransactionOptions, SendSwapTransactionResult } from "./types.js";
+import type {
+  CreateSwapQuoteResult,
+  CreateSwapQuoteOptions,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import type {
+  CdpOpenApiClientType,
+  SendEvmTransactionBodyNetwork,
+} from "../../../openapi-client/index.js";
+import type { Hex } from "../../../types/misc.js";
+import type { TransactionRequestEIP1559 } from "viem";
+
+/**
+ * Sends a swap transaction to the blockchain.
+ * 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/typescript/evm/account.sendSwapTransaction.ts` for example code on handling token approvals.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use for sending the swap.
+ * @param {SendSwapTransactionOptions} options - The options for the swap submission.
+ *
+ * @returns {Promise<SendSwapTransactionResult>} A promise that resolves to the transaction hash.
+ *
+ * @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: account.address
+ * });
+ *
+ * // Check if liquidity is available
+ * if (!swapQuote.liquidityAvailable) {
+ *   console.error("Insufficient liquidity for swap");
+ *   return;
+ * }
+ *
+ * // Send the swap
+ * const result = await sendSwapTransaction(client, {
+ *   address: account.address,
+ *   swapQuote: swapQuote
+ * });
+ *
+ * console.log(`Swap sent with transaction hash: ${result.transactionHash}`);
+ * ```
+ *
+ * @example **Sending a swap with inline options (all-in-one)**
+ * ```ts
+ * // Send swap in one call
+ * const result = await sendSwapTransaction(client, {
+ *   address: account.address,
+ *   network: "base",
+ *   toToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   fromToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+ *   fromAmount: BigInt("1000000000000000000"), // 1 WETH in wei
+ *   taker: account.address
+ * });
+ *
+ * console.log(`Swap sent with transaction hash: ${result.transactionHash}`);
+ * ```
+ */
+export async function sendSwapTransaction(
+  client: CdpOpenApiClientType,
+  options: SendSwapTransactionOptions,
+): Promise<SendSwapTransactionResult> {
+  const { address, 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 (InlineSendSwapTransactionOptions)
+    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,
+    });
+  }
+
+  // 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) {
+    // Sign the Permit2 EIP-712 message
+    const signature = await client.signEvmTypedData(
+      address,
+      {
+        domain: swap.permit2.eip712.domain,
+        types: swap.permit2.eip712.types,
+        primaryType: swap.permit2.eip712.primaryType,
+        message: swap.permit2.eip712.message,
+      },
+      idempotencyKey,
+    );
+
+    // Calculate the signature length as a 32-byte hex value
+    const signatureLengthInHex = numberToHex(size(signature.signature as Hex), {
+      signed: false,
+      size: 32,
+    });
+
+    // Append the signature length and signature to the transaction data
+    txData = concat([txData, signatureLengthInHex, signature.signature as Hex]);
+  }
+
+  // Create a transaction object
+  const transaction: TransactionRequestEIP1559 = {
+    to: swap.transaction.to as `0x${string}`,
+    data: txData,
+    // Only include these properties if they exist
+    ...(swap.transaction.value ? { value: BigInt(swap.transaction.value) } : {}),
+    ...(swap.transaction.gas ? { gas: BigInt(swap.transaction.gas) } : {}),
+  };
+
+  // Use sendTransaction instead of directly calling client.sendEvmTransaction
+  const result = await sendTransaction(client, {
+    address,
+    network: swap.network as SendEvmTransactionBodyNetwork,
+    transaction,
+    idempotencyKey,
+  });
+
+  return {
+    transactionHash: result.transactionHash,
+  };
+}

package/actions/evm/swap/types.ts

@@ -0,0 +1,94 @@
+import type {
+  CreateSwapQuoteOptions,
+  CreateSwapQuoteResult,
+  SwapUnavailableResult,
+} from "../../../client/evm/evm.types.js";
+import type { SendEvmTransactionBodyNetwork } from "../../../openapi-client/index.js";
+import type { Address, Hex } from "../../../types/misc.js";
+
+/**
+ * Base options for sending a swap transaction.
+ */
+interface BaseSendSwapTransactionOptions {
+  /**
+   * The address of the account that will execute the swap.
+   */
+  address: Address;
+
+  /**
+   * Optional idempotency key for the request.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options when providing an already created swap quote.
+ */
+interface QuoteBasedSendSwapTransactionOptions extends BaseSendSwapTransactionOptions {
+  /**
+   * The swap quote returned by the createSwapQuote method.
+   */
+  swapQuote: CreateSwapQuoteResult;
+}
+
+/**
+ * Options when creating a swap quote inline.
+ */
+interface InlineSendSwapTransactionOptions extends BaseSendSwapTransactionOptions {
+  /**
+   * 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 address that will perform the swap. */
+  taker: Address;
+  /** 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;
+}
+
+/**
+ * Options for sending a swap transaction.
+ * Either provide a pre-created swap quote result or inline swap parameters.
+ */
+export type SendSwapTransactionOptions =
+  | QuoteBasedSendSwapTransactionOptions
+  | InlineSendSwapTransactionOptions;
+
+/**
+ * Result of sending a swap transaction.
+ */
+export interface SendSwapTransactionResult {
+  /**
+   * The transaction hash of the submitted swap.
+   */
+  transactionHash: Hex;
+}
+
+/**
+ * Options for creating a swap quote (account-level).
+ */
+export type QuoteSwapOptions = Omit<CreateSwapQuoteOptions, "taker">;
+
+/**
+ * Result of creating a swap quote (account-level).
+ */
+export type QuoteSwapResult = CreateSwapQuoteResult | SwapUnavailableResult;
+
+/**
+ * Options for executing a token swap (account-level).
+ */
+export type SwapOptions = Omit<SendSwapTransactionOptions, "address">;
+
+/**
+ * Result of executing a token swap (account-level).
+ */
+export type SwapResult = SendSwapTransactionResult;