# sherlock-audit/2023-03-notional architecture

> Architecture diagram of the GitHub repository sherlock-audit/2023-03-notional, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sherlock-audit/2023-03-notional
- Repository: https://github.com/sherlock-audit/2023-03-notional

## Overview

##### Main Components to Identify and Represent
- External Contracts:
- Contracts in the “contracts/external” folder (e.g., CalculationViews, Router, SettleAssetsExternal, Views)
- External actions modules (AccountAction, GovernanceAction, LiquidateCurrencyAction, VaultAction, etc.).
– These are entry points for users or external systems and they route calls into internal logic.
- Internal Contracts:
- Modules under “contracts/internal” (e.g., balances, liquidation, markets, nToken, pCash, portfolio, settlement, valuation, vaults).
– Each subdirectory represents a specific domain (e.g., BalanceHandler, LiquidatefCash, Market, PortfolioHandler, VaultAccount) carrying core business logic.
- Proxy & Upgradeable Components:
- Proxy implementations for ERC1155 (fCash and vault tokens) and ERC20/ERC4626 proxies for PrimeCash, nTokens, and Prime Debt.
- These ensure that contract upgrades happen safely (e.g., Notional V3 proxy, PrimeCashProxy).
- Governance & Administration Modules:
- Governance actions and roles embedded in contracts (like the governance routers, pause router, and actions such as GovernanceAction).
- Off-chain roles (Notional Owner, Pause Guardian, Notional Manager, Treasury Manager) that govern how upgrades, emergency actions, and treasury rebalancing occur.
- Scripting and Deployment:
- Deployment and initialization scripts (folder “scripts” and “deployers”) that show how contracts are instantiated, deployed, and configured.
- Testing Infrastructure:
- Extensive test suites in “tests” (stateful, mainnet-fork, unit tests) that simulate protocol behavior and validate interactions.

##### Relationships and Interactions
- External actions serve as the “front door” for user interactions, aggregating user calls and routing them into the underlying business logic.
- Internal modules perform specific tasks:
- Balance, portfolio, and valuation modules interact to process user funds, determine interest and cash group computations, and maintain collateral balances.
- Liquidation modules listen to risk conditions and interact with both market and balance modules to execute liquidations.
- Proxy contracts abstract the upgradeable architecture, ensuring that user calls are always routed to the correct underlying implementation.
- Off-chain managers (e.g., Treasury Manager, Liquidation Bots) interact with on-chain components via scripted actions (or external calls) to keep the protocol’s state updated.
- External integrations (oracles such as Chainlink, money market adapters like Compound) feed price data and asset information to internal modules.

##### Architectural Patterns and Design Principles
- Modularity: The code is split into “external” and “internal” components for clear demarcation of concerns (front-facing actions versus core business logic).
- Proxy/Upgradeability: Use of proxy contracts enables upgradability without disrupting user state.
- Separation of Concerns: Distinct modules handle governance, market operations, valuations, liquidations, and treasury functions.
- Testing & Deployment Pipelines: Build scripts and Brownie configuration files illustrate a mature CI/CD/testing strategy.

##### Relevant Technologies & Frameworks
- Solidity for smart contract programming.
- Brownie as the development and testing framework.
- Integration with Ethereum networks and potentially layer-2 solutions (Arbitrum and Optimism) in the future.
- Use of ERC standards (ERC1155, ERC20, ERC4626) to ensure protocol interoperability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User / External Calls"]

    %% On-Chain Architecture
    subgraph "On-Chain Architecture"
        EContracts["External Contracts\n(e.g., CalculationViews, Router, SettleAssetsExternal, Views)"]
        EActions["External Actions Modules\n(AccountAction, GovernanceAction, LiquidateCurrencyAction, VaultAction)"]
        Proxy["Proxy & Upgradeable Components"]
        IContracts["Internal Contracts\n(balances, liquidation, markets, nToken, pCash, portfolio, settlement, valuation, vaults)"]
    end

    %% External Integrations (Oracles, Adapters)
    ExtInt["External Integrations\n(Oracles, MoneyMarket Adapters)"]

    %% Deployment & Testing
    subgraph "Deployment & Testing"
        Deploy["Scripting & Deployment"]
        Tests["Testing Infrastructure"]
    end

    %% Off-Chain Governance & Operations
    subgraph "Off-Chain Governance & Operations"
        GovModules["Governance & Administration Modules"]
        OffChainRoles["Protocol Roles\n(Notional Owner, Pause Guardian, Notional Manager, Treasury Manager)"]
    end

    %% Data Flow
    User --> EContracts
    User --> EActions
    EContracts --> Proxy
    EActions --> Proxy
    Proxy --> IContracts
    ExtInt --> IContracts
    GovModules --> IContracts
    OffChainRoles --> GovModules
    Deploy --> Proxy
    Deploy --> IContracts
    Tests --> IContracts

    %% Styles
    class User user;
    class EContracts external;
    class EActions external;
    class IContracts internal;
    class Proxy proxy;
    class GovModules governance;
    class OffChainRoles offchain;
    class Deploy deployment;
    class Tests testing;
    class ExtInt extInt;

    %% Class Definitions
    classDef user fill:#FADBD8,stroke:#943126,stroke-width:2px;
    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef internal fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef proxy fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef governance fill:#85C1E9,stroke:#1B4F72,stroke-width:2px;
    classDef deployment fill:#D5D8DC,stroke:#566573,stroke-width:2px;
    classDef testing fill:#E5E7E9,stroke:#717D7E,stroke-width:2px;
    classDef offchain fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef extInt fill:#FDEBD0,stroke:#D35400,stroke-width:2px;

    %% Click Events
    click EContracts "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/contracts/external"
    click EActions "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/contracts/external/actions"
    click IContracts "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/contracts/internal"
    click Proxy "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/contracts/proxy"
    click GovModules "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/contracts/external/governance"
    click Deploy "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/scripts"
    click Tests "https://github.com/sherlock-audit/2023-03-notional/tree/main/contracts-v2/tests"
```
