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

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

Original ERC · ← ERCs