@coinbase/cdp-sdk 1.5.0 → 1.7.0

package/actions/evm/types.ts

@@ -1,6 +1,21 @@
-import { TransferOptions, TransferResult } from "./transfer/types.js";
+import { SendUserOperationOptions, SendUserOperationReturnType } from "./sendUserOperation.js";
+import { GetUserOperationOptions, UserOperation } from "../../client/evm/evm.types.js";
+import { EvmAccount, EvmSmartAccount } from "../../openapi-client/index.js";
 
-export type Actions = {
+import type { ListTokenBalancesOptions, ListTokenBalancesResult } from "./listTokenBalances.js";
+import type { RequestFaucetOptions, RequestFaucetResult } from "./requestFaucet.js";
+import type { SendTransactionOptions, TransactionResult } from "./sendTransaction.js";
+import type {
+  AccountTransferOptions,
+  SmartAccountTransferOptions,
+  TransferResult,
+} from "./transfer/types.js";
+import type {
+  WaitForUserOperationOptions,
+  WaitForUserOperationReturnType,
+} from "./waitForUserOperation.js";
+
+type Actions<T extends EvmAccount | EvmSmartAccount> = {
   /**
    * Transfer an amount of a token from an account to another account.
    *
@@ -84,5 +99,178 @@ export type Actions = {
    * });
    * ```
    */
-  transfer: (options: TransferOptions) => Promise<TransferResult>;
+  transfer: (
+    options: T extends EvmSmartAccount ? SmartAccountTransferOptions : AccountTransferOptions,
+  ) => Promise<TransferResult>;
+
+  /**
+   * List the token balances of an account.
+   *
+   * @param options - The options for the list token balances.
+   * @param options.network - The network to list the token balances on.
+   *
+   * @returns The result of the list token balances.
+   *
+   * @example
+   * ```typescript
+   * const balances = await account.listTokenBalances({
+   *   network: "base-sepolia",
+   * });
+   * ```
+   */
+  listTokenBalances: (
+    options: Omit<ListTokenBalancesOptions, "address">,
+  ) => Promise<ListTokenBalancesResult>;
+
+  /**
+   * Requests funds from an EVM faucet.
+   *
+   * @param {RequestFaucetOptions} options - Parameters for requesting funds from the EVM faucet.
+   * @param {string} options.network - The network to request funds from.
+   * @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 hash.
+   *
+   * @example
+   * ```ts
+   * const result = await account.requestFaucet({
+   *   network: "base-sepolia",
+   *   token: "eth",
+   * });
+   * ```
+   */
+  requestFaucet: (options: Omit<RequestFaucetOptions, "address">) => Promise<RequestFaucetResult>;
+};
+
+export type AccountActions = Actions<EvmAccount> & {
+  /**
+   * Signs an EVM transaction and sends it to the specified network using the Coinbase API.
+   * This method handles nonce management and gas estimation automatically.
+   *
+   * @param {SendTransactionOptions} options - Configuration options for sending the transaction.
+   * @returns A promise that resolves to the transaction hash.
+   *
+   * @example
+   * **Sending an RLP-encoded transaction**
+   * ```ts
+   * import { parseEther, serializeTransaction } from "viem";
+   * import { baseSepolia } from "viem/chains";
+   *
+   * const { transactionHash } = await account.sendTransaction({
+   *   transaction: serializeTransaction({
+   *     to: "0x4252e0c9A3da5A2700e7d91cb50aEf522D0C6Fe8",
+   *     value: parseEther("0.000001"),
+   *     chainId: baseSepolia.id,
+   *     // Fields below are optional, CDP API will populate them if omitted.
+   *     // nonce
+   *     // maxPriorityFeePerGas
+   *     // maxFeePerGas
+   *     // gas
+   *   }),
+   *   network: "base-sepolia",
+   * });
+   * ```
+   * @example
+   * **Sending an EIP-1559 transaction request object**
+   * ```ts
+   * const { transactionHash } = await account.sendTransaction({
+   *   transaction: {
+   *     to: "0x4252e0c9A3da5A2700e7d91cb50aEf522D0C6Fe8",
+   *     value: parseEther("0.000001"),
+   *     // Fields below are optional, CDP API will populate them if omitted.
+   *     // nonce
+   *     // maxPriorityFeePerGas
+   *     // maxFeePerGas
+   *     // gas
+   *   },
+   *   network: "base-sepolia",
+   * });
+   * ```
+   */
+  sendTransaction: (options: Omit<SendTransactionOptions, "address">) => Promise<TransactionResult>;
+};
+
+export type SmartAccountActions = Actions<EvmSmartAccount> & {
+  /**
+   * Sends a user operation.
+   *
+   * @param {SendUserOperationOptions} options - Parameters for sending the user operation.
+   * @param {string} options.network - The network to send the user operation on.
+   * @param {EvmCall[]} options.calls - The calls to include in the user operation.
+   * @param {string} [options.paymasterUrl] - The optional paymaster URL to use for the user operation.
+   * @param {string} [options.idempotencyKey] - An idempotency key.
+   *
+   * @returns A promise that resolves to an object containing the smart account address,
+   * the user operation hash, and the status of the user operation.
+   *
+   * @example
+   * ```ts
+   * const userOp = await smartAccount.sendUserOperation({
+   *   network: "base-sepolia",
+   *   calls: [
+   *     {
+   *       to: "0x1234567890123456789012345678901234567890",
+   *       value: parseEther("0.000001"),
+   *       data: "0x",
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  sendUserOperation: (
+    options: Omit<SendUserOperationOptions<unknown[]>, "smartAccount">,
+  ) => Promise<SendUserOperationReturnType>;
+
+  /**
+   * Waits for a user operation to complete or fail.
+   *
+   * @param {WaitForUserOperationOptions} options - Parameters for waiting for the user operation.
+   * @param {string} options.userOpHash - The user operation hash.
+   * @param {WaitOptions} [options.waitOptions] - Optional parameters for the wait operation.
+   *
+   * @returns A promise that resolves to the transaction receipt.
+   *
+   * @example
+   * ```ts
+   * // Send a user operation and get the user operation hash
+   * const { userOpHash } = await smartAccount.sendUserOperation({
+   *   network: "base-sepolia",
+   *   calls: [
+   *     {
+   *       to: "0x0000000000000000000000000000000000000000",
+   *       value: parseEther("0.000001"),
+   *       data: "0x",
+   *     },
+   *   ],
+   * });
+   *
+   * // Wait for the user operation to complete or fail
+   * const result = await smartAccount.waitForUserOperation({
+   *   userOpHash: userOp.userOpHash,
+   * });
+   * ```
+   */
+  waitForUserOperation: (
+    options: Omit<WaitForUserOperationOptions, "smartAccountAddress">,
+  ) => Promise<WaitForUserOperationReturnType>;
+
+  /**
+   * Gets a user operation by its hash.
+   *
+   * @param {GetUserOperationOptions} options - Parameters for getting the user operation.
+   * @param {string} options.userOpHash - The user operation hash.
+   *
+   * @returns A promise that resolves to the user operation.
+   *
+   * @example
+   * ```ts
+   * const userOp = await smartAccount.getUserOperation({
+   *   userOpHash: "0x1234567890123456789012345678901234567890",
+   * });
+   * ```
+   */
+  getUserOperation: (
+    options: Omit<GetUserOperationOptions, "smartAccount">,
+  ) => Promise<UserOperation>;
 };

package/actions/solana/requestFaucet.ts

@@ -0,0 +1,35 @@
+import { RequestFaucetOptions, SignatureResult } from "../../client/solana/solana.types.js";
+import { CdpOpenApiClientType } from "../../openapi-client/index.js";
+
+/**
+ * Requests funds from a Solana faucet.
+ *
+ * @param apiClient - The API client.
+ * @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 requestFaucet(cdp.solana, {
+ *            address: "1234567890123456789012345678901234567890",
+ *            token: "sol",
+ *          });
+ *          ```
+ */
+export async function requestFaucet(
+  apiClient: CdpOpenApiClientType,
+  options: RequestFaucetOptions,
+): Promise<SignatureResult> {
+  const signature = await apiClient.requestSolanaFaucet(
+    { address: options.address, token: options.token },
+    options.idempotencyKey,
+  );
+
+  return {
+    signature: signature.transactionSignature,
+  };
+}

package/actions/solana/signMessage.ts

@@ -0,0 +1,36 @@
+import { SignMessageOptions, SignatureResult } from "../../client/solana/solana.types.js";
+import { CdpOpenApiClientType } from "../../openapi-client/index.js";
+
+/**
+ * Sign a message.
+ *
+ * @param apiClient - The API client.
+ * @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 transaction signature.
+ *
+ * @example
+ *          ```ts
+ *          const signature = await signMessage(cdp.solana, {
+ *            address: "1234567890123456789012345678901234567890",
+ *            message: "Hello, world!",
+ *          });
+ *          ```
+ */
+export async function signMessage(
+  apiClient: CdpOpenApiClientType,
+  options: SignMessageOptions,
+): Promise<SignatureResult> {
+  const signature = await apiClient.signSolanaMessage(
+    options.address,
+    { message: options.message },
+    options.idempotencyKey,
+  );
+
+  return {
+    signature: signature.signature,
+  };
+}

package/actions/solana/signTransaction.ts

@@ -0,0 +1,53 @@
+import { SignTransactionOptions, SignatureResult } from "../../client/solana/solana.types.js";
+import { CdpOpenApiClientType } from "../../openapi-client/index.js";
+
+/**
+ * Signs a transaction.
+ *
+ * @param apiClient - The API client.
+ * @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 signTransaction(cdp.solana, {
+ *   address: account.address,
+ *   transaction,
+ * });
+ * ```
+ */
+export async function signTransaction(
+  apiClient: CdpOpenApiClientType,
+  options: SignTransactionOptions,
+): Promise<SignatureResult> {
+  const signature = await apiClient.signSolanaTransaction(
+    options.address,
+    {
+      transaction: options.transaction,
+    },
+    options.idempotencyKey,
+  );
+
+  return {
+    signature: signature.signedTransaction,
+  };
+}

package/actions/solana/types.ts

@@ -0,0 +1,87 @@
+import {
+  RequestFaucetOptions,
+  SignatureResult,
+  SignMessageOptions,
+  SignTransactionOptions,
+} from "../../client/solana/solana.types.js";
+
+export type AccountActions = {
+  /**
+   * Requests funds from a Solana faucet.
+   *
+   * @param {RequestFaucetOptions} options - Parameters for requesting funds from the Solana faucet.
+   * @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 hash.
+   *
+   * @example
+   * ```ts
+   * // Create a Solana account
+   * const account = await cdp.solana.createAccount();
+   *
+   * // Request funds from the Solana faucet
+   * const result = await account.requestFaucet({
+   *   token: "sol",
+   * });
+   * ```
+   */
+  requestFaucet: (options: Omit<RequestFaucetOptions, "address">) => Promise<SignatureResult>;
+
+  /**
+   * 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();
+   *
+   * // Sign a message
+   * const { signature } = await account.signMessage({
+   *   message: "Hello, world!",
+   * });
+   * ```
+   */
+  signMessage: (options: Omit<SignMessageOptions, "address">) => Promise<SignatureResult>;
+
+  /**
+   * 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 account.signTransaction({
+   *   transaction,
+   * });
+   * ```
+   */
+  signTransaction: (options: Omit<SignTransactionOptions, "address">) => Promise<SignatureResult>;
+};

package/client/evm/evm.ts

@@ -1,14 +1,11 @@
-import { Address, serializeTransaction } from "viem";
+import { Address } from "viem";
 
 import {
   CreateServerAccountOptions,
   GetServerAccountOptions,
   ListServerAccountsOptions,
   CreateSmartAccountOptions,
-  RequestFaucetOptions,
-  SendUserOperationOptions,
   WaitForUserOperationOptions,
-  RequestFaucetResult,
   SignHashOptions,
   SignatureResult,
   SignMessageOptions,
@@ -23,16 +20,25 @@ import {
   GetUserOperationOptions,
   ListSmartAccountResult,
   ListSmartAccountsOptions,
-  ListTokenBalancesOptions,
-  ListTokenBalancesResult,
-  SendTransactionOptions,
-  TransactionResult,
   GetOrCreateServerAccountOptions,
 } 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,
+} from "../../actions/evm/listTokenBalances.js";
+import {
+  RequestFaucetOptions,
+  RequestFaucetResult,
+  requestFaucet,
+} from "../../actions/evm/requestFaucet.js";
+import { sendTransaction } from "../../actions/evm/sendTransaction.js";
 import {
   sendUserOperation,
+  SendUserOperationOptions,
   SendUserOperationReturnType,
 } from "../../actions/evm/sendUserOperation.js";
 import {
@@ -43,6 +49,11 @@ import { APIError } from "../../openapi-client/errors.js";
 import { CdpOpenApiClient } from "../../openapi-client/index.js";
 import { Hex } from "../../types/misc.js";
 
+import type {
+  TransactionResult,
+  SendTransactionOptions,
+} from "../../actions/evm/sendTransaction.js";
+
 /**
  * The namespace containing all EVM methods.
  */
@@ -283,22 +294,7 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async getUserOperation(options: GetUserOperationOptions): Promise<UserOperation> {
-    const userOp = await CdpOpenApiClient.getUserOperation(
-      options.smartAccount.address,
-      options.userOpHash,
-    );
-
-    return {
-      calls: userOp.calls.map(call => ({
-        to: call.to as Address,
-        value: BigInt(call.value),
-        data: call.data as Hex,
-      })),
-      network: userOp.network,
-      status: userOp.status,
-      transactionHash: userOp.transactionHash as Hex | undefined,
-      userOpHash: userOp.userOpHash as Hex,
-    };
+    return getUserOperation(CdpOpenApiClient, options);
   }
 
   /**
@@ -376,28 +372,7 @@ export class EvmClient implements EvmClientInterface {
    * }
    */
   async listTokenBalances(options: ListTokenBalancesOptions): Promise<ListTokenBalancesResult> {
-    const response = await CdpOpenApiClient.listEvmTokenBalances(options.network, options.address, {
-      pageSize: options.pageSize,
-      pageToken: options.pageToken,
-    });
-
-    const balances = response.balances.map(balance => {
-      return {
-        token: {
-          network: balance.token.network,
-          contractAddress: balance.token.contractAddress as Address,
-        },
-        amount: {
-          amount: BigInt(balance.amount.amount),
-          decimals: BigInt(balance.amount.decimals),
-        },
-      };
-    });
-
-    return {
-      balances,
-      nextPageToken: response.nextPageToken,
-    };
+    return listTokenBalances(CdpOpenApiClient, options);
   }
 
   /**
@@ -509,14 +484,7 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async requestFaucet(options: RequestFaucetOptions): Promise<RequestFaucetResult> {
-    const { transactionHash } = await CdpOpenApiClient.requestEvmFaucet(
-      { address: options.address, network: options.network, token: options.token },
-      options.idempotencyKey,
-    );
-
-    return {
-      transactionHash: transactionHash as Hex,
-    };
+    return requestFaucet(CdpOpenApiClient, options);
   }
 
   /**
@@ -566,27 +534,7 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async sendTransaction(options: SendTransactionOptions): Promise<TransactionResult> {
-    const { address, network, idempotencyKey } = options;
-    let transaction = options.transaction;
-
-    if (typeof transaction !== "string") {
-      transaction = serializeTransaction({
-        ...transaction,
-        // chainId is ignored in favor of network
-        chainId: 1,
-        type: "eip1559",
-      });
-    }
-
-    const result = await CdpOpenApiClient.sendEvmTransaction(
-      address,
-      { transaction, network },
-      idempotencyKey,
-    );
-
-    return {
-      transactionHash: result.transactionHash as Hex,
-    };
+    return sendTransaction(CdpOpenApiClient, options);
   }
 
   /**
@@ -617,8 +565,11 @@ export class EvmClient implements EvmClientInterface {
    * });
    * ```
    */
-  async sendUserOperation(options: SendUserOperationOptions): Promise<SendUserOperationReturnType> {
-    return sendUserOperation(CdpOpenApiClient, options.smartAccount, {
+  async sendUserOperation(
+    options: SendUserOperationOptions<unknown[]>,
+  ): Promise<SendUserOperationReturnType> {
+    return sendUserOperation(CdpOpenApiClient, {
+      smartAccount: options.smartAccount,
       network: options.network,
       calls: options.calls,
       paymasterUrl: options.paymasterUrl,