How to Design a Smart Account Plugin Architecture

A plugin architecture transforms a smart account from a monolithic contract into a composable system. Instead of baking all logic—like social recovery, session keys, or batched transactions—into a single contract, you create a core account abstraction (AA) entry point that delegates specific functions to external, swappable modules. This design, pioneered by standards like ERC-4337 and implemented by projects such as Safe{Wallet} and ZeroDev, separates concerns. The core account handles ownership validation and transaction execution, while plugins manage discrete features, enabling permissionless innovation and user-customized security models.

The core technical pattern involves an account proxy and a logic contract. The proxy, which holds the user's assets and state, delegates delegatecall operations to a logic contract containing the core validation and execution functions. Plugins interact with this system through well-defined interfaces. For example, a recovery plugin might implement a validateRecovery function that the core logic calls. Key design decisions include: - Execution flow: Does the plugin run before, after, or instead of the main execution? - State management: How does the plugin read from or write to the account's isolated storage? - Permissioning: Who can install or remove plugins—the owner, a guardian, or via multi-sig?

Implementing a basic plugin hook in Solidity involves defining interfaces and using function delegates. Below is a simplified example of a core account that checks for a validation plugin:

solidityCopy
interface IValidationPlugin {
    function validateUserOp(
        UserOperation calldata userOp,
        bytes32 userOpHash
    ) external returns (uint256 validationData);
}

contract ModularAccount {
    address public validationPlugin;

    function setValidationPlugin(address _plugin) external onlyOwner {
        validationPlugin = _plugin;
    }

    function _validateUserOp(UserOperation calldata userOp, bytes32 userOpHash)
        internal
        override
        returns (uint256 validationData)
    {
        if (validationPlugin != address(0)) {
            return IValidationPlugin(validationPlugin).validateUserOp(userOp, userOpHash);
        }
        // Default validation logic
        return super._validateUserOp(userOp, userOpHash);
    }
}

This pattern allows the account's validation strategy to be upgraded without migrating assets.

Security is the paramount concern in plugin design. Each plugin operates with the full authority of the smart account, making malicious or buggy code catastrophic. Mitigations include: - Formal verification of core and plugin contracts. - Registry patterns where only audited plugins can be installed, as seen in Safe{Wallet}'s Zodiac framework. - Runtime validation using techniques like function allow-lists or gas limits for plugin calls. - Sandboxed execution where plugins cannot call certain privileged functions. The ERC-6900 standard proposal aims to formalize these interfaces and permission guards to improve interoperability and security across the ecosystem.

For developers, the workflow involves using SDKs from existing AA providers. With ZeroDev's Kernel, you can create a plugin that implements the IPlugin interface and deploy it. Alchemy's Account Kit or Stackup's Bundler can then be used to generate UserOperations that invoke your plugin's logic. Testing must be exhaustive, simulating malicious transaction flows and upgrade scenarios. The end goal is a user-centric account that can evolve over time, integrating new transaction types from Uniswap, new security models from OpenZeppelin, or novel recovery methods, all without sacrificing the security of the underlying asset store.

Smart accounts, like ERC-4337 accounts or Safe{Core} modules, move beyond simple EOAs by enabling programmable logic. A plugin architecture allows developers to extend this logic post-deployment without modifying the core account contract. This is achieved by designing a system where the main account acts as an execution hub, validating and routing calls to external, modular components. Key to this design is a secure validation and execution flow that prevents unauthorized plugin interactions while maintaining composability.

The foundation of a secure plugin system is a robust permission model. This defines which plugins can be installed, who can install them (the account owner, a multi-sig, a DAO), and what operations they are authorized to perform. Common patterns include function signature allowlists, delegate call restrictions, and spending limits. For example, a plugin might only be permitted to call transfer on a specific ERC-20 token up to a daily limit. Implementing these checks in a central validateUserOp or isValidSignature function is critical for security.

Plugins typically interact with the main account via delegatecall or static calls. Using delegatecall allows the plugin to execute in the context of the account's storage, which is powerful but dangerous. A safer pattern is the handler pattern, where the main account makes external calls to plugin contracts. The Safe{Core Protocol uses this approach with Manager and Module contracts. Always implement a dependency management system to handle plugin upgrades and ensure that removing one plugin doesn't break others.

Consider the user experience (UX) implications of your architecture. Plugins should be discoverable and composable. A registry contract can map plugin addresses to metadata and compatibility flags. For execution, design a standard interface like IPlugin with methods for onInstall, onUninstall, and execute. This allows the account to initialize plugin storage and clean it up safely. Use ERC-165 for interface detection so the account can verify a contract supports the required plugin standard before installation.

Security auditing is non-negotiable. Each plugin increases the account's attack surface. Enforce mandatory security reviews for all plugins in a registry. Implement circuit breakers or timelocks for critical operations like changing ownership or upgrading core logic. Use established libraries like OpenZeppelin's for access control and pausable mechanisms. Finally, design for gas efficiency; plugin validation and execution should minimize overhead to keep user operation costs competitive with traditional transactions.

An execution hook is a smart contract that implements a specific interface, allowing it to be plugged into a modular account's transaction lifecycle. When a user initiates a transaction, the account's core logic calls each registered hook in sequence. The hook can perform pre-execution logic—such as validating a signature, checking a spending limit, or adding a fee payment—and must return a boolean indicating whether the transaction should proceed. This architecture, central to standards like ERC-4337 and ERC-6900, transforms smart accounts from monolithic contracts into composable platforms where functionality is defined by its plugins.

Designing a robust plugin architecture requires defining clear interfaces and a secure execution flow. The core account contract should maintain a registry of enabled hooks and their execution order. A common pattern is the validateUserOp and execute flow from ERC-4337, where hooks are invoked during validation. For example, a SpendingLimitHook would check if the transaction value is below a daily cap stored for the user. The hook must be stateless for validation to be gas-efficient, performing only reads and reverting if conditions aren't met. This separation ensures the core account remains upgradeable and secure, while hooks manage specific policies.

Implementation involves writing a hook contract that adheres to a standard interface. Using Solidity and the ERC-6900 reference, a basic hook includes a preCheck and postCheck function. The preCheck function receives the user operation data and can validate custom logic.

solidityCopy
interface IHook {
    function preCheck(
        address account,
        UserOperation calldata userOp,
        bytes calldata hookData
    ) external returns (bool);
}

A SessionKeyHook might use hookData to verify a signed timestamp, allowing transactions only within a specific time window. Hooks should be immutable and audited once deployed, as they handle critical security logic.

Key considerations for production hook design include gas overhead, reentrancy risks, and hook ordering dependencies. Each hook adds gas cost to the user's transaction, so logic must be minimal. To prevent reentrancy, hooks should not make external calls to untrusted contracts during the validation phase. Furthermore, if one hook's logic depends on another's state change, their execution order in the registry is critical; a fee payment hook must run before a hook that validates the final balance. Testing hooks in isolation and within the full account flow using frameworks like Foundry is essential to ensure security and correct integration.

Real-world use cases demonstrate the power of this pattern. The Safe{Wallet} ecosystem uses Guards and Modules as hook-like components for transaction screening and automated executions. A RecoveryHook could allow a social recovery module to co-sign a transaction if the primary key is lost. A BatchHook could aggregate multiple token transfers into a single user operation, saving gas. By decoupling these features, teams can develop, audit, and deploy hooks independently, and users can curate a personalized security and feature set for their smart account without needing a full contract migration.

A plugin architecture for smart accounts, like those in ERC-4337 or ERC-6900, separates core account logic from optional features. The core account—a minimal, audited contract—manages ownership and validation. Extensions, or plugins, are separate contracts that add specific capabilities: - social recovery - session keys - batched transactions - gas sponsorship. This separation enhances security by limiting the attack surface of the core contract and allows for permissionless innovation in plugin development.

Secure installation requires a manifest and validation system. Each plugin should publish a manifest—an on-chain or off-chain record detailing its interface, required permissions, and dependencies. Before installation, the account must validate this manifest against a registry or a security policy set by the account owner. The installation function, often called installPlugin, must enforce that only the account itself (via an authorized user operation) can execute it, preventing unauthorized modifications. Critical checks include verifying the plugin's bytecode hash and ensuring no dependency conflicts.

The installation mechanism typically uses delegatecall or a similar pattern to execute plugin logic in the context of the account's storage. For example, when a user op triggers a plugin's function, the account delegatecalls the plugin contract. This allows the plugin to modify the account's storage but requires strict access control to prevent storage collisions. A common pattern is to use namespaced storage slots, where each plugin is allocated a specific range of slots using bytes32(uint256(keccak256("plugin.namespace")) - 1) to avoid overwriting critical state.

Removal, or plugin uninstallation, must be as secure as installation. A removePlugin function should deactivate the plugin's hooks and clear its allocated storage. However, simply disabling calls is not enough; you must also consider data persistence. Some plugins may leave residual state that could be exploited. Best practice is to implement a cleanup hook that the plugin can optionally define, which is called during removal to sanitize state. Uninstallation should also update the account's internal plugin whitelist to prevent the deactivated code from being called.

To manage risks, implement a timelock or voting mechanism for critical plugins. For accounts controlled by multisigs or DAOs, installing a plugin that changes fee mechanics or ownership logic should have a mandatory delay. Furthermore, design your architecture to support plugin dependency graphs. If Plugin B depends on Plugin A, uninstalling A should either be blocked or trigger a cascading removal of B. Tools like Etherscan's Sourcify can be used to verify plugin metadata, and frameworks like Safe{Core} Protocol provide reference implementations for these patterns.

Finally, audit and test the plugin lifecycle extensively. Use fuzzing tools like Echidna to test unexpected sequences of installPlugin and removePlugin calls. Ensure your system handles malicious plugin manifests and reentrancy during the installation phase. By formalizing the install/remove cycle with strict checks, namespaced storage, and dependency management, you create a robust foundation for a modular smart account ecosystem that balances flexibility with security.

A plugin permission system defines the rules governing which plugins a smart account can execute and under what conditions. Unlike monolithic contracts, modular accounts delegate functionality to external modules, making a formalized security model essential. The primary goal is to prevent unauthorized or malicious plugins from accessing the account's assets or state. This is typically implemented through an on-chain registry or a validation hook within the account's core entry point, such as the validateUserOp function in ERC-4337. The system must answer a critical question for every transaction: is this plugin call authorized?

Design your system around a central Plugin Manager. This can be a separate contract or integrated logic within the account core. Its responsibilities include maintaining a whitelist of approved plugin addresses, storing associated execution permissions (e.g., CALL, DELEGATECALL, CREATE), and enforcing validation rules. A common pattern is to store a mapping from (account address, plugin address, function selector) to a permission struct. When a user operation is validated, the manager checks this mapping. For dynamic rules, the manager can call an isValidSignature-style function on the plugin itself or a separate policy contract that evaluates complex logic like spending limits or multi-signature requirements.

Implement granular permission levels to balance security and flexibility. Common tiers include: Unrestricted (plugin can call any contract), Restricted (plugin can only call pre-approved target addresses), and Self-Only (plugin can only modify the account's own storage). For DELEGATECALL plugins, which execute in the account's own context, you need the highest level of trust and should implement strict, often immutable, whitelisting. Consider using function selectors to restrict plugins to specific methods, preventing them from calling unexpected functions on target contracts. This granularity prevents a plugin with permission to interact with a DEX from being tricked into draining funds to an attacker's address.

Integrate the permission check into the account's validation flow. For ERC-4337 accounts, the validateUserOp function should decode the calldata to identify the target plugin and requested function. It then queries the Plugin Manager. If the call is unauthorized, validation must fail, causing the entire user operation to revert. For native AA implementations (like ERC-7579), a similar hook exists in the account's execution path. Always validate permissions before execution, not during. This "fail-fast" approach saves gas and prevents partial state changes. Log permission grants and revokes as events for off-chain monitoring and to enable easy account recovery or audit trails.

Consider upgradeability and security trade-offs. An immutable permission rule set is most secure but least flexible. A system where the account owner can freely update permissions is flexible but introduces risk if the owner's key is compromised. A hybrid approach uses security periods (timelocks) for critical changes or guardian multi-sigs. For team or DAO-controlled accounts, use a modular policy contract that encodes the organization's governance rules. Always reference established standards where possible, such as the permission flags proposed in ERC-7579, to ensure compatibility with future tooling and plugin ecosystems. Your design choices here fundamentally define the account's security model.

A smart account plugin architecture separates core account logic from optional, user-installable features. The core account, often an ERC-4337 Account contract, acts as a minimal proxy or diamond proxy that delegates specific function calls to external plugin modules. This design enables permissionless innovation, where developers can create plugins for social recovery, session keys, batched transactions, or novel signature schemes without modifying the core wallet contract. The architecture's success hinges on a secure execution flow where the account validates and routes user operations (UserOperations) to the appropriate plugin.

The primary technical challenge is managing plugin lifecycle and permissions. A robust architecture must define clear interfaces for installation, removal, and upgrade of plugins. Common patterns include using an allowlist registry for vetted plugins or a permissionless registry with security audits. Each plugin should implement a standard interface, such as a validateUserOp hook for pre-execution logic and an execute hook for the core action. The main account contract's validateUserOp function must aggregate validation from all active plugins relevant to the operation, ensuring composability without introducing security vulnerabilities.

Security is paramount. Plugins operate with the account's authority, so the architecture must enforce strict execution boundaries. Key considerations include: preventing reentrancy between plugins, ensuring gas limits per plugin to avoid DoS, and implementing dependency checks to avoid conflicts. Using a manifest system where plugins declare their required permissions, accessed storage slots, and callable functions helps the account perform safety checks. For example, a plugin should not be able to modify the account's ownership state unless explicitly granted that right. Frameworks like Safe{Core} Protocol and ZeroDev Kernel provide reference implementations of these patterns.

Implementing a plugin marketplace requires an on-chain registry and off-chain indexer. The registry, a smart contract, stores plugin metadata, developer addresses, and version history. The off-chain indexer (a subgraph or API) enables discoverability, filtering, and displaying audit reports. When a user initiates a transaction to install a plugin, the account should verify the plugin's code hash against the registry and check any required proof-of-audit. Transaction flows can be streamlined using ERC-4337 bundlers to pay gas fees abstractly. This creates a seamless user experience similar to installing a mobile app.

For developers building plugins, focus on modularity and gas efficiency. A well-designed plugin does one thing well and declares its dependencies explicitly. Use the IAccount interface for ERC-4337 compatibility and consider writing plugins as Stateless Libraries or Minimal Proxies to reduce deployment costs. Always include comprehensive tests simulating integration with popular account implementations like Safe or Biconomy. Example plugin types include: transaction schedulers, multi-signature policy enforcers, gas sponsorship managers, and DeFi strategy automators. The future of account abstraction lies in this ecosystem of interoperable, user-curated functionality.

Designing a smart account plugin architecture requires balancing flexibility with security. The core principles are modularity, where each plugin is a self-contained unit; composability, allowing plugins to be safely combined; and upgradability, enabling fixes and new features without migrating the core account. A successful architecture uses a validation-centric model, where the account's entry point validates all operations against a set of installed plugins, each enforcing its own rules via a validateUserOp function. This pattern, used by ERC-4337 bundlers and frameworks like Safe{Core} AA SDK and ZeroDev Kernel, ensures that plugin logic is isolated and security boundaries are clear.

To start building, first define your plugin's validation and execution logic. The validation function must verify the user operation's signatures, nonces, and permissions. The execution function performs the state-changing actions. Use ERC-6900 as a reference standard for interface compatibility. For example, a session key plugin's validation would check a cryptographic signature against a stored public key and a validity timestamp, while its execution could be a simple token transfer. Always implement fallback handlers and guardrails like spending limits to mitigate risks from malicious or buggy plugins.

Next, integrate your plugin with a smart account framework. For Safe{Core}, you would deploy your module and enable it via the enableModule function on a Safe account. For a custom ERC-4337 account, your factory would deploy an account with your plugin pre-installed in its validation logic. Thoroughly test using frameworks like Foundry or Hardhat, simulating complex multi-plugin interactions and edge cases. Security audits are non-negotiable; consider engaging firms like Trail of Bits or OpenZeppelin for a professional review before mainnet deployment.

The future of account abstraction is interoperable plugins. Look towards standards like ERC-7579, which aims to unify how plugins are discovered, installed, and managed across different account implementations. Explore advanced use cases: recurring payments with automated approvals, social recovery schemes, or zk-proof based validation for privacy. Continuously monitor the ecosystem through resources like the Ethereum Magicians forum, ERC-4337's official GitHub, and AA-focused research from teams like Rhinestone and Alchemy to stay current on best practices and emerging patterns.