@coinbase/cdp-sdk 1.28.0 → 1.30.0

package/accounts/solana/toSolanaAccount.ts

@@ -1,11 +1,22 @@
 import { Account, SolanaAccount } from "./types.js";
+import { SolanaQuote } from "../../actions/Quote.js";
+import { SolanaFundOptions, fund } from "../../actions/solana/fund/fund.js";
+import { SolanaQuoteFundOptions, quoteFund } from "../../actions/solana/fund/quoteFund.js";
 import { requestFaucet } from "../../actions/solana/requestFaucet.js";
+import { sendTransaction, SendTransactionResult } from "../../actions/solana/sendTransaction.js";
 import { signMessage } from "../../actions/solana/signMessage.js";
-import { signTransaction } from "../../actions/solana/signTransaction.js";
+import { signTransaction, SignTransactionResult } from "../../actions/solana/signTransaction.js";
 import { transfer, type TransferOptions } from "../../actions/solana/transfer.js";
+import { FundOperationResult } from "../../actions/types.js";
+import {
+  WaitForFundOperationOptions,
+  WaitForFundOperationResult,
+  waitForFundOperationReceipt,
+} from "../../actions/waitForFundOperationReceipt.js";
 import { Analytics } from "../../analytics.js";
 import {
   RequestFaucetOptions,
+  SendTransactionOptions,
   SignatureResult,
   SignMessageOptions,
   SignTransactionOptions,
@@ -35,6 +46,7 @@ export function toSolanaAccount(
   const account: SolanaAccount = {
     address: options.account.address,
     name: options.account.name,
+    policies: options.account.policies,
     async requestFaucet(options: Omit<RequestFaucetOptions, "address">): Promise<SignatureResult> {
       Analytics.trackAction({
         action: "request_faucet",
@@ -59,7 +71,7 @@ export function toSolanaAccount(
     },
     async signTransaction(
       options: Omit<SignTransactionOptions, "address">,
-    ): Promise<SignatureResult> {
+    ): Promise<SignTransactionResult> {
       Analytics.trackAction({
         action: "sign_transaction",
         accountType: "solana",
@@ -70,7 +82,18 @@ export function toSolanaAccount(
         address: account.address,
       });
     },
-    policies: options.account.policies,
+    async sendTransaction(
+      options: Omit<SendTransactionOptions, "address">,
+    ): Promise<SendTransactionResult> {
+      Analytics.trackAction({
+        action: "send_transaction",
+        accountType: "solana",
+      });
+
+      return sendTransaction(apiClient, {
+        ...options,
+      });
+    },
     async transfer(options: Omit<TransferOptions, "from">): Promise<SignatureResult> {
       Analytics.trackAction({
         action: "transfer",
@@ -85,6 +108,38 @@ export function toSolanaAccount(
         from: account.address,
       });
     },
+    async quoteFund(options: Omit<SolanaQuoteFundOptions, "address">): Promise<SolanaQuote> {
+      Analytics.trackAction({
+        action: "quote_fund",
+        accountType: "solana",
+      });
+
+      return quoteFund(apiClient, {
+        ...options,
+        address: account.address,
+      });
+    },
+    async fund(options: Omit<SolanaFundOptions, "address">): Promise<FundOperationResult> {
+      Analytics.trackAction({
+        action: "fund",
+        accountType: "solana",
+      });
+
+      return fund(apiClient, {
+        ...options,
+        address: account.address,
+      });
+    },
+    async waitForFundOperationReceipt(
+      options: WaitForFundOperationOptions,
+    ): Promise<WaitForFundOperationResult> {
+      Analytics.trackAction({
+        action: "wait_for_fund_operation_receipt",
+        accountType: "solana",
+      });
+
+      return waitForFundOperationReceipt(apiClient, options);
+    },
   };
 
   return account;

package/actions/Quote.ts

@@ -0,0 +1,154 @@
+import { FundOperationResult } from "./types.js";
+import { CdpOpenApiClientType } from "../openapi-client/index.js";
+
+/**
+ * Base class representing a funding quote that can be executed.
+ */
+abstract class BaseQuote {
+  /** Quote for the transfer. */
+  public quoteId: string;
+  /** The amount in fiat currency. */
+  public fiatAmount: string;
+  /** The fiat currency. */
+  public fiatCurrency: string;
+  /** The amount in the token to transfer. */
+  public tokenAmount: string;
+  /** The token to transfer. */
+  public token: string;
+  /** Fees in the token to transfer. */
+  public fees: {
+    /** The type of fee. */
+    type: "exchange_fee" | "network_fee";
+    amount: string;
+    currency: string;
+  }[];
+
+  protected apiClient: CdpOpenApiClientType;
+
+  /**
+   * Creates a new BaseQuote instance.
+   *
+   * @param apiClient - The API client.
+   * @param quoteId - The quote ID.
+   * @param fiatAmount - The amount in fiat currency.
+   * @param fiatCurrency - The fiat currency.
+   * @param tokenAmount - The amount in the token to transfer.
+   * @param token - The token to transfer.
+   * @param fees - Fees for the transfer.
+   */
+  constructor(
+    apiClient: CdpOpenApiClientType,
+    quoteId: string,
+    fiatAmount: string,
+    fiatCurrency: string,
+    tokenAmount: string,
+    token: string,
+    fees: {
+      type: "exchange_fee" | "network_fee";
+      amount: string;
+      currency: string;
+    }[],
+  ) {
+    this.apiClient = apiClient;
+    this.quoteId = quoteId;
+    this.fiatAmount = fiatAmount;
+    this.fiatCurrency = fiatCurrency;
+    this.tokenAmount = tokenAmount;
+    this.token = token;
+    this.fees = fees;
+  }
+
+  /**
+   * Executes the quote to perform the actual fund transfer.
+   *
+   * @returns A promise that resolves to the result of the executed quote.
+   */
+  async execute(): Promise<FundOperationResult> {
+    const transfer = await this.apiClient.executePaymentTransferQuote(this.quoteId);
+
+    return {
+      id: transfer.id,
+      network: transfer.target.network,
+      targetAmount: transfer.targetAmount,
+      targetCurrency: transfer.targetCurrency,
+      status: transfer.status,
+      transactionHash: transfer.transactionHash,
+    };
+  }
+}
+
+/**
+ * A class representing an EVM funding quote that can be executed.
+ */
+export class EvmQuote extends BaseQuote {
+  /** Network to transfer the funds to (EVM networks). */
+  public network: "base" | "ethereum";
+
+  /**
+   * Creates a new EvmQuote instance.
+   *
+   * @param apiClient - The API client.
+   * @param quoteId - The quote ID.
+   * @param network - The EVM network to transfer funds to.
+   * @param fiatAmount - The amount in fiat currency.
+   * @param fiatCurrency - The fiat currency.
+   * @param tokenAmount - The amount in the token to transfer.
+   * @param token - The token to transfer.
+   * @param fees - Fees for the transfer.
+   */
+  constructor(
+    apiClient: CdpOpenApiClientType,
+    quoteId: string,
+    network: "base" | "ethereum",
+    fiatAmount: string,
+    fiatCurrency: string,
+    tokenAmount: string,
+    token: string,
+    fees: {
+      type: "exchange_fee" | "network_fee";
+      amount: string;
+      currency: string;
+    }[],
+  ) {
+    super(apiClient, quoteId, fiatAmount, fiatCurrency, tokenAmount, token, fees);
+    this.network = network;
+  }
+}
+
+/**
+ * A class representing a Solana funding quote that can be executed.
+ */
+export class SolanaQuote extends BaseQuote {
+  /** Network to transfer the funds to (Solana). */
+  public network: "solana";
+
+  /**
+   * Creates a new SolanaQuote instance.
+   *
+   * @param apiClient - The API client.
+   * @param quoteId - The quote ID.
+   * @param network - The Solana network to transfer funds to.
+   * @param fiatAmount - The amount in fiat currency.
+   * @param fiatCurrency - The fiat currency.
+   * @param tokenAmount - The amount in the token to transfer.
+   * @param token - The token to transfer.
+   * @param fees - Fees for the transfer.
+   */
+  constructor(
+    apiClient: CdpOpenApiClientType,
+    quoteId: string,
+    network: "solana",
+    fiatAmount: string,
+    fiatCurrency: string,
+    tokenAmount: string,
+    token: string,
+    fees: {
+      type: "exchange_fee" | "network_fee";
+      amount: string;
+      currency: string;
+    }[],
+  ) {
+    super(apiClient, quoteId, fiatAmount, fiatCurrency, tokenAmount, token, fees);
+    this.network = network;
+  }
+}

package/actions/evm/fund/fund.ts

@@ -1,23 +1,19 @@
 import { formatUnits } from "viem";
 
-import { FundOperationResult } from "./types.js";
 import { UserInputValidationError } from "../../../errors.js";
 import {
   CreatePaymentTransferQuoteBodySourceType,
   CreatePaymentTransferQuoteBodyTargetType,
   type CdpOpenApiClientType,
 } from "../../../openapi-client/index.js";
+import { BaseFundOptions, FundOperationResult } from "../../types.js";
 
 /**
  * Options for funding an EVM account.
  */
-export interface FundOptions {
-  /** The address of the account. */
-  address: string;
+export interface EvmFundOptions extends BaseFundOptions {
   /** The network to request funds from. */
   network: "base" | "ethereum";
-  /** The amount to fund the account with, in atomic units (wei) of the token. */
-  amount: bigint;
   /** The token to request funds for. */
   token: "eth" | "usdc";
 }
@@ -32,8 +28,15 @@ export interface FundOptions {
  */
 export async function fund(
   apiClient: CdpOpenApiClientType,
-  options: FundOptions,
+  options: EvmFundOptions,
 ): Promise<FundOperationResult> {
+  if (options.token !== "eth" && options.token !== "usdc") {
+    throw new UserInputValidationError("Invalid token, must be eth or usdc");
+  }
+
+  const decimals = options.token === "eth" ? 18 : 6;
+  const amount = formatUnits(options.amount, decimals);
+
   const paymentMethods = await apiClient.getPaymentMethods();
   const cardPaymentMethod = paymentMethods.find(
     method => method.type === "card" && method.actions.includes("source"),
@@ -43,13 +46,6 @@ export async function fund(
     throw new Error("No card found to fund account");
   }
 
-  if (options.token !== "eth" && options.token !== "usdc") {
-    throw new UserInputValidationError("Invalid token, must be eth or usdc");
-  }
-
-  const decimals = options.token === "eth" ? 18 : 6;
-  const amount = formatUnits(options.amount, decimals);
-
   const response = await apiClient.createPaymentTransferQuote({
     sourceType: CreatePaymentTransferQuoteBodySourceType.payment_method,
     source: {

package/actions/evm/fund/quoteFund.ts

@@ -1,23 +1,20 @@
 import { formatUnits } from "viem";
 
-import { Quote } from "./Quote.js";
 import { UserInputValidationError } from "../../../errors.js";
 import {
   CreatePaymentTransferQuoteBodySourceType,
   CreatePaymentTransferQuoteBodyTargetType,
   type CdpOpenApiClientType,
 } from "../../../openapi-client/index.js";
+import { EvmQuote } from "../../Quote.js";
+import { BaseQuoteFundOptions } from "../../types.js";
 
 /**
  * Options for getting a quote to fund an EVM account.
  */
-export interface QuoteFundOptions {
-  /** The address of the account. */
-  address: string;
+export interface EvmQuoteFundOptions extends BaseQuoteFundOptions {
   /** The network to request funds from. */
   network: "base" | "ethereum";
-  /** The amount to fund the account with, in atomic units (wei) of the token. */
-  amount: bigint;
   /** The token to request funds for. */
   token: "eth" | "usdc";
 }
@@ -32,8 +29,15 @@ export interface QuoteFundOptions {
  */
 export async function quoteFund(
   apiClient: CdpOpenApiClientType,
-  options: QuoteFundOptions,
-): Promise<Quote> {
+  options: EvmQuoteFundOptions,
+): Promise<EvmQuote> {
+  if (options.token !== "eth" && options.token !== "usdc") {
+    throw new UserInputValidationError("Invalid token, must be eth or usdc");
+  }
+
+  const decimals = options.token === "eth" ? 18 : 6;
+  const amount = formatUnits(options.amount, decimals);
+
   const paymentMethods = await apiClient.getPaymentMethods();
   const cardPaymentMethod = paymentMethods.find(
     method => method.type === "card" && method.actions.includes("source"),
@@ -43,13 +47,6 @@ export async function quoteFund(
     throw new Error("No card found to fund account");
   }
 
-  if (options.token !== "eth" && options.token !== "usdc") {
-    throw new UserInputValidationError("Invalid token, must be eth or usdc");
-  }
-
-  const decimals = options.token === "eth" ? 18 : 6;
-  const amount = formatUnits(options.amount, decimals);
-
   const response = await apiClient.createPaymentTransferQuote({
     sourceType: CreatePaymentTransferQuoteBodySourceType.payment_method,
     source: {
@@ -65,7 +62,7 @@ export async function quoteFund(
     currency: options.token,
   });
 
-  return new Quote(
+  return new EvmQuote(
     apiClient,
     response.transfer.id,
     options.network,

package/actions/evm/getUserOperation.ts

@@ -39,5 +39,6 @@ export async function getUserOperation(
     status: userOp.status,
     transactionHash: userOp.transactionHash as Hex | undefined,
     userOpHash: userOp.userOpHash as Hex,
+    receipts: userOp.receipts,
   };
 }

package/actions/evm/spend-permissions/account.use.ts

@@ -0,0 +1,48 @@
+import { encodeFunctionData } from "viem";
+
+import {
+  SPEND_PERMISSION_MANAGER_ABI,
+  SPEND_PERMISSION_MANAGER_ADDRESS,
+} from "../../../spend-permissions/constants.js";
+import { serializeEIP1559Transaction } from "../../../utils/serializeTransaction.js";
+
+import type { UseSpendPermissionOptions } from "./types.js";
+import type {
+  CdpOpenApiClientType,
+  SendEvmTransactionBodyNetwork,
+} from "../../../openapi-client/index.js";
+import type { Address, Hex } from "../../../types/misc.js";
+import type { TransactionResult } from "../sendTransaction.js";
+
+/**
+ * Use a spend permission to spend tokens.
+ *
+ * @param apiClient - The API client to use.
+ * @param address - The address of the account to use the spend permission on.
+ * @param options - The options for the spend permission.
+ *
+ * @returns The transaction hash of the spend permission.
+ */
+export async function useSpendPermission(
+  apiClient: CdpOpenApiClientType,
+  address: Address,
+  options: UseSpendPermissionOptions,
+): Promise<TransactionResult> {
+  const { spendPermission, value, network } = options;
+
+  const result = await apiClient.sendEvmTransaction(address, {
+    transaction: serializeEIP1559Transaction({
+      to: SPEND_PERMISSION_MANAGER_ADDRESS,
+      data: encodeFunctionData({
+        abi: SPEND_PERMISSION_MANAGER_ABI,
+        functionName: "spend",
+        args: [spendPermission, value],
+      }),
+    }),
+    network: network as SendEvmTransactionBodyNetwork,
+  });
+
+  return {
+    transactionHash: result.transactionHash as Hex,
+  };
+}

package/actions/evm/spend-permissions/smartAccount.use.ts

@@ -0,0 +1,49 @@
+import { encodeFunctionData } from "viem";
+
+import {
+  SPEND_PERMISSION_MANAGER_ABI,
+  SPEND_PERMISSION_MANAGER_ADDRESS,
+} from "../../../spend-permissions/constants.js";
+import { type SendUserOperationReturnType, sendUserOperation } from "../sendUserOperation.js";
+
+import type { UseSpendPermissionOptions } from "./types.js";
+import type { EvmSmartAccount } from "../../../accounts/evm/types.js";
+import type {
+  CdpOpenApiClientType,
+  EvmUserOperationNetwork,
+} from "../../../openapi-client/index.js";
+
+/**
+ * Use a spend permission to spend tokens.
+ *
+ * @param apiClient - The API client to use.
+ * @param account - The smart account to use.
+ * @param options - The options for the spend permission.
+ *
+ * @returns The result of the spend permission.
+ */
+export function useSpendPermission(
+  apiClient: CdpOpenApiClientType,
+  account: EvmSmartAccount,
+  options: UseSpendPermissionOptions,
+): Promise<SendUserOperationReturnType> {
+  const { spendPermission, value, network } = options;
+
+  const data = encodeFunctionData({
+    abi: SPEND_PERMISSION_MANAGER_ABI,
+    functionName: "spend",
+    args: [spendPermission, value],
+  });
+
+  return sendUserOperation(apiClient, {
+    smartAccount: account,
+    network: network as EvmUserOperationNetwork,
+    calls: [
+      {
+        to: SPEND_PERMISSION_MANAGER_ADDRESS,
+        data,
+        value: 0n,
+      },
+    ],
+  });
+}

package/actions/evm/spend-permissions/types.ts

@@ -0,0 +1,13 @@
+import type { SpendPermission, SpendPermissionNetworks } from "../../../spend-permissions/types.js";
+
+/**
+ * Options for using a spend permission
+ */
+export type UseSpendPermissionOptions = {
+  /** The spend permission to use */
+  spendPermission: SpendPermission;
+  /** The amount to spend (must be <= allowance) */
+  value: bigint;
+  /** The network to execute the transaction on */
+  network: SpendPermissionNetworks;
+};

package/actions/evm/transfer/accountTransferStrategy.ts

@@ -1,6 +1,7 @@
 import { encodeFunctionData, erc20Abi } from "viem";
 
 import { getErc20Address } from "./utils.js";
+import { SendEvmTransactionBodyNetwork } from "../../../openapi-client/index.js";
 import { serializeEIP1559Transaction } from "../../../utils/serializeTransaction.js";
 
 import type { TransferExecutionStrategy } from "./types.js";
@@ -9,6 +10,7 @@ import type { TransactionResult } from "../sendTransaction.js";
 
 export const accountTransferStrategy: TransferExecutionStrategy<EvmAccount> = {
   executeTransfer: async ({ apiClient, from, to, value, token, network }) => {
+    network = network as SendEvmTransactionBodyNetwork;
     if (token === "eth") {
       return apiClient.sendEvmTransaction(from.address, {
         transaction: serializeEIP1559Transaction({

package/actions/evm/types.ts

@@ -1,11 +1,10 @@
-import { FundOptions } from "./fund/fund.js";
-import { Quote } from "./fund/Quote.js";
-import { QuoteFundOptions } from "./fund/quoteFund.js";
-import { FundOperationResult } from "./fund/types.js";
+import { FundOperationResult } from "../types.js";
 import {
   WaitForFundOperationOptions,
   WaitForFundOperationResult,
-} from "./fund/waitForFundOperationReceipt.js";
+} from "../waitForFundOperationReceipt.js";
+import { EvmFundOptions } from "./fund/fund.js";
+import { EvmQuoteFundOptions } from "./fund/quoteFund.js";
 import { SendUserOperationOptions, SendUserOperationReturnType } from "./sendUserOperation.js";
 import { KnownEvmNetworks } from "../../accounts/evm/types.js";
 import {
@@ -14,6 +13,8 @@ import {
   UserOperation,
 } from "../../client/evm/evm.types.js";
 import { Hex } from "../../types/misc.js";
+import { EvmQuote } from "../Quote.js";
+import { UseSpendPermissionOptions } from "./spend-permissions/types.js";
 
 import type { ListTokenBalancesOptions, ListTokenBalancesResult } from "./listTokenBalances.js";
 import type { RequestFaucetOptions, RequestFaucetResult } from "./requestFaucet.js";
@@ -95,7 +96,7 @@ export type Actions = {
    * });
    * ```
    */
-  quoteFund: (options: Omit<QuoteFundOptions, "address">) => Promise<Quote>;
+  quoteFund: (options: Omit<EvmQuoteFundOptions, "address">) => Promise<EvmQuote>;
 
   /**
    * Funds an EVM account with the specified token amount.
@@ -118,7 +119,7 @@ export type Actions = {
    * });
    * ```
    */
-  fund: (options: Omit<FundOptions, "address">) => Promise<FundOperationResult>;
+  fund: (options: Omit<EvmFundOptions, "address">) => Promise<FundOperationResult>;
 
   /**
    * Waits for a fund operation to complete and returns the transfer receipt.
@@ -353,6 +354,46 @@ export type AccountActions = Actions & {
    * ```
    */
   swap: (options: AccountSwapOptions) => Promise<AccountSwapResult>;
+
+  /**
+   * @deprecated Experimental! This method name will change, and is subject to other breaking changes.
+   *
+   * Uses a spend permission to execute a transaction.
+   * This allows the account to spend tokens that have been approved via a spend permission.
+   *
+   * @param {UseSpendPermissionOptions} options - Configuration options for using the spend permission.
+   * @param {SpendPermission} options.spendPermission - The spend permission object containing authorization details.
+   * @param {bigint} options.value - The amount to spend (must not exceed the permission's allowance).
+   * @param {KnownEvmNetworks} options.network - The network to execute the transaction on.
+   *
+   * @returns A promise that resolves to the transaction result.
+   *
+   * @throws {Error} If the network doesn't support spend permissions via CDP API.
+   *
+   * @example
+   * ```typescript
+   * const spendPermission = {
+   *   account: "0x1234...", // Smart account that owns the tokens
+   *   spender: account.address, // This account that can spend
+   *   token: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+   *   allowance: parseEther("0.01"),
+   *   period: 86400, // 1 day
+   *   start: 0,
+   *   end: 281474976710655,
+   *   salt: 0n,
+   *   extraData: "0x",
+   * };
+   *
+   * const result = await account.__experimental_useSpendPermission({
+   *   spendPermission,
+   *   value: parseEther("0.001"), // Spend 0.001 ETH
+   *   network: "base-sepolia",
+   * });
+   * ```
+   */
+  __experimental_useSpendPermission: (
+    options: UseSpendPermissionOptions,
+  ) => Promise<TransactionResult>;
 };
 
 export type SmartAccountActions = Actions & {
@@ -640,4 +681,44 @@ export type SmartAccountActions = Actions & {
   signTypedData: (
     options: Omit<SignTypedDataOptions, "address"> & { network: KnownEvmNetworks },
   ) => Promise<Hex>;
+
+  /**
+   * @deprecated Experimental! This method name will change, and is subject to other breaking changes.
+   *
+   * Uses a spend permission to execute a transaction via user operation.
+   * This allows the smart account to spend tokens that have been approved via a spend permission.
+   *
+   * @param {UseSpendPermissionOptions} options - Configuration options for using the spend permission.
+   * @param {SpendPermission} options.spendPermission - The spend permission object containing authorization details.
+   * @param {bigint} options.value - The amount to spend (must not exceed the permission's allowance).
+   * @param {KnownEvmNetworks} options.network - The network to execute the transaction on.
+   *
+   * @returns A promise that resolves to the user operation result.
+   *
+   * @throws {Error} If the network doesn't support spend permissions via CDP API.
+   *
+   * @example
+   * ```typescript
+   * const spendPermission = {
+   *   account: "0x1234...", // Smart account that owns the tokens
+   *   spender: smartAccount.address, // This smart account that can spend
+   *   token: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+   *   allowance: parseEther("0.01"),
+   *   period: 86400, // 1 day
+   *   start: 0,
+   *   end: 281474976710655,
+   *   salt: 0n,
+   *   extraData: "0x",
+   * };
+   *
+   * const result = await smartAccount.__experimental_useSpendPermission({
+   *   spendPermission,
+   *   value: parseEther("0.001"), // Spend 0.001 ETH
+   *   network: "base-sepolia",
+   * });
+   * ```
+   */
+  __experimental_useSpendPermission: (
+    options: UseSpendPermissionOptions,
+  ) => Promise<SendUserOperationReturnType>;
 };