# liquity/bold architecture

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

## Overview

##### Main Components (Nodes
- Smart Contracts Layer:
– Top-level contracts: CollateralRegistry and BoldToken.
– Branch-level contracts (deployed per collateral branch): BorrowerOperations, TroveManager, TroveNFT, StabilityPool, ActivePool, DefaultPool, CollSurplusPool, GasPool, SortedTroves, and LiquityBase.
– Peripheral helper contracts: HintHelpers and MultiTroveGetter.
– PriceFeed contracts: MainnetPriceFeedBase, CompositePriceFeed, WETHPriceFeed, WSTETHPriceFeed, and RETHPriceFeed.
– Additional contracts: Foundry and Hardhat configuration files, deployment scripts, utility scripts for extracting ABI, deployment manifests, and fuzz tests.
- Frontend Layer:
– dApp (Next.js based) interacting with the protocol via web3,
– UI components and the separate UI kit libraries.
- External Services:
– External oracles (e.g. Chainlink price feeds for ETH/USD, stETH/USD, RETH-ETH, etc.),
– Off-chain systems (e.g., IPFS for image serving via tokenURI functions in TroveNFT).
- Deployment & CI/CD Tools:
– GitHub workflows, Vercel configuration, and package managers (pnpm).

##### Relationships and Data Flows
- The frontend directly calls functions on the borrowed “user-facing” contracts (e.g. BorrowerOperations) and performs read-only queries via HintHelpers to assist with gas-efficient transaction hints.
- The CollateralRegistry routes redemptions across collateral branches and (as a hub) maps ERC20 tokens to specific branch-level TroveManagers.
- Each branch-level set of contracts (BorrowerOperations, TroveManager, StabilityPool, etc.) interact internally to manage Trove opening, adjustments, liquidations, debt accrual, redemptions, and fee calculations.
- Deployment scripts, CI/CD workflows, and configuration files (e.g. Hardhat, Foundry, pnpm workspace) support development and deployment but can be drawn as “Infrastructure” components that form the foundation of the development cycle.

##### Architectural Patterns & Design Principles
- Modular design: The protocol is split into common core logic (LiquityBase) and collateral branch-specific contracts; each branch (for WETH, WSTETH, RETH) is self-contained though coordinated via CollateralRegistry.
- Gas-efficiency via off-chain hint calculations for inserting troves into a sorted doubly linked list.
- Use of helper libraries (e.g. SortedTroves and HintHelpers) to reduce complexity and gas cost.
- Robust interactions with external oracles for price feeds, which in themselves have fallback and shutdown mechanisms.

##### Relevant Technologies and Frameworks
- Ethereum and Solidity for smart contracts.
- Hardhat and Foundry for testing and deployment.
- Next.js, React, TypeScript (or JavaScript) for the frontend dApp.
- PNPM and GitHub workflows for project management, CI/CD, and deployment configuration.
- Chainlink or similar for the external price and oracle services.

##### Elements
- Labels for every major component:
– From external oracles (Chainlink Price Feeds) to PriceFeed Contracts.
– From the frontend to smart contracts (vía web3 calls).
- Optional grouping:
– Group all branch-level contracts together indicating that there is one set per each collateral type.
– Differentiate between “Core” protocols and “Helper” modules.
- Annotating important data flow paths (for token minting/burning, collateral deposits/withdrawals, interest accrual updates, and liquidation/redemption flows).

– The smart contracts layered into top-level (CollateralRegistry, BoldToken) and branch-specific contracts (BorrowerOperations, TroveManager, etc.),
– The flow of assets (collateral deposits, BOLD stablecoin minting/burning, redemptions, fee and interest processing),
– The interactions with external oracles to price collateral, and

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "On-chain Layer: Smart Contracts"
        direction TB
        subgraph "Core Contracts"
            CR["CollateralRegistry"]:::contract
            BT["BoldToken"]:::contract
            LB["LiquityBase"]:::contract
        end

        subgraph "Branch-Level Contracts"
            direction TB
            BO["BorrowerOperations"]:::contract
            TM["TroveManager"]:::contract
            TN["TroveNFT"]:::contract
            SP["StabilityPool"]:::contract
            AP["ActivePool"]:::contract
            DP["DefaultPool"]:::contract
            CSP["CollSurplusPool"]:::contract
            GP["GasPool"]:::contract
            ST["SortedTroves"]:::contract
        end

        subgraph "Peripheral Helper Contracts"
            direction TB
            HH["HintHelpers"]:::contract
            MT["MultiTroveGetter"]:::contract
            HHA["HintHelpers ABI"]:::contractabi
            MTA["MultiTroveGetter ABI"]:::contractabi
        end

        subgraph "PriceFeed Contracts"
            direction TB
            MPF["MainnetPriceFeedBase"]:::contract
            CPF["CompositePriceFeed"]:::contract
            WPF["WETHPriceFeed"]:::contract
            WSP["WSTETHPriceFeed"]:::contract
            RPF["RETHPriceFeed"]:::contract
        end

        subgraph "Deployment & Infrastructure"
            direction TB
            HHconf["Hardhat Config"]:::infra
            FDconf["Foundry Config"]:::infra
            DS["Deployment Scripts & Utilities"]:::infra
        end
    end

    subgraph "Off-chain Layer"
        direction TB
        FE["Frontend dApp"]:::frontend
        UI["UI Kit Libraries"]:::frontend
        SG["Subgraph Indexer"]:::subgraphIndex
    end

    subgraph "External Services"
        direction TB
        ORA["Chainlink Oracles"]:::external
        IPFS["IPFS Storage"]:::external
    end

    %% Data Flow Connections
    FE -->|"calls"| BO
    FE -->|"queries"| HH
    CR -->|"routes redemption"| TM
    BO -->|"invokes"| TM
    TM -->|"interacts"| SP
    SP -->|"updates sorted order"| ST
    IPFS -->|"serves image data"| TN
    SG -->|"data feed"| FE

    %% External Oracle Feeds to PriceFeeds
    ORA -->|"feeds price"| MPF
    ORA -->|"feeds price"| CPF
    ORA -->|"feeds price"| WPF
    ORA -->|"feeds price"| WSP
    ORA -->|"feeds price"| RPF

    %% PriceFeeds provide pricing to branch logic
    MPF -->|"price"| TM
    CPF -->|"price"| TM
    WPF -->|"price"| TM
    WSP -->|"price"| TM
    RPF -->|"price"| TM

    %% Smart Contracts emit events to Subgraph Indexer
    CR ---|"emits events"| SG
    BO ---|"emits events"| SG
    TM ---|"emits events"| SG
    SP ---|"emits events"| SG

    %% Click Events for Component Mapping
    click CR "https://github.com/liquity/bold/tree/main/contracts/src"
    click BT "https://github.com/liquity/bold/tree/main/contracts/src"
    click LB "https://github.com/liquity/bold/tree/main/contracts/src"

    click BO "https://github.com/liquity/bold/tree/main/contracts/src"
    click TM "https://github.com/liquity/bold/tree/main/contracts/src"
    click TN "https://github.com/liquity/bold/tree/main/contracts/src"
    click SP "https://github.com/liquity/bold/tree/main/contracts/src"
    click AP "https://github.com/liquity/bold/tree/main/contracts/src"
    click DP "https://github.com/liquity/bold/tree/main/contracts/src"
    click CSP "https://github.com/liquity/bold/tree/main/contracts/src"
    click GP "https://github.com/liquity/bold/tree/main/contracts/src"
    click ST "https://github.com/liquity/bold/tree/main/contracts/src"

    click HH "https://github.com/liquity/bold/tree/main/contracts/src"
    click HHA "https://github.com/liquity/bold/blob/main/frontend/app/src/abi/HintHelpers.ts"
    click MT "https://github.com/liquity/bold/tree/main/contracts/src"
    click MTA "https://github.com/liquity/bold/blob/main/frontend/app/src/abi/MultiTroveGetter.ts"

    click MPF "https://github.com/liquity/bold/tree/main/contracts/src/PriceFeeds"
    click CPF "https://github.com/liquity/bold/tree/main/contracts/src/PriceFeeds"
    click WPF "https://github.com/liquity/bold/tree/main/contracts/src/PriceFeeds"
    click WSP "https://github.com/liquity/bold/tree/main/contracts/src/PriceFeeds"
    click RPF "https://github.com/liquity/bold/tree/main/contracts/src/PriceFeeds"

    click HHconf "https://github.com/liquity/bold/blob/main/contracts/hardhat.config.js"
    click FDconf "https://github.com/liquity/bold/blob/main/contracts/foundry.toml"
    click DS "https://github.com/liquity/bold/tree/main/contracts/script"

    click FE "https://github.com/liquity/bold/tree/main/frontend/app/src"
    click UI "https://github.com/liquity/bold/tree/main/frontend/uikit/src"
    click UI "https://github.com/liquity/bold/tree/main/frontend/uikit-gallery/src"

    click SG "https://github.com/liquity/bold/tree/main/subgraph"

    %% Style Definitions
    classDef contract fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef subgraphIndex fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef contractabi fill:#87CEFA,stroke:#000,stroke-width:2px;
```
