Skip to main content

Smart Contracts architecture

In this document, we will provide a comprehensive overview of the W3Smart Wallet’s smart contract architecture. The diagram below illustrates the relationships between various smart contracts used in the W3Smart Wallet system.

Smart contract architecture overview Smart contract architecture overview

Entrypoint​

The Entrypoint smart contract is a vital component of the W3Smart Wallet’s smart contract architecture, serving as a singleton contract responsible for executing bundles of UserOperations. Upon receiving a UserOperation, the Entrypoint will execute the operation to the sender. Additionally, the Entrypoint calculates the transaction fee based on the gas used and the gas price set in the UserOperation.

In situations where the Sender lacks a contract account, the Entrypoint calls upon the AccountDiamondFactory contract to create a new contract account. With its crucial functions in handling fee calculations, ensuring the authenticity and security of UserOperations, and facilitating the creation of new contract wallets, the Entrypoint plays an indispensable role in the W3Smart Wallet architecture.

AccountDiamond​

Account Diamond is implemented as a smart contract that delegates calls to other implementation smart contracts using the Diamond pattern. This design allows the separation of concerns and the ability to upgrade individual contracts without affecting the rest of the account. The following are the implementation smart contracts used by W3Smart Wallet:

  • BaseAccount: This contract is required to initialize the account, update the implementation address of functions, and update the AccountRegistry contract address. All of these are must-have functions, so the BaseAccount contract address has to be immutable in the AccountDiamond contract. This ensures the stability and security of the system and is a necessary measure to maintain the integrity of the platform.
  • DefaultAccount: Used as the default implementation for an account that is deployed by the AccountDiamondFactory. In order to provide the full range of features offered by the W3Smart Wallet, it inherits from four underlying smart contracts (EIP4337Account, GuardianManager, TransactionManager and SecurityManager). This design is implemented to reduce the gas costs associated with deploying a W3Smart Wallet's account.
  • EIP4337Account: This contract implements the EIP4337 compatible features of the W3Smart Wallet's account. The most important feature is to verify the UserOperation's signature.
  • GuardianManager: This contract implements the guardian-related features of the W3Smart Wallet's account, such as adding new guards and removing them.
  • TransactionManager: This contract implements the transaction-related features of the W3Smart Wallet's account, such as sending and sending batch transactions, as well as handling the whitelist logic.
  • SecurityManager: This contract implements the security-related features of the W3Smart Wallet's account, such as locking, unlocking, and recovery.

Paymaster​

The Entrypoint logic is extended to support paymasters that can sponsor transactions for other users. This feature allows application developers to subsidize fees for their users and allows users to pay fees with ERC-20 tokens.

AccountDiamondFactory​

The AccountDiamondFactory is a smart contract designed to facilitate the creation of new contract accounts with high efficiency and reliability. Its unique feature of storing the bytecode for the AccountDiamond contract within itself, allowing for efficient deployment of new contract accounts. This improves the scalability of the system and minimizes gas costs.

When the Entrypoint contract receives a UserOperation that requires the creation of a new contract account, it calls the AccountDiamondFactory contract to deploy a new instance of the AccountDiamond contract. The AccountDiamondFactory uses the init code defined in the UserOperation to initialize the new contract account with the required features.

AccountRegistry​

The Authorized Accounts list is a shared whitelist that is managed by an AccountRegistry smart contract. This list allows users to interact with trusted vendors and dApps without requiring guardian signatures.

Summary​

It's important to note that the EIP4337Account contract implements the EIP4337 compatible features of the W3Smart Wallet's account. We encourage readers to refer to the EIP4337 documentation to gain a deeper understanding of these features.

Overall, the W3Smart Wallet architecture is designed to provide users with a secure and flexible way to manage their assets. The use of smart contracts and the Diamond pattern allows for easy upgrades and customization, while still ensuring the security and integrity of the wallet's functionality.