ch12 DeepBook SDK 集成专题

本章目标

官方 DeepBookV3 SDK 文档把 @mysten/deepbook-v3 定位为 TypeScript 集成层：它抽象交易调用、维护 coins/pools/managers 的 key-value 配置，并通过 Sui TypeScript SDK 构造和提交交易。本章在此基础上继续往工程化推进：不仅要会调用 SDK，还要知道 SDK 背后的 Move 入口、对象 ID、type arguments、dry run 和错误定位。

本章把前面章节中的 Move 合约能力落到应用工程：用 @mysten/deepbook-v3、Sui SDK 和 PTB 把 DeepBook Spot、Margin、Predict 的核心交易封装成可复用服务。目标不是堆 API 清单，而是建立一套生产应用可以采用的 SDK 边界：配置集中管理、交易只构造不托管私钥、提交前 dry run、失败后能解析错误并定位到 Move 入口。

本章代码放在 book/ch12/code/，每个目录都是可以扩展成 TypeScript 工程的骨架。

本章学习阶梯

L1 先安装 SDK、连接 RPC、读取配置。
L2 查询池子、资产、BalanceManager 和对象状态。
L3 封装限价单、市价单、swap、撤单、Margin 和 Predict 交易。
L4 加入 dry run、错误解析、钱包签名和后端安全构造交易。

关键定义卡片

SDK 封装的目标不是隐藏 Move，而是稳定翻译 Move 签名。比如 BalanceManager 操作背后是：

public fun new(ctx: &mut TxContext): BalanceManager
public fun deposit<T>(balance_manager: &mut BalanceManager, coin: Coin<T>, ctx: &mut TxContext)
public fun withdraw<T>(
    balance_manager: &mut BalanceManager,
    withdraw_amount: u64,
    ctx: &mut TxContext,
): Coin<T>
public fun generate_proof_as_owner(
    balance_manager: &BalanceManager,
    ctx: &TxContext,
): TradeProof

所以 SDK 服务层必须保存三类信息：对象 ID、类型参数、资源输入输出。只暴露 placeLimitOrder() 这种名字不够，错误发生时要能打印出 pool id、manager id、coin type、price/quantity 原始整数、dry run error 和对应 Move 入口。

源码地图

Sui Docs: DeepBookV3 SDK：安装、constants、DeepBookClient、BalanceManager key、pool/coin/manager 配置和示例代码。
scripts/config/constants.ts：主网、测试网的 admin cap、margin cap、supplier cap、market maker 地址等配置来源。
scripts/transactions/deepbookMarketMaker.ts：继承 DeepBookClient，封装 keypair、SuiClient、签名提交、限价单和闪电贷 PTB。
scripts/transactions/createPool.ts：用 SuiGrpcClient().$extend(deepbook(...)) 初始化 SDK，并调用 deepBookAdmin.createPoolAdmin。
scripts/transactions/prepBalanceManager.ts：配置 balanceManagers，调用 balanceManager.createAndShareBalanceManager。
scripts/transactions/marginPrep.ts、supplyToMarginPool.ts、enableMarginVersion.ts：Margin admin、maintainer、supplier 侧 SDK 调用。
scripts/utils/utils.ts：读取 signer、设置 gas payment、dryRunTransactionBlock、生成 multisig 交易 bytes。
packages/deepbook/sources/pool.move：Spot 交易入口，例如 place_limit_order、place_market_order、swap_exact_base_for_quote、cancel_order、borrow_flashloan_base。
packages/deepbook/sources/balance_manager.move：BalanceManager、deposit、withdraw、cap 和 trade proof。
packages/deepbook_margin/sources/margin_manager.move：Margin 用户入口，例如 deposit、withdraw、borrow、repay、条件单和风险查询。
packages/deepbook_margin/sources/margin_pool.move：Margin 资金池 supply、withdraw、费用和利率状态。
packages/predict/sources/predict.move、predict_manager.move、registry.move：Predict 当前 Move 层入口。Predict 需要按实际发布网络和对象 ID 标注，不应把迁移中的能力写成稳定主网接口。

小节目录

本章代码

book/ch12/code/s01-sdk-init/：SDK 初始化模板。
book/ch12/code/s02-deepbook-service/：Spot 服务封装。
book/ch12/code/s03-margin-service/：Margin 服务封装。
book/ch12/code/s04-predict-service/：Predict 服务封装。
book/ch12/code/s05-wallet-flow/：前端钱包交易流程。
book/ch12/code/s06-dry-run-helper/：dry run 和错误解析工具。

Move 高阶穿插点

SDK 集成的本质是把 Move 函数签名翻译成类型安全的交易构造器。
每个 wrapper 都应保留 type arguments、object ids、coin 输入输出和 dry run 结果，方便定位失败。
不要让 SDK 隐藏关键资源语义；用户至少要知道哪些对象被 mutably borrowed，哪些 coin 被消费。

常见错误

只复制官方 SDK 示例，不补 dry run、错误解析、钱包签名和对象版本刷新。
把主网对象 ID 用在测试网交易中。
前端要求用户导出私钥，而不是调用钱包签名。
忽略 BalanceManager 所有权和 cap，导致交易 dry run 通过不了。
只检查 SDK 抛错字符串，不解析 effects.status.error。
Predict 未标注网络和版本状态，把迁移中的接口写成稳定接口。
管理员交易不设置 expiration 和固定 gas payment，导致 multisig 流程不可复现。

本章检查清单

所有服务初始化都能明确 network、rpcUrl、address。
所有 cap、pool、manager、registry 对象 ID 都来自配置层。
用户交易返回 PTB 或 bytes，不要求后端托管私钥。
每个写交易都有 dry run 和错误解析路径。
Margin 交易检查 oracle、风险率和版本。
Predict 交易标注 package/object IDs、网络和版本状态。

进阶练习

为 DeepBookService 增加 route swap，并在 dry run 后校验最小输出。
为 MarginService 增加 borrowAndPlaceLimitOrder 组合 PTB。
为 PredictService 增加 quote 缓存和 oracle stale 检查。
用 fixture 写一个 dry run 错误解析测试表，覆盖 Move abort、对象不存在、余额不足和 gas 不足。

Keyboard shortcuts

DeepBook 开发权威指南