上传文件至 document

document/ytLp池子合约流程文档.md

@@ -0,0 +1,551 @@
+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）：
+├─ 商店不知道你有权拿商品
+├─ 商店无法验证价值
+└─ ❌ 系统无法运转
+