Structure Overview
Last updated
Last updated
With the emergence of ERC-4337, the crypto landscape is witnessing a dramatic shift, sparking off new possibilities in the domain of smart contract wallets. This breakthrough is redefining the very idea of what a wallet can be, bringing us one step closer to a truly seamless Web3 experience.
Amid this evolution, we are proud to introduce Versa Wallet. Versa employs an innovative design to optimize the beauty of account abstraction while also providing robust security and customizable automation features.
With versatility at its heart, Versa strikes a unique balance between:
Accessibility to everyday users, and
Extensibility for advanced applications and developers
This dual nature is the cornerstone of our design philosophy, allowing us to cater to a broad range of user needs.
Without any plug-ins, Versa functions as a streamlined, easy-to-use wallet that offers all the functions of an externally owned account (EOA). But where Versa truly shines is in its extensibility. Users can easily activate a variety of plug-ins, which add layers of functionality and customization to the wallet. These plug-ins can assist with identity verification through transactions, provide an extra layer of security by guarding your transactions, and even add custom logic to your transactions, such as scheduling them for convenient times.
Our contract architecture is designed as depicted in the following diagram：
In Versa Wallet, we have five main components: EntryPointManager, ValidatorManager, HooksManager, ModuleManager and FallbackManager.
EntryPointManager is responsible for implementing compatibility with the ERC-4337 standard. ValidatorManager, ModuleManager, and HooksManager serve as powerful management components for Versa's comprehensive plug-in system. FallbackManager empowers the Versa wallet with unparalleled extensibility, enabling the implementation of advanced native functionalities.
The following diagram illustrates the complete lifecycle of different type of transactions in the Versa wallet based on the ERC-4337 protocol:
⚠️ The following section requires you to be familiar with ERC-4337 and solidity.
A Validator is a contract that validates the signature of a UserOp. When EntryPoint calls the wallet for validateUserOp function, the wallet would go to ask the validator that UserOp specifies. This allows us to easily add any kind of key verification logic to our wallet. Currently, we have the simple ECDSA validator, multi-sig validator and the time-delayed version of those two (to schedule your transaction). We will also add session-key validator, secure enclave validator of IOS and passkey validator based on webauthn.
We designed two types of validator: normal validator and sudo validator. The normal validator cannot access the storage of the wallet and other validators, and cannot do delegate calls. This means that only the sudo validator can enable or disable other validator. And all the transactions coming out from normal validator would have to first go through another component: Hooks.
A Hook is a contract that the user can use to add custom logic before and after the execution of normal transactions. Hooks can perform checks on the transaction logic, such as the recipient address, called function selectors and parameters, as well as modifications in the wallet state, such as token balance. If any condition set by the Hooks is not met, the Hooks will throw an error, causing the wallet to reject the transaction. The introduction of Hooks provides additional security protection for the wallet.
Additionally, a wallet can add multiple Hooks, and these Hooks operate independently without interfering with each other, which we believe will bring convenience to third-party Hooks developers.
As an example, we have implemented SpendingLimitHooks which allows users to set daily usage limits for native tokens and ERC20 tokens. Before each normal transaction, SpendingLimitHooks checks and updates the token usage. If the pre-set limit is exceeded, the user needs to use a sudo validator, such as the multi-sig validator, to authorize the token usage(as sudo transactions would not have to go through hooks). This design ensures the security of your high-value assets while maintaining a good user experience for your day-to-day usage.
The Module component is the last piece of the puzzle to a butter-like spending experience. Versa owners can use this sophisticated component to add any logic to their wallet and feed Modules with off-chain data and on-chain functions. For users with advanced needs, Modules make it possible to bridge their everyday Web2 experience and the Web3 capacities. With Modules, the list of Versa use cases only stops with developers' imagination. If you are familiar with other AA wallets, our Module design is pretty much like the Safe's.
In Versa, the Module is the ultimate backup for extendibility. As the Validator and Hooks have already served to add custom logic for verifying and transaction checking, we expect Modules to be the advanced option for developers to do fancy functions like on-chain automatic arbitrages and so on. To avoid any malicious Modules, Versa is dedicated to reviewing any implication with the closest attention.
You may have seen other AA wallets that are also built on a modular framework. Versa is unique in the way we architect with high flexibility and robust security for retail users:
1. The abstraction of user activity verification
Unlike embedding the verification logic within the wallet contract itself, Versa Wallet abstracts the process of verifying user activity into validators. A validator implements the signature verification logic for ERC-4337 UserOp and EIP-1271, which allows users to flexibly choose their preferred verification method based on their needs for security, privacy, and convenience. Users can set up their wallet as a multi-sig wallet, MPC wallet, or PassKey wallet, or use different verification methods in different scenarios, providing them with great flexibility in usage.
2. The two levels set of security in verification methods
Versa divides validators and transactions into two levels: sudo and normal, based on the security of different verification methods and the risk associated with user behavior. User actions must match their chosen verification method. For example, if a user has selected ECDSA as the normal validator and multi-signature as the sudo validator, and they intend to execute a high-risk operation, such as modifying the ECDSA owner or multi-signature guardians, the user is only permitted to authorize the operation using the more secure multi-signature verification method. Additionally, Versa supports the use of Hooks to implement finer behavior management for normal transactions. This design provides a robust risk management mechanism for multiple coexisting verification methods, maximizing the security of user assets.
3. Flexible and secure plug-in management system
Versa provides a powerful plug-in management mechanism that enables the orderly collaboration of various components within the wallet. In addition to the flexibility of validators, Versa offers Hooks and Modules to extend wallet functionality and customize wallet behavior. Furthermore, Versa provides a FallbackManager to enhance the native capabilities of the wallet. This architecture enables Versa to have strong composability backward compatibility.
Zerodev’s Kernel v1 also put the validating logic and execution logic together and used diamond patterns. Kernel v2 also separates the idea of a validator and executor. What makes Versa different from Kernel is that Versa does not require the executor’s function to be strictly tied to a specific validator.
As Versa is designed for retail users to further push Web3 mass adoption, linking the executor and designated validator just to enable a function would cause extra complexity and barriers to use.
Alternatively, Versa sets two roles of validators to mimic the good old admin and user style in permission control. Versa also has Hook components to do verification for transactions. Otherwise, plugin developers would have to route all the transactions to the plugin and check themselves if they decide to enable functions like spending limit. Imagine routing all the transactions if plugin devs just need to put the spending limit on the local key but not on the multi-sig, they would have to create another executor only for the local key and link that executor to the local key validator. This could get messy especially when a user has a number of keys and devices or would like to change each permission accordingly.
You may have seen other AA wallets that are also built on a modular framework such as Soul Wallet. The main difference is that Versa extends the logic of UserOp’s signature to extract a component like a validator, instead of putting logic like social recovery in a separate module.
For example, when users apply the social recovery function, Versa would not need to call the social recovery module to change the storage in the wallet. Calling a module means that you need to have another working wallet (no matter EOA or AA), which requires users to have another wallet just for recovering a wallet. This creates an extra burden for retail users. In Versa, social recovery’s signature can pass the ValidateUserOp function in the validator, all you have to do is to broadcast your signed recovery UserOp to the bundler, and let the 4337 magic do the rest for you.
Another main difference is that Versa has set a security level for the modules so that the wallet does not need to specify which selector the modules can use. This design could simplify the whole permission control process when more validators are adding up. A case with no such security level for modules would limit the wallet to change the storage in the social recovery module so that the wallet ends up making another module called SecurityControlModule. This could be too complex for retail users and put extra effort to add or update the module’s validation logic. By using a separate validator component and two sets of security levels, we are confident that Versa is delivering the most secure and extendable modular system just like any Web2 institutional account (think of the root and IAM user in AWS account).
Versa was initiated by learning from Safe's core. However, Versa now only inherits the ModuleManger.sol contract in Gnosis Safe for module management with considerations that:
Safe is not the most efficient 4337 solution and was originally designed for institutional usage. As for an AA wallet, Safe enables 4337 compatibilities through a module and 4337 fallback manager to remain its core as a multi-sig wallet.
Simplicity is key. Versa puts the 4337 compatibility in the wallet contract to avoid complexity issues just as in Safe. Safe has no validator abstraction, so to add another validation method, you would have to add an entire module, also triggering the problem of calling module from another wallet in social recovery.
By extending the validation logic, and extracting the hook and modules, the Versa Core Architecture allows the flexible development of any custom verification logic, transaction automation and permission control.
Versa Core v1.0 has begun the auditing process, and will soon enter public beta. Here are some more resources for learning more about Versa's contract design:
If you’d like to share feedback, suggest improvements, or explore collaboration opportunities, please get in touch with us at:
Twitter: https://twitter.com/versawallet
Telegram: https://t.me/versawallet
Discord: https://discord.gg/gGkcce2mRM
