Modules

Nexus is following the ERC-7579 specification. ERC-7579 is the standard for minimal modular smart accounts. Thus, modules are crucial component that allows to add features and extend the functionality of Nexus.

There are currently 4 module types specified in ERC-7579 and all of them are supported by Nexus:

• Validators: validate userOperations as per ERC-4337.
• Executors: can initiate executions on behalf of the Smart Account they are installed on.
• Fallback handlers: extend the native functionality of the Smart Account. Calls to functions which are not implemented in the Smart Account are forwarded to fallbacks handlers.
• Hooks: hook executions by executing code before and after execution.

Installation

Install module

Nexus implements ERC-7579 installModule interface for the installation of the modules. It allows specifying which module to install and accepts data to perform the initial configuration for a module being installed. Another important parameter that has to be provided at module installation is the moduleTypeId.

Module Type Id

It is an incremental identifier, which must be used by accounts, modules and other entities to identify the module type.

• Validator modules have type id: 1
• Executors have type id: 2
• Fallback Handlers have type id: 3
• and Hooks have type id: 4 Every module self-reports its type via isModuleType(uint256 moduleTypeId) method. Module can implements several types, i.e. be a validator and an executor at the same time.

There is Module type id: 0 which means the Multitype installation. It allows installing the module as several types in course of the same installModule call.

Module enable mode

There is another way to install the module. Sometimes, there can be a situation, when user wants to use the modules, which is not enabled yet. In this case we'd want to avoid sending a separate userOperation that installs the module. If the module we want to install before the usage is executor, this can be simply solved by batching installModule(executor) call before the call that goes through this executor. However, that would not work for validators, as validation phase in 4337 goes before execution, thus the new validator should be enabled before it is used for the validation. Enable Mode allows to enable the module in the beginning of the validation phase. To achieve this, user signs the data object that describes which module is going to be installed and how it should be configured during the installation. Any module type can be installed via Module Enable Mode, however we believe it makes most sense for validators and hooks.

Usage of Modules

Modules are used according to their types.

Usage of validators

Validators validate userOperations. The validators address should be encoded into the userOp.nonce field. Nexus decodes this address and forwards the validation flow to the appropriate validator.

Usage of executors

Executors can be called directly or via Nexus.execute. The most important ability of executors is to perform actions on behalf of Nexus they are installed on by calling ERC-7579' executeFromExecutor method. For example, Executors can implement some complex logic of conditionally batching actions together.

Usage of fallback handlers

Sometimes, developers may want to add native functions to Nexus. To avoid dealing with upgrades, a Fallback can be installed on Nexus, and Nexus will forward the calls to non-existent methods to such modules that implement them.

Usage of hooks

Hooks are used to actually 'hook' executions. For example they can store (ideally, temporarily) some data that reflect the state before the execution, and then compare it to what the state is after the execution. Hooks are the most convenient way to implement spending limits for Nexus for example.

Querying installed modules

There are two methods of querying this. One can check if a given module is installed as a given type on a given Nexus, by calling Nexus.isModuleInstalled method. If one just needs to learn what modules are installed, there are dedicated methods for it:

• getValidatorsPaginated for validators
• getExecutorsPaginated for executors
• getActiveHook for the hook. As you may see, only one hook can be enabled at a given time (this can be a hook multiplexer though).
• getFallbackHandlerBySelector to check where the implementation for a method with given selector lives

Uninstalling the module

When uninstalling the module it is very important to provide the appropriate data that will deinitialize the module (by clearing its state or in any other way). Leaving module initialized (configured for a given Smart Account) after its uninstallation may lead to unexpected behaviours when the module will be installed on the same Smart Account next time.