@coinbase/cdp-sdk 1.25.0 → 1.27.0

package/client/solana/solana.ts

@@ -13,19 +13,23 @@ import {
   ListTokenBalancesOptions,
   ListTokenBalancesResult,
   RequestFaucetOptions,
+  SendTransactionOptions,
   SignatureResult,
   SignMessageOptions,
   SignTransactionOptions,
   SolanaClientInterface,
+  TransactionResult,
   UpdateSolanaAccountOptions,
 } from "./solana.types.js";
 import { toSolanaAccount } from "../../accounts/solana/toSolanaAccount.js";
 import { SolanaAccount } from "../../accounts/solana/types.js";
 import { requestFaucet } from "../../actions/solana/requestFaucet.js";
+import { sendTransaction } from "../../actions/solana/sendTransaction.js";
 import { signMessage } from "../../actions/solana/signMessage.js";
 import { signTransaction } from "../../actions/solana/signTransaction.js";
 import { Analytics } from "../../analytics.js";
 import { ImportAccountPublicRSAKey } from "../../constants.js";
+import { UserInputValidationError } from "../../errors.js";
 import { APIError } from "../../openapi-client/errors.js";
 import { CdpOpenApiClient } from "../../openapi-client/index.js";
 import {
@@ -69,6 +73,11 @@ export class SolanaClient implements SolanaClientInterface {
    *          ```
    */
   async createAccount(options: CreateAccountOptions = {}): Promise<SolanaAccount> {
+    Analytics.trackAction({
+      action: "create_account",
+      accountType: "solana",
+    });
+
     const openApiAccount = await CdpOpenApiClient.createSolanaAccount(
       {
         name: options.name,
@@ -111,6 +120,11 @@ export class SolanaClient implements SolanaClientInterface {
    * ```
    */
   async exportAccount(options: ExportAccountOptions): Promise<string> {
+    Analytics.trackAction({
+      action: "export_account",
+      accountType: "solana",
+    });
+
     const { publicKey, privateKey } = await generateExportEncryptionKeyPair();
 
     const { encryptedPrivateKey } = await (async () => {
@@ -134,7 +148,7 @@ export class SolanaClient implements SolanaClientInterface {
         );
       }
 
-      throw new Error("Either address or name must be provided");
+      throw new UserInputValidationError("Either address or name must be provided");
     })();
 
     const decryptedPrivateKey = decryptWithPrivateKey(privateKey, encryptedPrivateKey);
@@ -180,6 +194,11 @@ export class SolanaClient implements SolanaClientInterface {
    *          ```
    */
   async importAccount(options: ImportAccountOptions): Promise<SolanaAccount> {
+    Analytics.trackAction({
+      action: "import_account",
+      accountType: "solana",
+    });
+
     let privateKeyBytes: Uint8Array = new Uint8Array();
 
     if (typeof options.privateKey === "string") {
@@ -189,7 +208,7 @@ export class SolanaClient implements SolanaClientInterface {
     }
 
     if (privateKeyBytes.length !== 32 && privateKeyBytes.length !== 64) {
-      throw new Error("Invalid private key length");
+      throw new UserInputValidationError("Invalid private key length");
     }
 
     if (privateKeyBytes.length === 64) {
@@ -250,6 +269,11 @@ export class SolanaClient implements SolanaClientInterface {
    *          ```
    */
   async getAccount(options: GetAccountOptions): Promise<SolanaAccount> {
+    Analytics.trackAction({
+      action: "get_account",
+      accountType: "solana",
+    });
+
     const openApiAccount = await (() => {
       if (options.address) {
         return CdpOpenApiClient.getSolanaAccount(options.address);
@@ -259,7 +283,7 @@ export class SolanaClient implements SolanaClientInterface {
         return CdpOpenApiClient.getSolanaAccountByName(options.name);
       }
 
-      throw new Error("Either address or name must be provided");
+      throw new UserInputValidationError("Either address or name must be provided");
     })();
 
     const account = toSolanaAccount(CdpOpenApiClient, {
@@ -287,6 +311,11 @@ export class SolanaClient implements SolanaClientInterface {
    * ```
    */
   async getOrCreateAccount(options: GetOrCreateAccountOptions): Promise<SolanaAccount> {
+    Analytics.trackAction({
+      action: "get_or_create_account",
+      accountType: "solana",
+    });
+
     try {
       const account = await this.getAccount(options);
       return account;
@@ -341,6 +370,11 @@ export class SolanaClient implements SolanaClientInterface {
    * ```
    */
   async listAccounts(options: ListAccountsOptions = {}): Promise<ListAccountsResult> {
+    Analytics.trackAction({
+      action: "list_accounts",
+      accountType: "solana",
+    });
+
     const solAccounts = await CdpOpenApiClient.listSolanaAccounts({
       pageSize: options.pageSize,
       pageToken: options.pageToken,
@@ -379,6 +413,11 @@ export class SolanaClient implements SolanaClientInterface {
    *          ```
    */
   async requestFaucet(options: RequestFaucetOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "request_faucet",
+      accountType: "solana",
+    });
+
     return requestFaucet(CdpOpenApiClient, options);
   }
 
@@ -405,6 +444,11 @@ export class SolanaClient implements SolanaClientInterface {
    * ```
    */
   async signMessage(options: SignMessageOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "sign_message",
+      accountType: "solana",
+    });
+
     return signMessage(CdpOpenApiClient, options);
   }
 
@@ -442,6 +486,11 @@ export class SolanaClient implements SolanaClientInterface {
    * ```
    */
   async signTransaction(options: SignTransactionOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "sign_transaction",
+      accountType: "solana",
+    });
+
     return signTransaction(CdpOpenApiClient, options);
   }
 
@@ -487,6 +536,11 @@ export class SolanaClient implements SolanaClientInterface {
    *          ```
    */
   async updateAccount(options: UpdateSolanaAccountOptions): Promise<SolanaAccount> {
+    Analytics.trackAction({
+      action: "update_account",
+      accountType: "solana",
+    });
+
     const openApiAccount = await CdpOpenApiClient.updateSolanaAccount(
       options.address,
       options.update,
@@ -502,12 +556,42 @@ export class SolanaClient implements SolanaClientInterface {
     return account;
   }
 
+  /**
+   * Sends a Solana transaction using the Coinbase API.
+   *
+   * @param {SendTransactionOptions} options - Parameters for sending the Solana transaction.
+   * @param {string} options.network - The network to send the transaction to.
+   * @param {string} options.transaction - The base64 encoded transaction to send.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to the transaction result.
+   *
+   * @example
+   * ```ts
+   * const signature = await cdp.solana.sendTransaction({
+   *   network: "solana-devnet",
+   *   transaction: "...",
+   * });
+   * ```
+   */
+  async sendTransaction(options: SendTransactionOptions): Promise<TransactionResult> {
+    Analytics.trackAction({
+      action: "send_transaction",
+      accountType: "solana",
+      properties: {
+        network: options.network,
+      },
+    });
+
+    return sendTransaction(CdpOpenApiClient, options);
+  }
+
   /**
    * Lists the token balances for a Solana account.
    *
    * @param {ListTokenBalancesOptions} options - Parameters for listing the Solana token balances.
    * @param {string} options.address - The address of the account to list token balances for.
-   * @param {string} options.network - The network to list token balances for.
+   * @param {string} [options.network] - The network to list token balances for. Defaults to "solana".
    * @param {number} [options.pageSize] - The number of token balances to return.
    * @param {string} [options.pageToken] - The page token to begin listing from.
    * This is obtained by previous calls to this method.
@@ -520,8 +604,16 @@ export class SolanaClient implements SolanaClientInterface {
    * ```
    */
   async listTokenBalances(options: ListTokenBalancesOptions): Promise<ListTokenBalancesResult> {
+    Analytics.trackAction({
+      action: "list_token_balances",
+      accountType: "solana",
+      properties: {
+        network: options.network,
+      },
+    });
+
     const tokenBalances = await CdpOpenApiClient.listSolanaTokenBalances(
-      options.network,
+      options.network || "solana",
       options.address,
       {
         pageSize: options.pageSize,

package/client/solana/solana.types.ts

@@ -2,6 +2,8 @@ import { Account, SolanaAccount } from "../../accounts/solana/types.js";
 import {
   ListSolanaTokenBalancesNetwork,
   OpenApiSolanaMethods,
+  SendSolanaTransactionBody,
+  SendSolanaTransactionBodyNetwork,
   UpdateSolanaAccountBody,
 } from "../../openapi-client/index.js";
 
@@ -23,6 +25,7 @@ export type SolanaClientInterface = Omit<
   | "exportSolanaAccountByName" // mapped to exportAccount
   | "importSolanaAccount" // mapped to importAccount
   | "listSolanaTokenBalances" // mapped to listTokenBalances
+  | "sendSolanaTransaction" // mapped to sendTransaction
 > & {
   createAccount: (options: CreateAccountOptions) => Promise<Account>;
   exportAccount: (options: ExportAccountOptions) => Promise<string>;
@@ -35,6 +38,7 @@ export type SolanaClientInterface = Omit<
   signMessage: (options: SignMessageOptions) => Promise<SignatureResult>;
   signTransaction: (options: SignTransactionOptions) => Promise<SignatureResult>;
   listTokenBalances: (options: ListTokenBalancesOptions) => Promise<ListTokenBalancesResult>;
+  sendTransaction: (options: SendSolanaTransactionBody) => Promise<SignatureResult>;
 };
 
 /**
@@ -178,13 +182,33 @@ export interface ListTokenBalancesOptions {
   /** The address of the account. */
   address: string;
   /** The network to list token balances for. */
-  network: ListSolanaTokenBalancesNetwork;
+  network?: ListSolanaTokenBalancesNetwork;
   /** The page size. */
   pageSize?: number;
   /** The page token. */
   pageToken?: string;
 }
 
+/**
+ * Options for sending a Solana transaction.
+ */
+export interface SendTransactionOptions {
+  /** The network to send the transaction to. */
+  network: SendSolanaTransactionBodyNetwork;
+  /** The base64 encoded transaction to send. */
+  transaction: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * The result of sending a Solana transaction.
+ */
+export interface TransactionResult {
+  /** The signature of the transaction base58 encoded. */
+  signature: string;
+}
+
 export interface SolanaTokenAmount {
   /** The amount of the token. */
   amount: bigint;

package/constants.ts

@@ -1,7 +1,7 @@
 /**
  * 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";
+export const ERROR_DOCS_PAGE_URL = "https://docs.cdp.coinbase.com/api-reference/v2/errors";
 
 /**
  * The public RSA key used to encrypt the private key when importing an EVM or Solana account.

package/errors.ts

@@ -15,3 +15,21 @@ export class TimeoutError extends Error {
     }
   }
 }
+
+/**
+ * UserInputValidationError is thrown when validation of a user-supplied input fails.
+ */
+export class UserInputValidationError extends Error {
+  /**
+   * Initializes a new UserInputValidationError instance.
+   *
+   * @param message - The user input validation error message.
+   */
+  constructor(message: string) {
+    super(message);
+    this.name = "UserInputValidationError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, UserInputValidationError);
+    }
+  }
+}

package/index.ts

@@ -7,5 +7,6 @@ export {
   type CreatePolicyBody,
   type UpdatePolicyBody,
 } from "./policies/schema.js";
+export { NetworkError } from "./openapi-client/errors.js";
 
 export { parseEther } from "viem";

package/openapi-client/cdpApiClient.ts

@@ -3,13 +3,7 @@ import Axios, { AxiosInstance, AxiosRequestConfig } from "axios";
 
 import { withAuth } from "../auth/hooks/axios/index.js";
 import { ERROR_DOCS_PAGE_URL } from "../constants.js";
-import {
-  isOpenAPIError,
-  APIError,
-  HttpErrorType,
-  UnknownApiError,
-  UnknownError,
-} from "./errors.js";
+import { isOpenAPIError, APIError, UnknownError, NetworkError } from "./errors.js";
 
 import type { Prettify } from "../types/utils.js";
 
@@ -135,11 +129,52 @@ export const cdpApiClient = async <T>(
   } catch (error) {
     // eslint-disable-next-line import/no-named-as-default-member
     if (Axios.isAxiosError(error) && !error.response) {
-      throw new UnknownApiError(
-        HttpErrorType.unknown,
-        error.cause instanceof Error ? error.cause.message : error.message,
-        error.cause,
-      );
+      // Network-level errors (no response received)
+      const errorMessage = (error.message || "").toLowerCase();
+      const errorCode = error.code?.toLowerCase();
+
+      // Categorize network errors based on error messages and codes
+      if (errorCode === "econnrefused" || errorMessage.includes("connection refused")) {
+        throw new NetworkError(
+          "network_connection_failed",
+          "Unable to connect to CDP service. The service may be unavailable.",
+          { code: error.code, message: error.message, retryable: true },
+          error.cause,
+        );
+      } else if (
+        errorCode === "etimedout" ||
+        errorCode === "econnaborted" ||
+        errorMessage.includes("timeout")
+      ) {
+        throw new NetworkError(
+          "network_timeout",
+          "Request timed out. Please try again.",
+          { code: error.code, message: error.message, retryable: true },
+          error.cause,
+        );
+      } else if (errorCode === "enotfound" || errorMessage.includes("getaddrinfo")) {
+        throw new NetworkError(
+          "network_dns_failure",
+          "DNS resolution failed. Please check your network connection.",
+          { code: error.code, message: error.message, retryable: false },
+          error.cause,
+        );
+      } else if (errorMessage.includes("network error") || errorMessage.includes("econnreset")) {
+        throw new NetworkError(
+          "network_connection_failed",
+          "Network error occurred. Please check your connection and try again.",
+          { code: error.code, message: error.message, retryable: true },
+          error.cause,
+        );
+      } else {
+        // Generic network error
+        throw new NetworkError(
+          "unknown",
+          error.cause instanceof Error ? error.cause.message : error.message,
+          { code: error.code, message: error.message, retryable: true },
+          error.cause,
+        );
+      }
     }
 
     // eslint-disable-next-line import/no-named-as-default-member
@@ -155,20 +190,55 @@ export const cdpApiClient = async <T>(
         );
       } else {
         const statusCode = error.response.status;
+        const responseData = error.response.data;
+
+        // Check for gateway-level errors that might indicate network issues
+        const isGatewayError =
+          responseData &&
+          typeof responseData === "string" &&
+          (responseData.toLowerCase().includes("forbidden") ||
+            responseData.toLowerCase().includes("ip") ||
+            responseData.toLowerCase().includes("blocked") ||
+            responseData.toLowerCase().includes("gateway"));
+
         switch (statusCode) {
           case 401:
             throw new APIError(
               statusCode,
-              HttpErrorType.unauthorized,
+              "unauthorized",
               "Unauthorized.",
               undefined,
               `${ERROR_DOCS_PAGE_URL}#unauthorized`,
               error.cause,
             );
+          case 403:
+            // Special handling for IP blocklist and other gateway-level 403s
+            if (isGatewayError) {
+              throw new NetworkError(
+                "network_ip_blocked",
+                "Access denied. Your IP address may be blocked or restricted.",
+                {
+                  code: "IP_BLOCKED",
+                  message:
+                    typeof responseData === "string" ? responseData : JSON.stringify(responseData),
+                  retryable: false,
+                },
+                error.cause,
+              );
+            }
+            // Regular 403 forbidden error
+            throw new APIError(
+              statusCode,
+              "unauthorized",
+              "Forbidden. You don't have permission to access this resource.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}#forbidden`,
+              error.cause,
+            );
           case 404:
             throw new APIError(
               statusCode,
-              HttpErrorType.not_found,
+              "not_found",
               "API not found.",
               undefined,
               `${ERROR_DOCS_PAGE_URL}#not_found`,
@@ -177,7 +247,7 @@ export const cdpApiClient = async <T>(
           case 502:
             throw new APIError(
               statusCode,
-              HttpErrorType.bad_gateway,
+              "bad_gateway",
               "Bad gateway.",
               undefined,
               `${ERROR_DOCS_PAGE_URL}`,
@@ -186,7 +256,7 @@ export const cdpApiClient = async <T>(
           case 503:
             throw new APIError(
               statusCode,
-              HttpErrorType.service_unavailable,
+              "service_unavailable",
               "Service unavailable. Please try again later.",
               undefined,
               `${ERROR_DOCS_PAGE_URL}`,
@@ -209,7 +279,7 @@ export const cdpApiClient = async <T>(
 
             throw new APIError(
               statusCode,
-              HttpErrorType.unexpected_error,
+              "unexpected_error",
               errorMessage,
               undefined,
               `${ERROR_DOCS_PAGE_URL}`,

package/openapi-client/errors.ts

@@ -1,18 +1,20 @@
+import { ERROR_DOCS_PAGE_URL } from "../constants.js";
 import {
   Error as OpenAPIError,
   ErrorType as OpenAPIErrorType,
 } from "./generated/coinbaseDeveloperPlatformAPIs.schemas.js";
 
-export const HttpErrorType = {
-  unexpected_error: "unexpected_error",
-  unauthorized: "unauthorized",
-  not_found: "not_found",
-  bad_gateway: "bad_gateway",
-  service_unavailable: "service_unavailable",
-  unknown: "unknown",
-} as const;
-
-export type HttpErrorType = (typeof HttpErrorType)[keyof typeof HttpErrorType];
+export type HttpErrorType =
+  | "unexpected_error"
+  | "unauthorized"
+  | "not_found"
+  | "bad_gateway"
+  | "service_unavailable"
+  | "unknown"
+  | "network_timeout"
+  | "network_connection_failed"
+  | "network_ip_blocked"
+  | "network_dns_failure";
 
 /**
  * Extended error codes that include both OpenAPI errors and network errors
@@ -114,6 +116,59 @@ export class UnknownError extends Error {
   }
 }
 
+/**
+ * Error thrown when a network-level failure occurs before reaching the CDP service
+ * This includes gateway errors, IP blocklist rejections, DNS failures, etc.
+ */
+export class NetworkError extends APIError {
+  networkDetails?: {
+    code?: string;
+    message?: string;
+    retryable?: boolean;
+  };
+
+  /**
+   * Constructor for the NetworkError class
+   *
+   * @param errorType - The type of network error
+   * @param errorMessage - The error message
+   * @param networkDetails - Additional network error details
+   * @param networkDetails.code - The error code
+   * @param networkDetails.message - The error message
+   * @param networkDetails.retryable - Whether the error is retryable
+   * @param cause - The cause of the error
+   */
+  constructor(
+    errorType: HttpErrorType,
+    errorMessage: string,
+    networkDetails?: { code?: string; message?: string; retryable?: boolean },
+    cause?: Error,
+  ) {
+    super(
+      0, // Status code 0 indicates no response was received
+      errorType,
+      errorMessage,
+      undefined,
+      `${ERROR_DOCS_PAGE_URL}#network-errors`,
+      cause,
+    );
+    this.name = "NetworkError";
+    this.networkDetails = networkDetails;
+  }
+
+  /**
+   * Convert the error to a JSON object, including network details
+   *
+   * @returns The error as a JSON object
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      ...(this.networkDetails && { networkDetails: this.networkDetails }),
+    };
+  }
+}
+
 /**
  * Type guard to check if an object is an OpenAPIError
  *

package/openapi-client/generated/coinbaseDeveloperPlatformAPIs.schemas.ts

@@ -2252,6 +2252,30 @@ export type SignSolanaMessage200 = {
   signature: string;
 };
 
+/**
+ * The Solana network to send the transaction to.
+ */
+export type SendSolanaTransactionBodyNetwork =
+  (typeof SendSolanaTransactionBodyNetwork)[keyof typeof SendSolanaTransactionBodyNetwork];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const SendSolanaTransactionBodyNetwork = {
+  solana: "solana",
+  "solana-devnet": "solana-devnet",
+} as const;
+
+export type SendSolanaTransactionBody = {
+  /** The Solana network to send the transaction to. */
+  network: SendSolanaTransactionBodyNetwork;
+  /** The base64 encoded transaction to sign and send. This transaction can contain multiple instructions for native Solana batching. */
+  transaction: string;
+};
+
+export type SendSolanaTransaction200 = {
+  /** The base58 encoded transaction signature. */
+  transactionSignature: string;
+};
+
 /**
  * The token to request funds for.
  */

package/openapi-client/generated/solana-accounts/solana-accounts.msw.ts

@@ -13,6 +13,7 @@ import type {
   ExportSolanaAccount200,
   ExportSolanaAccountByName200,
   ListSolanaAccounts200,
+  SendSolanaTransaction200,
   SignSolanaMessage200,
   SignSolanaTransaction200,
   SolanaAccount,
@@ -203,6 +204,13 @@ export const getSignSolanaMessageResponseMock = (
   overrideResponse: Partial<SignSolanaMessage200> = {},
 ): SignSolanaMessage200 => ({ signature: faker.string.alpha(20), ...overrideResponse });
 
+export const getSendSolanaTransactionResponseMock = (
+  overrideResponse: Partial<SendSolanaTransaction200> = {},
+): SendSolanaTransaction200 => ({
+  transactionSignature: faker.string.alpha(20),
+  ...overrideResponse,
+});
+
 export const getListSolanaAccountsMockHandler = (
   overrideResponse?:
     | ListSolanaAccounts200
@@ -432,6 +440,29 @@ export const getSignSolanaMessageMockHandler = (
     );
   });
 };
+
+export const getSendSolanaTransactionMockHandler = (
+  overrideResponse?:
+    | SendSolanaTransaction200
+    | ((
+        info: Parameters<Parameters<typeof http.post>[1]>[0],
+      ) => Promise<SendSolanaTransaction200> | SendSolanaTransaction200),
+) => {
+  return http.post("*/v2/solana/accounts/send/transaction", async info => {
+    await delay(0);
+
+    return new HttpResponse(
+      JSON.stringify(
+        overrideResponse !== undefined
+          ? typeof overrideResponse === "function"
+            ? await overrideResponse(info)
+            : overrideResponse
+          : getSendSolanaTransactionResponseMock(),
+      ),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  });
+};
 export const getSolanaAccountsMock = () => [
   getListSolanaAccountsMockHandler(),
   getCreateSolanaAccountMockHandler(),
@@ -443,4 +474,5 @@ export const getSolanaAccountsMock = () => [
   getExportSolanaAccountByNameMockHandler(),
   getSignSolanaTransactionMockHandler(),
   getSignSolanaMessageMockHandler(),
+  getSendSolanaTransactionMockHandler(),
 ];