@coinbase/cdp-sdk 1.9.0 → 1.11.0

package/accounts/evm/toEvmServerAccount.ts

@@ -1,5 +1,14 @@
 import { type TransactionSerializable, serializeTransaction } from "viem";
 
+import { FundOptions, fund } from "../../actions/evm/fund/fund.js";
+import { Quote } from "../../actions/evm/fund/Quote.js";
+import { QuoteFundOptions, quoteFund } from "../../actions/evm/fund/quoteFund.js";
+import { FundOperationResult } from "../../actions/evm/fund/types.js";
+import {
+  WaitForFundOperationOptions,
+  WaitForFundOperationResult,
+  waitForFundOperationReceipt,
+} from "../../actions/evm/fund/waitForFundOperationReceipt.js";
 import {
   listTokenBalances,
   type ListTokenBalancesResult,
@@ -95,6 +104,23 @@ export function toEvmServerAccount(
         address: this.address,
       });
     },
+    async quoteFund(options: Omit<QuoteFundOptions, "address">): Promise<Quote> {
+      return quoteFund(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async fund(options: Omit<FundOptions, "address">): Promise<FundOperationResult> {
+      return fund(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async waitForFundOperationReceipt(
+      options: WaitForFundOperationOptions,
+    ): Promise<WaitForFundOperationResult> {
+      return waitForFundOperationReceipt(apiClient, options);
+    },
     name: options.account.name,
     type: "evm-server",
     policies: options.account.policies,

package/accounts/evm/toEvmSmartAccount.ts

@@ -1,3 +1,12 @@
+import { fund, FundOptions } from "../../actions/evm/fund/fund.js";
+import { Quote } from "../../actions/evm/fund/Quote.js";
+import { quoteFund, QuoteFundOptions } from "../../actions/evm/fund/quoteFund.js";
+import { FundOperationResult } from "../../actions/evm/fund/types.js";
+import {
+  WaitForFundOperationResult,
+  waitForFundOperationReceipt,
+  WaitForFundOperationOptions,
+} from "../../actions/evm/fund/waitForFundOperationReceipt.js";
 import { getUserOperation } from "../../actions/evm/getUserOperation.js";
 import {
   listTokenBalances,
@@ -102,6 +111,23 @@ export function toEvmSmartAccount(
         address: account.address,
       });
     },
+    async quoteFund(options: Omit<QuoteFundOptions, "address">): Promise<Quote> {
+      return quoteFund(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async fund(options: Omit<FundOptions, "address">): Promise<FundOperationResult> {
+      return fund(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async waitForFundOperationReceipt(
+      options: WaitForFundOperationOptions,
+    ): Promise<WaitForFundOperationResult> {
+      return waitForFundOperationReceipt(apiClient, options);
+    },
     name: options.smartAccount.name,
     type: "evm-smart",
   };

package/accounts/evm/types.ts

@@ -3,8 +3,7 @@ import { SignableMessage, TransactionSerializable } from "viem";
 import { Prettify } from "../../types/utils.js";
 
 import type { AccountActions, SmartAccountActions } from "../../actions/evm/types.js";
-import type { EIP712Message } from "../../openapi-client/generated/coinbaseDeveloperPlatformAPIs.schemas.js";
-import type { Address, Hash, Hex } from "../../types/misc.js";
+import type { Address, EIP712Message, Hash, Hex } from "../../types/misc.js";
 
 /**
  * Base type for any Ethereum account with signing capabilities.

package/actions/evm/fund/Quote.ts

@@ -0,0 +1,83 @@
+import { FundOperationResult } from "./types.js";
+import { CdpOpenApiClientType } from "../../../openapi-client/index.js";
+
+/**
+ * A class representing a funding quote that can be executed.
+ */
+export class Quote {
+  /** Quote for the transfer. */
+  public quoteId: string;
+  /** Network to transfer the funds to. */
+  public network: "base" | "ethereum";
+  /** 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;
+  }[];
+
+  private apiClient: CdpOpenApiClientType;
+
+  /**
+   * Creates a new Quote instance.
+   *
+   * @param apiClient - The API client.
+   * @param quoteId - The quote ID.
+   * @param network - The 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;
+    }[],
+  ) {
+    this.apiClient = apiClient;
+    this.quoteId = quoteId;
+    this.network = network;
+    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,
+    };
+  }
+}

package/actions/evm/fund/fund.ts

@@ -0,0 +1,76 @@
+import { formatUnits } from "viem";
+
+import { FundOperationResult } from "./types.js";
+import {
+  CreatePaymentTransferQuoteBodySourceType,
+  CreatePaymentTransferQuoteBodyTargetType,
+  type CdpOpenApiClientType,
+} from "../../../openapi-client/index.js";
+
+/**
+ * Options for funding an EVM account.
+ */
+export interface FundOptions {
+  /** The address of the account. */
+  address: string;
+  /** The network to request funds from. */
+  network: "base";
+  /** 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";
+}
+
+/**
+ * Funds an EVM account.
+ *
+ * @param apiClient - The API client.
+ * @param options - The options for funding an EVM account.
+ *
+ * @returns A promise that resolves to the fund operation result.
+ */
+export async function fund(
+  apiClient: CdpOpenApiClientType,
+  options: FundOptions,
+): Promise<FundOperationResult> {
+  const paymentMethods = await apiClient.getPaymentMethods();
+  const cardPaymentMethod = paymentMethods.find(
+    method => method.type === "card" && method.actions.includes("source"),
+  );
+
+  if (!cardPaymentMethod) {
+    throw new Error("No card found to fund account");
+  }
+
+  if (options.token.toLowerCase() !== "eth" && options.token.toLowerCase() !== "usdc") {
+    throw new Error("Invalid currency, 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: {
+      id: cardPaymentMethod.id,
+    },
+    targetType: CreatePaymentTransferQuoteBodyTargetType.crypto_rail,
+    target: {
+      currency: options.token,
+      network: options.network,
+      address: options.address,
+    },
+    amount,
+    currency: options.token,
+    execute: true,
+  });
+
+  return {
+    id: response.transfer.id,
+    network: response.transfer.target.network,
+    status: response.transfer.status,
+    targetAmount: response.transfer.targetAmount,
+    targetCurrency: response.transfer.targetCurrency,
+    transactionHash: response.transfer.transactionHash,
+  };
+}

package/actions/evm/fund/quoteFund.ts

@@ -0,0 +1,81 @@
+import { formatUnits } from "viem";
+
+import { Quote } from "./Quote.js";
+import {
+  CreatePaymentTransferQuoteBodySourceType,
+  CreatePaymentTransferQuoteBodyTargetType,
+  type CdpOpenApiClientType,
+} from "../../../openapi-client/index.js";
+
+/**
+ * Options for getting a quote to fund an EVM account.
+ */
+export interface QuoteFundOptions {
+  /** The address of the account. */
+  address: string;
+  /** The network to request funds from. */
+  network: "base";
+  /** 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";
+}
+
+/**
+ * Gets a quote to fund an EVM account.
+ *
+ * @param apiClient - The API client.
+ * @param options - The options for getting a quote to fund an EVM account.
+ *
+ * @returns A promise that resolves to the quote.
+ */
+export async function quoteFund(
+  apiClient: CdpOpenApiClientType,
+  options: QuoteFundOptions,
+): Promise<Quote> {
+  const paymentMethods = await apiClient.getPaymentMethods();
+  const cardPaymentMethod = paymentMethods.find(
+    method => method.type === "card" && method.actions.includes("source"),
+  );
+
+  if (!cardPaymentMethod) {
+    throw new Error("No card found to fund account");
+  }
+
+  if (options.token.toLowerCase() !== "eth" && options.token.toLowerCase() !== "usdc") {
+    throw new Error("Invalid currency, 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: {
+      id: cardPaymentMethod.id,
+    },
+    targetType: CreatePaymentTransferQuoteBodyTargetType.crypto_rail,
+    target: {
+      currency: options.token,
+      network: options.network,
+      address: options.address,
+    },
+    amount,
+    currency: options.token,
+  });
+
+  return new Quote(
+    apiClient,
+    response.transfer.id,
+    options.network,
+    response.transfer.sourceAmount,
+    response.transfer.sourceCurrency,
+    response.transfer.targetAmount,
+    response.transfer.targetCurrency,
+    response.transfer.fees.map(fee => ({
+      type: fee.type,
+      amount: fee.amount,
+      currency: fee.currency,
+    })),
+  );
+}

package/actions/evm/fund/types.ts

@@ -0,0 +1,16 @@
+import { TransferStatus } from "../../../openapi-client/index.js";
+
+export type FundOperationResult = {
+  /** The transfer that was created to fund the account. */
+  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 fund operation. */
+  status: TransferStatus;
+  /** The transaction hash of the transfer. */
+  transactionHash?: string;
+};

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/types.ts

@@ -1,3 +1,11 @@
+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 {
+  WaitForFundOperationOptions,
+  WaitForFundOperationResult,
+} from "./fund/waitForFundOperationReceipt.js";
 import { SendUserOperationOptions, SendUserOperationReturnType } from "./sendUserOperation.js";
 import { GetUserOperationOptions, UserOperation } from "../../client/evm/evm.types.js";
 import { Hex } from "../../types/misc.js";
@@ -50,6 +58,71 @@ type Actions = {
    * ```
    */
   requestFaucet: (options: Omit<RequestFaucetOptions, "address">) => Promise<RequestFaucetResult>;
+
+  /**
+   * Gets a quote to fund an EVM account.
+   *
+   * @param options - The options for the quote fund.
+   * @param options.network - The network to fund the account on.
+   * @param options.token - The token to fund the account with.
+   * @param options.amount - The amount of the token to fund represented as an atomic unit.
+   * It's common to use `parseUnits` utils from viem to convert to atomic units.
+   * Otherwise, you can pass atomic units directly.
+   *
+   * @returns A promise that resolves to a Quote object containing details about the funding operation.
+   *
+   * @example
+   * ```ts
+   * const quote = await account.quoteFund({
+   *   network: "base",
+   *   token: "usdc",
+   *   amount: 1000000n,
+   * });
+   * ```
+   */
+  quoteFund: (options: Omit<QuoteFundOptions, "address">) => Promise<Quote>;
+
+  /**
+   * Funds an EVM account with the specified token amount.
+   *
+   * @param options - The options for the fund operation.
+   * @param options.network - The network to fund the account on.
+   * @param options.token - The token to fund the account with (e.g., 'usdc').
+   * @param options.amount - The amount of the token to fund represented as an atomic unit.
+   * It's common to use `parseUnits` utils from viem to convert to atomic units.
+   * Otherwise, you can pass atomic units directly.
+   *
+   * @returns A promise that resolves to the fund operation result containing the transfer details.
+   *
+   * @example
+   * ```ts
+   * const fundOperation = await account.fund({
+   *   network: "base",
+   *   token: "usdc",
+   *   amount: 1000000n,
+   * });
+   * ```
+   */
+  fund: (options: Omit<FundOptions, "address">) => Promise<FundOperationResult>;
+
+  /**
+   * Waits for a fund operation to complete and returns the transfer receipt.
+   *
+   * @param options - The options for the wait for fund operation.
+   * @param options.transferId - The ID of the transfer to wait for.
+   *
+   * @returns A promise that resolves to the completed transfer receipt containing details about the funding operation.
+   *
+   * @example
+   * ```ts
+   * const completedTransfer = await account.waitForFundOperationReceipt({
+   *   transferId: "transfer_123",
+   * });
+   * ```
+   */
+  waitForFundOperationReceipt(
+    options: WaitForFundOperationOptions,
+  ): Promise<WaitForFundOperationResult>;
 };
 
 export type AccountActions = Actions & {

package/client/evm/constants.ts

@@ -0,0 +1,17 @@
+/**
+ * The public RSA key used to encrypt the private key when importing an EVM account.
+ */
+export const ImportEvmAccountPublicRSAKey = `-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA2Fxydgm/ryYk0IexQIuL
+9DKyiIk2WmS36AZ83a9Z0QX53qdveg08b05g1Qr+o+COoYOT/FDi8anRGAs7rIyS
+uigrjHR6VrmFjnGrrTr3MINwC9cYQFHwET8YVGRq+BB3iFTB1kIb9XJ/vT2sk1xP
+hJ6JihEwSl4DgbeVjqw59wYqrNg355oa8EdFqkmfGU2tpbM56F8iv1F+shwkGo3y
+GhW/UOQ5OLauXvsqo8ranwsK+lqFblLEMlNtn1VSJeO2vMxryeKFrY2ob8VqGchC
+ftPJiLWs2Du6juw4C1rOWwSMlXzZ6cNMHkxdTcEHMr3C2TEHgzjZY41whMwNTB8q
+/pxXnIbH77caaviRs4R/POe8cSsznalXj85LULvFWOIHp0w+jEYSii9Rp9XtHWAH
+nrK/O/SVDtT1ohp2F+Zg1mojTgKfLOyGdOUXTi95naDTuG770rSjHdL80tJBz1Fd
++1pzGTGXGHLZQLX5YZm5iuy2cebWfF09VjIoCIlDB2++tr4M+O0Z1X1ZE0J5Ackq
+rOluAFalaKynyH3KMyRg+NuLmibu5OmcMjCLK3D4X1YLiN2OK8/bbpEL8JYroDwb
+EXIUW5mGS06YxfSUsxHzL9Tj00+GMm/Gvl0+4/+Vn8IXVHjQOSPNEy3EnqCiH/OW
+8v0IMC32CeGrX7mGbU+MzlsCAwEAAQ==
+-----END PUBLIC KEY-----`;

package/client/evm/evm.ts

@@ -1,5 +1,8 @@
+import { publicEncrypt, constants } from "crypto";
+
 import { Address } from "viem";
 
+import { ImportEvmAccountPublicRSAKey } from "./constants.js";
 import {
   CreateServerAccountOptions,
   GetServerAccountOptions,
@@ -23,6 +26,7 @@ import {
   GetOrCreateServerAccountOptions,
   SignTypedDataOptions,
   UpdateEvmAccountOptions,
+  ImportServerAccountOptions,
 } from "./evm.types.js";
 import { toEvmServerAccount } from "../../accounts/evm/toEvmServerAccount.js";
 import { toEvmSmartAccount } from "../../accounts/evm/toEvmSmartAccount.js";
@@ -99,6 +103,7 @@ export class EvmClient implements EvmClientInterface {
     const openApiAccount = await CdpOpenApiClient.createEvmAccount(
       {
         name: options.name,
+        accountPolicy: options.accountPolicy,
       },
       options.idempotencyKey,
     );
@@ -112,6 +117,92 @@ export class EvmClient implements EvmClientInterface {
     return account;
   }
 
+  /**
+   * Imports a CDP EVM account from an external source.
+   *
+   * @param {ImportServerAccountOptions} options - Parameters for importing the account.
+   * @param {string} options.privateKey - The private key of the account to import.
+   * @param {string} [options.name] - A name for the account to import.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the imported account.
+   *
+   * @example **Without arguments**
+   *          ```ts
+   *          const account = await cdp.evm.importAccount({
+   *            privateKey: "0x123456"
+   *          });
+   *          ```
+   *
+   * @example **With a name**
+   *          ```ts
+   *          const account = await cdp.evm.importAccount({
+   *            privateKey: "0x123456",
+   *            name: "MyAccount"
+   *          });
+   *          ```
+   *
+   * @example **With an idempotency key**
+   *          ```ts
+   *          const idempotencyKey = uuidv4();
+   *
+   *          // First call
+   *          await cdp.evm.importAccount({
+   *            privateKey: "0x123456",
+   *            idempotencyKey,
+   *          });
+   *
+   *          // Second call with the same idempotency key will return the same account
+   *          await cdp.evm.importAccount({
+   *            privateKey: "0x123456"
+   *            idempotencyKey,
+   *          });
+   *          ```
+   */
+  async importAccount(options: ImportServerAccountOptions): Promise<ServerAccount> {
+    const privateKeyHex = options.privateKey.startsWith("0x")
+      ? options.privateKey.slice(2)
+      : options.privateKey;
+
+    if (!/^[0-9a-fA-F]+$/.test(privateKeyHex)) {
+      throw new Error("Private key must be a valid hexadecimal string");
+    }
+
+    try {
+      const privateKeyBytes = Buffer.from(privateKeyHex, "hex");
+
+      const encryptedPrivateKey = publicEncrypt(
+        {
+          key: ImportEvmAccountPublicRSAKey,
+          padding: constants.RSA_PKCS1_OAEP_PADDING,
+          oaepHash: "sha256",
+        },
+        privateKeyBytes,
+      );
+
+      const openApiAccount = await CdpOpenApiClient.importEvmAccount(
+        {
+          name: options.name,
+          encryptedPrivateKey: encryptedPrivateKey.toString("base64"),
+        },
+        options.idempotencyKey,
+      );
+
+      const account = toEvmServerAccount(CdpOpenApiClient, {
+        account: openApiAccount,
+      });
+
+      Analytics.wrapObjectMethodsWithErrorTracking(account);
+
+      return account;
+    } catch (error) {
+      if (error instanceof APIError) {
+        throw error;
+      }
+      throw new Error(`Failed to import account: ${String(error)}`);
+    }
+  }
+
   /**
    * Creates a new CDP EVM smart account.
    *