Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ch03 DeepBookV3 总体架构

本章目标

  • 建立 DeepBookV3 的全局对象模型：Pool、Book、State、Vault、BalanceManager、Registry 分别承担什么职责。
  • 能从一次下单交易反推源码调用链、资金结算链和事件链。
  • 理解哪些状态集中在共享 Pool 上，哪些状态被抽象到 BalanceManager，以及这种拆分如何影响并发交易设计。
  • 能解释 DeepBookV3 与 DeepBook Margin、DeepBook Predict 的依赖边界，而不是把不同协议的借贷和预测市场状态混在一起。

本章学习阶梯

  • L2 先从一次下单的对象清单理解架构。
  • L3 追 Pool -> Book -> State -> Vault -> BalanceManager 的主调用链。
  • L4 解释版本、注册、capability 和对象借用如何影响真实交易。
  • L5 能画出协议升级或交易失败时的排查路径。

关键定义卡片

先看 Pool，不要急着进入撮合函数：

public struct Pool<phantom BaseAsset, phantom QuoteAsset> has key {
    id: UID,
    inner: Versioned,
}

public struct PoolInner<phantom BaseAsset, phantom QuoteAsset> has store {
    allowed_versions: VecSet<u64>,
    pool_id: ID,
    book: Book,
    state: State,
    vault: Vault<BaseAsset, QuoteAsset>,
    deep_price: DeepPrice,
    registered_pool: bool,
}

这段定义说明 DeepBookV3 的池不是“只有订单簿”。Pool 是外部 PTB 传入的共享对象，PoolInner 才是业务状态。book 管撮合，state 管账户、历史、费用和治理，vault 管真实资产，allowed_versions 管升级后的可用版本。读 place_limit_order 时要把这四个内部对象都带上，否则会误以为下单只是 Book 内部操作。

源码地图

小节目录

本章代码

  • code/s01-architecture-map/：从源码提取模块依赖关系，生成架构图输入。
  • code/s02-pool-object-query/：查询链上 Pool 对象字段，核对 PoolInner 中的 book/state/vault 结构。
  • code/s03-event-flow/：按交易 digest 解析 DeepBook 事件，复原一次下单的事件链。

Move 高阶穿插点

  • 读架构时先画对象借用图：哪些是 &mut shared object，哪些只是只读参数，哪些资源会被消费。
  • Versioned、Registry 和 capability 不是外围细节，它们决定生产环境升级、暂停和权限边界。
  • 把每个模块都绑定到一种 Move 状态迁移：创建、借用、写入、拆分、合并、销毁或事件发出。

常见错误

  • 错误：把 Pool 当成只包含订单簿的对象。实际 Pool 还包含 State、Vault、DeepPrice 和版本控制。
  • 错误：下单前只检查钱包 coin。实际订单资金来自 BalanceManager，必须检查 BalanceManager 余额和 TradeProof 权限。
  • 错误：认为 Book 负责费用和余额。Book 只负责撮合和挂单；费用在 State/OrderInfo 计算，资产在 Vault 结算。
  • 错误：把 DeepBookV3 闪电贷与 Margin 借贷混写。V3 闪电贷入口在 pool.move，底层是 vault.move 的 hot potato。
  • 错误：忽略版本开关。Pool::load_inner 和 Registry::load_inner 都可能因 package version 禁用而 abort。

本章检查清单

  • 能画出 Pool、Book、State、Vault、BalanceManager、Registry 的关系。
  • 能说出 place_limit_order 到 vault::settle_balance_manager 的完整调用链。
  • 能解释 Pool<BaseAsset, QuoteAsset> 中 base/quote 泛型的意义。
  • 能说明为什么 BalanceManager 是交易账户而不是钱包余额。
  • 能区分 DeepBookV3 闪电贷和 DeepBook Margin 借贷。

进阶练习

  • 练习 1：打开 pool.move，列出每个 public mutative 函数需要 mutable borrow 的对象，并判断它们的并发边界。
  • 练习 2：从 Registry::register_pool 出发，解释为什么反向交易对不能重复注册。
  • 练习 3：用一次部分成交订单，画出 OrderInfo、Fill、State、Vault 的状态变化表。