Thirdweb Modular Account Contracts

A comprehensive collection of smart contract wallet implementations and supporting infrastructure, featuring modular account abstraction contracts compatible with ERC-4337 and ERC-7579 standards.

Overview

This repository contains production-ready smart contract implementations for:

• Modular Account Wallets - Full-featured ERC-4337/ERC-7579 compatible smart wallets
• Minimal Accounts - Lightweight ERC-7702 account implementations
• Paymaster Contracts - Transaction sponsorship and gas abstraction
• Validation Systems - Signature verification and transaction validation
• Access Control - Ownership and role-based permission management

Security Audit

The MinimalAccount and Paymaster contracts have been audited by 0xMacro. View the full audit report: https://0xmacro.com/library/audits/thirdweb-22

Core Contracts

🔐 Account Implementations

ModularAccount (ModularAccount.sol)

• Purpose: Full-featured smart contract wallet with modular architecture
• Standards: ERC-4337, ERC-7579, ERC-1271 compatible
• Features:
  • Modular plugin system (validators, executors, hooks, fallbacks)
  • Multi-signature support
  • Role-based access control
  • Batch transaction execution
  • Upgradeable via UUPS proxy pattern
  • Gas-efficient execution with EntryPoint integration

MinimalAccount (7702/MinimalAccount.sol)

• Purpose: Lightweight account implementation for ERC-7702
• Features:
  • Session-based permissions
  • Multi-signer support
  • Call and transfer policies
  • Minimal gas overhead
  • EIP-712 signature validation

🏭 Factory Contracts

ModularAccountFactory (ModularAccountFactory.sol)

• Purpose: Deploy and manage ModularAccount instances
• Features:
  • Deterministic account addresses
  • Module whitelist management
  • Beacon proxy pattern for upgrades
  • Gas-optimized deployment

AccountProxy (AccountProxy.sol)

• Purpose: Minimal proxy for account contracts
• Features:
  • Low deployment cost
  • Delegate all calls to implementation

✅ Validation System

DefaultValidator (DefaultValidator.sol)

• Purpose: Standard ECDSA signature validation for accounts
• Features:
  • EIP-712 structured signature validation
  • Multi-signer support with threshold
  • Session key validation
  • Compatible with ERC-7579 validator interface

🎛️ Manager Contracts

ExecutorManager (ExecutorManager.sol)

• Purpose: Manage executor modules for accounts
• Features: Install, uninstall, and validate executor modules

ValidatorManager (ValidatorManager.sol)

• Purpose: Manage validator modules for signature verification
• Features: Validator lifecycle management and validation routing

HookManager (HookManager.sol)

• Purpose: Manage pre/post execution hooks
• Features: Hook installation and execution flow management

FallbackManager (FallbackManager.sol)

• Purpose: Manage fallback handlers for unknown function calls
• Features: Fallback routing and handler management

💳 Paymaster Contracts

Transaction sponsorship and gas abstraction layer supporting multiple EntryPoint versions.

Version 7 (Latest)

• BasePaymasterV7 - Base implementation for v0.7 EntryPoint
• VerifyingPaymasterV7 - Signature-based transaction sponsorship
• ShieldedVerifyingPaymasterV7 - Enhanced security with additional verification

Version 6 (Legacy)

• BasePaymasterV6 - Base implementation for v0.6 EntryPoint
• VerifyingPaymasterV6 - Signature-based sponsorship for v0.6
• ShieldedVerifyingPaymasterV6 - Enhanced v0.6 implementation

Supporting Contracts

• MultiSigner - Multi-signature verification for paymasters

🛡️ Access Control

Ownable Contracts (ownable/)

Ownable (Ownable.sol)

• Purpose: Single owner access control pattern
• Features:
  • Owner transfer functionality
  • 2-step ownership transfer for security
  • Zero address protection

OwnableRoles (OwnableRoles.sol)

• Purpose: Role-based access control with ownership
• Features:
  • Hierarchical role system
  • Role granting/revoking
  • Role-based function access
  • Owner has super-admin privileges

🔌 Interfaces

Standard interfaces ensuring compatibility with ecosystem standards:

• IERC4337Account - Account abstraction interface
• IERC7579Account - Modular account interface
• IERC7579Module - Module interface (validator, executor, hook, fallback)
• IModularAccount - Thirdweb modular account interface
• IERC165 - Interface detection
• IERC721Receiver - NFT receiving capability
• IERC1155Receiver - Multi-token receiving capability

🛠️ Development Setup

Prerequisites

• Foundry toolkit installed

Installation

git clone <repository-url>
cd contracts-modular-account
forge install

Build

forge build

Test

forge test

Format Code

forge fmt

Gas Analysis

forge snapshot

📋 Architecture

The modular account system follows a plugin-based architecture:

1. Core Account: Base wallet functionality with standard features
2. Validators: Handle signature verification and authorization
3. Executors: Process and execute transactions
4. Hooks: Pre/post execution logic (logging, validation, etc.)
5. Fallbacks: Handle calls to non-existent functions
6. Paymasters: Sponsor gas costs for user operations

This design enables:

• Composability: Mix and match components based on needs
• Upgradeability: Add new features without changing core contracts
• Gas Efficiency: Only pay for features you use
• Security: Isolated module permissions and validation

🔗 Standards Compliance

• ERC-4337: Account Abstraction via Entry Point Contract Specification
• ERC-7579: Minimal Modular Smart Accounts
• ERC-7702: Set EOA account code for one transaction
• ERC-1271: Standard Signature Validation Method for Contracts
• EIP-712: Typed structured data hashing and signing

📄 License

This project is licensed under the Apache-2.0 License.