ERC-6900 Modular smart contract accounts
Draft · Accounts & wallets · created 2023-04-18
A standard that separates a smart contract account's validation, execution, and hook logic into external contracts called modules, so they can be installed into and removed from any account that follows the standard.
Why it is needed
Thanks to ERC-4337 account abstraction, features like session keys, subscription payments, spending limits, and role-based access control can now be implemented by changing an account's validation and execution logic. But today these features are either built into specific account implementations or offered only through platform-specific module systems like Safe modules. As a result, users have to switch between multiple account implementations depending on which feature they want, fragmenting accounts by feature and security settings and reducing data portability. Module developers also have to choose which platform to support, leading to platform lock-in or having to build the same feature multiple times. This standard defines a common specification that coordinates the implementation work of account developers and module developers, making it possible to build modular accounts that support any module that follows the standard.
What to implement
function execute(address target, uint256 value, bytes calldata data) external payable returns (bytes memory);: A standard execution function through which the account sends value and call data to a specified address.function executeBatch(Call[] calldata calls) external payable returns (bytes[] memory);: Executes multiple calls at once. If any one fails, the entire batch must revert.function executeWithRuntimeValidation(bytes calldata data, bytes calldata authorization) external payable returns (bytes memory);: Executes a call by specifying which runtime validation function to use via the first 24 bytes of authorization (ModuleEntity).function accountId() external view returns (string memory);: Returns a unique identifier for the account implementation as a string in the format "vendor.account.semver".event ExecutionInstalled(address indexed module, ExecutionManifest manifest);: An event emitted when an execution module is installed.event ExecutionUninstalled(address indexed module, bool onUninstallSucceeded, ExecutionManifest manifest);: An event emitted when an execution module is removed, along with whether onUninstall succeeded.event ValidationInstalled(address indexed module, uint32 indexed entityId);: An event emitted when a validation function is installed.event ValidationUninstalled(address indexed module, uint32 indexed entityId, bool onUninstallSucceeded);: An event emitted when a validation function is removed, along with whether onUninstall succeeded.function onInstall(bytes calldata data) external;: Called by the account on installation so the module can set up its initial data for that account.function onUninstall(bytes calldata data) external;: Called by the account on removal so the module can clean up its data for that account.function moduleId() external view returns (string memory);: Returns a unique identifier for the module as a string in the format "vendor.module.semver".function validateUserOp(uint32 entityId, PackedUserOperation calldata userOp, bytes32 userOpHash) external returns (uint256);: Performs user operation validation and returns a value containing validAfter, validUntil, and authorizer.function preUserOpValidationHook(uint32 entityId, PackedUserOperation calldata userOp, bytes32 userOpHash) external returns (uint256);: A hook that runs before user operation validation; its authorizer value must return only 0 or 1.function preSignatureValidationHook(uint32 entityId, address sender, bytes32 hash, bytes calldata signature) external view;: A hook that runs before signature validation. It must revert to reject.function executionManifest() external pure returns (ExecutionManifest memory);: Returns a manifest containing the execution functions, hooks, and interface IDs the module will install on the account. It must not change over time.function preExecutionHook(uint32 entityId, address sender, uint256 value, bytes calldata data) external returns (bytes memory);: A hook that runs before execution and can return context to pass to the paired post hook.function postExecutionHook(uint32 entityId, bytes calldata preExecHookData) external;: A hook that runs after execution and receives the data returned by its paired pre hook.
In depth
The three modular functions and the basic structure
This standard divides account functionality into three categories. A validation function checks authorization for an action performed on behalf of the account, an execution function runs custom logic the account has allowed, and a hook performs additional logic and checks before and after that. Hooks are further divided into validation hooks, which run before a validation function, and execution hooks, which run before and after execution. Execution hooks can be attached to a specific execution function or a specific validation function, and a pre execution hook can return data for its post execution hook to consume. A module is a deployed contract containing any number of these three kinds of modular functions, and a manifest describes the execution functions, interface IDs, and hooks to be installed on the account. Modular accounts support both calls routed through the ERC-4337 EntryPoint and direct calls from EOAs or contracts.
Required and optional interfaces
A modular account must implement ERC-4337's IAccount and IAccountExecute, IERC6900Account for module management and execution, and ERC-1271's isValidSignature. IERC6900AccountView for on-chain state queries and ERC-165 for interfaces installed by modules are optional. A module must implement IERC6900Module and support ERC-165 for it, and may optionally implement IERC6900ValidationModule, IERC6900ValidationHookModule, IERC6900ExecutionModule, and IERC6900ExecutionHookModule depending on its role. Account and module identifiers must be in the format "vendor.account.semver" and "vendor.module.semver" respectively.
Packed types: ModuleEntity, ValidationConfig, HookConfig
A module function is identified by the bytes24 type ModuleEntity, combining the 20-byte module address and a 4-byte entity ID. The entity ID is an identifier that routes calls to one of several internal implementations within a module. ValidationConfig is a bytes25 made of this plus 1 byte of flags, holding the three flags isGlobal, isSignatureValidation, and isUserOpValidation. HookConfig is also a bytes25, holding the hasPre and hasPost flags for execution hooks plus a hook-type flag (0 for execution hook, 1 for validation hook). This packing lets validation functions and hooks be stored and passed around as a single short value.
The three validation flows and applicability checks
Validation happens through three paths: user operation validation (validateUserOp), runtime validation (via executeWithRuntimeValidation or direct call validation), and signature validation (isValidSignature). In each path, the account must first check whether the relevant validation function applies to the selector being executed, then run all validation hooks of the same kind attached to that validation function, and then call the validation function itself. If a hook or the validation function reverts, the account must also revert. Per-hook data is recommended to be passed via the userOp.signature field for user operations, the authorization field at runtime, and the signature field for signature validation. The resulting time range for user operation validation must be the intersection of the ranges returned by the hooks and the validation function, and if any of them returns 1 (signature failure) as authorizer, the account must also return 1. Attempting to use a validation function for user operation or signature validation when its isUserOpValidation or isSignatureValidation flag is off must revert, and if the target of execute or executeBatch is the account itself, it must additionally check whether validation applies to the internal selector or revert.
Direct call validation
A validation function installed with entity ID 0xffffffff is used for direct call validation. If a module or another address calls an account function directly without wrapping it in executeWithRuntimeValidation, the account must treat this as a validation attempt under the combination of the caller's address and entity ID 0xffffffff. If such a validation function is installed and applies to the function being called, the account must allow the call to proceed without performing runtime validation. However, the validation hooks and execution hooks installed on that validation function must still run. This mechanism can be used to grant a specific address direct access to part of the account's functionality.
Execution flow and hook ordering
The state-changing functions of IERC6900Account other than executeWithRuntimeValidation, execution functions defined by modules, and the account's native functions must follow a common execution procedure. If the caller is neither the EntryPoint nor the account itself, the access control of direct call validation is checked. All pre execution hooks that apply before the target function must be executed, running hooks attached to the validation function first and hooks attached to the selector after. Post execution hooks after the target function runs must run in the reverse order of the pre hooks, and if a hook that serves as both pre and post returned non-empty bytes, that data must be passed to its post hook. The set of hooks to execute must be fixed at the account's state at the start of the execution phase; even if the hook configuration changes during execution, the original set runs to completion. It is recommended that hooks run in first-installed-first-executed order.
Installation and uninstallation rules
When installing a validation function, the account must install all the validation hooks and execution hooks specified by the user, configure it to validate the specified selectors, set flags such as isGlobal as specified, and emit the ValidationInstalled event. On removal, it must clear both the flag and selector configuration and remove all hooks, and a revert from onUninstall may be ignored via try/catch depending on the account's design. Installing an execution module follows the manifest, and execution function selectors must be unique within the account and must not collide with native ERC-4337 or ERC-6900 functions. The ExecutionInstalled and ExecutionUninstalled events must be emitted on install and uninstall respectively. Semi-modular accounts that build some functionality such as default validation into the core are also allowed, and in this case it is recommended to maintain compatibility with fully modular accounts.
Proposal status
This proposal is in Draft status. Since the specification may still change at this stage, the latest source material should be checked before implementing. The source material notes that while it currently requires ERC-4337 as one call flow, modular accounts that do not use ERC-4337, such as a rollup's native account abstraction, may emerge, and the standard is expected to evolve alongside research and adoption in the ecosystem.
Things to watch out for
- Validating the executionManifest parameter: The executionManifest parameter passed to installExecution() is checked only in a very limited way on chain and does not necessarily match the module's executionManifest() return value. Wallets and SDKs should carefully construct and validate this parameter before installation, and on removal should use the same manifest that was used for installation so that no residual data is left behind.
- Root-privilege risk of global validation functions: A validation function with global validation enabled can validate any execution function that has allowGlobalValidation enabled, bypassing the restrictions that were meant to protect those functions. This effectively grants root access to the exposed native and execution functions and to the account as a whole, so wallets must be careful about which validation functions they allow to be installed globally.
- Residual state after removal: The standard does not enforce what data must be installed or removed when a module is added or deleted. If onUninstall() is not called, or fails to fully clear state, residual data can remain, and execution hooks tied to the removed function can stay in place. Reinstalling a module with the same entityId can cause previous permissions or data to be unintentionally reused, so it is advisable to fully remove all related data, including execution hooks.
- Modules are trusted components: The account itself is a trusted component, and installed modules are trusted to varying degrees depending on their scope. A malicious module with broad scope can attach a hook that reverts on native function selectors, rendering the account unusable, or add an execution function that drains funds. Users should be careful about which modules they add to an account.