@coinbase/cdp-sdk 1.4.0 → 1.6.0

package/accounts/evm/toEvmServerAccount.ts

@@ -1,9 +1,24 @@
-import { serializeTransaction, TransactionSerializable } from "viem";
+import { type Hex, type TransactionSerializable, serializeTransaction } from "viem";
 
-import { CdpOpenApiClientType, EvmAccount } from "../../openapi-client/index.js";
-import { EvmServerAccount } from "../types.js";
+import {
+  listTokenBalances,
+  type ListTokenBalancesResult,
+  type ListTokenBalancesOptions,
+} from "../../actions/evm/listTokenBalances.js";
+import {
+  requestFaucet,
+  type RequestFaucetOptions,
+  type RequestFaucetResult,
+} from "../../actions/evm/requestFaucet.js";
+import { sendTransaction } from "../../actions/evm/sendTransaction.js";
+import { accountTransferStrategy } from "../../actions/evm/transfer/accountTransferStrategy.js";
+import { transfer } from "../../actions/evm/transfer/transfer.js";
 
+import type { SendTransactionOptions } from "../../actions/evm/sendTransaction.js";
+import type { TransferResult } from "../../actions/evm/transfer/types.js";
+import type { CdpOpenApiClientType, EvmAccount } from "../../openapi-client/index.js";
 import type { Address, Hash } from "../../types/misc.js";
+import type { EvmServerAccount } from "../types.js";
 
 /**
  * Options for converting a pre-existing EvmAccount to a EvmServerAccount.
@@ -32,26 +47,51 @@ export function toEvmServerAccount(
       const result = await apiClient.signEvmMessage(options.account.address, {
         message: message.toString(),
       });
-      return result.signature as `0x${string}`;
+      return result.signature as Hex;
     },
 
     async sign(parameters: { hash: Hash }) {
       const result = await apiClient.signEvmHash(options.account.address, {
         hash: parameters.hash,
       });
-      return result.signature as `0x${string}`;
+      return result.signature as Hex;
     },
 
     async signTransaction(transaction: TransactionSerializable) {
       const result = await apiClient.signEvmTransaction(options.account.address, {
         transaction: serializeTransaction(transaction),
       });
-      return result.signedTransaction as `0x${string}`;
+      return result.signedTransaction as Hex;
     },
 
     async signTypedData() {
       throw new Error("Not implemented");
     },
+    async transfer(transferArgs): Promise<TransferResult> {
+      return transfer(apiClient, account, transferArgs, accountTransferStrategy);
+    },
+    async listTokenBalances(
+      options: Omit<ListTokenBalancesOptions, "address">,
+    ): Promise<ListTokenBalancesResult> {
+      return listTokenBalances(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async requestFaucet(
+      options: Omit<RequestFaucetOptions, "address">,
+    ): Promise<RequestFaucetResult> {
+      return requestFaucet(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async sendTransaction(options: Omit<SendTransactionOptions, "address">) {
+      return sendTransaction(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
     name: options.account.name,
     type: "evm-server",
   };

package/accounts/evm/toEvmSmartAccount.ts

@@ -1,7 +1,33 @@
-import { EvmSmartAccount as EvmSmartAccountModel } from "../../openapi-client/index.js";
-import { EvmAccount, EvmSmartAccount } from "../types.js";
+import {
+  listTokenBalances,
+  type ListTokenBalancesOptions,
+  type ListTokenBalancesResult,
+} from "../../actions/evm/listTokenBalances.js";
+import {
+  RequestFaucetResult,
+  RequestFaucetOptions,
+  requestFaucet,
+} from "../../actions/evm/requestFaucet.js";
+import {
+  type SendUserOperationOptions,
+  type SendUserOperationReturnType,
+  sendUserOperation,
+} from "../../actions/evm/sendUserOperation.js";
+import { smartAccountTransferStrategy } from "../../actions/evm/transfer/smartAccountTransferStrategy.js";
+import { transfer } from "../../actions/evm/transfer/transfer.js";
+import {
+  waitForUserOperation,
+  WaitForUserOperationOptions,
+  WaitForUserOperationReturnType,
+} from "../../actions/evm/waitForUserOperation.js";
 
+import type { TransferResult } from "../../actions/evm/transfer/types.js";
+import type {
+  CdpOpenApiClientType,
+  EvmSmartAccount as EvmSmartAccountModel,
+} from "../../openapi-client/index.js";
 import type { Address } from "../../types/misc.js";
+import type { EvmAccount, EvmSmartAccount } from "../types.js";
 
 /**
  * Options for converting a pre-existing EvmSmartAccount and owner to a EvmSmartAccount
@@ -19,16 +45,54 @@ export type ToEvmSmartAccountOptions = {
  *
  * The owner must be the original owner of the evm smart account.
  *
+ * @param {CdpOpenApiClientType} apiClient - The API client.
  * @param {ToEvmSmartAccountOptions} options - Configuration options.
  * @param {EvmSmartAccount} options.smartAccount - The deployed evm smart account.
  * @param {EvmAccount} options.owner - The owner which signs for the smart account.
  * @returns {EvmSmartAccount} A configured EvmSmartAccount instance ready for user operation submission.
- * @throws {Error} If the account is not an original owner of the smart account.
  */
-export function toEvmSmartAccount(options: ToEvmSmartAccountOptions): EvmSmartAccount {
+export function toEvmSmartAccount(
+  apiClient: CdpOpenApiClientType,
+  options: ToEvmSmartAccountOptions,
+): EvmSmartAccount {
   const account: EvmSmartAccount = {
     address: options.smartAccount.address as Address,
     owners: [options.owner],
+    async transfer(transferArgs): Promise<TransferResult> {
+      return transfer(apiClient, account, transferArgs, smartAccountTransferStrategy);
+    },
+    async listTokenBalances(
+      options: Omit<ListTokenBalancesOptions, "address">,
+    ): Promise<ListTokenBalancesResult> {
+      return listTokenBalances(apiClient, {
+        ...options,
+        address: this.address,
+      });
+    },
+    async sendUserOperation(
+      options: Omit<SendUserOperationOptions<unknown[]>, "smartAccount">,
+    ): Promise<SendUserOperationReturnType> {
+      return sendUserOperation(apiClient, {
+        ...options,
+        smartAccount: account,
+      });
+    },
+    async waitForUserOperation(
+      options: Omit<WaitForUserOperationOptions, "smartAccountAddress">,
+    ): Promise<WaitForUserOperationReturnType> {
+      return waitForUserOperation(apiClient, {
+        ...options,
+        smartAccountAddress: account.address,
+      });
+    },
+    async requestFaucet(
+      options: Omit<RequestFaucetOptions, "address">,
+    ): Promise<RequestFaucetResult> {
+      return requestFaucet(apiClient, {
+        ...options,
+        address: account.address,
+      });
+    },
     name: options.smartAccount.name,
     type: "evm-smart",
   };

package/accounts/types.ts

@@ -1,5 +1,6 @@
 import { SignableMessage, TransactionSerializable, TypedData, TypedDataDefinition } from "viem";
 
+import { Actions } from "../actions/evm/types.js";
 import { Prettify } from "../types/utils.js";
 
 import type { Hash, Hex, Address } from "../types/misc.js";
@@ -30,24 +31,27 @@ export type EvmAccount = {
  * Server-managed ethereum account
  */
 export type EvmServerAccount = Prettify<
-  EvmAccount & {
-    /** Optional name for the server account. */
-    name?: string;
-    /** Indicates this is a server-managed account. */
-    type: "evm-server";
-  }
+  EvmAccount &
+    Omit<Actions, "sendUserOperation" | "waitForUserOperation"> & {
+      /** Optional name for the server account. */
+      name?: string;
+      /** Indicates this is a server-managed account. */
+      type: "evm-server";
+    }
 >;
 
 /**
  * Ethereum smart account which supports account abstraction features like user operations, batch transactions, and paymaster.
  */
-export type EvmSmartAccount = {
-  /** The smart account's address. */
-  address: Address;
-  /** The name of the smart account. */
-  name?: string;
-  /** Array of accounts that own and can sign for the smart account (currently only supports one owner but will be extended to support multiple owners in the future). */
-  owners: EvmAccount[];
-  /** Identifier for the smart account type. */
-  type: "evm-smart";
-};
+export type EvmSmartAccount = Prettify<
+  {
+    /** The smart account's address. */
+    address: Address;
+    /** The name of the smart account. */
+    name?: string;
+    /** Array of accounts that own and can sign for the smart account (currently only supports one owner but will be extended to support multiple owners in the future). */
+    owners: EvmAccount[];
+    /** Identifier for the smart account type. */
+    type: "evm-smart";
+  } & Omit<Actions, "sendTransaction">
+>;

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

@@ -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

@@ -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,72 @@
+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, {
+          smartAccount: 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, {
+          smartAccount: 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}`,
+      );
+    }
+  },
+};