永续交易合约

• 本指南不涵盖事件。
• 借贷逻辑见借贷费用。
• 费用逻辑见 ./fees/README.md。
• 价格影响见价格影响模块。
• 非交易时段杠杆见非交易时段杠杆。

---

目录

• 永续交易合约
  • 目录
  • 概述
  • 仓库结构
  • 核心概念
    • 交易生命周期
    • 合约入口
    • 索引类型
    • 合约间交互
  • 消息
  • 详细交易流程
    • 开仓
    • 平仓
    • 修改交易
  • 附加模块
    • 借贷参考
    • 费用参考
    • 价格影响参考
  • 补充说明

---

概述

该合约在 CosmWasm 中实现永续合约交易：

• 开立和平仓多空杠杆仓位。
• 限价及止损入场单。
• 动态更新止损 SL、止盈 TP。
• 通过增减抵押资产或杠杆部分修改仓位。
• 对跨收盘持仓实施非交易时段杠杆控制。
• 自动累积借贷费用。
• 动态计算费用。
• 按 OI 调整价格影响。

---

仓库结构

主要文件和目录：

• ./contract.rs
  • 实例化、迁移和执行的顶层入口。
  • 分发 ExecuteMsg::Admin { .. }。
• ./msgs.rs
  • 定义公开 ExecuteMsg 和特权操作 AdminExecuteMsg。
• ./trade.rs、./update_position_size.rs、./exec_update_leverage.rs
  • 管理开平仓、部分平仓、SL/TP、杠杆更新和非交易时段归一化。
• ./borrowing/
  • 参考。
  • 借贷结构、OI 追踪和费用累积。
• ./fees/
  • 参考。
  • 费用计算、等级逻辑和金库分配。
• ./price_impact/
  • 参考。
  • 大额交易的价格变动及滑点。
• ./trading/state.rs、./trading/utils.rs
  • Trade、TradeInfo、TradingActivated 等核心状态。
  • 验证、订单检查、滑点和敞口限制辅助方法。

还会引用以下部分。

• borrowing、fees、price_impact、pairs、trading 各有独立目录。
• keys.rs 包含 MarketIndex、TokenIndex 等类型化索引。
• entry.rs 汇集开平仓等入口操作。

---

核心概念

交易生命周期

1. 开仓
   • 创建包含杠杆、抵押资产、方向的 Trade，收取开仓费。
2. 持仓
   • 随时间累积借贷费用。
   • 市场变化影响未实现盈亏，平仓时才实现。
3. 平仓
   • 撤销 OI 影响，结清费用，返还抵押资产或将亏损分配给金库。
4. 止损入场、限价、TP、SL
   • 保存待成交订单及止损止盈条件。
   • 通常由链下 Keeper 调用 TriggerTrade。

合约入口

• instantiate：初始化所有权、预言机引用和 OI_WINDOWS_SETTINGS 默认设置。
• execute：分发 ExecuteMsg，区分普通和管理操作。
• migrate：合约升级逻辑。

索引类型

./keys.rs 定义存储使用的类型化索引。

• MarketIndex(u16)：市场或交易对的唯一 ID。
• GroupIndex(u16)：借贷费用分组的市场组。
• TokenIndex(u16)：抵押代币。
• UserTradeIndex(u64)：用户内唯一交易 ID。
• TradeInfoIndex(u64)：该交易的附加信息索引，如创建区块、滑点设置。

这些索引保证类型安全，并统一使用 2 或 8 字节存储键。

合约间交互

主要交互：

• 预言机，oracle_address
  • 查询 GetExchangeRate，获取基础资产与报价资产价格。
  • 获取抵押资产的 USD 价格。
• 金库，VAULT_ADDRESSES
  • 部分平仓、强平、退出时收发抵押资产。
  • 管理用户保证金充值。

合约直接整合借贷和费用逻辑，不为计算单独执行调用。部分分配仍使用 BankMsg::Send 或金库的 ExecuteMsg::ReceiveAssets。

---

消息

用户命令位于 ./msgs.rs，全部参数见该文件。

• OpenTrade { market_index: MarketIndex, leverage: Decimal, long: bool, ... }：按指定参数新开仓。
• CloseTrade { trade_index: UserTradeIndex }：按市价平仓。
• UpdateOpenLimitOrder { trade_index, price, tp, sl, slippage_p }：修改未成交限价单的价格和 SL/TP。
• TriggerTrade { trader: String, trade_index: UserTradeIndex, order_type: PendingOrderType }：条件成立时触发限价、止损入场、TP、SL、强平，也可路由到符合条件的留仓归一化。
• UpdateLeverage { trade_index, new_leverage }：通过增减抵押资产调整杠杆。
• IncreasePositionSize / DecreasePositionSize：部分修改规模或增减抵押资产。

AdminExecuteMsg 管理操作包括：

• SetMarkets 设置市场。
• 更新预言机和金库地址。
• 配置费用和借贷组。
• 用 UpdateAfterHours 配置非交易时段控制。
• 提取协议资金。
• 切换暂停和交易启用状态。

这些管理消息引用以下逻辑。

• 借贷管理操作
• 费用管理操作
• 价格影响管理操作

---

详细交易流程

开仓

1. 用户使用以下参数调用 ExecuteMsg::OpenTrade。

   OpenTrade {
       market_index: MarketIndex(0),
       leverage: Decimal::from_str("5.0")?,
       long: true,
       collateral_index: TokenIndex(1),
       trade_type: TradeType::Trade,
       open_price: Decimal::from_str("1000")?,
       tp: Some(...),
       sl: Some(...),
       slippage_p: Decimal::from_str("0.03")?,
   }

2. 消息须附带 collateral_index 对应的资金。

3. 合约：

   • 从 info.funds 获取充值。
   • 验证杠杆、最低抵押资产、敞口限制、滑点等。
   • 收取开仓费。
   • 使用借贷逻辑追踪 OI。
   • 保存到 TRADES[(User, UserTradeIndex)]。

平仓

1. 调用 CloseTrade { trade_index }。
2. 合约：
   • 更新最终借贷和平仓费。
   • 返还剩余抵押资产；亏损超过存储金额时向用户收取更多。
   • 从借贷存储移除 OI。
   • 在 TRADES 删除或标记为已平仓。

修改交易

持仓期间可用的修改消息：

• TriggerTrade { order_type: PendingOrderType }：通常由 Keeper 调用，激活限价和止损入场、执行 SL/TP 或强平，或按合约判断进行非交易时段归一化。
• UpdateOpenLimitOrder：修改未触发订单的价格、SL、TP 等。
• UpdateTp / UpdateSl：调整已开仓交易的止盈止损边界。
• UpdateLeverage { new_leverage }：增减杠杆。降低杠杆须追加抵押资产；提高杠杆会返还抵押资产。

内部会重新计算费用、检查强平价，并按需更新借贷 OI。

设有非交易时段控制的市场，在更新杠杆、SL/TP 或增加规模前先落实归一化。见非交易时段杠杆。

---

附加模块

高级逻辑参考：

借贷参考

./borrowing/README.md 介绍：

• 随时间累积借贷费。
• 组或交易对级的 OI 上限。
• 每笔交易用 BorrowingPairGroup 引用组变更历史。

费用参考

./fees/README.md 介绍：

• 开仓、平仓、部分平仓、触发和强平的费用。
• 治理、触发奖励和金库之间的分配。
• 高交易量用户的等级折扣。

价格影响参考

./price_impact/README.md 介绍：

• PAIR_DEPTHS 设置交易对上下方向的 1% 深度。
• 大额交易的成交价惩罚或改善。
• 时间窗口 OI 平滑短期尖峰。

---

补充说明

• 所有权： 通过 nibiru-ownable 的 UpdateOwnership 管理消息更新。
• 验证： 多模块检查，防止负敞口或抵押资产不足。
• 扩展： 可沿用类型化存储、滑点检查、借贷和费用钩子，增加消息或费用逻辑。

以上为核心永续合约逻辑。详细计算见 ./borrowing、./fees、./price_impact 中的 README。