Percolator Protocol: Perpetual Trading on Solana

Understanding the Percolator perpetual protocol on Solana — without the jargon.

What Is Percolator?

Percolator is an on-chain perpetual futures protocol built on Solana. In plain terms: it lets people trade leveraged long/short positions on an asset (e.g. SOL) that never expire, with collateral held in a shared vault and prices coming from oracles (e.g. Chainlink, Pyth). The protocol is experimental and unaudited — for educational and testing only, not production or real funds.

Think of it as a decentralized, programmable “perps engine”: one program holds all market state in a single slab account, and external matcher programs define how trades are priced.

This separation makes it flexible: you can run standard or inverted markets, passive LPs, or custom AMM-style pricing.

Percolator Protocol — Core Ideas

1. The Slab = One Market, One Big Account

Everything for a single market lives in one on-chain account called a slab:

• Header — magic, version, admin, flags (e.g. “resolved” for binary markets).

• Market config — collateral mint, vault, oracle feed ID, invert/unit scale, funding and risk-threshold parameters, optional oracle authority.

• Risk engine — vault balance, insurance fund, risk params (margins, fees, liquidation), funding index, crank/sweep state, and a bitmap + array of up to 4096 accounts (users and LPs).

So: one slab = one perpetual (or one binary) market.

Deploy another slab = another market.

2. Two Kinds of Accounts: Users and LPs

Each account in the slab is either:

• User — a trader. They deposit collateral, open/close positions (long = positive size, short = negative size), and have PnL, margin, funding, etc.

• LP (liquidity provider) — provides liquidity and takes the other side of trades. They also have capital and a position (opposite to the net of user positions they’ve matched). LPs are bound to a matcher (program + context) that defines how trades are priced.

Accounts are indexed (0..N). The slab tracks which indices are used via a bitmap and stores each account’s capital, position, entry price, funding index, matcher program/context (for LPs), and owner.

3. Oracles Feed Price; Optional Authority Overrides

Prices come from oracles (e.g. Pyth Pull feed ID or Chainlink). The slab stores:

• Max staleness and confidence filter.

• Optional oracle authority: if set, an admin can push a price (used for testing, binary settlement, or controlled environments). When authority price is set and recent, it overrides the external feed.

So: normal operation = Pyth/Chainlink; special cases = admin-controlled price.

4. Inverted Markets

A market can be inverted: internally the protocol uses 1/price (e.g. USD per SOL → SOL per USD). That’s useful when collateral is SOL and you want “long USD / short USD” style exposure: long = profit when SOL goes down, short = profit when SOL goes up. Same risk engine, different price interpretation.

5. Matchers: Who Decides Trade Price?

Trades can happen in two ways:

• Trade (no CPI) — Only the percolator program runs. User and LP sign; execution and pricing are handled inside percolator (e.g. agreed off-chain or by a simple rule). No other program is called. Good for testing or trusted LP–user pairs.
• Trade (CPI) — Percolator invokes an external matcher program via CPI. The matcher (e.g. percolator-match) is passed the oracle and its context, computes the execution price, and returns it. Percolator then applies that price (size, fees, margin) and updates state.

CPI here means Cross-Program Invocation on Solana.

So matchers are the “pricing layer”: passive (e.g. oracle ± 50 bps), vAMM-style (spread + impact), or fully custom. The protocol enforces that the LP’s matcher program/context match and that the matcher verifies the LP PDA as signer (so only that LP’s liquidity is used).

6. Keeper Crank: Funding, Mark, and Liquidation

A keeper crank is a permissionless instruction that:

• Updates mark price and funding from the oracle and LP net position.

• Applies funding to open positions.

• Runs the liquidation/force-close logic (e.g. under-maintenance-margin accounts liquidated at oracle price; dust positions cleaned up).

Funding is computed on-chain from LP inventory so that longs/shorts pay each other (and the protocol can take a cut). Risk-increasing trades require a “recent” crank (e.g. within ~200 slots) so that mark and funding are up to date.

7. Insurance and Risk

• An insurance fund (topped up by admin or fees) absorbs losses when positions are liquidated or force-closed. There is a threshold; below it, the market can enter “risk reduction only” (only position-reducing trades allowed).

• Haircut-ratio logic (O(1) aggregates: total capital, positive PnL) is used so the system can handle insolvencies without a heavy ADL sweep. Conservation is maintained: vault ≥ capital + insurance + positive PnL (with small rounding tolerance).

8. Binary / Premarkets

The same slab can be used as a binary (event) market: outcome YES/NO. Admin sets an oracle authority, pushes a settlement price (e.g. 1.0 = YES, ~0 = NO), then calls resolve-market. After that, no new trades/deposits; keeper crank force-closes all positions at the settlement price. Once everything is closed, admin can withdraw insurance and users withdraw remaining capital. So: one codebase for both perpetuals and event settlement.

Use Cases

1. Perpetual Futures (Standard or Inverted)

• Standard: e.g. SOL/USD perp with SOL or USDC as collateral; long/short SOL.

• Inverted: e.g. SOL collateral, price = 1/SOL in USD terms; long = bullish USD (bearish SOL), short = bearish USD (bullish SOL). Good when you want to keep collateral in SOL and express a view on “SOL going up or down.”

Use the CLI (or SDK) to: init market → init user → deposit → run keeper crank → trade (trade-cpi or trade-nocpi). Same flow for both, only invert and unit_scale differ in init-market.

2. Liquidity Provision (Passive or vAMM)

• Passive LP: one matcher (e.g. percolator-match) with a fixed spread (e.g. 50 bps). LP deposits collateral, init-lp with that matcher context; traders get oracle ± spread.

• vAMM-style LP: matcher with base spread + impact + fee. Tighter spreads for small size, wider for large; you can run scripts like add-vamm-lp.ts to add such LPs. Bots (e.g. random-traders.ts) can route to the best LP by simulated price.

Use case: market-making, earning spread/fees, or running a custom pricing strategy in your own matcher.

3. Keeper / Infrastructure

• Crank bot: calls keeper-crank every few seconds so funding and mark are fresh and liquidations run. Required for risk-increasing trades (staleness checks).

• Liquidator: monitors accounts and calls liquidate-at-oracle when an account is under maintenance margin. Permissionless; liquidator earns a fee.

Use case: run public goods (crank) or profit from liquidation fees.

4. Binary / Event Markets (Premarkets)

• Create a slab with no external feed (e.g. Pyth feed ID = zeros, “Hyperp” mode), set initial mark price (e.g. 0.5 = 50% implied), set oracle authority to admin.

• Users trade as in a perp; when the event resolves, admin push-oracle-price (YES=1e6, NO≈0), then resolve-market, then crank until all positions are force-closed, then withdraw insurance and user capital.

Use case: prediction markets, event contracts, or any binary outcome that settles at a single price.

5. Testing and Stress Testing

• Oracle authority: push fixed or extreme prices to test liquidations, funding, or edge cases without moving real markets.

• Scripts: e.g. stress-haircut-system.ts, stress-worst-case.ts, oracle-authority-stress.ts, pentest-oracle.ts for security/stress; test-*.ts for invariants and flows.

• Devnet: setup-devnet-market.ts creates a full inverted SOL/USD market with Chainlink and a funded LP; you can run bots and tests against it.

Use case: protocol teams, auditors, or integrators validating behavior before mainnet.

6. Admin and Parameter Tuning

• update-config: change funding horizon, K, scale, max premium, threshold floor/risk/interval/step/alpha/min/max (funding and risk-threshold behavior).

• set-risk-threshold, set-maintenance-fee: fine-tune risk and cost.

• topup-insurance, withdraw-insurance (when resolved and empty): manage insurance fund.

Use case: market operators adjusting to volatility or demand.

Potential and Directions

1. Perpetuals on Solana

Percolator shows that a single-program, single-slab perpetual engine can live on Solana with Pyth/Chainlink, multiple LPs, and permissionless crank/liquidators. That’s a base for:

• Public perp markets (e.g. SOL, BTC, ETH) with SOL or stablecoin collateral.

• Inverted markets where collateral is the native asset and traders want leveraged exposure to “the other side” of the pair.

2. Pluggable Matchers

Because pricing is in external matcher programs, the core protocol stays minimal and secure while:

• Teams can ship new matchers (e.g. order-book style, RFQ, or hybrid) without changing the risk engine.

• Multiple matchers (passive, vAMM, etc.) can coexist in one market; traders and bots choose the best price (as in best-price and random-traders).

Potential: a matcher ecosystem (central limit order book, request-for-quote, volatility-sensitive spreads) on top of one shared perp engine.

3. Binary and Event Markets

The same slab and risk engine support resolve + force-close at settlement price, so:

• Prediction markets and event contracts can be built on the same codebase as perps.

• Operators can run both perps and binary markets with one deployment and one CLI/SDK.

Potential: unified “futures + events” layer on Solana.

4. Composability and Automation

• Programmatic API: the CLI is a thin wrapper over instructions and slab parsing; the repo’s encode*, buildAccountMetas, and parse* functions are a small SDK. UIs, bots, and other programs can compose on top.

• Keeper/liquidator incentives: permissionless crank and liquidate-at-oracle allow third parties to run infrastructure and earn fees without permission.

Potential: integrations with wallets, aggregators, and automated strategies.

FOR EDUCATIONAL PURPOSES ONLY. The Percolator program and this CLI have not been audited. Do not use in production or with real funds. Use at your own risk.

Source

This article is based on the percolator-cli codebase (https://github.com/aeyakovenko/percolator-cli) and related repos (percolator, percolator-prog, percolator-match).

Percolator Protocol: Perpetual Trading on Solana was originally published in Coinmonks on Medium, where people are continuing the conversation by highlighting and responding to this story.