@alchemy/smart-accounts 5.0.0-beta.8 → 5.0.1

package/src/ma-v2/accounts/account.ts

@@ -65,6 +65,45 @@ export type ToModularAccountV2Params<
  *
  * @param {ToModularAccountV2Params} param0 - The parameters for creating a MAv2 account.
  * @returns {Promise<ModularAccountV2>} A MAv2 account.
+ *
+ * @example
+ * ```ts
+ * import { createPublicClient } from "viem";
+ * import { createBundlerClient, createPaymasterClient } from "viem/account-abstraction";
+ * import { sepolia } from "viem/chains";
+ * import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+ * import { alchemyTransport } from "@alchemy/common";
+ * import { estimateFeesPerGas } from "@alchemy/aa-infra";
+ * import { toModularAccountV2 } from "@alchemy/smart-accounts";
+ *
+ * const transport = alchemyTransport({ apiKey: "YOUR_API_KEY" });
+ *
+ * // 1. Create a MAv2 smart account
+ * const account = await toModularAccountV2({
+ *   client: createPublicClient({ chain: sepolia, transport }),
+ *   owner: privateKeyToAccount(generatePrivateKey()),
+ * });
+ *
+ * // 2. Create a bundler client with the account
+ * const bundlerClient = createBundlerClient({
+ *   account,
+ *   chain: sepolia,
+ *   transport,
+ *   userOperation: {
+ *     estimateFeesPerGas,
+ *   },
+ *   // Optional: sponsor gas with a paymaster
+ *   paymaster: createPaymasterClient({ transport }),
+ *   paymasterContext: { policyId: "YOUR_POLICY_ID" },
+ * });
+ *
+ * // 3. Send a user operation
+ * const hash = await bundlerClient.sendUserOperation({
+ *   calls: [{ to: "0x...", value: 0n, data: "0x" }],
+ * });
+ *
+ * const receipt = await bundlerClient.waitForUserOperationReceipt({ hash });
+ * ```
  */
 export async function toModularAccountV2<TMode extends Mode = Mode>({
   client,

package/src/ma-v2/decorators/deferralActions.ts

@@ -45,7 +45,7 @@ export type CreateDeferredActionTypedDataParams = {
   nonce: bigint;
 };
 
-export type BuildPreSignatureDeferredActionDigestParams = {
+export type BuildPreSignatureDeferredActionPayloadParams = {
   typedData: DeferredActionTypedData;
 };
 
@@ -60,8 +60,8 @@ export type DeferralActions = {
   createDeferredActionTypedDataObject: (
     args: CreateDeferredActionTypedDataParams,
   ) => Promise<DeferredActionReturnData>;
-  buildPreSignatureDeferredActionDigest: (
-    args: BuildPreSignatureDeferredActionDigestParams,
+  buildPreSignatureDeferredActionPayload: (
+    args: BuildPreSignatureDeferredActionPayloadParams,
   ) => Hex;
   getEntityIdAndNonce: (
     args: EntityIdAndNonceParams,
@@ -72,7 +72,7 @@ export type DeferralActions = {
  * Provides deferred action functionalities for a MA v2 client, ensuring compatibility with `SmartAccountClient`.
  *
  * @param {ModularAccountV2Client} client - The client instance which provides account and sendUserOperation functionality.
- * @returns {object} - An object containing three methods: `createDeferredActionTypedDataObject`, `buildDeferredActionDigest`, and `buildUserOperationWithDeferredAction`.
+ * @returns {object} - An object containing three methods: `createDeferredActionTypedDataObject`, `buildPreSignatureDeferredActionPayload`, and `buildUserOperationWithDeferredAction`.
  */
 export const deferralActions = <
   TTransport extends Transport = Transport,
@@ -114,9 +114,9 @@ export const deferralActions = <
     };
   };
 
-  const buildPreSignatureDeferredActionDigest = ({
+  const buildPreSignatureDeferredActionPayload = ({
     typedData,
-  }: BuildPreSignatureDeferredActionDigestParams): Hex => {
+  }: BuildPreSignatureDeferredActionPayloadParams): Hex => {
     const account = client.account;
     if (!account || !isModularAccountV2(account)) {
       throw new AccountNotFoundError();
@@ -187,7 +187,7 @@ export const deferralActions = <
 
   return {
     createDeferredActionTypedDataObject,
-    buildPreSignatureDeferredActionDigest,
+    buildPreSignatureDeferredActionPayload,
     getEntityIdAndNonce,
   };
 };

package/src/ma-v2/permissionBuilder.ts

@@ -35,15 +35,59 @@ import {
   ValidationConfigUnsetError,
   ZeroAddressError,
 } from "../errors/permissionBuilderErrors.js";
+import { InvalidEntityIdError } from "../errors/InvalidEntityIdError.js";
 import type { SmartAccount } from "viem/account-abstraction";
 import { DefaultModuleAddress, isModularAccountV2 } from "./utils/account.js";
 
-// We use this to offset the ERC20 spend limit entityId
+// Reserved offset for hooks that would otherwise collide on shared module storage
+// (ERC20 spend limit vs PREVAL_ALLOWLIST on AllowlistModule; GAS_LIMIT vs
+// NATIVE_TOKEN_TRANSFER on NativeTokenLimitModule). Any user-supplied entityId
+// must be strictly less than this so the offset namespace stays disjoint.
 const HALF_UINT32 = 2147483647;
 const ERC20_APPROVE_SELECTOR = "0x095ea7b3";
 const ERC20_TRANSFER_SELECTOR = "0xa9059cbb";
 const ACCOUNT_EXECUTE_SELECTOR = "0xb61d27f6";
 const ACCOUNT_EXECUTEBATCH_SELECTOR = "0x34fcd5be";
+const ACCOUNT_PERFORM_CREATE_SELECTOR = "0x5998db5c";
+const ACCOUNT_EXECUTE_WITH_RUNTIME_VALIDATION_SELECTOR = "0xf2680c0f";
+const ACCOUNT_INSTALL_VALIDATION_SELECTOR = "0x1bbf564c";
+const ACCOUNT_UNINSTALL_VALIDATION_SELECTOR = "0xb6b1ccfe";
+const ACCOUNT_INSTALL_EXECUTION_SELECTOR = "0x1d37e7d6";
+const ACCOUNT_UNINSTALL_EXECUTION_SELECTOR = "0x0b7cad71";
+const ACCOUNT_UPGRADE_TO_AND_CALL_SELECTOR = "0x4f1ef286";
+// Wrapped native functions that must not be added to a session key's selector allowlist.
+const PRIVILEGED_SELECTORS: Record<string, string> = {
+  [ACCOUNT_PERFORM_CREATE_SELECTOR]: "performCreate",
+  [ACCOUNT_EXECUTE_WITH_RUNTIME_VALIDATION_SELECTOR]:
+    "executeWithRuntimeValidation",
+  [ACCOUNT_INSTALL_VALIDATION_SELECTOR]: "installValidation",
+  [ACCOUNT_UNINSTALL_VALIDATION_SELECTOR]: "uninstallValidation",
+  [ACCOUNT_INSTALL_EXECUTION_SELECTOR]: "installExecution",
+  [ACCOUNT_UNINSTALL_EXECUTION_SELECTOR]: "uninstallExecution",
+  [ACCOUNT_UPGRADE_TO_AND_CALL_SELECTOR]: "upgradeToAndCall",
+};
+
+// Auto-added by translatePermissions when a PREVAL_ALLOWLIST hook exists.
+// Blocked from manual addition to ensure they're only added with proper hook context.
+const SYSTEM_MANAGED_SELECTORS: Record<string, string> = {
+  [ACCOUNT_EXECUTE_SELECTOR]: "execute",
+  [ACCOUNT_EXECUTEBATCH_SELECTOR]: "executeBatch",
+};
+
+function assertNotForbiddenSelector(selector: Hex): void {
+  const normalized = selector.toLowerCase();
+  const match =
+    PRIVILEGED_SELECTORS[normalized] ?? SYSTEM_MANAGED_SELECTORS[normalized];
+  if (match != null) {
+    throw new SelectorNotAllowed(match);
+  }
+}
+
+function assertNoForbiddenSelectors(selectors: Hex[]): void {
+  for (const selector of selectors) {
+    assertNotForbiddenSelector(selector);
+  }
+}
 
 /**
  * A pseudo-enum for permission types.
@@ -264,6 +308,13 @@ export class PermissionBuilder {
       throw new AccountNotFoundError();
     }
 
+    // EntityIds in [HALF_UINT32, uint32.max] overlap the offset namespace used by
+    // ERC20 spend-limit and GAS_LIMIT hooks, which would silently corrupt the
+    // shared module storage. Reject early.
+    if (entityId >= HALF_UINT32) {
+      throw new InvalidEntityIdError(entityId, HALF_UINT32 - 1);
+    }
+
     this.client = client;
     this.validationConfig = {
       moduleAddress: DefaultModuleAddress.SINGLE_SIGNER_VALIDATION,
@@ -277,7 +328,10 @@ export class PermissionBuilder {
       signer: key.publicKey,
     });
     this.nonce = nonce;
-    if (selectors) this.selectors = selectors;
+    if (selectors) {
+      assertNoForbiddenSelectors(selectors);
+      this.selectors = selectors;
+    }
     if (hooks) this.hooks = hooks;
     if (deadline) this.deadline = deadline;
   }
@@ -289,6 +343,7 @@ export class PermissionBuilder {
    * @returns {this} The permission builder instance.
    */
   addSelector({ selector }: { selector: Hex }): this {
+    assertNotForbiddenSelector(selector);
     this.selectors.push(selector);
     return this;
   }
@@ -351,14 +406,7 @@ export class PermissionBuilder {
       if (permission.data.functions.length === 0) {
         throw new NoFunctionsProvidedError(permission);
       }
-      // Explicitly disallow adding execute & executeBatch
-      if (permission.data.functions.includes(ACCOUNT_EXECUTE_SELECTOR)) {
-        throw new SelectorNotAllowed("execute");
-      } else if (
-        permission.data.functions.includes(ACCOUNT_EXECUTEBATCH_SELECTOR)
-      ) {
-        throw new SelectorNotAllowed("executeBatch");
-      }
+      assertNoForbiddenSelectors(permission.data.functions);
       this.selectors = [...this.selectors, ...permission.data.functions];
     }
 
@@ -384,11 +432,11 @@ export class PermissionBuilder {
   /**
    * Compiles the deferred action typed data to sign.
    *
-   * @returns {Promise<{typedData: DeferredActionTypedData, fullPreSignatureDeferredActionDigest: Hex}>} The deferred action typed data and the full pre-signature deferred action digest.
+   * @returns {Promise<{typedData: DeferredActionTypedData, fullPreSignatureDeferredActionPayload: Hex}>} The deferred action typed data and the full pre-signature deferred action payload.
    */
   async compileDeferred(): Promise<{
     typedData: DeferredActionTypedData;
-    fullPreSignatureDeferredActionDigest: Hex;
+    fullPreSignatureDeferredActionPayload: Hex;
   }> {
     // Add time range module hook via expiry
     if (this.deadline !== 0) {
@@ -421,20 +469,20 @@ export class PermissionBuilder {
       nonce: this.nonce,
     });
 
-    const preSignatureDigest = deferralActions(
+    const preSignaturePayload = deferralActions(
       this.client,
-    ).buildPreSignatureDeferredActionDigest({ typedData });
+    ).buildPreSignatureDeferredActionPayload({ typedData });
 
-    // Encode additional information to build the full pre-signature digest
-    const fullPreSignatureDeferredActionDigest: `0x${string}` = `0x0${
+    // Encode additional information to build the full pre-signature payload
+    const fullPreSignatureDeferredActionPayload: `0x${string}` = `0x0${
       this.hasAssociatedExecHooks ? "1" : "0"
     }${toHex(this.nonce, {
       size: 32,
-    }).slice(2)}${preSignatureDigest.slice(2)}`;
+    }).slice(2)}${preSignaturePayload.slice(2)}`;
 
     return {
       typedData,
-      fullPreSignatureDeferredActionDigest,
+      fullPreSignatureDeferredActionPayload,
     };
   }
 
@@ -591,16 +639,18 @@ export class PermissionBuilder {
           if (rawHooks[HookIdentifier.GAS_LIMIT] !== undefined) {
             throw new MultipleGasLimitError(permission);
           }
+          // Offset the entityId so GAS_LIMIT writes to a different slot than
+          // NATIVE_TOKEN_TRANSFER on the shared NativeTokenLimitModule.
           rawHooks[HookIdentifier.GAS_LIMIT] = {
             hookConfig: {
               address: DefaultModuleAddress.NATIVE_TOKEN_LIMIT,
-              entityId,
+              entityId: entityId + HALF_UINT32,
               hookType: HookType.VALIDATION,
               hasPreHooks: true,
               hasPostHooks: false,
             },
             initData: {
-              entityId,
+              entityId: entityId + HALF_UINT32,
               spendLimit: BigInt(permission.data.limit),
             },
           };

package/src/ma-v2/utils/deferredActions.ts

@@ -34,31 +34,31 @@ export const parseDeferredAction = (
   };
 };
 
-export type BuildDeferredActionDigestParams = {
-  fullPreSignatureDeferredActionDigest: Hex;
+export type EncodeDeferredActionWithSignatureParams = {
+  fullPreSignatureDeferredActionPayload: Hex;
   sig: Hex;
   signaturePrefix?: SignaturePrefix;
 };
 
 /**
- * Creates the digest which must be prepended to the userOp signature.
+ * Encodes the deferred action with its signature, producing the payload to prepend to the userOp signature.
  *
  * Assumption: The client this extends is used to sign the typed data.
  *
- * @param {BuildDeferredActionDigestParams} params - The parameters for building the deferred action digest.
- * @returns {Hex} The encoded digest to be prepended to the userOp signature.
+ * @param {EncodeDeferredActionWithSignatureParams} params - The parameters for encoding the deferred action with its signature.
+ * @returns {Hex} The encoded payload to be prepended to the userOp signature.
  */
-export const buildDeferredActionDigest = ({
-  fullPreSignatureDeferredActionDigest,
+export const encodeDeferredActionWithSignature = ({
+  fullPreSignatureDeferredActionPayload,
   sig,
-}: BuildDeferredActionDigestParams): Hex => {
+}: EncodeDeferredActionWithSignatureParams): Hex => {
   // 6492 sigs don't work here.
   const _sig = parseErc6492Signature(sig).signature;
 
   const sigLength = size(_sig);
 
   const encodedData = concatHex([
-    fullPreSignatureDeferredActionDigest,
+    fullPreSignatureDeferredActionPayload,
     toHex(sigLength, { size: 4 }),
     _sig,
   ]);

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is autogenerated by inject-version.ts. Any changes will be
 // overwritten on commit!
-export const VERSION = "5.0.0-beta.8";
+export const VERSION = "5.0.1";