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
• 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