# lindy-labs/sandclock-contracts architecture

> Architecture diagram of the GitHub repository lindy-labs/sandclock-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lindy-labs/sandclock-contracts
- Repository: https://github.com/lindy-labs/sandclock-contracts

## Overview

##### Main Components

a. Vault Layer:
- Five main vaults (scWETH, scUSDC, scUSDCv2, scWETHv2, scLUSD)
- SQuartz staking contract separately
- Each vault should be represented as a distinct component

b. Protocol Integration Layer:
- External DeFi protocols (Lido, Curve, Balancer, Aave V3, Uniswap V3, Liquity)
- Price feeds (Chainlink)
- 0x Exchange router

c. Adapter Layer (for v2 vaults):
- Adapter architecture for scUSDCv2 and scWETHv2
- Adapter connections to multiple lending protocols

d. Keeper System:
- Keeper bot infrastructure
- Rebalancing flows

##### Component Relationships

a. User Interaction Flow:
- Entry points for user deposits (WETH, USDC, LUSD, Quartz)
- Token flow for minting vault shares
- Redemption paths

b. Strategy Flows:
- Leveraged positions
- Rebalancing paths
- Profit reinvestment routes

##### Specific Implementation Details

- Rectangles: Main vault contracts
- Hexagons: External protocols
- Diamonds: Price oracles
- Rounded rectangles: Adapters
- Circles: Keeper systems

- Blue: Core vault contracts
- Green: External protocols
- Yellow: Oracle systems
- Purple: Adapter layer
- Red: Critical paths/risk areas

**User Interaction Layer**
**↓**
**Vault Layer (ERC4626 Vaults)**
**↓**
**Adapter Layer (for v2 vaults)**
**↓**
**Protocol Integration Layer**
**↓**
**External DeFi Protocols & Oracles**

##### Important Elements to Highlight

- Security boundaries (based on audit reports in /audits)
- Multi-sig controlled components
- Keeper bot interaction points
- Risk exposure paths
- ERC4626 compliance interfaces

##### Technical Details

- Interface connections (from /src/interfaces)
- Price feed integrations
- Testing boundaries (based on /test structure)
- Contract interactions

##### Documentation References

References to:
- Audit reports location
- Certora formal verification specs
- Testing coverage metrics
- External protocol documentation

Remember to include version control information and deployment addresses in supplementary documentation, as indicated by the presence of deployment scripts in the /script directory.

This architecture should emphasize the modular nature of the system, particularly the adapter pattern used in v2 vaults, while clearly showing the risk exposure paths through various external protocols.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef vault fill:#3498db,stroke:#2980b9,color:white
    classDef protocol fill:#2ecc71,stroke:#27ae60,color:white
    classDef oracle fill:#f1c40f,stroke:#f39c12,color:black
    classDef adapter fill:#9b59b6,stroke:#8e44ad,color:white
    classDef keeper fill:#e74c3c,stroke:#c0392b,color:white
    classDef testing fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef security fill:#e67e22,stroke:#d35400,color:white
    classDef price fill:#1abc9c,stroke:#16a085,color:white

    %% User Layer
    User((User))

    %% Vault Layer
    subgraph VaultLayer[Vault Layer]
        scWETH[scWETH Vault]:::vault
        scUSDC[scUSDC Vault]:::vault
        scUSDCv2[scUSDCv2 Vault]:::vault
        scWETHv2[scWETHv2 Vault]:::vault
        scLUSD[scLUSD Vault]:::vault
        sQuartz[sQuartz Staking]:::vault
    end
    click sQuartz "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/staking"
    click scLUSD "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/liquity"

    %% Adapter Layer
    subgraph AdapterLayer[Adapter Layer]
        USDCAdapters[USDC V2 Adapters]:::adapter
        WETHAdapters[WETH V2 Adapters]:::adapter
        USDTAdapters[USDT Adapters]:::adapter
        USDSAdapters[USDS Adapters]:::adapter
        SDAIAdapters[SDAI Adapters]:::adapter
    end
    click USDCAdapters "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/scUsdcV2-adapters"
    click WETHAdapters "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/scWethV2-adapters"
    click USDTAdapters "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/scUsdt-adapters"
    click USDSAdapters "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/scUsds-adapters"
    click SDAIAdapters "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/scSDai-adapters"

    %% Protocol Integration Layer
    subgraph ProtocolLayer[Protocol Integration]
        Aave[Aave V3]:::protocol
        Balancer[Balancer]:::protocol
        Curve[Curve]:::protocol
        Lido[Lido]:::protocol
        Uniswap[Uniswap V3]:::protocol
        Liquity[Liquity]:::protocol
        Morpho[Morpho]:::protocol
    end
    click Aave "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/aave-v3"
    click Balancer "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/balancer"
    click Curve "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/curve"
    click Lido "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/lido"
    click Uniswap "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/uniswap"
    click Liquity "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/liquity"
    click Morpho "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/morpho"

    %% Price & Oracle Systems
    subgraph PriceSystem[Price Systems]
        Chainlink[Chainlink Feeds]:::oracle
        PriceConverter[Price Converter]:::price
        Swapper[Swapper]:::price
    end
    click Chainlink "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/interfaces/chainlink"
    click PriceConverter "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/priceConverter"
    click Swapper "https://github.com/lindy-labs/sandclock-contracts/tree/main/src/steth/swapper"

    %% Keeper System
    subgraph KeeperSystem[Keeper System]
        KeeperBot[Keeper Bot]:::keeper
        KeeperActions[Keeper Actions]:::keeper
    end
    click KeeperActions "https://github.com/lindy-labs/sandclock-contracts/tree/main/script/v2/keeper-actions"

    %% Testing & Security
    subgraph TestingSecurity[Testing & Security]
        Mocks[Protocol Mocks]:::testing
        AdapterTests[Adapter Tests]:::testing
        FormalVerification[Formal Verification]:::security
        Audits[Audit Reports]:::security
    end
    click Mocks "https://github.com/lindy-labs/sandclock-contracts/tree/main/test/mocks"
    click FormalVerification "https://github.com/lindy-labs/sandclock-contracts/tree/main/certora/specs"
    click Audits "https://github.com/lindy-labs/sandclock-contracts/tree/main/audits/"

    %% Relationships
    User --> VaultLayer
    VaultLayer --> AdapterLayer
    AdapterLayer --> ProtocolLayer
    ProtocolLayer --> PriceSystem
    KeeperSystem --> AdapterLayer
    KeeperSystem --> VaultLayer
    PriceSystem --> ProtocolLayer

    %% Legend
    subgraph Legend
        L1[Vault Contracts]:::vault
        L2[External Protocols]:::protocol
        L3[Oracle Systems]:::oracle
        L4[Adapters]:::adapter
        L5[Keeper Components]:::keeper
        L6[Testing Components]:::testing
        L7[Security Components]:::security
        L8[Price Systems]:::price
    end
```
