# Percolator > Percolator perpetual futures protocol development (Feb 2026). Educational research project for predictable risk management using profit-as-junior-claims model. Covers core risk engine (Rust), Solana programs, CLI tools, matcher development, testing, and formal verification. Alternative to traditional ADL with global coverage ratio and self-healing mechanics. Use when this capability is needed. - Skill: `tomevault-io/percolator` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/percolator` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/percolator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/percolator --- # Percolator Development Skill ## What this Skill is for Use this Skill when the user asks for: - Percolator protocol development or integration - Perpetual futures risk engine implementation - Profit warmup and withdrawal mechanics - Global coverage ratio (`h`) calculations - Matcher program development (passive or vAMM) - Oracle integration (Pyth, Chainlink, or custom) - Liquidation and keeper operations - Funding rate mechanics - Formal verification with Kani - Testing and stress testing the protocol - CLI tool usage and scripting ## Core Concepts ### The Percolator Model Percolator treats profit differently from traditional exchanges: - **Capital (Senior Claims)**: User deposits, always withdrawable - **Profit (Junior Claims)**: Trading gains, must mature before withdrawal - **Global Coverage Ratio `h`**: Determines how much profit is actually backed - **Self-Healing**: System automatically recovers as conditions improve ### Key Formula ``` Residual = max(0, V - C_tot - I) h = min(Residual, PNL_pos_tot) / PNL_pos_tot Where: V = vault balance C_tot = total capital across all accounts I = insurance fund PNL_pos_tot = sum of all positive PnL ``` ### Why Not ADL? Traditional ADL forcibly closes profitable positions when insurance depletes. Percolator instead applies a pro-rata haircut on profit extraction, preserving positions. ## Default Stack Decisions 1. **Core Library**: Rust with formal verification (Kani) - 145 proofs covering conservation, principal protection, isolation - Zero unsafe code in critical paths 2. **Solana Program**: percolator-prog - Market initialization and configuration - User and LP account management - Keeper operations (liquidations, funding) 3. **CLI**: TypeScript with @solana/web3.js - User operations (deposit, withdraw, trade) - LP management - Keeper bots - Testing and monitoring scripts 4. **Matchers**: Separate Solana programs - Passive: Fixed spread pricing - vAMM: Dynamic pricing with impact - Custom: Implement your own pricing logic 5. **Oracles**: Multi-source support - Pyth Network (preferred for production) - Chainlink OCR2 - Oracle Authority (testing only) ## Operating Procedure ### 1. Classify the Task Layer - **Core risk engine**: Rust library modifications - **On-chain program**: Solana smart contract changes - **Matcher logic**: Pricing algorithm implementation - **CLI/tooling**: User-facing commands and scripts - **Testing**: Unit tests, integration tests, stress tests - **Verification**: Kani proofs and invariants ### 2. Understand the Invariants Always preserve: - **Conservation**: `Withdrawable ≤ Backed capital` - **Principal Protection**: Capital never haircut - **Isolation**: Account operations don't affect others (except via `h`) - **No Teleport**: Value can't appear/disappear ### 3. Implement with Percolator-Specific Correctness Be explicit about: - **Slab state**: Market configuration and nonce - **Account types**: User vs LP, capital vs profit - **Coverage ratio**: How `h` affects the operation - **Keeper requirements**: Fresh crank for risk-increasing trades - **Oracle freshness**: Timestamp and staleness checks - **Matcher security**: LP PDA signature verification ### 4. Add Tests - **Unit tests**: Core logic in Rust - **Kani proofs**: Formal verification of invariants - **Integration tests**: Full transaction flows on devnet - **Stress tests**: Worst-case scenarios (gap risk, insurance depletion) - **Pen tests**: Security and oracle manipulation ### 5. Deliverables Expectations When implementing changes, provide: - Exact files changed with diffs - Commands to build/test/deploy - Risk notes for anything touching: - Withdrawal mechanics - Liquidation logic - Oracle price handling - Matcher CPI calls - Insurance fund operations ## Progressive Disclosure (Read When Needed) - Core risk engine: [risk-engine.md](risk-engine.md) - Solana program architecture: [program-architecture.md](program-architecture.md) - Matcher development: [matchers.md](matchers.md) - CLI usage and scripting: [cli-guide.md](cli-guide.md) - Testing strategy: [testing.md](testing.md) - Oracle integration: [oracles.md](oracles.md) - Formal verification: [verification.md](verification.md) - Security considerations: [security.md](security.md) - Deployment guide: [deployment.md](deployment.md) ## Quick Reference ### Common CLI Commands ```bash # Initialize user account percolator-cli init-user --slab # Deposit collateral percolator-cli deposit --slab --user-idx --amount # Check best prices percolator-cli best-price --slab --oracle # Run keeper crank (required before trading) percolator-cli keeper-crank --slab --oracle # Trade via matcher percolator-cli trade-cpi --slab --user-idx --lp-idx \ --size --matcher-program --matcher-ctx --oracle # Withdraw capital percolator-cli withdraw --slab --user-idx --amount ``` ### Devnet Test Market ``` Slab: A7wQtRT9DhFqYho8wTVqQCDc7kYPTUXGPATiyVbZKVFs Oracle: 99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR (Chainlink SOL/USD) Program: 2SSnp35m7FQ7cRLNKGdW5UzjYFF6RBUNq7d3m5mqNByp Type: INVERTED (price = 1/SOL in USD) ``` ### Risk Parameters ``` Maintenance Margin: 5% Initial Margin: 10% Trading Fee: 10 bps (0.1%) ``` ## Important Warnings ⚠️ **EDUCATIONAL RESEARCH PROJECT** - NOT audited - NOT production ready - Do NOT use with real funds - For learning and testing only ⚠️ **Keeper Crank Requirement** - Risk-increasing trades require recent crank (within 200 slots / ~80s) - Run keeper before trading or use a keeper bot ⚠️ **Matcher Security** - MUST verify LP PDA signature in matcher programs - MUST create matcher context + LP atomically - Failure = potential fund theft ⚠️ **Inverted Markets** - Long = long USD (profit if SOL drops) - Short = short USD (profit if SOL rises) - Understand direction before trading --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/agentic-reserve) — claim your Tome and manage your conversions.