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

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,
   }));
-};
+}

package/src/msca/utils.ts

@@ -39,7 +39,7 @@ import { MultiOwnerPlugin } from "./plugins/multi-owner/plugin.js";
 /**
  * Utility method returning the default multi sig msca factory address given a {@link Chain} object
  *
- * @param chain - a {@link Chain} object
+ * @param chain a {@link Chain} object
  * @returns a {@link Address} for the given chain
  * @throws if the chain doesn't have an address currently deployed
  */
@@ -78,6 +78,30 @@ export const getDefaultMultiOwnerModularAccountFactoryAddress = (
   }
 };
 
+export type GetMSCAUpgradeToData<
+  TSigner extends SmartAccountSigner = SmartAccountSigner,
+  TAccount extends
+    | SmartContractAccountWithSigner<string, TSigner>
+    | undefined = SmartContractAccountWithSigner<string, TSigner> | undefined
+> = {
+  multiOwnerPluginAddress?: Address;
+} & GetAccountParameter<TAccount>;
+
+/**
+ * Retrieves the data necessary to upgrade to a Multi-Signature Contract Account (MSCA) and provides a method to create a Multi-Owner Modular Account.
+ *
+ * @example
+ * ```ts
+ * import { createLightAccountClient, getMSCAUpgradeToData } from "@account-kit/smart-contracts";
+ *
+ * const client = createLightAccountClient(...);
+ * const upgradeData = await getMSCAUpgradeToData(client, {});
+ * ```
+ *
+ * @param {SmartAccountClient<TTransport, TChain, TAccount>} client The smart account client
+ * @param {GetMSCAUpgradeToData<TSigner, TAccount>} args The arguments required for the upgrade
+ * @returns {Promise<UpgradeToData & { createMAAccount: () => Promise<MultiOwnerModularAccount<TSigner>>}>} A promise that resolves to upgrade data augmented with a function to create a Multi-Owner Modular Account
+ */
 export async function getMSCAUpgradeToData<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,
@@ -87,9 +111,7 @@ export async function getMSCAUpgradeToData<
     | undefined = SmartContractAccountWithSigner<string, TSigner> | undefined
 >(
   client: SmartAccountClient<TTransport, TChain, TAccount>,
-  args: {
-    multiOwnerPluginAddress?: Address;
-  } & GetAccountParameter<TAccount>
+  args: GetMSCAUpgradeToData<TSigner, TAccount>
 ): Promise<
   UpgradeToData & {
     createMAAccount: () => Promise<MultiOwnerModularAccount<TSigner>>;
@@ -125,6 +147,39 @@ export async function getMSCAUpgradeToData<
   };
 }
 
+export type GetMAInitializationDataParams<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined
+> = {
+  multiOwnerPluginAddress?: Address;
+  client: SmartAccountClient<TTransport, TChain, TAccount>;
+  signerAddress: Address | Address[];
+};
+
+/**
+ * Retrieves the initialization data for a multi-owner modular account. Throws an error if the client's chain is not found or if the multi-owner plugin address is not retrievable.
+ *
+ * @example
+ * ```ts
+ * import { getMAInitializationData } from "@account-kit/smart-contracts";
+ * import { createSmartAccountClient } from "@aa-sdk/core";
+ *
+ * const client = createSmartAccountClient(...);
+ * const initializationData = await getMAInitializationData({
+ *  client,
+ *  signerAddress: "0x...", // or array of signers
+ * });
+ * ```
+ *
+ * @param {GetMAInitializationDataParams<TTransport, TChain, TAccount>} params the parameters for getting initialization data
+ * @param {SmartAccountClient<TTransport, TChain, TAccount>} params.client the smart account client
+ * @param {Address | Address[]} params.signerAddress the address of the signer or an array of signer addresses
+ * @param {Address} [params.multiOwnerPluginAddress] optional address of the multi-owner plugin
+ * @returns {Promise<UpgradeToData>} a promise that resolves to the initialization data required for upgrading to a multi-owner modular account
+ */
 export async function getMAInitializationData<
   TTransport extends Transport = Transport,
   TChain extends Chain | undefined = Chain | undefined,
@@ -135,11 +190,11 @@ export async function getMAInitializationData<
   client,
   multiOwnerPluginAddress,
   signerAddress,
-}: {
-  multiOwnerPluginAddress?: Address;
-  client: SmartAccountClient<TTransport, TChain, TAccount>;
-  signerAddress: Address | Address[];
-}): Promise<UpgradeToData> {
+}: GetMAInitializationDataParams<
+  TTransport,
+  TChain,
+  TAccount
+>): Promise<UpgradeToData> {
   if (!client.chain) {
     throw new ChainNotFoundError();
   }