ERC-7579 Minimal Modular Smart Accounts Standard (Minimal Modular Smart Accounts)
Draft · Accounts & wallets · created 2023-12-14
Defines the minimal interface and behavior that accounts and modules must follow so that smart accounts, which separate functionality into external contracts called modules, remain compatible with each other.
Why it is needed
Smart contract accounts are increasingly built so that functions like signature verification or automated execution can be separated into modules that can be attached and detached. However, because each account currently takes its own approach, module fragmentation arises in which a module built for one account cannot be used with another, and users face a lock-in problem of being tied to whichever account product they first chose. Wallet apps and developer tools also have to individually support each account's different approach. This standard is a proposal that leaves the account implementation itself as free as possible while defining only the common interface needed for execution, configuration, and module connection, so that a module ecosystem can work across multiple accounts together.
What to implement
function execute(bytes32 mode, bytes calldata executionCalldata) external;: Executes a transaction on behalf of the account. It MUST revert if an unsupported mode is requested.function executeFromExecutor(bytes32 mode, bytes calldata executionCalldata) external returns (bytes[] memory returnData);: An execution function called by an Executor module. It returns the return data of each subcall as an array.function executeUserOp(PackedUserOperation calldata userOp, bytes32 userOpHash) external;: An optional function called by the ERC-4337 EntryPoint, through which the account executes userOp.callData.function accountId() external view returns (string memory accountImplementationId);: Returns a string identifying the account implementation. The vendorname.accountname.semver format is recommended.function supportsExecutionMode(bytes32 encodedMode) external view returns (bool);: Indicates whether the account supports the given execution mode.function supportsModule(uint256 moduleTypeId) external view returns (bool);: Indicates whether the account supports the given module type.event ModuleInstalled(uint256 moduleTypeId, address module);: An event that MUST be emitted when a module is installed.event ModuleUninstalled(uint256 moduleTypeId, address module);: An event that MUST be emitted when a module is uninstalled.function installModule(uint256 moduleTypeId, address module, bytes calldata initData) external;: Installs a module of a given type on the account and calls the module's onInstall. Reverts if it is already installed.function uninstallModule(uint256 moduleTypeId, address module, bytes calldata deInitData) external;: Removes an installed module and calls the module's onUninstall. Reverts if it is not installed.function isModuleInstalled(uint256 moduleTypeId, address module, bytes calldata additionalContext) external view returns (bool);: Indicates whether the given module is installed on the account.function onInstall(bytes calldata data) external;: An initialization function called on the module's side when the account installs it. Reverts on error.function onUninstall(bytes calldata data) external;: A deinitialization function called on the module's side when the account uninstalls it. Reverts on error.function isModuleType(uint256 moduleTypeId) external view returns(bool);: Indicates whether the module corresponds to a given type. A single module can be of multiple types.function validateUserOp(PackedUserOperation calldata userOp, bytes32 userOpHash) external returns (uint256);: The validator module verifies whether the ERC-4337 UserOperation's signature is valid against userOpHash.function isValidSignatureWithSender(address sender, bytes32 hash, bytes calldata signature) external view returns (bytes4);: The validator module handles ERC-1271 signature verification requests. It returns MAGIC_VALUE if valid, without changing state.function preCheck(address msgSender, uint256 value, bytes calldata msgData) external returns (bytes memory hookData);: A pre-check function the account calls on a hook module before execution. It can return arbitrary hookData.function postCheck(bytes calldata hookData) external;: A post-check function the account calls on a hook module after execution, which can verify the hookData returned by preCheck.
In depth
Four Module Types and the Common Interface
Modules are distinguished by a unique type ID. Validation is 1, Execution is 2, Fallback is 3, and Hooks is 4. All modules must implement IERC7579Module (onInstall, onUninstall, isModuleType), validators must additionally implement IERC7579Validator, and hooks must implement IERC7579Hook. A single module can serve multiple types, in which case the moduleTypeId is placed inside the data of onInstall and onUninstall to handle per-type installation and removal. Accounts must be able to distinguish types when storing installed modules, for example to restrict access so that only an installed executor can call executeFromExecutor. The Rationale explains that without distinguishing types, a security problem could arise where a validator executes arbitrary transactions on behalf of the account.
Execution Mode bytes32 Encoding
execute and executeFromExecutor take the execution method as a mode encoded into a single bytes32. It consists of a 1-byte callType (0x00 single call, 0x01 batch call, 0xfe staticcall, 0xff delegatecall), a 1-byte execType (0x00 revert on failure, 0x01 handle errors without reverting), 4 reserved unused bytes, a 4-byte modeSelector for creating custom modes, and a 22-byte modePayload for additional data. An account does not need to implement every mode, but it must declare which ones it supports via supportsExecutionMode and MUST revert if an unsupported mode is requested. The modeSelector is 4 bytes to give it the same level of collision resistance as a Solidity function selector, and the modePayload can hold data such as the address of a hook to call before and after execution.
Execution Data Encoding Rules
The encoding method for execution data is also specified. A single call concatenates target, value, and callData in that order (Solidity's abi.encodePacked). A delegatecall concatenates target and callData the same way. A batch call is built as an array of Execution(address target, uint256 value, bytes memory callData) structs, then encoded including padding (abi.encode). Accounts can also optionally implement ERC-4337 v0.7's executeUserOp, in which case userOp.callData[4:] excluding the 4-byte selector must be executed as a valid call to the account, and it is recommended to execute it via delegatecall to preserve the original msg.sender.
Account Configuration and Module Configuration Interfaces
Accounts must implement IERC7579AccountConfig. accountId must return a non-empty string, and the vendorname.accountname.semver structure with uniqueness across accounts is recommended. This is used by frontend libraries to distinguish non-standardized, account-specific behavior. supportsExecutionMode and supportsModule each indicate support for an execution mode and a module type, respectively. On the module configuration side, installModule must implement access control, call the module's onInstall with initData, emit a ModuleInstalled event, and revert if it is already installed or initialization fails. uninstallModule follows the same structure, requiring a call to onUninstall, a ModuleUninstalled event, and a revert if not installed. isModuleInstalled takes additionalContext and returns whether the module is installed.
Validation and ERC-1271 Forwarding
The standard does not dictate how validator selection should be implemented. However, if an account encodes validator selection information in a data field (e.g. userOp.signature in ERC-4337), that value must be sanitized before the validator is called. An account's validation function is recommended to return the validator's return value as is. Accounts must implement the ERC-1271 interface and may forward isValidSignature calls to a validator. When forwarding, the call must be made as isValidSignatureWithSender(sender, hash, signature), where sender is the msg.sender that called the account. If the signature parameter contains validator selection encoding, it must likewise be sanitized before being passed on. A validator's validateUserOp is recommended to return ERC-4337's SIG_VALIDATION_FAILED on a signature mismatch instead of reverting.
Fallback Handlers and Hooks
An account may implement a fallback function that forwards calls to a fallback handler module. In doing so it must call the handler via call or staticcall, append the original msg.sender to the calldata using the ERC-2771 convention, and route to the handler based on the function selector in the calldata. If a fallback handler implements its own access control, it must use ERC-2771's _msgSender() instead of msg.sender. Implementing core account logic as a fallback is not recommended. Hooks are an optional extension; accounts that support them must call the hook's preCheck and postCheck before and after every call that goes through execute or executeFromExecutor, and calling them before and after installModule and uninstallModule is also recommended. If an account implements ERC-165, it must return false for the interface ID of any interface function that reverts instead of providing functionality.
ERC-4337 Dependency, Extension Path, and Proposal Status
This standard's validation flow depends on ERC-4337, since all modular accounts currently being built are ERC-4337 based. If other approaches start being used, such as a rollup's native account abstraction, an upgrade path is laid out for moving the ERC-4337 dependency into a separate ERC extension to make it optional. Standardizing new features is also recommended to be proposed as separate ERC extensions rather than by changing the core interface. It is explained that already deployed smart accounts can also comply with this standard if they are proxies, by upgrading to a compatible implementation, or, if the account cannot be upgraded, by adding a compatible adapter as a fallback handler. This proposal is currently in Draft status and its contents may still change.
Things to watch out for
- Delegatecall Execution Caution: When an account implements delegatecall execution, it must verify that the target contract is safe. Otherwise security vulnerabilities can arise.
- onInstall / onUninstall Callback Risk: A module's onInstall and onUninstall can lead to unexpected callbacks such as reentrancy, so accounts need protective routines. A malicious module could also deliberately revert in onUninstall to block its own removal.
- Residual State When Replacing a Single Active Module: For module types where only one can be active at a time, such as fallback handlers, installing a new module via installModule may not properly remove the previous module. If the previous module is later reinstalled, leftover state can cause unexpected behavior.
- Insufficient Fallback Handler Access Control: If a fallback handler's access control is insufficient, unauthorized execution can occur.
- Denial of Service via Malicious Hooks: A malicious hook can revert in preCheck or postCheck, so adding an untrusted hook can cause the entire account to stop working, resulting in denial of service.