@coinbase/cdp-sdk 1.4.0 → 1.6.0

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,244 @@
+import { SendUserOperationReturnType, SendUserOperationOptions } from "./sendUserOperation.js";
+
+import type { ListTokenBalancesResult, ListTokenBalancesOptions } from "./listTokenBalances.js";
+import type { RequestFaucetOptions, RequestFaucetResult } from "./requestFaucet.js";
+import type { SendTransactionOptions, TransactionResult } from "./sendTransaction.js";
+import type { TransferOptions, TransferResult } from "./transfer/types.js";
+import type {
+  WaitForUserOperationOptions,
+  WaitForUserOperationReturnType,
+} from "./waitForUserOperation.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>;
+
+  /**
+   * 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>;
+
+  /**
+   * 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>;
+
+  /**
+   * 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>;
+};

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,24 +20,38 @@ 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 {
+  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 {
   waitForUserOperation,
   WaitForUserOperationReturnType,
 } from "../../actions/evm/waitForUserOperation.js";
+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.
  */
@@ -145,7 +156,7 @@ export class EvmClient implements EvmClientInterface {
       options.idempotencyKey,
     );
 
-    return toEvmSmartAccount({
+    return toEvmSmartAccount(CdpOpenApiClient, {
       smartAccount,
       owner: options.owner,
     });
@@ -216,12 +227,53 @@ export class EvmClient implements EvmClientInterface {
   async getSmartAccount(options: GetSmartAccountOptions): Promise<SmartAccount> {
     const smartAccount = await CdpOpenApiClient.getEvmSmartAccount(options.address);
 
-    return toEvmSmartAccount({
+    return toEvmSmartAccount(CdpOpenApiClient, {
       smartAccount,
       owner: options.owner,
     });
   }
 
+  /**
+   * Gets a CDP EVM account, or creates one if it doesn't exist.
+   *
+   * @param {GetOrCreateServerAccountOptions} options - Parameters for getting or creating the account.
+   * @param {string} [options.name] - The name of the account to get or create.
+   *
+   * @returns A promise that resolves to the account.
+   *
+   * @example
+   * ```ts
+   * const account = await cdp.evm.getOrCreateAccount({
+   *   name: "MyAccount",
+   * });
+   * ```
+   */
+  async getOrCreateAccount(options: GetOrCreateServerAccountOptions): Promise<ServerAccount> {
+    try {
+      const account = await this.getAccount(options);
+      return account;
+    } catch (error) {
+      // If it failed because the account doesn't exist, create it
+      const doesAccountNotExist = error instanceof APIError && error.statusCode === 404;
+      if (doesAccountNotExist) {
+        try {
+          const account = await this.createAccount(options);
+          return account;
+        } catch (error) {
+          // If it failed because the account already exists, throw an error
+          const doesAccountAlreadyExist = error instanceof APIError && error.statusCode === 409;
+          if (doesAccountAlreadyExist) {
+            const account = await this.getAccount(options);
+            return account;
+          }
+          throw error;
+        }
+      }
+
+      throw error;
+    }
+  }
+
   /**
    * Gets a user operation for a smart account by user operation hash.
    *
@@ -333,28 +385,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);
   }
 
   /**
@@ -466,14 +497,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);
   }
 
   /**
@@ -523,27 +547,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);
   }
 
   /**
@@ -574,8 +578,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,