核心概念

理解这些概念有助于使用 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

份额价格： 一份金库份额的价值。

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： 金库总锁仓价值。
• 份额价格： 一份代币的价值。
• 周期： 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。