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
Core Library: Rust with formal verification (Kani)
- 145 proofs covering conservation, principal protection, isolation
- Zero unsafe code in critical paths
Solana Program: percolator-prog
- Market initialization and configuration
- User and LP account management
- Keeper operations (liquidations, funding)
CLI: TypeScript with @solana/web3.js
- User operations (deposit, withdraw, trade)
- LP management
- Keeper bots
- Testing and monitoring scripts
Matchers: Separate Solana programs
- Passive: Fixed spread pricing
- vAMM: Dynamic pricing with impact
- Custom: Implement your own pricing logic
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
haffects 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
- Solana program architecture: program-architecture.md
- Matcher development: matchers.md
- CLI usage and scripting: cli-guide.md
- Testing strategy: testing.md
- Oracle integration: oracles.md
- Formal verification: verification.md
- Security considerations: security.md
- Deployment guide: deployment.md
Quick Reference
Common CLI Commands
# Initialize user account
percolator-cli init-user --slab <slab-pubkey>
# Deposit collateral
percolator-cli deposit --slab <slab> --user-idx <n> --amount <lamports>
# Check best prices
percolator-cli best-price --slab <slab> --oracle <oracle>
# Run keeper crank (required before trading)
percolator-cli keeper-crank --slab <slab> --oracle <oracle>
# Trade via matcher
percolator-cli trade-cpi --slab <slab> --user-idx <n> --lp-idx <n> \
--size <i128> --matcher-program <prog> --matcher-ctx <ctx> --oracle <oracle>
# Withdraw capital
percolator-cli withdraw --slab <slab> --user-idx <n> --amount <lamports>
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 — claim your Tome and manage your conversions.