@coinbase/cdp-sdk 1.4.0 → 1.5.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,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/client/evm/evm.ts

@@ -27,6 +27,7 @@ import {
   ListTokenBalancesResult,
   SendTransactionOptions,
   TransactionResult,
+  GetOrCreateServerAccountOptions,
 } from "./evm.types.js";
 import { toEvmServerAccount } from "../../accounts/evm/toEvmServerAccount.js";
 import { toEvmSmartAccount } from "../../accounts/evm/toEvmSmartAccount.js";
@@ -38,6 +39,7 @@ 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";
 
@@ -145,7 +147,7 @@ export class EvmClient implements EvmClientInterface {
       options.idempotencyKey,
     );
 
-    return toEvmSmartAccount({
+    return toEvmSmartAccount(CdpOpenApiClient, {
       smartAccount,
       owner: options.owner,
     });
@@ -216,12 +218,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.
    *

package/client/evm/evm.types.ts

@@ -4,6 +4,7 @@ import {
   EvmSmartAccount as SmartAccount,
 } from "../../accounts/types.js";
 import { SendUserOperationReturnType } from "../../actions/evm/sendUserOperation.js";
+import { Actions } from "../../actions/evm/types.js";
 import {
   EvmUserOperationNetwork,
   EvmUserOperationStatus,
@@ -41,6 +42,7 @@ export type EvmClientInterface = Omit<
   createSmartAccount: (options: CreateSmartAccountOptions) => Promise<SmartAccount>;
   getAccount: (options: GetServerAccountOptions) => Promise<ServerAccount>;
   getSmartAccount: (options: GetSmartAccountOptions) => Promise<SmartAccount>;
+  getOrCreateAccount: (options: GetOrCreateServerAccountOptions) => Promise<ServerAccount>;
   getUserOperation: (options: GetUserOperationOptions) => Promise<UserOperation>;
   listAccounts: (options: ListServerAccountsOptions) => Promise<ListServerAccountResult>;
   listSmartAccounts: (options: ListSmartAccountsOptions) => Promise<ListSmartAccountResult>;
@@ -146,6 +148,14 @@ export interface GetSmartAccountOptions {
   owner: Account;
 }
 
+/**
+ * Options for getting an EVM account, or creating one if it doesn't exist.
+ */
+export interface GetOrCreateServerAccountOptions {
+  /** The name of the account. */
+  name: string;
+}
+
 /**
  * Options for listing EVM accounts.
  */
@@ -159,7 +169,7 @@ export interface ListServerAccountsOptions {
 /**
  * A smart account that only contains the owner address.
  */
-export interface ReadonlySmartAccount extends Omit<SmartAccount, "owners"> {
+export interface ReadonlySmartAccount extends Omit<SmartAccount, "owners" | keyof Actions> {
   /** The owners of the smart account. */
   owners: Address[];
 }

package/client/solana/solana.ts

@@ -9,7 +9,9 @@ import {
   SignatureResult,
   SignMessageOptions,
   SignTransactionOptions,
+  GetOrCreateAccountOptions,
 } from "./solana.types.js";
+import { APIError } from "../../openapi-client/errors.js";
 import { CdpOpenApiClient } from "../../openapi-client/index.js";
 
 /**
@@ -87,6 +89,47 @@ export class SolanaClient implements SolanaClientInterface {
     throw new Error("Either address or name must be provided");
   }
 
+  /**
+   * Gets a Solana account by its address.
+   *
+   * @param {GetOrCreateAccountOptions} options - Parameters for getting or creating the Solana account.
+   * @param {string} options.name - The name of the account.
+   *
+   * @returns A promise that resolves to the account.
+   *
+   * @example
+   * ```ts
+   * const account = await cdp.solana.getOrCreateAccount({
+   *   name: "MyAccount",
+   * });
+   * ```
+   */
+  async getOrCreateAccount(options: GetOrCreateAccountOptions): Promise<Account> {
+    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;
+    }
+  }
+
   /**
    * Lists all Solana accounts.
    *

package/client/solana/solana.types.ts

@@ -17,6 +17,7 @@ export type SolanaClientInterface = Omit<
 > & {
   createAccount: (options: CreateAccountOptions) => Promise<Account>;
   getAccount: (options: GetAccountOptions) => Promise<Account>;
+  getOrCreateAccount: (options: GetOrCreateAccountOptions) => Promise<Account>;
   listAccounts: (options: ListAccountsOptions) => Promise<ListAccountsResult>;
   requestFaucet: (options: RequestFaucetOptions) => Promise<SignatureResult>;
   signMessage: (options: SignMessageOptions) => Promise<SignatureResult>;
@@ -47,6 +48,14 @@ export interface GetAccountOptions {
   name?: string;
 }
 
+/**
+ * Options for getting a Solana account.
+ */
+export interface GetOrCreateAccountOptions {
+  /** The name of the account. */
+  name: string;
+}
+
 /**
  * Options for listing Solana accounts.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cdp-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "SDK for interacting with the Coinbase Developer Platform Wallet API",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",

package/utils/serializeTransaction.ts

@@ -0,0 +1,17 @@
+import { serializeTransaction } from "viem";
+
+import { TransactionRequestEIP1559 } from "../types/misc.js";
+
+/**
+ * Serializes a transaction for the Coinbase API.
+ *
+ * @param transaction - The transaction to serialize.
+ * @returns The serialized transaction.
+ */
+export function serializeEIP1559Transaction(transaction: TransactionRequestEIP1559) {
+  return serializeTransaction({
+    ...transaction,
+    chainId: 1, // ignored by Coinbase API
+    type: "eip1559",
+  });
+}

package/version.ts

@@ -1 +1 @@
-export const version = "1.4.0";
+export const version = "1.5.0";