# level-money/level-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/level-money/level-contracts
- Repository: https://github.com/level-money/level-contracts

## Overview

##### Project type and overall purpose
- This is a blockchain protocol project focusing on minting and staking a stablecoin (lvlUSD), backed by restaked dollar tokens. The core functionality resides in smart contracts (located in src and integration_tests) and is orchestrated via Foundry (a Solidity testing and deployment framework).
- The protocol creates yield by integrating with on-chain lending protocols and restaking protocols (as noted via operations in contracts, tests, and integrations).

##### File structure
- Top-level directories:
- “src”: Contains the Solidity source files (and possibly interfaces) for the smart contracts.
- “lib”: Third-party libraries such as OpenZeppelin and Forge Standard library, which provide reusable components and security primitives.
- “integration_tests” and “test”: These house the testing scripts and setup files (using Forge and Foundry) that validate the contracts’ logic.
- “script”: Contains helper scripts (like sync_from_monorepo.sh) to assist with deployment or integration.
- “docs”: Contains both documentation and archived audit information. Audits are a critical aspect when dealing with financial protocols.
- In the tests and integration tests, you see multiple directories and files for ABIs representing contracts (like LevelMintingABI, LevelStakingPool, etc.) — these indicate that the system is closely interacting with several contract components.

##### Details from the README
- The README focuses on Level USD’s design for minting and staking, along with requirements such as using Foundry.
- It provides a link to audits, implying that security and verifiability are essential components.
- There might not be a dedicated “frontend” (at least not in this repo), so the primary focus is on smart contract logic and its interactions.

a. Main components:
- Smart Contracts:
- LevelMinting, LevelReserveManager, LevelStakingPool, Token contracts (lvlUSD, possibly erc20 & derivatives from OpenZeppelin).
- Testing & Integration Layer:
- Integration tests (simulate interactions, validate contract behavior, and edge cases).
- External Protocol Interfaces:
- Integration with on-chain lending protocols and AVS (automated value strategies or similar) and restaking protocols.
- Deployment/Script Components:
- Foundry and deployment scripts (sync_from_monorepo.sh, remappings.txt, foundry configuration files).
- Documentation & Audit:
- Auditing reports and documentation archived under “docs” and “docs/archive”.

b. Relationships and interactions:
- Design directional flows among the smart contracts. For example:
- The “Minting” contract receives user inputs (money/tokens) and interacts with the Reserve Manager.
- The Reserve Manager sets aside assets and communicates with the staking contract.
- The Staking Pool then handles the process for users to earn yield.
- “Reserve Manager verifies funds” → “Staking Pool engages yield protocols.”

c. Architectural Patterns and principles:
- There’s a modular design: separate directories for contracts, interfaces, tests, and integrations. This hints at decoupling the business logic from testing and deployment.
- Even though auth is not deeply detailed, note that certain operations (such as minting and staking) likely require role-based access (for example, only authorized wallets or smart contracts can trigger sensitive operations). Document these roles:
- Admin/Operator: Likely has privileges to configure or pause the protocol.
- User: Can mint and stake.
- Auditor: External entity reviewing the interactions (linking to docs/archive audit reports).

d. Relevant Technologies:
- Foundry (for testing and scripting).
- Solidity for smart contracts.
- OpenZeppelin for pre-built contracts and libraries.
- Integration tools (Mocha configuration under integration_tests, package.json) for running validations.

##### Document roles clearly
- Beside each major component, note which user roles interact:
- "User": Initiates minting and staking.
- "Admin/Operator": Configures settings and may control emergency stops.
- "Auditor": Reviews logs and audit trails (linking to the audit docs provided).

- Lay out major components: User, LevelMinting Contract, LevelReserveManager, LevelStakingPool, External Protocols, and Testing/Deployment scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Roles Legend
    subgraph "Role Legend"
        USER["User (Minter)"]:::role
        ADMIN["Admin/Operator"]:::role
        AUDITOR["Auditor"]:::role
    end

    %% Smart Contracts
    subgraph "Smart Contracts"
        MINT["LevelMinting Contract"]:::contract
        RESERVE["LevelReserveManager Contract"]:::contract
        STAKE["LevelStakingPool Contract"]:::contract
        LVLUSD["lvlUSD Contract"]:::token
        STAKED["StakedlvlUSD Contract"]:::token
    end

    %% Testing & Integration Layer
    subgraph "Testing & Integration"
        INT["Integration Tests"]:::testing
        FOUN["Foundry Tests"]:::testing
        MOCKS["Mocks & Utilities"]:::testing
    end

    %% External Protocol Interfaces
    subgraph "External Protocol Interfaces"
        EXT_MAIN["Yield & Lending Protocols"]:::external
        EXT_AAVE["Aave V3 Pool ABI"]:::external
        EXT_ERC20["ERC20 ABI"]:::external
        EXT_OP["Operator Registry ABI"]:::external
        EXT_USDT["USDT ABI"]:::external
        EXT_VAULT["Vault ABI"]:::external
        EXT_CONFIG["Vault Configurator ABI"]:::external
    end

    %% Deployment & Scripts
    subgraph "Deployment & Scripts"
        DEPLOY_SCRIPT["Deployment Script"]:::deploy
        DEPLOY_CONFIG["Foundry Config & Remappings"]:::deploy
    end

    %% Documentation & Audit
    subgraph "Documentation & Audit"
        DOCS["Documentation"]:::docs
        AUDIT_DOC["Audit Reports"]:::docs
    end

    %% Relationships and Data Flow
    USER -->|"mint(auth:wallet_signature)"| MINT
    ADMIN ---|"oversees"| MINT
    ADMIN ---|"oversees"| RESERVE
    ADMIN ---|"oversees"| STAKE

    MINT -->|"validate_input&reserve_check"| RESERVE
    RESERVE -->|"delegate_stake(auth:operator)"| STAKE

    MINT ---|"collateral_token"| LVLUSD
    MINT ---|"staked_token"| STAKED

    STAKE -->|"query_yield_protocols"| EXT_MAIN

    %% Testing connections
    INT -->|"simulate_txn"| MINT
    INT -->|"simulate_txn"| RESERVE
    INT -->|"simulate_txn"| STAKE
    FOUN -->|"deploy&test"| MINT
    FOUN -->|"deploy&test"| RESERVE
    FOUN -->|"deploy&test"| STAKE
    MOCKS -->|"support_txn"| MINT
    MOCKS -->|"support_txn"| RESERVE
    MOCKS -->|"support_txn"| STAKE

    %% Deployment connections
    DEPLOY_SCRIPT -->|"deploy_via_Foundry"| MINT
    DEPLOY_SCRIPT -->|"deploy_via_Foundry"| RESERVE
    DEPLOY_SCRIPT -->|"deploy_via_Foundry"| STAKE
    DEPLOY_CONFIG -->|"configures_deployment"| MINT
    DEPLOY_CONFIG -->|"configures_deployment"| RESERVE
    DEPLOY_CONFIG -->|"configures_deployment"| STAKE

    %% Documentation connections
    DOCS -->|"audit_verification"| MINT
    DOCS -->|"audit_verification"| RESERVE
    DOCS -->|"audit_verification"| STAKE
    AUDITOR ---|"reviews"| AUDIT_DOC

    %% External Protocol Internal Connections
    EXT_MAIN --> EXT_AAVE
    EXT_MAIN --> EXT_ERC20
    EXT_MAIN --> EXT_OP
    EXT_MAIN --> EXT_USDT
    EXT_MAIN --> EXT_VAULT
    EXT_MAIN --> EXT_CONFIG

    %% Click Events for Smart Contracts
    click MINT "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/LevelMintingABI.ts"
    click RESERVE "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/LevelReserveManagerABI.ts"
    click STAKE "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/LevelStakingPool.ts"
    click LVLUSD "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/LvlUSDABI.ts"
    click STAKED "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/StakedlvlUSDABI.ts"

    %% Click Events for Testing & Integration
    click INT "https://github.com/level-money/level-contracts/tree/main/integration_tests"
    click FOUN "https://github.com/level-money/level-contracts/tree/main/test/foundry"
    click MOCKS "https://github.com/level-money/level-contracts/tree/main/test/mocks"

    %% Click Events for External Protocol Interfaces
    click EXT_AAVE "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/aaveV3Pool.json"
    click EXT_ERC20 "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/erc20ABI.json"
    click EXT_OP "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/operatorRegistry.json"
    click EXT_USDT "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/usdtAbi.ts"
    click EXT_VAULT "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/vaultABI.json"
    click EXT_CONFIG "https://github.com/level-money/level-contracts/blob/main/integration_tests/abis/abis/VaultConfigurator.json"

    %% Click Events for Deployment & Scripts
    click DEPLOY_SCRIPT "https://github.com/level-money/level-contracts/blob/main/script/sync_from_monorepo.sh"
    click DEPLOY_CONFIG "https://github.com/level-money/level-contracts/blob/main/foundry.toml"

    %% Click Events for Documentation & Audit
    click DOCS "https://github.com/level-money/level-contracts/tree/main/docs"
    click AUDIT_DOC "https://github.com/level-money/level-contracts/blob/main/docs/archive/overview.md"

    %% Class Definitions for Colors
    classDef role fill:#FFEFD5,stroke:#333,stroke-width:2px;
    classDef contract fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef token fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef testing fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef deploy fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef docs fill:#F0E68C,stroke:#333,stroke-width:2px;
```
