Modules explained

Modules are smart contracts, usually singletons, that extend the functionality of smart accounts. Modular smart accounts allow users and developers to easily change how a smart account works. In order to understand more deeply what is possible with modules (spoiler: a lot), let’s quickly recap the transaction flow of a smart account.

ERC-4337 UserOperation flow

While there are many different ways of implementing Account Abstraction on Ethereum, Rhinestone is built on top of ERC-4337, which is a standard for implementing Account Abstraction using an alternative mempool and without requiring protocol changes. If you want to read up more about this ERC, view the specs here and an excellent blog post here.

In order to achieve Account Abstraction, ERC-4337 specifies a new type of transaction for this alternative mempool, termed a UserOperation. On a high level, this UserOperation goes through two distinct phases: validation and execution.

Validation Phase

During the validation phase, the ERC-4337 Entrypoint calls the validateUserOp function on the smart account in order for it to determine whether a UserOperation is valid and should be executed. If this function returns 0, then the Entrypoint will consider it valid, if it returns 1 or reverts then the Entrypoint will halt execution there and move on to the next UserOperation.

How exactly signature validation occurs is entirely up to the developer to decide, which enables the possibility of modular validation logic that can be added and replaced at any point.

ERC-4337 places some storage and opcode restrictions on accounts during the validation phase, which impacts how validation modules can be built. Read more about these below.

Execution Phase

If the validation phase was successful, then the Entrypoint will call the smart account again, this time with the calldata provided in the UserOperation. While the Entrypoint always calls the validateUserOp function during the validation phase, there is no such restriction during execution, meaning that accounts can implement any number of execution functions and the wallet client can choose which exact one to call depending on the transaction intent.

Similar to the validation phase, ERC-4337 does not stipulate how execution occurs, enabling the possibility to build modules for the execution phase.

Module types

ERC-4337 breaks down the flow of a UserOperation into two distinct phases, validation and execution. The account functionality that is required in either of these two phases differs to that of the other, so there are at least two different types of modules: validators and executors. However, there are at least two more distinct types of modules that perform different functions to the aforementioned: hooks and fallback modules.

Validators

Determine whether a transaction is valid and should be executed

Executors

Create executions on the account with custom logic

Hooks

Enforce conditions or execute logic pre- or post-execution

Fallbacks

Extend the account logic to add more functionality into the account

Validators

Validators are modules that are called during the validation phase of a UserOperation. This means that their primary function is to verify the signature of a UserOperation and determine whether it is valid and should be executed. As a result, validators are the primary mechanism for enforcing access control on a smart account and are highly security critical.

Executors

Executors are modules that are called during the execution phase of a UserOperation. They extend the execution logic of the account and thus allow for a more diverse set of actions that the account can natively perform. On top of this, Executors can also be used to automate certain actions that are triggered outside of the regular ERC-4337 execution flow on the account. For example, a user could set up an executor that automatically swaps their tokens when the price of a token reaches a certain threshold.

Conditional Executors

Conditional executors extend the capabilities of normal executors, by allowing transactions to be executed based on checks performed by the ComposableConditionManager. This allows for more complex logic to be implemented in executors, such as the ability to execute transactions based on the price of a token or the current gas price. Importantly, these conditions are verified on-chain meaning that a user can be sure that the transaction will be executed only if the condition is met and does not need to trust a third party.

Hooks

Hooks are modules that are triggered either before or after execution and can be used to enforce certain behavior. Some examples of hooks include spending limits, restricting tokens that can be transferred, ensuring that contracts that are interacted with are audited, and more.

Fallbacks

Fallbacks are modules that can add additional functionality into the account. They are called by the fallback function of the account, meaning that they are triggered when a transaction is sent to the account that does not match any of the existing functions on the account. Fallbacks can, for example, implement logic for receiving tokens, allow smart accounts to be used for flashloans or potentially even as a paymaster for sub-accounts.