# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-agentic-reserve-agent-skill-percolator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agentic-reserve](https://agentstack.voostack.com/s/agentic-reserve)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [agentic-reserve](https://github.com/agentic-reserve)
- **Source:** https://github.com/agentic-reserve/AGENT_SKILL/tree/main/percolator

## Install

```sh
agentstack add skill-agentic-reserve-agent-skill-percolator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agentic-reserve](https://github.com/agentic-reserve)
- **Source:** [agentic-reserve/AGENT_SKILL](https://github.com/agentic-reserve/AGENT_SKILL)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-agentic-reserve-agent-skill-percolator
- Seller: https://agentstack.voostack.com/s/agentic-reserve
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.