無期限先物コントラクト

• 本ガイドではイベントは扱いません。
• 借入処理は借入手数料を参照してください。
• 手数料処理は./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)：同じ取引の追加情報ID。作成ブロックやスリッページ設定など。

型安全性を確保し、2・8バイトのキーを一貫して使えます。

コントラクト間連携

主な連携：

• オラクル、oracle_address
  • GetExchangeRate で基軸・決済資産の価格を取得。
  • 担保のUSD価格も取得。
• ボールト、VAULT_ADDRESSES
  • 一部決済、清算、退出で担保を送受信。
  • 利用者の証拠金入金を管理。

借入・手数料処理は直接組み込み、計算用の別execute呼び出しは行いません。一部の分配は 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を参照してください。