Nexus Architecture - bcnmy/nexus GitHub Wiki

Nexus Smart Account Architecture

The Nexus Smart Account architecture is designed to provide a robust, modular, and flexible framework for managing smart accounts. This section delves into the architecture of the Nexus project, explaining the core components and how they interact to offer advanced functionalities.


Nexus Smart Accounts are compliant with ERC-7579 and ERC-4337 standards, allowing for modularity and extensibility. The architecture is composed of several key contracts, interfaces, and libraries, each serving a specific purpose. The following diagrams illustrate the overall flow and structure of the Nexus Smart Account system.

Architectural Diagrams

Modular Smart Account Flow

Modular Smart Account Flow

This diagram depicts the overall flow of operations within the Nexus Smart Account system, from the deployment of smart accounts to the execution of transactions. Key components include the Smart Account Factory, EntryPoint, Paymaster, Validation Modules, and Execution Modules.

Nexus Architecture

Nexus Architecture

This diagram provides a detailed view of the Nexus architecture, highlighting the relationships between various contracts, interfaces, and libraries.

Core Components

Smart Account Factory

The Smart Account Factory is responsible for deploying new smart accounts. It interacts with the EntryPoint to ensure that smart accounts are created and initialized correctly.


The EntryPoint serves as the main gateway for executing user operations and managing the flow of transactions. It handles validation, gas estimation, and ensures that transactions comply with predefined rules.


The Paymaster module supports various payment schemes, including sponsorship and token-based payments. It ensures that transactions have sufficient gas to execute and handles gas reimbursements.

Validation Modules

Validation Modules are essential for verifying the integrity and authenticity of transactions. They can include various schemes, such as ECDSA ownership, multi-signature validation, and session key management.

Execution Modules

Execution Modules handle the actual execution of transactions. They support different execution modes, including single, batch, and delegate calls. Execution modules ensure that transactions are executed securely and efficiently.

Hook Modules

Hook modules are used to add additional logic before and after transaction executions. They are crucial for adding custom behavior, such as logging, additional validations, or triggering other actions based on the transaction.

  • Pre-Execution Hooks: These are executed before the main transaction logic to perform tasks like input validation or preconditions.
  • Post-Execution Hooks: These are executed after the main transaction logic to perform tasks like logging or triggering subsequent actions.

Fallback Handlers

Fallback handlers manage transactions that do not match any predefined function signatures or encounter errors during execution. They ensure that the smart account can gracefully handle unexpected conditions and provide a mechanism for recovering from errors.

Execution Flow

The execution flow in Nexus Smart Accounts involves multiple steps, including validation, execution, and post-execution hooks. The following subsections explain the different execution types and how they are managed within the system.

Execution Modes

Nexus supports various execution modes to cater to different use cases:

  • Single Execution: Executes a single transaction.
  • Batch Execution: Executes multiple transactions in a single call.
  • Delegate Execution: Executes transactions in the context of another contract.

Execution Functions

The core functions responsible for managing executions are:

  • execute: Handles single or batch transactions based on the specified mode.
  • executeFromExecutor: Allows an executor module to perform transactions on behalf of the smart account.
  • executeUserOp: Executes user operations via a call using the contract's context.

Security Considerations

[!IMPORTANT] Security is paramount in the Nexus architecture. All execution functions are protected by strict access control mechanisms to prevent unauthorized transactions.

  • onlyEntryPointOrSelf: Ensures that only the EntryPoint or the smart account itself can execute certain functions.
  • withHook: Adds pre and post-execution hooks to ensure that additional checks and balances are applied during transaction execution.

Call and Execution Types

  • CallType: Defines how the execution calldata should be decoded (single, batch, or delegate).
  • ExecType: Determines how the account should handle the execution (default, try/catch).

Example Usage

When a user wants to execute a batch of transactions, the execute function is called with the appropriate ExecutionMode. The system will decode the batch, validate each transaction, and then execute them in sequence.

[!NOTE] It's crucial to ensure that all necessary validation modules are installed and configured correctly to maintain the integrity and security of the smart account.


The Nexus Smart Account architecture is designed to offer a high level of flexibility, security, and modularity. By leveraging advanced execution modes and validation mechanisms, Nexus provides a robust framework for managing smart accounts in the Ethereum ecosystem.

For further details and technical documentation, please refer to the Nexus GitHub repository.