Skip to main content
Repository: purpletrade/percolator-prog · License: Apache 2.0 · Language: Rust · ~4,400 lines

​
What It Does

percolator-prog is a single-file Solana program that implements the entire perpetual futures engine. It stores all market state in a single on-chain account called a slab and exposes 22 instructions for market creation, trading, risk management, and liquidation. This is the program deployed on mainnet at PRPLUgjCUxCEzNPP6x7XJVK1WR5XX28Zu8MEyTqvGjF.

​
Architecture

One market = one slab account containing:
  • Header (72 bytes) — magic, version, admin key, nonce, threshold slot
  • MarketConfig (320 bytes) — collateral mint, vault, oracle keys, margin thresholds, funding params
  • RiskEngine — stored in-place (zero-copy), wraps the formally verified percolator crate
  • Account slots (240 bytes x 4096) — user and LP positions, collateral, PnL
Total slab size: ~992 KB (~6.9 SOL rent).

​
Trust Model

The program enforces three distinct trust layers:
LayerResponsibilityTrust Level
RiskEnginePure accounting, risk checks, state transitionsTrusted core — no CPI, no token transfers, no signer checks
Percolator programAccount validation, token transfers, oracle reads, matcher CPITrusted glue — enforces all on-chain constraints
Matcher programProvides execution price/size via CPILP-scoped — treated as adversarial, strict ABI validation

​
Two Trade Paths

  • TradeNoCpi — Direct trade without an external matcher. Used for testing and deterministic scenarios.
  • TradeCpi — Production path. Calls an LP-chosen matcher program via CPI, validates the return prefix, then executes through the risk engine.

​
Matcher CPI Safety

When a trade goes through TradeCpi, the program enforces:
  • LP identity signer (PDA-derived, not user-provided)
  • Matcher program + context must match what the LP registered
  • Matcher context must not be executable, must be owned by matcher program
  • Nonce binding prevents replay
  • ABI validation of all return fields (flags, echoed identifiers, size constraints)
  • Engine always uses the matcher’s exec_size, never the user’s requested size

​
Risk-Reduction Gating

When the insurance fund is low, the program can enforce risk-reduction-only mode:
  • Risk-increasing trades are rejected
  • Risk-reducing trades (closing positions) are always allowed
  • Auto-threshold updates via KeeperCrank with EWMA smoothing and step clamping

​
Admin Powers and Limits

The admin key can rotate governance, set risk thresholds, update market config, resolve markets, and force-close abandoned accounts. Setting admin to all zeros permanently disables all admin operations. After market resolution:
  • No config changes allowed
  • Insurance withdrawal only after all positions closed
  • Force-close only for zero-position accounts
See the admin threat model in the repository for the full attack surface analysis.

​
Verified Build

The program is built deterministically using the Solana Foundation’s verifiable build toolchain. See the Source Verification page for SHA-256 hashes, CI links, and instructions to reproduce the build yourself.

​
Instructions

All 22 instructions with their tags:
TagInstructionCategory
0InitMarketMarket lifecycle
1InitUserParticipant lifecycle
2InitLPParticipant lifecycle
3DepositCollateralParticipant lifecycle
4WithdrawCollateralParticipant lifecycle
5TradeCpiTrading
6KeeperCrankRisk / maintenance
7PushOraclePriceOracle
8SetOracleAuthorityOracle
9UpdateAdminAdmin
10UpdateConfigAdmin
11CloseAccountParticipant lifecycle
12SetMatcherAdmin
13CloseSlabAdmin
14SettleFundingRisk / maintenance
15LiquidateRisk / maintenance
16UpdateFundingRateRisk / maintenance
17ReallocSlabAdmin
18SetFeeReceiverAdmin
19WithdrawFeesAdmin
20ToggleTradingAdmin
21AdminForceCloseAccountAdmin (emergency)

​
Build & Test

# Build for Solana
cargo-build-sbf --sbf-out-dir target/deploy -- --locked

# Unit tests
cargo test

# Kani formal verification (requires kani toolchain)
cargo kani --tests

​
Original Source

Forked from Anatoly Yakovenko’s aeyakovenko/percolator-prog. An upstream sync workflow checks for divergence from the original source.

View Repository

Source code, CI workflows, threat model documentation

Verified Build

Latest SBF build artifact with SHA-256 hash