552 lines
18 KiB
Markdown
552 lines
18 KiB
Markdown
ytLp池子合约流程文档
|
||
1. 项目概述
|
||
1.1 设计目标
|
||
基于GMX GLP原理，设计一个支持多种YT（Yield Token）代币的流动性池系统。
|
||
1.2 架构对比
|
||
Plain Text
|
||
GMX GLP池子： YT流动性池：
|
||
├─ ETH ├─ YT-A
|
||
├─ WBTC ├─ YT-B
|
||
├─ USDC ├─ YT-C
|
||
├─ USDT ├─ YT-D
|
||
└─ DAI └─ WUSD
|
||
↓ ↓
|
||
以USDG统一计价 以USDY统一计价
|
||
核心特点：
|
||
Markdown
|
||
- 一篮子YT代币: YT-A, YT-B, YT-C等（不同的收益代币）
|
||
- WUSD代币支持: 支持WUSD稳定币（地址: `0x7Cd017ca5ddb86861FA983a34b5F495C6F898c41`）
|
||
- 统一底层: 所有YT都基于USDC
|
||
- LP代币（ytLP）: 代表用户在池子中的份额
|
||
- Swap功能: YT-A ↔ YT-B ↔ YT-C ↔ WUSD
|
||
- 计价单位: USDY（完全模拟GMX的USDG）
|
||
- 动态手续费: 根据池子占比自动调整手续费
|
||
- 自动复利: 手续费直接留在池子中，ytLP价值自动增长
|
||
2. 系统流程图
|
||
Plain Text
|
||
┌─────────────────────────────────────────┐
|
||
│ 用户交互层 │
|
||
│ YTRewardRouter.sol │
|
||
│ (addLiquidity / removeLiquidity) │
|
||
└──────────────┬──────────────────────────┘
|
||
│
|
||
┌───────────┴─────────────┐
|
||
▼ ▼
|
||
┌───────────────┐ ┌──────────────────┐
|
||
│ YTPoolManager │◄── │ YTVault │
|
||
│ (流动性管理) │ │ (资金池+动态费率) │
|
||
└───────┬───────┘ └──────┬───────────┘
|
||
│ │
|
||
│ ├──► YT-A (40%)
|
||
│ ├──► YT-B (30%)
|
||
│ ├──► YT-C (20%)
|
||
│ └──► WUSD (10%)
|
||
▼
|
||
┌───────────────┐
|
||
│ ytLP Token │
|
||
│ (ERC20) │
|
||
│ 持有即增值 │
|
||
└───────────────┘
|
||
|
||
辅助合约:
|
||
├─ USDY.sol (统一计价代币)
|
||
└─ YTPriceFeed.sol (价格读取器)
|
||
流程图查看网站：https://www.processon.com/mermaid
|
||
2.1 系统总览架构图
|
||
Plain Text
|
||
graph TB
|
||
subgraph "用户交互层"
|
||
User[用户]
|
||
Router[YTRewardRouter<br/>一站式入口]
|
||
end
|
||
|
||
subgraph "核心业务层"
|
||
PoolManager[YTPoolManager<br/>流动性管理]
|
||
Vault[YTVault<br/>资金池 + 动态手续费]
|
||
USDY[USDY Token<br/>统一计价单位]
|
||
end
|
||
|
||
subgraph "资产层"
|
||
YTA[YT-A Token<br/>40% 目标占比]
|
||
YTB[YT-B Token<br/>30% 目标占比]
|
||
YTC[YT-C Token<br/>20% 目标占比]
|
||
WUSD[WUSD Token<br/>10% 目标占比<br/>0x7Cd017...c41]
|
||
end
|
||
|
||
subgraph "LP代币层"
|
||
YTLP[ytLP Token<br/>流动性凭证]
|
||
end
|
||
|
||
subgraph "奖励层"
|
||
FeeTracker[FeeYtLPTracker<br/>手续费奖励追踪]
|
||
end
|
||
|
||
User -->|存入/取出/交换| Router
|
||
Router -->|管理流动性| PoolManager
|
||
Router -->|质押ytLP| FeeTracker
|
||
PoolManager -->|buyUSDY/sellUSDY| Vault
|
||
PoolManager <-->|铸造/销毁| YTLP
|
||
PoolManager <-->|转移USDY| USDY
|
||
|
||
Vault -->|持有| YTA
|
||
Vault -->|持有| YTB
|
||
Vault -->|持有| YTC
|
||
Vault -->|持有| WUSD
|
||
Vault <-->|铸造/销毁| USDY
|
||
|
||
FeeTracker -->|分发奖励| USDY
|
||
|
||
style WUSD fill:#90EE90
|
||
style USDY fill:#FFD700
|
||
style Vault fill:#87CEEB
|
||
2.2 用户存入流程图
|
||
Plain Text
|
||
flowchart LR
|
||
subgraph "输入"
|
||
A[用户YT代币<br/>10,000 YT-A]
|
||
end
|
||
|
||
subgraph "Router处理"
|
||
B[收集用户代币]
|
||
end
|
||
|
||
subgraph "PoolManager处理"
|
||
C[调用Vault.buyUSDY]
|
||
D[计算ytLP数量<br/>ytLP = USDY * supply / AUM]
|
||
E[铸造ytLP]
|
||
end
|
||
|
||
subgraph "Vault处理"
|
||
F[接收YT代币<br/>poolAmounts增加]
|
||
G[计算手续费<br/>0.3% = 30 YT-A]
|
||
H[更新USDY债务<br/>usdyAmounts增加]
|
||
I[铸造USDY<br/>9,970 USDY]
|
||
end
|
||
|
||
subgraph "输出"
|
||
J[用户获得ytLP<br/>价值9,970 USDY]
|
||
end
|
||
|
||
A --> B
|
||
B --> C
|
||
C --> F
|
||
F --> G
|
||
G --> H
|
||
H --> I
|
||
I --> D
|
||
D --> E
|
||
E --> J
|
||
|
||
style A fill:#90EE90
|
||
style J fill:#FFD700
|
||
style G fill:#FFA07A
|
||
2.3 用户取出流程图
|
||
Plain Text
|
||
flowchart LR
|
||
subgraph "输入"
|
||
A[用户ytLP<br/>5,000 ytLP]
|
||
end
|
||
|
||
subgraph "PoolManager处理"
|
||
B[销毁ytLP]
|
||
C[计算USDY价值<br/>USDY = ytLP * AUM / supply]
|
||
D[转USDY给Vault<br/>5,000 USDY]
|
||
end
|
||
|
||
subgraph "Vault处理"
|
||
E[收到USDY并销毁]
|
||
F[计算YT数量<br/>根据价格]
|
||
G[计算手续费<br/>动态费率]
|
||
H[减少poolAmounts<br/>减少usdyAmounts]
|
||
I[转YT代币]
|
||
end
|
||
|
||
subgraph "输出"
|
||
J[用户收到YT<br/>4,985 YT-A]
|
||
end
|
||
|
||
A --> B
|
||
B --> C
|
||
C --> D
|
||
D --> E
|
||
E --> F
|
||
F --> G
|
||
G --> H
|
||
H --> I
|
||
I --> J
|
||
|
||
style A fill:#FFD700
|
||
style J fill:#90EE90
|
||
style G fill:#FFA07A
|
||
2.4 YT代币互换流程图
|
||
Plain Text
|
||
flowchart LR
|
||
subgraph "输入"
|
||
A[用户YT-A<br/>1,000 YT-A]
|
||
end
|
||
|
||
subgraph "Vault处理"
|
||
B[收到YT-A<br/>poolAmounts增加]
|
||
C[查询价格<br/>priceA, priceB]
|
||
D[计算USDY中间值<br/>1,000 * priceA]
|
||
E[计算YT-B数量<br/>USDY / priceB]
|
||
F[计算动态手续费<br/>检查两端占比]
|
||
G[更新状态<br/>YT-A增, YT-B减<br/>USDY债务转移]
|
||
H[转出YT-B]
|
||
end
|
||
|
||
subgraph "输出"
|
||
I[用户收到YT-B<br/>997 YT-B]
|
||
end
|
||
|
||
A --> B
|
||
B --> C
|
||
C --> D
|
||
D --> E
|
||
E --> F
|
||
F --> G
|
||
G --> H
|
||
H --> I
|
||
|
||
style A fill:#90EE90
|
||
style I fill:#87CEEB
|
||
style F fill:#FFA07A
|
||
2.5 USDY铸造销毁流程图
|
||
Plain Text
|
||
graph TB
|
||
subgraph "USDY生命周期"
|
||
Create[创建: 用户存入YT]
|
||
Mint[Vault铸造USDY]
|
||
Hold[PoolManager持有USDY]
|
||
Transfer[PoolManager转USDY给Vault]
|
||
Burn[Vault销毁USDY]
|
||
Destroy[结束: 用户取回YT]
|
||
end
|
||
|
||
subgraph "关键状态"
|
||
Supply[USDY总供应量]
|
||
PoolBalance[PoolManager余额]
|
||
Debt[各代币USDY债务]
|
||
end
|
||
|
||
Create --> Mint
|
||
Mint --> Supply
|
||
Mint --> Hold
|
||
Hold --> PoolBalance
|
||
Hold --> Transfer
|
||
Transfer --> Burn
|
||
Burn --> Supply
|
||
Burn --> Destroy
|
||
|
||
Mint -.更新.-> Debt
|
||
Burn -.更新.-> Debt
|
||
|
||
style Mint fill:#90EE90
|
||
style Burn fill:#FFB6C1
|
||
style Supply fill:#FFD700
|
||
2.6 动态手续费架构图
|
||
Plain Text
|
||
graph TB
|
||
subgraph "输入层"
|
||
User[用户操作<br/>存入/取出/Swap]
|
||
Token[操作的代币<br/>YT-A/YT-B/YT-C/WUSD]
|
||
Amount[操作数量]
|
||
end
|
||
|
||
subgraph "状态查询层"
|
||
Current[当前USDY债务<br/>usdyAmounts]
|
||
Target[目标USDY债务<br/>getTargetUsdyAmount]
|
||
Weight[代币权重<br/>tokenWeights]
|
||
Supply[USDY总供应<br/>totalSupply]
|
||
end
|
||
|
||
subgraph "计算层"
|
||
Calc1[计算操作后债务<br/>nextAmount]
|
||
Calc2[计算偏离度<br/>initialDiff vs nextDiff]
|
||
Calc3[判断改善/恶化]
|
||
end
|
||
|
||
subgraph "手续费决策层"
|
||
Decision{改善平衡?}
|
||
Rebate[降低手续费<br/>baseFee - rebate]
|
||
Penalty[提高手续费<br/>baseFee + tax]
|
||
end
|
||
|
||
subgraph "输出层"
|
||
Final[最终手续费<br/>0% - 0.8%]
|
||
Effect[效果反馈<br/>引导池子平衡]
|
||
end
|
||
|
||
User --> Token
|
||
Token --> Amount
|
||
Amount --> Current
|
||
|
||
Current --> Calc1
|
||
Target --> Calc1
|
||
Weight --> Target
|
||
Supply --> Target
|
||
|
||
Calc1 --> Calc2
|
||
Calc2 --> Calc3
|
||
Calc3 --> Decision
|
||
|
||
Decision -->|是| Rebate
|
||
Decision -->|否| Penalty
|
||
|
||
Rebate --> Final
|
||
Penalty --> Final
|
||
Final --> Effect
|
||
|
||
style Decision fill:#FFD700
|
||
style Rebate fill:#90EE90
|
||
style Penalty fill:#FFA07A
|
||
style Final fill:#87CEEB
|
||
2.7 各YT代币价格获取图
|
||
Plain Text
|
||
graph TB
|
||
subgraph "价格查询层"
|
||
Query[Vault查询价格<br/>getPrice]
|
||
end
|
||
|
||
subgraph "YTPriceFeed"
|
||
Feed[价格读取器]
|
||
Check{是WUSD?}
|
||
end
|
||
|
||
subgraph "WUSD处理"
|
||
Fixed[返回固定价格<br/>1.0 USDY]
|
||
end
|
||
|
||
subgraph "YT代币处理"
|
||
YTContract[YT代币合约]
|
||
ReadVar[ 直接读取public变量<br/>assetPrice]
|
||
AddSpread[添加价差<br/>0.2%]
|
||
end
|
||
|
||
subgraph "返回"
|
||
Price[返回USDY价格<br/>30位小数]
|
||
end
|
||
|
||
Query --> Feed
|
||
Feed --> Check
|
||
|
||
Check -->|是| Fixed
|
||
Check -->|否| YTContract
|
||
|
||
YTContract --> ReadVar
|
||
Note1[：只读一个变量<br/>Gas成本极低]
|
||
ReadVar -.说明.-> Note1
|
||
ReadVar --> AddSpread
|
||
|
||
AddSpread --> Price
|
||
Fixed --> Price
|
||
|
||
style Check fill:#FFD700
|
||
style Fixed fill:#90EE90
|
||
style ReadVar fill:#87CEEB
|
||
style Note1 fill:#FFE4B5
|
||
3. 收益机制设计
|
||
3.1 自动复利机制
|
||
Plain Text
|
||
ytLP自动增值模型
|
||
|
||
┌──────────────────────┐
|
||
│ 用户持有 ytLP │
|
||
│ (无需质押，无需领取) │
|
||
└────────┬─────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────┐
|
||
│ 池子收取手续费 │
|
||
│ ├─ Swap手续费 │
|
||
│ ├─ 存取手续费 │
|
||
│ └─ 全部留在池子中 │
|
||
└────────┬─────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────┐
|
||
│ 池子总价值(AUM)自动增长 │
|
||
│ AUM = Σ(poolAmounts * prices) │
|
||
│ 手续费 → poolAmounts ↑ │
|
||
└────────┬─────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────┐
|
||
│ ytLP价格自动上涨 │
|
||
│ ytLP价格 = AUM / ytLP总量 │
|
||
│ 持有者自动获得收益 │
|
||
└──────────────────────┘
|
||
3.2 收益来源
|
||
Plain Text
|
||
| 收益来源 | 实现方式 | 说明 |
|
||
|---------|---------|------|
|
||
| **YT Swap手续费** | 留在池子 | 手续费不转出，直接增加poolAmounts |
|
||
| **存入手续费** | 留在池子 | 用户存入时收取的手续费留在池子 |
|
||
| **取出手续费** | 留在池子 | 用户取出时收取的手续费留在池子 |
|
||
| **YT 增值** | 自动 | YT代币本身增值，体现在价格 |
|
||
优势:
|
||
• ✅ 100%手续费归LP
|
||
• ✅ 自动复利，无需操作
|
||
• ✅ Gas高效，零额外成本
|
||
3.3 自动复利效果演示
|
||
Plain Text
|
||
场景：Alice持有1000 ytLP
|
||
|
||
T0: 初始状态
|
||
├─ 池子AUM: 100M USDY
|
||
├─ ytLP总量: 100M
|
||
├─ ytLP价格: 1.0 USDY
|
||
├─ Alice持有: 1000 ytLP
|
||
└─ Alice价值: 1000 USDY
|
||
|
||
T1: 1天后（产生手续费）
|
||
├─ 每日交易量: 5M USDY
|
||
├─ 平均手续费: 0.3%
|
||
├─ 日手续费: 15,000 USDY
|
||
├─ 手续费留在池子 ✅
|
||
│
|
||
├─ 池子AUM: 100,015,000 USDY
|
||
├─ ytLP总量: 100M (不变)
|
||
├─ ytLP价格: 1.00015 USDY ⬆️
|
||
├─ Alice持有: 1000 ytLP (不变)
|
||
└─ Alice价值: 1000.15 USDY ✅ (+0.015%)
|
||
|
||
T30: 30天后（复利累积）
|
||
├─ 累积手续费: ~450,000 USDY
|
||
├─ 池子AUM: 100,450,000 USDY
|
||
├─ ytLP价格: 1.0045 USDY ⬆️
|
||
├─ Alice持有: 1000 ytLP
|
||
└─ Alice价值: 1004.5 USDY ✅ (+0.45%)
|
||
|
||
T365: 1年后（年化收益）
|
||
├─ 累积手续费: ~5.475M USDY
|
||
├─ 加上YT增值: ~8M USDY
|
||
├─ 池子AUM: 113.475M USDY
|
||
├─ ytLP价格: 1.13475 USDY ⬆️
|
||
├─ Alice持有: 1000 ytLP
|
||
└─ Alice价值: 1134.75 USDY ✅ (+13.475%)
|
||
|
||
Alice全程无需任何操作！
|
||
只需持有ytLP，价值自动增长
|
||
4. 动态手续费
|
||
4.1 动态手续费机制
|
||
场景1：YT-A占比过高
|
||
公式：
|
||
avg_dev = (|D_after| + |D_before|)/2
|
||
adjustment = K * avg_dev / target
|
||
Plain Text
|
||
当前状态：
|
||
YT-A: usdyAmounts = 50M, 目标 = 40M (+10M, 占比过高)
|
||
YT-B: usdyAmounts = 30M, 目标 = 30M (正好)
|
||
YT-C: usdyAmounts = 15M, 目标 = 20M (-5M, 占比过低)
|
||
WUSD: usdyAmounts = 5M, 目标 = 10M (-5M, 占比过低)
|
||
|
||
用户A想存入1M USDY价值的YT-A：
|
||
┌─────────────────────────────────────┐
|
||
│ 初始偏离: +10M │
|
||
│ 操作后偏离: +11M (恶化平衡) │
|
||
│ 基础手续费: 0.3% (30 bps) │
|
||
│ 税费计算: 50 * 10.5M / 40M ≈ 13 bps │
|
||
│ 最终手续费: 30 + 13 = 43 bps (0.43%) │
|
||
└─────────────────────────────────────┘
|
||
结果：手续费提高 43% → 😱 惩罚
|
||
|
||
用户B想存入1M USDY价值的YT-C：
|
||
┌─────────────────────────────────────┐
|
||
│ 初始偏离: -5M │
|
||
│ 操作后偏离: -4M (改善平衡) │
|
||
│ 基础手续费: 0.3% (30 bps) │
|
||
│ 折扣计算: 50 * 5M / 20M = 12.5 bps │
|
||
│ 最终手续费: 30 - 12.5 = 17.5 bps │
|
||
└─────────────────────────────────────┘
|
||
结果：手续费降低 42% → 🎉 激励
|
||
|
||
用户C想从YT-A换到YT-C：
|
||
┌─────────────────────────────────────┐
|
||
│ YT-A减少 → 改善平衡 ✅ │
|
||
│ YT-C增加 → 改善平衡 ✅ │
|
||
│ 最终手续费: 可能接近0% 🎁 │
|
||
└─────────────────────────────────────┘
|
||
结果：双重鼓励！
|
||
场景2：WUSD作为稳定资产
|
||
Plain Text
|
||
WUSD (0x7Cd017ca5ddb86861FA983a34b5F495C6F898c41)
|
||
|
||
特点：
|
||
✅ 稳定币，价格 ≈ $1
|
||
✅ 可以直接存入池子
|
||
✅ 目标占比: 50%
|
||
✅ 作为池子的"稳定锚"
|
||
|
||
动态手续费：
|
||
当WUSD占比过低时 → 鼓励存入WUSD
|
||
当WUSD占比过高时 → 鼓励取出WUSD
|
||
|
||
用户存入WUSD场景：
|
||
当前: WUSD占5M，目标10M
|
||
存入5M WUSD:
|
||
- 改善平衡 → 手续费可能只有0.05% 🎉
|
||
4.2 手续费范围
|
||
Plain Text
|
||
YT代币互换:
|
||
- 最低: 0% (大幅改善平衡)
|
||
- 正常: 0.3% (平衡状态)
|
||
- 最高: 0.8% (严重失衡)
|
||
|
||
涉及WUSD的操作:
|
||
- 最低: 0% (大幅改善平衡)
|
||
- 正常: 0.04% (平衡状态)
|
||
- 最高: 0.24% (严重失衡)
|
||
4.3 USDY债务追踪机制
|
||
Solidity
|
||
// usdyAmounts: 追踪每个代币的USDY债务
|
||
mapping(address => uint256) public usdyAmounts;
|
||
|
||
// 存入YT-A时：
|
||
buyUSDY(YT-A) {
|
||
// 1. 收YT-A
|
||
// 2. 增加池子中YT-A数量
|
||
// 3. 增加usdyAmounts[YT-A] ← 关键！
|
||
// 4. 铸造USDY给用户
|
||
}
|
||
|
||
// 取出YT-B时：
|
||
sellUSDY(YT-B) {
|
||
// 1. 收用户的USDY并销毁
|
||
// 2. 减少usdyAmounts[YT-B] ← 关键！
|
||
// 3. 减少池子中YT-B数量
|
||
// 4. 转YT-B给用户
|
||
}
|
||
|
||
// Swap: YT-A → YT-C时：
|
||
swap(YT-A, YT-C) {
|
||
// 1. 收YT-A，增加usdyAmounts[YT-A]
|
||
// 2. 转YT-C，减少usdyAmounts[YT-C]
|
||
// 3. 根据两边的偏离度计算手续费
|
||
}
|
||
4.4 USDY主要作用
|
||
✅ 统一计价：所有YT转换为USDY价值
|
||
✅ 价值传递：PoolManager和Vault通过USDY交互
|
||
✅ 动态手续费：usdyAmounts追踪债务，自动平衡
|
||
✅ 按需铸造：资金高效利用，会计清晰
|
||
4.4.1 举例说明
|
||
Plain Text
|
||
场景：你去商店用积分换商品
|
||
├─ 你：有1000积分（ytLP）
|
||
├─ 积分中心（PoolManager）：销毁你的积分
|
||
├─ 商店（Vault）：有商品（YT代币）
|
||
└─ 问题：商店凭什么给你商品？
|
||
|
||
解决方案：
|
||
1. 积分中心销毁你的积分 ✅
|
||
2. 积分中心给商店"提货券"（USDY） ✅ ← 关键！
|
||
3. 商店验证提货券 ✅
|
||
4. 商店给你商品 ✅
|
||
5. 商店销毁提货券 ✅
|
||
|
||
如果没有第2步（转USDY）：
|
||
├─ 商店不知道你有权拿商品
|
||
├─ 商店无法验证价值
|
||
└─ ❌ 系统无法运转
|
||
|