@alchemy/smart-accounts 0.0.0-alpha.0

package/src/ma-v2/predictAddress.ts

@@ -0,0 +1,149 @@
+import { assertNever } from "@alchemy/common";
+import {
+  concatHex,
+  encodePacked,
+  getContractAddress,
+  keccak256,
+  type Address,
+  type Hex,
+} from "viem";
+import { parsePublicKey } from "webauthn-p256";
+
+export type PredictModularAccountV2AddressParams = {
+  factoryAddress: Address;
+  implementationAddress: Address; // Should be the implementation address of the account type you are predicting the address for.
+  salt: bigint;
+} & (
+  | {
+      type: "MA";
+      ownerAddress: Address;
+      entityId: number;
+    }
+  | {
+      type: "SMA";
+      ownerAddress: Address;
+    }
+  | {
+      type: "WebAuthn";
+      ownerPublicKey: Hex;
+      entityId: number;
+    }
+);
+
+/**
+ * Predicts the address of a modular account V2 based on the provided parameters, which include factory address, salt, and implementation address. This function supports different types of accounts including "SMA", "MA", and "WebAuthn".
+ *
+ * @example
+ * ```ts
+ * import { predictModularAccountV2Address } from "@alchemy/smart-accounts";
+ *
+ * const accountAddress = predictModularAccountV2Address({
+ *   factoryAddress: "0xFactoryAddress" as Address,
+ *   implementationAddress: "0xImplementation" as Address,
+ *   salt: 0n,
+ *   type: "SMA",
+ *   ownerAddress: "0xOwner" as Address,
+ * });
+ * ```
+ *
+ * @param {PredictModularAccountV2AddressParams} params The parameters for predicting the modular account address, including `factoryAddress`, `salt`, `implementationAddress`, and additional properties based on the account type.
+ * @returns {Address} The predicted address for the modular account V2.
+ */
+export function predictModularAccountV2Address(
+  params: PredictModularAccountV2AddressParams,
+): Address {
+  const { factoryAddress, salt, implementationAddress } = params;
+
+  // Note(v4): prediction for MA is currently untested, because it is not supported as an account type yet.
+  // Prior to using this prediction logic, ensure that the counterfactual computation is correct by updating `predictAddress.test.ts` to include a test for MA.
+  const { combinedSalt, initcode } = (() => {
+    switch (params.type) {
+      case "SMA":
+        // MAv2 factory uses max uint32 for SMA entityId
+        return {
+          combinedSalt: getCombinedSaltK1(
+            params.ownerAddress,
+            salt,
+            0xffffffff,
+          ),
+          initcode: getProxyBytecodeWithImmutableArgs(
+            implementationAddress,
+            params.ownerAddress,
+          ),
+        };
+      case "MA":
+        return {
+          combinedSalt: getCombinedSaltK1(
+            params.ownerAddress,
+            salt,
+            params.entityId,
+          ),
+          initcode: getProxyBytecode(implementationAddress),
+        };
+      case "WebAuthn":
+        const { x, y } = parsePublicKey(params.ownerPublicKey);
+        return {
+          combinedSalt: getCombinedSaltWebAuthn(
+            { x, y },
+            salt,
+            params.entityId,
+          ),
+          initcode: getProxyBytecode(implementationAddress),
+        };
+      default:
+        return assertNever(params, "Unexpected MAv2 type");
+    }
+  })();
+
+  return getContractAddress({
+    from: factoryAddress,
+    opcode: "CREATE2",
+    salt: combinedSalt,
+    bytecode: initcode,
+  });
+}
+
+function getCombinedSaltK1(
+  ownerAddress: Address,
+  salt: bigint,
+  entityId: number,
+): Hex {
+  return keccak256(
+    encodePacked(
+      ["address", "uint256", "uint32"],
+      [ownerAddress, salt, entityId],
+    ),
+  );
+}
+
+function getCombinedSaltWebAuthn(
+  ownerPublicKey: { x: bigint; y: bigint },
+  salt: bigint,
+  entityId: number,
+): Hex {
+  return keccak256(
+    encodePacked(
+      ["uint256", "uint256", "uint256", "uint32"],
+      [ownerPublicKey.x, ownerPublicKey.y, salt, entityId],
+    ),
+  );
+}
+
+function getProxyBytecode(implementationAddress: Address): Hex {
+  return concatHex([
+    "0x603d3d8160223d3973",
+    implementationAddress,
+    "0x60095155f3363d3d373d3d363d7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e6038573d6000fd5b3d6000f3",
+  ]);
+}
+
+function getProxyBytecodeWithImmutableArgs(
+  implementationAddress: Address,
+  immutableArgs: Hex,
+): Hex {
+  return `0x6100513d8160233d3973${implementationAddress.slice(
+    2,
+  )}60095155f3363d3d373d3d363d7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e6038573d6000fd5b3d6000f3${immutableArgs.slice(
+    2,
+  )}`;
+}

package/src/ma-v2/types.ts

@@ -0,0 +1,73 @@
+import type { Address, Hex } from "viem";
+
+export const SignaturePrefix = {
+  EOA: "0x00",
+  CONTRACT: "0x01",
+} as const;
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type SignaturePrefix =
+  (typeof SignaturePrefix)[keyof typeof SignaturePrefix];
+
+export type SignerEntity = {
+  isGlobalValidation: boolean;
+  entityId: number;
+};
+
+export type ExecutionDataView = {
+  module: Address;
+  skipRuntimeValidation: boolean;
+  allowGlobalValidation: boolean;
+  executionHooks: readonly Hex[];
+};
+
+export type ValidationDataView = {
+  validationHooks: readonly Hex[];
+  executionHooks: readonly Hex[];
+  selectors: readonly Hex[];
+  validationFlags: number;
+};
+
+export type ModuleEntity = {
+  moduleAddress: Address;
+  entityId: number;
+};
+
+export type ValidationConfig = {
+  moduleAddress: Address;
+  entityId: number; // uint32
+  isGlobal: boolean;
+  isSignatureValidation: boolean;
+  isUserOpValidation: boolean;
+};
+
+export const HookType = {
+  EXECUTION: "0x00",
+  VALIDATION: "0x01",
+} as const;
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type HookType = (typeof HookType)[keyof typeof HookType];
+
+export type HookConfig = {
+  address: Address;
+  entityId: number; // uint32
+  hookType: HookType;
+  hasPreHooks: boolean;
+  hasPostHooks: boolean;
+};
+
+// maps to type ValidationStorage in MAv2 implementation
+export type ValidationData = {
+  isGlobal: boolean; // validation flag
+  isSignatureValidation: boolean; // validation flag
+  isUserOpValidation: boolean;
+  validationHooks: HookConfig[];
+  executionHooks: Hex[];
+  selectors: Hex[];
+};
+
+export type UpgradeToData = {
+  implAddress: Address;
+  initializationData: Hex;
+};

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

@@ -0,0 +1,137 @@
+import {
+  concatHex,
+  encodeFunctionData,
+  toHex,
+  type Address,
+  type Hex,
+} from "viem";
+import type { SmartAccount } from "viem/account-abstraction";
+import type { GetAccountParameter } from "../../types.js";
+import type { ModuleEntity, UpgradeToData } from "../types.js";
+import { semiModularAccountStorageAbi } from "../abis/semiModularAccountStorageAbi.js";
+import type { ModularAccountV2Base } from "../accounts/base.js";
+
+/**
+ * A mapping of default addresses for the ModularAccountV2.
+ */
+export const DefaultAddress = {
+  MAV2_FACTORY: "0x00000000000017c61b5bEe81050EC8eFc9c6fecd",
+  MAV2_FACTORY_WEBAUTHN: "0x55010E571dCf07e254994bfc88b9C1C8FAe31960",
+  SMAV2_BYTECODE: "0x000000000000c5A9089039570Dd36455b5C07383",
+  SMAV2_STORAGE: "0x0000000000006E2f9d80CaEc0Da6500f005EB25A",
+  SMAV2_7702: "0x69007702764179f14F51cdce752f4f775d74E139",
+  MAV2: "0x00000000000002377B26b1EdA7b0BC371C60DD4f",
+} satisfies Record<string, Address>;
+
+/**
+ * A mapping of default addresses for the ModularAccountV2 modules.
+ */
+export const DefaultModuleAddress = {
+  SINGLE_SIGNER_VALIDATION: "0x00000000000099DE0BF6fA90dEB851E2A2df7d83",
+  WEBAUTHN_VALIDATION: "0x0000000000001D9d34E07D9834274dF9ae575217",
+  TIME_RANGE: "0x00000000000082B8e2012be914dFA4f62A0573eA",
+  PAYMASTER_GUARD: "0x0000000000001aA7A7F7E29abe0be06c72FD42A1",
+  NATIVE_TOKEN_LIMIT: "0x00000000000001e541f0D090868FBe24b59Fbe06",
+  ALLOWLIST: "0x00000000003e826473a313e600b5b9b791f5a59a",
+} satisfies Record<string, Address>;
+
+/**
+ * The default owner entity ID.
+ */
+export const DEFAULT_OWNER_ENTITY_ID = 0;
+
+/**
+ * The selector for the execute user operation function.
+ */
+export const EXECUTE_USER_OP_SELECTOR: Hex = "0x8DD7712F";
+
+export type GetMAV2UpgradeToData<
+  TAccount extends SmartAccount | undefined = SmartAccount | undefined,
+> = GetAccountParameter<TAccount>;
+
+/**
+ * Gets the upgrade to data for the ModularAccountV2.
+ *
+ * @param {Address} ownerAddress - The address of the owner.
+ * @returns {Promise<UpgradeToData>} The upgrade to data.
+ */
+export async function getMAV2UpgradeToData(
+  ownerAddress: Address,
+): Promise<UpgradeToData> {
+  const initData = encodeFunctionData({
+    abi: semiModularAccountStorageAbi,
+    functionName: "initialize",
+    args: [ownerAddress],
+  });
+
+  return {
+    implAddress: DefaultAddress.SMAV2_STORAGE,
+    initializationData: initData,
+    // TODO(v5): do we need `createModularAccountV2FromExisting()` in the return type here like we had in v4 or no?
+    // Almost certainly not, but we need to clean up other parts in SDK for client-side upgrades.
+  };
+}
+
+export type BuildNonceParams = {
+  nonceKey?: bigint;
+  entityId?: number;
+  isGlobalValidation?: boolean;
+  isDeferredAction?: boolean;
+  isDirectCallValidation?: boolean;
+};
+
+/**
+ * Builds a full nonce key.
+ *
+ * @param {BuildNonceParams} params - The parameters for building a full nonce key.
+ * @returns {bigint} The full nonce key.
+ */
+export const buildFullNonceKey = ({
+  nonceKey = 0n,
+  entityId = 0,
+  isGlobalValidation = true,
+  isDeferredAction = false,
+}: BuildNonceParams): bigint => {
+  return (
+    (nonceKey << 40n) +
+    (BigInt(entityId) << 8n) +
+    (isDeferredAction ? 2n : 0n) +
+    (isGlobalValidation ? 1n : 0n)
+  );
+};
+
+/**
+ * Serializes a module entity into a hexadecimal format by concatenating the module address and entity ID.
+ *
+ * @example
+ * ```ts
+ * import { serializeModuleEntity } from "@alchemy/smart-accounts";
+ * import { Address } from "viem";
+ *
+ * const moduleAddress: Address = "0x1234";
+ * const entityId: number = 1234;
+ *
+ * const moduleEntityHex = serializeModuleEntity({
+ *  moduleAddress,
+ *  entityId
+ * });
+ * ```
+ *
+ * @param {ModuleEntity} config The module entity configuration containing the module address and entity ID
+ * @returns {Hex} A hexadecimal string representation of the serialized module entity
+ */
+export function serializeModuleEntity(config: ModuleEntity): Hex {
+  return concatHex([config.moduleAddress, toHex(config.entityId, { size: 4 })]);
+}
+
+/**
+ * Checks if an account is a ModularAccountV2.
+ *
+ * @param {SmartAccount} account - The account to check.
+ * @returns {boolean} True if the account is a ModularAccountV2, false otherwise.
+ */
+export function isModularAccountV2(
+  account: SmartAccount,
+): account is ModularAccountV2Base {
+  return "source" in account && account.source === "ModularAccountV2";
+}

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

@@ -0,0 +1,66 @@
+import {
+  concatHex,
+  hexToNumber,
+  parseErc6492Signature,
+  size,
+  toHex,
+  type Hex,
+} from "viem";
+import { SignaturePrefix } from "../types.js";
+
+/**
+ * Parses out the 3 components from a deferred action.
+ *
+ * @param {Hex} deferredAction - The deferred action to parse.
+ * @returns {object} The parsed deferred action.
+ */
+export const parseDeferredAction = (
+  deferredAction: Hex,
+): {
+  entityId: number;
+  isGlobalValidation: boolean;
+  nonce: bigint;
+  deferredActionData: Hex;
+  hasAssociatedExecHooks: boolean;
+} => {
+  // 2 for 0x, 2 for 00/01, 38 for parallel nonce, 8 for entity id, 2 for options byte, 16 for parallel nonce
+  return {
+    entityId: hexToNumber(`0x${deferredAction.slice(42, 50)}`),
+    isGlobalValidation:
+      hexToNumber(`0x${deferredAction.slice(50, 52)}`) % 2 === 1,
+    nonce: BigInt(`0x${deferredAction.slice(4, 68)}`),
+    deferredActionData: `0x${deferredAction.slice(68)}` as Hex,
+    hasAssociatedExecHooks: deferredAction[3] === "1",
+  };
+};
+
+export type BuildDeferredActionDigestParams = {
+  fullPreSignatureDeferredActionDigest: Hex;
+  sig: Hex;
+  signaturePrefix?: SignaturePrefix;
+};
+
+/**
+ * Creates the digest which must be prepended 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.
+ */
+export const buildDeferredActionDigest = ({
+  fullPreSignatureDeferredActionDigest,
+  sig,
+}: BuildDeferredActionDigestParams): Hex => {
+  // 6492 sigs don't work here.
+  const _sig = parseErc6492Signature(sig).signature;
+
+  const sigLength = size(_sig);
+
+  const encodedData = concatHex([
+    fullPreSignatureDeferredActionDigest,
+    toHex(sigLength, { size: 4 }),
+    _sig,
+  ]);
+  return encodedData;
+};

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

@@ -0,0 +1,79 @@
+import { concatHex, toHex, type Hex } from "viem";
+import { HookType, type HookConfig, type ValidationConfig } from "../types.js";
+import { serializeModuleEntity } from "./account.js";
+
+/**
+ * Serializes a validation configuration into a hexadecimal string representation. This involves converting boolean flags into bitwise representation and combining them with serialized module entity data.
+ *
+ * @example
+ * ```ts
+ * import { serializeValidationConfig } from "@alchemy/smart-accounts";
+ * import { Address } from "viem";
+ *
+ * const moduleAddress: Address = "0x1234";
+ * const entityId: number = 1234;
+ * const isGlobal: boolean = true;
+ * const isSignatureValidation: boolean = false;
+ * const isUserOpValidation: boolean = true;
+ *
+ * const validationConfigHex = serializeValidationConfig({
+ *  moduleAddress,
+ *  entityId,
+ *  isGlobal,
+ *  isSignatureValidation,
+ *  isUserOpValidation
+ * });
+ * ```
+ * @param {ValidationConfig} config The validation configuration object containing details to serialize
+ * @returns {Hex} A hexadecimal string representing the serialized configuration
+ */
+export function serializeValidationConfig(config: ValidationConfig): Hex {
+  const isUserOpValidationBit = config.isUserOpValidation ? 1 : 0;
+  const isSignatureValidationBit = config.isSignatureValidation ? 2 : 0;
+  const isGlobalBit = config.isGlobal ? 4 : 0;
+  return concatHex([
+    serializeModuleEntity(config),
+    toHex(isUserOpValidationBit + isSignatureValidationBit + isGlobalBit, {
+      size: 1,
+    }),
+  ]);
+}
+
+/**
+ * Serializes a `HookConfig` object into a `Hex` format by encoding the hook type, presence of post/pre hooks, address, and entity ID.
+ *
+ * @example
+ * ```ts
+ * import { type HookType, serializeHookConfig } from "@alchemy/smart-accounts";
+ * import { Address } from "viem";
+ *
+ * const moduleAddress: Address = "0x1234";
+ * const entityId: number = 1234;
+ * const hookType: HookType = HookType.Validation;
+ * const hasPostHooks: boolean = false;
+ * const hasPreHooks: boolean = true;
+ *
+ * const hookConfigHex = serializeHookConfig({
+ *  moduleAddress,
+ *  entityId,
+ *  hookType,
+ *  hasPostHooks,
+ *  hasPreHooks
+ * });
+ * ```
+ *
+ * @param {HookConfig} config The hook configuration containing address, entity ID, hook type, and post/pre hook indicators
+ * @returns {Hex} The serialized hook configuration in hexadecimal format
+ */
+export function serializeHookConfig(config: HookConfig): Hex {
+  const hookTypeBit = config.hookType === HookType.VALIDATION ? 1 : 0;
+  const hasPostHooksBit = config.hasPostHooks ? 2 : 0;
+  const hasPreHooksBit = config.hasPreHooks ? 4 : 0;
+  return concatHex([
+    config.address,
+    toHex(config.entityId, { size: 4 }),
+    toHex(hookTypeBit + hasPostHooksBit + hasPreHooksBit, {
+      size: 1,
+    }),
+  ]);
+}

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

@@ -0,0 +1,129 @@
+import {
+  concatHex,
+  encodeAbiParameters,
+  toHex,
+  type Address,
+  type Hash,
+  type Hex,
+} from "viem";
+import { SignaturePrefix } from "../types.js";
+import { Signature, type WebAuthnP256 } from "ox";
+
+export type PackUOSignatureParams = {
+  // orderedHookData: HookData[];
+  validationSignature: Hex;
+};
+
+/**
+ * Signature packing utility for user operations.
+ *
+ * @param {PackUOSignatureParams} params - The parameters for packing a user operation signature.
+ * @returns {Hex} The packed user operation signature.
+ */
+export const packUOSignature = ({
+  // orderedHookData, TODO: integrate in next iteration of MAv2 sdk
+  validationSignature,
+}: PackUOSignatureParams): Hex => {
+  return concatHex(["0xFF", "0x00", validationSignature]);
+};
+
+// TODO(v4): direct call validation 1271
+export type Pack1271SignatureParams = {
+  entityId: number;
+  validationSignaturePrefix: SignaturePrefix | null;
+  validationSignature: Hex;
+};
+
+/**
+ * Signature packing utility for 1271 signatures.
+ *
+ * @param {Pack1271SignatureParams} params - The parameters for packing a 1271 signature.
+ * @returns {Hex} The packed 1271 signature.
+ */
+export const pack1271Signature = ({
+  entityId,
+  validationSignaturePrefix,
+  validationSignature,
+}: Pack1271SignatureParams): Hex => {
+  return concatHex([
+    "0x00",
+    toHex(entityId, { size: 4 }),
+    "0xFF",
+    ...(validationSignaturePrefix ? [validationSignaturePrefix] : []),
+    validationSignature,
+  ]);
+};
+
+/**
+ * Converts a hash to a replay safe typed data.
+ *
+ * @param {ToReplaySafeTypedDataParams} params - The parameters for converting a hash to a replay safe typed data.
+ * @returns {object} The replay safe typed data.
+ */
+export function toReplaySafeTypedData({
+  address,
+  chainId,
+  hash,
+  salt,
+}: {
+  address: Address;
+  chainId: number;
+  hash: Hash;
+  salt?: Hex;
+}) {
+  return {
+    domain: {
+      chainId,
+      verifyingContract: address,
+      ...(salt ? { salt } : {}),
+    },
+    types: {
+      ReplaySafeHash: [{ name: "hash", type: "bytes32" }],
+    },
+    message: {
+      hash,
+    },
+    primaryType: "ReplaySafeHash" as const,
+  };
+}
+/**
+ * Wraps a P256 signature with the webauthn metadata.
+ *
+ * @param {ToWebAuthnSignatureParams} params - The parameters for wrapping a P256 signature with the webauthn metadata.
+ * @returns {object} The wrapped P256 signature.
+ */
+export function toWebAuthnSignature({
+  webauthn,
+  signature,
+}: {
+  webauthn: WebAuthnP256.SignMetadata;
+  signature: Hex;
+}) {
+  const { r, s } = Signature.fromHex(signature);
+  return encodeAbiParameters(
+    [
+      {
+        name: "params",
+        type: "tuple",
+        components: [
+          { name: "authenticatorData", type: "bytes" },
+          { name: "clientDataJSON", type: "string" },
+          { name: "challengeIndex", type: "uint256" },
+          { name: "typeIndex", type: "uint256" },
+          { name: "r", type: "uint256" },
+          { name: "s", type: "uint256" },
+        ],
+      },
+    ],
+    [
+      {
+        authenticatorData: webauthn.authenticatorData,
+        clientDataJSON: webauthn.clientDataJSON,
+        challengeIndex: BigInt(webauthn.challengeIndex),
+        typeIndex: BigInt(webauthn.typeIndex),
+        r,
+        s,
+      },
+    ],
+  );
+}

package/src/test-utils/getAccountAddressViaEntryPoint.ts

@@ -0,0 +1,43 @@
+import { getContract, type Address, type Hex, type Client } from "viem";
+
+/**
+ * Test utility function that computes the counterfactual address using the EntryPoint's getSenderAddress function.
+ * This is copied from v4's @aa-sdk/core's getAccountAddress logic.
+ *
+ * @param {object} params - The parameters object
+ * @param {Client} params.client - The viem client for blockchain interaction
+ * @param {Address} params.entryPointAddress - The EntryPoint contract address
+ * @param {Array} params.entryPointAbi - The EntryPoint contract ABI
+ * @param {() => Promise<Hex>} params.getAccountInitCode - Function that returns the account init code
+ * @returns {Promise<Address>} Promise that resolves to the counterfactual account address
+ */
+export async function getAccountAddressViaEntryPoint({
+  client,
+  entryPointAddress,
+  entryPointAbi,
+  getAccountInitCode,
+}: {
+  client: Client;
+  entryPointAddress: Address;
+  entryPointAbi: readonly any[];
+  getAccountInitCode: () => Promise<Hex>;
+}): Promise<Address> {
+  const entryPointContract = getContract({
+    address: entryPointAddress,
+    abi: entryPointAbi,
+    client,
+  });
+
+  const initCode = await getAccountInitCode();
+
+  try {
+    await entryPointContract.simulate.getSenderAddress([initCode]);
+  } catch (err: any) {
+    if (err.cause?.data?.errorName === "SenderAddressResult") {
+      return err.cause.data.args[0] as Address;
+    }
+    throw err;
+  }
+
+  throw new Error("Failed to get counterfactual address");
+}