On-Chain Program

The on-chain program is written in Rust using the Anchor framework (v0.32.1), compiled to Solana BPF bytecode, and deployed to devnet at program ID 6d4fSCD7mNy7aDNS2mXUxYpZjFFQKBKwAsM5kojKQA6h.

Program instructions

Grouped by role:

Trading (user-invoked)

Trigger orders

Oracle & funding

Liquidation (all permissionless)

Market lifecycle

Insurance fund

Liquidity pool administration

Liquidity pool (public LP)

Authority rotation (admin)

The 8 PDA account types

Every stateful object in the protocol is a Program Derived Address. All seeds listed below are literal byte strings + little-endian serialized primitives:

Capital model — single global pool, no per-market vaults

Earlier versions of SportsPerp used one VaultAccount per market (68 PDAs + 68 SPL token accounts). That created structural illiquidity in any one-sided market — losses on Arsenal could not fund profits on Manchester City, and a fresh market with thin LP could block a profitable close. The 2026-04-25 NFO incident (VaultInsufficient on a profitable +$20 close) made the defect concrete in production.

The design was replaced before mainnet by a single global pool. Per-market accounting still lives on MarketConfig; only the capital custody moved.

Solvency invariant

pool_token.amount  ≥  Σ open positions [max(0, collateral + pnl − funding_owed − close_fee)]
                    + Σ pending LimitOpen escrows
                    + Σ open backstop obligations

The full Σ is enforced off-chain by a solvency-probe service (60s loop, operator alerts on drift). On-chain instructions do cheap local checks only:

Two thresholds

• risk_floor — admin-set, hard on-chain gate. Below it, opens and LimitOpens are blocked; closes / SL / TP / cancels / margin-passing collateral withdrawals all keep working. Surfaced in the trader UI as “Opening paused: pool liquidity below risk floor.”
• target_balance — admin-set, off-chain only. The monitor service fires [warning] operator alerts at pool < 2× target_balance, [error] at pool < 1.25× target_balance. Designed to surface low-pool conditions before risk_floor engages.

The InsuranceFund stays separate; pool capital and insurance capital have different invariants and different admin policies.

The cross-market liquidity-pool design is documented in the project’s internal design plans.

The error model

59 custom error codes are declared in the program’s errors.rs. Error code discipline:

• Codes are never reused. Even when a check is removed, its code is retired, not repurposed. Downstream consumers parsing logs won’t get silently misled.
• Every condition has a dedicated code. OracleStale, PositionAlreadyExists, InvalidLeverage, LiquidationCooldownActive, ProfitableLiquidation, NoOpposingPositionsForADL, etc. — the cause is always specific.
• Anchor error numbers start at 6000 (offset 0) and increment. SDK consumers can pattern-match numerically or by name.

Compilation and deployment

Builds require Linux (the BPF toolchain doesn’t compile on Windows or macOS ARM). Builds and deploys are performed from a controlled, access-restricted build environment.

# on the build server
anchor build
# → target/deploy/obv_perps.so (~940 KB)
 
solana program deploy \
  --program-id target/deploy/obv_perps-keypair.json \
  target/deploy/obv_perps.so \
  --url devnet

After deployment, the IDL is copied to two places:

• sdk/idl/obv_perps.json — consumed by the SDK.
• app/idl/obv_perps.json — consumed by the frontend.

Both are committed to the repo. A contributor fetching the repo at any commit can reproduce a working stack without running anchor build themselves.

Program ID changes

When the program ID changes (rare — typically only on major re-architectures), ~23 files across the codebase need updating. The full procedure is captured in the project’s internal deployment runbook. This is the kind of operation that gets a dedicated migration branch, never a one-shot edit.

Historical dead program IDs are preserved in that runbook so no one accidentally reuses them. Devnet rent on each dead ID is still recoverable but has not been reclaimed.

Admin, oracle authority, upgrade authority, and multi-sig path

On devnet, price-pushing and oracle-update authority is separated from the general admin authority. A dedicated oracle_authority key gates update_oracle and pause_market (pause_market also accepts the admin), so the hot key that publishes prices and can emergency-halt a market is distinct from the key that controls capital and configuration. Admin authority covers:

• Per-market unpause_market, update_market_params (and pause_market, shared with the oracle authority).
• Insurance deposit_insurance, withdraw_insurance, configure_insurance.
• force_settle_market.
• Liquidity pool initialize_pool, seed_pool, withdraw_pool_lp.
• Authority rotation: set_oracle_authority, set_market_admin, set_pool_admin, set_insurance_admin, set_obligations_snapshot_authority (a hot authority can never rotate the admin, and a rotated hot authority can never equal the admin).

The oracle-authority separation was deployed to devnet (program upgraded; all 68 markets migrated to the 238-byte layout and verified), with the oracle running on a dedicated hot key distinct from the admin. The single-key admin (and the program’s upgrade authority) remains the protocol’s primary centralization vector on devnet, and removing it is a hard mainnet gate: both move to a multi-signature setup with a timelock on parameter-changing instructions before mainnet. See the Roadmap.

Testing

The program ships with:

• ~30 Anchor integration tests — covering trade lifecycles, oracle updates, liquidations, insurance flows.
• 28 Phase 5 risk-engine tests — 9 risk scenarios including composite mark dislocations, confidence scaling, margin tiers, three-layer cascade.
• 109 E2E tests against live devnet across 18 .test.ts files — open/close, partial-close, oracle, funding, liquidation, admin, trigger orders, sunset, sunset-extended, pool-solvency, risk-floor-gate, S4-01 expiry regression.
• 151 SDK unit tests — math parity, PDA derivation, devnet integration, E2E trading, liquidation builders, update_market_params.
• ~823 engine Vitest tests across 55 suites — composite math, EMA blender, live-processor replay, ID bridge, shadow pipeline, candle store, WS server.

E2E tests are the last gate before any devnet deploy.

Further reading

• Off-Chain Services — the services that invoke the permissionless instructions.
• Oracle Design — detail on update_oracle + TWAP sampling.
• Program Instructions Reference — per-instruction argument and account tables.
• Account Structure (PDAs) — field-by-field breakdown of each PDA.