@account-kit/smart-contracts 4.24.0 → 4.25.1

package/src/ma-v2/permissionBuilder.ts

@@ -1,4 +1,4 @@
-import { toHex, zeroAddress, type Address, type Hex } from "viem";
+import { maxUint48, toHex, zeroAddress, type Address, type Hex } from "viem";
 import {
   HookType,
   type HookConfig,
@@ -23,6 +23,19 @@ import {
 import { SingleSignerValidationModule } from "./modules/single-signer-validation/module.js";
 import { AllowlistModule } from "./modules/allowlist-module/module.js";
 import { TimeRangeModule } from "./modules/time-range-module/module.js";
+import {
+  AccountAddressAsTargetError,
+  DeadlineOverLimitError,
+  DuplicateTargetAddressError,
+  ExpiredDeadlineError,
+  MultipleGasLimitError,
+  MultipleNativeTokenTransferError,
+  NoFunctionsProvidedError,
+  RootPermissionOnlyError,
+  UnsupportedPermissionTypeError,
+  ValidationConfigUnsetError,
+  ZeroAddressError,
+} from "./permissionBuilderErrors.js";
 
 // We use this to offset the ERC20 spend limit entityId
 const HALF_UINT32 = 2147483647;
@@ -209,25 +222,26 @@ export class PermissionBuilder {
   private hooks: Hook[] = [];
   private nonce: bigint = 0n;
   private hasAssociatedExecHooks: boolean = false;
+  private deadline: number = 0;
 
-  constructor(client: ModularAccountV2Client) {
-    this.client = client;
-  }
-
-  // Configures the builder
-  configure({
+  constructor({
+    client,
     key,
     entityId,
     nonce,
     selectors,
     hooks,
+    deadline,
   }: {
+    client: ModularAccountV2Client;
     key: Key;
     entityId: number;
     nonce: bigint;
     selectors?: Hex[];
     hooks?: Hook[];
-  }): this {
+    deadline?: number;
+  }) {
+    this.client = client;
     this.validationConfig = {
       moduleAddress: getDefaultSingleSignerValidationModuleAddress(
         this.client.chain
@@ -241,10 +255,10 @@ export class PermissionBuilder {
       entityId: entityId,
       signer: key.publicKey,
     });
+    this.nonce = nonce;
     if (selectors) this.selectors = selectors;
     if (hooks) this.hooks = hooks;
-    this.nonce = nonce;
-    return this;
+    if (deadline) this.deadline = deadline;
   }
 
   addSelector({ selector }: { selector: Hex }): this {
@@ -256,9 +270,7 @@ export class PermissionBuilder {
     // Check 1: If we're adding root, we can't have any other permissions
     if (permission.type === PermissionType.ROOT) {
       if (this.permissions.length !== 0) {
-        throw new Error(
-          "PERMISSION: ROOT: Cannot add ROOT permission with other permissions"
-        );
+        throw new RootPermissionOnlyError(permission);
       }
       this.permissions.push(permission);
       // Set isGlobal to true
@@ -271,9 +283,7 @@ export class PermissionBuilder {
     // NOTE: Technically this could be replaced by checking permissions[0] since it should not be possible
     // to have >1 permission with root among them
     if (this.permissions.find((p) => p.type === PermissionType.ROOT)) {
-      throw new Error(
-        `PERMISSION: ${permission.type} => Cannot add permissions with ROOT enabled`
-      );
+      throw new RootPermissionOnlyError(permission);
     }
 
     // Check 3: If the permission is either CONTRACT_ACCESS or FUNCTIONS_ON_CONTRACT, ensure it doesn't collide with another like it.
@@ -283,9 +293,7 @@ export class PermissionBuilder {
     ) {
       // Check 3.1: address must not be the account address, or the user should use the ACCOUNT_FUNCTIONS permission
       if (permission.data.address === this.client.account.address) {
-        throw new Error(
-          `PERMISSION: ${permission.type} => Account address as target, use ACCOUNT_FUNCTIONS for account address`
-        );
+        throw new AccountAddressAsTargetError(permission);
       }
 
       // Check 3.2: there must not be an existing permission with this address as a target
@@ -301,20 +309,19 @@ export class PermissionBuilder {
       );
 
       if (existingPermissionWithSameAddress) {
-        throw new Error(
-          `PERMISSION: ${permission.type} => Address ${targetAddress} already has a permission. Cannot add multiple CONTRACT_ACCESS or FUNCTIONS_ON_CONTRACT permissions for the same target address.`
-        );
+        throw new DuplicateTargetAddressError(permission, targetAddress);
       }
     }
 
     // Check 4: If the permission is ACCOUNT_FUNCTIONS, add selectors
     if (permission.type === PermissionType.ACCOUNT_FUNCTIONS) {
+      if (permission.data.functions.length === 0) {
+        throw new NoFunctionsProvidedError(permission);
+      }
       this.selectors = [...this.selectors, ...permission.data.functions];
-      return this;
     }
 
     this.permissions.push(permission);
-
     return this;
   }
 
@@ -328,33 +335,24 @@ export class PermissionBuilder {
   }
 
   // Use for building deferred action typed data to sign
-  async compileDeferred({
-    deadline,
-  }: {
-    deadline: number;
-    uoValidationEntityId: number;
-    uoIsGlobalValidation: boolean;
-  }): Promise<{
+  async compileDeferred(): Promise<{
     typedData: DeferredActionTypedData;
     fullPreSignatureDeferredActionDigest: Hex;
   }> {
-    // Need to remove this because compileRaw may add selectors
-    // this.validateConfiguration();
-
     // Add time range module hook via expiry
-    if (deadline !== 0) {
-      if (deadline < Date.now() / 1000) {
-        throw new Error(
-          `PERMISSION: compileDeferred(): Deadline ${deadline} cannot be before now (${
-            Date.now() / 1000
-          })`
-        );
+    if (this.deadline !== 0) {
+      if (this.deadline < Date.now() / 1000) {
+        throw new ExpiredDeadlineError(this.deadline, Date.now() / 1000);
+      }
+      if (this.deadline > maxUint48) {
+        throw new DeadlineOverLimitError(this.deadline);
       }
+
       this.hooks.push(
         TimeRangeModule.buildHook(
           {
-            entityId: this.validationConfig.entityId, // will be timerange entityId
-            validUntil: deadline,
+            entityId: this.validationConfig.entityId,
+            validUntil: this.deadline,
             validAfter: 0,
           },
           getDefaultTimeRangeModuleAddress(this.client.chain)
@@ -368,7 +366,7 @@ export class PermissionBuilder {
       this.client
     ).createDeferredActionTypedDataObject({
       callData: installValidationCall,
-      deadline: deadline,
+      deadline: this.deadline,
       nonce: this.nonce,
     });
 
@@ -377,8 +375,8 @@ export class PermissionBuilder {
     ).buildPreSignatureDeferredActionDigest({ typedData });
 
     // Encode additional information to build the full pre-signature digest
-    const fullPreSignatureDeferredActionDigest: `0x${string}` = `0x00${
-      this.hasAssociatedExecHooks ? "01" : "00"
+    const fullPreSignatureDeferredActionDigest: `0x${string}` = `0x0${
+      this.hasAssociatedExecHooks ? "1" : "0"
     }${toHex(this.nonce, {
       size: 32,
     }).slice(2)}${preSignatureDigest.slice(2)}`;
@@ -428,9 +426,7 @@ export class PermissionBuilder {
       this.validationConfig.isGlobal === false &&
       this.selectors.length === 0
     ) {
-      throw new Error(
-        "Validation config unset, use permissionBuilder.configure(...)"
-      );
+      throw new ValidationConfigUnsetError();
     }
   }
 
@@ -449,9 +445,7 @@ export class PermissionBuilder {
         case PermissionType.NATIVE_TOKEN_TRANSFER:
           // Should never be added twice, check is on addPermission(s) too
           if (rawHooks[HookIdentifier.NATIVE_TOKEN_TRANSFER] !== undefined) {
-            throw new Error(
-              "PERMISSION: NATIVE_TOKEN_TRANSFER => Must have at most ONE native token transfer permission"
-            );
+            throw new MultipleNativeTokenTransferError(permission);
           }
           rawHooks[HookIdentifier.NATIVE_TOKEN_TRANSFER] = {
             hookConfig: {
@@ -472,9 +466,7 @@ export class PermissionBuilder {
           break;
         case PermissionType.ERC20_TOKEN_TRANSFER:
           if (permission.data.address === zeroAddress) {
-            throw new Error(
-              "PERMISSION: ERC20_TOKEN_TRANSFER => Zero address provided"
-            );
+            throw new ZeroAddressError(permission);
           }
           rawHooks[HookIdentifier.ERC20_TOKEN_TRANSFER] = {
             hookConfig: {
@@ -530,9 +522,7 @@ export class PermissionBuilder {
         case PermissionType.GAS_LIMIT:
           // Should only ever be added once, check is also on addPermission(s)
           if (rawHooks[HookIdentifier.GAS_LIMIT] !== undefined) {
-            throw new Error(
-              "PERMISSION: GAS_LIMIT => Must have at most ONE gas limit permission"
-            );
+            throw new MultipleGasLimitError(permission);
           }
           rawHooks[HookIdentifier.GAS_LIMIT] = {
             hookConfig: {
@@ -552,9 +542,7 @@ export class PermissionBuilder {
           break;
         case PermissionType.CONTRACT_ACCESS:
           if (permission.data.address === zeroAddress) {
-            throw new Error(
-              "PERMISSION: CONTRACT_ACCESS => Zero address provided"
-            );
+            throw new ZeroAddressError(permission);
           }
           rawHooks[HookIdentifier.PREVAL_ALLOWLIST] = {
             hookConfig: {
@@ -582,17 +570,11 @@ export class PermissionBuilder {
           };
           break;
         case PermissionType.ACCOUNT_FUNCTIONS:
-          if (permission.data.functions.length === 0) {
-            throw new Error(
-              "PERMISSION: ACCOUNT_FUNCTION => No functions provided"
-            ); // should be in add perm
-          }
+          // This is handled in add permissions
           break;
         case PermissionType.FUNCTIONS_ON_ALL_CONTRACTS:
           if (permission.data.functions.length === 0) {
-            throw new Error(
-              "PERMISSION: FUNCTIONS_ON_ALL_CONTRACTS => No functions provided"
-            );
+            throw new NoFunctionsProvidedError(permission);
           }
           rawHooks[HookIdentifier.PREVAL_ALLOWLIST] = {
             hookConfig: {
@@ -621,14 +603,10 @@ export class PermissionBuilder {
           break;
         case PermissionType.FUNCTIONS_ON_CONTRACT:
           if (permission.data.functions.length === 0) {
-            throw new Error(
-              "PERMISSION: FUNCTIONS_ON_CONTRACT => No functions provided"
-            );
+            throw new NoFunctionsProvidedError(permission);
           }
           if (permission.data.address === zeroAddress) {
-            throw new Error(
-              "PERMISSION: FUNCTIONS_ON_CONTRACT => Zero address provided"
-            );
+            throw new ZeroAddressError(permission);
           }
           rawHooks[HookIdentifier.PREVAL_ALLOWLIST] = {
             hookConfig: {
@@ -659,9 +637,7 @@ export class PermissionBuilder {
           // Root permission handled in addPermission
           break;
         default:
-          throw new Error(
-            `Unsupported permission type: ${(permission as any).type}`
-          );
+          assertNever(permission);
       }
 
       // isGlobal guaranteed to be false since it's only set with root permissions,
@@ -722,3 +698,7 @@ export class PermissionBuilder {
     }
   }
 }
+
+export function assertNever(_valid: never): never {
+  throw new UnsupportedPermissionTypeError();
+}

package/src/ma-v2/permissionBuilderErrors.ts

@@ -0,0 +1,153 @@
+import { BaseError, type Address } from "@aa-sdk/core";
+import type { Permission } from "./permissionBuilder";
+
+export class RootPermissionOnlyError extends BaseError {
+  override name = "PermissionBuilder: RootPermissionOnlyError";
+
+  /**
+   * Constructor for initializing an error message indicating that an account could not be found to execute the specified action.
+   *
+   * @param {Permission} permission The permission trying to be added atop the root permission
+   */
+  constructor(permission: Permission) {
+    super(`Adding ${permission}: Cannot add permissions with ROOT permission`);
+  }
+}
+
+export class AccountAddressAsTargetError extends BaseError {
+  override name = "PermissionBuilder: AccountAddressAsTargetError";
+
+  /**
+   * Constructor for initializing an error message indicating that account address is used as target.
+   *
+   * @param {Permission} permission The permission with account address as target
+   */
+  constructor(permission: Permission) {
+    super(
+      `${permission.type}: Account address as target, use ACCOUNT_FUNCTIONS for account address`
+    );
+  }
+}
+
+export class DuplicateTargetAddressError extends BaseError {
+  override name = "PermissionBuilder: DuplicateTargetAddressError";
+
+  /**
+   * Constructor for initializing an error message indicating duplicate target address in permissions.
+   *
+   * @param {Permission} permission The permission with duplicate target address
+   * @param {Address} targetAddress The duplicate target address
+   */
+  constructor(permission: Permission, targetAddress: Address) {
+    super(
+      `${permission.type}: Address ${targetAddress} already has a permission. Cannot add multiple CONTRACT_ACCESS or FUNCTIONS_ON_CONTRACT permissions for the same target address.`
+    );
+  }
+}
+
+export class NoFunctionsProvidedError extends BaseError {
+  override name = "PermissionBuilder: NoFunctionsProvidedError";
+
+  /**
+   * Constructor for initializing an error message indicating no functions were provided.
+   *
+   * @param {Permission} permission The permission missing functions
+   */
+  constructor(permission: Permission) {
+    super(`${permission.type}: No functions provided`);
+  }
+}
+
+export class ExpiredDeadlineError extends BaseError {
+  override name = "PermissionBuilder: ExpiredDeadlineError";
+
+  /**
+   * Constructor for initializing an error message indicating the deadline has expired.
+   *
+   * @param {number} deadline The expired deadline timestamp
+   * @param {number} currentTime The current timestamp
+   */
+  constructor(deadline: number, currentTime: number) {
+    super(
+      `compileDeferred(): deadline ${deadline} cannot be before now (${currentTime})`
+    );
+  }
+}
+
+export class DeadlineOverLimitError extends BaseError {
+  override name = "PermissionBuilder: DeadlineOverLimitError";
+
+  /**
+   * Constructor for initializing an error message indicating the deadline has expired.
+   *
+   * @param {number} deadline The expired deadline timestamp
+   */
+  constructor(deadline: number) {
+    super(
+      `compileDeferred(): deadline ${deadline} cannot be > max uint48 (2^48 - 1)`
+    );
+  }
+}
+
+export class ValidationConfigUnsetError extends BaseError {
+  override name = "PermissionBuilder: ValidationConfigUnsetError";
+
+  /**
+   * Constructor for initializing an error message indicating the validation config is unset.
+   */
+  constructor() {
+    super("Validation config unset, use permissionBuilder.configure(...)");
+  }
+}
+
+export class MultipleNativeTokenTransferError extends BaseError {
+  override name = "PermissionBuilder: MultipleNativeTokenTransferError";
+
+  /**
+   * Constructor for initializing an error message indicating multiple native token transfer permissions.
+   *
+   * @param {Permission} permission The duplicate native token transfer permission
+   */
+  constructor(permission: Permission) {
+    super(
+      `${permission.type}: Must have at most ONE native token transfer permission`
+    );
+  }
+}
+
+export class ZeroAddressError extends BaseError {
+  override name = "PermissionBuilder: ZeroAddressError";
+
+  /**
+   * Constructor for initializing an error message indicating zero address was provided.
+   *
+   * @param {Permission} permission The permission with zero address
+   */
+  constructor(permission: Permission) {
+    super(`${permission.type}: Zero address provided`);
+  }
+}
+
+export class MultipleGasLimitError extends BaseError {
+  override name = "PermissionBuilder: MultipleGasLimitError";
+
+  /**
+   * Constructor for initializing an error message indicating multiple gas limit permissions.
+   *
+   * @param {Permission} permission The duplicate gas limit permission
+   */
+  constructor(permission: Permission) {
+    super(`${permission.type}: Must have at most ONE gas limit permission`);
+  }
+}
+
+export class UnsupportedPermissionTypeError extends BaseError {
+  override name = "PermissionBuilder: UnsupportedPermissionTypeError";
+
+  /**
+   * Constructor for initializing an error message indicating an unsupported permission type.
+   */
+  constructor() {
+    super(`Unsupported permission type`);
+  }
+}

package/src/ma-v2/utils.ts

@@ -8,6 +8,8 @@ import {
   type Address,
   type Transport,
   parseAbi,
+  size,
+  concatHex,
 } from "viem";
 import {
   arbitrum,
@@ -263,3 +265,46 @@ export const buildFullNonceKey = ({
     (isGlobalValidation ? 1n : 0n)
   );
 };
+
+// Parses out the 3 components from a deferred action
+export const parseDeferredAction = (
+  deferredAction: Hex
+): {
+  nonce: bigint;
+  deferredActionData: Hex;
+  hasAssociatedExecHooks: boolean;
+} => {
+  return {
+    nonce: BigInt(`0x${deferredAction.slice(4, 68)}`),
+    deferredActionData: `0x${deferredAction.slice(68)}`,
+    hasAssociatedExecHooks: deferredAction[3] === "1",
+  };
+};
+export type BuildDeferredActionDigestParams = {
+  fullPreSignatureDeferredActionDigest: Hex;
+  sig: Hex;
+};
+
+/**
+ * Creates the digest which must be prepended to the userOp signature.
+ *
+ * Assumption: The client this extends is used to sign the typed data.
+ *
+ * @param {object} args The argument object containing the following:
+ * @param {Hex} args.fullPreSignatureDeferredActionDigest The The data to append the signature and length to
+ * @param {Hex} args.sig The signature to include in the digest
+ * @returns {Hex} The encoded digest to be prepended to the userOp signature
+ */
+export const buildDeferredActionDigest = ({
+  fullPreSignatureDeferredActionDigest,
+  sig,
+}: BuildDeferredActionDigestParams): Hex => {
+  const sigLength = size(sig);
+
+  const encodedData = concatHex([
+    fullPreSignatureDeferredActionDigest,
+    toHex(sigLength, { size: 4 }),
+    sig,
+  ]);
+  return encodedData;
+};