# curvefi/curve-stablecoin architecture

> Architecture diagram of the GitHub repository curvefi/curve-stablecoin, 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/curvefi/curve-stablecoin
- Repository: https://github.com/curvefi/curve-stablecoin

## Overview

##### Project’s Nature and Purpose
- The README clearly states “Curve Stablecoin contracts,” and the file structure reveals a modular DeFi system focused on stablecoins.
- The project contains smart contracts for automated market making (AMM), lending, flashloans, price oracles, monetary policy, and stabilizer functions. It includes deployment scripts (using both ape and brownie frameworks), testing folders, and various factory patterns.

##### Main Components
A. Smart Contract Modules (On-chain components):
- Stablecoin Contract: Central token logic and governance.
- AMM & Stableswap Contracts: Including AMM.vy and Stableswap.vy that manage liquidity pools and swaps.
- Controller & ControllerFactory: Likely handling governance or administrative control of protocols.
- Lending Modules: Contracts found in the lending folder such as Vault, LiquidityGauge, and various lending factories (OneWayLendingFactory, TwoWayLendingFactory) that manage lending, borrowing, and liquidity.
- Price Oracles: Numerous contracts in the “price_oracles” directory (e.g., ChainlinkWrapper, various CryptoFromPool variations) that fetch and process external price data.
- Monetary Policies & Stabilizers: Files in “mpolicies” and “stabilizer” (like multiple AggMonetaryPolicy variants and PegKeeper) that implement strategies to maintain the stablecoin peg.
- Flash Loan & Zaps: Contracts for flashloan functionality and simplified multi-operation transactions as seen in the “flashloan” and “zaps” directories.
- Factories: The “factory” subdirectory and similar patterns (e.g., in lending) that indicate use of the factory design pattern for deploying further contract instances.

B. Deployment and Configuration Components:
- Deployment Scripts: Both “scripts” and “brownie-deploy-emas” scripts show how deployments are automated across different networks.
- Environment & Config Files: Deployment environment in “deploy_env”, general configuration (e.g., .env-example, ape-config.yaml, brownie-config.yaml) which determine external dependencies (like web3 providers).
- Testing Suite: Extensive tests spread across “tests”, “tests_brownie”, “tests_forked”, etc., which validate the integrity of contract interactions and protocol flows.

C. Supporting Artifacts and Documentation:
- Documentation: “doc” and “docs” directories provide whitepapers, lending documentation, and architectural details.
- Models: Scripts in the “model” directory suggest off-chain computations or simulation models that might inform on-chain strategies.

##### Relationships, Interactions, and Data Flow
- How external data (price feeds from Chainlink or other oracles) flows into the Price Oracle contracts and then propagates to both the AMM and monetary policy/stabilizer components.
- How the AMM/stableswap contracts interact with the Stablecoin contract (for minting/burning) and the Controller contracts for governance.
- Deployment layer (scripts, configuration files) as the bridge between off-chain management (via ape, brownie, poetry, etc.) and on-chain smart contracts.

##### Important Architectural Patterns and Design Principles
- Modular design: Each contract or group of contracts (AMM, lending, oracles, policies) is a dedicated module which could be updated or replaced independently.
- Factory Pattern: Multiple “factory” directories show the use of factories to standardize contract creation.
- Separation of Concerns: There is a clear delineation between pricing, liquidity, policy enforcement, and administrative functions.
- Automated Testing & Deployment: A robust test suite is evident, underlining the emphasis on reliability.
- Off-chain & On-chain Separation: Deployment scripts and configuration files clearly separate on-chain business logic from off-chain orchestration and environment management.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Deployment & Configuration Layer
    subgraph "Deployment & Configuration"
        ADS["Ape Deploy Script"]:::deployment
        BDS["Brownie Deploy Script"]:::deployment
        EC["Environment & Config"]:::deployment
        TS["Testing Suite"]:::deployment
        DOC["Documentation"]:::deployment
        MOD["Off-chain Models"]:::deployment
    end

    %% External Dependencies
    EPF["External Price Feed"]:::external

    %% On-Chain Smart Contracts Layer
    subgraph "On-Chain Smart Contracts"
        SCS["Stablecoin Contract"]:::onchain
        CTL["Controller"]:::onchain
        CTLF["ControllerFactory"]:::onchain
        AMM["AMM Contract"]:::onchain
        SS["Stableswap Contract"]:::onchain
        SSF["StableswapFactory"]:::onchain
        VAULT["Vault"]:::onchain
        LG["LiquidityGauge"]:::onchain
        OWLF["OneWayLendingFactory"]:::onchain
        TWLF["TwoWayLendingFactory"]:::onchain
        CW["Chainlink Wrapper"]:::onchain
        AMP["AggMonetaryPolicy"]:::onchain
        PK["PegKeeper"]:::onchain
        FL["FlashLender"]:::onchain
        HCZ["HealthCalculatorZap"]:::onchain
    end

    %% Deployment flows to on-chain contracts
    EC -->|deploys| SCS
    ADS -->|deploys| SCS
    BDS -->|deploys| SCS
    TS -->|tests| SCS

    %% External price feed integration
    EPF -->|feeds| CW

    %% On-chain interactions
    SCS -->|calls| AMM
    SCS -->|calls| SS
    CTL -->|monitors| SCS
    CTLF -->|creates| CTL
    SSF -->|creates| SS

    VAULT -->|manages| OWLF
    VAULT -->|manages| TWLF
    VAULT -->|monitors| LG

    CW -->|feeds| AMP
    AMP -->|adjusts| SCS
    FL -->|initiates| HCZ
    HCZ -->|calls| SCS

    %% Styles
    classDef deployment fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef onchain fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef external fill:#FFDAB9,stroke:#000,stroke-width:2px;

click ADS "https://github.com/curvefi/curve-stablecoin/blob/master/scripts/ape-deploy.py"
click BDS "https://github.com/curvefi/curve-stablecoin/blob/master/brownie-deploy-emas/scripts/deploy_emas.py"
click EC "https://github.com/curvefi/curve-stablecoin/blob/master/.env-example"
click TS "https://github.com/curvefi/curve-stablecoin/tree/master/tests/"
click DOC "https://github.com/curvefi/curve-stablecoin/tree/master/doc/"
click MOD "https://github.com/curvefi/curve-stablecoin/tree/master/model/"

click SCS "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/Stablecoin.vy"
click AMM "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/AMM.vy"
click SS "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/Stableswap.vy"
click CTL "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/Controller.vy"
click CTLF "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/ControllerFactory.vy"
click VAULT "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/lending/Vault.vy"
click LG "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/lending/LiquidityGauge.vy"
click OWLF "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/lending/OneWayLendingFactory.vy"
click TWLF "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/lending/TwoWayLendingFactory.vy"
click CW "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/price_oracles/ChainlinkWrapper.vy"
click AMP "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/mpolicies/AggMonetaryPolicy.vy"
click PK "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/stabilizer/PegKeeper.vy"
click FL "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/flashloan/FlashLender.vy"
click HCZ "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/zaps/HealthCalculatorZap.vy"
click SSF "https://github.com/curvefi/curve-stablecoin/blob/master/contracts/factory/StableswapFactory.vy"
```
