@account-kit/smart-contracts 4.0.0-alpha.0 → 4.0.0-alpha.2

package/src/msca/client/client.ts

@@ -80,6 +80,28 @@ export function createMultiOwnerModularAccountClient<
   >
 >;
 
+/**
+ * Creates a multi-owner modular account client with the provided parameters including account, transport, chain, and additional client configuration. This function uses a modular account and extends it with various plugin actions.
+ *
+ * @example
+ * ```ts
+ * import { createMultiOwnerModularAccountClient } from "@account-kit/smart-contracts";
+ * import { LocalAccountSigner } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ * import { http, generatePrivateKey } from "viem"
+ *
+ * const accountClient = await createMultiOwnerModularAccountClient({
+ *  chain: sepolia,
+ *  transport: http("RPC_URL"),
+ *  account: {
+ *    signer: LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey())
+ *  }
+ * });
+ * ```
+ *
+ * @param {CreateMultiOwnerModularAccountClientParams} config The parameters for creating the multi-owner modular account client
+ * @returns {Promise<SmartAccountClient>} A promise that resolves to a `SmartAccountClient` instance with extended plugin actions
+ */
 export async function createMultiOwnerModularAccountClient({
   account,
   transport,
@@ -121,6 +143,30 @@ export function createMultisigModularAccountClient<
   >
 >;
 
+/**
+ * Creates a multisig modular account client using the provided parameters including account details, transport, chain, and additional client configuration. This function constructs the multisig modular account and extends it with various actions to create a comprehensive client.
+ *
+ * @example
+ * ```ts
+ * import { createMultisigModularAccountClient } from "@account-kit/smart-contracts";
+ * import { LocalAccountSigner } from "@aa-sdk/core";
+ * import { sepolia } from "viem/chains";
+ * import { http, generatePrivateKey } from "viem"
+ *
+ * const accountClient = await createMultisigModularAccountClient({
+ *  chain: sepolia,
+ *  transport: http("RPC_URL"),
+ *  account: {
+ *    signer: LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey()),
+ *    owners: [...], // other owners on the account
+ *    threshold: 2, // 2 of N signatures
+ *  }
+ * });
+ * ```
+ *
+ * @param {CreateMultisigModularAccountClientParams} config the parameters for configuring the multisig modular account client
+ * @returns {Promise<SmartAccountClient<Transport, Chain, MultisigModularAccount<SmartAccountSigner>, {}, SmartAccountClientRpcSchema, MultisigUserOperationContext>>} a promise that resolves to a `SmartAccountClient` object extended with the multisig modular account and additional actions
+ */
 export async function createMultisigModularAccountClient({
   account,
   transport,

package/src/msca/client/multiSigAlchemyClient.ts

@@ -1,3 +1,7 @@
+import {
+  smartAccountClientActions,
+  type SmartAccountSigner,
+} from "@aa-sdk/core";
 import {
   AlchemyProviderConfigSchema,
   createAlchemyPublicRpcClient,
@@ -19,10 +23,6 @@ import {
   type MultisigUserOperationContext,
   type PluginManagerActions,
 } from "@account-kit/smart-contracts";
-import {
-  smartAccountClientActions,
-  type SmartAccountSigner,
-} from "@aa-sdk/core";
 import {
   custom,
   type Chain,
@@ -65,6 +65,28 @@ export function createMultisigAccountAlchemyClient<
   >
 >;
 
+/**
+ * Creates an Alchemy client for a multisig account using the provided configuration.
+ *
+ * @example
+ * ```ts
+ * import { createMultisigAccountAlchemyClient } from "@account-kit/smart-contracts";
+ * import { sepolia } from "@account-kit/infra";
+ * import { LocalAccountSigner } from "@aa-sdk/core";
+ * import { generatePrivateKey } from "viem"
+ *
+ * const alchemyAccountClient = await createMultisigAccountAlchemyClient({
+ *  apiKey: "your-api-key",
+ *  chain: sepolia,
+ *  signer: LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey()),
+ *  owners: [...], // other owners on the account
+ *  threshold: 2, // 2 of N signatures
+ * });
+ * ```
+ *
+ * @param {AlchemyMultisigAccountClientConfig} config The configuration for the Alchemy multisig account client
+ * @returns {Promise<AlchemySmartAccountClient<Transport, Chain | undefined, MultisigModularAccount<SmartAccountSigner>, MultisigPluginActions<MultisigModularAccount<SmartAccountSigner>> & PluginManagerActions<MultisigModularAccount<SmartAccountSigner>> & AccountLoupeActions<MultisigModularAccount<SmartAccountSigner>>, MultisigUserOperationContext>>} A promise that resolves to an Alchemy Smart Account Client for multisig accounts with extended functionalities.
+ */
 export async function createMultisigAccountAlchemyClient(
   config: AlchemyMultisigAccountClientConfig
 ): Promise<

package/src/msca/errors.ts

@@ -1,5 +1,8 @@
 import { BaseError } from "@aa-sdk/core";
 
+/**
+ * Error thrown when the aggregated signature is invalid
+ */
 export class InvalidAggregatedSignatureError extends BaseError {
   override name = "InvalidAggregatedSignatureError";
   constructor() {
@@ -7,6 +10,9 @@ export class InvalidAggregatedSignatureError extends BaseError {
   }
 }
 
+/**
+ * Error thrown when the context signature is invalid
+ */
 export class InvalidContextSignatureError extends BaseError {
   override name = "InvalidContextSignatureError";
   constructor() {
@@ -14,6 +20,9 @@ export class InvalidContextSignatureError extends BaseError {
   }
 }
 
+/**
+ * Error thrown when the expected account is not a multisig modular account
+ */
 export class MultisigAccountExpectedError extends BaseError {
   override name = "MultisigAccountExpectedError";
   constructor() {
@@ -21,6 +30,9 @@ export class MultisigAccountExpectedError extends BaseError {
   }
 }
 
+/**
+ * Error thrown when a multisig user op is missing a signature
+ */
 export class MultisigMissingSignatureError extends BaseError {
   override name = "MultisigMissingSignatureError";
   constructor() {

package/src/msca/plugin-manager/decorator.ts

@@ -27,7 +27,22 @@ export type PluginManagerActions<
   ) => Promise<SendUserOperationResult<TEntryPointVersion>>;
 };
 
-export const pluginManagerActions: <
+/**
+ * Provides actions for managing plugins on a given client, including installing and uninstalling plugins.
+ * NOTE: this is provided by default when using a modular account client
+ *
+ * @example
+ * ```ts
+ * import { pluginManagerActions } from "@account-kit/smart-contracts";
+ * import { createSmartAccountClient } from "@aa-sdk/core";
+ *
+ * const client = createSmartAccountClient(...).extend(pluginManagerActions);
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client instance on which to manage plugins
+ * @returns {PluginManagerActions<TAccount>} An object containing functions to install and uninstall plugins
+ */
+export function pluginManagerActions<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,
   TAccount extends SmartContractAccount | undefined =
@@ -35,7 +50,9 @@ export const pluginManagerActions: <
     | undefined
 >(
   client: Client<TTransport, TChain, TAccount>
-) => PluginManagerActions<TAccount> = (client) => ({
-  installPlugin: async (params) => installPlugin(client, params),
-  uninstallPlugin: async (params) => uninstallPlugin(client, params),
-});
+): PluginManagerActions<TAccount> {
+  return {
+    installPlugin: async (params) => installPlugin(client, params),
+    uninstallPlugin: async (params) => uninstallPlugin(client, params),
+  };
+}

package/src/msca/plugin-manager/installPlugin.ts

@@ -40,6 +40,27 @@ export type InstallPluginParams<
   GetAccountParameter<TAccount> &
   GetContextParameter<TContext>;
 
+/**
+ * Installs a plugin on a smart account via the client, sending the user operation with the appropriate parameters.
+ * NOTE: it's recommended to just use the installPlugin action returned from generated plugins
+ *
+ * @example
+ * ```ts
+ * import { installPlugin, createModularAccountAlchemyClient } from "@account-kit/smart-contracts";
+ *
+ * const client = createModularAccountAlchemyClient(...);
+ *
+ * const hash = await installPlugin(client, {
+ *  pluginAddress: "0x...",
+ *  manifestHash: "0x...",
+ *  dependencies: [], // this is defined by the plugin you're installing
+ * });
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client configured to the smart account on which the plugin will be installed
+ * @param {InstallPluginParams<TAccount, TContext>} params The parameters required to install the plugin, including overrides, context, and account information
+ * @returns {Promise<any>} A promise that resolves once the plugin installation operation is sent
+ */
 export async function installPlugin<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,

package/src/msca/plugins/multi-owner/extension.ts

@@ -33,6 +33,21 @@ export type MultiOwnerPluginActions<
       }
     : {});
 
+/**
+ * Creates actions for the MultiOwner plugin, including reading owners and checking ownership.
+ * NOTE: this is already added to the client returned from createMultiOwnerModularAccountClient
+ *
+ * @example
+ * ```ts
+ * import { multiOwnerPluginActions } from "@account-kit/smart-contracts";
+ * import { createSmartAccountClient } from "@aa-sdk/core";
+ *
+ * const client = createSmartAccountClient(...).extend(multiOwnerPluginActions);
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client the client instance containing the transport, chain, and account information
+ * @returns {MultiOwnerPluginActions<TAccount>} an object containing the actions for the MultiOwner plugin, such as `readOwners` and `isOwnerOf`
+ */
 export const multiOwnerPluginActions: <
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,

package/src/msca/plugins/multi-owner/index.ts

@@ -1,6 +1,9 @@
 export type * from "./extension.js";
 export { multiOwnerPluginActions } from "./extension.js";
+
 export {
+  MultiOwnerPlugin,
   MultiOwnerPluginAbi,
   MultiOwnerPluginExecutionFunctionAbi,
+  type InstallMultiOwnerPluginParams,
 } from "./plugin.js";

package/src/msca/plugins/multisig/actions/proposeUserOperation.ts

@@ -10,8 +10,8 @@ import {
   type UserOperationOverrides,
 } from "@aa-sdk/core";
 import { type Chain, type Client, type Transport } from "viem";
-import { splitAggregatedSignature } from "../index.js";
 import { type ProposeUserOperationResult } from "../types.js";
+import { splitAggregatedSignature } from "../utils/splitAggregatedSignature.js";
 
 export async function proposeUserOperation<
   TTransport extends Transport = Transport,

package/src/msca/plugins/multisig/actions/signMultisigUserOperation.ts

@@ -8,11 +8,11 @@ import {
 } from "@aa-sdk/core";
 import { type Chain, type Client, type Transport } from "viem";
 import { MultisigMissingSignatureError } from "../../../errors.js";
-import { combineSignatures, splitAggregatedSignature } from "../index.js";
 import {
   type SignMultisigUserOperationParams,
   type SignMultisigUserOperationResult,
 } from "../types.js";
+import { combineSignatures, splitAggregatedSignature } from "../utils/index.js";
 
 export async function signMultisigUserOperation<
   TTransport extends Transport = Transport,

package/src/msca/plugins/multisig/extension.ts

@@ -58,6 +58,19 @@ export type MultisigPluginActions<
       }
     : {});
 
+/**
+ * Provides actions for managing a multisig plugin within the specified client, including reading owners, checking ownership, getting the threshold, proposing user operations, and signing multisig user operations.
+ *
+ * @example
+ * ```ts
+ * import { createModularAccountAlchemyClient, multisigPluginActions } from "@account-kit/smart-contracts";
+ *
+ * const client = createModularAccountAlchemyClient(...).extend(multisigPluginActions);
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client instance configured with transport, chain, and account information
+ * @returns {MultisigPluginActions<TAccount>} An object containing methods to perform actions related to the multisig plugin
+ */
 export const multisigPluginActions: <
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,

package/src/msca/plugins/multisig/index.ts

@@ -1,8 +1,3 @@
-export { getThreshold } from "./actions/getThreshold.js";
-export { isOwnerOf } from "./actions/isOwnerOf.js";
-export { proposeUserOperation } from "./actions/proposeUserOperation.js";
-export { readOwners } from "./actions/readOwners.js";
-export { signMultisigUserOperation } from "./actions/signMultisigUserOperation.js";
 export type * from "./extension.js";
 export { multisigPluginActions } from "./extension.js";
 export { multisigSignatureMiddleware } from "./middleware.js";
@@ -10,12 +5,6 @@ export {
   MultisigPlugin,
   MultisigPluginAbi,
   MultisigPluginExecutionFunctionAbi,
+  type InstallMultisigPluginParams,
 } from "./plugin.js";
 export type * from "./types.js";
-export { type SignerType } from "./types.js";
-export {
-  combineSignatures,
-  formatSignatures,
-  getSignerType,
-  splitAggregatedSignature,
-} from "./utils/index.js";

package/src/msca/plugins/multisig/middleware.ts

@@ -15,12 +15,12 @@ import {
   InvalidContextSignatureError,
   MultisigAccountExpectedError,
 } from "../../errors.js";
+import { type MultisigUserOperationContext } from "./types.js";
 import {
   combineSignatures,
   getSignerType,
   splitAggregatedSignature,
-  type MultisigUserOperationContext,
-} from "./index.js";
+} from "./utils/index.js";
 
 /**
  * A signer middleware to be used with Multisig Account Clients.

package/src/msca/plugins/multisig/utils/combineSignatures.ts

@@ -2,23 +2,50 @@ import { type Hex, concat, pad } from "viem";
 import type { Signature } from "../types.js";
 import { formatSignatures } from "./formatSignatures.js";
 
-export const combineSignatures = ({
-  signatures,
-  upperLimitMaxFeePerGas,
-  upperLimitMaxPriorityFeePerGas,
-  upperLimitPvg,
-  usingMaxValues,
-}: {
+export type CombineSignaturesParams = {
   upperLimitPvg: Hex;
   upperLimitMaxFeePerGas: Hex;
   upperLimitMaxPriorityFeePerGas: Hex;
   signatures: Signature[];
   usingMaxValues: boolean;
-}) => {
+};
+
+/**
+ * Combines multiple signatures with provided upper limit values for gas fees and returns the concatenated result.
+ *
+ * @example
+ * ```ts
+ * import { combineSignatures } from "@account-kit/smart-contracts";
+ *
+ * const combinedSignature = combineSignatures({
+ *  // this is the upper limit pre-verification gas
+ *  upperLimitPvg: "0x01",
+ *  upperLimitMaxFeePerGas: "0x02",
+ *  upperLimitMaxPriorityFeePerGas: "0x03",
+ *  signatures: [{
+ *    signerType: "EOA",
+ *    userOpSigType: "UPPERLIMIT",
+ *    signer: `0x...`,
+ *    signature: `0x...`,
+ *  }]
+ *  usingMaxValues: false,
+ * });
+ * ```
+ *
+ * @param {CombineSignaturesParams} params The function parameters
+ * @returns {Hex} The concatenated result of padding and formatting the provided values and signatures
+ */
+export function combineSignatures({
+  signatures,
+  upperLimitMaxFeePerGas,
+  upperLimitMaxPriorityFeePerGas,
+  upperLimitPvg,
+  usingMaxValues,
+}: CombineSignaturesParams): Hex {
   return concat([
     pad(upperLimitPvg),
     pad(upperLimitMaxFeePerGas),
     pad(upperLimitMaxPriorityFeePerGas),
     formatSignatures(signatures, usingMaxValues),
   ]);
-};
+}

package/src/msca/plugins/multisig/utils/getSignerType.ts

@@ -1,12 +1,12 @@
-import type { SmartContractAccount, SmartAccountSigner } from "@aa-sdk/core";
+import type { SmartAccountSigner, SmartContractAccount } from "@aa-sdk/core";
 import {
-  type Transport,
   type Chain,
   type Client,
-  type PublicRpcSchema,
-  type PublicActions,
   type Hex,
+  type PublicActions,
+  type PublicRpcSchema,
   size,
+  type Transport,
 } from "viem";
 import type { SignerType } from "../types";
 
@@ -29,6 +29,25 @@ type GetSignerTypeParams<
   client: TClient;
 };
 
+/**
+ * Determines the type of signer (Externally Owned Account (EOA) or CONTRACT) based on the provided client, signature, and signer.
+ *
+ * @example
+ * ```ts
+ * import { getSignerType } from "@account-kit/smart-contracts";
+ * import { LocalAccountSigner } from "@aa-sdk/core";
+ * import { createPublicClient, generatePrivateKey } from "viem";
+ *
+ * const signer = LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey());
+ * const client = createPublicClient(...);
+ * const signature = signer.signMessage("Hello World");
+ *
+ * const signerType = await getSignerType({ client, signature, signer }); // EOA
+ * ```
+ *
+ * @param {GetSignerTypeParams<TTransport, TChain>} params the parameters including the client, signature, and signer
+ * @returns {Promise<SignerType>} A promise that resolves to the signer type, which is either "EOA" or "CONTRACT"
+ */
 export const getSignerType = async <
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined

package/src/msca/plugins/multisig/utils/index.ts

@@ -1,4 +1,8 @@
+export type * from "./combineSignatures.js";
 export { combineSignatures } from "./combineSignatures.js";
+export type * from "./formatSignatures.js";
 export { formatSignatures } from "./formatSignatures.js";
+export type * from "./getSignerType.js";
 export { getSignerType } from "./getSignerType.js";
+export type * from "./splitAggregatedSignature.js";
 export { splitAggregatedSignature } from "./splitAggregatedSignature.js";

package/src/msca/plugins/session-key/extension.ts

@@ -82,6 +82,19 @@ export type SessionKeyPluginActions<
       }
     : {});
 
+/**
+ * Creates actions for managing session keys in a smart contract associated with a client, including adding, removing, rotating, and updating session key permissions.
+ *
+ * @example
+ * ```ts
+ * import { createModularAccountAlchemyClient, sessionKeyPluginActions } from "@account-kit/smart-contracts";
+ *
+ * const client = createModularAccountAlchemyClient(...).extend(sessionKeyPluginActions);
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client instance to use for managing session keys
+ * @returns {SessionKeyPluginActions<TAccount>} An object containing methods for session key management and interaction with the smart contract
+ */
 export const sessionKeyPluginActions: <
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,

package/src/msca/plugins/session-key/index.ts

@@ -1,3 +1,9 @@
 export type * from "./extension.js";
 export { sessionKeyPluginActions } from "./extension.js";
-export { SessionKeyPlugin } from "./plugin.js";
+
+export {
+  SessionKeyPlugin,
+  SessionKeyPluginAbi,
+  SessionKeyPluginExecutionFunctionAbi,
+  type InstallSessionKeyPluginParams,
+} from "./plugin.js";

package/src/msca/plugins/session-key/permissions.ts

@@ -56,6 +56,9 @@ export type GasSpendLimit = {
   refreshInterval?: number;
 };
 
+/**
+ * A builder for creating the hex-encoded data for updating session key permissions.
+ */
 export class SessionKeyPermissionsBuilder {
   private _contractAccessControlType: SessionKeyAccessListType =
     SessionKeyAccessListType.ALLOWLIST;

package/src/msca/plugins/session-key/signer.ts

@@ -18,14 +18,13 @@ export const SessionKeySignerSchema = z.object({
 });
 
 export type SessionKeySignerConfig = z.input<typeof SessionKeySignerSchema>;
+export const SESSION_KEY_SIGNER_TYPE_PFX = "alchemy:session-key";
 
 /**
  * A simple session key signer that uses localStorage or sessionStorage to store
  * a private key. If the key is not found, it will generate a new one and store
  * it in the storage.
  */
-
-export const SESSION_KEY_SIGNER_TYPE_PFX = "alchemy:session-key";
 export class SessionKeySigner
   implements SmartAccountSigner<LocalAccountSigner<PrivateKeyAccount>>
 {

package/src/msca/plugins/session-key/utils.ts

@@ -3,9 +3,34 @@ import { AccountNotFoundError } from "@aa-sdk/core";
 import type { Address, Chain, Client, Transport } from "viem";
 import { SessionKeyPlugin } from "./plugin.js";
 
-// find predecessors for each keys and returned the struct `ISessionKeyPlugin.SessionKeyToRemove[]`
-// where SessionKeyToRemove = { sessionKey: Address, predecessor: Hex }
-export const buildSessionKeysToRemoveStruct: <
+type BuildSessionKeysToRemoveStructParams<
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined
+> = {
+  keys: ReadonlyArray<Address>;
+  pluginAddress?: Address;
+} & GetAccountParameter<TAccount>;
+
+/**
+ * Finds predecessors for each provided key and returns them in the struct `ISessionKeyPlugin.SessionKeyToRemove[]`.
+ *
+ * @example
+ * ```ts
+ * import { buildSessionKeysToRemoveStruct } from "@account-kit/smart-contracts";
+ *
+ * const client = createSmartAccountClient(...);
+ *
+ * const keysToRemove = await buildSessionKeysToRemoveStruct(client, {
+ *  keys: ["0x...", "0x..."],
+ * });
+ * ```
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client instance used to interact with the smart account
+ * @param {BuildSessionKeysToRemoveStructParams<TAccount>} args Arguments to configure the session key removal process
+ * @returns {Promise<{ sessionKey: Address; predecessor: Address }[]>} A promise that resolves to an array of objects each containing a session key and its predecessor
+ */
+export async function buildSessionKeysToRemoveStruct<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,
   TAccount extends SmartContractAccount | undefined =
@@ -13,14 +38,10 @@ export const buildSessionKeysToRemoveStruct: <
     | undefined
 >(
   client: Client<TTransport, TChain, TAccount>,
-  args: {
-    keys: ReadonlyArray<Address>;
-    pluginAddress?: Address;
-  } & GetAccountParameter<TAccount>
-) => Promise<{ sessionKey: Address; predecessor: Address }[]> = async (
-  client,
-  { keys, pluginAddress, account = client.account }
-) => {
+  args: BuildSessionKeysToRemoveStructParams
+): Promise<{ sessionKey: Address; predecessor: Address }[]> {
+  const { keys, pluginAddress, account = client.account } = args;
+
   if (!account) throw new AccountNotFoundError();
 
   const contract = SessionKeyPlugin.getContract(client, pluginAddress);
@@ -37,4 +58,4 @@ export const buildSessionKeysToRemoveStruct: <
     sessionKey: key,
     predecessor,
   }));
-};
+}