@coinbase/cdp-sdk 1.5.0 → 1.7.0

package/accounts/solana/types.ts

@@ -0,0 +1,13 @@
+import { AccountActions } from "../../actions/solana/types.js";
+import { SolanaAccount as OpenAPISolanaAccount } from "../../openapi-client/index.js";
+import { Prettify } from "../../types/utils.js";
+
+/**
+ * A base Solana account.
+ */
+export type Account = OpenAPISolanaAccount;
+
+/**
+ * A Solana account with actions.
+ */
+export type SolanaAccount = Prettify<OpenAPISolanaAccount & AccountActions>;

package/actions/evm/getUserOperation.ts

@@ -0,0 +1,40 @@
+import { GetUserOperationOptions, UserOperation } from "../../client/evm/evm.types.js";
+import { CdpOpenApiClientType } from "../../openapi-client/index.js";
+import { Address, Hex } from "../../types/misc.js";
+
+/**
+ * Gets a user operation for a smart account by user operation hash.
+ *
+ * @param {CdpOpenApiClientType} client - The client to use to get the user operation.
+ * @param {GetUserOperationOptions} options - Parameters for getting the user operation.
+ * @param {SmartAccount} options.smartAccount - The smart account signing 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 getUserOperation(client, {
+ *   smartAccount,
+ *   userOpHash: "0x1234567890123456789012345678901234567890123456789012345678901234",
+ * });
+ * ```
+ */
+export async function getUserOperation(
+  client: CdpOpenApiClientType,
+  options: GetUserOperationOptions,
+): Promise<UserOperation> {
+  const userOp = await client.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,
+  };
+}

package/actions/evm/listTokenBalances.ts

@@ -0,0 +1,107 @@
+import { Address } from "viem";
+
+import { CdpOpenApiClientType, ListEvmTokenBalancesNetwork } from "../../openapi-client/index.js";
+
+/**
+ * A token on an EVM network, which is either an ERC-20 or a native token (i.e. ETH).
+ */
+export interface EvmToken {
+  /**
+   * The contract address of the token. For Ether, the contract address is 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
+   * per EIP-7528. For ERC-20 tokens, this is the contract address where the token is deployed.
+   */
+  contractAddress: Address;
+  /** The network the token is on. */
+  network: ListEvmTokenBalancesNetwork;
+  /**
+   * The symbol of the token, which is optional and non-unique. Note: This field
+   * may not be present for most tokens while the API is still under development.
+   */
+  symbol?: string;
+  /**
+   * The name of the token, which is optional and non-unique. Note: This field
+   * may not be present for most tokens while the API is still under development.
+   */
+  name?: string;
+}
+
+/**
+ * A token amount on an EVM network.
+ */
+export interface EvmTokenAmount {
+  /** The amount of the token in the smallest indivisible unit of the token. */
+  amount: bigint;
+  /** The number of decimals in the token. */
+  decimals: bigint;
+}
+/**
+ * An EVM token balance.
+ */
+export interface EvmTokenBalance {
+  /** The token. */
+  token: EvmToken;
+  /** The amount of the token. */
+  amount: EvmTokenAmount;
+}
+
+/**
+ * Options for listing EVM token balances.
+ */
+export interface ListTokenBalancesOptions {
+  /** The address of the account. */
+  address: Address;
+  /** The network. */
+  network: ListEvmTokenBalancesNetwork;
+  /** The page size to paginate through the token balances. */
+  pageSize?: number;
+  /** The page token to paginate through the token balances. */
+  pageToken?: string;
+}
+
+/**
+ * The result of listing EVM token balances.
+ */
+export interface ListTokenBalancesResult {
+  /** The token balances. */
+  balances: EvmTokenBalance[];
+  /**
+   * The next page token to paginate through the token balances.
+   * If undefined, there are no more token balances to paginate through.
+   */
+  nextPageToken?: string;
+}
+
+/**
+ * List the token balances for an EVM account.
+ *
+ * @param client - The client to use to list the token balances.
+ * @param options - The options for listing the token balances.
+ * @returns The result of listing the token balances.
+ */
+export async function listTokenBalances(
+  client: CdpOpenApiClientType,
+  options: ListTokenBalancesOptions,
+): Promise<ListTokenBalancesResult> {
+  const response = await client.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,
+  };
+}

package/actions/evm/requestFaucet.ts

@@ -0,0 +1,46 @@
+import { type CdpOpenApiClientType } from "../../openapi-client/index.js";
+import { Hex } from "../../types/misc.js";
+
+/**
+ * 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;
+}
+
+/**
+ * Requests funds from an EVM faucet.
+ *
+ * @param apiClient - The API client.
+ * @param options - The options for requesting funds from the EVM faucet.
+ *
+ * @returns A promise that resolves to the transaction hash.
+ */
+export async function requestFaucet(
+  apiClient: CdpOpenApiClientType,
+  options: RequestFaucetOptions,
+) {
+  const { transactionHash } = await apiClient.requestEvmFaucet(
+    { address: options.address, network: options.network, token: options.token },
+    options.idempotencyKey,
+  );
+
+  return {
+    transactionHash: transactionHash as Hex,
+  };
+}

package/actions/evm/sendTransaction.ts

@@ -0,0 +1,73 @@
+import { serializeTransaction, TransactionRequestEIP1559 } from "viem";
+
+import type {
+  CdpOpenApiClientType,
+  SendEvmTransactionBodyNetwork,
+} from "../../openapi-client/index.js";
+import type { Address, Hex } from "../../types/misc.js";
+
+/**
+ * Options for sending an EVM transaction.
+ */
+export interface SendTransactionOptions {
+  /** The address of the account. */
+  address: Address;
+  /**
+   * The transaction to send. The chainId is ignored in favor of the `network` field.
+   *
+   * This can be either:
+   * - An RLP-encoded transaction to sign and send, as a 0x-prefixed hex string, or
+   * - An EIP-1559 transaction request object.
+   */
+  transaction: Hex | TransactionRequestEIP1559;
+  /**
+   * The network to send the transaction to.
+   * The chainId in the `transaction` field is ignored in favor of this field.
+   */
+  network: SendEvmTransactionBodyNetwork;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Result of a transaction
+ */
+export interface TransactionResult {
+  /** The hash of the transaction. */
+  transactionHash: Hex;
+}
+
+/**
+ * Sends an EVM transaction.
+ *
+ * @param apiClient - The API client.
+ * @param options - The options for sending the transaction.
+ *
+ * @returns The result of the transaction.
+ */
+export async function sendTransaction(
+  apiClient: CdpOpenApiClientType,
+  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 apiClient.sendEvmTransaction(
+    address,
+    { transaction, network },
+    idempotencyKey,
+  );
+
+  return {
+    transactionHash: result.transactionHash as Hex,
+  };
+}

package/actions/evm/sendUserOperation.ts

@@ -6,7 +6,7 @@ import {
   CdpOpenApiClientType,
 } from "../../openapi-client/index.js";
 
-import type { EvmSmartAccount } from "../../accounts/types.js";
+import type { EvmSmartAccount } from "../../accounts/evm/types.js";
 import type { Calls } from "../../types/calls.js";
 import type { Address, Hex } from "../../types/misc.js";
 
@@ -16,6 +16,8 @@ import type { Address, Hex } from "../../types/misc.js";
  * @template T - Array type for the calls parameter.
  */
 export type SendUserOperationOptions<T extends readonly unknown[]> = {
+  /** The smart account. */
+  smartAccount: EvmSmartAccount;
   /**
    * Array of contract calls to execute in the user operation.
    * Each call can either be:
@@ -97,13 +99,11 @@ export type SendUserOperationReturnType = {
  * ```
  *
  * @param {CdpOpenApiClientType} client - The client to use to send the user operation.
- * @param {EvmSmartAccount} smartAccount - The smart account to send the user operation from.
  * @param {SendUserOperationOptions<T>} options - The options for the user operation.
  * @returns {Promise<SendUserOperationReturnType>} The result of the user operation.
  */
 export async function sendUserOperation<T extends readonly unknown[]>(
   client: CdpOpenApiClientType,
-  smartAccount: EvmSmartAccount,
   options: SendUserOperationOptions<T>,
 ): Promise<SendUserOperationReturnType> {
   const { calls, network, paymasterUrl } = options;
@@ -134,20 +134,20 @@ export async function sendUserOperation<T extends readonly unknown[]>(
     };
   });
 
-  const createOpResponse = await client.prepareUserOperation(smartAccount.address, {
+  const createOpResponse = await client.prepareUserOperation(options.smartAccount.address, {
     network,
     calls: encodedCalls,
     paymasterUrl,
   });
 
-  const owner = smartAccount.owners[0];
+  const owner = options.smartAccount.owners[0];
 
   const signature = await owner.sign({
     hash: createOpResponse.userOpHash as Hex,
   });
 
   const broadcastResponse = await client.sendUserOperation(
-    smartAccount.address,
+    options.smartAccount.address,
     createOpResponse.userOpHash as Hex,
     {
       signature,
@@ -156,7 +156,7 @@ export async function sendUserOperation<T extends readonly unknown[]>(
   );
 
   return {
-    smartAccountAddress: smartAccount.address,
+    smartAccountAddress: options.smartAccount.address,
     status: broadcastResponse.status,
     userOpHash: createOpResponse.userOpHash,
   } as SendUserOperationReturnType;

package/actions/evm/transfer/accountTransferStrategy.ts

@@ -8,23 +8,23 @@ import {
 
 import { TransferExecutionStrategy } from "./types.js";
 import { getErc20Address } from "./utils.js";
-import { EvmAccount } from "../../../accounts/types.js";
+import { EvmAccount } from "../../../accounts/evm/types.js";
 import { serializeEIP1559Transaction } from "../../../utils/serializeTransaction.js";
 
 export const accountTransferStrategy: TransferExecutionStrategy<EvmAccount> = {
-  executeTransfer: async ({ apiClient, from, transferArgs, to, value }) => {
+  executeTransfer: async ({ apiClient, from, to, value, token, network }) => {
     const transactionHash = await (async () => {
-      if (transferArgs.token === "eth") {
+      if (token === "eth") {
         const result = await apiClient.sendEvmTransaction(from.address, {
           transaction: serializeEIP1559Transaction({
             value,
             to,
           }),
-          network: transferArgs.network,
+          network,
         });
         return result.transactionHash as Hex;
       } else {
-        const erc20Address = getErc20Address(transferArgs.token, transferArgs.network);
+        const erc20Address = getErc20Address(token, network);
 
         await apiClient.sendEvmTransaction(from.address, {
           transaction: serializeEIP1559Transaction({
@@ -35,7 +35,7 @@ export const accountTransferStrategy: TransferExecutionStrategy<EvmAccount> = {
               args: [to, value],
             }),
           }),
-          network: transferArgs.network,
+          network,
         });
 
         const result = await apiClient.sendEvmTransaction(from.address, {
@@ -47,7 +47,7 @@ export const accountTransferStrategy: TransferExecutionStrategy<EvmAccount> = {
               args: [to, value],
             }),
           }),
-          network: transferArgs.network,
+          network,
         });
 
         return result.transactionHash as Hex;
@@ -57,11 +57,15 @@ export const accountTransferStrategy: TransferExecutionStrategy<EvmAccount> = {
     return transactionHash;
   },
 
-  waitForResult: async ({ publicClient, hash }) => {
+  waitForResult: async ({ publicClient, hash, waitOptions }) => {
     let receipt: TransactionReceipt;
     try {
       receipt = await publicClient.waitForTransactionReceipt({
         hash,
+        pollingInterval: waitOptions?.intervalSeconds
+          ? waitOptions.intervalSeconds * 1000
+          : undefined,
+        timeout: waitOptions?.timeoutSeconds ? waitOptions.timeoutSeconds * 1000 : undefined,
       });
     } catch (error) {
       if (error instanceof WaitForTransactionReceiptTimeoutError) {

package/actions/evm/transfer/smartAccountTransferStrategy.ts

@@ -2,16 +2,18 @@ import { encodeFunctionData, erc20Abi } from "viem";
 
 import { TransferExecutionStrategy } from "./types.js";
 import { getErc20Address } from "./utils.js";
-import { EvmSmartAccount } from "../../../accounts/types.js";
+import { EvmSmartAccount } from "../../../accounts/evm/types.js";
 import { sendUserOperation } from "../sendUserOperation.js";
 import { waitForUserOperation } from "../waitForUserOperation.js";
 
 export const smartAccountTransferStrategy: TransferExecutionStrategy<EvmSmartAccount> = {
-  executeTransfer: async ({ apiClient, from, transferArgs, to, value }) => {
+  executeTransfer: async ({ apiClient, from, to, value, token, network, paymasterUrl }) => {
     const userOpHash = await (async () => {
-      if (transferArgs.token === "eth") {
-        const result = await sendUserOperation(apiClient, from, {
-          network: transferArgs.network,
+      if (token === "eth") {
+        const result = await sendUserOperation(apiClient, {
+          smartAccount: from,
+          paymasterUrl,
+          network,
           calls: [
             {
               to,
@@ -22,10 +24,12 @@ export const smartAccountTransferStrategy: TransferExecutionStrategy<EvmSmartAcc
         });
         return result.userOpHash;
       } else {
-        const erc20Address = getErc20Address(transferArgs.token, transferArgs.network);
+        const erc20Address = getErc20Address(token, network);
 
-        const result = await sendUserOperation(apiClient, from, {
-          network: transferArgs.network,
+        const result = await sendUserOperation(apiClient, {
+          smartAccount: from,
+          paymasterUrl,
+          network,
           calls: [
             {
               to: erc20Address,
@@ -53,10 +57,11 @@ export const smartAccountTransferStrategy: TransferExecutionStrategy<EvmSmartAcc
     return userOpHash;
   },
 
-  waitForResult: async ({ apiClient, publicClient, from, hash }) => {
+  waitForResult: async ({ apiClient, publicClient, from, hash, waitOptions }) => {
     const result = await waitForUserOperation(apiClient, {
       smartAccountAddress: from.address,
       userOpHash: hash,
+      waitOptions,
     });
 
     if (result.status === "complete") {

package/actions/evm/transfer/transfer.ts

@@ -1,10 +1,16 @@
 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 { EvmAccount, EvmSmartAccount } from "../../../accounts/evm/types.js";
 import { CdpOpenApiClientType } from "../../../openapi-client/index.js";
 
+import type {
+  TransferResult,
+  TransferExecutionStrategy,
+  SmartAccountTransferOptions,
+  AccountTransferOptions,
+} from "./types.js";
+
 /**
  * Transfer an amount of a token from an account to another account.
  *
@@ -17,7 +23,7 @@ import { CdpOpenApiClientType } from "../../../openapi-client/index.js";
 export async function transfer<T extends EvmAccount | EvmSmartAccount>(
   apiClient: CdpOpenApiClientType,
   from: T,
-  transferArgs: TransferOptions,
+  transferArgs: T extends EvmSmartAccount ? SmartAccountTransferOptions : AccountTransferOptions,
   transferStrategy: TransferExecutionStrategy<T>,
 ): Promise<TransferResult> {
   const publicClient = createPublicClient<Transport, Chain>({
@@ -52,19 +58,24 @@ export async function transfer<T extends EvmAccount | EvmSmartAccount>(
     return parseUnits(transferArgs.amount, decimals);
   })();
 
-  const hash = await transferStrategy.executeTransfer({
+  const transfer = {
     apiClient,
     from,
-    transferArgs,
     to,
     value,
-  });
+    token: transferArgs.token,
+    network: transferArgs.network,
+    paymasterUrl: "paymasterUrl" in transferArgs ? transferArgs.paymasterUrl : undefined,
+  };
+
+  const hash = await transferStrategy.executeTransfer(transfer);
 
   const result = await transferStrategy.waitForResult({
     apiClient,
     publicClient,
     from,
     hash,
+    waitOptions: transferArgs.waitOptions,
   });
 
   return result;

package/actions/evm/transfer/types.ts

@@ -1,12 +1,22 @@
-import { Hex, TransactionReceipt, Address, PublicClient, Chain, Transport } from "viem";
+import {
+  Hex,
+  TransactionReceipt,
+  Address,
+  PublicClient,
+  Chain,
+  Transport,
+  WaitForTransactionReceiptParameters,
+} from "viem";
 
 import {
   CdpOpenApiClientType,
-  EvmAccount,
   EvmUserOperationNetwork,
   SendEvmTransactionBodyNetwork,
 } from "../../../openapi-client/index.js";
 
+import type { EvmAccount, EvmSmartAccount } from "../../../accounts/evm/types.js";
+import type { WaitForUserOperationOptions } from "../waitForUserOperation.js";
+
 /**
  * The network to transfer the token on.
  */
@@ -15,7 +25,7 @@ export type Network = SendEvmTransactionBodyNetwork | EvmUserOperationNetwork;
 /**
  * The options for the transfer.
  */
-export type TransferOptions = {
+type TransferOptions = {
   /** The account to transfer the token to. */
   to: EvmAccount | Address;
   /**
@@ -29,6 +39,33 @@ export type TransferOptions = {
   network: Network;
 };
 
+/**
+ * The options for the transfer using an account.
+ */
+export type AccountTransferOptions = TransferOptions & {
+  /** The options for waiting for the result of the transfer. */
+  waitOptions?: {
+    /**
+     * Polling frequency (in seconds). Defaults to 4 seconds.
+     */
+    intervalSeconds?: WaitForTransactionReceiptParameters["pollingInterval"];
+    /**
+     * Optional timeout (in seconds) to wait before stopping polling. Defaults to 180 seconds.
+     */
+    timeoutSeconds?: WaitForTransactionReceiptParameters["timeout"];
+  };
+};
+
+/**
+ * The options for the transfer using a smart account.
+ */
+export type SmartAccountTransferOptions = TransferOptions & {
+  /** The paymaster URL to use for the transfer. */
+  paymasterUrl?: string;
+  /** The options for waiting for the result of the transfer. */
+  waitOptions?: WaitForUserOperationOptions["waitOptions"];
+};
+
 /**
  * The result of the transfer.
  */
@@ -42,25 +79,29 @@ export type TransferResult = {
 /**
  * A strategy for executing a transfer.
  */
-export interface TransferExecutionStrategy<T> {
+export interface TransferExecutionStrategy<T extends EvmAccount | EvmSmartAccount> {
   /**
    * 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.
+   * @param args.token - The token to transfer.
+   * @param args.network - The network to transfer the token on.
    * @returns The transaction hash of the transfer.
    */
-  executeTransfer(args: {
-    apiClient: CdpOpenApiClientType;
-    from: T;
-    transferArgs: TransferOptions;
-    to: Address;
-    value: bigint;
-  }): Promise<Hex>;
+  executeTransfer(
+    args: {
+      apiClient: CdpOpenApiClientType;
+      from: T;
+      to: Address;
+      value: bigint;
+      token: TransferOptions["token"];
+      network: TransferOptions["network"];
+    } & (T extends EvmSmartAccount ? { paymasterUrl?: string } : object),
+  ): Promise<Hex>;
 
   /**
    * Waits for the result of the transfer.
@@ -70,6 +111,7 @@ export interface TransferExecutionStrategy<T> {
    * @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.
+   * @param args.waitOptions - The options for waiting for the result of the transfer.
    * @returns The result of the transfer.
    */
   waitForResult(args: {
@@ -77,5 +119,6 @@ export interface TransferExecutionStrategy<T> {
     publicClient: PublicClient<Transport, Chain>;
     from: T;
     hash: Hex;
+    waitOptions?: WaitForUserOperationOptions["waitOptions"];
   }): Promise<TransferResult>;
 }