位置数据维护

本文档描述 MoolahUserPosition 实体，以及为 Lista Lending 维护和消费该实体的各项服务。它是风险监控、清算预警、排放（奖励）与借款历史的数据基础。

---

1. 概述

MoolahUserPosition 是 Moolah 借贷协议中用户仓位的核心实体。它按「每个用户、每个市场」存储：

• 抵押品与借款数量

• 清算价格（或清算价格比）

• 相关标识符（链、市场、用户地址）

该实体支撑：

• 风险监控 — 追踪接近清算的仓位。

• 清算预警 — 识别达到或超过清算阈值的仓位并推送预警。

• 排放（奖励） — 按市场汇总抵押品，作为奖励分配的权重。

• 借款 / 利率统计 — 每日与每小时的借款与利率报表。

---

2. 实体定义

每个（用户地址，市场）组合有且仅有一条仓位记录。

典型字段（实际实现中的命名可能不同）：

字段	说明
userAddress	钱包地址
marketId	市场标识符（或等效字段）
chainId	链（例如 BSC、Ethereum）
collateralAmount	已提供的抵押品（可读格式，例如 18 位小数）
borrowShares	链上的借款份额（原始 Wei）
borrowedAmount	实际借款金额（由份额与市场状态推导）
liquidationPriceRatio	使该仓位变为可清算的抵押品/借款资产价格比
updatedAt	最后更新时间

---

3. 数据流

                    ┌───────────────┐
                    │ On-chain      │
                    │ contract      │
                    │ events        │
                    └──────┬────────┘
                           │
               ┌───────────▼───────────┐
               │ Event-driven write    │
               │ (incremental consume) │
               └───────────┬───────────┘
                           │ UPSERT
                           ▼
               ┌───────────────────────┐     ┌───────────────────┐
               │ moolah_user_position  │◄────│ Scheduled refresh  │
               │ (user position table) │UPDATE│ (debt + liq. rate) │
               └──────────┬────────────┘     └───────────────────┘
                          │ READ
          ┌───────────────┼────────────────────┐
          ▼               ▼                    ▼
  ┌───────────────┐ ┌──────────────┐  ┌─────────────────┐
  │ Borrow history│ │ Liquidation  │  │ Emission        │
  │ (daily/hourly)│ │ risk monitor │  │ reward calc     │
  └───────────────┘ └──────────────┘  └─────────────────┘

---

4. 数据写入

4.1 事件驱动写入

仓位数据通过消费 Moolah 的链上事件（supply、withdraw、borrow、repay、liquidate 等）进行更新。对每个相关事件：

1. 获取事件 — 使用游标（lastId）从事件存储中按序读取尚未处理的 Moolah 事件。

2. 读取链上状态 — 通过 multicall 查询当前市场状态、用户仓位与预言机价格。

3. 计算派生字段 — 根据市场的利率类型，计算实际借款金额与清算价格比。

4. 写入数据库 — 按 (userAddress, marketId)（如适用还包括 chainId）执行 UPSERT。

5. 写入操作日志 — 可选地写入用户操作日志表。

6. 触发预警 — 若该事件为清算事件，则触发 Telegram（或其他渠道）预警。

幂等性： 每个事件都会被追踪（例如使用 TTL 为 1500 秒的 Redis key），确保同一事件不会被重复应用。失败的事件会重试；达到最大重试次数后跳过并继续处理。

4.2 定时刷新

由于链上利息持续累积，即使没有新事件，借款金额与清算价格也会发生变化。定时任务会周期性刷新所有活跃仓位：

• 浮动利率市场 — 从链上读取当前利率，在本地计算已累积利息，再将份额换算为资产，得到当前借款金额与清算价格。

• 固定利率（Broker）市场 — 向 Broker 合约查询每个用户的总债务（getBrokerTotalDebt(borrower, market)），再计算清算价格。

---

5. 数据读取

5.1 借款历史

• 每日 — 基于仓位表（以及各类快照）计算每个用户的日均借款金额、抵押品与美元价值；写入每日借款历史表。

• 每小时 — 每小时将所有仓位快照写入小时级借款快照表。

5.2 清算风险监控

系统会周期性读取每个仓位的清算价格比，并与预言机提供的当前市场价格比做比较。当清算触发价格 > 当前市场价格（即仓位可被清算）时，生成风险摘要并发送预警（例如 Telegram）。

5.3 排放（奖励）

排放逻辑按市场汇总用户抵押品（取自仓位表），并以此作为奖励分配的权重。

---

6. 关联数据

• 市场配置 — 链、资产、预言机、LLTV、利率类型（浮动或固定）。

• 事件日志 — 用于重放与审计的原始合约事件。

• 用户操作日志 — 每个用户的操作历史（supply、borrow、repay 等）。

---

7. 关键概念

7.1 借款份额 vs 实际借款金额

• 借款份额是链上的表示形式，仅在用户操作（借款、还款、清算）时发生变化。

• 实际借款金额由份额与市场状态（总资产、总份额，固定利率场景下还可能包括 Broker 状态）推导得出，并随利息随时间增长。定时刷新任务负责保持该字段同步。

7.2 清算价格比

清算价格比是使该仓位变为可清算的抵押品/借款资产价格比。当预言机的当前价格比跌破该值时，该仓位即可被清算。它由抵押品、借款金额与该市场的 LLTV 推导得出。

7.3 多链

Moolah 运行在 BSC 与 Ethereum 上。仓位数据通常存储在单张表中并带有链标识符（例如 chainId），以便下游任务与 API 按链过滤。

---

8. 任务清单

任务	说明
事件消费者	消费 Moolah 事件并 UPSERT 仓位
定时刷新	刷新所有活跃仓位的借款金额与清算价格
借款历史（每日）	计算并存储每日借款/抵押品统计
借款快照（每小时）	为小时级统计对仓位做快照
清算监控	将清算价格与预言机价格比较并发送预警
排放汇总	按市场汇总抵押品作为奖励权重

---

9. 注意事项

• 精度： 抵押品与借款金额通常以可读形式存储（例如 18 位小数）；借款份额通常以原始 Wei 存储。

• 读写分离： 写入走主库；读取可走只读副本。为保证一致性需考虑复制延迟。

• 幂等性： 事件处理结合 Redis（或类似组件）与 UPSERT，确保同一事件不会被重复应用。

• 利率类型： 浮动利率与固定利率市场在借款金额与清算价格上使用不同公式；具体走哪条路径由市场配置决定。