deepbook-move

DeepBook V3 Move 集成

**MCP 工具：**如果你的环境支持，也请查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），获取最新答案。请用它进行验证，并查找这些参考文件未涵盖的详细信息。

**来源限制：**此技能中的所有信息仅来自 docs.sui.io 和 deepbookv3 Move 源码。扩展或更新此技能时，只能从这些来源获取信息。请勿使用第三方博客、教程或非官方文档。

DeepBook V3 提供了 Move API，以实现链上可组合性——协议可以直接通过 Move 智能合约下单、执行交换、获取闪电贷并管理余额。此技能介绍 Move 层的合约接口。常见错误包括：调用交换或订单函数时使用了错误的 coin 类型参数、忘记归还闪电贷的烫手山芋，以及误解 TradeProof 授权模型。

此技能会引导你使用针对特定主题的参考文件。只加载与当前任务相关的文件。

此技能中的所有模式均源自： https://docs.sui.io/onchain-finance/deepbook/deepbookv3/contract-information https://docs.sui.io/onchain-finance/deepbook/deepbookv3/contract-information/balance-manager https://docs.sui.io/onchain-finance/deepbook/deepbookv3/contract-information/flash-loans https://docs.sui.io/onchain-finance/deepbook/deepbookv3/contract-information/swaps https://github.com/MystenLabs/deepbookv3/tree/main/packages/deepbook/sources

如果不确定某个函数签名，请在回答前获取相关源文件或文档页面。 请勿猜测，也不要根据其他协议进行推断。

---

参考文件

pool-api — 池与订单函数

路径： pool-api.md 在以下情况加载： 用户需要下单、创建池、查询池状态、管理治理，或了解 Pool Move API。 涵盖内容： 池创建、限价单和市价单下单、订单取消、池状态查询、治理函数、订单类型与常量、Move 依赖项设置。

balance-manager-api — BalanceManager Move API

路径： balance-manager-api.md 在以下情况加载： 用户需要从 Move 代码创建或与 BalanceManager 交互、铸造能力（TradeCap、DepositCap、WithdrawCap）、生成 TradeProof，或了解授权模型。 涵盖内容： BalanceManager 创建、能力铸造与撤销、存款和取款函数、TradeProof 生成、所有者与能力持有者授权模型、事件。

flash-loans — 闪电贷模式

路径： flash-loans.md 在以下情况加载： 用户想从池中借入资产并在同一笔交易中偿还，或需要了解闪电贷的烫手山芋模式。 涵盖内容： 借入基础资产和报价资产、FlashLoan 烫手山芋结构体、归还资产、限制与失败情况，以及完整示例。

---

相关技能

主题	技能	加载时机
架构、设计、合约地址	deepbook-overview/	了解 Pool/Book/State/Vault 设计、查询地址或池 ID
TypeScript SDK 交易	deepbook-sdk/	使用 SDK 构建交易机器人或脚本
Sui Move 基础知识	sui-move/	编写一般的 Move 代码——能力、TxContext、事件、coins
PTB 组合	ptbs/	在可编程交易块中组合 DeepBook 调用

---

路由指南

任务	加载
将 DeepBook 添加为 Move 依赖项	pool-api
创建新交易池	pool-api
从 Move 代码下单	pool-api
在链上查询交易池状态	pool-api
从 Move 创建 BalanceManager	balance-manager-api
铸造 TradeCap/DepositCap/WithdrawCap	balance-manager-api
生成用于交易的 TradeProof	balance-manager-api
了解授权模型	balance-manager-api
使用闪电贷	flash-loans
将 DeepBook 集成到协议中	pool-api + balance-manager-api
构建闪电贷策略	flash-loans + pool-api
完整的 Move 集成审查	所有参考文件

---

技能内容

关键概念

• TradeProof。 一种用于授权在交易池上交易的证明对象。可由 BalanceManager 所有者（通过 generate_proof_as_owner）或 TradeCap 持有者（通过 generate_proof_as_trader）生成。每次下单和取消订单都需要 TradeProof。

• Hot potato 模式（闪电贷）。 FlashLoan 结构体没有任何能力 — 不能存储、复制或丢弃。必须在同一笔交易中归还借入的资产来消耗它。若未归还，交易将失败。

• 交易池类型参数。 交易池函数对 <BaseAsset, QuoteAsset> 是泛型的。类型参数必须与交易池的币种类型完全匹配，否则调用会失败。

• Move 依赖项。 通过 MVR 将 DeepBook 添加到 Move.toml：deepbook = { mvr = "@deepbook/core" }。

规则

1. 始终精确匹配类型参数。 Pool<SUI, USDC> 与 Pool<USDC, SUI> 不同。基础资产和报价资产类型必须与创建交易池时的顺序一致。
2. 始终归还闪电贷 hot potato。 FlashLoan 结构体没有任何能力 — 未归还会导致交易中止。
3. 不要在同一笔交易中从某个交易池借款并在该交易池中交易。 借入的资金无法用于交易，这些操作组合在一起可能会失败。
4. 所有者操作使用 generate_proof_as_owner，通过 TradeCap 执行委托操作时使用 generate_proof_as_trader。
5. 能力数量上限：每个 BalanceManager 总计 1,000 个能力（TradeCap、DepositCap 和 WithdrawCap 合计）。在大规模场景中，此上限会限制单个 BalanceManager 可支持的委托交易者数量 — 如果需要超过 1,000 个委托账户，请规划使用多个 BalanceManager。
6. 对于提供 _v2 变体的函数，请使用 _v2 变体。 不带后缀的原始函数（例如 new_with_custom_owner_caps）是已弃用的桩函数，调用后会中止。请始终使用 _v2 后缀（例如 new_with_custom_owner_caps_v2）。

常见错误

• 类型参数顺序错误。 当交易池类型为 <SUI, USDC> 时传入 <USDC, SUI> 会导致类型不匹配错误。
• 忘记归还 FlashLoan。 交易可以通过编译，但会在运行时中止，因为 hot potato 不能被丢弃。
• 在借款的同一交易池中交易。 闪电贷资金被锁定在 FlashLoan 对象中，无法用于订单结算，导致交易失败。
• 从非所有者地址调用 generate_proof_as_owner。 只有 BalanceManager 所有者才能生成所有者证明。委托交易者必须使用有效的 TradeCap 调用 generate_proof_as_trader。
• 调用 generate_proof_as_trader 时忘记传入 ctx。 此函数接收 (balance_manager, trade_cap, ctx) — 省略 ctx: &TxContext 会导致编译错误。
• 调用已弃用的不带后缀的函数。 new_with_custom_owner_caps 等函数是会执行 abort 1337 的桩函数。请改用 _v2 变体。