@coinbase/cdp-sdk 1.7.0 → 1.9.0

package/actions/evm/transfer/utils.ts

@@ -1,5 +1,3 @@
-import { base, baseSepolia } from "viem/chains";
-
 import { Network } from "./types.js";
 
 /**
@@ -26,14 +24,3 @@ const addressMap = {
 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

@@ -1,63 +1,89 @@
 import { SendUserOperationOptions, SendUserOperationReturnType } from "./sendUserOperation.js";
 import { GetUserOperationOptions, UserOperation } from "../../client/evm/evm.types.js";
-import { EvmAccount, EvmSmartAccount } from "../../openapi-client/index.js";
+import { Hex } from "../../types/misc.js";
 
 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 { TransferOptions } from "./transfer/types.js";
 import type {
   WaitForUserOperationOptions,
   WaitForUserOperationReturnType,
 } from "./waitForUserOperation.js";
 
-type Actions<T extends EvmAccount | EvmSmartAccount> = {
+type Actions = {
   /**
-   * Transfer an amount of a token from an account to another account.
+   * List the token balances of an 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.
+   * @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 transfer.
+   * @returns The result of the list token balances.
    *
    * @example
    * ```typescript
-   * const { status } = await sender.transfer({
-   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
-   *   amount: "0.01",
-   *   token: "usdc",
+   * 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 & {
+  /**
+   * 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 represented as an atomic unit.
+   * It's common to use `parseEther` or `parseUnits` utils from viem to convert to atomic units.
+   * Otherwise, you can pass atomic units directly. See examples below.
+   * @param options.token - The token to transfer. This can be 'eth', 'usdc', or a contract address.
+   * @param options.network - The network to transfer the token on.
+   *
+   * @returns An object containing the transaction hash.
    *
    * @example
-   * **Pass a bigint value**
    * ```typescript
-   * const { status } = await sender.transfer({
+   * const { transactionHash } = await sender.transfer({
    *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
-   *   amount: 10000n, // equivalent to 0.01 usdc
+   *   amount: 10000n, // equivalent to 0.01 USDC
    *   token: "usdc",
    *   network: "base-sepolia",
    * });
    * ```
    *
    * @example
-   * **Transfer from a smart account**
+   * **Using parseUnits to specify USDC amount**
    * ```typescript
-   * const sender = await cdp.evm.createSmartAccount({
-   *   owner: await cdp.evm.createAccount({ name: "Owner" }),
-   * });
+   * import { parseUnits } from "viem";
    *
-   * const { status } = await sender.transfer({
+   * const { transactionHash } = await sender.transfer({
    *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
-   *   amount: "0.01",
+   *   amount: parseUnits("0.01", 6), // USDC uses 6 decimal places
    *   token: "usdc",
    *   network: "base-sepolia",
    * });
@@ -66,9 +92,11 @@ type Actions<T extends EvmAccount | EvmSmartAccount> = {
    * @example
    * **Transfer ETH**
    * ```typescript
-   * const { status } = await sender.transfer({
+   * import { parseEther } from "viem";
+   *
+   * const { transactionHash } = await sender.transfer({
    *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
-   *   amount: "0.000001",
+   *   amount: parseEther("0.000001"),
    *   token: "eth",
    *   network: "base-sepolia",
    * });
@@ -77,9 +105,11 @@ type Actions<T extends EvmAccount | EvmSmartAccount> = {
    * @example
    * **Using a contract address**
    * ```typescript
-   * const { status } = await sender.transfer({
+   * import { parseEther } from "viem";
+   *
+   * const { transactionHash } = await sender.transfer({
    *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
-   *   amount: "0.000001",
+   *   amount: parseEther("0.000001"),
    *   token: "0x4200000000000000000000000000000000000006", // WETH on Base Sepolia
    *   network: "base-sepolia",
    * });
@@ -91,59 +121,16 @@ type Actions<T extends EvmAccount | EvmSmartAccount> = {
    * const sender = await cdp.evm.createAccount({ name: "Sender" });
    * const receiver = await cdp.evm.createAccount({ name: "Receiver" });
    *
-   * const { status } = await sender.transfer({
+   * const { transactionHash } = await sender.transfer({
    *   to: receiver,
-   *   amount: "0.01",
+   *   amount: 10000n, // equivalent to 0.01 USDC
    *   token: "usdc",
    *   network: "base-sepolia",
    * });
    * ```
    */
-  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>;
-};
+  transfer: (options: TransferOptions) => Promise<{ transactionHash: Hex }>;
 
-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.
@@ -191,7 +178,85 @@ export type AccountActions = Actions<EvmAccount> & {
   sendTransaction: (options: Omit<SendTransactionOptions, "address">) => Promise<TransactionResult>;
 };
 
-export type SmartAccountActions = Actions<EvmSmartAccount> & {
+export type SmartAccountActions = 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 represented as an atomic unit.
+   * It's common to use `parseEther` or `parseUnits` utils from viem to convert to atomic units.
+   * Otherwise, you can pass atomic units directly. See examples below.
+   * @param options.token - The token to transfer. This can be 'eth', 'usdc', or a contract address.
+   * @param options.network - The network to transfer the token on.
+   *
+   * @returns The user operation result.
+   *
+   * @example
+   * ```typescript
+   * const { userOpHash } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: 10000n, // equivalent to 0.01 USDC
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Using parseUnits to specify USDC amount**
+   * ```typescript
+   * import { parseUnits } from "viem";
+   *
+   * const { userOpHash } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: parseUnits("0.01", 6), // USDC uses 6 decimal places
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Transfer ETH**
+   * ```typescript
+   * import { parseEther } from "viem";
+   *
+   * const { userOpHash } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: parseEther("0.000001"),
+   *   token: "eth",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   *
+   * @example
+   * **Using a contract address**
+   * ```typescript
+   * import { parseEther } from "viem";
+   *
+   * const { userOpHash } = await sender.transfer({
+   *   to: "0x9F663335Cd6Ad02a37B633602E98866CF944124d",
+   *   amount: parseEther("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 { userOpHash } = await sender.transfer({
+   *   to: receiver,
+   *   amount: 10000n, // equivalent to 0.01 USDC
+   *   token: "usdc",
+   *   network: "base-sepolia",
+   * });
+   * ```
+   */
+  transfer: (options: TransferOptions) => Promise<SendUserOperationReturnType>;
+
   /**
    * Sends a user operation.
    *

package/actions/solana/constants.ts

@@ -0,0 +1,6 @@
+export const GENESIS_HASH_MAINNET = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
+export const GENESIS_HASH_DEVNET = "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG";
+export const GENESIS_HASH_TESTNET = "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY";
+
+export const USDC_MAINNET_MINT_ADDRESS = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export const USDC_DEVNET_MINT_ADDRESS = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";

package/actions/solana/transfer.ts

@@ -0,0 +1,219 @@
+import {
+  getMint,
+  getAssociatedTokenAddress,
+  getAccount,
+  createAssociatedTokenAccountInstruction,
+  createTransferCheckedInstruction,
+} from "@solana/spl-token";
+import {
+  Connection,
+  MessageV0,
+  PublicKey,
+  SystemProgram,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedTransaction,
+} from "@solana/web3.js";
+
+import {
+  getConnectedNetwork,
+  getOrCreateConnection,
+  getUsdcMintAddress,
+  type Network,
+} from "./utils.js";
+
+import type { SignatureResult } from "../../client/solana/solana.types.js";
+import type { CdpOpenApiClientType } from "../../openapi-client/index.js";
+
+export interface TransferOptions {
+  /**
+   * The base58 encoded Solana address of the source account.
+   */
+  from: string;
+  /**
+   * The base58 encoded Solana address of the destination account.
+   */
+  to: string;
+  /**
+   * The amount to transfer, represented as an atomic unit of the token.
+   */
+  amount: bigint;
+  /**
+   * The token to transfer, or mint address of the SPL token to transfer.
+   */
+  token: "sol" | "usdc" | string;
+  /**
+   * The network to use which will be used to create a Connection, otherwise a Connection can be provided.
+   */
+  network: Network | Connection;
+}
+
+/**
+ * Transfers SOL or SPL tokens between accounts
+ *
+ * @param apiClient - The API client to use
+ * @param options - The transfer options
+ *
+ * @returns The transfer result
+ */
+export async function transfer(
+  apiClient: CdpOpenApiClientType,
+  options: TransferOptions,
+): Promise<SignatureResult> {
+  const connection = getOrCreateConnection({ networkOrConnection: options.network });
+
+  const tx =
+    options.token === "sol"
+      ? await getNativeTransfer({
+          connection,
+          from: options.from,
+          to: options.to,
+          amount: options.amount,
+        })
+      : await getSplTransfer({
+          connection,
+          from: options.from,
+          to: options.to,
+          mintAddress:
+            options.token === "usdc"
+              ? getUsdcMintAddress(await getConnectedNetwork(connection))
+              : options.token,
+          amount: options.amount,
+        });
+
+  const serializedTx = Buffer.from(tx.serialize()).toString("base64");
+
+  const signedTxResponse = await apiClient.signSolanaTransaction(options.from, {
+    transaction: serializedTx,
+  });
+
+  const decodedSignedTx = Buffer.from(signedTxResponse.signedTransaction, "base64");
+
+  const signature = await connection.sendRawTransaction(decodedSignedTx, {
+    skipPreflight: false,
+    maxRetries: 3,
+  });
+
+  return { signature };
+}
+
+type GetNativeTransferOptions = Omit<TransferOptions, "token" | "network"> & {
+  /**
+   * The connection to the Solana network
+   */
+  connection: Connection;
+};
+
+/**
+ * Gets the instructions for a native SOL transfer
+ *
+ * @param options - The options for the native SOL transfer
+ *
+ * @param options.connection - The Solana connection
+ * @param options.from - The source address
+ * @param options.to - The destination address
+ * @param options.amount - The amount to transfer
+ *
+ * @returns The native SOL transfer transaction
+ */
+async function getNativeTransfer({
+  connection,
+  from,
+  to,
+  amount,
+}: GetNativeTransferOptions): Promise<VersionedTransaction> {
+  const { blockhash } = await connection.getLatestBlockhash();
+
+  const instructions = [
+    SystemProgram.transfer({
+      fromPubkey: new PublicKey(from),
+      toPubkey: new PublicKey(to),
+      lamports: amount,
+    }),
+  ];
+
+  const messageV0 = new TransactionMessage({
+    payerKey: new PublicKey(from),
+    recentBlockhash: blockhash,
+    instructions,
+  }).compileToV0Message();
+
+  return new VersionedTransaction(messageV0);
+}
+
+type GetSplTransferOptions = GetNativeTransferOptions & {
+  /**
+   * The mint address of the token
+   */
+  mintAddress: string;
+};
+
+/**
+ * Gets the instructions for a SPL token transfer
+ *
+ * @param options - The options for the SPL token transfer
+ *
+ * @param options.connection - The Solana connection
+ * @param options.from - The source address
+ * @param options.to - The destination address
+ * @param options.mintAddress - The mint address of the token
+ * @param options.amount - The amount to transfer
+ *
+ * @returns The SPL token transfer transaction
+ */
+async function getSplTransfer({
+  connection,
+  from,
+  to,
+  mintAddress,
+  amount,
+}: GetSplTransferOptions): Promise<VersionedTransaction> {
+  const fromPubkey = new PublicKey(from);
+  const toPubkey = new PublicKey(to);
+  const mintPubkey = new PublicKey(mintAddress);
+
+  let mintInfo: Awaited<ReturnType<typeof getMint>>;
+  try {
+    mintInfo = await getMint(connection, mintPubkey);
+  } catch (error) {
+    throw new Error(`Failed to fetch mint info for mint address ${mintAddress}. Error: ${error}`);
+  }
+
+  const sourceAta = await getAssociatedTokenAddress(mintPubkey, fromPubkey);
+  const destinationAta = await getAssociatedTokenAddress(mintPubkey, toPubkey);
+
+  const instructions: TransactionInstruction[] = [];
+
+  const sourceAccount = await getAccount(connection, sourceAta);
+  if (sourceAccount.amount < amount) {
+    throw new Error(`Insufficient token balance. Have ${sourceAccount.amount}, need ${amount}`);
+  }
+
+  // Check if destination account exists, if not create it
+  try {
+    await getAccount(connection, destinationAta);
+  } catch {
+    instructions.push(
+      createAssociatedTokenAccountInstruction(fromPubkey, destinationAta, toPubkey, mintPubkey),
+    );
+  }
+
+  instructions.push(
+    createTransferCheckedInstruction(
+      sourceAta,
+      mintPubkey,
+      destinationAta,
+      fromPubkey,
+      amount,
+      mintInfo.decimals,
+    ),
+  );
+
+  return new VersionedTransaction(
+    MessageV0.compile({
+      payerKey: fromPubkey,
+      instructions: instructions,
+      recentBlockhash: (await connection.getLatestBlockhash()).blockhash,
+    }),
+  );
+}

package/actions/solana/types.ts

@@ -1,3 +1,4 @@
+import { TransferOptions } from "./transfer.js";
 import {
   RequestFaucetOptions,
   SignatureResult,
@@ -84,4 +85,31 @@ export type AccountActions = {
    * ```
    */
   signTransaction: (options: Omit<SignTransactionOptions, "address">) => Promise<SignatureResult>;
+
+  /**
+   * Transfers SOL or SPL tokens between accounts
+   *
+   * @param {TransferOptions} options - Parameters for the transfer.
+   * @param {string} options.to - The base58 encoded Solana address of the destination account.
+   * @param {sol|usdc|string} options.token - The token to transfer ("sol" or "usdc"), or mint address of the SPL token to transfer.
+   * @param {bigint} options.amount - The amount to transfer in atomic units of the token. For example, 0.01 * LAMPORTS_PER_SOL would transfer 0.01 SOL.
+   * @param {string | Connection} options.network - The network identifier to use, or a Solana Connection object.
+   *
+   * @returns A promise that resolves to the transaction signature, which can be used to wait for the transaction result.
+   *
+   * @example
+   * ```ts
+   * import { LAMPORTS_PER_SOL } from "@solana/web3.js";
+   *
+   * const account = await cdp.solana.getAccount({ name: "Account" });
+   *
+   * const { signature } = await account.transfer({
+   *   token: "sol",
+   *   amount: 5 * LAMPORTS_PER_SOL,
+   *   to: "3KzDtddx4i53FBkvCzuDmRbaMozTZoJBb1TToWhz3JfE",
+   *   network: "devnet",
+   * });
+   * ```
+   */
+  transfer: (options: Omit<TransferOptions, "from">) => Promise<SignatureResult>;
 };

package/actions/solana/utils.ts

@@ -0,0 +1,79 @@
+import { Connection } from "@solana/web3.js";
+
+import {
+  GENESIS_HASH_MAINNET,
+  GENESIS_HASH_TESTNET,
+  GENESIS_HASH_DEVNET,
+  USDC_MAINNET_MINT_ADDRESS,
+  USDC_DEVNET_MINT_ADDRESS,
+} from "./constants.js";
+
+export type Network = "mainnet" | "devnet" | "testnet";
+
+type GetOrCreateConnectionOptions = {
+  networkOrConnection: Network | Connection;
+};
+
+/**
+ * Get a connection to the Solana network
+ *
+ * @param options - The options for the connection
+ *
+ * @param options.networkOrConnection - The network to use or a connection
+ *
+ * @returns The connection
+ */
+export function getOrCreateConnection({
+  networkOrConnection,
+}: GetOrCreateConnectionOptions): Connection {
+  if (typeof networkOrConnection !== "string") {
+    return networkOrConnection;
+  }
+
+  return new Connection(
+    networkOrConnection === "mainnet"
+      ? "https://api.mainnet-beta.solana.com"
+      : networkOrConnection === "devnet"
+        ? "https://api.devnet.solana.com"
+        : "https://api.testnet.solana.com",
+  );
+}
+
+/**
+ * Get the network of the connected Solana node
+ *
+ * @param connection - The connection to the Solana network
+ * @throws {Error} If the network is not mainnet, devnet, or testnet
+ *
+ * @returns The network of the connected Solana node
+ */
+export async function getConnectedNetwork(connection: Connection): Promise<Network> {
+  const genesisHash = await connection.getGenesisHash();
+
+  if (genesisHash === GENESIS_HASH_MAINNET) {
+    return "mainnet";
+  } else if (genesisHash === GENESIS_HASH_DEVNET) {
+    return "devnet";
+  } else if (genesisHash === GENESIS_HASH_TESTNET) {
+    return "testnet";
+  }
+
+  throw new Error("Unknown network");
+}
+
+/**
+ * Get the USDC mint address for the given connection
+ *
+ * @param network - The network to use
+ *
+ * @returns The USDC mint address
+ */
+export function getUsdcMintAddress(network: Network): string {
+  if (network === "mainnet") {
+    return USDC_MAINNET_MINT_ADDRESS;
+  } else if (network === "devnet") {
+    return USDC_DEVNET_MINT_ADDRESS;
+  } else {
+    throw new Error("Testnet is not supported for USDC");
+  }
+}