# sky-ecosystem/dss architecture

> Architecture diagram of the GitHub repository sky-ecosystem/dss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sky-ecosystem/dss
- Repository: https://github.com/sky-ecosystem/dss

## Overview

##### Project Type and Purpose
- This is a blockchain‐native, on‐chain financial system: the core smart contracts for MakerDAO’s Multi Collateral Dai (MCD).

##### Main Components
a. External Assets
- Native Ether or ERC-20 tokens (e.g., WETH, USDC, custom collateral).
b. Adapters (“join” contracts)
- One adapter per collateral type.
- They standardize token decimals/semantics and funnel collateral into the core via a single function (`slip`).
c. Core System Contracts (in `src/`)
- Vat: the heart of the system, holds collateral balances and Dai-denominated debt balances.
- Jug / Spotter: risk parameters (stability fees, liquidation ratios, price feeds).
- Dog: liquidation trigger logic.
- Flapper / Flopper: auctions for surplus Dai (flap) and system debt (flop).
- Vow: orchestrates auctions and system surplus/debt management.
d. Dai Token Implementation
- DSToken wrapper around core’s `vat.dai`. Users `exit` to mint ERC-20 Dai.
e. MKR Token (external)
- Used in system debt auctions (to cover bad debt) and governance.
f. Price Feeds (oracles)
- Push price data into the Spotter contract.
g. Governance Layer (external contracts/users)
- Multi-owner authority that adjusts risk parameters and upgrades modules.

##### Relationships and Data Flows
- Users send collateral to an Adapter → Adapter calls `Vat.slip()` → Vat updates collateral balance.
- To get ERC-20 Dai, users call `exit()`, which burns core Dai and mints ERC-20 DSToken.
- Price Feed updates trigger Spotter to mark undercollateralized CDPs → Dog starts a liquidation auction.
- Flopper (debt auction) and Flapper (surplus auction) are invoked by Vow based on system surplus/debt.
- MKR holders bid MKR in auctions to cover system debt or claim surplus.

##### Architectural Patterns & Principles
- Modular contracts: each responsibility in its own contract (SRP).
- Adapter pattern: abstracts arbitrary collateral via a uniform interface.
- Auction pattern: fixed‐lot auctions for collateral and MKR.
- No external calls & no precision loss in core (formal verification–friendly).
- Multi‐owner/simple authentication: contracts trust a small set of actors for configuration.

##### Technologies & Libraries
- Solidity contracts under `src/`
- ds-math, ds-token, ds-value libs under `lib/`
- Nix (`shell.nix`) for reproducible dev environment
- GitHub Actions for CI (`.github/workflows/tests.yaml`)
- Formal verification tools (via zero‐division and external‐call constraints)

##### Putting It All Together
- At the top, list off‐chain actors: Users, Price Feeds, Governance UI.
- Modularity by grouping adapters separately and linking them back to core via the single “slip” interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain actors
    Users["Users"]:::external
    PriceFeeds["Price Feeds"]:::external
    GovernanceUI["Governance UI"]:::external

    %% Adapters layer
    subgraph "Adapters" 
        direction TB
        JoinETH["JoinETH Adapter"]:::adapter
        JoinUSDC["JoinUSDC Adapter"]:::adapter
    end

    %% Core system
    subgraph "Core System"
        direction TB
        Vat["Vat (state)"]:::core
        Jug["Jug (stability fees)"]:::core
        Spotter["Spotter (price feed)"]:::core
        Dog["Dog (liquidation)"]:::core
        Vow["Vow (auctions orchestrator)"]:::core
        Flapper["Flapper (surplus auction)"]:::auction
        Flopper["Flopper (debt auction)"]:::auction
    end

    %% Tokens
    DAIToken["ERC-20 Dai"]:::token
    MKRToken["MKR Token"]:::token

    %% Flows
    Users -->|"lock collateral"| JoinETH
    Users -->|"lock collateral"| JoinUSDC
    JoinETH -->|"slip()"| Vat
    JoinUSDC -->|"slip()"| Vat

    Users -->|"draw Dai"| Vat
    Vat -->|"exit() mints"| DAIToken

    PriceFeeds -.->|"push price"| Spotter
    Spotter -->|"mark CDP"| Dog
    Dog -->|"start liquidation auction"| Flopper

    Vow -->|"surplus auction"| Flapper
    Vow -->|"debt auction"| Flopper

    MKRToken -->|"bid MKR"| Flapper
    MKRToken -->|"bid MKR"| Flopper

    GovernanceUI -.->|"update params"| Jug
    GovernanceUI -.->|"update params"| Spotter
    GovernanceUI -.->|"configure auth"| Dog
    GovernanceUI -.->|"configure auth"| Vow

    %% Click events
    click JoinETH "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click JoinUSDC "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Vat "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Jug "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Spotter "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Dog "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Vow "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Flapper "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click Flopper "https://github.com/sky-ecosystem/dss/tree/master/src/"
    click DAIToken "https://github.com/sky-ecosystem/dss/tree/master/lib/ds-token/"
    click PriceFeeds "https://github.com/sky-ecosystem/dss/tree/master/lib/ds-value/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef adapter fill:#9cf,stroke:#333,stroke-width:1px
    classDef core fill:#cfc,stroke:#333,stroke-width:1px,rx:5,ry:5
    classDef token fill:#fc9,stroke:#333,stroke-width:1px,shape:cylinder
    classDef auction fill:#fcc,stroke:#333,stroke-width:1px,shape:diamond
```
