Understand Solana’s Percolator persistence protocol without the jargon.
What is a percolator?
Percolator is an on-chain perpetual futures protocol built on Solana. Simply put, people can trade leveraged long/short positions on non-expiring assets (e.g. SOL), collateral is held in a shared vault and prices are provided by oracles (e.g. Chainlink, Pyth). This protocol is experimental and unaudited. It is only used for training and testing purposes and is not used for production or actual funding purposes.
Think of it as a decentralized, programmable “perps engine”. One program holds all market conditions in a single slab account, and an external matching program defines how trades are priced.
This separation increases flexibility. You can run standard or inverting markets, passive LP, or custom AMM style pricing.
Percolator Protocol – Core Ideas
1. Slab = one market, one big account
Everything in the single market resides in one on-chain account called a slab.
• header — Magic, version, maintainer, flag (e.g. “resolved” for binary markets).
• Market Composition — Collateral issuance, vault, oracle feed ID, reversal/unit size, funding and risk threshold parameters, and optional oracle permissions.
• risk engine — Vault balance, insurance fund, risk parameters (margin, commission, liquidation), funding index, crank/sweep status and bitmap + arrangement of up to 4096 accounts (users and LPs).
So: one slab = One permanent (or one binary) market.
Different slab distribution= Different markets.
2. Two types of accounts: user and LP
Each account in the slab is one of the following:
• user— Merchant. They deposit collateral and open/close positions (long = plus size, short = minus size). There are profit and loss, margin, funds, etc.
• Liquidity Provider (LP) — Provides liquidity and takes on counterparties to transactions. They also have capital and positions (the net opposite of matching user positions). LPs are bound to a matcher (program + context) that defines how transactions are priced.
Accounts are indexed (0..N). Slab tracks which indices are used via a bitmap and stores each account’s capitalization, position, entry price, funding index, matching program/context (for LPs) and owner.
3. Oracle’s feed price; Optional Permission Override
Prices come from oracles (e.g. Pyth Pull feed ID or Chainlink). The slab stores:
• Maximum staleness and confidence filters.
• Optional oracle permissions: When set, administrators can push prices (used for testing, binary payments, or controlled environments). If the authority price is set and recent, it will take precedence over external feeds.
So: normal operation = Pyth/Chainlink; Special case = price controlled by manager.
4. Market turned upside down
The market can reverse. The protocol internally uses 1/price (e.g. USD per SOL → SOL per USD). This is useful when your collateral is SOL and you want “buy USD/sell USD” style exposure. Long = Profit when SOL falls, Short = Profit when SOL rises. Same risk engine, different price interpretation.
5. Matchers: Who decides the transaction price?
Transactions can be made in two ways:
- Transactions (no CPI) — Only the filter program runs. User and LP symbols; Execution and pricing are handled inside the filter (e.g. off-chain or according to simple rules agreed upon). No other programs are called. Suitable for testing or trusted LP-user pairs.
- Trade (CPI) — Percolator calls an external matching program via CPI. A matcher (e.g. percolator-match) passes the oracle and its context, computes the execution price, and returns it. Percolator then applies those prices (size, fees, margin) and updates the status.
Here, CPI stands for Solana’s Cross-Program Invocation.
Matchers are therefore “pricing tiers”: passive (e.g. oracle ± 50bps), vAMM style (spread + influence), or fully custom. The protocol forces the LP’s matcher program/context to match and the matcher to verify the LP PDA as a signer (so only the LP’s liquidity is used).
6. Keeper Crank: Funding, Marking and Liquidation
A keeper crank is an unauthorized command that:
• Update mark prices and funding in oracle and LP net positions.
• Apply funds to open positions.
• Execute liquidation/forced closure logic (e.g., out-of-maintenance margin accounts are liquidated at the oracle price and dust positions are cleared).
Funds are calculated on-chain from LP inventory, so buys/sells pay each other (the protocol may cut). Increasing risk trades require “recent” cranks (i.e. within the 200 slot maximum) to ensure that your marks and funds are up to date.
7. Insurance and Risk
• Insurance funds (filled by managers or commissions) absorb losses when positions are liquidated or forced to close. There is a threshold. Below that, the market can be entered as “risk reduction only” (only position reduction transactions are allowed).
• Haircut Proportion Logic (O(1) Aggregation: Total Capital, Positive P&L) is used to enable the system to handle insolvencies without excessive ADL sweep. Conservation is maintained: Vaults ≥ Capital + Insurance + Plus P&L (with small rounding tolerances).
8. Binary/Free Market
The same slab can be used as a binary (event) market: the outcome is YES/NO. The administrator sets the oracle permissions, pushes the settlement price (e.g. 1.0 = YES, ~0 = NO), and then calls the settlement market. There will be no new transactions/deposits after that. Keeper Crank forces all positions to be liquidated at the settlement price. When all is said and done, the manager can withdraw the insurance and the user can withdraw the remaining capital. That is, one codebase for perpetual contracts and event payments.
Use cases
1. Perpetual futures (standard or reverse)
• standard : Example: SOL/USD perp collateralized by SOL or USDC; Long/Short SOL.
• upside down : Example: SOL collateral, price = 1/SOL in USD; Long = bullish USD (bearish SOL), short = bearish USD (bullish SOL). This is great if you hold collateral in SOL and want to express your opinion on “what SOL will go up or down”.
Use the CLI (or SDK) to initialize the market → initialize the user → deposit → run the keeper crank → perform a trade (trade-cpi or trade-nocpi). Both are the same flow, only invert and unit_scale are different in init-market.
2. Provide liquidity (Passive or vAMM)
• Passive LP:One matcher (e.g. filter match) with a fixed spread (e.g. 50bps). LP uses its matcher context to deposit collateral, init-lp. Traders get the oracle ± spread.
• vAMM style LP:It is a matcher with basic spread + impact + commission. For small, the spread is narrower, and for large, the spread is wider. You can add these LPs by running a script like add-vamm-lp.ts. Bots (e.g. random-traders.ts) can route to the best LPs with simulated prices.
Use cases:Make markets, earn spreads/commissions, or run custom pricing strategies in your own matching program.
3. Keeper/Infrastructure
• Crank Bot:It calls the keeper crank every few seconds to ensure that funds and marks are fresh and liquidations are executed. Required for transactions with increased risk (staleness checks).
• Liquidator:Monitors the account and calls liquidation from the oracle when the account falls below the maintenance margin. unauthorized; Liquidators receive a fee.
Use case: Operate a public good (crank) or profit from liquidation fees.
4. Binary/event market (free market)
• Create a slab without an external feed (e.g. Pyth feed ID = 0, “Hyperp” mode), set an initial mark price (e.g. 0.5 = 50% implied), and set Oracle permissions to Administrator.
• Users trade like criminals. Once the event is resolved, the management pushes the oracle price (YES=1e6, NO≒0), resolves the market, cranks until all positions are forced to close, and then withdraws insurance and user capital.
Use cases:Prediction markets, event contracts or binary outcomes settled at a single price.
5. Testing and Stress Testing
• Oracle Powers: Offers fixed or extreme prices for liquidation, financing, or testing edge cases without moving the actual market.
• Scripts: Examples: stress-haircut-system.ts, stress-worst-case.ts, oracle-authority-stress.ts, pentest-oracle.ts for security/stress; test-*.ts for immutability and flow.
• Devnet: setup-devnet-market.ts creates a fully inverted SOL/USD market via Chainlink and funded LPs. You can run the bot and test against it.
Use case: Protocol team, auditor, or integrator to verify behavior prior to mainnet.
6. Management and parameter adjustment
• update-config: Change funding period, K, size, max premium, threshold lower/risk/interval/step/alpha/min/max (funding and risk threshold behavior).
• Set risk thresholds, set maintenance costs: Fine-tune risks and costs.
• Insurance Top-Up, Insurance Withdrawal (if resolved and empty): Manages the insurance fund.
Use case: Market operators adapting to volatility or demand.
Potential and Direction
1. Solana’s Perpetual
Percolator demonstrates that a single-program, single-slab perpetual engine can operate on Solana via Pyth/Chainlink, multiple LPs, and permissionless cranks/clearers. This is the foundation for:
• Public illicit markets with SOL or stablecoin collateral (e.g. SOL, BTC, ETH).
• Inversion markets where the collateral is the underlying asset and traders want leveraged exposure to the “other side” of the collateral pair.
2. Pluggable matcher
Pricing is determined by an external matcher program, so the core protocol remains minimal and secure:
• Teams can ship new matchers (e.g. order book style, RFQ or hybrid) without changing the risk engine.
• Multiple matchers (manual, vAMM, etc.) can coexist in one market. Traders and bots choose the optimal price (as with optimal price and random trading).
Potential:A matcher ecosystem (central limit order book, call for quote, volatility sensitive spreads) sits on top of one shared Perp engine.
3. Binary and event markets
The same slab and risk engine supports resolution + force termination 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 distribution and one CLI/SDK.
potential: Solana’s integrated “gift + event” layer.
4. Configurability and automation
• Programmatic API: CLI is a thin wrapper around command and slab parsing. The repository’s encode*, buildAccountMetas and parse* functions are small SDKs. UI, bots, and other programs can be built on top of it.
• Custodian/Liquidator Incentives: Permissionless cranking and oracle clearing allow third parties to operate the infrastructure without permission and earn fees.
potential: Integration with wallets, aggregators and automated strategies.
For educational purposes only. The Percolator program and this CLI have not been audited. Do not use for production or real money. Use at your own risk.
source
This document is based on the percolator-cli codebase (https://github.com/aeyakovenko/percolator-cli) and related repositories (percolator, percolator-prog, percolator-match).
Percolator Protocol: Perpetual Transactions on Solana was originally published on Coinmonks on Medium, and people are continuing the conversation by highlighting and responding to this story.