Protocol Architecture — Overview

SportsPerp is split across three layers: on-chain (the Anchor program and its PDAs), off-chain (a set of permissionless services that feed and maintain the program), and frontend (a Next.js app plus the published SDK). This page is the map; the following pages drill into each layer.

The big picture

┌─────────────────────────────────────────────────────────────────────────┐
│                           STATSBOMB DATA                                │
│  Direct API (REST)          ◄── post-match canonical OBV                │
│  Live API (GraphQL)         ◄── in-match event stream                   │
└──────────────────────────────────┬──────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼──────────────────────────────────────┐
│                      OFF-CHAIN SERVICES (Hetzner)                        │
│                                                                          │
│  ┌─────────────────┐   ┌───────────────┐   ┌──────────────┐             │
│  │  Oracle Crank   │──►│ Oracle Pusher │──►│ update_oracle│             │
│  │  (engine/)      │   │ (oracle-pusher│   │              │             │
│  │  port 3456      │   │  port 3458)   │   │              │             │
│  └────────┬────────┘   └───────────────┘   └──────────────┘             │
│           │                                                             │
│           ├─► Candle API (REST, SQLite-backed)                          │
│           ├─► WebSocket feed (ticks, live events)                       │
│           └─► obv-engine Python sidecar (port 8100, XGBoost)            │
│                                                                          │
│  ┌──────────────────┐   ┌─────────────────┐   ┌────────────────┐        │
│  │  Keeper          │   │  Liquidator Bot │   │ Monitor        │        │
│  │  (triggers +     │   │  (3-layer       │   │ (health +      │        │
│  │   funding crank) │   │   cascade)      │   │  Telegram)     │        │
│  │  port 3457       │   │  port 3459      │   │  port 3460     │        │
│  └──────────────────┘   └─────────────────┘   └────────────────┘        │
└──────────────────────────────────┬──────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼──────────────────────────────────────┐
│                    ON-CHAIN PROGRAM (Solana devnet)                      │
│                                                                          │
│  Program ID: 6d4fSCD7mNy7aDNS2mXUxYpZjFFQKBKwAsM5kojKQA6h                │
│                                                                          │
│  30 instructions · 47 error codes · 7 PDA account types · 13 events     │
│                                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────┐     │
│  │ MarketConfig │  │ UserPosition │  │LiquidityPool │  │Insurance │     │
│  │  ×68         │  │  (per trade) │  │  (singleton) │  │Fund (×1) │     │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────┘     │
│                                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────┐              │
│  │  Backstop-   │  │ TriggerOrder │  │ UserOrderCounter  │              │
│  │  Position    │  │  (per order) │  │  (per user)       │              │
│  └──────────────┘  └──────────────┘  └───────────────────┘              │
└──────────────────────────────────┬──────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼──────────────────────────────────────┐
│                    FRONTEND + SDK (Vercel + npm)                         │
│                                                                          │
│  ┌──────────────────────┐      ┌──────────────────────┐                 │
│  │  Next.js 16 app      │◄─────│ @sportsperp/sdk      │                 │
│  │  Wallet adapter      │      │ Instruction builders │                 │
│  │  TradingView charts  │      │ PDA helpers          │                 │
│  │  HTTPS proxy routes  │      │ Math (mirrors Rust)  │                 │
│  └──────────────────────┘      └──────────────────────┘                 │
└─────────────────────────────────────────────────────────────────────────┘

Design principles

Three principles keep the architecture disciplined:

1. Keep the program small

The on-chain program does the minimum necessary: custody, settlement, invariant enforcement. Everything that doesn’t have to be on-chain isn’t:

• Price calculation → off-chain oracle crank.
• TWAP sample collection → on-chain (every update_oracle adds a premium sample); funding consumes the mean across all samples accumulated since the last apply_funding.
• Trigger-order polling → off-chain keeper.
• Liquidator candidate selection → off-chain.
• Candle history → off-chain (SQLite, exposed via REST).

The result: a small compiled binary with 30 instructions — small enough to audit fully, cheap to invoke, and minimal attack surface.

2. Make every off-chain role permissionless

Every operation the off-chain services perform can be run by anyone:

• update_oracle requires admin signature — but multi-source oracle (built, not deployed) relaxes this to a 2-of-N weighted median.
• apply_funding is permissionless.
• partial_liquidate, backstop_liquidate, unwind_backstop, auto_deleverage are permissionless.
• execute_trigger_close, execute_trigger_open are permissionless.
• sunset_market, settle_position are permissionless.

Our Hetzner services exist to guarantee these operations happen, not to monopolize them. If SportsPerp’s services go dark, the protocol continues: any independent keeper can pick up the work.

3. Single source of truth for everything

The same data representation flows end-to-end:

• Markets are defined in roster.json — one file, file-watched, hot-reloaded by every service.
• Math is defined once in Rust (programs/obv-perps/src/math/) and mirrored bit-for-bit in TypeScript (sdk/src/math/). A PnL computed off-chain equals the on-chain computation to the last integer.
• IDL is generated by anchor build and copied verbatim into both the SDK and the frontend — no divergent hand-maintained bindings.

How a trade flows through the stack

Concrete example — a trader opens a 5x long on market 0 (Arsenal):

1. Frontend — user clicks “Long 5x”; OrderPanel calls useProgram() to build the open_position instruction via the SDK.
2. Wallet — Phantom signs the transaction. The instruction specifies direction=0 (long), collateral_amount=100_000_000 (100 USDC at 10⁶ scale), leverage=500 (5x at 10² scale).
3. On-chain — the program:
   • Checks the market isn’t paused, oracle isn’t stale, caller has sufficient USDC.
   • Validates pool_token.amount ≥ pool.risk_floor — the hard gate on new risk. Below the floor, the instruction is rejected with RiskFloorBreached. (Closes, cancels, SL/TP, and reduce-only paths are unaffected.)
   • Validates the tier cap. The denominator is effective_oi = max(market_total_oi, initial_capacity) — same example: 100 USDC on a 1,000 USDC effective_oi = 10% → tier 2, max 4x — instruction rejected at 5x. Retry at 4x.
   • Applies any pending funding.
   • Transfers 100 USDC from the trader’s associated token account to the global pool_token SPL account (one shared pool across all 68 markets — see On-Chain Program → Liquidity Pool).
   • Creates a UserPosition PDA with the entry price set to the current mark EMA.
   • Deducts 10 bps taker fee (0.4 USDC) from collateral.
   • Updates MarketConfig.total_long_oi by the notional size.
4. Off-chain visibility — the crank’s WebSocket server observes the transaction signature and broadcasts a position-opened event to subscribed frontends. TradingView shows the new position.
5. Ongoing — every 8 hours the keeper invokes apply_funding; every 5 minutes the oracle crank pushes a new oracle price; the liquidator bot monitors margin ratios; if the mark drops far enough, Layer 1 partial liquidation fires.

What lives where

Further reading

• On-Chain Program — 30 instructions, 7 PDA types (incl. singleton LiquidityPool), error model, deployment.
• Off-Chain Services — the systemd services running on Hetzner (6 Node services + Python obv-engine sidecar; trade-history indexer live since 2026-05-11).
• Oracle Design — how upstream event data becomes an on-chain oracle price.
• Fixed-Point Math — how Rust and TypeScript stay in lockstep.