@alchemy/smart-accounts 0.0.0-alpha.0

package/src/ma-v1/accounts/base.ts

@@ -0,0 +1,245 @@
+import {
+  type Address,
+  type Chain,
+  type Client,
+  type Hex,
+  type JsonRpcAccount,
+  type LocalAccount,
+  type Transport,
+  type Hash,
+  type TypedDataDefinition,
+  encodeFunctionData,
+} from "viem";
+import {
+  entryPoint06Abi,
+  toSmartAccount,
+  type SmartAccount,
+  type SmartAccountImplementation,
+  entryPoint06Address,
+  getUserOperationHash,
+} from "viem/account-abstraction";
+import type { SignatureRequest } from "../../types.js";
+import { IStandardExecutorAbi } from "../abis/IStandardExecutor.js";
+import { signMessage, signTypedData } from "viem/actions";
+import {
+  decodeFunctionData,
+  getAction,
+  hashMessage,
+  hashTypedData,
+  isAddressEqual,
+} from "viem/utils";
+import { BaseError } from "@alchemy/common";
+
+type MaV1AccountType = "MultiOwnerModularAccountV1"; // Currently no SDK v5 support for "MultiSigModularAccountV1".
+
+export type BaseMaV1AccountImplementation = SmartAccountImplementation<
+  typeof entryPoint06Abi,
+  "0.6",
+  {
+    source: MaV1AccountType;
+    prepareSignature: (request: SignatureRequest) => Promise<SignatureRequest>;
+    formatSignature: (signature: Hex) => Promise<Hex>;
+  },
+  false
+>;
+
+export type ModularAccountV1Base = SmartAccount<BaseMaV1AccountImplementation>;
+
+export type ToModularAccountV1BaseParams<
+  TTransport extends Transport = Transport,
+> = {
+  client: Client<TTransport, Chain, JsonRpcAccount | LocalAccount | undefined>;
+  accountAddress: Address;
+  owner: JsonRpcAccount | LocalAccount;
+  getFactoryArgs: () => Promise<{
+    factory?: Address | undefined;
+    factoryData?: Hex | undefined;
+  }>;
+  get712Wrapper: (msg: Hash) => Promise<TypedDataDefinition>;
+  type: MaV1AccountType;
+};
+
+/**
+ * Creates a ModularAccountV1Base instance.
+ *
+ * @param {ToModularAccountV1BaseParams<TTransport>} params The parameters for creating a ModularAccountV1Base instance
+ * @returns {Promise<ModularAccountV1Base>} A promise that resolves to a ModularAccountV1Base instance
+ */
+export async function toModularAccountV1Base<
+  TTransport extends Transport = Transport,
+>({
+  client,
+  accountAddress,
+  owner,
+  getFactoryArgs,
+  get712Wrapper,
+  type,
+}: ToModularAccountV1BaseParams<TTransport>): Promise<ModularAccountV1Base> {
+  const entryPoint = {
+    abi: entryPoint06Abi,
+    address: entryPoint06Address,
+    version: "0.6" as const,
+  };
+
+  const prepareSignature = async (
+    params: SignatureRequest,
+  ): Promise<SignatureRequest> => {
+    const data = await get712Wrapper(
+      params.type === "personal_sign"
+        ? hashMessage(params.data)
+        : hashTypedData(params.data),
+    );
+    return {
+      type: "eth_signTypedData_v4",
+      data,
+    };
+  };
+
+  const formatSignature = async (signature: Hex): Promise<Hex> => {
+    return signature;
+  };
+
+  return await toSmartAccount({
+    getFactoryArgs,
+    client,
+    entryPoint,
+
+    async getAddress() {
+      return accountAddress;
+    },
+
+    async encodeCalls(calls) {
+      if (!calls.length) {
+        throw new BaseError("No calls to encode.");
+      }
+
+      if (calls.length === 1) {
+        const call = calls[0];
+
+        // If the call is to the account itself, we need to avoid wrapping it in an `execute` call.
+        if (isAddressEqual(call.to, accountAddress)) {
+          if (call.data == null) {
+            throw new BaseError("Data is required for an account self-call.");
+          }
+
+          return call.data;
+        }
+
+        return encodeFunctionData({
+          abi: IStandardExecutorAbi,
+          functionName: "execute",
+          args: [call.to, call.value ?? 0n, call.data ?? "0x"],
+        });
+      }
+
+      return encodeFunctionData({
+        abi: IStandardExecutorAbi,
+        functionName: "executeBatch",
+        args: [
+          calls.map((call) => ({
+            target: call.to,
+            value: call.value ?? 0n,
+            data: call.data ?? "0x",
+          })),
+        ],
+      });
+    },
+
+    // Inverse of `encodeCalls`.
+    async decodeCalls(data) {
+      const decoded = decodeFunctionData({
+        abi: IStandardExecutorAbi,
+        data,
+      });
+
+      if (decoded.functionName === "execute") {
+        return [
+          {
+            to: decoded.args[0],
+            value: decoded.args[1],
+            data: decoded.args[2],
+          },
+        ];
+      }
+
+      if (decoded.functionName === "executeBatch") {
+        return decoded.args[0].map((call) => ({
+          to: call.target,
+          value: call.value,
+          data: call.data,
+        }));
+      }
+
+      // If the data is not for an `execute` or `executeBatch` call, we treat it as a single call to the account itself.
+      return [
+        {
+          to: accountAddress,
+          data,
+        },
+      ];
+    },
+
+    async getStubSignature() {
+      return "0xfffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c";
+    },
+
+    async signMessage({ message }) {
+      const signMessageAction = getAction(client, signMessage, "signMessage");
+      const signTypedDataAction = getAction(
+        client,
+        signTypedData,
+        "signTypedData",
+      );
+      const { type, data } = await prepareSignature({
+        type: "personal_sign",
+        data: message,
+      });
+      return type === "personal_sign"
+        ? signMessageAction({ account: owner, message: data })
+        : signTypedDataAction({ ...data, account: owner });
+    },
+
+    async signTypedData(params) {
+      const signMessageAction = getAction(client, signMessage, "signMessage");
+      const signTypedDataAction = getAction(
+        client,
+        signTypedData,
+        "signTypedData",
+      );
+      const { type, data } = await prepareSignature({
+        type: "eth_signTypedData_v4",
+        data: params as TypedDataDefinition, // TODO(v5): try harder to avoid this cast?
+      });
+      return type === "personal_sign"
+        ? signMessageAction({ account: owner, message: data })
+        : signTypedDataAction({ ...data, account: owner });
+    },
+
+    async signUserOperation(parameters) {
+      const { chainId = client.chain.id, ...userOperation } = parameters;
+      const userOpHash = getUserOperationHash({
+        chainId,
+        entryPointAddress: entryPoint.address,
+        entryPointVersion: entryPoint.version,
+        userOperation: {
+          ...userOperation,
+          sender: accountAddress,
+        },
+      });
+
+      const signMessageAction = getAction(client, signMessage, "signMessage");
+      return signMessageAction({
+        account: owner,
+        message: {
+          raw: userOpHash,
+        },
+      });
+    },
+
+    extend: {
+      source: type,
+      prepareSignature,
+      formatSignature,
+    },
+  });
+}

package/src/ma-v1/accounts/multi-owner-account.ts

@@ -0,0 +1,162 @@
+import {
+  hexToBigInt,
+  type Address,
+  type Chain,
+  type Client,
+  type Hex,
+  type JsonRpcAccount,
+  type LocalAccount,
+  type OneOf,
+  type Transport,
+  encodeFunctionData,
+  type Hash,
+  type TypedDataDefinition,
+} from "viem";
+import { toModularAccountV1Base, type ModularAccountV1Base } from "./base.js";
+import { lowerAddress, BaseError } from "@alchemy/common";
+import { DefaultMaV1Address, DefaultMaV1PluginAddress } from "../account.js";
+import { MultiOwnerModularAccountFactoryAbi } from "../abis/MultiOwnerModularAccountFactory.js";
+import { predictMultiOwnerModularAccountV1Address } from "../predictAddress.js";
+import { MultiOwnerPluginExecutionFunctionAbi } from "../abis/MultiOwnerPluginExecutionFunction.js";
+import { readContract } from "viem/actions";
+import { getAction } from "viem/utils";
+import { MultiOwnerPluginAbi } from "../abis/MultiOwnerPlugin.js";
+
+export type MultiOwnerModularAccountV1 = ModularAccountV1Base & {
+  encodeUpdateOwners: (
+    ownersToAdd: Address[],
+    ownersToRemove: Address[],
+  ) => Hex;
+  getOwnerAddresses: () => Promise<readonly Address[]>;
+};
+
+export type ToMultiOwnerModularAccountV1Params = {
+  client: Client<Transport, Chain, JsonRpcAccount | LocalAccount | undefined>;
+  owners: [OneOf<JsonRpcAccount | LocalAccount>, ...{ address: Address }[]];
+  salt?: bigint;
+  accountAddress?: Address;
+  factoryAddress?: Address;
+};
+
+/**
+ * Creates a multi-owner MAv1 account.
+ *
+ * @param {ToMultiOwnerModularAccountV1Params} param0 - The parameters for creating a multi-owner MAv1 account.
+ * @returns {Promise<MultiOwnerModularAccountV1<TSigner>>} A multi-owner MAv1 account.
+ */
+export async function toMultiOwnerModularAccountV1({
+  client,
+  salt = 0n,
+  owners,
+  accountAddress: accountAddress_,
+  factoryAddress = DefaultMaV1Address.MULTI_OWNER_MAV1_FACTORY,
+}: ToMultiOwnerModularAccountV1Params): Promise<MultiOwnerModularAccountV1> {
+  const signer = owners[0];
+
+  const dedupedOwners = Array.from(
+    new Set(owners.map((it) => lowerAddress(it.address))),
+  );
+
+  const sortedOwners = dedupedOwners.sort((a, b) => {
+    const bigintA = hexToBigInt(a);
+    const bigintB = hexToBigInt(b);
+    return bigintA < bigintB ? -1 : bigintA > bigintB ? 1 : 0;
+  });
+
+  const accountAddress =
+    accountAddress_ ??
+    predictMultiOwnerModularAccountV1Address({
+      factoryAddress,
+      salt,
+      ownerAddresses: sortedOwners,
+    });
+
+  const getFactoryArgs = async () => {
+    const factoryData = encodeFunctionData({
+      abi: MultiOwnerModularAccountFactoryAbi,
+      functionName: "createAccount",
+      args: [salt, sortedOwners],
+    });
+
+    return {
+      factory: factoryAddress,
+      factoryData,
+    };
+  };
+
+  const get712Wrapper = async (msg: Hash): Promise<TypedDataDefinition> => {
+    const readContractAction = getAction(client, readContract, "readContract");
+
+    const [, name, version, chainId, verifyingContract, salt] =
+      await readContractAction({
+        abi: MultiOwnerPluginAbi,
+        address: DefaultMaV1PluginAddress.MULTI_OWNER,
+        functionName: "eip712Domain",
+        account: accountAddress,
+      });
+
+    return {
+      domain: {
+        chainId: Number(chainId),
+        name,
+        salt,
+        verifyingContract,
+        version,
+      },
+      types: {
+        AlchemyModularAccountMessage: [{ name: "message", type: "bytes" }],
+      },
+      message: {
+        message: msg,
+      },
+      primaryType: "AlchemyModularAccountMessage",
+    };
+  };
+
+  const baseAccount = await toModularAccountV1Base({
+    client,
+    owner: signer,
+    accountAddress,
+    getFactoryArgs,
+    type: "MultiOwnerModularAccountV1",
+    get712Wrapper,
+  });
+
+  return {
+    ...baseAccount,
+
+    encodeUpdateOwners: (ownersToAdd: Address[], ownersToRemove: Address[]) => {
+      return encodeFunctionData({
+        abi: MultiOwnerPluginExecutionFunctionAbi,
+        functionName: "updateOwners",
+        args: [ownersToAdd, ownersToRemove],
+      });
+    },
+
+    async getOwnerAddresses(): Promise<readonly Address[]> {
+      const readContractAction = getAction(
+        client,
+        readContract,
+        "readContract",
+      );
+      const ownersOnChain = await readContractAction({
+        address: DefaultMaV1PluginAddress.MULTI_OWNER,
+        abi: MultiOwnerPluginAbi,
+        functionName: "ownersOf",
+        args: [accountAddress],
+      });
+
+      if (
+        !ownersOnChain
+          .map((it) => lowerAddress(it))
+          .includes(lowerAddress(signer.address))
+      ) {
+        throw new BaseError(
+          "on-chain owners does not include the current signer",
+        );
+      }
+
+      return ownersOnChain;
+    },
+  };
+}

package/src/ma-v1/decorators/multiOwner.ts

@@ -0,0 +1,69 @@
+import type { Address, Chain, Client, Hex, IsUndefined, Transport } from "viem";
+import { sendUserOperation, type SmartAccount } from "viem/account-abstraction";
+import { getAction } from "viem/utils";
+import type { GetAccountParameter } from "../../types.js";
+import { AccountNotFoundError } from "@alchemy/common";
+import type { MultiOwnerModularAccountV1 } from "../accounts/multi-owner-account.js";
+
+export type MultiOwnerModularAccountV1Actions<
+  TAccount extends MultiOwnerModularAccountV1 | undefined =
+    | MultiOwnerModularAccountV1
+    | undefined,
+> = {
+  updateOwners: (
+    args: {
+      ownersToAdd: Address[];
+      ownersToRemove: Address[];
+    } & GetAccountParameter<TAccount, MultiOwnerModularAccountV1>,
+  ) => Promise<Hex>;
+};
+
+function isMultiOwnerModularAccountV1(
+  account: SmartAccount,
+): account is MultiOwnerModularAccountV1 {
+  return "source" in account && account.source === "MultiOwnerModularAccountV1";
+}
+
+/**
+ * Generates client actions for a multi-owner MAv1 account, including the ability to update owners.
+ *
+ * @param {Client<TTransport, TChain, TAccount>} client The client instance used to interact with the account
+ * @returns {MultiOwnerLightAccountActions<TAccount>} An object containing the client actions specifically for a multi-owner modular account
+ */
+export function multiOwnerModularAccountV1Actions<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartAccount | undefined = SmartAccount | undefined,
+>(
+  client: Client<TTransport, TChain, TAccount>,
+): MultiOwnerModularAccountV1Actions<
+  IsUndefined<TAccount> extends true ? undefined : MultiOwnerModularAccountV1
+> {
+  return {
+    // TODO(v5): Another pattern I think we should consider deprecating for v5 - actions that
+    // implicitly do a sendUserOperation internally. These are non-composable with batching
+    // and have a number of other issues that are solved with viem writeContract.
+    updateOwners: async (args) => {
+      const { ownersToAdd, ownersToRemove, account = client.account } = args;
+
+      if (!account || !isMultiOwnerModularAccountV1(account)) {
+        throw new AccountNotFoundError();
+      }
+
+      const data = account.encodeUpdateOwners(ownersToAdd, ownersToRemove);
+
+      const action = getAction(client, sendUserOperation, "sendUserOperation");
+      const result = await action({
+        calls: [
+          {
+            to: account.address,
+            data,
+          },
+        ],
+        account,
+      });
+
+      return result;
+    },
+  };
+}

package/src/ma-v1/mav1StaticImpl.ts

@@ -0,0 +1,53 @@
+import { type Address, encodeFunctionData } from "viem";
+import { entryPoint06Abi, entryPoint06Address } from "viem/account-abstraction";
+import { lowerAddress } from "@alchemy/common";
+import type { StaticSmartAccountImplementation } from "../types";
+import { MultiOwnerModularAccountFactoryAbi } from "./abis/MultiOwnerModularAccountFactory.js";
+import { UpgradeableModularAccountAbi } from "./abis/UpgradeableModularAccount.js";
+import { DefaultMaV1Address } from "./account.js";
+import { predictMultiOwnerModularAccountV1Address } from "./predictAddress.js";
+
+export type MultiOwnerModularAccountV1FactoryArgs = {
+  owners: Address[];
+  salt: bigint;
+};
+
+/**
+ * Static implementation logic for ModularAccountV1.
+ *
+ * TODO(v5): update JSDoc format when doc-gen supports structs or records.
+ */
+export const multiOwnerModularAccountStaticImpl: StaticSmartAccountImplementation<
+  false,
+  "0.6",
+  MultiOwnerModularAccountV1FactoryArgs,
+  typeof entryPoint06Abi,
+  typeof UpgradeableModularAccountAbi,
+  typeof MultiOwnerModularAccountFactoryAbi
+> = {
+  entryPoint: {
+    abi: entryPoint06Abi,
+    address: entryPoint06Address,
+    version: "0.6",
+  },
+  accountAbi: UpgradeableModularAccountAbi,
+  factoryAbi: MultiOwnerModularAccountFactoryAbi,
+  getFactoryData: (factoryArgs: MultiOwnerModularAccountV1FactoryArgs) => {
+    return encodeFunctionData({
+      abi: MultiOwnerModularAccountFactoryAbi,
+      functionName: "createAccount",
+      args: [factoryArgs.salt, factoryArgs.owners],
+    });
+  },
+  accountImplementation: lowerAddress(
+    DefaultMaV1Address.IMPLEMENTATION_ADDRESS,
+  ),
+  factoryAddress: lowerAddress(DefaultMaV1Address.MULTI_OWNER_MAV1_FACTORY),
+  predictAccountAddress: (args) => {
+    return predictMultiOwnerModularAccountV1Address({
+      salt: args.salt,
+      ownerAddresses: args.owners,
+      factoryAddress: DefaultMaV1Address.MULTI_OWNER_MAV1_FACTORY,
+    });
+  },
+};

package/src/ma-v1/predictAddress.ts

@@ -0,0 +1,85 @@
+import {
+  type Address,
+  getContractAddress,
+  encodeAbiParameters,
+  keccak256,
+  concatHex,
+  type Hex,
+} from "viem";
+import { DefaultMaV1Address } from "./account.js";
+import { BaseError } from "@alchemy/common";
+
+export type PredictMultiOwnerModularAccountV1AddressParams = {
+  salt: bigint;
+  /* Owner addresses must be already deduped, sorted in ascending order, and have the signer address included. */
+  ownerAddresses: Address[];
+  factoryAddress?: Address;
+};
+
+/**
+ * Predicts the address of a MultiOwnerModularAccountV1 smart account before deployment.
+ *
+ * This function uses CREATE2 to deterministically compute the account address based on the factory address,
+ * salt, and owner addresses. The predicted address will match the actual deployed address if the same
+ * parameters are used during deployment.
+ *
+ * @param {PredictMultiOwnerModularAccountV1AddressParams} params The parameters for predicting the account address
+ * @param {bigint} params.salt A unique value used to generate different account addresses for the same set of owners
+ * @param {Address[]} params.ownerAddresses Array of owner addresses that will control the account. Must be deduplicated, sorted in ascending order, and include the signer address. Cannot be empty and must contain at most 100 addresses.
+ * @param {Address} [params.factoryAddress] The factory contract address that will deploy the account. Defaults to the standard MultiOwnerModularAccountV1 factory address.
+ * @returns {Address} The predicted address where the account will be deployed
+ *
+ * @example
+ * ```ts
+ * const predictedAddress = predictMultiOwnerModularAccountV1Address({
+ *   salt: 0n,
+ *   ownerAddresses: ["0x1234...", "0x5678..."]
+ * });
+ * ```
+ */
+export const predictMultiOwnerModularAccountV1Address = ({
+  salt,
+  ownerAddresses,
+  factoryAddress = DefaultMaV1Address.MULTI_OWNER_MAV1_FACTORY,
+}: PredictMultiOwnerModularAccountV1AddressParams): Address => {
+  if (ownerAddresses.length === 0) {
+    throw new BaseError("Owners array cannot be empty");
+  }
+  if (ownerAddresses.length > 100) {
+    throw new Error("Maximum 100 owners on creation");
+  }
+
+  const combinedSalt = getCombinedSalt(salt, ownerAddresses);
+
+  const initCodeHash = getERC1967ProxyInitCodeHash(
+    DefaultMaV1Address.IMPLEMENTATION_ADDRESS,
+  );
+
+  return getContractAddress({
+    from: factoryAddress,
+    opcode: "CREATE2",
+    salt: combinedSalt,
+    bytecodeHash: initCodeHash,
+  });
+};
+
+function getCombinedSalt(salt: bigint, owners: Address[]): Hex {
+  const encodedOwners = encodeAbiParameters([{ type: "address[]" }], [owners]);
+  const saltAndOwners = encodeAbiParameters(
+    [{ type: "uint256" }, { type: "bytes" }],
+    [salt, encodedOwners],
+  );
+  return keccak256(saltAndOwners);
+}
+
+function getERC1967ProxyInitCodeHash(implementationAddress: Address): Hex {
+  const ERC1967_PROXY_BYTECODE =
+    "0x60406080815261042c908138038061001681610218565b93843982019181818403126102135780516001600160a01b038116808203610213576020838101516001600160401b0394919391858211610213570186601f820112156102135780519061007161006c83610253565b610218565b918083528583019886828401011161021357888661008f930161026e565b813b156101b9577f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc80546001600160a01b031916841790556000927fbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b8480a28051158015906101b2575b61010b575b855160e790816103458239f35b855194606086019081118682101761019e578697849283926101889952602788527f416464726573733a206c6f772d6c6576656c2064656c65676174652063616c6c87890152660819985a5b195960ca1b8a8901525190845af4913d15610194573d9061017a61006c83610253565b91825281943d92013e610291565b508038808080806100fe565b5060609250610291565b634e487b7160e01b84526041600452602484fd5b50826100f9565b855162461bcd60e51b815260048101859052602d60248201527f455243313936373a206e657720696d706c656d656e746174696f6e206973206e60448201526c1bdd08184818dbdb9d1c9858dd609a1b6064820152608490fd5b600080fd5b6040519190601f01601f191682016001600160401b0381118382101761023d57604052565b634e487b7160e01b600052604160045260246000fd5b6001600160401b03811161023d57601f01601f191660200190565b60005b8381106102815750506000910152565b8181015183820152602001610271565b919290156102f357508151156102a5575090565b3b156102ae5790565b60405162461bcd60e51b815260206004820152601d60248201527f416464726573733a2063616c6c20746f206e6f6e2d636f6e74726163740000006044820152606490fd5b8251909150156103065750805190602001fd5b6044604051809262461bcd60e51b825260206004830152610336815180928160248601526020868601910161026e565b601f01601f19168101030190fdfe60806040523615605f5773ffffffffffffffffffffffffffffffffffffffff7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc54166000808092368280378136915af43d82803e15605b573d90f35b3d90fd5b73ffffffffffffffffffffffffffffffffffffffff7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc54166000808092368280378136915af43d82803e15605b573d90f3fea26469706673582212208f3104255ee3c201238ea03e118ee6ec0a2cff51cbfbdc3af1727982a5a959a564736f6c63430008160033" as const;
+
+  const constructorArgs = encodeAbiParameters(
+    [{ type: "address" }, { type: "bytes" }],
+    [implementationAddress, "0x"],
+  );
+
+  return keccak256(concatHex([ERC1967_PROXY_BYTECODE, constructorArgs]));
+}