# Solana Perps

> Build perpetual futures protocols on Solana using the Percolator risk-engine. Covers Percolator v16 architecture, account-local cross-margin, source-domain realizable credit, permissionless crank/recovery, wrapper integration, formal verification with Kani, and production best practices. Use when developing Solana perps DEXs, integrating Percolator, or designing perps risk systems.

- Skill: `max-de-bug/solana-perps` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add max-de-bug/solana-perps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/max-de-bug/solana-perps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: max-de-bug (https://skillmd.com/u/max-de-bug)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/max-de-bug/solana-perps

---


# 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](https://github.com/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/`](../examples/minimal-wrapper/). Build and test with `cargo test` (pure Rust, no Solana SDK required).