@coinbase/cdp-sdk 1.14.0 → 1.16.0

package/client/evm/evm.ts

@@ -1,51 +1,52 @@
-import { publicEncrypt, constants } from "crypto";
+import { constants, publicEncrypt } from "crypto";
 
-import { Address } from "viem";
+import { type Address, getTypesForEIP712Domain } from "viem";
 
 import { ImportEvmAccountPublicRSAKey } from "./constants.js";
 import {
   CreateServerAccountOptions,
-  GetServerAccountOptions,
-  ListServerAccountsOptions,
   CreateSmartAccountOptions,
-  WaitForUserOperationOptions,
-  SignHashOptions,
-  SignatureResult,
-  SignMessageOptions,
-  SignTransactionOptions,
-  GetSmartAccountOptions,
-  SmartAccount,
-  ServerAccount,
+  CreateSwapQuoteOptions,
+  CreateSwapQuoteResult,
   EvmClientInterface,
-  ListServerAccountResult,
-  PrepareUserOperationOptions,
-  UserOperation,
+  ExportServerAccountOptions,
+  GetOrCreateServerAccountOptions,
+  GetOrCreateSmartAccountOptions,
+  GetServerAccountOptions,
+  GetSmartAccountOptions,
+  GetSwapPriceOptions,
+  GetSwapPriceResult,
   GetUserOperationOptions,
+  ImportServerAccountOptions,
+  ListServerAccountResult,
+  ListServerAccountsOptions,
   ListSmartAccountResult,
   ListSmartAccountsOptions,
-  GetOrCreateServerAccountOptions,
+  PrepareUserOperationOptions,
+  ServerAccount,
+  SignatureResult,
+  SignHashOptions,
+  SignMessageOptions,
+  SignTransactionOptions,
   SignTypedDataOptions,
-  UpdateEvmAccountOptions,
-  ImportServerAccountOptions,
-  GetSwapPriceOptions,
-  CreateSwapQuoteOptions,
-  GetSwapPriceResult,
-  CreateSwapQuoteResult,
+  SmartAccount,
   SwapUnavailableResult,
-  GetOrCreateSmartAccountOptions,
+  UpdateEvmAccountOptions,
+  UserOperation,
+  WaitForUserOperationOptions,
 } from "./evm.types.js";
 import { toEvmServerAccount } from "../../accounts/evm/toEvmServerAccount.js";
 import { toEvmSmartAccount } from "../../accounts/evm/toEvmSmartAccount.js";
 import { getUserOperation } from "../../actions/evm/getUserOperation.js";
 import {
   listTokenBalances,
-  ListTokenBalancesResult,
   ListTokenBalancesOptions,
+  ListTokenBalancesResult,
 } from "../../actions/evm/listTokenBalances.js";
 import {
+  requestFaucet,
   RequestFaucetOptions,
   RequestFaucetResult,
-  requestFaucet,
 } from "../../actions/evm/requestFaucet.js";
 import { sendTransaction } from "../../actions/evm/sendTransaction.js";
 import {
@@ -61,12 +62,16 @@ import {
 } from "../../actions/evm/waitForUserOperation.js";
 import { Analytics } from "../../analytics.js";
 import { APIError } from "../../openapi-client/errors.js";
-import { CdpOpenApiClient } from "../../openapi-client/index.js";
+import {
+  CdpOpenApiClient,
+  EIP712Message as OpenAPIEIP712Message,
+} from "../../openapi-client/index.js";
 import { Hex } from "../../types/misc.js";
+import { decryptWithPrivateKey, generateExportEncryptionKeyPair } from "../../utils/export.js";
 
 import type {
-  TransactionResult,
   SendTransactionOptions,
+  TransactionResult,
 } from "../../actions/evm/sendTransaction.js";
 
 /**
@@ -213,6 +218,61 @@ export class EvmClient implements EvmClientInterface {
     }
   }
 
+  /**
+   * Exports a CDP EVM account's private key.
+   * It is important to store the private key in a secure place after it's exported.
+   *
+   * @param {ExportServerAccountOptions} options - Parameters for exporting the account.
+   * @param {string} [options.address] - The address of the account to export.
+   * @param {string} [options.name] - The name of the account to export.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the exported account’s 32-byte private key as a hex string, without the "0x" prefix.
+   *
+   * @example **With an address**
+   * ```ts
+   * const privateKey = await cdp.evm.exportAccount({
+   *   address: "0x1234567890123456789012345678901234567890",
+   * });
+   * ```
+   *
+   * @example **With a name**
+   * ```ts
+   * const privateKey = await cdp.evm.exportAccount({
+   *   name: "MyAccount",
+   * });
+   * ```
+   */
+  async exportAccount(options: ExportServerAccountOptions): Promise<string> {
+    const { publicKey, privateKey } = await generateExportEncryptionKeyPair();
+
+    const { encryptedPrivateKey } = await (async () => {
+      if (options.address) {
+        return CdpOpenApiClient.exportEvmAccount(
+          options.address,
+          {
+            exportEncryptionKey: publicKey,
+          },
+          options.idempotencyKey,
+        );
+      }
+
+      if (options.name) {
+        return CdpOpenApiClient.exportEvmAccountByName(
+          options.name,
+          {
+            exportEncryptionKey: publicKey,
+          },
+          options.idempotencyKey,
+        );
+      }
+
+      throw new Error("Either address or name must be provided");
+    })();
+
+    return decryptWithPrivateKey(privateKey, encryptedPrivateKey);
+  }
+
   /**
    * Creates a new CDP EVM smart account.
    *
@@ -921,14 +981,22 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async signTypedData(options: SignTypedDataOptions): Promise<SignatureResult> {
+    const { domain, message, primaryType } = options;
+    const types = {
+      EIP712Domain: getTypesForEIP712Domain({ domain }),
+      ...options.types,
+    };
+
+    const openApiMessage: OpenAPIEIP712Message = {
+      domain,
+      types,
+      primaryType,
+      message,
+    };
+
     const signature = await CdpOpenApiClient.signEvmTypedData(
       options.address,
-      {
-        domain: options.domain,
-        types: options.types,
-        primaryType: options.primaryType,
-        message: options.message,
-      },
+      openApiMessage,
       options.idempotencyKey,
     );
 

package/client/evm/evm.types.ts

@@ -36,6 +36,8 @@ export type EvmClientInterface = Omit<
   | "createEvmAccount" // mapped to createAccount
   | "createEvmSmartAccount" // mapped to createSmartAccount
   | "importEvmAccount" // mapped to importAccount
+  | "exportEvmAccount" // mapped to exportAccount
+  | "exportEvmAccountByName" // mapped to exportAccount
   | "getEvmAccount" // mapped to getAccount
   | "getEvmAccountByName" // mapped to getAccount
   | "getEvmSmartAccount" // mapped to getSmartAccount
@@ -63,6 +65,7 @@ export type EvmClientInterface = Omit<
   createAccount: (options: CreateServerAccountOptions) => Promise<ServerAccount>;
   createSmartAccount: (options: CreateSmartAccountOptions) => Promise<SmartAccount>;
   importAccount: (options: ImportServerAccountOptions) => Promise<ServerAccount>;
+  exportAccount: (options: ExportServerAccountOptions) => Promise<string>;
   getAccount: (options: GetServerAccountOptions) => Promise<ServerAccount>;
   getSmartAccount: (options: GetSmartAccountOptions) => Promise<SmartAccount>;
   getSwapPrice: (
@@ -103,14 +106,18 @@ export interface CreateSwapQuoteOptions {
   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). */
+  /** The address receiving the output of the swap. */
+  taker: Address;
+  /** The address signing the swap (only needed if taker is a smart contract, i.e. for smart account swaps). */
   signerAddress?: Address;
-  /** The gas price in Wei. */
+  /** The smart account object (required for smart account execution context only). */
+  smartAccount?: SmartAccount;
+  /** The price per unit of gas in wei. */
   gasPrice?: bigint;
   /** The slippage tolerance in basis points (0-10000). */
   slippageBps?: number;
+  /** The idempotency key. */
+  idempotencyKey?: string;
 }
 
 /**
@@ -133,6 +140,8 @@ export interface GetSwapPriceOptions {
   gasPrice?: bigint;
   /** The slippage tolerance in basis points (0-10000). */
   slippageBps?: number;
+  /** The idempotency key. */
+  idempotencyKey?: string;
 }
 
 /**
@@ -183,8 +192,14 @@ export interface ExecuteSwapQuoteOptions {
  * Result of executing a swap quote.
  */
 export interface ExecuteSwapQuoteResult {
-  /** The transaction hash of the executed swap. */
-  transactionHash: Hex;
+  /** The transaction hash of the executed swap (for EOA swaps). */
+  transactionHash?: Hex;
+  /** The user operation hash of the executed swap (for smart account swaps). */
+  userOpHash?: Hex;
+  /** The address of the smart account (for smart account swaps). */
+  smartAccountAddress?: Address;
+  /** The status of the user operation (for smart accounts swaps). */
+  status?: typeof EvmUserOperationStatus.broadcast;
 }
 
 /**
@@ -324,6 +339,18 @@ export interface ImportServerAccountOptions {
   privateKey: Hex;
 }
 
+/**
+ * Options for exporting an EVM server account.
+ */
+export interface ExportServerAccountOptions {
+  /** The address of the account. */
+  address?: Address;
+  /** The name of the account. */
+  name?: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
 /**
  * Options for getting an EVM account.
  */
@@ -584,3 +611,18 @@ export type GetSwapQuoteOptions = GetSwapPriceOptions;
 export type GetSwapQuoteResult = GetSwapPriceResult;
 export type SwapQuoteUnavailableResult = SwapUnavailableResult;
 export type SwapPriceUnavailableResult = SwapUnavailableResult;
+
+/**
+ * Options for signing and wrapping EIP-712 typed data with a smart account.
+ * This method handles the full smart account signature flow including replay-safe hashing.
+ */
+export interface SmartAccountSignAndWrapTypedDataOptions {
+  /** The chain ID for the signature (used for replay protection). */
+  chainId: bigint;
+  /** The EIP-712 typed data message to sign. */
+  typedData: EIP712Message;
+  /** The index of the owner to sign with (defaults to 0). */
+  ownerIndex?: bigint;
+  /** Optional idempotency key for the signing request. */
+  idempotencyKey?: string;
+}

package/client/solana/solana.ts

@@ -1,5 +1,6 @@
 import {
   CreateAccountOptions,
+  ExportAccountOptions,
   GetAccountOptions,
   GetOrCreateAccountOptions,
   ListAccountsOptions,
@@ -19,6 +20,11 @@ import { signTransaction } from "../../actions/solana/signTransaction.js";
 import { Analytics } from "../../analytics.js";
 import { APIError } from "../../openapi-client/errors.js";
 import { CdpOpenApiClient } from "../../openapi-client/index.js";
+import {
+  decryptWithPrivateKey,
+  formatSolanaPrivateKey,
+  generateExportEncryptionKeyPair,
+} from "../../utils/export.js";
 
 /**
  * The namespace containing all Solana methods.
@@ -72,6 +78,61 @@ export class SolanaClient implements SolanaClientInterface {
     return account;
   }
 
+  /**
+   * Exports a CDP Solana account's private key.
+   * It is important to store the private key in a secure place after it's exported.
+   *
+   * @param {ExportAccountOptions} options - Parameters for exporting the Solana account.
+   * @param {string} [options.address] - The address of the account.
+   * @param {string} [options.name] - The name of the account.
+   *
+   * @returns A promise that resolves to the exported account's full 64-byte private key as a base58 encoded string.
+   *
+   * @example **With an address**
+   * ```ts
+   * const privateKey = await cdp.solana.exportAccount({
+   *   address: "1234567890123456789012345678901234567890",
+   * });
+   * ```
+   *
+   * @example **With a name**
+   * ```ts
+   * const privateKey = await cdp.solana.exportAccount({
+   *   name: "MyAccount",
+   * });
+   * ```
+   */
+  async exportAccount(options: ExportAccountOptions): Promise<string> {
+    const { publicKey, privateKey } = await generateExportEncryptionKeyPair();
+
+    const { encryptedPrivateKey } = await (async () => {
+      if (options.address) {
+        return CdpOpenApiClient.exportSolanaAccount(
+          options.address,
+          {
+            exportEncryptionKey: publicKey,
+          },
+          options.idempotencyKey,
+        );
+      }
+
+      if (options.name) {
+        return CdpOpenApiClient.exportSolanaAccountByName(
+          options.name,
+          {
+            exportEncryptionKey: publicKey,
+          },
+          options.idempotencyKey,
+        );
+      }
+
+      throw new Error("Either address or name must be provided");
+    })();
+
+    const decryptedPrivateKey = decryptWithPrivateKey(privateKey, encryptedPrivateKey);
+    return formatSolanaPrivateKey(decryptedPrivateKey);
+  }
+
   /**
    * Gets a Solana account by its address.
    *

package/client/solana/solana.types.ts

@@ -15,10 +15,11 @@ export type SolanaClientInterface = Omit<
   | "signSolanaMessage" // mapped to signMessage
   | "signSolanaTransaction" // mapped to signTransaction
   | "updateSolanaAccount" // mapped to updateAccount
-  | "exportSolanaAccount"
-  | "exportSolanaAccountByName"
+  | "exportSolanaAccount" // mapped to exportAccount
+  | "exportSolanaAccountByName" // mapped to exportAccount
 > & {
   createAccount: (options: CreateAccountOptions) => Promise<Account>;
+  exportAccount: (options: ExportAccountOptions) => Promise<string>;
   getAccount: (options: GetAccountOptions) => Promise<Account>;
   getOrCreateAccount: (options: GetOrCreateAccountOptions) => Promise<Account>;
   updateAccount: (options: UpdateSolanaAccountOptions) => Promise<Account>;
@@ -48,6 +49,18 @@ export interface CreateAccountOptions {
   idempotencyKey?: string;
 }
 
+/**
+ * Options for exporting a Solana account.
+ */
+export interface ExportAccountOptions {
+  /** The address of the account. */
+  address?: string;
+  /** The name of the account. */
+  name?: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
 /**
  * Options for getting a Solana account.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cdp-sdk",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "SDK for interacting with the Coinbase Developer Platform Wallet API",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",

package/utils/export.ts

@@ -0,0 +1,89 @@
+import { generateKeyPair, privateDecrypt, constants, createPrivateKey } from "crypto";
+
+import { Keypair } from "@solana/web3.js";
+import bs58 from "bs58";
+
+/**
+ * Generates a new RSA key pair with 4096-bit private key.
+ * - Private key in PKCS1 DER format
+ * - Public key in PKIX/SPKI DER format
+ *
+ * @returns A promise that resolves to the generated key pair, or rejects with an error.
+ */
+export const generateExportEncryptionKeyPair = async () => {
+  return await new Promise<{
+    publicKey: string;
+    privateKey: string;
+  }>((resolve, reject) => {
+    generateKeyPair(
+      "rsa",
+      {
+        modulusLength: 4096,
+        publicKeyEncoding: {
+          type: "spki",
+          format: "der",
+        },
+        privateKeyEncoding: {
+          type: "pkcs1",
+          format: "der",
+        },
+      },
+      (err, publicKey, privateKey) => {
+        if (err) {
+          reject(err);
+        }
+        resolve({
+          publicKey: publicKey.toString("base64"),
+          privateKey: privateKey.toString("base64"),
+        });
+      },
+    );
+  });
+};
+
+/**
+ * Decrypts a ciphertext using RSA-OAEP-SHA256.
+ * - Parses PKCS1 private key
+ * - Uses RSA-OAEP-SHA256 for decryption
+ * - Returns hex-encoded result
+ *
+ * @param b64PrivateKey - The base64-encoded private key in PKCS1 DER format.
+ * @param b64Cipher - The base64-encoded ciphertext.
+ * @returns The decrypted key hex string, or throws an error if decryption fails.
+ */
+export const decryptWithPrivateKey = (b64PrivateKey: string, b64Cipher: string): string => {
+  try {
+    // Create a private key object from the PKCS1 DER format
+    const privateKey = createPrivateKey({
+      key: Buffer.from(b64PrivateKey, "base64"),
+      format: "der",
+      type: "pkcs1",
+    });
+
+    const decryptedBuffer = privateDecrypt(
+      {
+        key: privateKey,
+        padding: constants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: "sha256",
+      },
+      Buffer.from(b64Cipher, "base64"),
+    );
+
+    return decryptedBuffer.toString("hex");
+  } catch (error) {
+    throw new Error(`Decryption failed: ${String(error)}`);
+  }
+};
+
+/**
+ * Format a private key to a base58 string for easy import into Solana wallet apps.
+ *
+ * @param privateKey - The private key as a hex string
+ * @returns The formatted private key as a base58 string
+ */
+export const formatSolanaPrivateKey = (privateKey: string): string => {
+  const privateKeyBytes = Buffer.from(privateKey, "hex");
+  const keypair = Keypair.fromSeed(privateKeyBytes);
+  const fullKey = Buffer.concat([keypair.secretKey.subarray(0, 32), keypair.publicKey.toBytes()]);
+  return bs58.encode(fullKey);
+};

package/utils/uuidV4.ts

@@ -0,0 +1,23 @@
+import { createHash } from "crypto";
+
+/**
+ * Deterministically generates a UUIDv4 from a given input string.
+ * This is necessary when we need to generate downstream idempotency keys for operations that have multiple calls.
+ *
+ * @param input - The input string to derive from
+ * @param salt - Optional salt to append to the input (defaults to "salt")
+ * @returns A UUIDv4 formatted string
+ */
+export function createDeterministicUuidV4(input: string, salt = "salt"): string {
+  const hash = createHash("sha256")
+    .update(input + "-" + salt)
+    .digest("hex");
+  // Format as UUIDv4: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  return [
+    hash.slice(0, 8),
+    hash.slice(8, 12),
+    "4" + hash.slice(13, 16), // Version 4
+    ((parseInt(hash.slice(16, 17), 16) & 0x3) | 0x8).toString(16) + hash.slice(17, 20), // Variant bits
+    hash.slice(20, 32),
+  ].join("-");
+}

package/version.ts

@@ -1 +1 @@
-export const version = "1.14.0";
+export const version = "1.16.0";