基本概念

これらの概念を理解すると、Sai Keeper APIを使いやすくなります。

目次

• プロトコル概要
• データモデル
• 無期限先物取引
• 流動性プール
• オラクル
• 手数料体系
• ブロックと時刻

プロトコル概要

SaiはNibiru上の分散型無期限先物プラットフォームです。RustをWasmにコンパイルし、5つの主要コントラクトがすべての操作をオンチェーンで管理します。

主な構成：

• 無期限市場： 満期なしのレバレッジ取引。
• 流動性ボールト： 資金提供で利回りを得る。
• オラクル： 対応資産の価格フィード。
• 手数料： 透明な料金体系。

データモデル

階層

Query/Subscription
├── perp (Perpetuals)
│   ├── trades
│   ├── tradeHistory
│   └── borrowings
├── lp (Liquidity Pools)
│   ├── vaults
│   ├── deposits
│   └── withdrawRequests
├── oracle (Price Feeds)
│   ├── tokens
│   └── tokenPricesUsd
└── fee (Fee Analytics)
    ├── feeTransactions
    ├── feeDailyStats
    └── summaries

無期限先物取引

無期限先物とは？

無期限先物は満期なしで資産をレバレッジ取引できるデリバティブです。通常の先物と異なり、資金調達率の仕組み、Saiでは借入手数料と呼ばれます、によって現物価格との連動を保ちます。

取引の流れ

1. 新規： ロング・ショートを作成。
2. 保有中： 市場状況に応じた借入手数料を累積。
3. 決済：
   • 利用者の操作。
   • 利確、TP。
   • 損切り、SL。
   • 損失が基準を超えた清算。

基本概念

レバレッジ： ポジションサイズを倍率で増やします。

Position Value = Collateral × Leverage

ロングとショート：

• ロング： 上昇で利益。
• ショート： 下落で利益。

未決済建玉、OI： 未決済ポジションの総額。

• oiLong：ロングOI。
• oiShort：ショートOI。
• oiMax：OI上限。

借入手数料： OIの偏りに応じた時間当たりの料金。

• OIの多い側が高くなります。
• 多空の均衡を促します。
• APR換算は feesPerHour × 24 × 365 × 100。

取引の種類

• 成行、trade：現在価格で即時約定。
• 指値、limit：指定価格で約定。
• 逆指値、stop：指定水準で発動。

損益計算

Unrealized PnL = Position Value × (Current Price - Open Price) / Open Price

For Long:  PnL = positive when price increases
For Short: PnL = positive when price decreases

例：

• 担保$1,000、10倍ロングならポジション$10,000。
• 建値$50,000、現在$55,000。
• 損益は $10,000 × ($55,000 - $50,000) / $50,000 = $1,000、10%。

清算

損失が担保額に近づくと清算されます。

Liquidation Price (Long) = Entry Price × (1 - 1/Leverage + Maintenance Margin)
Liquidation Price (Short) = Entry Price × (1 + 1/Leverage - Maintenance Margin)

例、10倍と維持証拠金5%：

• $50,000のロングなら、約$47,500で清算。
• $50,000のショートなら、約$52,500で清算。

流動性プール

LPの仕組み

LPはボールトに資産を入れます。ボールトは：

• トレーダーの相手方になる。
• 取引手数料を得る。
• トレーダーの損失を収益にする。
• トレーダーの利益を支払う。

リスクと報酬:

• LPは手数料とトレーダーの損失の一部を得ます。
• トレーダーが利益を上げるリスクを負います。
• 純利益は revenueInfo に記録します。

ボールト指標

TVL： ボールトの総資産。

TVL = Available Assets + Assets in Open Positions

持分価格： 持分1単位の価値。

Share Price = Total Vault Value / Total Shares Outstanding

• 利益で上昇。
• 損失で低下。
• 初期価格は通常1.0。

APY： 年換算利回り。

APY = (Net Profit / TVL) × (365 / Epoch Duration Days) × 100

• 過去の収益から計算。
• 成績に応じて更新。
• 市場状況で変動。

入出金フロー

1. 入金： 資産を預けて持分を受け取ります。

   Shares Received = Deposit Amount / Current Share Price

2. 出金申請：

   • 次のエポックまで持分をロック。
   • unlockEpoch が出金時期を示します。
   • autoRedeem: true で自動償還。

3. 出金実行： エポック終了後に持分を償還します。

   • 価値は持分×現在の持分価格。

エポック

LP操作の期間です。

• 長さは epochDurationDays または epochDurationHours。
• 現在値は currentEpoch。
• 開始はUnix時刻。
• 即時出金攻撃を防ぎ、公平な価格を保ちます。

収益情報

各ボールトは詳しい収益指標を記録します。

• RevenueCumulative：全期間収益。
• NetProfit：収益から負債を引いた純利益。
• TraderLosses：トレーダー損失からの利益。
• ClosedPnl：決済済みの実現損益。
• CurrentEpochPositiveOpenPnl：現在の未実現利益。
• Liabilities：トレーダーの未実現利益への負債。
• Rewards：追加報酬。

オラクル

価格フィード

オラクルは各トークンの最新で信頼できる価格を提供します。

更新の仕組み:

• オラクルのバリデーターがオンチェーン更新。
• ブロック・時刻を記録。
• 複数ソースを集約。
• トークンによって数ブロックごとに更新。

トークン種類:

• Bank、TokenType.bank：Cosmos SDKコイン。
• ERC20、TokenType.erc20：Ethereum互換トークン。

価格の利用

鮮度を確認するため lastUpdatedBlock をチェックしてください。

{
  oracle {
    tokenPricesUsd(where: { tokenId: 1 }) {
      priceUsd
      lastUpdatedBlock {
        block
        block_ts
      }
    }
  }
}

推奨事項:

const ageSeconds = (Date.now() - new Date(lastUpdatedBlock.block_ts).getTime()) / 1000
if (ageSeconds > 60) {
  console.warn('Price may be stale')
}

手数料体系

手数料の種類

新規手数料、FeeType.OPENING：

• 新規時に徴収。
• サイズが基準。
• ボールト・ガバナンス部分。

決済手数料、FeeType.CLOSING：

• 決済時に徴収。
• サイズが基準。
• ボールト、ガバナンス、Keeper実行時のトリガー部分。

手数料の内訳

各手数料取引の内訳：

Total Fee = Vault Fee + Gov Fee + Trigger Fee

• ボールト： 最大部分、通常80〜90%。
• ガバナンス： 通常10〜20%。
• トリガー： 逆指値・指値実行報酬、該当時。

手数料内訳の例:

Position Size: $10,000
Opening Fee: 0.1% = $10
├─ Vault Fee: $8 (80%)
├─ Gov Fee: $2 (20%)
└─ Total: $10

手数料倍率

市場状況に応じた動的倍率です。

Actual Fee = Base Fee × Fee Multiplier

• 高い変動・リスクで増加。
• 通常1.0〜2.0倍。
• リスク時のLPを保護。
• 分析用に avgFeeMultiplier を記録。

不良債権

清算時に担保が足りない場合：

Bad Debt = Total Loss - Collateral Available

• 取引ごとに記録。
• プロトコル・ボールトが負担。
• 手数料分析で監視。
• 適切な管理ではまれに発生。

ブロックと時刻

ブロック構造

type Block {
  block: Int!         # Block height/number
  block_ts: Time!     # Block timestamp (RFC3339 format)
}

使い方：

• block：単調増加する連番。
• block_ts：読める時刻。
• 新規・決済・入金など重要イベントに含まれます。

Time型

Time スカラーはRFC3339形式の時刻です。

2024-11-03T10:30:00Z

時刻による絞り込み

期間指定には TimeFilter を使います。

{
  fee {
    feeTransactions(
      filter: {
        fromDate: "2024-01-01T00:00:00Z"
        toDate: "2024-01-31T23:59:59Z"
      }
    ) {
      id
    }
  }
}

ブロックとタイムスタンプの違い

• ブロック高： 決定的な連番で変わりません。
• 時刻： 読みやすい概算。生成間隔は変わることがあります。
• 多くのクエリが両方に対応します。

期間指定には時刻、厳密なイベント順にはブロックを使います。

主な用語

取引用語

• 担保： 新規作成に預ける資産。
• 証拠金： 無期限先物では担保と同じ意味。
• 清算： 損失基準を超える強制決済。
• 資金調達率： ロング・ショート間の定期支払い。Saiでは借入手数料と呼びます。
• マーク価格： 損益用のオラクル価格。
• 指数価格： オラクルの現物価格。

LP用語

• TVL： 総預かり資産。
• 持分価格： 持分トークン1単位の価値。
• エポック： LP操作の期間。
• APY： 年換算利回り。
• 収益： 手数料とトレーダー損失。

手数料用語

• 新規手数料： 新規作成時。
• 決済手数料： 決済時。
• 倍率： 基本手数料の動的倍率。
• 不良債権： 担保を超えた損失。

データの鮮度

• リアルタイム： イベント発生時に購読更新。
• クエリ遅延： 通常100ms未満。
• ブロック時間： Nibiruで約1〜2秒。
• オラクル： 通常数ブロックごと、資産により異なる。
• キャッシュ： 性能のため短時間保存する場合あり。

コントラクト構成

5つの主要Wasmコントラクトがあります。

1. Perp Manager： 無期限先物操作。
2. LP Vault： ポジションと出金。
3. Oracle： 価格。
4. Fee Manager： 手数料処理・分配。
5. Governance： パラメーター管理。

すべてRustで記述され、オンチェーンで動作します。

次のステップ

• 取引データは無期限先物API。
• 流動性はLP API。
• 価格はオラクルAPI。
• 手数料分析は手数料API。