@aa-sdk/core 4.0.0-alpha.0 → 4.0.0-alpha.10

package/src/actions/smartAccount/sendTransaction.ts

@@ -20,6 +20,30 @@ import { _sendUserOperation } from "./internal/sendUserOperation.js";
 import type { UserOperationContext } from "./types.js";
 import { waitForUserOperationTransaction } from "./waitForUserOperationTransacation.js";
 
+/**
+ * Sends a transaction using the provided client, arguments, optional overrides, and context.
+ * This sends a UO and then waits for it to be mined
+ *
+ * @example
+ * ```ts
+ * import { createSmartAccountClient } from "@aa-sdk/core";
+ *
+ * // smart account client is already extended with sendTransaction
+ * const client = createSmartAccountClient(...);
+ * const result = await client.sendTransaction({
+ *  to: "0x...",
+ *  data: "0x...", // or "0x",
+ *  value: 0n, // optional
+ *  account, // only required if the client above is not connected to an account
+ * });
+ * ```
+ *
+ * @param {Client<Transport, TChain, TAccount>} client The client to send the transaction through
+ * @param {SendTransactionParameters<TChain, TAccount, TChainOverride>} args The parameters required to send the transaction
+ * @param {UserOperationOverrides<TEntryPointVersion>} [overrides] Optional overrides for the user operation
+ * @param {UserOperationContext} [context] Optional context for the user operation
+ * @returns {Promise<Hex>} A promise that resolves to a hex string representing the transaction hash
+ */
 export async function sendTransaction<
   TChain extends Chain | undefined = Chain | undefined,
   TAccount extends SmartContractAccount | undefined =

package/src/actions/smartAccount/sendTransactions.ts

@@ -9,6 +9,29 @@ import { _sendUserOperation } from "./internal/sendUserOperation.js";
 import type { SendTransactionsParameters, UserOperationContext } from "./types";
 import { waitForUserOperationTransaction } from "./waitForUserOperationTransacation.js";
 
+/**
+ * Sends transactions using the provided client and transaction parameters. This function builds user operations from the transactions, sends them, and waits for the transaction to be mined.
+ *
+ * @example
+ * ```ts
+ * import { createSmartAccountClient } from "@aa-sdk/core";
+ *
+ * // smart account client is already extended with sendTransactions
+ * const client = createSmartAccountClient(...);
+ * const result = await client.sendTransactions({
+ *  requests: [{
+ *    to: "0x...",
+ *    data: "0x...", // or "0x",
+ *    value: 0n, // optional
+ *  }],
+ *  account, // only required if the client above is not connected to an account
+ * });
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client used to send the transactions
+ * @param {SendTransactionsParameters<TAccount, TContext>} args The parameters for sending the transactions, including requests, overrides, account, and context
+ * @returns {Promise<Hex>} A promise that resolves to the transaction hash of the sent transactions
+ */
 export async function sendTransactions<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,

package/src/actions/smartAccount/sendUserOperation.ts

@@ -17,9 +17,23 @@ import type {
 /**
  * Sends a user operation or batch of user operations using the connected account. Before executing, sendUserOperation will run the user operation through the middleware pipeline.
  *
- * @param client the smart account client to use for RPC requests
- * @param args {@link SendUserOperationParameters} containg the UO or batch to send, context, overrides, and account if not hoisted on the client
- * @returns a Promise containing the {@link SendUserOperationResult}
+ * @example
+ * ```ts
+ * import { createSmartAccountClient, toSmartContractAccount } from "@aa-sdk/core";
+ *
+ * const account = await toSmartContractAccount(...);
+ * const result = await createSmartAccountClient(...).sendUserOperation({
+ *  uo: {
+ *    target: "0x...",
+ *    data: "0x...", // or "0x",
+ *    value: 0n, // optional
+ *  }
+ * });
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client the smart account client to use for RPC requests
+ * @param {SendUserOperationParameters<TAccount, TContext>} args contains the UO or batch to send, context, overrides, and account if not hoisted on the client
+ * @returns {Promise<SendUserOperationResult<TEntryPointVersion>>} a Promise containing the result of the user operation
  */
 export async function sendUserOperation<
   TTransport extends Transport = Transport,

package/src/actions/smartAccount/waitForUserOperationTransacation.ts

@@ -6,6 +6,30 @@ import { FailedToFindTransactionError } from "../../errors/transaction.js";
 import { Logger } from "../../logger.js";
 import type { WaitForUserOperationTxParameters } from "./types.js";
 
+/**
+ * Waits for a user operation transaction to be confirmed by checking the receipt periodically until it is found or a maximum number of retries is reached.
+ *
+ * @example
+ * ```ts
+ * import { createSmartAccountClient } from "@aa-sdk/core";
+ *
+ * // smart account client is already extended with waitForUserOperationTransaction
+ * const client = createSmartAccountClient(...);
+ * const result = await client.waitForUserOperationTransaction({
+ *  hash: "0x...",
+ *  retries: {...} // optional param to configure the retry amounts
+ * });
+ * ```
+ *
+ * @param {Client<TTransport, TChain, any>} client The client instance used to interact with the blockchain
+ * @param {WaitForUserOperationTxParameters} args The parameters for the transaction to wait for
+ * @param {Hex} args.hash The transaction hash to wait for
+ * @param {WaitForUserOperationTxParameters["retries"]} [args.retries] Optional retry parameters
+ * @param {number} [args.retries.maxRetries] The maximum number of retry attempts
+ * @param {number} [args.retries.intervalMs] The interval in milliseconds between retries
+ * @param {number} [args.retries.multiplier] The multiplier for the interval between retries
+ * @returns {Promise<Hex>} A promise that resolves to the transaction hash when the transaction is confirmed
+ */
 export const waitForUserOperationTransaction: <
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined

package/src/client/bundlerClient.ts

@@ -29,6 +29,21 @@ export type BundlerClient<T extends Transport = Transport> = Client<
   PublicActions<T, Chain> & BundlerActions
 >;
 
+/**
+ * Creates a bundler client from an existing public client with the provided transport and chain.
+ *
+ * @example
+ * ```ts
+ * import { createPublicClient } from "viem";
+ * import { createBundlerClientFromExisting } from "@aa-sdk/core";
+ *
+ * const publicClient = createPublicClient(...);
+ * const bundlerClient = createBundlerClientFromExisting(publicClient);
+ * ```
+ *
+ * @param {PublicClient<T, Chain>} client The existing public client to be extended with bundler actions
+ * @returns {BundlerClient<T>} A bundler client that extends the functionality of the provided public client
+ */
 export const createBundlerClientFromExisting: <
   T extends Transport | FallbackTransport = Transport
 >(
@@ -43,13 +58,30 @@ export const createBundlerClientFromExisting: <
 /**
  * Creates a PublicClient with methods for calling Bundler RPC methods
  *
- * @param args - configuration for the client
- * @returns a PublicClient with methods for calling Bundler RPC methods
+ * @param {PublicClientConfig<TTransport, Chain> & { type?: string }} args - configuration for the client
+ * @returns {BundlerClient<TTransport>} a PublicClient with methods for calling Bundler RPC methods
  */
 export function createBundlerClient<TTransport extends Transport>(
   args: PublicClientConfig<TTransport, Chain> & { type?: string }
 ): BundlerClient<TTransport>;
 
+/**
+ * Creates a Bundler Client using the provided configuration parameters, including chain and optional type.
+ *
+ * @example
+ * ```ts
+ * import { createBundlerClient } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ *
+ * const client = createBundlerClient({
+ *  chain: sepolia,
+ *  transport: http("RPC_URL"),
+ * });
+ * ```
+ *
+ * @param {PublicClientConfig & { type?: string }} args Configuration for creating the Bundler Client, including parameters for the chain, transport, and optional type
+ * @returns {BundlerClient} The created Bundler Client with extended public and bundler actions
+ */
 export function createBundlerClient(
   args: PublicClientConfig & { type?: string }
 ): BundlerClient {

package/src/client/decorators/bundlerClient.ts

@@ -55,10 +55,10 @@ export type BundlerActions = {
   /**
    * calls `eth_estimateUserOperationGas` and  returns the result
    *
-   * @param request - the {@link UserOperationRequest} to estimate gas for
+   * @param request - the UserOperationRequest to estimate gas for
    * @param entryPoint - the entry point address the op will be sent to
    * @param stateOverride - the state override to use for the estimation
-   * @returns the gas estimates for the given response (see: {@link UserOperationEstimateGasResponse})
+   * @returns the gas estimates for the given response
    */
   estimateUserOperationGas<
     TEntryPointVersion extends EntryPointVersion = EntryPointVersion
@@ -71,7 +71,7 @@ export type BundlerActions = {
   /**
    * calls `eth_sendUserOperation` and returns the hash of the sent UserOperation
    *
-   * @param request - the {@link UserOperationRequest} to send
+   * @param request - the UserOperationRequest to send
    * @param entryPoint - the entry point address the op will be sent to
    * @returns the hash of the sent UserOperation
    */
@@ -83,30 +83,39 @@ export type BundlerActions = {
   ): Promise<Hash>;
 
   /**
-   * calls `eth_getUserOperationByHash` and returns the {@link UserOperationResponse}
+   * calls `eth_getUserOperationByHash` and returns the UserOperationResponse
    *
    * @param hash - the hash of the UserOperation to fetch
-   * @returns - {@link UserOperationResponse}
+   * @returns - the user operation if found or null
    */
   getUserOperationByHash(hash: Hash): Promise<UserOperationResponse | null>;
 
   /**
-   * calls `eth_getUserOperationReceipt` and returns the {@link UserOperationReceipt}
+   * calls `eth_getUserOperationReceipt` and returns the UserOperationReceipt
    *
    * @param hash - the hash of the UserOperation to get the receipt for
-   * @returns - {@link UserOperationReceipt}
+   * @returns - a user operation receipt or null if not found
    */
   getUserOperationReceipt(hash: Hash): Promise<UserOperationReceipt | null>;
 
   /**
    * calls `eth_supportedEntryPoints` and returns the entry points the RPC supports
    *
-   * @returns - {@link Address}[]
+   * @returns - an array of the entrypoint addresses supported
    */
   getSupportedEntryPoints(): Promise<Address[]>;
 };
 // [!endregion BundlerActions]
 
+/**
+ * A viem client decorator that provides Bundler specific actions.
+ * These actions include estimating gas for user operations, sending raw user operations, retrieving user operations by hash, getting supported entry points, and getting user operation receipts.
+ *
+ * NOTE: this is already added to the client returned from `createBundlerClient`
+ *
+ * @param {TClient} client The client instance that will be used to perform bundler actions
+ * @returns {BundlerActions} An object containing various bundler-related actions that can be executed using the provided client
+ */
 export const bundlerActions: <
   TClient extends Client<
     Transport,

package/src/client/decorators/smartAccountClient.ts

@@ -133,6 +133,14 @@ export type BaseSmartAccountClientActions<
     });
 // #endregion SmartAccountClientActions
 
+/**
+ * Provides a set of smart account client actions to decorate the provided client. These actions include building and signing user operations, sending transactions, and more.
+ *
+ * NOTE: this is already added to clients returned from `createSmartAccountClient`
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client to bind the smart account actions to
+ * @returns {BaseSmartAccountClientActions<TChain, TAccount, TContext>} An object containing various smart account client actions
+ */
 export const smartAccountClientActions: <
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,

package/src/client/isSmartAccountClient.ts

@@ -11,8 +11,8 @@ import type {
  * Useful for narrowing the type of the client down when used within the
  * smart account client decorators
  *
- * @param client a viem client
- * @returns true if the client is a SmartAccountClient
+ * @param {Client<TTransport, TChain, TAccount>} client a viem client
+ * @returns {boolean} true if the client is a SmartAccountClient
  */
 export function isSmartAccountClient<
   TTransport extends Transport = Transport,
@@ -37,8 +37,8 @@ export function isSmartAccountClient<
  * Useful for narrowing the type of the client down when used within the
  * smart account action decorators
  *
- * @param client a viem client
- * @returns true if the account is a BaseSmartAccountClient
+ * @param {Client<TTransport, TChain, TAccount>} client a viem client
+ * @returns {boolean} true if the account is a BaseSmartAccountClient
  */
 export function isBaseSmartAccountClient<
   TTransport extends Transport = Transport,

package/src/client/smartAccountClient.ts

@@ -135,6 +135,26 @@ export function createSmartAccountClient<
   config: SmartAccountClientConfig<TTransport, TChain, TAccount, TContext>
 ): SmartAccountClient<TTransport, TChain, TAccount>;
 
+/**
+ * Creates a smart account client using the provided configuration. This client handles various Ethereum transactions and message signing operations.
+ *
+ * @example
+ * ```ts
+ * import { createSmartAccountClient, toSmartContractAccount } from "@aa-sdk/core";
+ * import { http } from "viem";
+ * import { sepolia } from "viem/chains";
+ *
+ * const client = createSmartAccountClient({
+ *  chain: sepolia,
+ *  transport: http("RPC_URL"),
+ *  // optionally hoist the account
+ *  account: toSmartContractAccount(...),
+ * });
+ * ```
+ *
+ * @param {SmartAccountClientConfig} config The configuration for creating the smart account client
+ * @returns {SmartAccountClient} A smart account client capable of handling transactions, message signing, and other operations on a smart account
+ */
 export function createSmartAccountClient(
   config: SmartAccountClientConfig
 ): SmartAccountClient {
@@ -263,6 +283,27 @@ export function createSmartAccountClientFromExisting<
   TContext
 >;
 
+/**
+ * Creates a smart account client using an existing client and specific configuration. This function can be used to reuse a pre-existing BundlerClient while customizing other aspects of the smart account.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createBundlerClient,
+ *   createSmartAccountClientFromExisting,
+ *   toSmartContractAccount
+ * } from "@aa-sdk/core";
+ *
+ * const bundlerClient = createBundlerClient(...);
+ * const client = createSmartAccountClientFromExisting({
+ *  client,
+ *  account: toSmartContractAccount(...),
+ * })
+ * ```
+ *
+ * @param {Omit<SmartAccountClientConfig, "transport" | "chain"> & {client: BundlerClient}} config the configuration object which includes the client
+ * @returns {SmartAccountClient} A smart account client created from the existing BundlerClient
+ */
 export function createSmartAccountClientFromExisting(
   config: Omit<SmartAccountClientConfig, "transport" | "chain"> & {
     client: BundlerClient;

package/src/client/types.ts

@@ -3,10 +3,7 @@ import type { Hash, Hex } from "viem";
 import type { z } from "zod";
 import type { UserOperationContext } from "../actions/smartAccount/types.js";
 import type { EntryPointVersion } from "../entrypoint/types.js";
-import type {
-  ClientMiddleware,
-  ClientMiddlewareFn,
-} from "../middleware/types.js";
+import type { ClientMiddleware } from "../middleware/types.js";
 import type { UserOperationRequest } from "../types.js";
 import type { ConnectionConfigSchema } from "./schema.js";
 
@@ -37,15 +34,5 @@ export type ClientMiddlewareConfig<
   TContext extends UserOperationContext | undefined =
     | UserOperationContext
     | undefined
-> = Omit<
-  Partial<ClientMiddleware<TContext>>,
-  "dummyPaymasterAndData" | "paymasterAndData"
-> & {
-  paymasterAndData?: {
-    dummyPaymasterAndData: () =>
-      | UserOperationRequest<"0.6.0">["paymasterAndData"]
-      | Pick<UserOperationRequest<"0.7.0">, "paymaster" | "paymasterData">;
-    paymasterAndData: ClientMiddlewareFn<TContext>;
-  };
-};
+> = Partial<ClientMiddleware<TContext>>;
 // [!endregion ClientMiddlewareConfig]

package/src/ens/utils.ts

@@ -1,11 +1,24 @@
-import type { Chain } from "viem/chains";
 import * as chains from "viem/chains";
-import { mainnet } from "../chains/index.js";
+import { mainnet, type Chain } from "viem/chains";
 
 export const ChainsById: Map<number, chains.Chain> = new Map(
   Object.values(chains).map((x) => [x.id, x])
 );
 
+/**
+ * Converts a given chain ID to a coin type, following specific standards for mainnet and non-mainnet chains.
+ *
+ * @example
+ * ```ts
+ * import { convertChainIdToCoinType } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ *
+ * const coinType = convertChainIdToCoinType(sepolia.id);
+ * ```
+ *
+ * @param {number} chainId the blockchain chain ID that you want to convert to a coin type
+ * @returns {number} the corresponding coin type for the given chain ID
+ */
 export const convertChainIdToCoinType = (chainId: number): number => {
   if (chainId === mainnet.id) {
     // this comes from [ensip-9](https://docs.ens.domains/ens-improvement-proposals/ensip-9-multichain-address-resolution)
@@ -16,6 +29,21 @@ export const convertChainIdToCoinType = (chainId: number): number => {
   return (0x80000000 | chainId) >>> 0;
 };
 
+/**
+ * Converts a coin type to a chain ID based on predefined mappings. This function follows ENSIP-9 for coin type 60 and ENSIP-11 for other coin types.
+ *
+ * @example
+ * ```ts
+ * import { convertChainIdToCoinType, convertCoinTypeToChainId } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ *
+ * const coinType = convertChainIdToCoinType(sepolia.id);
+ * const chainId = convertCoinTypeToChainId(coinType);
+ * ```
+ *
+ * @param {number} coinType the coin type to be converted to a chain ID
+ * @returns {number} the corresponding chain ID
+ */
 export const convertCoinTypeToChainId = (coinType: number): number => {
   if (coinType === 60) {
     // this comes from [ensip-9](https://docs.ens.domains/ens-improvement-proposals/ensip-9-multichain-address-resolution)
@@ -26,6 +54,22 @@ export const convertCoinTypeToChainId = (coinType: number): number => {
   return (0x7fffffff & coinType) >> 0;
 };
 
+/**
+ * Converts a coin type to its corresponding blockchain chain based on a predefined mapping.
+ *
+ * @example
+ * ```ts
+ * import { convertChainIdToCoinType, convertCoinTypeToChain } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ *
+ * const coinType = convertChainIdToCoinType(sepolia.id);
+ * const chain = convertCoinTypeToChain(coinType);
+ * ```
+ *
+ * @param {number} coinType The numerical identifier for the coin type
+ * @returns {Chain} The corresponding blockchain chain
+ * @throws {Error} If the coin type does not map to a supported chain
+ */
 export const convertCoinTypeToChain = (coinType: number): Chain => {
   const chainId = convertCoinTypeToChainId(coinType);
   const chain = ChainsById.get(chainId);

package/src/entrypoint/index.ts

@@ -17,6 +17,20 @@ export const entryPointRegistry: EntryPointRegistry = {
   "0.7.0": EntryPoint_v7,
 };
 
+/**
+ * Checks if the given value is a valid key of the EntryPointRegistry.
+ *
+ * @example
+ * ```ts
+ * import { isEntryPointVersion } from "@aa-sdk/core";
+ *
+ * const valid = isEntryPointVersion("0.6.0");
+ * const invalid = isEntryPointVersion("0.8.0");
+ * ```
+ *
+ * @param {*} value The value to be checked
+ * @returns {boolean} true if the value is a valid key of EntryPointRegistry, false otherwise
+ */
 export const isEntryPointVersion = (
   value: any
 ): value is keyof EntryPointRegistry => {
@@ -44,6 +58,22 @@ export function getEntryPoint<TChain extends Chain = Chain>(
   options?: GetEntryPointOptions<DefaultEntryPointVersion>
 ): EntryPointDefRegistry<TChain>[DefaultEntryPointVersion];
 
+/**
+ * Retrieves the entry point definition for the specified chain and version, falling back to the default version if not provided. Throws an error if the entry point address cannot be found.
+ *
+ * @example
+ * ```ts
+ * import { getEntryPoint } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ *
+ * const entryPoint060 = getEntryPoint(sepolia);
+ * const entryPoint070 = getEntryPoint(sepolia, { version: "0.7.0" });
+ * ```
+ *
+ * @param {Chain} chain The chain for which the entry point is being retrieved
+ * @param {GetEntryPointOptions<TEntryPointVersion>} options Options containing the version and address overrides for the entry point
+ * @returns {EntryPointDefRegistry<TChain>[EntryPointVersion]} The entry point definition for the specified chain and version
+ */
 export function getEntryPoint<
   TEntryPointVersion extends EntryPointVersion,
   TChain extends Chain = Chain
@@ -88,65 +118,3 @@ export function getEntryPoint<
 
   throw new EntryPointNotFoundError(chain, version);
 }
-
-// // =================================================================================
-// // TODO: Add tests for the following cases
-
-// const chain: Chain = mainnet;
-
-// // 1. left and right hand side version type should match, as well as the param
-
-// // === Error ===
-// const ep1_a: EntryPointDef<"0.6.0"> = getEntryPoint(chain, {
-//   version: "0.7.0",
-// }); // error
-// const ep1_b: EntryPointDef<"0.7.0"> = getEntryPoint(chain); // error
-// const ep1_c: EntryPointDef<"0.6.0"> = getEntryPoint(chain, {
-//   version: "0.7.0",
-// }); // error
-// const ep1_d: EntryPointDef<"0.6.0"> = getEntryPoint<"0.6.0">(chain, {
-//   version: "0.7.0",
-// }); // error
-
-// // === Valid ===
-// const ep1a: EntryPointDef<"0.6.0"> = getEntryPoint(chain);
-// const ep1b: EntryPointDef<"0.6.0"> = getEntryPoint(chain, { version: "0.6.0" });
-// const ep1c: EntryPointDef<"0.7.0"> = getEntryPoint(chain, { version: "0.7.0" });
-// const ep1d: EntryPointDef<"0.6.0"> = getEntryPoint(chain, {
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-// });
-// const ep1e: EntryPointDef<"0.6.0"> = getEntryPoint(chain, {
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-//   version: "0.6.0",
-// });
-// const ep1f: EntryPointDef<"0.7.0"> = getEntryPoint(chain, {
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-//   version: "0.7.0",
-// });
-
-// // 2. If non-default type is specified, version option param of the type is required
-
-// // === Error ===
-// const ep2_a: EntryPointDef<"0.7.0"> = getEntryPoint<"0.7.0">(chain); // error
-// const ep2_b: EntryPointDef<"0.7.0"> = getEntryPoint<"0.7.0">(chain, {
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-// });
-
-// // === Valid ===
-// const ep2a: EntryPointDef<"0.7.0"> = getEntryPoint<"0.7.0">(chain, {
-//   version: "0.7.0",
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-// });
-// const ep2b: EntryPointDef<"0.6.0"> = getEntryPoint<"0.6.0">(chain, {
-//   version: "0.6.0",
-// });
-// const ep2c: EntryPointDef<"0.6.0"> = getEntryPoint<"0.6.0">(chain);
-// const ep2d: EntryPointDef<"0.6.0"> = getEntryPoint<"0.6.0">(chain, {
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-// });
-// const ep2e: EntryPointDef<"0.7.0"> = getEntryPoint<"0.7.0">(chain, {
-//   version: "0.7.0",
-//   addressOverride: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-// });
-
-// // =================================================================================