# sentimentxyz/protocol-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/sentimentxyz/protocol-v2
- Repository: https://github.com/sentimentxyz/protocol-v2

## Overview

##### Main Components
- Smart Contracts (src): Represent the core logic of the protocol. Highlight sub-components such as:
- IRM: Likely related to interest rate models or risk management.
- Lens: Possibly a module to get aggregated state or analysis-related functionality.
- Oracle: For external data feeds (integrated with Redstone oracles).
- Lib: Common internal libraries.
- Interfaces: Standardized interfaces defining interactions.

- Scripts (script): These components handle administrative operations, pool initialization, risk parameter settings, oracle updates, and other protocol maintenance activities. Emphasize that scripts execute transactions using parameters from external configuration files (pointed to by SCRIPT_CONFIG and FORK_TEST_CONFIG in .env).

- DevOps/CI Pipeline (.github/workflows): Represent the automation for testing and deployment triggers.

- Configuration & Environment Setup: Foundry configuration (foundry.toml and remappings), .env for environment variables, and JSON config files for scripts and fork tests.

##### Relationships and Interactions
- The core smart contracts (under src) interact with each other to form the protocol's logic.
- Scripts (under script) are used to deploy, initialize, and manage the protocol, invoking the smart contract methods and using external configuration data.
- The tests (under test) simulate interactions between these components, ensuring that the smart contract logic and integrations work as expected.
- The CI/CD pipeline (via GitHub actions in .github/workflows) automatically runs tests and possibly triggers deployments.
- External dependencies from lib (including the OpenZeppelin libraries and Redstone oracles) are utilized by the smart contracts to ensure security and to interface with external data feeds.

##### Architectural Patterns and Design Principles
- Modular Decomposition: Different functionalities (IRM, Lens, Oracle, Risk, etc.) are clearly separated to isolate concerns.
- Dependency Injection: Likely used when deploying and interacting with different contracts.
- Test-Driven Development: The comprehensive test directory shows a strong commitment to testing, including both unit and integration tests.
- External Configuration Management: Environment variables via .env and external JSON configuration files for dynamic script parameters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contracts (On-Chain Logic)
    subgraph "Smart Contracts (On-Chain Logic)"
        IRM["IRM Module"]:::contract
        Lens["Lens Module"]:::contract
        Oracle["Oracle Module"]:::contract
        Lib["Common Libraries"]:::contract
        Interfaces["Standardized Interfaces"]:::contract
    end

    %% Deployment & Management Scripts (Off-Chain Automation)
    subgraph "Deployment & Management Scripts (Off-Chain Automation)"
        IRM_Scripts["IRM Scripts"]:::script
        Lens_Scripts["Lens Scripts"]:::script
        Oracle_Scripts["Oracle Scripts"]:::script
        Pool_Scripts["Pool Scripts"]:::script
        PositionManager_Scripts["Position Manager Scripts"]:::script
        Risk_Scripts["Risk Scripts"]:::script
        SuperPool_Scripts["SuperPool Scripts"]:::script
    end

    %% Testing Setup
    subgraph "Testing Setup"
        Core_Tests["Core Tests"]:::test
        Integration_Tests["Integration Tests"]:::test
        Mocks["Mocks"]:::test
        Lib_Tests["Lib Tests"]:::test
        Util_Tests["Util Tests"]:::test
        Oracle_Tests["Oracle Tests"]:::test
        Repro_Tests["Repro Tests"]:::test
        Guardian_Tests["Guardian Tests"]:::test
        Hyperliquid_Tests["Hyperliquid Tests"]:::test
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CI_CD["GitHub Actions"]:::ci
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        Foundry_Config["Foundry Config"]:::config
        Env[".env & JSON Configs"]:::config
    end

    %% External Libraries & Dependencies
    subgraph "External Libraries & Dependencies"
        ForgeStd["Forge-std"]:::external
        OpenZeppelin["OpenZeppelin Contracts"]:::external
        OpenZeppelin_Upgradeable["OpenZeppelin Upgradeable"]:::external
        Redstone["Redstone Oracles"]:::external
    end

    %% Relationships
    %% Deployment Scripts invoke Smart Contracts
    IRM_Scripts -->|"deploys"| IRM
    Lens_Scripts -->|"deploys"| Lens
    Oracle_Scripts -->|"deploys"| Oracle
    Pool_Scripts -->|"deploys"| IRM
    PositionManager_Scripts -->|"manages"| IRM
    Risk_Scripts -->|"updates"| IRM
    SuperPool_Scripts -->|"initializes"| IRM

    %% Data flow within Smart Contracts
    Oracle -->|"feeds_data"| IRM

    %% External Libraries integration
    ForgeStd --> IRM
    OpenZeppelin --> Lib
    OpenZeppelin_Upgradeable --> Lib
    Redstone --> Oracle

    %% Configuration influence
    Foundry_Config --> IRM
    Foundry_Config --> IRM_Scripts
    Env --> IRM
    Env --> IRM_Scripts

    %% Scripts calling additional contract methods
    IRM_Scripts -->|"calls"| Lib
    Lens_Scripts -->|"calls"| Interfaces
    Oracle_Scripts -->|"calls"| Interfaces

    %% Testing verifies Smart Contracts
    Core_Tests -->|"tests"| IRM
    Integration_Tests -->|"tests"| Lens
    Oracle_Tests -->|"tests"| Oracle
    Repro_Tests -->|"tests"| IRM

    %% CI/CD Pipeline executes tests
    Core_Tests --> CI_CD
    Integration_Tests --> CI_CD
    Mocks --> CI_CD
    Lib_Tests --> CI_CD
    Util_Tests --> CI_CD
    Oracle_Tests --> CI_CD
    Repro_Tests --> CI_CD
    Guardian_Tests --> CI_CD
    Hyperliquid_Tests --> CI_CD
    CI_CD -->|"runs"| Core_Tests

    %% Click Events for Smart Contracts
    click IRM "https://github.com/sentimentxyz/protocol-v2/tree/master/src/irm"
    click Lens "https://github.com/sentimentxyz/protocol-v2/tree/master/src/lens"
    click Oracle "https://github.com/sentimentxyz/protocol-v2/tree/master/src/oracle"
    click Lib "https://github.com/sentimentxyz/protocol-v2/tree/master/src/lib"
    click Interfaces "https://github.com/sentimentxyz/protocol-v2/tree/master/src/interfaces"

    %% Click Events for Deployment & Management Scripts
    click IRM_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/irm"
    click Lens_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/lens"
    click Oracle_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/oracle"
    click Pool_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/pool"
    click PositionManager_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/positionManager"
    click Risk_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/risk"
    click SuperPool_Scripts "https://github.com/sentimentxyz/protocol-v2/tree/master/script/superPool"

    %% Click Events for Testing Setup
    click Core_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/core"
    click Integration_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/integration"
    click Mocks "https://github.com/sentimentxyz/protocol-v2/tree/master/test/mocks"
    click Lib_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/lib"
    click Util_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/utils"
    click Oracle_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/oracle"
    click Repro_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/repro"
    click Guardian_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/repro/guardian"
    click Hyperliquid_Tests "https://github.com/sentimentxyz/protocol-v2/tree/master/test/hyperliquid"

    %% Click Event for CI/CD Pipeline
    click CI_CD "https://github.com/sentimentxyz/protocol-v2/blob/master/.github/workflows/test.yml"

    %% Click Events for External Libraries & Dependencies
    click ForgeStd "https://github.com/sentimentxyz/protocol-v2/tree/master/lib/forge-std"
    click OpenZeppelin "https://github.com/sentimentxyz/protocol-v2/tree/master/lib/openzeppelin-contracts"
    click OpenZeppelin_Upgradeable "https://github.com/sentimentxyz/protocol-v2/tree/master/lib/openzeppelin-contracts-upgradeable"
    click Redstone "https://github.com/sentimentxyz/protocol-v2/tree/master/lib/redstone-oracles-monorepo"

    %% Click Event for Configuration & Environment
    click Foundry_Config "https://github.com/sentimentxyz/protocol-v2/blob/master/foundry.toml"

    %% Styles
    classDef contract fill:#f9c,stroke:#333,stroke-width:2px;
    classDef script fill:#bbf,stroke:#333,stroke-width:2px;
    classDef test fill:#bfb,stroke:#333,stroke-width:2px;
    classDef ci fill:#ff9,stroke:#333,stroke-width:2px;
    classDef config fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#cff,stroke:#333,stroke-width:2px;
```
