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