assetxContracts/doc/YTLending-流程说明.md

# YT Lending 借贷池系统流程说明

## 系统概述

YT Lending 是基于 Compound V3 架构的简化借贷池系统，采用 OpenZeppelin UUPS 升级模式和 Ownable 权限管理。

### 核心特性

- ✅ **UUPS 可升级**：使用 OpenZeppelin 的 UUPS 代理模式
- ✅ **简化权限**：使用 Owner 权限管理，替代复杂的 Governor 治理
- ✅ **单一基础资产**：支持一种基础资产（如 USDC）的借贷
- ✅ **多种抵押品**：支持多种抵押资产（如 ETH、WBTC）
- ✅ **动态利率**：双拐点利率模型
- ✅ **清算机制**：支持不良贷款清算和抵押品拍卖

---

## 合约架构

```
├── Lending.sol                    # 核心借贷合约（UUPS）
├── LendingFactory.sol             # 工厂合约
├── Configurator.sol               # 配置管理合约（UUPS）
├── LendingConfiguration.sol       # 配置结构体
├── LendingStorage.sol             # 存储定义
├── LendingMath.sol                # 数学计算库
├── ConfiguratorStorage.sol        # 配置器存储
└── interfaces/
    ├── ILending.sol               # 借贷接口
    └── IPriceFeed.sol             # 价格预言机接口
```

---

## 部署流程

### 步骤 1: 部署基础合约

运行部署脚本：
```bash
npx hardhat run scripts/deploy/07-deployLending.ts --network <network>
```

部署内容：
1. **LendingFactory** - 工厂合约
2. **Configurator Implementation** - 配置管理实现合约
3. **Configurator Proxy** - 配置管理代理合约
4. **Lending Implementation** - 借贷池实现合约

### 步骤 2: 配置市场参数

运行配置脚本：
```bash
npx hardhat run scripts/deploy/08-configureLending.ts --network <network>
```

配置内容：
1. 设置工厂合约地址
2. 配置市场参数（利率模型、清算参数等）
3. 添加抵押资产配置
4. 部署 Lending Proxy 代理合约

---

## 配置参数说明

### 利率模型参数

| 参数 | 说明 | 示例值 |
|------|------|--------|
| `supplyKink` | 供应利率拐点（利用率） | 80% |
| `supplyPerYearInterestRateSlopeLow` | 供应拐点前斜率 | 3% APY |
| `supplyPerYearInterestRateSlopeHigh` | 供应拐点后斜率 | 40% APY |
| `borrowKink` | 借款利率拐点（利用率） | 80% |
| `borrowPerYearInterestRateSlopeLow` | 借款拐点前斜率 | 5% APY |
| `borrowPerYearInterestRateSlopeHigh` | 借款拐点后斜率 | 150% APY |

### 抵押资产参数

| 参数 | 说明 | 示例值 |
|------|------|--------|
| `borrowCollateralFactor` | 借款抵押率（LTV） | 80% |
| `liquidateCollateralFactor` | 清算抵押率 | 85% |
| `liquidationFactor` | 清算激励 | 5% |
| `supplyCap` | 供应上限 | 100,000 ETH |

---

## 核心功能流程

### 1. 存款（Supply）

```solidity
lending.supply(1000 * 1e6); // 存入 1000 USDC
```

**流程**：
1. 用户授权 USDC 给 Lending 合约
2. 调用 `supply()` 存入 USDC
3. 合约记录用户正余额
4. 开始计息

### 2. 存入抵押品（Supply Collateral）

```solidity
lending.supplyCollateral(WETH, 10 * 1e18); // 存入 10 ETH
```

**流程**：
1. 用户授权抵押品（如 WETH）给 Lending 合约
2. 调用 `supplyCollateral()` 存入抵押品
3. 合约记录用户抵押品余额

### 3. 借款（Borrow）

```solidity
lending.borrow(5000 * 1e6); // 借出 5000 USDC
```

**流程**：
1. 用户已存入足够的抵押品
2. 调用 `borrow()` 借出 USDC
3. 合约检查抵押品是否充足（根据 borrowCollateralFactor）
4. 用户余额变为负数（表示借款）
5. 开始计息

**借款能力计算**：
```
借款能力 = Σ(抵押品价值 × borrowCollateralFactor)
```

### 4. 取出资产（Withdraw）

```solidity
lending.withdraw(500 * 1e6); // 取出 500 USDC
```

**流程**：
1. 调用 `withdraw()` 取出 USDC
2. 如果用户有借款，检查抵押品是否充足
3. 转账 USDC 给用户

### 5. 取出抵押品（Withdraw Collateral）

```solidity
lending.withdrawCollateral(WETH, 2 * 1e18); // 取出 2 ETH
```

**流程**：
1. 调用 `withdrawCollateral()` 取出抵押品
2. 如果用户有借款，检查剩余抵押品是否充足
3. 转账抵押品给用户

### 6. 清算（Absorb）

```solidity
lending.absorb(borrowerAddress); // 清算借款人
```

**触发条件**：
```
债务 > Σ(抵押品价值 × liquidateCollateralFactor)
```

**流程**：
1. 清算人调用 `absorb()` 清算不良贷款
2. 合约检查借款人是否可被清算
3. 将借款人的债务清零
4. 将借款人的抵押品转移到清算库存

### 7. 购买清算抵押品（Buy Collateral）

```solidity
lending.buyCollateral(WETH, 1 * 1e18, 2000 * 1e6);
// 用 2000 USDC 购买至少 1 ETH
```

**流程**：
1. 购买者调用 `buyCollateral()`
2. 按折扣价（storeFrontPriceFactor）计算可购买的抵押品数量
3. 转账 USDC 给合约
4. 转账抵押品给购买者

**折扣价格计算**：
```
折扣价 = 市场价 × storeFrontPriceFactor
可购买数量 = 支付 USDC 数量 / 折扣价
```

---

## 利率计算

### 利用率

```
利用率 = 总借款 / 总供应
```

### 双拐点利率模型

```
如果 利用率 <= Kink:
    利率 = 基础利率 + 利用率 × 低斜率

如果 利用率 > Kink:
    超额利用率 = 利用率 - Kink
    利率 = 基础利率 + 低斜率 + 超额利用率 × 高斜率
```

**示例**（借款利率，Kink = 80%）：

| 利用率 | 借款利率 |
|--------|----------|
| 0% | 1.5% |
| 40% | 3.5% |
| 80% | 5.5% |
| 90% | 20.5% |
| 100% | 35.5% |

### 利率计算优化（采用 Compound V3 方式）

**关键优化**：配置时传入年化利率，初始化时自动转换为每秒利率

```solidity
// 初始化时（只计算一次）
uint256 SECONDS_PER_YEAR = 31,536,000;
supplyPerSecondRate = supplyPerYearRate / SECONDS_PER_YEAR;
borrowPerSecondRate = borrowPerYearRate / SECONDS_PER_YEAR;

// 每次计提利息（高效计算）
newIndex = oldIndex + (oldIndex * perSecondRate * timeElapsed) / 1e18;
```

**优化效果**：
- ✅ 精度更高：每秒利率避免了重复除法导致的精度损失
- ✅ Gas 更低：每次计提节省 ~100 gas（~66% Gas 优化）
- ✅ 计算更快：只需乘法，无需除以 31,536,000
- ✅ 完全兼容：配置文件仍使用易读的年化利率

---

## 权限管理

### Owner 权限

Owner（所有者）可以执行以下操作：

1. **升级合约**：调用 `upgradeTo()` 升级 Lending 或 Configurator
2. **暂停/恢复**：调用 `pause()` / `unpause()` 暂停或恢复合约
3. **配置市场**：通过 Configurator 修改市场参数
4. **转移所有权**：调用 `transferOwnership()` 转移 Owner

### 推荐配置

建议使用多签钱包（如 Gnosis Safe）作为 Owner：

```typescript
// 部署后转移所有权到多签
await lending.transferOwnership(GNOSIS_SAFE_ADDRESS);
await configurator.transferOwnership(GNOSIS_SAFE_ADDRESS);
```

---

## 安全注意事项

### ⚠️ 关键风险

1. **价格预言机风险**：依赖外部价格源，需确保价格源可靠
2. **清算延迟风险**：市场剧烈波动时可能来不及清算
3. **Owner 权限过大**：Owner 拥有所有管理权限，需使用多签

### 🔒 安全建议

1. **使用多签钱包**：将 Owner 设为 Gnosis Safe 等多签钱包
2. **设置合理参数**：
   - `borrowCollateralFactor` < `liquidateCollateralFactor`
   - 合理的清算折扣（storeFrontPriceFactor）
   - 适当的 supplyCap 防止单一资产风险过大
3. **监控系统**：实时监控抵押率，及时清算
4. **价格源多样化**：考虑使用多个价格源取平均

---

## 升级流程

### 使用 upgrades 插件升级（推荐）

运行升级脚本：
```bash
npx hardhat run scripts/deploy/09-upgradeLending.ts --network <network>
```

**脚本特性**：
- ✅ 自动验证存储布局兼容性
- ✅ 自动部署新实现合约
- ✅ 自动更新代理指向
- ✅ 保留所有状态数据

**修改升级目标**：
```typescript
// 在 09-upgradeLending.ts 中修改
const UPGRADE_LENDING = true;  // true = 升级 Lending, false = 升级 Configurator
```

### 手动 UUPS 升级步骤（不推荐）

如果需要手动升级：

1. **部署新实现合约**：
```typescript
const NewLending = await ethers.getContractFactory("LendingV2");
const newImpl = await NewLending.deploy();
```

2. **升级代理**：
```typescript
await lending.upgradeTo(newImpl.address);
```

### 注意事项

- ✅ 只有 Owner 可以升级
- ✅ 必须保持存储布局一致
- ✅ 只能在末尾添加新存储变量
- ⚠️ 升级前在测试网充分测试
- 🔧 推荐使用 upgrades 插件，它会自动验证兼容性

---

## 监控指标

### 关键指标

1. **利用率**：`totalBorrow / totalSupply`
2. **供应利率**：`getSupplyRate()`
3. **借款利率**：`getBorrowRate()`
4. **储备金**：`reserves`
5. **清算库存**：`collateralReserves[asset]`

### 健康检查

```typescript
// 检查利用率
const utilization = totalBorrow.mul(1e18).div(totalSupply);
console.log("Utilization:", utilization / 1e18 * 100, "%");

// 检查是否需要清算
const isLiquidatable = await lending.isLiquidatable(userAddress);
```

---

## 总结

YT Lending 提供了一个简化但功能完整的借贷池系统：

- ✅ 核心借贷功能（存款、借款、抵押品管理）
- ✅ 清算机制（absorb + buyCollateral）
- ✅ 动态利率模型（双拐点）
- ✅ 可升级架构（UUPS）
- ✅ 简化权限管理（Owner）

**适用场景**：
- 中小型借贷协议
- 需要快速上线的项目
- 中心化或半中心化管理的借贷池

**限制**：
- 单一基础资产（只能借贷一种资产）
- 简化的权限模型（不支持 DAO 治理）
- 需要可靠的价格预言机