ch10 DeepBook Predict 协议源码精读

本章目标

官方文档把 DeepBook Predict 定位为 Sui 上基于到期日的预测市场协议，并明确当前公共集成目标是 Testnet。它支持 binary positions、vertical ranges、oracle-driven prices、PredictManager、Vault liquidity 和 PLP LP shares。本章必须先把这个网络状态说清楚，再进入源码。

读完本章，读者应该能从源码层面解释 DeepBook Predict 的核心对象、交易入口、资金路径、oracle 生命周期、vault 风险和 LP 份额，并能区分：官方 Testnet 集成面、public Predict server 数据面、本书锁定 GitHub 源码快照，以及未来 Mainnet 部署前可能变化的部分。

本章使用的源码快照位于 packages/predict。官方文档当前指出 Predict 来自 predict-testnet-4-16 分支，公共集成目标在 Sui Testnet；因此本书不能把 package IDs、object layouts、entry points 或 public server 行为写成永久主网事实。

官方集成基线

Predict 应用不是只读链，也不是只读 server。官方推荐的集成模型可以整理成三层：

数据来源	适合场景	本书展开
Public Predict server	页面渲染、市场列表、portfolio、vault summary、历史数据	ch11、ch13 会把它当作读模型和产品数据源。
Sui checkpoint / event streaming	需要低延迟 oracle 更新的页面或策略	ch10-05、ch10-12 讲 oracle event 和 freshness。
Direct onchain object reads	钱包交易前后需要确认关键状态	ch10 源码章和 ch12 SDK 章都会保留直接对象读取路径。

版本旁白：Predict 是本书里最需要标注版本状态的章节。写法上要避免“源码里有函数，所以产品已经稳定”的推断；官方 Testnet 文档、public server、源码分支和本地锁定提交必须分别说明。

本章学习阶梯

L2 先理解 Predict 的产品模型：区间、到期、oracle、LP vault。
L3 读 predict.move、manager、vault、pricing、risk 和 fee reserve。
L4 能解释 mint、redeem、settle、withdraw 的状态变化。
L5 能判断 Predict 当前网络/版本边界和可产品化范围。

关键定义卡片

Predict 的核心对象不是订单簿，而是预测市场共享状态：

public struct Predict has key {
    id: UID,
    vault: Vault,
    fee_reserve: FeeReserve,
    treasury_cap: TreasuryCap<PLP>,
    pricing_config: PricingConfig,
    risk_config: RiskConfig,
    treasury_config: TreasuryConfig,
    oracle_config: OracleConfig,
    withdrawal_limiter: RateLimiter,
    trading_paused: bool,
}

这段定义说明 Predict 的主线是 vault 风险、oracle、pricing 和 LP 份额，不是 price level 撮合。trading_paused 是全局交易开关，withdrawal_limiter 约束 LP 退出，fee_reserve 把 LP、协议和保险费用从 vault 价值中拆出来。

核心交易入口：

public fun mint<Quote>(
    predict: &mut Predict,
    manager: &mut PredictManager,
    oracle: &OracleSVI,
    key: RangeKey,
    quantity: u64,
    clock: &Clock,
    ctx: &mut TxContext,
)

public fun redeem<Quote>(
    predict: &mut Predict,
    manager: &mut PredictManager,
    oracle: &OracleSVI,
    key: RangeKey,
    quantity: u64,
    clock: &Clock,
    ctx: &mut TxContext,
)

mint 和 redeem 都需要 PredictManager、oracle、range key、clock 和 quote 类型。应用开发时如果只展示“买入/卖出”按钮，而不展示 oracle 状态、区间、到期和费用，就解释不了交易为什么失败。

源码地图

packages/predict/sources/predict.move：Predict 共享对象、交易入口、LP 入口、配置读写和事件。
packages/predict/sources/registry.move：Registry、AdminCap、创建 Predict、创建 Oracle、创建 PredictManager、配置管理入口。
packages/predict/sources/predict_manager.move：用户资金账户和头寸表，内部包裹 DeepBook BalanceManager。
packages/predict/sources/oracle.move：SVI oracle、Pyth Lazer spot、basis、结算价格和二元定价输入。
packages/predict/sources/oracle_config.move：strike grid、ask bounds、basis bounds、asset -> Pyth Lazer feed id。
packages/predict/sources/vault/vault.move：LP vault 余额、区间敞口、MTM 和最大赔付。
packages/predict/sources/vault/plp.move：Predict LP token，6 位精度。
packages/predict/sources/market_key/range_key.move：市场 key，表示 (oracle, expiry, lower, higher]。
packages/predict/sources/config/pricing_config.move：base fee、min fee、utilization multiplier、ask price bound。
packages/predict/sources/config/risk_config.move：总敞口百分比和 MTM 新鲜度。
packages/predict/sources/config/treasury_config.move：quote asset 白名单和 6 位精度校验。
packages/predict/sources/accounting/fee_reserve.move：LP、protocol、insurance fee reserve 拆分。
packages/predict/sources/helper/strike_matrix.move：固定 strike 网格下的区间库存、MTM 和 worst-case payout。
packages/predict/sources/helper/rate_limiter.move：LP 提款 token bucket 限速器。
packages/predict/tests：当前测试覆盖 fee reserve、pricing config、rate limiter、oracle cap，迁移文档计划中的端到端 Predict 测试尚不能视为已完成。

小节目录

本章代码

book/ch10/code/s01-predict-source-map/：生成 Predict 模块依赖图。
book/ch10/code/s02-market-key-builder/：构造 RangeKey 所需参数。
book/ch10/code/s03-pricing-calculator/：实现简化 fee 计算器。
book/ch10/code/s04-vault-accounting/：模拟 Predict vault、PLP、fee reserve 和 payout 的账本变化。

Move 高阶穿插点

Predict 是学习 Move 定价型协议的案例：头寸不是普通订单，而是区间、到期、oracle 和 vault 风险的组合。
读配置模块时区分全局参数、单 oracle override、资产级边界和管理员权限。
事件不仅服务历史展示，也服务用户理解费用、赎回、结算和 LP 份额变化。

常见错误

把 Testnet integration surface 写成 Mainnet 稳定能力。
把旧 Predict 实验 package ID 或本地脚本配置写进正文，覆盖官方当前 contract information。
把 quote fee 当成 bps；源码中它是每单位绝对价格增量。
只用 strike 和方向当市场 ID，忽略 oracle ID 与 expiry。
LP 页面只展示 vault balance，不展示 MTM、max payout 和 withdrawal limiter。
把 settled redeem 写成收费交易；源码中 settled redeem 是 zero-fee。
把 Predict vault 误写成 DeepBookV3 spot pool 或 MarginPool。

本章检查清单

能解释 Predict、Registry、PredictManager、OracleSVI、Vault、PLP 的对象关系。
能写出 mint 的资金路径：manager withdraw、fee split、vault accept payment、position increase。
能解释 live redeem 与 settled redeem 的区别。
能说明 RangeKey 为什么必须包含 oracle 和 expiry。
能说明 pricing config 与 risk config 分别控制什么。
能区分本书采用的 GitHub 源码快照能力和迁移计划未完成事项。

进阶练习

设计一个 SUI 价格 UP/DOWN 市场，写出 oracle asset、feed id、expiry、strike grid、两个 RangeKey。
给定 vault balance、total MTM、max payout 和 fee 参数，计算 LP 当前 NAV 与用户 mint 的 all-in cost。
为 Predict 设计最小事件索引表，至少覆盖 market、oracle update、position、LP share 和 fee accrual。

Keyboard shortcuts

DeepBook 开发权威指南