How liquity/bold works
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