Core Concepts

Understanding these core concepts will help you effectively use the Sai Keeper API.

Table of Contents

• Protocol Overview
• Data Models
• Perpetual Trading
• Liquidity Pools
• Oracle System
• Fee Structure
• Blocks and Timestamps

Protocol Overview

Sai Protocol is a decentralized perpetual trading platform on Nibiru Chain. The protocol is implemented in Rust and compiled into WebAssembly (Wasm) bytecode, with 5 key contracts managing all operations fully on-chain.

Key components:

• Perpetual Markets: Trade with leverage without expiration dates
• Liquidity Vaults: Users provide liquidity to earn yield
• Oracle Prices: Reliable price feeds for all tradeable assets
• Fee System: Transparent fee structure for all operations

Data Models

Hierarchy

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

Perpetual Trading

What is a Perpetual?

A perpetual contract (perp) is a derivative that lets you trade an asset with leverage without an expiration date. Unlike futures, perpetuals use a funding rate mechanism (called borrowing fees in Sai) to keep prices anchored to spot prices.

Trade Lifecycle

1. Opening: Trader opens a position (long or short)
2. Active: Position accumulates borrowing fees based on market conditions
3. Closing: Position closed by:
   • User action
   • Take Profit (TP) trigger
   • Stop Loss (SL) trigger
   • Liquidation (if losses exceed threshold)

Key Concepts

Leverage: Multiply your position size

Position Value = Collateral × Leverage

Long vs Short:

• Long: Profit when price increases
• Short: Profit when price decreases

Open Interest (OI): Total value of open positions

• oiLong: Long positions open interest
• oiShort: Short positions open interest
• oiMax: Maximum allowed open interest

Borrowing Fees: Charged per hour based on OI imbalance

• Higher fees on the side with more open interest
• Helps balance long/short positions
• Converted to APR: feesPerHour × 24 × 365 × 100

Trade Types

• Market Trade (trade): Instant execution at current price
• Limit Order (limit): Execute when price reaches target
• Stop Order (stop): Trigger when price hits stop level

PnL Calculation

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

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

Example:

• Long 10x position with $1,000 collateral = $10,000 position value
• Entry: $50,000 | Current: $55,000
• PnL = $10,000 × ($55,000 - $50,000) / $50,000 = $1,000 (10%)

Liquidation

A position gets liquidated when losses approach the collateral amount:

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

Example (10x leverage, 5% maintenance margin):

• Long entry at $50,000 → Liquidation at ~$47,500
• Short entry at $50,000 → Liquidation at ~$52,500

Liquidity Pools

How LP Works

Liquidity Providers (LPs) deposit assets into vaults. These vaults:

• Serve as counterparty to traders
• Earn fees from trading activity
• Share profits when traders lose
• Cover losses when traders profit

Risk/Reward:

• LPs earn trading fees and a share of trader losses
• LPs bear the risk when traders are profitable
• Net profit tracked in revenueInfo

Vault Metrics

TVL (Total Value Locked): Total assets in the vault

TVL = Available Assets + Assets in Open Positions

Share Price: Value of one vault share

Share Price = Total Vault Value / Total Shares Outstanding

• Increases when vault is profitable
• Decreases when vault incurs losses
• Initial share price typically starts at 1.0

APY (Annual Percentage Yield): Annualized return

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

• Calculated from historical revenue
• Updates based on vault performance
• Can fluctuate with market conditions

Deposit/Withdrawal Flow

1. Deposit: User deposits → receives shares

   Shares Received = Deposit Amount / Current Share Price

2. Withdrawal Request: User requests withdrawal

   • Shares locked until next epoch
   • unlockEpoch indicates when withdrawal available
   • Can set autoRedeem: true for automatic redemption

3. Withdrawal Execution: After epoch ends

   • User redeems shares for assets
   • Value = Shares × Current Share Price

Epochs

Time periods for LP operations:

• Duration: Check epochDurationDays or epochDurationHours
• Current Epoch: Track with currentEpoch
• Epoch Start: Unix timestamp of epoch start
• Purpose: Prevents instant withdrawal attacks, ensures fair pricing

Revenue Info

Each vault tracks detailed revenue metrics:

• RevenueCumulative: Total revenue earned all-time
• NetProfit: Current net profit (revenue - liabilities)
• TraderLosses: Profits from trader losses
• ClosedPnl: Realized PnL from closed positions
• CurrentEpochPositiveOpenPnl: Current unrealized gains
• Liabilities: Current liabilities (trader unrealized profits)
• Rewards: Additional rewards received

Oracle System

Price Feeds

Oracle provides reliable, up-to-date prices for all tokens:

Update Mechanism:

• Prices updated on-chain via oracle validators
• Each update recorded with block number and timestamp
• Multiple price sources aggregated for accuracy
• Updates occur every few blocks (varies by token)

Token Types:

• Bank tokens (TokenType.bank): Native Cosmos SDK tokens
• ERC20 tokens (TokenType.erc20): Ethereum-compatible tokens

Using Prices

Always check lastUpdatedBlock to ensure price freshness:

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

Best Practice:

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

Fee Structure

Fee Types

Opening Fees (FeeType.OPENING):

• Charged when opening a position
• Based on position size
• Components: vault fee, gov fee

Closing Fees (FeeType.CLOSING):

• Charged when closing a position
• Based on position size
• Components: vault fee, gov fee, trigger fee (if triggered by keeper)

Fee Components

Every fee transaction breaks down into:

Total Fee = Vault Fee + Gov Fee + Trigger Fee

• Vault Fee: Goes to LP vault (largest portion, typically 80-90%)
• Gov Fee: Protocol governance fee (typically 10-20%)
• Trigger Fee: Reward for triggering stop/limit orders (if applicable)

Example Fee Breakdown:

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

Fee Multiplier

Dynamic multiplier based on market conditions:

Actual Fee = Base Fee × Fee Multiplier

• Higher multipliers during high volatility or risk periods
• Typical range: 1.0x to 2.0x
• Protects LP vaults during risky conditions
• Tracked in avgFeeMultiplier for analytics

Bad Debt

When a position is liquidated but collateral is insufficient:

Bad Debt = Total Loss - Collateral Available

• Bad debt is tracked per transaction
• Absorbed by the protocol/vault
• Monitored in fee analytics
• Rare occurrence with proper risk management

Blocks and Timestamps

Block Structure

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

Usage:

• block: Sequential number, increases monotonically
• block_ts: Human-readable timestamp
• Every important event (trade open/close, deposit, etc.) includes block info

Time Type

The Time scalar represents timestamps in RFC3339 format:

2024-11-03T10:30:00Z

Filtering by Time

Use TimeFilter for date ranges:

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

Block vs Timestamp

• Block height: Sequential, deterministic, never changes
• Timestamp: Human-readable, approximate (block times can vary)
• Most queries support both

Best Practice: Use timestamps for date ranges, blocks for precise event ordering.

Key Terminology

Trading Terms

• Collateral: Asset deposited to open positions
• Margin: Same as collateral in perpetuals context
• Liquidation: Forced position closure when losses exceed threshold
• Funding Rate: Periodic payment between longs and shorts (borrowing fees in Sai)
• Mark Price: Oracle price used for PnL calculations
• Index Price: Spot price from oracle

LP Terms

• TVL: Total Value Locked in a vault
• Share Price: Value of one vault share token
• Epoch: Time period for LP operations
• APY: Annual Percentage Yield
• Revenue: Earnings from trading fees and trader losses

Fee Terms

• Opening Fee: Fee charged when opening a position
• Closing Fee: Fee charged when closing a position
• Fee Multiplier: Dynamic multiplier applied to base fees
• Bad Debt: Losses exceeding available collateral

Data Freshness

• Real-time: Subscriptions provide live updates as events occur
• Query Latency: Typically <100ms for queries
• Block Time: ~1-2 seconds on Nibiru Chain
• Oracle Updates: Varies by token, typically every few blocks
• Cache: Some data cached briefly for performance

Smart Contract Architecture

Sai Protocol consists of 5 key Wasm contracts:

1. Perp Manager: Handles perpetual trading operations
2. LP Vault: Manages positions and withdrawals
3. Oracle: Provides price feeds
4. Fee Manager: Processes and distributes fees
5. Governance: Protocol parameter management

All contracts are fully on-chain and written in Rust for security and performance.

Next Steps

• Learn about Perp API for trading data
• Explore LP API for liquidity pool data
• Check Oracle API for price feeds
• Understand Fee API for fee analytics