Skip to content
/ cdp-liquidation-protocol Public

An Ethereum-based **CDP (collateralized lending) + liquidation system** designed as a modular, extensible DeFi protocol. The system spans on-chain risk accounting (Vault/RiskEngine), liquidation execution, and a full-featured front-end console for positions, markets, assets, and keeper operations.

cdp-liquidation-protocol.vercel.app
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

Linwentao-tech/cdp-liquidation-protocol

BranchesTags

Repository files navigation

CDP Liquidation Protocol

中文

这是一个基于以太坊的 CDP（抵押借贷）+ 清算系统，目标是实现模块化、可扩展、接近生产级的 DeFi 借贷协议。整体设计与 MakerDAO 类似：用户质押 WETH 作为抵押品，铸造稳定币 dUSD，并在风险触发时进入清算流程。

系统包含链上风险核算（Vault/RiskEngine）、清算执行（LiquidationEngine）、以及完整的前端控制台（仓位、市场、资产、清算）。

🔍 核心逻辑说明

  • 质押 WETH → 获得 dUSD 用户向 Vault 存入 WETH 抵押，通过 PositionManager合约 借出 dUSD。债务与健康系数（HF）会随抵押价值和价格波动实时变化。

  • 基于 mUSDC 的流动性池 系统提供 dUSD / mUSDC 的流动性池，用于：

    1. 给 dUSD 一个“真实的价格发现 + 退出通道”；
    2. 在清算发生时，为清算与风险计算提供可用的市场参考；
    3. 让整个 CDP 系统在经济层面可运行，而不是单纯的账本内循环。

🧩 前端技术栈

  • Next.js (App Router)
  • wagmi + viem
  • shadcn/ui
  • Tailwind CSS

🌐 前端地址

https://cdp-liquidation-protocol.vercel.app/

📍 合约地址（Sepolia）

Vault              0xee73e22AD6160C01e895C391F63EAa86e41A347F
DebtToken          0xF81ab1d0783FDbADbAa6967D76A21C57cc4f6a46
OracleAdapter      0xDC41837Ba41024468e17548eD3B97C9616bBecDf
RiskEngine         0x6995435b11Fb52D8B7d347155b889789EEE66c98
PositionManager    0x8F2cd4Bfc426FD56F5898F0a6206D0AA4a124399
LiquidationEngine  0xCBE947e1f592DD7f08d7cB2d1756b11887D4b93d
MockUSDC           0xD0A4aB298abf949207D80D9D1D64CF84963d2C0F

Factory            0x57deFcF1c0d9bFdD2677EBAd09F6B88f59f7e422
Pair               0x0A573CDc78C2D6C95d433e8d534ed0022e12f779

✨ 主要特性

  • 超额抵押 CDP 系统
    • 每个钱包一个 WETH 抵押仓位
    • 抵押铸造 / 归还 dUSD
  • 风险与健康系数模型
    • WAD 精度数学与明确的舍入规则
    • 以健康系数判断清算资格
  • 清算流程
    • 确定性的清算数学
    • Keeper 执行与预览机制
  • 模块化架构
    • 风险逻辑与账本分离
    • 预言机适配器支持过期判断
  • 前端控制台
    • 仓位管理（存入/取出/借款/还款/关闭）
    • 市场风险与预言机状态
    • 资产余额与 WETH/ETH 兑换
    • Keeper 清算控制台

🧠 核心概念

健康系数（HF）

协议使用 健康系数 判断是否可被清算： HF = (抵押价值 × 清算阈值) / 债务

  • 全部采用 WAD（1e18） 精度
  • HF ≥ 1.0 → 安全
  • HF < 1.0 → 可清算
  • 舍入规则：
    • HF 与债务上限 → 向下取整
    • 所需抵押 → 向上取整（更安全）

📂 目录结构

src/
├─ core/            # 账本与仓位
│  ├─ Vault.sol
│  ├─ PositionManager.sol
│  └─ DebtToken.sol
│
├─ risk/            # 风险规则与预言机
│  ├─ RiskEngine.sol
│  └─ OracleAdapter.sol
│
├─ liquidation/     # 清算逻辑
│  ├─ LiquidationEngine.sol
│  └─ LiquidationMath.sol
│
├─ libraries/       # 数学与工具库
│  └─ HealthFactor.sol
│
└─ mocks/           # 测试使用

✅ 合约测试覆盖率（Forge）

╭---------------------------------------+------------------+------------------+-----------------+------------------╮
| File                                  | % Lines          | % Statements     | % Branches      | % Funcs          |
+==================================================================================================================+
| script/DeployDebtToken.s.sol          | 100.00% (5/5)    | 100.00% (5/5)    | 100.00% (0/0)   | 100.00% (1/1)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeployLocal.s.sol              | 0.00% (0/26)     | 0.00% (0/32)     | 100.00% (0/0)   | 0.00% (0/1)      |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeployMockDebtToken.s.sol      | 100.00% (5/5)    | 100.00% (5/5)    | 100.00% (0/0)   | 100.00% (1/1)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeployMockOracleAdapter.s.sol  | 100.00% (5/5)    | 100.00% (5/5)    | 100.00% (0/0)   | 100.00% (1/1)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeployMockRiskEngine.s.sol     | 100.00% (5/5)    | 100.00% (5/5)    | 100.00% (0/0)   | 100.00% (1/1)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeployMockVault.s.sol          | 100.00% (5/5)    | 100.00% (5/5)    | 100.00% (0/0)   | 100.00% (1/1)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeployRiskEngine.s.sol         | 100.00% (5/5)    | 100.00% (5/5)    | 100.00% (0/0)   | 100.00% (1/1)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/DeploySepolia.s.sol            | 0.00% (0/28)     | 0.00% (0/35)     | 100.00% (0/0)   | 0.00% (0/1)      |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| script/LocalFlow.s.sol                | 0.00% (0/47)     | 0.00% (0/44)     | 0.00% (0/4)     | 0.00% (0/4)      |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/core/DebtToken.sol                | 100.00% (32/32)  | 96.97% (32/33)   | 90.00% (9/10)   | 100.00% (9/9)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/core/PositionManager.sol          | 90.91% (40/44)   | 89.47% (51/57)   | 85.71% (12/14)  | 87.50% (7/8)     |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/core/Vault.sol                    | 96.51% (83/86)   | 89.80% (88/98)   | 69.57% (16/23)  | 94.44% (17/18)   |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/libraries/HealthFactor.sol        | 100.00% (41/41)  | 100.00% (56/56)  | 100.00% (12/12) | 100.00% (10/10)  |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/liquidation/LiquidationEngine.sol | 100.00% (29/29)  | 90.20% (46/51)   | 70.00% (7/10)   | 100.00% (2/2)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/liquidation/LiquidationMath.sol   | 100.00% (25/25)  | 96.97% (32/33)   | 85.71% (6/7)    | 100.00% (6/6)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/MockAggregatorV3.sol        | 77.78% (7/9)     | 83.33% (5/6)     | 100.00% (0/0)   | 66.67% (2/3)     |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/MockDebtToken.sol           | 100.00% (7/7)    | 100.00% (4/4)    | 100.00% (0/0)   | 100.00% (3/3)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/MockOracleAdapter.sol       | 100.00% (7/7)    | 100.00% (4/4)    | 100.00% (0/0)   | 100.00% (3/3)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/MockRiskEngine.sol          | 90.00% (18/20)   | 90.00% (9/10)    | 100.00% (0/0)   | 90.00% (9/10)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/MockUSDC.sol                | 0.00% (0/4)      | 0.00% (0/2)      | 100.00% (0/0)   | 0.00% (0/2)      |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/MockVault.sol               | 100.00% (48/48)  | 80.00% (36/45)   | 0.00% (0/9)     | 100.00% (14/14)  |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/mocks/WETH.sol                    | 0.00% (0/10)     | 0.00% (0/8)      | 0.00% (0/2)     | 0.00% (0/3)      |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/risk/OracleAdapter.sol            | 100.00% (16/16)  | 95.83% (23/24)   | 75.00% (3/4)    | 100.00% (3/3)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| src/risk/RiskEngine.sol               | 95.35% (41/43)   | 98.51% (66/67)   | 100.00% (9/9)   | 90.00% (9/10)    |
|---------------------------------------+------------------+------------------+-----------------+------------------|
| Total                                 | 76.81% (424/552) | 75.43% (482/639) | 71.15% (74/104) | 86.21% (100/116) |
+---------------------------------------------------------------------------------------------------------------+

备注：

  • 覆盖率统计包含 fuzz tests（核心数学与风险逻辑）
  • script/ 覆盖率反映 Foundry 对脚本的覆盖统计

English

An Ethereum-based CDP (collateralized lending) + liquidation system designed as a modular, extensible DeFi protocol. The system spans on-chain risk accounting (Vault/RiskEngine), liquidation execution, and a full-featured front-end console for positions, markets, assets, and keeper operations.

✨ Key Features

  • Over‑collateralized CDP system
    • Single WETH‑backed position per wallet
    • Mint / repay dUSD against collateral
  • Risk & Health Factor model
    • WAD‑based math with explicit rounding rules
    • Liquidation eligibility via HF thresholds
  • Liquidation pipeline
    • Deterministic liquidation math
    • Keeper execution flow with preview + safety checks
  • Modular architecture
    • Risk rules isolated from accounting
    • Oracle adapter with staleness checks
  • Front-end console
    • Position management (deposit/withdraw/borrow/repay/close)
    • Market risk + oracle status
    • Asset balances and WETH/ETH swap
    • Keeper liquidation console

🧠 Core Concepts

Health Factor (HF)

The protocol uses a Health Factor to determine liquidation eligibility: HF = (collateralValue × liquidationThreshold) / debt

  • All values are WAD-based (1e18)
  • HF ≥ 1.0 → healthy
  • HF < 1.0 → liquidatable
  • Explicit rounding rules:
    • HF & debt limits → round down
    • Required collateral → round up (safety)

🌐 Frontend

Live app:

https://cdp-liquidation-protocol.vercel.app/

The UI is built in Next.js with a shadcn-based component system and includes:

  • Home: protocol + personal position snapshot
  • Position: full CDP management with previews
  • Assets: token balances + WETH/ETH swap
  • Market: oracle freshness + risk parameters
  • Liquidate: keeper console for liquidation execution
  • Contracts: deployed addresses

📍 Contract Addresses (Sepolia)

Vault              0xee73e22AD6160C01e895C391F63EAa86e41A347F
DebtToken          0xF81ab1d0783FDbADbAa6967D76A21C57cc4f6a46
OracleAdapter      0xDC41837Ba41024468e17548eD3B97C9616bBecDf
RiskEngine         0x6995435b11Fb52D8B7d347155b889789EEE66c98
PositionManager    0x8F2cd4Bfc426FD56F5898F0a6206D0AA4a124399
LiquidationEngine  0xCBE947e1f592DD7f08d7cB2d1756b11887D4b93d
MockUSDC           0xD0A4aB298abf949207D80D9D1D64CF84963d2C0F

Factory            0x57deFcF1c0d9bFdD2677EBAd09F6B88f59f7e422
Pair               0x0A573CDc78C2D6C95d433e8d534ed0022e12f779

📂 Project Structure

src/
├─ core/            # Stable accounting layer
│  ├─ Vault.sol
│  ├─ PositionManager.sol
│  └─ DebtToken.sol
│
├─ risk/            # Risk rules & calculations
│  ├─ RiskEngine.sol
│  └─ OracleAdapter.sol
│
├─ liquidation/     # Liquidation reliability core
│  ├─ LiquidationEngine.sol
│  └─ LiquidationMath.sol
│
├─ libraries/       # Math & utilities
│  └─ HealthFactor.sol
│
└─ mocks/           # Test mocks

About

An Ethereum-based **CDP (collateralized lending) + liquidation system** designed as a modular, extensible DeFi protocol. The system spans on-chain risk accounting (Vault/RiskEngine), liquidation execution, and a full-featured front-end console for positions, markets, assets, and keeper operations.

cdp-liquidation-protocol.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages