Skill

Solana Perps Development Skill (Percolator)

Comprehensive guide for building perpetual futures protocols on Solana using the Percolator risk-engine library.

Overview

Percolator is a perpetual-futures risk-engine library for account-local, permissionless risk progress. It is a pure Rust library — it does not define an on-chain program id, account decoder, persisted market registry, or deployment manifest. Wrappers own authorization, account loading, oracle/funding authentication, fee-schedule policy, and raw-state layout migration.

Three Core Invariants

1. Realizable credit: protected principal is senior, positive PnL is junior, and source-domain positive credit cannot exceed realizable backing reserved for that domain.
2. Account-local safety: every favorable action refreshes the account's full active portfolio first; hidden, stale, or B-stale legs fail closed.
3. Bounded progress: cranks and recovery paths are account-local and incremental; no public instruction needs to evaluate the whole market.

Key Design Decisions

• Full shared cross-margin inside one instance (Hyperliquid-like UX)
• No global B pool — bankruptcy residual is asset-side domain local
• No global account scan — all operations are account-local or bounded by MAX_PORTFOLIO_ASSETS_N
• Permissionless crank — one public entrypoint, engine-selected actions, out-of-order safe
• Formally verified — 258 plain Kani proofs + 51 contract proofs, conditional 10/10 No-LoF / No-DoS

Skill Structure

solana-perps/
├── SKILL.md                           # This file (entry point)
├── percolator-engine.md               # Engine architecture deep dive
├── account-model.md                   # PortfolioAccount, provenance, health
├── credit-model.md                    # Source-domain credit, backing, liens
├── crank-recovery.md                  # Permissionless crank, recovery
├── risk-params.md                     # Configuration, hard bounds, envelopes
├── wrapper-integration.md             # Building wrapper programs
├── testing-verification.md            # Testing, Kani proofs, fuzzing
├── resources.md                       # References, further reading
├── examples/                          # Working code examples (in examples/ dir)
├── agents/                            # AI agent definitions
│   ├── perps-architect.md
│   ├── perps-engineer.md
│   ├── perps-security-auditor.md
│   └── solana-guide.md
├── commands/                          # Reusable commands
│   ├── verify-perps.md
│   └── deploy-perps.md
└── rules/                             # Coding rules
    ├── perps-rust.md
    └── rust.md

Quick Reference

Key Types

Type	Purpose
PortfolioAccountV16	Per-account portfolio with provenance, active bitmap, bounded leg array
MarketGroupV16	Market group instance, one quote-token vault
SourceCreditState	Per-domain source credit, backing, liens, credit rate
AutoCrankWorkV16	Input struct for the permissionless crank entrypoint
AutoCrankPlanV16	Engine-selected crank action output
BackingBucket	Freshness-bucketed counterparty backing
InsuranceLedger	Insurance budget, reservations, spending
TokenValueFlowProof	Balanced quote-value conservation proof
ReservationEncumbranceProof	Backing/insurance encumbrance proof

Key Constants

Constant	Value	Description
POS_SCALE	1_000_000	Position quantity scale
BOUND_SCALE	1_000_000_000_000	Claim bound scale
CREDIT_RATE_SCALE	1_000_000_000_000	Credit rate scale
ADL_ONE	1_000_000_000_000_000	ADL quantity scale
FUNDING_DEN	1_000_000_000	Funding denominator
MAX_ORACLE_PRICE	1_000_000_000_000	Max oracle price
MAX_PORTFOLIO_ASSETS_N	config-bounded	Max assets per portfolio

Invariant Checklist

• usable_positive_credit_from_source_domain <= realizable_counterparty_backing_reserved_for_that_domain
• After every instruction: all global, asset, account, certificate, credit, lien, close-state, insurance, payout, and obligation invariants hold
• Every TokenValueFlowProof is balanced (quote atoms only)
• Every ReservationEncumbranceProof is valid
• fresh_reserved_backing_num >= valid_liened_backing_num
• available_backing_num >= 0
• 0 <= credit_rate_num <= CREDIT_RATE_SCALE
• valid_liened_insurance_num + impaired_liened_insurance_num <= insurance_credit_reserved_num

How to Use This Skill

When helping with perps development:

1. Architecture: Refer to percolator-engine.md for the engine architecture and design philosophy
2. Account Model: Refer to account-model.md for portfolio accounts, provenance, health certificates
3. Credit Model: Refer to credit-model.md for source-domain credit, counterparty backing, insurance liens
4. Crank & Recovery: Refer to crank-recovery.md for permissionless crank, recovery paths
5. Risk Parameters: Refer to risk-params.md for configuration, hard bounds, solvency envelopes
6. Wrapper Integration: Refer to wrapper-integration.md for building wrapper programs around Percolator
7. Testing: Refer to testing-verification.md for Kani proofs, fuzz testing, conformance
8. Resources: Refer to resources.md for references, papers, related projects

Related Skills

• solana-dev (core Solana development: Anchor, Pinocchio, LiteSVM, security)
• trailofbits (security auditing for Solana programs)
• sendai (DeFi protocol integrations: Jupiter, Raydium, Kamino)
• position-manager (CLMM position management via Orca, Raydium, Meteora)

Reference Implementation

The authoritative Solana wrapper program is at aeyakovenko/percolator-prog (12K lines, Anchor v2 / Pinocchio, LiteSVM tests). All API patterns in this skill are based on that implementation. When in doubt about wrapper patterns, consult percolator-prog first.

A minimal compilable example demonstrating view construction and engine API calls is in examples/minimal-wrapper/. Build and test with cargo test (pure Rust, no Solana SDK required).