@coinbase/cdp-sdk 1.1.2 → 1.2.0

package/client/evm/evm.types.ts

@@ -0,0 +1,303 @@
+import { SendUserOperationReturnType } from "../../actions/evm/sendUserOperation.js";
+import { Call, Calls } from "../../types/calls.js";
+import { Address, Hex } from "../../types/misc.js";
+import { WaitOptions } from "../../utils/wait.js";
+
+import type {
+  EvmAccount as Account,
+  EvmServerAccount as ServerAccount,
+  EvmSmartAccount as SmartAccount,
+} from "../../accounts/types.js";
+import type {
+  EvmUserOperationNetwork,
+  EvmUserOperationStatus,
+  OpenApiEvmMethods,
+} from "../../openapi-client/index.js";
+
+/**
+ * The EvmClient type, where all OpenApiEvmMethods methods are wrapped.
+ */
+export type EvmClientInterface = Omit<
+  typeof OpenApiEvmMethods,
+  | "createEvmAccount" // mapped to createAccount
+  | "createEvmSmartAccount" // mapped to createSmartAccount
+  | "getEvmAccount" // mapped to getAccount
+  | "getEvmAccountByName" // mapped to getAccount
+  | "getEvmSmartAccount" // mapped to getSmartAccount
+  | "getUserOperation"
+  | "listEVMBalances" // omit
+  | "listEvmAccounts" // mapped to listAccounts
+  | "listEvmSmartAccounts" // mapped to listSmartAccounts
+  | "prepareUserOperation"
+  | "requestEvmFaucet" // mapped to requestFaucet
+  | "sendUserOperation"
+  | "signEvmHash" // mapped to signHash
+  | "signEvmMessage" // mapped to signMessage
+  | "signEvmTransaction" // mapped to signTransaction
+> & {
+  createAccount: (options: CreateServerAccountOptions) => Promise<ServerAccount>;
+  createSmartAccount: (options: CreateSmartAccountOptions) => Promise<SmartAccount>;
+  getAccount: (options: GetServerAccountOptions) => Promise<ServerAccount>;
+  getSmartAccount: (options: GetSmartAccountOptions) => Promise<SmartAccount>;
+  getUserOperation: (options: GetUserOperationOptions) => Promise<UserOperation>;
+  listAccounts: (options: ListServerAccountsOptions) => Promise<ListServerAccountResult>;
+  listSmartAccounts: (options: ListSmartAccountsOptions) => Promise<ListSmartAccountResult>;
+  prepareUserOperation: (options: PrepareUserOperationOptions) => Promise<UserOperation>;
+  requestFaucet: (options: RequestFaucetOptions) => Promise<RequestFaucetResult>;
+  sendUserOperation: (options: SendUserOperationOptions) => Promise<SendUserOperationReturnType>;
+  signHash: (options: SignHashOptions) => Promise<SignatureResult>;
+  signMessage: (options: SignMessageOptions) => Promise<SignatureResult>;
+  signTransaction: (options: SignTransactionOptions) => Promise<SignatureResult>;
+};
+
+export type { ServerAccount, SmartAccount };
+
+/**
+ * Options for getting a user operation.
+ */
+export interface GetUserOperationOptions {
+  /** The smart account. */
+  smartAccount: SmartAccount;
+  /** The user operation hash. */
+  userOpHash: Hex;
+}
+
+/**
+ * Options for preparing a user operation.
+ */
+export interface PrepareUserOperationOptions {
+  /** The smart account. */
+  smartAccount: SmartAccount;
+  /** The network. */
+  network: EvmUserOperationNetwork;
+  /** The calls. */
+  calls: Calls<EvmCall[]>;
+  /** The paymaster URL. */
+  paymasterUrl?: string;
+}
+
+/**
+ * A call to be executed in a user operation.
+ */
+export interface EvmCall {
+  /**
+   * The address the call is directed to.
+   */
+  to: Address;
+  /** The amount of ETH to send with the call, in wei. */
+  value: bigint;
+  /**
+   * The call data to send. This is the hex-encoded data of the function call consisting of the method selector and the function arguments.
+   */
+  data: Hex;
+}
+
+/**
+ * A user operation.
+ */
+export interface UserOperation {
+  /** The network the user operation is for. */
+  network: EvmUserOperationNetwork;
+  /**
+   * The hash of the user operation. This is not the transaction hash, as a transaction consists of multiple user operations. The user operation hash is the hash of this particular user operation which gets signed by the owner of the Smart Account.
+   */
+  userOpHash: Hex;
+  /** The list of calls in the user operation. */
+  calls: Calls<EvmCall[]>;
+  /** The status of the user operation. */
+  status: EvmUserOperationStatus;
+  /**
+   * The hash of the transaction that included this particular user operation. This gets set after the user operation is broadcasted and the transaction is included in a block.
+   */
+  transactionHash?: Hex;
+}
+
+/**
+ * Options for creating an EVM server account.
+ */
+export interface CreateServerAccountOptions {
+  /** The name of the account. */
+  name?: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for getting an EVM account.
+ */
+export interface GetServerAccountOptions {
+  /** The address of the account. */
+  address?: Address;
+  /** The name of the account. */
+  name?: string;
+}
+
+/**
+ * Options for getting an EVM smart account.
+ */
+export interface GetSmartAccountOptions {
+  /** The address of the account. */
+  address: Address;
+  /** The owner of the account. */
+  owner: Account;
+}
+
+/**
+ * Options for listing EVM accounts.
+ */
+export interface ListServerAccountsOptions {
+  /** The page size to paginate through the accounts. */
+  pageSize?: number;
+  /** The page token to paginate through the accounts. */
+  pageToken?: string;
+}
+
+/**
+ * A smart account that only contains the owner address.
+ */
+export interface ReadonlySmartAccount extends Omit<SmartAccount, "owners"> {
+  /** The owners of the smart account. */
+  owners: Address[];
+}
+
+/**
+ * The result of listing EVM smart accounts.
+ */
+export interface ListSmartAccountResult {
+  /** The accounts. */
+  accounts: ReadonlySmartAccount[];
+  /**
+   * The next page token to paginate through the accounts.
+   * If undefined, there are no more accounts to paginate through.
+   */
+  nextPageToken?: string;
+}
+
+/**
+ * The result of listing EVM server accounts.
+ */
+export interface ListServerAccountResult {
+  /** The accounts. */
+  accounts: ServerAccount[];
+  /**
+   * The next page token to paginate through the accounts.
+   * If undefined, there are no more accounts to paginate through.
+   */
+  nextPageToken?: string;
+}
+
+/**
+ * Options for listing EVM smart accounts.
+ */
+export interface ListSmartAccountsOptions {
+  /** The name of the account. */
+  name?: string;
+  /** The page size to paginate through the accounts. */
+  pageSize?: number;
+  /** The page token to paginate through the accounts. */
+  pageToken?: string;
+}
+
+/**
+ * Options for creating an EVM smart account.
+ */
+export interface CreateSmartAccountOptions {
+  /** The owner of the account. */
+  owner: Account;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for requesting funds from an EVM faucet.
+ */
+export interface RequestFaucetOptions {
+  /** The address of the account. */
+  address: string;
+  /** The network to request funds from. */
+  network: "base-sepolia" | "ethereum-sepolia";
+  /** The token to request funds for. */
+  token: "eth" | "usdc" | "eurc" | "cbbtc";
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * The result of requesting funds from an EVM faucet.
+ */
+export interface RequestFaucetResult {
+  /** The transaction hash. */
+  transactionHash: Hex;
+}
+
+/**
+ * Options for sending a user operation.
+ */
+export interface SendUserOperationOptions {
+  /** The smart account. */
+  smartAccount: SmartAccount;
+  /** The network. */
+  network: EvmUserOperationNetwork;
+  /** The calls. */
+  calls: Call[];
+  /** The paymaster URL. */
+  paymasterUrl?: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing an EVM hash.
+ */
+export interface SignHashOptions {
+  /** The address of the account. */
+  address: Address;
+  /** The hash to sign. */
+  hash: Hex;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing an EVM message.
+ */
+export interface SignMessageOptions {
+  /** The address of the account. */
+  address: Address;
+  /** The message to sign. */
+  message: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing an EVM transaction.
+ */
+export interface SignTransactionOptions {
+  /** The address of the account. */
+  address: Address;
+  /** The RLP-encoded transaction to sign, as a 0x-prefixed hex string. */
+  transaction: Hex;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * A signature result.
+ */
+export interface SignatureResult {
+  /** The signature. */
+  signature: Hex;
+}
+
+/**
+ * Options for waiting for a user operation.
+ */
+export interface WaitForUserOperationOptions {
+  /** The smart account address. */
+  smartAccountAddress: Address;
+  /** The user operation hash. */
+  userOpHash: Hex;
+  /** The wait options. */
+  waitOptions?: WaitOptions;
+}

package/client/solana/index.ts

@@ -0,0 +1 @@
+export { SolanaClient } from "./solana.js";

package/client/solana/solana.ts

@@ -0,0 +1,237 @@
+import {
+  SolanaClientInterface,
+  Account,
+  CreateAccountOptions,
+  GetAccountOptions,
+  ListAccountsOptions,
+  RequestFaucetOptions,
+  ListAccountsResult,
+  SignatureResult,
+  SignMessageOptions,
+  SignTransactionOptions,
+} from "./solana.types.js";
+import { CdpOpenApiClient } from "../../openapi-client/index.js";
+
+/**
+ * The namespace containing all Solana methods.
+ */
+export class SolanaClient implements SolanaClientInterface {
+  /**
+   * Creates a new Solana account.
+   *
+   * @param {CreateAccountOptions} options - Parameters for creating the Solana account.
+   * @param {string} [options.name] - The name of the account.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the newly created account.
+   *
+   * @example **Without arguments**
+   *          ```ts
+   *          const account = await cdp.solana.createAccount();
+   *          ```
+   *
+   * @example **With a name**
+   *          ```ts
+   *          const account = await cdp.solana.createAccount({ name: "MyAccount" });
+   *          ```
+   *
+   * @example **With an idempotency key**
+   *          ```ts
+   *          const idempotencyKey = uuidv4();
+   *
+   *          // First call
+   *          await cdp.solana.createAccount({ idempotencyKey });
+   *
+   *          // Second call with the same idempotency key will return the same account
+   *          await cdp.solana.createAccount({ idempotencyKey });
+   *          ```
+   */
+  async createAccount(options: CreateAccountOptions = {}): Promise<Account> {
+    return CdpOpenApiClient.createSolanaAccount(options, options.idempotencyKey);
+  }
+
+  /**
+   * Gets a Solana account by its address.
+   *
+   * @param {GetAccountOptions} options - Parameters for getting the Solana account.
+   * Either `address` or `name` must be provided.
+   * If both are provided, lookup will be done by `address` and `name` will be ignored.
+   * @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 account.
+   *
+   * @example **Get an account by address**
+   *          ```ts
+   *          const account = await cdp.solana.getAccount({
+   *            address: "1234567890123456789012345678901234567890",
+   *          });
+   *          ```
+   *
+   * @example **Get an account by name**
+   *          ```ts
+   *          const account = await cdp.solana.getAccount({
+   *            name: "MyAccount",
+   *          });
+   *          ```
+   */
+  async getAccount(options: GetAccountOptions): Promise<Account> {
+    if (options.address) {
+      return CdpOpenApiClient.getSolanaAccount(options.address);
+    }
+
+    if (options.name) {
+      return CdpOpenApiClient.getSolanaAccountByName(options.name);
+    }
+
+    throw new Error("Either address or name must be provided");
+  }
+
+  /**
+   * Lists all Solana accounts.
+   *
+   * @param {ListAccountsOptions} options - Parameters for listing the Solana accounts.
+   * @param {number} [options.pageSize] - The number of accounts to return.
+   * @param {string} [options.pageToken] - The page token to begin listing from.
+   * This is obtained by previous calls to this method.
+   *
+   * @returns A promise that resolves to an array of Solana account instances.
+   *
+   * @example **Without arguments**
+   *          ```ts
+   *          const accounts = await cdp.solana.listAccounts();
+   *          ```
+   *
+   * @example **With pagination**
+   *          ```ts
+   *          let page = await cdp.solana.listAccounts();
+   *
+   *          while (page.nextPageToken) {
+   *            page = await cdp.solana.listAccounts({ pageToken: page.nextPageToken });
+   *          }
+   *
+   *          page.accounts.forEach(account => console.log(account));
+   *          ```
+   * }
+   * ```
+   */
+  async listAccounts(options: ListAccountsOptions = {}): Promise<ListAccountsResult> {
+    const solAccounts = await CdpOpenApiClient.listSolanaAccounts({
+      pageSize: options.pageSize,
+      pageToken: options.pageToken,
+    });
+
+    return {
+      accounts: solAccounts.accounts,
+      nextPageToken: solAccounts.nextPageToken,
+    };
+  }
+
+  /**
+   * Requests funds from a Solana faucet.
+   *
+   * @param {RequestFaucetOptions} options - Parameters for requesting funds from the Solana faucet.
+   * @param {string} options.address - The address to request funds for.
+   * @param {string} options.token - The token to request funds for.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the transaction signature.
+   *
+   * @example
+   *          ```ts
+   *          const signature = await cdp.solana.requestFaucet({
+   *            address: "1234567890123456789012345678901234567890",
+   *            token: "sol",
+   *          });
+   *          ```
+   */
+  async requestFaucet(options: RequestFaucetOptions): Promise<SignatureResult> {
+    const signature = await CdpOpenApiClient.requestSolanaFaucet(
+      { address: options.address, token: options.token },
+      options.idempotencyKey,
+    );
+
+    return {
+      signature: signature.transactionSignature,
+    };
+  }
+
+  /**
+   * Signs a message.
+   *
+   * @param {SignMessageOptions} options - Parameters for signing the message.
+   * @param {string} options.address - The address to sign the message for.
+   * @param {string} options.message - The message to sign.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the signature.
+   *
+   * @example
+   * ```ts
+   * // Create a Solana account
+   * const account = await cdp.solana.createAccount();
+   *
+   * // When you want to sign a message, you can do so by address
+   * const signature = await cdp.solana.signMessage({
+   *   address: account.address,
+   *   message: "Hello, world!",
+   * });
+   * ```
+   */
+  async signMessage(options: SignMessageOptions): Promise<SignatureResult> {
+    return CdpOpenApiClient.signSolanaMessage(
+      options.address,
+      {
+        message: options.message,
+      },
+      options.idempotencyKey,
+    );
+  }
+
+  /**
+   * Signs a transaction.
+   *
+   * @param {SignTransactionOptions} options - Parameters for signing the transaction.
+   * @param {string} options.address - The address to sign the transaction for.
+   * @param {string} options.transaction - The transaction to sign.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the signature.
+   *
+   * @example
+   * ```ts
+   * // Create a Solana account
+   * const account = await cdp.solana.createAccount();
+   *
+   * // Add your transaction instructions here
+   * const transaction = new Transaction()
+   *
+   * // Make sure to set requireAllSignatures to false, since signing will be done through the API
+   * const serializedTransaction = transaction.serialize({
+   *   requireAllSignatures: false,
+   * });
+   *
+   * // Base64 encode the serialized transaction
+   * const transaction = Buffer.from(serializedTransaction).toString("base64");
+   *
+   * // When you want to sign a transaction, you can do so by address and base64 encoded transaction
+   * const signature = await cdp.solana.signTransaction({
+   *   address: account.address,
+   *   transaction,
+   * });
+   * ```
+   */
+  async signTransaction(options: SignTransactionOptions): Promise<SignatureResult> {
+    const signature = await CdpOpenApiClient.signSolanaTransaction(
+      options.address,
+      {
+        transaction: options.transaction,
+      },
+      options.idempotencyKey,
+    );
+
+    return {
+      signature: signature.signedTransaction,
+    };
+  }
+}

package/client/solana/solana.types.ts

@@ -0,0 +1,114 @@
+import {
+  OpenApiSolanaMethods,
+  SolanaAccount as OpenAPISolanaAccount,
+} from "../../openapi-client/index.js";
+/**
+ * The SolanaClient type, where all OpenApiSolanaMethods methods are wrapped.
+ */
+export type SolanaClientInterface = Omit<
+  typeof OpenApiSolanaMethods,
+  | "createSolanaAccount" // mapped to createAccount
+  | "getSolanaAccount" // mapped to getAccount
+  | "getSolanaAccountByName" // mapped to getAccount
+  | "listSolanaAccounts" // mapped to listAccounts
+  | "requestSolanaFaucet" // mapped to requestFaucet
+  | "signSolanaMessage" // mapped to signMessage
+  | "signSolanaTransaction" // mapped to signTransaction
+> & {
+  createAccount: (options: CreateAccountOptions) => Promise<Account>;
+  getAccount: (options: GetAccountOptions) => Promise<Account>;
+  listAccounts: (options: ListAccountsOptions) => Promise<ListAccountsResult>;
+  requestFaucet: (options: RequestFaucetOptions) => Promise<SignatureResult>;
+  signMessage: (options: SignMessageOptions) => Promise<SignatureResult>;
+  signTransaction: (options: SignTransactionOptions) => Promise<SignatureResult>;
+};
+/**
+ * A Solana account.
+ */
+export type Account = OpenAPISolanaAccount;
+
+/**
+ * Options for creating a Solana account.
+ */
+export interface CreateAccountOptions {
+  /** The name of the account. */
+  name?: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for getting a Solana account.
+ */
+export interface GetAccountOptions {
+  /** The address of the account. */
+  address?: string;
+  /** The name of the account. */
+  name?: string;
+}
+
+/**
+ * Options for listing Solana accounts.
+ */
+export interface ListAccountsOptions {
+  /** The page size. */
+  pageSize?: number;
+  /** The page token. */
+  pageToken?: string;
+}
+
+/**
+ * The result of listing Solana accounts.
+ */
+export interface ListAccountsResult {
+  /** The accounts. */
+  accounts: Account[];
+  /**
+   * The token for the next page of accounts, if any.
+   */
+  nextPageToken?: string;
+}
+
+/**
+ * Options for requesting funds from a Solana faucet.
+ */
+export interface RequestFaucetOptions {
+  /** The address of the account. */
+  address: string;
+  /** The token to request funds for. */
+  token: "sol" | "usdc";
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing a Solana message.
+ */
+export interface SignMessageOptions {
+  /** The address of the account. */
+  address: string;
+  /** The message to sign. */
+  message: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing a Solana transaction.
+ */
+export interface SignTransactionOptions {
+  /** The address of the account. */
+  address: string;
+  /** The base64 encoded transaction to sign. */
+  transaction: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * A Solana signature result.
+ */
+export interface SignatureResult {
+  /** The signature. */
+  signature: string;
+}

package/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * The URL to the Coinbase CDP API error docs page.
+ */
+export const ERROR_DOCS_PAGE_URL = "https://docs.cdp.coinbase.com/api-v2/docs/errors";

package/errors.ts

@@ -0,0 +1,17 @@
+/**
+ * TimeoutError is thrown when an operation times out.
+ */
+export class TimeoutError extends Error {
+  /**
+   * Initializes a new TimeoutError instance.
+   *
+   * @param message - The error message.
+   */
+  constructor(message: string = "Timeout Error") {
+    super(message);
+    this.name = "TimeoutError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TimeoutError);
+    }
+  }
+}

package/index.ts

@@ -0,0 +1,4 @@
+import "./analytics.js";
+
+export { CdpClient } from "./client/cdp.js";
+export type { EvmServerAccount, EvmSmartAccount } from "./accounts/types.js";