文档版本: 1.0
生成日期: 2026-01-15
分析范围: Aave V4 协议核心数据结构
目标: 深入理解数据结构的用途、设计原理和使用示例
Aave V4 的数据结构遵循 Hub-Spoke 架构，分为三个主要层次：
┌─────────────────────────────────────────┐
│ Hub Layer (资产层) │
│ - Asset (资产数据) │
│ - SpokeData (Spoke数据) │
│ - 流动性管理 │
└─────────────┬───────────────────────────┘
│
┌─────────────▼───────────────────────────┐
│ Spoke Layer (业务逻辑层) │
│ - Reserve (储备金) │
│ - UserPosition (用户仓位) │
│ - PositionStatus (仓位状态) │
└─────────────┬───────────────────────────┘
│
┌─────────────▼───────────────────────────┐
│ Library Layer (工具层) │
│ - SharesMath (份额计算) │
│ - Premium (溢价计算) │
│ - PositionStatusMap (位图) │
└─────────────────────────────────────────┘
- 存储优化: 使用位打包技术，最大化利用存储槽
- 精度管理: 使用 RAY (1e27) 精度处理利息累积
- 份额系统: 类似 ERC4626，用份额代替余额
- 安全防护: 虚拟资产/份额防止首存攻击
Asset 是 Hub 中最核心的数据结构，表示一个流动性池中的单一资产（如 USDC、DAI、WETH）。它管理该资产的所有流动性、份额、利率和费用信息。
struct Asset {
// === 流动性和份额数据 (Slot 1-3) ===
uint120 liquidity; // 可用流动性（底层资产单位）
uint200 deficitRay; // 赤字金额（RAY精度）
uint120 swept; // 被扫走的资产数量
// === 份额数据 (Slot 4-5) ===
uint120 addedShares; // 总存款份额
uint120 drawnShares; // 总借款份额
uint120 premiumShares; // 总溢价份额（利息）
// === 溢价偏移和索引 (Slot 6-7) ===
int200 premiumOffsetRay; // 溢价偏移（RAY精度）
uint120 drawnIndex; // 借款索引（累积利率）
// === 地址和配置 (Slot 8-9) ===
address underlying; // 底层资产地址（如USDC合约地址）
uint40 lastUpdateTimestamp; // 最后更新时间戳
uint8 decimals; // 资产小数位数
uint96 drawnRate; // 当前借款利率
// === 策略和费用 (Slot 10-11) ===
address irStrategy; // 利率策略合约地址
uint256 realizedFees; // 已实现费用
address reinvestmentController; // 再投资控制器
address feeReceiver; // 费用接收者
uint256 liquidityFee; // 流动性费用（BPS）
}1. 位打包优化
Slot 1: [liquidity: 120 bits] + [136 bits 可用]
Slot 2: [deficitRay: 200 bits] + [56 bits 可用]
Slot 3: [swept: 120 bits] + [136 bits 可用]
Slot 4: [addedShares: 120] + [drawnShares: 120] + [16 bits 可用]
Slot 5: [premiumShares: 120 bits] + [136 bits 可用]
Slot 6: [premiumOffsetRay: 200 bits] + [56 bits 可用]
Slot 7: [drawnIndex: 120] + [underlying: 160] (部分)
Slot 8: [underlying: 剩余] + [lastUpdateTimestamp: 40] + [decimals: 8] + [drawnRate: 96]
...
优势:
- 减少存储槽使用 ~40-60%
- 降低 Gas 消耗
- 保持数据紧密性
2. 份额系统
存款份额 (addedShares):
- 用户存入资产 → 铸造份额
- 份额价值随时间增长（利息累积）
- assets = shares × (totalAssets + VIRTUAL) / (totalShares + VIRTUAL)
借款份额 (drawnShares):
- 用户借出资产 → 铸造债务份额
- 债务随时间增长（利息累积）
- debt = shares × drawnIndex
溢价份额 (premiumShares):
- 表示累积的利息费用
- 激励流动性提供者
- 从借款利息中收取
3. 利率索引机制
// 借款索引增长
drawnIndex_new = drawnIndex_old × (1 + rate × Δt)
// 用户债务计算
userDebt = userDrawnShares × drawnIndex
// 特点：
// - O(1) 时间复杂度
// - 自动累积利息
// - 无需遍历所有用户4. RAY 精度
// RAY = 1e27 (27位小数)
// WAD = 1e18 (18位小数)
// 为什么使用 RAY？
// 1. 更高精度，适合长期累积
// 2. 减少舍入误差
// 3. 支持小额交易
// 示例：
uint256 premiumRay = 1234567890123456789012345678; // 1.234... 单位
uint256 premium = premiumRay / 1e27; // 转换为普通单位示例 1: 用户存款
// 场景：Alice 存入 1000 USDC
// 1. 计算存款份额
uint256 amount = 1000e6; // 1000 USDC (6 decimals)
uint256 shares = asset.toAddedSharesDown(amount);
// shares = 1000e6 × (totalShares + 1e6) / (totalAssets + 1e6)
// 2. 更新资产状态
asset.liquidity += amount;
asset.addedShares += shares;
// 3. 更新用户仓位
userPosition.suppliedShares += shares;
// 4. 用户以后可以赎回
uint256 redeemableAssets = shares × (totalAssets + 1e6) / (totalShares + 1e6);
// redeemableAssets >= 1000 USDC (包含利息)示例 2: 利息累积
// 场景：10天后利息累积
// 初始状态
drawnIndex = 1e27; // 1.0
drawnRate = 0.05e27; // 5% APR
timeElapsed = 10 days;
// 计算新索引
uint256 linearInterest = 1e27 + (drawnRate × timeElapsed / 365 days);
// linearInterest ≈ 1.00137e27 (约0.137%增长)
drawnIndex_new = drawnIndex × linearInterest / 1e27;
// drawnIndex_new ≈ 1.00137e27
// 用户债务自动增长
// userDebt = 1000 × 1.00137 = 1001.37 USDC示例 3: 虚拟资产防护
// 没有虚拟资产的攻击场景
// 1. 攻击者首次存入 1 wei
shares_attacker = 1; // 1 wei → 1 share
totalShares = 1;
totalAssets = 1;
// 2. 攻击者直接转账 1000 ETH（捐赠攻击）
totalAssets = 1000e18 + 1;
totalShares = 1;
// 3. 受害者存入 1 ETH
shares_victim = 1e18 × 1 / 1000e18 = 0; // 四舍五入为0！
// 受害者损失 1 ETH
// ===========================
// 有虚拟资产的防御
VIRTUAL_ASSETS = 1e6;
VIRTUAL_SHARES = 1e6;
// 1. 攻击者首次存入 1 wei
shares_attacker = 1 × (0 + 1e6) / (0 + 1e6) = 1;
totalShares = 1;
totalAssets = 1;
// 2. 攻击者直接转账 1000 ETH
totalAssets = 1000e18 + 1;
// 3. 受害者存入 1 ETH
shares_victim = 1e18 × (1 + 1e6) / (1000e18 + 1 + 1e6);
shares_victim ≈ 1000; // 攻击失败！受害者获得合理份额示例 4: 赤字报告
// 场景：清算后出现坏账
// 清算前
user.drawnShares = 1000;
user.collateralShares = 500; // 价值不足
// 清算后（抵押品不足以覆盖债务）
uint256 debtValue = 1000 USDC;
uint256 collateralValue = 800 USDC; // 不足
uint256 deficit = 200 USDC;
// 报告赤字
uint256 deficitRay = deficit.toRay(); // 200e27
asset.deficitRay += deficitRay;
spoke.deficitRay += deficitRay;
// 协议损失由所有流动性提供者分担
// 通过份额价值稀释实现SpokeData 记录特定 Spoke 合约在特定资产中的活动状态，包括该 Spoke 代表的所有用户的总存款、借款和风险参数。
struct SpokeData {
// === 份额数据 (Slot 1-2) ===
uint120 addedShares; // Spoke的总存款份额
uint120 drawnShares; // Spoke的总借款份额
uint120 premiumShares; // Spoke的总溢价份额
// === 溢价和赤字 (Slot 3-4) ===
int200 premiumOffsetRay; // 溢价偏移
uint200 deficitRay; // Spoke的赤字
// === 配置参数 (Slot 5) ===
uint40 addCap; // 存款上限
uint40 drawCap; // 借款上限
uint24 riskPremiumThreshold; // 风险溢价阈值
// === 状态标志 (Slot 5 continued) ===
bool active; // 是否活跃
bool paused; // 是否暂停
}1. 分层管理
Hub (全局视角)
├── Asset: 所有Spoke的聚合数据
│ ├── totalAddedShares: 10000
│ ├── totalDrawnShares: 5000
│ └── totalLiquidity: 50000
│
├── SpokeData[SpokeA]: Spoke A的数据
│ ├── addedShares: 6000
│ ├── drawnShares: 3000
│ └── deficit: 0
│
└── SpokeData[SpokeB]: Spoke B的数据
├── addedShares: 4000
├── drawnShares: 2000
└── deficit: 100e27
2. 风险隔离
// 每个Spoke可以有独立的风险参数
spoke1.addCap = 1000000e6; // Spoke 1 上限 100万 USDC
spoke1.drawCap = 500000e6; // Spoke 1 借款上限 50万 USDC
spoke1.riskPremiumThreshold = 1000; // 10% 风险溢价阈值
spoke2.addCap = 100000e6; // Spoke 2 上限 10万 USDC (更保守)
spoke2.drawCap = 50000e6; // Spoke 2 借款上限 5万 USDC
spoke2.riskPremiumThreshold = 500; // 5% 风险溢价阈值
// 好处：
// - 不同市场不同风险承受能力
// - 新Spoke可以从低上限开始
// - 降低单点风险3. 上限机制
// 场景：Spoke 存款上限控制
// Spoke配置
spoke.addCap = 1000000; // 100万（无小数位，将乘以资产decimals）
asset.decimals = 6; // USDC
uint256 actualCap = spoke.addCap × 10^6 = 1000000e6;
// 用户Alice想存入 100 USDC
uint256 amount = 100e6;
uint256 currentDeposits = hub.previewRemoveByShares(
assetId,
spoke.addedShares
); // 例如: 999950e6
// 检查上限
require(
spoke.addCap == type(uint40).max || // 无限上限
actualCap >= currentDeposits + amount, // 或在上限内
"上限超限"
);
// 999950e6 + 100e6 = 1000050e6 > 1000000e6 → 失败！示例 1: Spoke 激活和配置
// 场景：为新的Spoke设置参数
// 1. 添加Spoke到Hub
hub.addSpoke(assetId, spokeAddress, {
addCap: 1000000, // 100万单位上限
drawCap: 500000, // 50万单位借款上限
riskPremiumThreshold: 1000, // 10% 风险溢价
active: true, // 立即激活
paused: false // 不暂停
});
// 2. Hub创建SpokeData
SpokeData storage spoke = _spokes[assetId][spokeAddress];
spoke.addCap = 1000000;
spoke.drawCap = 500000;
spoke.riskPremiumThreshold = 1000;
spoke.active = true;
spoke.paused = false;
// 3. 现在Spoke可以开始操作示例 2: 跟踪Spoke的总活动
// 场景：查询Spoke A的统计数据
SpokeData storage spokeA = _spokes[assetId][spokeAAddress];
// Spoke A 的总存款
uint256 spokeDeposits = asset.toAddedAssetsDown(spokeA.addedShares);
// 示例: 5000 shares × (100000 + 1e6) / (10000 + 1e6) ≈ 50000 USDC
// Spoke A 的总借款
uint256 spokeDebt = asset.toDrawnAssetsUp(spokeA.drawnShares);
// 示例: 2000 shares × drawnIndex ≈ 20500 USDC (包含利息)
// Spoke A 的溢价债务
uint256 spokePremium = calculatePremiumRay(
spokeA.premiumShares,
spokeA.premiumOffsetRay,
asset.drawnIndex
).fromRayUp();
// 示例: 500 USDC 利息
// Spoke A 的赤字
uint256 spokeDeficit = spokeA.deficitRay.fromRayUp();
// 示例: 100 USDC 坏账示例 3: 风险溢价检查
// 场景：还款时检查风险溢价阈值
// 用户还款后计算新的溢价份额
uint256 newPremiumShares = userPosition.drawnShares.percentMulUp(riskPremium);
// 示例: 1000 shares × 5% = 50 premium shares
// 应用到Spoke
spoke.premiumShares += newPremiumShares;
// 检查阈值
uint24 threshold = spoke.riskPremiumThreshold;
uint256 maxAllowedPremium = spoke.drawnShares.percentMulUp(threshold);
// 示例: 5000 shares × 10% = 500 shares
require(
threshold == MAX_RISK_PREMIUM_THRESHOLD || // 无限制
spoke.premiumShares <= maxAllowedPremium, // 或在阈值内
"风险溢价超限"
);
// 如果 premiumShares = 550 > 500 → 失败！Reserve 表示 Spoke 中的一个资产储备金，连接 Hub 中的资产和 Spoke 的业务逻辑。每个储备金对应一个底层资产（如 USDC），并包含该资产的风险参数和配置。
struct Reserve {
// === 基础信息 (Slot 1) ===
address underlying; // 底层资产地址 (20 bytes)
// === Hub连接 (Slot 1 continued + Slot 2) ===
IHubBase hub; // Hub合约地址 (20 bytes)
uint16 assetId; // Hub中的资产ID (2 bytes)
uint8 decimals; // 资产小数位 (1 byte)
// === 配置 (Slot 2 continued) ===
uint24 dynamicConfigKey; // 动态配置键 (3 bytes)
uint24 collateralRisk; // 抵押品风险 BPS (3 bytes)
// === 标志位 (Slot 2 continued) ===
ReserveFlags flags; // 位图标志 (1 byte)
}ReserveFlags 位图结构:
type ReserveFlags is uint8;
// 位定义
Bit 0: paused // 储备金是否暂停
Bit 1: frozen // 储备金是否冻结
Bit 2: borrowable // 是否可借款
Bit 3: liquidatable // 是否可清算
Bit 4: receiveSharesEnabled // 是否允许接收份额
Bit 5-7: 未使用
// 示例值
0b00011101 = 29
│││││└── paused = 1 (暂停)
││││└─── frozen = 0 (未冻结)
│││└──── borrowable = 1 (可借)
││└───── liquidatable = 1 (可清算)
│└────── receiveSharesEnabled = 1 (可接收份额)
└─────── 未使用1. 极致的存储优化
Slot 1 完整布局 (256 bits):
┌────────────────────┬──────────┬─────────┬────────────┬───────────────┬───────┐
│ underlying │ hub │ assetId │ decimals │dynamicConfigKey│collat.│
│ 160 bits │ 160 bits │ 16 bits │ 8 bits │ 24 bits │24 bits│
└────────────────────┴──────────┴─────────┴────────────┴───────────────┴───────┘
↓ 跨槽存储 ↓
Slot 2 完整布局 (256 bits):
┌──────────────┬────────────────┬──────────────┬──────────┬────────────────────┐
│ hub (剩余) │dynamicConfigKey│collateralRisk│ flags │ 未使用 │
│ bits │ 24 bits │ 24 bits │ 8 bits │ ... │
└──────────────┴────────────────┴──────────────┴──────────┴────────────────────┘
总计: 约 2 个存储槽（相比传统设计节省 50%）
2. 标志位打包
// 传统方式（5个存储槽）
bool paused; // 1 槽
bool frozen; // 1 槽
bool borrowable; // 1 槽
bool liquidatable; // 1 槽
bool receiveSharesEnabled;// 1 槽
// 总计: 5 槽 = 100,000 gas 读取
// V4 方式（1个字节）
uint8 flags; // 1 字节（与其他数据共享槽）
// 总计: 0 额外槽 = 0 额外 gas
// 操作示例
flags |= BORROWABLE_MASK; // 设置可借款
flags &= ~FROZEN_MASK; // 取消冻结
bool isBorrowable = (flags & BORROWABLE_MASK) != 0; // 检查3. 动态配置系统
Reserve
├── dynamicConfigKey: 2 (当前激活的配置版本)
│
DynamicReserveConfig[0]: 旧配置
├── collateralFactor: 8000 (80% LTV)
├── maxLiquidationBonus: 11000 (110% 奖励)
└── liquidationFee: 500 (5% 费用)
DynamicReserveConfig[1]: 中间配置
├── collateralFactor: 7500 (75% LTV)
├── maxLiquidationBonus: 11500 (115% 奖励)
└── liquidationFee: 1000 (10% 费用)
DynamicReserveConfig[2]: 当前配置 ← dynamicConfigKey
├── collateralFactor: 7000 (70% LTV)
├── maxLiquidationBonus: 12000 (120% 奖励)
└── liquidationFee: 1000 (10% 费用)
// 用途：
// - 新用户使用最新配置
// - 老用户保持原配置直到刷新
// - 避免突然改变所有用户条件
示例 1: 添加新储备金
// 场景：Spoke 添加 USDC 储备金
// 1. 获取Hub中的资产信息
(address underlying, uint8 decimals) = hub.getAssetUnderlyingAndDecimals(assetId);
// underlying = 0xA0b8...USDC合约地址
// decimals = 6
// 2. 创建储备金
uint256 reserveId = _reserveCount++;
_reserves[reserveId] = Reserve({
underlying: underlying, // USDC地址
hub: IHubBase(hubAddress), // Hub地址
assetId: uint16(assetId), // 在Hub中的ID = 0
decimals: decimals, // 6
dynamicConfigKey: 0, // 第一个配置
collateralRisk: 500, // 5% 抵押品风险
flags: ReserveFlagsMap.create({
initPaused: false,
initFrozen: false,
initBorrowable: true,
initLiquidatable: true,
initReceiveSharesEnabled: true
})
});
// 3. 设置动态配置
_dynamicConfig[reserveId][0] = DynamicReserveConfig({
collateralFactor: 8000, // 80% LTV
maxLiquidationBonus: 11000, // 110% 清算奖励
liquidationFee: 500 // 5% 清算费
});示例 2: 检查储备金状态
// 场景：用户想借款前检查
Reserve storage reserve = _reserves[reserveId];
// 检查1: 储备金未暂停
require(!reserve.flags.paused(), "储备金已暂停");
// 检查2: 储备金未冻结
require(!reserve.flags.frozen(), "储备金已冻结");
// 检查3: 储备金可借款
require(reserve.flags.borrowable(), "储备金不可借款");
// 检查4: 有足够流动性
uint256 liquidity = reserve.hub.getAssetLiquidity(reserve.assetId);
require(liquidity >= amount, "流动性不足");
// 全部通过，可以借款示例 3: 更新储备金配置
// 场景：市场波动，需要降低 LTV
// 1. 添加新的动态配置
uint24 currentKey = reserve.dynamicConfigKey; // 例如: 1
uint24 newKey = currentKey + 1; // 2
_dynamicConfig[reserveId][newKey] = DynamicReserveConfig({
collateralFactor: 7000, // 从80%降低到70%
maxLiquidationBonus: 12000, // 提高清算奖励（鼓励清算）
liquidationFee: 1000 // 提高清算费
});
// 2. 更新储备金配置键
reserve.dynamicConfigKey = newKey;
// 3. 影响
// - 新用户/刷新配置的用户: 使用70% LTV
// - 现有用户: 仍使用旧配置，直到下次操作刷新
// userPosition.dynamicConfigKey = 1 (旧)示例 4: 抵押品风险评分
// 场景：计算用户的风险溢价
// 用户有多个抵押品
// Reserve 1 (USDC): collateralRisk = 100 (1%)
// Reserve 2 (WETH): collateralRisk = 500 (5%)
// Reserve 3 (LINK): collateralRisk = 1000 (10%)
// 用户的债务分布
userDebtValue = 10000 USD;
// 抵押品价值（按风险排序）
collateral[USDC] = 5000 USD (最低风险)
collateral[WETH] = 3000 USD (中等风险)
collateral[LINK] = 3000 USD (最高风险)
// 计算风险溢价（按风险从低到高匹配债务）
riskPremium = (5000 × 100 + 3000 × 500 + 2000 × 1000) / 10000
= (500000 + 1500000 + 2000000) / 10000
= 400 (4%)
// 用途：
// - 高风险抵押品支付更高利息
// - 激励使用低风险抵押品
// - 保护协议安全UserPosition 记录单个用户在单个储备金中的仓位，包括存款份额、借款份额和溢价债务。
struct UserPosition {
// === 份额数据 (Slot 1-2) ===
uint120 suppliedShares; // 用户的存款份额
uint120 drawnShares; // 用户的借款份额
uint120 premiumShares; // 用户的溢价份额（利息债务）
// === 溢价偏移 (Slot 3) ===
int200 premiumOffsetRay; // 溢价偏移（RAY精度）
// === 配置引用 (Slot 3 continued) ===
uint24 dynamicConfigKey; // 用户使用的配置版本
}1. 三层份额系统
用户仓位 = 存款 + 借款 + 利息
存款份额 (suppliedShares):
├── 代表用户存入的资产
├── 随时间增值（存款利息）
└── 可以提取或作为抵押品
借款份额 (drawnShares):
├── 代表用户借出的资产
├── 随时间增长（借款利息）
└── 必须偿还
溢价份额 (premiumShares):
├── 代表用户欠的额外利息
├── 基于风险溢价计算
├── 从借款利息中支付
└── premium = drawnShares × riskPremium
2. 溢价计算公式
// 溢价份额表示风险调整后的利息
premiumRay = premiumShares × drawnIndex - premiumOffsetRay
// 为什么需要offset？
// - 允许精确调整溢价
// - 支持风险溢价变化
// - 避免重新计算所有历史数据
// 示例：
drawnShares = 1000
riskPremium = 500 (5%)
drawnIndex = 1.1e27
// 初始
premiumShares = 1000 × 5% = 50
premiumOffsetRay = 50 × 1.0e27 = 50e27
premiumRay = 50 × 1.0e27 - 50e27 = 0
// 10天后
drawnIndex = 1.1e27
premiumRay = 50 × 1.1e27 - 50e27 = 5e27 (5 units 利息)3. 配置版本绑定
时间线:
T0: 用户开仓
├── Reserve.dynamicConfigKey = 1
├── UserPosition.dynamicConfigKey = 1
├── 配置1: LTV 80%, 奖励 110%
│
T1: 协议更新配置
├── Reserve.dynamicConfigKey = 2
├── UserPosition.dynamicConfigKey = 1 (仍是旧配置)
├── 配置2: LTV 75%, 奖励 115%
│ └── 用户仍受配置1约束
│
T2: 用户操作（借款/还款/刷新配置）
├── Reserve.dynamicConfigKey = 2
├── UserPosition.dynamicConfigKey = 2 (更新!)
└── 配置2: 现在用户使用新配置
示例 1: 存款操作
// 场景：Alice 存入 1000 USDC
// 1. 转账资产到Hub
IERC20(reserve.underlying).safeTransferFrom(alice, address(hub), 1000e6);
// 2. Hub计算份额
uint256 shares = hub.add(reserve.assetId, 1000e6);
// shares = 1000e6 × (totalShares + 1e6) / (totalAssets + 1e6)
// 假设: totalShares = 10000e6, totalAssets = 10500e6
// shares = 1000e6 × 10001e6 / 10501e6 ≈ 952.9e6
// 3. 更新用户仓位
UserPosition storage position = _userPositions[alice][reserveId];
position.suppliedShares += uint120(shares); // 952.9e6
// 4. Alice 现在可以随时提取
// 如果价值增长到 totalAssets = 11000e6:
// withdrawal = 952.9e6 × 11001e6 / 11000e6 ≈ 953e6 ≈ 1000.1 USDC示例 2: 借款操作
// 场景：Bob 借款 500 DAI
// 1. 检查健康因子（借款前）
UserAccountData memory data = calculateUserAccountData(bob);
// totalCollateralValue = 2000 USD
// totalDebtValue = 500 USD
// avgCollateralFactor = 80%
// healthFactor = 2000 × 0.8 / 500 = 3.2 (健康)
// 2. Hub执行借款
uint256 drawnShares = hub.draw(reserve.assetId, 500e18, bob);
// drawnShares = 500e18 / drawnIndex
// 假设 drawnIndex = 1.05e27
// drawnShares = 500e18 × 1e27 / 1.05e27 ≈ 476.19e18
// 3. 更新用户仓位
UserPosition storage position = _userPositions[bob][reserveId];
position.drawnShares += uint120(drawnShares); // 476.19e18
// 4. 计算并应用风险溢价
uint256 riskPremium = calculateUserAccountData(bob).riskPremium; // 例如 300 (3%)
uint256 newPremiumShares = position.drawnShares × 3% = 14.29e18;
PremiumDelta memory delta = getPremiumDelta({
drawnSharesTaken: 0,
drawnIndex: 1.05e27,
riskPremium: 300,
restoredPremiumRay: 0
});
// delta.sharesDelta = 14.29e18 - oldPremiumShares
// delta.offsetRayDelta = ...
position.premiumShares = uint120(newPremiumShares);
position.premiumOffsetRay = int200(newOffset);
// 5. 检查健康因子（借款后）
data = calculateUserAccountData(bob);
// totalDebtValue = 1000 USD (增加了500)
// healthFactor = 2000 × 0.8 / 1000 = 1.6 (仍然健康)
require(data.healthFactor >= 1e18, "健康因子不足");示例 3: 还款操作
// 场景：Bob 还款 200 DAI
// 1. 计算债务
uint256 drawnIndex = hub.getAssetDrawnIndex(reserve.assetId); // 1.06e27
(uint256 drawnDebt, uint256 premiumDebtRay) = position.getDebt(drawnIndex);
// drawnDebt = 476.19e18 × 1.06e27 / 1e27 = 504.76 DAI
// premiumDebtRay = 14.29e18 × 1.06e27 - offsetRay = 15.15e27 (≈15.15 DAI)
// totalDebt = 519.91 DAI
// 2. 确定还款分配（利息优先）
uint256 repayAmount = 200e18;
uint256 premiumRepay = min(15.15e18, 200e18) = 15.15e18;
uint256 drawnRepay = 200e18 - 15.15e18 = 184.85e18;
// 3. 计算份额减少
uint256 restoredShares = 184.85e18 × 1e27 / 1.06e27 = 174.39e18;
// 4. 转账还款
IERC20(reserve.underlying).safeTransferFrom(bob, address(hub), 200e18);
// 5. Hub恢复资产
hub.restore(reserve.assetId, 184.85e18, premiumDelta);
// 6. 更新用户仓位
position.drawnShares -= uint120(restoredShares); // 476.19 - 174.39 = 301.8
position.applyPremiumDelta(premiumDelta); // 更新溢价
// 7. 剩余债务
// drawnDebt = 301.8e18 × 1.06e27 / 1e27 ≈ 319.91 DAI
// 总共还款了 200 DAI示例 4: 配置刷新
// 场景：Carol 的仓位需要刷新到新配置
// 当前状态
Reserve storage reserve = _reserves[reserveId];
UserPosition storage position = _userPositions[carol][reserveId];
// reserve.dynamicConfigKey = 3 (最新)
// position.dynamicConfigKey = 1 (旧)
// 1. Carol 执行某个触发刷新的操作（如借款、提款）
spoke.borrow(reserveId, amount, carol);
// 2. 内部自动刷新配置
function _refreshAndValidateUserAccountData(carol) {
// 刷新所有抵押品的配置
for (each collateral reserve) {
if (isUsingAsCollateral(carol, reserveId)) {
userPosition.dynamicConfigKey = reserve.dynamicConfigKey;
// 1 → 3
}
}
// 重新计算账户数据（使用新配置）
UserAccountData memory data = calculateUserAccountData(carol);
// 新的LTV可能更严格
// 旧配置: LTV 80% → healthFactor = 2.5
// 新配置: LTV 75% → healthFactor = 2.34
require(data.healthFactor >= 1e18, "健康因子不足");
}
// 3. 现在 Carol 受新配置约束
// position.dynamicConfigKey = 3PositionStatus 使用位图技术高效记录用户在哪些储备金中有活动（借款或抵押品），避免遍历所有储备金。
struct PositionStatus {
// === 位图数组 ===
mapping(uint256 bucketId => uint256 word) map;
// === 风险溢价 ===
uint24 riskPremium; // 用户当前风险溢价 (BPS)
}位图编码方案:
每个储备金使用 2 bits:
- Bit 0: 是否有借款 (borrowing)
- Bit 1: 是否用作抵押品 (collateral)
一个 uint256 (256 bits) 可以表示 128 个储备金
map[0]: Reserve 0-127
map[1]: Reserve 128-255
map[2]: Reserve 256-383
...
示例:
map[0] = 0x...0101001001
││││││││││
│││││││││└─ Reserve 0: 借款=1, 抵押=0
││││││││└── Reserve 0: 抵押=1
││││││└──── Reserve 1: 借款=0, 抵押=0
│││││└───── Reserve 1: 抵押=1
│││└─────── Reserve 2: 借款=1, 抵押=0
││└──────── Reserve 2: 抵押=0
│└────────── Reserve 3: 借款=0, 抵押=0
└─────────── Reserve 3: 抵押=1
1. 高效的存在性检查
// 传统方式：O(n) 遍历
for (uint256 i = 0; i < reserveCount; i++) {
if (userPositions[user][i].drawnShares > 0) {
// 处理借款
}
}
// Gas: ~5000 × n
// 位图方式：O(log n) 跳过空位
uint256 reserveId = positionStatus.nextBorrowing(reserveCount);
while (reserveId != NOT_FOUND) {
// 只处理有借款的储备金
reserveId = positionStatus.nextBorrowing(reserveId);
}
// Gas: ~2000 × actualBorrowingCount2. 位操作优化
// 设置借款标志
function setBorrowing(uint256 reserveId, bool borrowing) {
uint256 bucket = reserveId / 128; // bucketId
uint256 bitPos = (reserveId % 128) × 2; // 在bucket中的位置
uint256 mask = 1 << bitPos;
if (borrowing) {
map[bucket] |= mask; // 设置位
} else {
map[bucket] &= ~mask; // 清除位
}
}
// Gas: ~5000 (SSTORE)
// 检查借款标志
function isBorrowing(uint256 reserveId) returns (bool) {
uint256 bucket = reserveId / 128;
uint256 bitPos = (reserveId % 128) × 2;
return (map[bucket] >> bitPos) & 1 != 0;
}
// Gas: ~2100 (SLOAD)3. 快速迭代算法
// 使用fls (find last set) 查找最高位
function next(uint256 fromReserveId) returns (uint256, bool, bool) {
uint256 bucket = fromReserveId / 128;
uint256 word = map[bucket];
// 屏蔽掉fromReserveId之后的位
word = word & ((1 << ((fromReserveId % 128) << 1)) - 1);
// 找到最高设置位
uint256 bitId = fls(word); // 使用solady的LibBit
// 如果当前bucket没有，检查前一个bucket
while (bitId == 256 && bucket != 0) {
word = map[--bucket];
bitId = fls(word);
}
if (bitId == 256) {
return (NOT_FOUND, false, false);
}
uint256 reserveId = (bitId / 2) + bucket × 128;
bool borrowing = (word >> bitId) & 1 != 0;
bool collateral = (word >> (bitId + 1)) & 1 != 0;
return (reserveId, borrowing, collateral);
}示例 1: 设置用户状态
// 场景：Dave 在 Reserve 5 借款，Reserve 3 作为抵押品
PositionStatus storage status = _positionStatus[dave];
// 1. 设置借款标志
status.setBorrowing(5, true);
// map[0] |= (1 << (5 × 2)) = 1 << 10
// map[0] = 0x...0000010000000000 (bit 10 设置)
// 2. 设置抵押品标志
status.setUsingAsCollateral(3, true);
// map[0] |= (1 << (3 × 2 + 1)) = 1 << 7
// map[0] = 0x...0000010010000000 (bit 7 和 10 设置)
// 3. Dave 的状态现在编码在单个 uint256 中示例 2: 遍历用户的借款
// 场景：计算 Dave 的总债务
uint256 totalDebt = 0;
PositionStatus storage status = _positionStatus[dave];
// 从最后一个储备金开始向前查找
uint256 reserveId = _reserveCount; // 例如: 100
while (true) {
reserveId = status.nextBorrowing(reserveId);
if (reserveId == NOT_FOUND) break;
// 计算该储备金的债务
UserPosition storage position = _userPositions[dave][reserveId];
Reserve storage reserve = _reserves[reserveId];
uint256 debt = reserve.hub.previewRestoreByShares(
reserve.assetId,
position.drawnShares
);
totalDebt += debt;
}
// 如果 Dave 只有 3 个借款（out of 100 reserves）
// 只读取 3 个 UserPosition，而不是 100 个
// Gas 节省: ~97% 示例 3: 计算抵押品数量
// 场景：快速计算 Eve 有多少个抵押品
PositionStatus storage status = _positionStatus[eve];
// 方法1: 位计数（popCount）
uint256 count = 0;
uint256 maxBucket = (_reserveCount - 1) / 128; // 例如: 0 (如果reserveCount <= 128)
for (uint256 bucket = 0; bucket <= maxBucket; bucket++) {
uint256 word = status.map[bucket];
// 分离抵押品位
uint256 collateralBits = word & COLLATERAL_MASK;
// COLLATERAL_MASK = 0xAAAA...AAAA (所有偶数位)
// 计算设置的位数
count += popCount(collateralBits); // 使用 LibBit.popCount
}
// count = 5 (Eve 有 5 个抵押品)
// 方法2: 直接调用库函数
count = status.collateralCount(_reserveCount);
// Gas: ~2000 × (maxBucket + 1)示例 4: 风险溢价追踪
// 场景：Frank 的风险溢价随抵押品变化
PositionStatus storage status = _positionStatus[frank];
// 初始状态
status.riskPremium = 300; // 3%
// Frank 借款 1000 DAI
// 他的溢价份额 = 1000 × 3% = 30
// Frank 增加更高风险的抵押品
_notifyRiskPremiumUpdate(frank, newRiskPremium);
function _notifyRiskPremiumUpdate(address user, uint256 newRiskPremium) {
PositionStatus storage status = _positionStatus[user];
uint256 oldRiskPremium = status.riskPremium; // 300
if (newRiskPremium == oldRiskPremium) return; // 无变化
status.riskPremium = uint24(newRiskPremium); // 500 (5%)
// 更新所有借款储备金的溢价
uint256 reserveId = _reserveCount;
while ((reserveId = status.nextBorrowing(reserveId)) != NOT_FOUND) {
UserPosition storage position = _userPositions[user][reserveId];
Reserve storage reserve = _reserves[reserveId];
// 计算新的溢价增量
PremiumDelta memory delta = position.getPremiumDelta({
drawnSharesTaken: 0,
drawnIndex: reserve.hub.getAssetDrawnIndex(reserve.assetId),
riskPremium: newRiskPremium, // 500
restoredPremiumRay: 0
});
// 新溢价份额 = 1000 × 5% = 50
// delta.sharesDelta = 50 - 30 = 20 (增加)
// 应用到Hub和用户仓位
reserve.hub.refreshPremium(reserve.assetId, delta);
position.applyPremiumDelta(delta);
}
}
// Frank 现在支付更高的利息费用（5% vs 3%）UserAccountData 是计算结果结构体，汇总用户在整个协议中的财务状况，用于健康检查和清算判断。
struct UserAccountData {
uint256 totalCollateralValue; // 总抵押品价值 (USD, 8 decimals)
uint256 totalDebtValue; // 总债务价值 (USD, 8 decimals)
uint256 avgCollateralFactor; // 平均抵押因子 (加权平均)
uint256 healthFactor; // 健康因子 (WAD: 1e18 = 1.0)
uint256 riskPremium; // 风险溢价 (BPS: 500 = 5%)
uint256 activeCollateralCount; // 活跃抵押品数量
uint256 borrowedCount; // 借款储备金数量
}1. 健康因子公式
健康因子 = (总抵押品价值 × 平均抵押因子) / 总债务价值
其中:
- 总抵押品价值 = Σ(每个抵押品的USD价值)
- 平均抵押因子 = 加权平均LTV
- 总债务价值 = Σ(每个债务的USD价值)
健康因子 >= 1.0: 健康
健康因子 < 1.0: 可清算
示例:
抵押品:
- 1000 USDC ($1000) × 85% LTV = $850
- 1 ETH ($2000) × 80% LTV = $1600
总抵押能力 = $2450
债务:
- 500 DAI = $500
- 0.5 WETH = $1000
总债务 = $1500
健康因子 = 2450 / 1500 = 1.63 (健康)
2. 加权平均抵押因子
// 不是简单平均，而是按价值加权
// 错误计算（简单平均）:
avgFactor = (85% + 80%) / 2 = 82.5%
// 正确计算（加权平均）:
avgFactor = (1000 × 85% + 2000 × 80%) / (1000 + 2000)
= (850 + 1600) / 3000
= 81.67%
// 为什么？
// - 高价值抵押品的LTV更重要
// - 反映实际可借款能力
// - 公平对待不同抵押品组合3. 风险溢价计算
// 风险溢价 = 按抵押品风险加权的平均风险
// 抵押品按风险排序（从低到高）:
collaterals = [
{asset: USDC, value: $5000, risk: 100 (1%)},
{asset: WETH, value: $3000, risk: 500 (5%)},
{asset: LINK, value: $3000, risk: 1000 (10%)}
];
// 债务
debtValue = $10000;
// 匹配算法（低风险优先）:
Step 1: $5000 debt ← $5000 USDC (1% risk)
riskContribution = 5000 × 1% = 50
Step 2: $3000 debt ← $3000 WETH (5% risk)
riskContribution = 3000 × 5% = 150
Step 3: $2000 debt ← $2000 LINK (10% risk)
riskContribution = 2000 × 10% = 200
// 总风险溢价
riskPremium = (50 + 150 + 200) / 10000 = 400 / 10000 = 4%
// 用途:
// - 用户使用高风险抵押品支付更高利息
// - 激励使用稳定抵押品
// - 补偿协议风险示例 1: 计算账户数据
// 场景：George 的完整财务状况
function calculateUserAccountData(address george)
returns (UserAccountData memory data)
{
PositionStatus storage status = _positionStatus[george];
// 1. 遍历所有活跃储备金
uint256 reserveId = _reserveCount;
// 用于风险溢价排序的列表
KeyValueList.List memory collateralInfo = KeyValueList.init(
status.collateralCount(reserveId)
);
while (true) {
(reserveId, bool borrowing, bool collateral) = status.next(reserveId);
if (reserveId == NOT_FOUND) break;
UserPosition storage position = _userPositions[george][reserveId];
Reserve storage reserve = _reserves[reserveId];
// 获取价格和单位
uint256 price = IAaveOracle(ORACLE).getReservePrice(reserveId);
// 例如: USDC price = 1.00e8 (8 decimals)
uint256 assetUnit = 10 ** reserve.decimals;
// 例如: USDC unit = 1e6
// 2. 处理抵押品
if (collateral) {
uint24 configKey = position.dynamicConfigKey;
uint256 ltv = _dynamicConfig[reserveId][configKey].collateralFactor;
// 例如: 8000 (80%)
if (ltv > 0) {
uint256 suppliedAssets = reserve.hub.previewRemoveByShares(
reserve.assetId,
position.suppliedShares
);
// 例如: 1000e6 USDC
// 计算USD价值
uint256 collateralValue = (suppliedAssets × price) / assetUnit;
// = (1000e6 × 1e8) / 1e6 = 1000e8 ($1000)
data.totalCollateralValue += collateralValue;
// += 1000e8
// 加权抵押因子
data.avgCollateralFactor += ltv × collateralValue;
// += 8000 × 1000e8 = 8000000e8
// 记录用于风险溢价计算
collateralInfo.add(
data.activeCollateralCount,
reserve.collateralRisk, // 例如: 100 (1%)
collateralValue // 1000e8
);
data.activeCollateralCount++;
}
}
// 3. 处理债务
if (borrowing) {
(uint256 drawnDebt, uint256 premiumDebtRay) = position.getDebt(
reserve.hub,
reserve.assetId
);
uint256 totalDebt = drawnDebt + premiumDebtRay.fromRayUp();
// 例如: 500e18 + 5e18 = 505e18 DAI
// 计算USD价值
uint256 debtValue = (totalDebt × price) / assetUnit;
// = (505e18 × 1e8) / 1e18 = 505e8 ($505)
data.totalDebtValue += debtValue;
data.borrowedCount++;
}
}
// 4. 计算健康因子
if (data.totalDebtValue > 0) {
// healthFactor = avgCollateralFactor / totalDebtValue
// 注意: avgCollateralFactor还未除以totalCollateralValue
data.healthFactor = data.avgCollateralFactor
.wadDivDown(data.totalDebtValue)
.fromBpsDown();
// = 8000000e8 / 505e8 / 100_00 = 1.584e18 (158.4%)
} else {
data.healthFactor = type(uint256).max; // 无债务 = 无限健康
}
// 5. 完成平均抵押因子计算
if (data.totalCollateralValue > 0) {
data.avgCollateralFactor = data.avgCollateralFactor
.wadDivDown(data.totalCollateralValue)
.fromBpsDown();
// = 8000000e8 / 1000e8 / 100_00 = 0.8e18 (80%)
}
// 6. 计算风险溢价
collateralInfo.sortByKey(); // 按风险排序
uint256 debtLeftToCover = data.totalDebtValue; // 505e8
for (uint256 i = 0; i < collateralInfo.length(); i++) {
if (debtLeftToCover == 0) break;
(uint256 risk, uint256 collateralValue) = collateralInfo.get(i);
uint256 coveredValue = min(collateralValue, debtLeftToCover);
data.riskPremium += coveredValue × risk;
debtLeftToCover -= coveredValue;
}
if (debtLeftToCover < data.totalDebtValue) {
data.riskPremium /= (data.totalDebtValue - debtLeftToCover);
// 简化示例: 505e8 × 100 / 505e8 = 100 (1%)
}
return data;
}示例 2: 健康检查
// 场景：Harry 想借更多钱，检查是否安全
// 当前状态
UserAccountData memory data = calculateUserAccountData(harry);
// totalCollateralValue = $5000
// totalDebtValue = $2000
// healthFactor = 2.5e18 (250%)
// Harry 想额外借 $1500
uint256 additionalDebt = 1500e8;
uint256 newTotalDebt = data.totalDebtValue + additionalDebt; // $3500
// 预测新的健康因子
uint256 newHealthFactor = (data.totalCollateralValue × data.avgCollateralFactor)
/ newTotalDebt;
// = (5000e8 × 0.8e18) / 3500e8 = 1.14e18 (114%)
// 检查是否安全
require(newHealthFactor >= 1e18, "借款后健康因子不足");
// 通过！Harry 可以借款示例 3: 清算判断
// 场景：Ivy 的健康因子降至 0.95，可以清算
UserAccountData memory data = calculateUserAccountData(ivy);
// healthFactor = 0.95e18 (95%)
// 检查是否可清算
require(
data.healthFactor < HEALTH_FACTOR_LIQUIDATION_THRESHOLD, // 1e18
"健康因子未低于阈值"
);
// 0.95e18 < 1e18 ✓
// 可以清算！LiquidationConfig 定义 Spoke 的全局清算参数，控制清算行为和奖励机制。
struct LiquidationConfig {
uint64 targetHealthFactor; // 目标健康因子 (WAD)
uint64 healthFactorForMaxBonus; // 最大奖励的健康因子阈值 (WAD)
uint64 liquidationBonusFactor; // 清算奖励因子 (BPS)
}动态清算奖励机制
清算奖励随健康因子变化:
maxBonus (例如: 11%)
│
│ ╱
│ ╱
│ ╱
│╱_____________ minBonus (例如: 5%)
│
└─────────────────────────────
HF_max HF_threshold
(0.95) (1.0)
公式:
if (healthFactor <= healthFactorForMaxBonus) {
bonus = maxBonus;
} else {
// 线性插值
bonus = minBonus + (maxBonus - minBonus) ×
(THRESHOLD - healthFactor) /
(THRESHOLD - healthFactorForMaxBonus);
}
// 场景：配置清算参数
LiquidationConfig config = LiquidationConfig({
targetHealthFactor: 1.25e18, // 125%
healthFactorForMaxBonus: 0.95e18, // 95%
liquidationBonusFactor: 5000 // 50%
});
// 含义：
// 1. 清算后目标恢复到 125% 健康因子
// 2. 健康因子 <= 95% 时给予最大奖励
// 3. 最小奖励 = maxBonus × 50% + 基础 = 约 5.5%
// 计算示例：
// 用户健康因子 = 0.98
// maxBonus = 11%
// minBonus = 11% × 50% + 100% = 105.5%
// 实际奖励 = 105.5% + (111% - 105.5%) × (100% - 98%) / (100% - 95%)
// = 105.5% + 5.5% × 2% / 5%
// = 105.5% + 2.2%
// = 107.7%DynamicReserveConfig 包含可变的风险参数，支持多版本配置以实现平滑升级。
struct DynamicReserveConfig {
uint256 collateralFactor; // 抵押因子/LTV (BPS: 8000 = 80%)
uint256 maxLiquidationBonus; // 最大清算奖励 (BPS: 11000 = 110%)
uint256 liquidationFee; // 清算费用 (BPS: 1000 = 10%)
}// 场景：市场波动时调整参数
// 版本 0: 牛市配置
_dynamicConfig[reserveId][0] = DynamicReserveConfig({
collateralFactor: 8500, // 85% LTV (激进)
maxLiquidationBonus: 10500, // 105% 奖励
liquidationFee: 500 // 5% 费用
});
// 版本 1: 熊市配置
_dynamicConfig[reserveId][1] = DynamicReserveConfig({
collateralFactor: 7000, // 70% LTV (保守)
maxLiquidationBonus: 12000, // 120% 奖励 (鼓励清算)
liquidationFee: 1500 // 15% 费用
});
// 更新储备金配置键
reserve.dynamicConfigKey = 1; // 切换到熊市配置
// 现有用户逐步迁移
// - 新用户立即使用配置1
// - 老用户在下次操作时更新PremiumDelta 记录溢价份额和偏移的变化，用于精确跟踪利息债务。
struct PremiumDelta {
int256 sharesDelta; // 份额变化（可正可负）
int256 offsetRayDelta; // 偏移变化（RAY精度）
uint256 restoredPremiumRay; // 已还款溢价（RAY精度）
}// 场景：用户风险溢价从 3% 变为 5%
// 当前状态
drawnShares = 1000e18;
oldPremiumShares = 30e18; // 1000 × 3%
oldPremiumOffsetRay = 30e27;
drawnIndex = 1.1e27;
// 计算新状态
newPremiumShares = 50e18; // 1000 × 5%
newPremiumOffsetRay = (50e18 × 1.1e27) - currentPremiumRay;
// 创建增量
PremiumDelta memory delta = PremiumDelta({
sharesDelta: int256(50e18 - 30e18) = 20e18,
offsetRayDelta: int256(newOffset - oldOffset),
restoredPremiumRay: 0 // 没有还款
});
// 应用增量
position.premiumShares += uint120(delta.sharesDelta); // 30 + 20 = 50
position.premiumOffsetRay += int200(delta.offsetRayDelta);AssetConfig 包含 Hub 资产的可配置参数。
struct AssetConfig {
address feeReceiver; // 费用接收地址
uint256 liquidityFee; // 流动性费用 (BPS)
address irStrategy; // 利率策略
address reinvestmentController; // 再投资控制器
}// 场景：更新资产费用配置
AssetConfig memory config = AssetConfig({
feeReceiver: treasuryAddress,
liquidityFee: 1000, // 10% 流动性费用
irStrategy: newStrategyAddress,
reinvestmentController: controllerAddress
});
hub.updateAssetConfig(assetId, config, irData);
// 影响：
// - 10% 的借款利息作为费用
// - 费用累积到 feeReceiver
// - 使用新的利率策略Hub
├── Asset[assetId]
│ ├── liquidity, shares, index
│ ├── irStrategy → 利率计算
│ └── feeReceiver → 费用收集
│
└── SpokeData[assetId][spokeAddr]
├── addedShares, drawnShares
├── premiumShares, premiumOffsetRay
├── addCap, drawCap
└── deficitRay
Spoke
├── Reserve[reserveId]
│ ├── underlying, hub, assetId
│ ├── collateralRisk
│ ├── flags (paused, frozen, borrowable, liquidatable)
│ └── dynamicConfigKey → DynamicReserveConfig
│
├── UserPosition[user][reserveId]
│ ├── suppliedShares
│ ├── drawnShares
│ ├── premiumShares, premiumOffsetRay
│ └── dynamicConfigKey
│
└── PositionStatus[user]
├── map (位图)
└── riskPremium
配置
├── DynamicReserveConfig[reserveId][key]
│ ├── collateralFactor
│ ├── maxLiquidationBonus
│ └── liquidationFee
│
└── LiquidationConfig
├── targetHealthFactor
├── healthFactorForMaxBonus
└── liquidationBonusFactor
存款流程:
User → Spoke.supply()
├→ IERC20.transferFrom(user → hub)
└→ Hub.add()
├→ 计算 shares
├→ 更新 Asset.addedShares
├→ 更新 Asset.liquidity
├→ 更新 SpokeData.addedShares
└→ 返回 shares
→ 更新 UserPosition.suppliedShares
借款流程:
User → Spoke.borrow()
├→ Hub.draw()
│ ├→ 计算 drawnShares
│ ├→ 更新 Asset.drawnShares
│ ├→ 更新 Asset.liquidity (减少)
│ ├→ 更新 SpokeData.drawnShares
│ └→ IERC20.transfer(hub → user)
├→ 更新 UserPosition.drawnShares
├→ 更新 PositionStatus.setBorrowing(true)
├→ 计算 riskPremium
├→ Hub.refreshPremium()
│ └→ 更新 premiumShares/Offset
├→ 更新 UserPosition.premiumShares/Offset
└→ 检查 healthFactor
清算流程:
Liquidator → Spoke.liquidationCall()
├→ 计算 UserAccountData
├→ 验证 healthFactor < 1.0
├→ 计算清算金额和奖励
├→ 清算抵押品
│ ├→ 减少 UserPosition.suppliedShares
│ ├→ 增加 Liquidator.suppliedShares 或转账
│ └→ Hub.payFeeShares() (协议费用)
├→ 清算债务
│ ├→ IERC20.transferFrom(liquidator → hub)
│ ├→ Hub.restore() 或 reportDeficit()
│ └→ 减少 UserPosition.drawnShares
└→ 评估是否产生赤字
1. 批量操作
// ❌ 低效：多次调用
spoke.supply(reserveId1, amount1, user);
spoke.setUsingAsCollateral(reserveId1, true, user);
spoke.borrow(reserveId2, amount2, user);
// Gas: ~450,000
// ✅ 高效：批量调用
bytes[] memory calls = new bytes[](3);
calls[0] = abi.encodeCall(spoke.supply, (reserveId1, amount1, user));
calls[1] = abi.encodeCall(spoke.setUsingAsCollateral, (reserveId1, true, user));
calls[2] = abi.encodeCall(spoke.borrow, (reserveId2, amount2, user));
spoke.multicall(calls);
// Gas: ~280,000 (节省 38%)2. 读取优化
// ❌ 多次读取存储
Reserve storage reserve = _reserves[reserveId];
uint256 decimals1 = reserve.decimals;
address underlying1 = reserve.underlying;
uint256 decimals2 = reserve.decimals; // 重复读取！
// ✅ 一次性读取到内存
Reserve memory reserve = _reserves[reserveId];
uint256 decimals = reserve.decimals;
address underlying = reserve.underlying;
// 节省 SLOAD (2100 gas each)1. 舍入方向
// 协议有利的舍入：
// - 用户存款：shares 向下舍入（用户获得更少份额）
// - 用户提款：assets 向下舍入（用户获得更少资产）
// - 用户借款：shares 向上舍入（用户承担更多债务）
// - 用户还款：assets 向上舍入（用户支付更多）
uint256 shares = toSharesDown(depositAmount); // 存款
uint256 assets = toAssetsDown(withdrawShares); // 提款
uint256 drawnShares = toDrawnSharesUp(borrowAmount); // 借款
uint256 repayAssets = toDrawnAssetsUp(repayShares); // 还款2. RAY vs WAD
// RAY (1e27): 用于累积计算（利息、溢价）
uint256 premiumRay = 123456789012345678901234567; // 27位小数
// WAD (1e18): 用于常规计算（价格、百分比）
uint256 healthFactor = 1.5e18; // 150%
// BPS (基点): 用于配置参数
uint256 ltv = 8000; // 80.00%
// 转换
uint256 premium = premiumRay.fromRayUp(); // RAY → 普通单位
uint256 ltvWad = ltv.fromBpsDown(); // BPS → WAD存款前:
- ✓ 储备金未暂停
- ✓ 储备金未冻结
- ✓ Spoke 存款上限未超限
- ✓ 授权充足
提款前:
- ✓ 储备金未暂停
- ✓ 流动性充足
- ✓ 如果用作抵押品，健康因子检查
借款前:
- ✓ 储备金可借款
- ✓ 储备金未暂停/冻结
- ✓ Spoke 借款上限未超限
- ✓ 流动性充足
- ✓ 借款后健康因子 >= 1.0
还款前:
- ✓ 储备金未暂停
- ✓ 还款金额 <= 债务金额
- ✓ 授权充足
清算前:
- ✓ 健康因子 < 1.0
- ✓ 抵押品可清算
- ✓ 用户有抵押品和债务
- ✓ 清算金额合理（不留灰尘）
| 数据结构 | 位置 | 主要用途 | 关键字段 |
|---|---|---|---|
Asset |
Hub | 资产流动性池 | liquidity, shares, drawnIndex |
SpokeData |
Hub | Spoke统计 | addedShares, drawnShares, caps |
Reserve |
Spoke | 资产储备金 | underlying, hub, flags |
UserPosition |
Spoke | 用户仓位 | suppliedShares, drawnShares |
PositionStatus |
Spoke | 用户状态位图 | map, riskPremium |
UserAccountData |
计算结果 | 账户摘要 | healthFactor, totalDebtValue |
LiquidationConfig |
Spoke配置 | 清算参数 | targetHealthFactor, bonus |
DynamicReserveConfig |
Spoke配置 | 风险参数 | collateralFactor, maxBonus |
- 极致的存储优化: 位打包、标志位、紧凑布局
- 份额系统创新: 自动利息累积、O(1)复杂度
- 位图高效性: 快速查找、低Gas遍历
- 配置版本化: 平滑升级、用户保护
- 动态清算机制: 风险敏感的奖励
- RAY精度: 长期累积的高精度
- 虚拟资产防护: 首存攻击防御
- 存储效率: 相比传统设计节省 40-60%
- Gas效率: 操作成本降低 20-40%
- 精度: RAY (1e27) 支持长期累积
- 可扩展性: 支持 256+ 储备金 (uint8 限制可解除)
- 安全性: 多层检查、虚拟资产、动态配置
报告结束 | 生成时间: 2026-01-15 | 版本: 1.0 | 作者: AI Code Analyst
// 资产 ↔ 份额
shares = asset.toAddedSharesDown(assets);
assets = asset.toAddedAssetsUp(shares);
// RAY ↔ 普通单位
assets = assetsRay.fromRayUp();
assetsRay = assets.toRay();
// BPS ↔ WAD
wad = bps.fromBpsDown(); // 8000 → 0.8e18
bps = wad.toBpsUp(); // 0.8e18 → 8000
// 百分比计算
result = value.percentMulDown(percentage); // value × percentage / 10000WAD = 1e18; // 18位小数
RAY = 1e27; // 27位小数
PERCENTAGE_FACTOR = 100_00; // 100.00% (BPS)
HEALTH_FACTOR_LIQUIDATION_THRESHOLD = 1e18; // 100%
VIRTUAL_ASSETS = 1e6;
VIRTUAL_SHARES = 1e6;// 健康检查
require(healthFactor >= 1e18, "不健康");
// 清算检查
require(healthFactor < 1e18, "无需清算");
// 份额非零
require(shares > 0, "份额为零");
// 金额非零
require(amount > 0, "金额无效");
// 储备金活跃
require(reserve.flags.active(), "储备金未激活");