@alchemy/smart-accounts 0.0.0-alpha.0

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

@@ -0,0 +1,193 @@
+import {
+  concatHex,
+  type Hex,
+  type Client,
+  type Chain,
+  type Transport,
+  encodePacked,
+  size,
+  toHex,
+  maxUint152,
+  encodeDeployData,
+  hexToNumber,
+  isHex,
+  type TypedDataDefinition,
+} from "viem";
+import type { SmartAccount } from "viem/account-abstraction";
+import { entityIdAndNonceReaderAbi } from "../abis/entityIdAndNonceReader.js";
+import { getAction } from "viem/utils";
+import { call } from "viem/actions";
+import { InvalidNonceKeyError } from "../../errors/InvalidNonceKeyError.js";
+import { buildFullNonceKey, isModularAccountV2 } from "../utils/account.js";
+import { AccountNotFoundError, BaseError } from "@alchemy/common";
+
+export const ENTITY_ID_AND_NONCE_READER_BYTECODE =
+  "0x608060405234801561001057600080fd5b506040516104f13803806104f183398101604081905261002f916101e5565b60006008826001600160c01b0316901c90506000808263ffffffff1611610057576001610059565b815b90506001600160a01b0385163b15610133575b60006001600160a01b03861663d31b575b6bffffffff0000000000000000604085901b166040516001600160e01b031960e084901b1681526001600160401b03199091166004820152602401600060405180830381865afa1580156100d5573d6000803e3d6000fd5b505050506040513d6000823e601f3d908101601f191682016040526100fd91908101906103c6565b805190915060ff161580156101155750606081015151155b156101205750610133565b8161012a816104a4565b9250505061006c565b604051631aab3f0d60e11b81526001600160a01b03868116600483015264ffffffff01600160c01b038516600884901b64ffffffff0016176024830152600091908616906335567e1a90604401602060405180830381865afa15801561019d573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906101c191906104d7565b90508060005260206000f35b6001600160a01b03811681146101e257600080fd5b50565b6000806000606084860312156101fa57600080fd5b8351610205816101cd565b6020850151909350610216816101cd565b60408501519092506001600160c01b038116811461023357600080fd5b809150509250925092565b634e487b7160e01b600052604160045260246000fd5b604051608081016001600160401b03811182821017156102765761027661023e565b60405290565b604051601f8201601f191681016001600160401b03811182821017156102a4576102a461023e565b604052919050565b60006001600160401b038211156102c5576102c561023e565b5060051b60200190565b600082601f8301126102e057600080fd5b81516102f36102ee826102ac565b61027c565b8082825260208201915060208360051b86010192508583111561031557600080fd5b602085015b8381101561034857805166ffffffffffffff198116811461033a57600080fd5b83526020928301920161031a565b5095945050505050565b600082601f83011261036357600080fd5b81516103716102ee826102ac565b8082825260208201915060208360051b86010192508583111561039357600080fd5b602085015b838110156103485780516001600160e01b0319811681146103b857600080fd5b835260209283019201610398565b6000602082840312156103d857600080fd5b81516001600160401b038111156103ee57600080fd5b82016080818503121561040057600080fd5b610408610254565b815160ff8116811461041957600080fd5b815260208201516001600160401b0381111561043457600080fd5b610440868285016102cf565b60208301525060408201516001600160401b0381111561045f57600080fd5b61046b868285016102cf565b60408301525060608201516001600160401b0381111561048a57600080fd5b61049686828501610352565b606083015250949350505050565b600063ffffffff821663ffffffff81036104ce57634e487b7160e01b600052601160045260246000fd5b60010192915050565b6000602082840312156104e957600080fd5b505191905056fe";
+
+export type DeferredActionTypedData = TypedDataDefinition<
+  {
+    DeferredAction: [
+      { name: "nonce"; type: "uint256" },
+      { name: "deadline"; type: "uint48" },
+      { name: "call"; type: "bytes" },
+    ];
+  },
+  "DeferredAction"
+>;
+
+export type DeferredActionReturnData = {
+  typedData: DeferredActionTypedData;
+};
+
+export type CreateDeferredActionTypedDataParams = {
+  callData: Hex;
+  deadline: number;
+  nonce: bigint;
+};
+
+export type BuildPreSignatureDeferredActionDigestParams = {
+  typedData: DeferredActionTypedData;
+};
+
+export type EntityIdAndNonceParams = {
+  entityId?: number;
+  nonceKey?: bigint;
+  isGlobalValidation: boolean;
+  isDeferredAction?: boolean;
+};
+
+export type DeferralActions = {
+  createDeferredActionTypedDataObject: (
+    args: CreateDeferredActionTypedDataParams,
+  ) => Promise<DeferredActionReturnData>;
+  buildPreSignatureDeferredActionDigest: (
+    args: BuildPreSignatureDeferredActionDigestParams,
+  ) => Hex;
+  getEntityIdAndNonce: (
+    args: EntityIdAndNonceParams,
+  ) => Promise<{ nonce: bigint; entityId: number }>;
+};
+
+/**
+ * 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`.
+ */
+export const deferralActions = <
+  TTransport extends Transport = Transport,
+  TChain extends Chain = Chain,
+  TAccount extends SmartAccount = SmartAccount,
+>(
+  client: Client<TTransport, TChain, TAccount>,
+): DeferralActions => {
+  const createDeferredActionTypedDataObject = async ({
+    callData,
+    deadline,
+    nonce,
+  }: CreateDeferredActionTypedDataParams): Promise<DeferredActionReturnData> => {
+    const account = client.account;
+    if (!account || !isModularAccountV2(account)) {
+      throw new AccountNotFoundError();
+    }
+
+    return {
+      typedData: {
+        domain: {
+          chainId: client.chain.id,
+          verifyingContract: client.account.address,
+        },
+        types: {
+          DeferredAction: [
+            { name: "nonce", type: "uint256" },
+            { name: "deadline", type: "uint48" },
+            { name: "call", type: "bytes" },
+          ],
+        },
+        primaryType: "DeferredAction",
+        message: {
+          nonce: nonce,
+          deadline: deadline,
+          call: callData,
+        },
+      },
+    };
+  };
+
+  const buildPreSignatureDeferredActionDigest = ({
+    typedData,
+  }: BuildPreSignatureDeferredActionDigestParams): Hex => {
+    const account = client.account;
+    if (!account || !isModularAccountV2(account)) {
+      throw new AccountNotFoundError();
+    }
+
+    const signerEntity = account.signerEntity;
+    const validationLocator =
+      (BigInt(signerEntity.entityId) << 8n) |
+      (signerEntity.isGlobalValidation ? 1n : 0n);
+
+    const encodedCallData = encodePacked(
+      ["uint168", "uint48", "bytes"],
+      [validationLocator, typedData.message.deadline, typedData.message.call],
+    );
+
+    const encodedDataLength = size(encodedCallData);
+    const encodedData = concatHex([
+      toHex(encodedDataLength, { size: 4 }),
+      encodedCallData,
+    ]);
+    return encodedData;
+  };
+
+  const getEntityIdAndNonce = async ({
+    entityId = 1,
+    nonceKey = 0n,
+    isGlobalValidation,
+    isDeferredAction = true,
+  }: EntityIdAndNonceParams) => {
+    const account = client.account;
+    if (!account || !isModularAccountV2(account)) {
+      throw new AccountNotFoundError();
+    }
+
+    if (nonceKey > maxUint152) {
+      throw new InvalidNonceKeyError(nonceKey);
+    }
+
+    const bytecode = encodeDeployData({
+      abi: entityIdAndNonceReaderAbi,
+      bytecode: ENTITY_ID_AND_NONCE_READER_BYTECODE,
+      args: [
+        account.address,
+        account.entryPoint.address,
+        buildFullNonceKey({
+          nonceKey,
+          entityId,
+          isGlobalValidation,
+          isDeferredAction,
+        }),
+      ],
+    });
+
+    const action = getAction(client, call, "call");
+    const { data } = await action({ data: bytecode });
+    if (!data) {
+      throw new BaseError("No data returned from contract call");
+    }
+    if (!isHex(data)) {
+      throw new BaseError("Expected hex data from contract call");
+    }
+
+    return {
+      nonce: BigInt(data),
+      entityId: hexToNumber(`0x${data.slice(40, 48)}`),
+    };
+  };
+
+  return {
+    createDeferredActionTypedDataObject,
+    buildPreSignatureDeferredActionDigest,
+    getEntityIdAndNonce,
+  };
+};

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

@@ -0,0 +1,257 @@
+import {
+  type Address,
+  type Client,
+  type Hex,
+  type IsUndefined,
+  type Chain,
+  type Transport,
+  zeroAddress,
+  concatHex,
+  encodeFunctionData,
+} from "viem";
+import type { HookConfig, ValidationConfig } from "../types.js";
+import type { ModularAccountV2 } from "../accounts/account.js";
+import type { GetAccountParameter } from "../../types.js";
+import { semiModularAccountBytecodeAbi } from "../abis/semiModularAccountBytecodeAbi.js";
+import { type SmartAccount, sendUserOperation } from "viem/account-abstraction";
+import { getAction } from "viem/utils";
+import { AccountNotFoundError } from "@alchemy/common";
+import { EntityIdOverrideError } from "../../errors/EntityIdOverrideError.js";
+import {
+  serializeHookConfig,
+  serializeValidationConfig,
+} from "../utils/hooks.js";
+import {
+  DEFAULT_OWNER_ENTITY_ID,
+  isModularAccountV2,
+  serializeModuleEntity,
+} from "../utils/account.js";
+
+export type InstallValidationParams<
+  TAccount extends SmartAccount | undefined = SmartAccount | undefined,
+> = {
+  validationConfig: ValidationConfig;
+  selectors: Hex[];
+  installData: Hex;
+  hooks: {
+    hookConfig: HookConfig;
+    initData: Hex;
+  }[];
+} & GetAccountParameter<TAccount, ModularAccountV2>;
+
+export type UninstallValidationParams<
+  TAccount extends SmartAccount | undefined = SmartAccount | undefined,
+> = {
+  moduleAddress: Address;
+  entityId: number;
+  uninstallData: Hex;
+  hookUninstallDatas: Hex[];
+} & GetAccountParameter<TAccount, ModularAccountV2>;
+
+export type InstallValidationActions<
+  TAccount extends SmartAccount | undefined = SmartAccount | undefined,
+> = {
+  encodeInstallValidation: (
+    args: InstallValidationParams<TAccount>,
+  ) => Promise<Hex>;
+  installValidation: (args: InstallValidationParams<TAccount>) => Promise<Hex>;
+  encodeUninstallValidation: (
+    args: UninstallValidationParams<TAccount>,
+  ) => Promise<Hex>;
+  uninstallValidation: (
+    args: UninstallValidationParams<TAccount>,
+  ) => Promise<Hex>;
+};
+
+// TODO(v5): update jsdoc
+/**
+ * Provides validation installation and uninstallation functionalities for a MA v2 client, ensuring compatibility with `SmartAccountClient`.
+ *
+ * @example
+ * ```ts
+ * import { createModularAccountV2Client, installValidationActions, getDefaultSingleSignerValidationModuleAddress, SingleSignerValidationModule } from "@alchemy/smart-accounts";
+ * import { Address } from "viem";
+ *
+ * const client = (await createModularAccountV2Client({ ... })).extend(installValidationActions);
+ * const sessionKeyAddress: Address = "0x1234";
+ * const sessionKeyEntityId: number = 1;
+ *
+ * await client.installValidation({
+ *   validationConfig: {
+ *     moduleAddress: getDefaultSingleSignerValidationModuleAddress(
+ *       client.chain
+ *     ),
+ *     entityId: sessionKeyEntityId,
+ *     isGlobal: true,
+ *     isSignatureValidation: false,
+ *     isUserOpValidation: true,
+ *   },
+ *   selectors: [],
+ *   installData: SingleSignerValidationModule.encodeOnInstallData({
+ *     entityId: sessionKeyEntityId,
+ *     signer: sessionKeyAddress,
+ *   }),
+ *   hooks: [],
+ * });
+ *
+ * await client.uninstallValidation({
+ *   moduleAddress: sessionKeyAddress,
+ *   entityId: sessionKeyEntityId,
+ *   uninstallData: SingleSignerValidationModule.encodeOnUninstallData({
+ *     entityId: sessionKeyEntityId,
+ *   }),
+ *   hookUninstallDatas: [],
+ * });
+ *
+ * ```
+ *
+ * @param {object} client - The client instance which provides account and sendUserOperation functionality.
+ * @returns {object} - An object containing two methods, `installValidation` and `uninstallValidation`.
+ */
+export function installValidationActions<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartAccount | undefined = SmartAccount | undefined,
+>(
+  client: Client<TTransport, TChain, TAccount>,
+): InstallValidationActions<
+  IsUndefined<TAccount> extends true ? undefined : ModularAccountV2
+> {
+  const encodeInstallValidation = async (
+    args: InstallValidationParams<
+      IsUndefined<TAccount> extends true ? undefined : ModularAccountV2
+    >,
+  ) => {
+    const {
+      validationConfig,
+      selectors,
+      installData,
+      hooks,
+      account = client.account,
+    } = args;
+
+    if (!account || !isModularAccountV2(account)) {
+      throw new AccountNotFoundError();
+    }
+
+    // An entityId of zero is only allowed if we're installing or uninstalling hooks on the fallback validation.
+    if (
+      validationConfig.entityId === DEFAULT_OWNER_ENTITY_ID &&
+      validationConfig.moduleAddress !== zeroAddress
+    ) {
+      throw new EntityIdOverrideError();
+    }
+
+    return account.encodeCallData(
+      encodeFunctionData({
+        abi: semiModularAccountBytecodeAbi,
+        functionName: "installValidation",
+        args: [
+          serializeValidationConfig(validationConfig),
+          selectors,
+          installData,
+          hooks.map((hook: { hookConfig: HookConfig; initData: Hex }) =>
+            concatHex([serializeHookConfig(hook.hookConfig), hook.initData]),
+          ),
+        ],
+      }),
+    );
+  };
+
+  const encodeUninstallValidation = async (
+    args: UninstallValidationParams<
+      IsUndefined<TAccount> extends true ? undefined : ModularAccountV2
+    >,
+  ) => {
+    const {
+      moduleAddress,
+      entityId,
+      uninstallData,
+      hookUninstallDatas,
+      account = client.account,
+    } = args;
+
+    if (!account || !isModularAccountV2(account)) {
+      throw new AccountNotFoundError();
+    }
+
+    return account.encodeCallData(
+      encodeFunctionData({
+        abi: semiModularAccountBytecodeAbi,
+        functionName: "uninstallValidation",
+        args: [
+          serializeModuleEntity({
+            moduleAddress,
+            entityId,
+          }),
+          uninstallData,
+          hookUninstallDatas,
+        ],
+      }),
+    );
+  };
+
+  return {
+    encodeInstallValidation,
+    encodeUninstallValidation,
+    installValidation: async (args) => {
+      const {
+        validationConfig,
+        selectors,
+        installData,
+        hooks,
+        account = client.account,
+      } = args;
+
+      if (!account || !isModularAccountV2(account)) {
+        throw new AccountNotFoundError();
+      }
+
+      const callData = await encodeInstallValidation({
+        validationConfig,
+        selectors,
+        installData,
+        hooks,
+        account,
+      });
+
+      const action = getAction(client, sendUserOperation, "sendUserOperation");
+      const result = await action({
+        callData,
+        account,
+      });
+
+      return result;
+    },
+
+    uninstallValidation: async (args) => {
+      const {
+        moduleAddress,
+        entityId,
+        uninstallData,
+        hookUninstallDatas,
+        account = client.account,
+      } = args;
+
+      if (!account || !isModularAccountV2(account)) {
+        throw new AccountNotFoundError();
+      }
+
+      const callData = await encodeUninstallValidation({
+        moduleAddress,
+        entityId,
+        uninstallData,
+        hookUninstallDatas,
+        account,
+      });
+
+      const action = getAction(client, sendUserOperation, "sendUserOperation");
+      const result = await action({
+        callData,
+        account,
+      });
+
+      return result;
+    },
+  };
+}

package/src/ma-v2/mav2StaticImpl.ts

@@ -0,0 +1,134 @@
+import { encodeFunctionData, type Address, type Hex } from "viem";
+import { entryPoint07Abi, entryPoint07Address } from "viem/account-abstraction";
+import { lowerAddress } from "@alchemy/common";
+import type { StaticSmartAccountImplementation } from "../types.js";
+import { semiModularAccountBytecodeAbi } from "./abis/semiModularAccountBytecodeAbi.js";
+import { accountFactoryAbi } from "./abis/accountFactoryAbi.js";
+import { webAuthnFactoryAbi } from "./abis/webAuthnFactoryAbi.js";
+import { DefaultAddress as DefaultMAV2Address } from "./utils/account.js";
+import { predictModularAccountV2Address } from "./predictAddress.js";
+import { modularAccountAbi } from "./abis/modularAccountAbi.js";
+import { parsePublicKey } from "webauthn-p256";
+
+export type SemiModularAccountV2FactoryArgs = {
+  owner: Address;
+  salt: bigint;
+};
+
+export type SemiModularAccountV2StaticImpl = StaticSmartAccountImplementation<
+  false,
+  "0.7",
+  SemiModularAccountV2FactoryArgs,
+  typeof entryPoint07Abi,
+  typeof semiModularAccountBytecodeAbi,
+  typeof accountFactoryAbi
+>;
+
+// Shared entryPoint configuration across all modular account v2 implementations
+const entryPoint = {
+  abi: entryPoint07Abi,
+  address: entryPoint07Address,
+  version: "0.7",
+} as const;
+
+// Shared base for semi-modular account implementations (SMA and 7702)
+const semiModularAccountBase = {
+  entryPoint,
+  accountAbi: semiModularAccountBytecodeAbi,
+} satisfies Partial<SemiModularAccountV2StaticImpl>;
+
+/**
+ * Static implementation logic for SemiModularAccountV2.
+ *
+ * TODO(v5): update JSDoc format when doc-gen supports structs or records.
+ */
+export const semiModularAccountV2StaticImpl: SemiModularAccountV2StaticImpl = {
+  ...semiModularAccountBase,
+  accountImplementation: lowerAddress(DefaultMAV2Address.SMAV2_BYTECODE),
+  factoryAddress: lowerAddress(DefaultMAV2Address.MAV2_FACTORY),
+  factoryAbi: accountFactoryAbi,
+  getFactoryData: (args: SemiModularAccountV2FactoryArgs) => {
+    return encodeFunctionData({
+      abi: accountFactoryAbi,
+      functionName: "createSemiModularAccount",
+      args: [args.owner, args.salt],
+    });
+  },
+  predictAccountAddress: (args: SemiModularAccountV2FactoryArgs) => {
+    return predictModularAccountV2Address({
+      factoryAddress: DefaultMAV2Address.MAV2_FACTORY,
+      implementationAddress: DefaultMAV2Address.SMAV2_BYTECODE,
+      type: "SMA",
+      salt: args.salt,
+      ownerAddress: args.owner,
+    });
+  },
+};
+
+export type SemiModularAccount7702StaticImpl = StaticSmartAccountImplementation<
+  true,
+  "0.7",
+  SemiModularAccountV2FactoryArgs,
+  typeof entryPoint07Abi,
+  typeof semiModularAccountBytecodeAbi,
+  typeof accountFactoryAbi
+>;
+
+/**
+ * Static implementation logic for SemiModularAccount7702.
+ *
+ * TODO(v5): update JSDoc format when doc-gen supports structs or records.
+ */
+export const semiModularAccount7702StaticImpl: SemiModularAccount7702StaticImpl =
+  {
+    ...semiModularAccountBase,
+    delegationAddress: lowerAddress(DefaultMAV2Address.SMAV2_7702),
+  };
+
+export type WebAuthnModularAccountV2FactoryArgs = {
+  ownerPublicKey: Hex;
+  salt: bigint;
+  entityId: number;
+};
+
+export type WebAuthnModularAccountV2StaticImpl =
+  StaticSmartAccountImplementation<
+    false,
+    "0.7",
+    WebAuthnModularAccountV2FactoryArgs,
+    typeof entryPoint07Abi,
+    typeof modularAccountAbi,
+    typeof webAuthnFactoryAbi
+  >;
+
+/**
+ * Static implementation logic for WebAuthnModularAccountV2.
+ *
+ * TODO(v5): update JSDoc format when doc-gen supports structs or records.
+ */
+export const webAuthnModularAccountV2StaticImpl: WebAuthnModularAccountV2StaticImpl =
+  {
+    entryPoint,
+    accountAbi: modularAccountAbi,
+    accountImplementation: lowerAddress(DefaultMAV2Address.MAV2),
+    factoryAddress: lowerAddress(DefaultMAV2Address.MAV2_FACTORY_WEBAUTHN),
+    factoryAbi: webAuthnFactoryAbi,
+    getFactoryData: (args: WebAuthnModularAccountV2FactoryArgs) => {
+      const { x, y } = parsePublicKey(args.ownerPublicKey);
+      return encodeFunctionData({
+        abi: webAuthnFactoryAbi,
+        functionName: "createWebAuthnAccount",
+        args: [x, y, args.salt, args.entityId],
+      });
+    },
+    predictAccountAddress: (args: WebAuthnModularAccountV2FactoryArgs) => {
+      return predictModularAccountV2Address({
+        factoryAddress: DefaultMAV2Address.MAV2_FACTORY_WEBAUTHN,
+        implementationAddress: DefaultMAV2Address.MAV2,
+        type: "WebAuthn",
+        salt: args.salt,
+        ownerPublicKey: args.ownerPublicKey,
+        entityId: args.entityId,
+      });
+    },
+  };