# immunefi-team/spectra-audit-competition architecture

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

- Interactive diagram: https://gitdiagram.com/immunefi-team/spectra-audit-competition
- Repository: https://github.com/immunefi-team/spectra-audit-competition

## Overview

##### Project Type and Purpose
- This is a smart contract–based DeFi protocol for interest rate derivatives.
- The system is built around the concept of users depositing ERC-4626 compliant tokens (or underlying assets), receiving a Principal Token (PT) and a Yield Token (YT), with additional components for swapping, fee settings, and registry management.
- It is also highly composable and permissionless, using standard contracts (e.g., OpenZeppelin’s Access Manager) and tailored libraries to perform specialized functionality.

##### Main Architectural Components
- Core Contracts:
- Principal Token (PT): Implements EIP-5095 and EIP-2612, handling the separation of yield.
- Yield Token (YT): An ERC-20/EIP-2612 token representing the yield earned.
- Utility and Interaction Contracts:
- Router: Provides utility functions for swapping, liquidity additions/removals, and handling native tokens.
- Factory and FactorySNG: Responsible for deploying new PTs and Curve pools and registering them in the Registry.
- Registry and RateOracleRegistry: Hold key addresses and fee values, and register rate oracles.
- RateAdjustmentOracle (and its math library): Provides adjustment rate calculations for stable swap pools.
- Libraries:
- A suite of libraries (PrincipalTokenUtil, CurvePoolUtil, CurveNGPoolUtil, Roles, NamingUtil, RateAdjustmentMath, etc.) that encapsulate recurring logic and mathematical computations.
- Access and Governance:
- Access Manager and Ownable: Implements roles via OpenZeppelin standards to manage permissions like UPGRADER_ROLE, PAUSER_ROLE, etc.

##### Relationships and Interactions
- Data Flow:
- Users deposit their tokens into the PrincipalToken contract which, in turn, mints both PT and YT.
- The Yield Token contract synchronizes with the Principal Token contract for yield generation.
- The Router facilitates extra operations (such as interacting with external pool protocols like Curve), linking with the deployed PTs and IBTs.
- Factories deploy new tokens and pool contracts and update the Registry so that other components (and external interfaces) can discover the new instances.
- Rate Oracles feed data into Curve-based pools to adjust ratios and yield calculations in real time.
- Dependency and Communication:
- Core contracts call upon libraries for recurrent functions (calculations, naming, role management).
- Multiple contracts interact with the Registry and Access Manager to maintain security and proper configuration.
- Testing and simulation utilities are provided to verify that these interactions hold during fuzz runs and unit tests.

##### Architectural Patterns and Technologies
- The design leverages modularization:
- Single-responsibility contracts (for PT, YT, router, factory, registry, oracles).
- Extensive use of libraries for pure computations and standardized operations.
- Decentralized finance patterns such as deposit-mint-burn mechanisms, dynamic rate oracles, and upgradeable proxies (as judged from the use of OpenZeppelin contracts and foundry/hardhat configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        U("User"):::external
    end

    %% Contract Layer: Core Contracts
    subgraph "Core Contracts"
        PT("PrincipalToken"):::core
        YT("YieldToken"):::core
    end

    %% Utility & Interaction
    subgraph "Utility & Interaction"
        R("Router"):::utility
        F("Factory"):::utility
        REG("Registry"):::utility
        ROR("RateOracleRegistry"):::utility
        RAO("RateAdjustmentOracle"):::utility
    end

    %% Libraries
    subgraph "Libraries"
        LIB("Libraries"):::library
    end

    %% Access & Governance
    subgraph "Access & Governance"
        AM("Access Manager & Ownable"):::access
    end

    %% External Integrations
    subgraph "External Integrations"
        SO("Spectra Oracles"):::external
    end

    %% Connections
    U -->|"deposits"| PT
    PT -->|"mints_YT"| YT
    U -->|"interacts"| R
    R -->|"processes"| PT
    F -->|"deploys"| PT
    F -->|"deploys"| YT
    F -->|"registers"| REG
    RAO -->|"updates"| ROR
    SO -->|"feeds"| ROR
    R -.->|"utilizes"| LIB
    PT -.->|"calls"| LIB
    YT -.->|"calls"| LIB
    RAO -.->|"calculates"| LIB
    F -.->|"calls"| LIB
    AM -->|"manages"| PT
    AM -->|"manages"| YT
    AM -->|"manages"| R
    AM -->|"manages"| F

    %% Click Events
    click PT "https://github.com/immunefi-team/spectra-audit-competition/tree/main/src/tokens"
    click YT "https://github.com/immunefi-team/spectra-audit-competition/tree/main/src/tokens"
    click R "https://github.com/immunefi-team/spectra-audit-competition/tree/main/src/router"
    click F "https://github.com/immunefi-team/spectra-audit-competition/tree/main/src/factory"
    click RAO "https://github.com/immunefi-team/spectra-audit-competition/tree/main/test/RateAdjustmentOracle"
    click LIB "https://github.com/immunefi-team/spectra-audit-competition/tree/main/src/libraries"
    click AM "https://github.com/immunefi-team/spectra-audit-competition/tree/main/lib/openzeppelin-contracts-upgradeable"
    click SO "https://github.com/immunefi-team/spectra-audit-competition/tree/main/src/spectra-oracles"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef utility fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef library fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef access fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
