Core Concepts This page explains the fundamental concepts you need to understand when working with Sera.
Price Indices Sera uses an Arithmetic Price Book where prices are represented as indices rather than raw values. This provides:
Gas-efficient storage (uint16 vs uint256)
Predictable price levels
Easy price level iteration
price = minPrice + (tickSpace × priceIndex)
Parameter Description minPriceThe minimum price supported by the market tickSpaceThe spacing between each price level priceIndexAn integer from 0 to 65,535 (uint16)
Example For a market with minPrice = 0.001 and tickSpace = 0.00001:
Price Index Actual Price 0 0.001000 100 0.002000 500 0.006000 1000 0.011000
Converting Between Price and Index Price → Index: // Get the index for a target price const { index , correctedPrice } = await priceBook . priceToIndex ( targetPrice , false // roundingUp: false for bids, true for asks );
Index → Price: const price = await priceBook . indexToPrice ( priceIndex );
Raw Amounts vs Token Amounts Sera uses “raw amounts” internally for gas efficiency. Understanding the conversion is crucial.
Quote Unit Each market has a quoteUnit that defines how many quote tokens equal one “raw unit”:
rawAmount = quoteAmount / quoteUnit quoteAmount = rawAmount × quoteUnit
Conversions Conversion Formula Raw → Quote quoteAmount = rawAmount × quoteUnitQuote → Raw rawAmount = quoteAmount / quoteUnitRaw → Base baseAmount = rawAmount × quoteUnit / priceBase → Raw rawAmount = baseAmount × price / quoteUnit
Example For a market with quoteUnit = 1000000 (6 decimals):
// You want to buy 100 USDC worth const quoteAmount = 100_000000 n ; // 100 USDC (6 decimals) const rawAmount = quoteAmount / 1000000 n ; // = 100 raw units
Order Types Limit Orders Limit orders sit on the order book until filled or cancelled.
Parameter Bid (Buy) Ask (Sell) priceIndexMaximum price willing to pay Minimum price willing to receive rawAmountQuote tokens to spend Not used (set to 0) baseAmountNot used (set to 0) Base tokens to sell postOnlyIf true, order fails if it would fill immediately Same
Market Orders Market orders execute immediately against existing orders.
Parameter Bid (Buy) Ask (Sell) limitPriceIndexMaximum price willing to pay Minimum price willing to receive rawAmountMax quote to spend (expendInput) / Min quote to receive (!expendInput) Min quote to receive (expendInput) / Max quote to spend (!expendInput) baseAmountMin base to receive (expendInput) / Max base to spend (!expendInput) Max base to spend (expendInput) / Min base to receive (!expendInput) expendInputIf true, spend all input tokens Same
Order Lifecycle ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Create │────▶│ Open │────▶│ Filled │────▶│ Claimed │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ▲ │ ┌──────────┐ │ └──────────▶│ Cancelled │ │ └──────────┘ │ │ │ └───────────────┘
Status Description openOrder is on the book, waiting to be filled filledOrder has been completely filled, proceeds ready to claim partialOrder is partially filled cancelledOrder was cancelled by the owner claimedProceeds have been claimed
Fees Sera uses a maker-taker fee model:
Fee Type Description Typical Value Taker Fee Paid by the party that takes liquidity 0.1% (10 bps) Maker Fee Paid/received by the party that provides liquidity -0.05% (rebate)
Negative maker fees mean makers receive a rebate for providing liquidity. For testnet, all fees are set to 0.
Fee values are stored as basis points × 100:
1000 = 0.1% = 10 bps-500 = -0.05% = 5 bps rebate
Order NFTs Each limit order creates an NFT representing ownership. This enables:
Transferability : Transfer order ownership to another addressComposability : Use orders in other DeFi protocolsClaim Delegation : Anyone holding the NFT can claim proceeds
// Get the NFT ID from an order const nftId = order . nftId ; // Transfer order ownership await orderNFT . transferFrom ( owner , newOwner , nftId );
Next Steps
Smart Contracts Explore the contract interfaces
Query Markets Fetch market data via GraphQL
