@coinbase/cdp-sdk 1.3.2 → 1.5.0

package/actions/evm/transfer/accountTransferStrategy.ts

@@ -0,0 +1,84 @@
+import {
+  encodeFunctionData,
+  erc20Abi,
+  Hex,
+  TransactionReceipt,
+  WaitForTransactionReceiptTimeoutError,
+} from "viem";
+
+import { TransferExecutionStrategy } from "./types.js";
+import { getErc20Address } from "./utils.js";
+import { EvmAccount } from "../../../accounts/types.js";
+import { serializeEIP1559Transaction } from "../../../utils/serializeTransaction.js";
+
+export const accountTransferStrategy: TransferExecutionStrategy<EvmAccount> = {
+  executeTransfer: async ({ apiClient, from, transferArgs, to, value }) => {
+    const transactionHash = await (async () => {
+      if (transferArgs.token === "eth") {
+        const result = await apiClient.sendEvmTransaction(from.address, {
+          transaction: serializeEIP1559Transaction({
+            value,
+            to,
+          }),
+          network: transferArgs.network,
+        });
+        return result.transactionHash as Hex;
+      } else {
+        const erc20Address = getErc20Address(transferArgs.token, transferArgs.network);
+
+        await apiClient.sendEvmTransaction(from.address, {
+          transaction: serializeEIP1559Transaction({
+            to: erc20Address,
+            data: encodeFunctionData({
+              abi: erc20Abi,
+              functionName: "approve",
+              args: [to, value],
+            }),
+          }),
+          network: transferArgs.network,
+        });
+
+        const result = await apiClient.sendEvmTransaction(from.address, {
+          transaction: serializeEIP1559Transaction({
+            to: erc20Address,
+            data: encodeFunctionData({
+              abi: erc20Abi,
+              functionName: "transfer",
+              args: [to, value],
+            }),
+          }),
+          network: transferArgs.network,
+        });
+
+        return result.transactionHash as Hex;
+      }
+    })();
+
+    return transactionHash;
+  },
+
+  waitForResult: async ({ publicClient, hash }) => {
+    let receipt: TransactionReceipt;
+    try {
+      receipt = await publicClient.waitForTransactionReceipt({
+        hash,
+      });
+    } catch (error) {
+      if (error instanceof WaitForTransactionReceiptTimeoutError) {
+        throw new Error(
+          `Transaction timed out. Check the transaction on the explorer: ${publicClient.chain.blockExplorers?.default.url}/tx/${hash}`,
+        );
+      } else {
+        throw error;
+      }
+    }
+
+    if (receipt.status === "success") {
+      return { status: receipt.status, transactionHash: hash };
+    } else {
+      throw new Error(
+        `Transaction failed. Check the transaction on the explorer: ${publicClient.chain.blockExplorers?.default.url}/tx/${hash}`,
+      );
+    }
+  },
+};

package/actions/evm/transfer/smartAccountTransferStrategy.ts

@@ -0,0 +1,70 @@
+import { encodeFunctionData, erc20Abi } from "viem";
+
+import { TransferExecutionStrategy } from "./types.js";
+import { getErc20Address } from "./utils.js";
+import { EvmSmartAccount } from "../../../accounts/types.js";
+import { sendUserOperation } from "../sendUserOperation.js";
+import { waitForUserOperation } from "../waitForUserOperation.js";
+
+export const smartAccountTransferStrategy: TransferExecutionStrategy<EvmSmartAccount> = {
+  executeTransfer: async ({ apiClient, from, transferArgs, to, value }) => {
+    const userOpHash = await (async () => {
+      if (transferArgs.token === "eth") {
+        const result = await sendUserOperation(apiClient, from, {
+          network: transferArgs.network,
+          calls: [
+            {
+              to,
+              value,
+              data: "0x",
+            },
+          ],
+        });
+        return result.userOpHash;
+      } else {
+        const erc20Address = getErc20Address(transferArgs.token, transferArgs.network);
+
+        const result = await sendUserOperation(apiClient, from, {
+          network: transferArgs.network,
+          calls: [
+            {
+              to: erc20Address,
+              data: encodeFunctionData({
+                abi: erc20Abi,
+                functionName: "approve",
+                args: [to, value],
+              }),
+            },
+            {
+              to: erc20Address,
+              data: encodeFunctionData({
+                abi: erc20Abi,
+                functionName: "transfer",
+                args: [to, value],
+              }),
+            },
+          ],
+        });
+
+        return result.userOpHash;
+      }
+    })();
+
+    return userOpHash;
+  },
+
+  waitForResult: async ({ apiClient, publicClient, from, hash }) => {
+    const result = await waitForUserOperation(apiClient, {
+      smartAccountAddress: from.address,
+      userOpHash: hash,
+    });
+
+    if (result.status === "complete") {
+      return { status: "success", transactionHash: hash };
+    } else {
+      throw new Error(
+        `Transaction failed. Check the transaction on the explorer: ${publicClient.chain.blockExplorers?.default.url}/tx/${hash}`,
+      );
+    }
+  },
+};

package/actions/evm/transfer/transfer.ts

@@ -0,0 +1,71 @@
+import { createPublicClient, http, erc20Abi, parseUnits, Address, Chain, Transport } from "viem";
+
+import { TransferResult, TransferOptions, TransferExecutionStrategy } from "./types.js";
+import { mapNetworkToChain } from "./utils.js";
+import { EvmAccount, EvmSmartAccount } from "../../../accounts/types.js";
+import { CdpOpenApiClientType } from "../../../openapi-client/index.js";
+
+/**
+ * Transfer an amount of a token from an account to another account.
+ *
+ * @param apiClient - The client to use to send the transaction.
+ * @param from - The account to send the transaction from.
+ * @param transferArgs - The options for the transfer.
+ * @param transferStrategy - The strategy to use to execute the transfer.
+ * @returns The result of the transfer.
+ */
+export async function transfer<T extends EvmAccount | EvmSmartAccount>(
+  apiClient: CdpOpenApiClientType,
+  from: T,
+  transferArgs: TransferOptions,
+  transferStrategy: TransferExecutionStrategy<T>,
+): Promise<TransferResult> {
+  const publicClient = createPublicClient<Transport, Chain>({
+    chain: mapNetworkToChain(transferArgs.network),
+    transport: http(),
+  });
+
+  const to =
+    typeof transferArgs.to === "string" ? transferArgs.to : (transferArgs.to.address as Address);
+
+  const value = await (async () => {
+    // user supplied a bigint. otherwise, we need to convert the amount to a bigint
+    if (typeof transferArgs.amount !== "string") {
+      return transferArgs.amount;
+    }
+
+    const decimals = await (async () => {
+      if (transferArgs.token === "eth") {
+        return 18;
+      } else if (transferArgs.token === "usdc") {
+        return 6;
+      } else {
+        return publicClient.readContract({
+          address: transferArgs.token,
+          abi: erc20Abi,
+          functionName: "decimals",
+          args: [],
+        });
+      }
+    })();
+
+    return parseUnits(transferArgs.amount, decimals);
+  })();
+
+  const hash = await transferStrategy.executeTransfer({
+    apiClient,
+    from,
+    transferArgs,
+    to,
+    value,
+  });
+
+  const result = await transferStrategy.waitForResult({
+    apiClient,
+    publicClient,
+    from,
+    hash,
+  });
+
+  return result;
+}

package/actions/evm/transfer/types.ts

@@ -0,0 +1,81 @@
+import { Hex, TransactionReceipt, Address, PublicClient, Chain, Transport } from "viem";
+
+import {
+  CdpOpenApiClientType,
+  EvmAccount,
+  EvmUserOperationNetwork,
+  SendEvmTransactionBodyNetwork,
+} from "../../../openapi-client/index.js";
+
+/**
+ * The network to transfer the token on.
+ */
+export type Network = SendEvmTransactionBodyNetwork | EvmUserOperationNetwork;
+
+/**
+ * The options for the transfer.
+ */
+export type TransferOptions = {
+  /** The account to transfer the token to. */
+  to: EvmAccount | Address;
+  /**
+   * The amount of the token to transfer.
+   * If a string is provided, it will be parsed into a bigint based on the token's decimals.
+   */
+  amount: bigint | string;
+  /** The token to transfer. Can be a contract address or a predefined token name. */
+  token: "eth" | "usdc" | Hex;
+  /** The network to transfer the token on. */
+  network: Network;
+};
+
+/**
+ * The result of the transfer.
+ */
+export type TransferResult = {
+  /** The status of the transaction. */
+  status: TransactionReceipt["status"];
+  /** The transaction hash of the transfer. */
+  transactionHash: Hex;
+};
+
+/**
+ * A strategy for executing a transfer.
+ */
+export interface TransferExecutionStrategy<T> {
+  /**
+   * Executes the transfer.
+   *
+   * @param args - The arguments for the transfer.
+   * @param args.apiClient - The API client to use for the transfer.
+   * @param args.from - The account to transfer the token from.
+   * @param args.transferArgs - The arguments for the transfer.
+   * @param args.to - The account to transfer the token to.
+   * @param args.value - The value of the transfer.
+   * @returns The transaction hash of the transfer.
+   */
+  executeTransfer(args: {
+    apiClient: CdpOpenApiClientType;
+    from: T;
+    transferArgs: TransferOptions;
+    to: Address;
+    value: bigint;
+  }): Promise<Hex>;
+
+  /**
+   * Waits for the result of the transfer.
+   *
+   * @param args - The arguments for the transfer.
+   * @param args.apiClient - The API client to use for the transfer.
+   * @param args.publicClient - The public client to use for the transfer.
+   * @param args.from - The account to transfer the token from.
+   * @param args.hash - The transaction hash of the transfer.
+   * @returns The result of the transfer.
+   */
+  waitForResult(args: {
+    apiClient: CdpOpenApiClientType;
+    publicClient: PublicClient<Transport, Chain>;
+    from: T;
+    hash: Hex;
+  }): Promise<TransferResult>;
+}

package/actions/evm/transfer/utils.ts

@@ -0,0 +1,39 @@
+import { base, baseSepolia } from "viem/chains";
+
+import { Network } from "./types.js";
+
+/**
+ * The address of an ERC20 token for a given network.
+ */
+const addressMap = {
+  base: {
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+  "base-sepolia": {
+    usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  },
+};
+
+/**
+ * Get the address of an ERC20 token for a given network.
+ * If a contract address is provided, it will not be found in the map and will be returned as is.
+ *
+ * @param token - The token symbol or contract address.
+ * @param network - The network to get the address for.
+ *
+ * @returns The address of the ERC20 token.
+ */
+export function getErc20Address(token: string, network: Network) {
+  return addressMap[network][token] ?? token;
+}
+
+/**
+ * Map a network to a viem chain.
+ * TODO: Add more networks (or dynamically map viem chains).
+ *
+ * @param network - The network to map to a chain.
+ * @returns The chain for the given network.
+ */
+export function mapNetworkToChain(network: Network) {
+  return network === "base" ? base : baseSepolia;
+}

package/actions/evm/types.ts

@@ -0,0 +1,88 @@
+import { TransferOptions, TransferResult } from "./transfer/types.js";
+
+export type Actions = {
+  /**
+   * Transfer an amount of a token from an account to another account.
+   *
+   * @param options - The options for the transfer.
+   * @param options.to - The account or 0x-prefixed address to transfer the token to.
+   * @param options.amount - The amount of the token to transfer.
+   * @param options.token - The token to transfer.
+   * @param options.network - The network to transfer the token on.
+   *
+   * @returns The result of the transfer.
+   *
+   * @example
+   * ```typescript
+   * const { status } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: "0.01",
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Pass a bigint value**
+   * ```typescript
+   * const { status } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: 10000n, // equivalent to 0.01 usdc
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Transfer from a smart account**
+   * ```typescript
+   * const sender = await cdp.evm.createSmartAccount({
+   *   owner: await cdp.evm.createAccount({ name: "Owner" }),
+   * });
+   *
+   * const { status } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: "0.01",
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Transfer ETH**
+   * ```typescript
+   * const { status } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: "0.000001",
+   *   token: "eth",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Using a contract address**
+   * ```typescript
+   * const { status } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: "0.000001",
+   *   token: "0x4200000000000000000000000000000000000006", // WETH on Base Sepolia
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Transfer to another account**
+   * ```typescript
+   * const sender = await cdp.evm.createAccount({ name: "Sender" });
+   * const receiver = await cdp.evm.createAccount({ name: "Receiver" });
+   *
+   * const { status } = await sender.transfer({
+   *   to: receiver,
+   *   amount: "0.01",
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   */
+  transfer: (options: TransferOptions) => Promise<TransferResult>;
+};

package/auth/README.md

@@ -25,6 +25,7 @@ npm install @coinbase/cdp-sdk
 ```typescript
 import { generateJwt } from "@coinbase/cdp-sdk/auth";
 
+// For REST (HTTP) requests
 const jwt = await generateJwt({
   apiKeyId: "YOUR_API_KEY_ID",
   apiKeySecret: "YOUR_API_KEY_SECRET",
@@ -35,6 +36,18 @@ const jwt = await generateJwt({
 });
 
 console.log(jwt);
+
+// For websocket connections
+const websocketJwt = await generateJwt({
+  apiKeyId: "YOUR_API_KEY_ID",
+  apiKeySecret: "YOUR_API_KEY_SECRET",
+  requestMethod: null,
+  requestHost: null,
+  requestPath: null,
+  expiresIn: 120, // optional (defaults to 120 seconds)
+});
+
+console.log(websocketJwt);
 ```
 
 For information about the above parameters, please refer to the [Authentication parameters](#authentication-parameters) section.
@@ -138,8 +151,10 @@ The following table provides more context of many of the authentication paramete
 | :-- | :-- | :-- |
 | `apiKeyId` | true | The unique identifier for your API key. Supported formats are:<br/>- `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`<br/>- `organizations/{orgId}/apiKeys/{keyId}` |
 | `apiKeySecret` | true | Your API key secret. Supported formats are:<br/>- Edwards key (Ed25519): `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==`<br/>- Elliptic Curve key (ES256): `-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n` |
-| `requestMethod` | true | The HTTP method for the API request you're authenticating (ie, `GET`, `POST`, `PUT`, `DELETE`). |
-| `requestHost` | true | The API host you're calling (ie, `api.cdp.coinbase.com`). |
-| `requestPath` | true | The path of the specific API endpoint you're calling (ie, `/platform/v1/wallets`). |
+| `requestMethod` | true* | The HTTP method for the API request you're authenticating (ie, `GET`, `POST`, `PUT`, `DELETE`). Can be `null` for JWTs intended for websocket connections. |
+| `requestHost` | true* | The API host you're calling (ie, `api.cdp.coinbase.com`). Can be `null` for JWTs intended for websocket connections. |
+| `requestPath` | true* | The path of the specific API endpoint you're calling (ie, `/platform/v1/wallets`). Can be `null` for JWTs intended for websocket connections. |
 | `requestBody` | false | Optional request body data. |
 | `expiresIn` | false | The JWT expiration time in seconds. After this time, the JWT will no longer be valid, and a new one must be generated. Defaults to `120` (ie, 2 minutes) if not specified. |
+
+\* Either all three request parameters (`requestMethod`, `requestHost`, and `requestPath`) must be provided for REST API requests, or all three must be `null` for JWTs intended for websocket connections.

package/auth/index.ts

@@ -2,4 +2,5 @@ import * as axiosHooks from "./hooks/axios/index.js";
 
 export * from "./utils/http.js";
 export * from "./utils/jwt.js";
+export * from "./utils/ws.js";
 export { axiosHooks };

package/auth/utils/http.ts

@@ -62,6 +62,11 @@ export interface GetAuthHeadersOptions {
    * Optional expiration time in seconds (defaults to 120)
    */
   expiresIn?: number;
+
+  /**
+   * Optional audience claim for the JWT
+   */
+  audience?: string[];
 }
 
 /**
@@ -83,6 +88,7 @@ export async function getAuthHeaders(
     requestHost: options.requestHost,
     requestPath: options.requestPath,
     expiresIn: options.expiresIn,
+    audience: options.audience,
   });
   headers["Authorization"] = `Bearer ${jwt}`;
   headers["Content-Type"] = "application/json";
@@ -131,7 +137,7 @@ function requiresWalletAuth(requestMethod: string, requestPath: string): boolean
  * @param sourceVersion - The version of the source making the request
  * @returns Encoded correlation data as a query string
  */
-function getCorrelationData(source?: string, sourceVersion?: string): string {
+export function getCorrelationData(source?: string, sourceVersion?: string): string {
   const data = {
     sdk_version: version,
     sdk_language: "typescript",

package/auth/utils/index.ts

@@ -1,2 +1,3 @@
 export * from "./http.js";
 export * from "./jwt.js";
+export * from "./ws.js";

package/auth/utils/jwt.ts

@@ -32,24 +32,29 @@ export interface JwtOptions {
   apiKeySecret: string;
 
   /**
-   * The HTTP method for the request (e.g. 'GET', 'POST')
+   * The HTTP method for the request (e.g. 'GET', 'POST'), or null for JWTs intended for websocket connections
    */
-  requestMethod: string;
+  requestMethod?: string | null;
 
   /**
-   * The host for the request (e.g. 'api.cdp.coinbase.com')
+   * The host for the request (e.g. 'api.cdp.coinbase.com'), or null for JWTs intended for websocket connections
    */
-  requestHost: string;
+  requestHost?: string | null;
 
   /**
-   * The path for the request (e.g. '/platform/v1/wallets')
+   * The path for the request (e.g. '/platform/v1/wallets'), or null for JWTs intended for websocket connections
    */
-  requestPath: string;
+  requestPath?: string | null;
 
   /**
    * Optional expiration time in seconds (defaults to 120)
    */
   expiresIn?: number;
+
+  /**
+   * Optional audience claim for the JWT
+   */
+  audience?: string[];
 }
 
 /**
@@ -88,7 +93,9 @@ export interface WalletJwtOptions {
 
 /**
  * Generates a JWT (also known as a Bearer token) for authenticating with Coinbase's REST APIs.
- * Supports both EC (ES256) and Ed25519 (EdDSA) keys.
+ * Supports both EC (ES256) and Ed25519 (EdDSA) keys. Also supports JWTs meant for
+ * websocket connections by allowing requestMethod, requestHost, and requestPath to all be
+ * null, in which case the 'uris' claim is omitted from the JWT.
  *
  * @param options - The configuration options for generating the JWT
  * @returns The generated JWT (Bearer token) string
@@ -102,22 +109,38 @@ export async function generateJwt(options: JwtOptions): Promise<string> {
   if (!options.apiKeySecret) {
     throw new Error("Private key is required");
   }
-  if (!options.requestMethod || !options.requestHost || !options.requestPath) {
-    throw new Error("Request details (method, host, path) are required");
+
+  // Check if we have a REST API request or a websocket connection
+  const hasAllRequestParams = Boolean(
+    options.requestMethod && options.requestHost && options.requestPath,
+  );
+  const hasNoRequestParams =
+    (options.requestMethod === undefined || options.requestMethod === null) &&
+    (options.requestHost === undefined || options.requestHost === null) &&
+    (options.requestPath === undefined || options.requestPath === null);
+
+  // Ensure we either have all request parameters or none (for websocket)
+  if (!hasAllRequestParams && !hasNoRequestParams) {
+    throw new Error(
+      "Either all request details (method, host, path) must be provided, or all must be null for JWTs intended for websocket connections",
+    );
   }
 
   const now = Math.floor(Date.now() / 1000);
   const expiresIn = options.expiresIn || 120; // Default to 120 seconds if not specified
-  const uri = `${options.requestMethod} ${options.requestHost}${options.requestPath}`;
 
   // Prepare the JWT payload
-  const claims = {
+  const claims: JWTPayload = {
     sub: options.apiKeyId,
     iss: "cdp",
-    aud: ["cdp_service"],
-    uris: [uri],
+    aud: options.audience || ["cdp_service"],
   };
 
+  // Add the uris claim only for REST API requests
+  if (hasAllRequestParams) {
+    claims.uris = [`${options.requestMethod} ${options.requestHost}${options.requestPath}`];
+  }
+
   // Generate random nonce for the header
   const randomNonce = nonce();
 

package/auth/utils/ws.ts

@@ -0,0 +1,76 @@
+import { getCorrelationData } from "./http.js";
+import { generateJwt } from "./jwt.js";
+
+/**
+ * Options for generating WebSocket authentication headers.
+ */
+export interface GetWebSocketAuthHeadersOptions {
+  /**
+   * The API key ID
+   *
+   * Examples:
+   *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   */
+  apiKeyId: string;
+
+  /**
+   * The API key secret
+   *
+   * Examples:
+   *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+   *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+   */
+  apiKeySecret: string;
+
+  /**
+   * The source identifier for the request
+   */
+  source?: string;
+
+  /**
+   * The version of the source making the request
+   */
+  sourceVersion?: string;
+
+  /**
+   * Optional expiration time in seconds (defaults to 120)
+   */
+  expiresIn?: number;
+
+  /**
+   * Optional audience claim for the JWT
+   */
+  audience?: string[];
+}
+
+/**
+ * Gets authentication headers for a WebSocket connection.
+ *
+ * @param options - The configuration options for generating WebSocket auth headers
+ * @returns Object containing the authentication headers
+ */
+export async function getWebSocketAuthHeaders(
+  options: GetWebSocketAuthHeadersOptions,
+): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {};
+
+  // Generate and add JWT token without request parameters for WebSocket
+  const jwt = await generateJwt({
+    apiKeyId: options.apiKeyId,
+    apiKeySecret: options.apiKeySecret,
+    // All request parameters are null for WebSocket
+    requestMethod: null,
+    requestHost: null,
+    requestPath: null,
+    expiresIn: options.expiresIn,
+    audience: options.audience,
+  });
+  headers["Authorization"] = `Bearer ${jwt}`;
+  headers["Content-Type"] = "application/json";
+
+  // Add correlation data
+  headers["Correlation-Context"] = getCorrelationData(options.source, options.sourceVersion);
+
+  return headers;
+}