Glossary#

Terminology and definitions for the Seesaw protocol.

A#

Ask#

An offer to sell shares at a specified price. In Seesaw, all asks are stored as YES share asks in the canonical order book.

Atomic#

An operation that either fully succeeds or fully fails, with no partial state changes. All Seesaw instructions are atomic.

B#

Basis Point (bps)#

One hundredth of a percentage point. 100 bps = 1%, 10,000 bps = 100%. Seesaw uses basis points for all price representation.

Best Ask#

The lowest price at which someone is willing to sell. Represented as best_ask_price in the orderbook.

Best Bid#

The highest price at which someone is willing to buy. Represented as best_bid_price in the orderbook.

Bid#

An offer to buy shares at a specified price. In Seesaw, all bids are stored as YES share bids in the canonical order book.

Binary Market#

A market with exactly two possible outcomes. In Seesaw, these are UP (price increased) or DOWN (price decreased).

BPF (Berkeley Packet Filter)#

The virtual machine used by Solana to execute on-chain programs. Seesaw is compiled to BPF.

C#

Canonical Order Book#

The single internal representation of all orders as YES share orders. NO orders are converted to equivalent YES orders.

Closer Reward#

A SOL bounty (DEFAULT_CLOSER_REWARD_LAMPORTS = 200,000 lamports) paid from market rent to the caller who successfully completes a lifecycle transition: snapshot_end, resolve_market, expire_market, force_close, or close_market. Five rewards are pre-funded per market at creation (CLOSER_REWARDS_PER_MARKET = 5). Incentivizes permissionless crank operators to keep markets progressing without the protocol owning any infrastructure.

Collateral#

The USDT (or other settlement currency) locked to back positions. Full collateralization ensures the protocol can always pay out.

Confidence Interval#

The Pyth oracle's uncertainty range for a price. Markets may optionally reject prices with wide confidence intervals.

Crank#

A permissionless operation that advances protocol state, such as creating markets or capturing price snapshots. Anyone can run a crank.

Crossed Book#

An invalid state where the best bid is >= the best ask. Seesaw prevents this condition.

D#

Discriminator#

An 8-byte prefix that identifies the account type. Used to prevent account confusion attacks.

Dual-View Single Engine#

Seesaw's order book design where users see four order types (BuyYes, SellYes, BuyNo, SellNo) but internally all orders are stored as YES orders.

E#

Epoch#

A time window during which a single market operates. Durations are configurable from 60 seconds to 7 days (default: 15 minutes). Each epoch has a unique market ID.

Expiry#

The deadline after which a market can be force-closed if not properly resolved. Set to 7 days after the epoch ends (MARKET_EXPIRY_WINDOW = 604,800 s).

F#

Fill#

A trade execution where a taker's order matches against a maker's resting order.

Free Funds#

Settlement tokens or share credits held in a trader's TraderLedgerAccount slot rather than in their external wallet. Used by the *WithFreeFunds instructions (swap_with_free_funds 0x0D, place_limit_order_with_free_funds 0x0E, place_multiple_post_only_orders_with_free_funds 0x0F, cancel variants 0x15–0x18). deposit_funds (0x08) moves tokens into the ledger; withdraw_funds (0x09) moves them back out. Free funds reduce per-trade transaction overhead for active market makers.

Force Close#

An emergency mechanism to close markets that are stuck. Available after the expiry window.

Full Collateralization#

The requirement that every share is backed by exactly 1 USDT in the vault. This ensures the protocol is always solvent.

G#

Governance#

The mechanism for updating protocol parameters. Currently controlled by protocol authority.

H#

Health Check#

A system to verify the protocol and crank infrastructure are operating correctly.

I#

Idempotency#

The property that an operation can be safely repeated without changing the result. All crank operations are idempotent.

Immediate-Or-Cancel (IOC)#

An order type that executes whatever quantity is possible immediately and cancels the remainder. Use order_type = 2 in PlaceOrderArgs. A worst_acceptable_price_bps guard limits how far the fill price may deviate from the specified price (SlippageExceeded, 0x3007).

Invariant#

A condition that must always be true. Violating an invariant indicates a bug or attack.

K#

Keypair#

A public/private key pair used for signing transactions. Crank operators need a funded keypair.

L#

Limit Order#

An order that specifies a maximum buy price or minimum sell price. Unfilled portions rest on the order book.

Liquidity#

The availability of orders on the book. More liquidity means tighter spreads and better execution.

Locked Shares#

Shares committed to open sell orders. Locked shares cannot be sold again until the order is cancelled or filled.

Locked Collateral#

USDT committed to open buy orders. Locked collateral cannot be used for other orders.

M#

Maker#

A trader whose order rests on the order book before execution. Makers pay zero taker fee.

Market#

A prediction market for a single epoch. Each market predicts whether the underlying asset's price will go UP or DOWN within its configured duration.

Market ID#

A unique identifier for a market, calculated as floor(unix_timestamp / duration_seconds). Example: 1892160 (for a 15-minute market).

Matching Engine#

The component that pairs buy and sell orders and executes trades.

Mid Price#

The average of the best bid and best ask. Used to estimate the market's implied probability.

N#

Naked Short#

Selling shares you don't own. Prohibited in Seesaw - you can only sell shares in your position.

NO Share#

A share that pays out 1 USDT if the market resolves to DOWN (price strictly decreased: P_end < P_start). Note: if the price is unchanged, the outcome is UP and YES shares win.

O#

Oracle#

An external data source providing price information. Seesaw uses Pyth Network exclusively. Two modes are supported per market: push (oracle_mode = 0) and pull (oracle_mode = 1).

Oracle Mode (Push)#

oracle_mode = 0. The Pyth price-feed account address is stored in market.pyth_feed at creation time. On each oracle read the program verifies that the account address matches the stored value AND that the account is owned by config.pyth_receiver_program_id. (config.pyth_program_id is used only to derive the PDA address; it is not the account owner.) This is the default mode for all existing feeds.

Oracle Mode (Pull)#

oracle_mode = 1. The caller posts an ephemeral PriceUpdateV2 account produced by the Pyth Solana Receiver; market.pyth_feed is set to [0u8;32] (pull indicator — no address binding). The program verifies feed-ID (not address) and that the account owner is config.pyth_receiver_program_id (default: rec2HHDDnjLfj4kE7VyEtFA1HPGQLK33259532cRyHp, the upgraded Pyth Core Receiver). Pull mode makes Sampling Rule A firstness deterministic because the caller controls which price is submitted.

Order Book#

A data structure that stores all open buy and sell orders, sorted by price.

Order ID#

A unique identifier for an order within a market's orderbook. Monotonically increasing.

Outcome#

The final result of a market: UP or DOWN. Determined by comparing end price to start price.

P#

PDA (Program Derived Address)#

A deterministic address derived from seeds and the program ID. PDAs can sign on behalf of the program.

PriceUpdateV2#

The Pyth Solana Receiver account format for pull-mode price data. A caller posts a PriceUpdateV2 (verified by the Pyth Receiver program) immediately before a lifecycle instruction like create_market or snapshot_end. Seesaw reads it by checking the account owner against config.pyth_receiver_program_id and the feed ID against market.pyth_feed_id, then extracts price, confidence, exponent, and publish time from fixed offsets.

Permissionless#

Operations that can be executed by anyone without special authorization.

Position#

A user's holdings in a specific market, including YES shares, NO shares, and locked amounts.

PostOnly Order#

An order that will only be placed if it doesn't immediately match. Rejected if it would cross the spread (WouldCross, 0x3004). Use order_type = 1 in PlaceOrderArgs. The place_multiple_post_only_orders (0x0C) instruction submits up to four post-only orders in a single transaction.

Price Band (Maker Price Band)#

A guard on resting maker orders. A bid or ask may not be placed more than MAKER_BAND_BPS (1,000 bps = 10%) away from the current orderbook midpoint. The static fallback floor is STATIC_MIN_BPS_FOR_BAND (100 bps) and the ceiling is STATIC_MAX_BPS_FOR_BAND (9,900 bps), used when the book is empty and no midpoint exists. Orders outside the band return OrderPriceOutOfBand (0x3014).

Price-Time Priority#

The matching rule where better prices match first, and at equal prices, earlier orders match first.

Protocol#

The Seesaw smart contract and its rules.

Pyth Network#

The decentralized oracle network providing price feeds for Seesaw markets.

Q#

Quantity#

The number of shares in an order or position.

R#

Referral Account#

A per-user PDA (["seesaw", "referral", user]) recording the attributed referrer and the attribution timestamp. Written once by set_referrer; immutable for 365 days.

Referrer#

An address recorded in a user's ReferralAccount. Earns 40% of every taker fee that user pays. Can be any Solana address.

Referrer Treasury#

Eight sharded escrow token account PDAs (["seesaw", "referrer_treasury", &[shard_index]], shard_index ∈ [0, 8)) that accumulate the 40% referral share of every taker fee. Per-referrer balances are tracked in individual ReferrerEarningsAccount PDAs and claimed via claim_referrer_earnings.

Rent#

Solana's fee for storing data on-chain. Accounts must be rent-exempt (hold enough SOL to cover 2 years of rent).

Resolution#

The process of determining a market's outcome based on the start and end price snapshots.

Resting Order#

An order that is sitting on the order book waiting to be filled.

S#

Self-Trade Behavior#

How the matching engine handles a taker order that would match against the same user's own resting order. Configured per-order via self_trade_behavior in PlaceOrderArgs:

CancelProvide (1) is the default.

Settlement Sweep#

The process by which claim_creator_fees (0x23) transfers deferred creator fee earnings from the market vault to the creator's token account, and claim_referrer_earnings (0x24) transfers accumulated referral earnings from the referrer_treasury shard to the referrer's token account. Both are permissionless — any caller may trigger them after market resolution, but funds always flow to the designated recipient.

Sampling Rule#

The rule for which Pyth price to use for snapshots. Seesaw uses "first price with publish_time >= boundary."

Settlement#

The process of paying out winning positions after a market resolves.

Settlement Currency#

The token used for collateral and payouts. Default: USDT.

Snapshot#

A captured oracle price at a specific time boundary (start or end of epoch).

Slippage#

The difference between the price a trader expected to pay (their limit price) and the average price they actually received. In Seesaw the worst_acceptable_price_bps field in PlaceOrderArgs sets a hard floor for IOC/taker orders; if the fill price would cross this guard the instruction returns SlippageExceeded (0x3007). Slippage is not the same as price impact.

Price Impact#

The permanent shift in the orderbook's mid price after a fill. A large taker order that sweeps several resting orders moves the best bid or best ask and therefore changes the mid price for all subsequent participants. Price impact is distinct from slippage (the deviation for the current taker) and distinct from the taker fee (which is charged on the fill amount separately).

Solvency#

The property that the protocol can always pay all obligations. Ensured by full collateralization.

Spread#

The difference between the best bid and best ask. Tighter spreads indicate better liquidity.

State Machine#

The formal model of market states (PENDING, CREATED, TRADING, SETTLING, RESOLVED, CLOSED) and valid transitions.

T#

Terminal Forfeiture#

When a market expires (outcome = 0 past the MARKET_EXPIRY_WINDOW) and a user does not call force_close before the market is cleaned up, any remaining collateral in that position is irrecoverably locked. Users should monitor market state and claim positions before expiry or call force_close to recover collateral from an unresolved market.

Trader Ledger#

The TraderLedgerAccount PDA (["seesaw", "trader_ledger", market]) that tracks per-trader free and locked balances (settlement tokens and YES/NO shares) for each market. The seat count (num_seats) is fixed at market creation and determines maximum concurrent traders. Balances are debited and credited directly by the matching engine on every fill, cancel, and settlement operation. See Free Funds for the on-chain deposit/withdraw mechanism.

Taker#

A trader whose order matches immediately against resting orders. Takers pay fees.

Taker Fee#

The per-fill fee paid by the taker. Seesaw uses a capped-linear-decay curve: fee_bps(p) = min(fee_cap_bps, decay_rate_bps × (10_000 − p) / 10_000). With defaults fee_cap_bps = 200 and decay_rate_bps = 600, the fee is 2.00% for fills at p ≤ 0.67 and decays toward 0 as p → 1.00. Every taker fee is split three ways: 50% protocol / 10% creator / 40% referral. Makers pay 0.

Tick#

The minimum price increment for orders. Default: 100 bps (1%).

Tick Rounding#

The process of rounding order prices to valid tick levels. Bids round down, asks round up.

Trade#

An executed match between a bid and an ask.

Trading Window#

The time period during which orders can be placed. From start snapshot to end of epoch.

Treasury Shard#

One of eight sharded escrow SPL Token accounts (["seesaw", "referrer_treasury", &[shard_index]], shard_index ∈ [0, 8)) that accumulate the referral share of taker fees. Sharding spreads write contention so concurrent fee-routing transactions across different markets do not all serialize on the same account. The creator selects a shard index at market creation; referrers are associated with a shard when their ReferrerEarningsAccount is initialized. See Referrer Treasury for derivation details.

Trustless SDK#

The @seesaw/core SDK is designed to be trustless: it constructs transactions locally without relying on a backend API to sign on behalf of the user. All instruction data, PDA derivations, and account resolution happen client-side; the user's wallet signs the final transaction. This means integrators can verify the complete transaction before submission. The SDK bundles the EnsureTraderLedgerSpace prelude and Pyth pull-price posting automatically.

Treasury#

The protocol account that holds accumulated fees and funds crank rewards.

U#

UP#

The market outcome when end_price >= start_price. YES shares pay out.

V#

Vault#

The token account holding all collateral for a market. Owned by the market PDA.

W#

Wallet#

A user's Solana account holding their keypair. Used to sign transactions.

Wash Trading#

Trading with yourself to create fake volume. Prevented by self-trade prevention.

Y#

YES Share#

A share that pays out 1 USDT if the market resolves to UP (price increased).

Symbols and Formulas#

Price Conversion#

YES price + NO price = 10,000 bps (100%)

Buy YES @ p     = Bid @ p         (canonical)
Sell YES @ p    = Ask @ p         (canonical)
Buy NO @ q      = Ask @ (10000-q) (canonical)
Sell NO @ q     = Bid @ (10000-q) (canonical)

Market ID#

market_id = floor(unix_timestamp / duration_seconds)
t_start = market_id * duration_seconds
t_end = t_start + duration_seconds

Collateral#

collateral = price_bps * quantity / 10,000

Solvency Invariant#

vault_balance >= max(total_yes_shares, total_no_shares) + accumulated_creator_fees

Fee Calculations#

Capped-linear-decay curve:

fee_bps(p)    = min(fee_cap_bps, decay_rate_bps * (10_000 - p) / 10_000)
taker_fee     = ceiling(amount * fee_bps(p) / 10_000)

protocol_fee  = ceiling(taker_fee * protocol_fee_bps / 10_000)
creator_fee   = ceiling(taker_fee * default_creator_fee_bps / 10_000)
referral_fee  = taker_fee - protocol_fee - creator_fee

The three shares are bps of the fee and MUST sum to exactly 10_000:

protocol_fee_bps + default_creator_fee_bps + referral_share_bps_of_fee == 10_000

Default split: 50% protocol / 10% creator / 40% referral (5_000 / 1_000 / 4_000 bps of the fee). If the taker has no referrer set, the 40% referral portion flows to the protocol treasury.

Abbreviations#

Next Steps#

• Review Error Codes for troubleshooting
• See Constants for protocol values