PERCOLATOR

Sharded Perpetual Exchange Protocol

Capital Efficiency Through Cross-Slab Portfolio Margin

CA: 77mP6LDQSbYzy7APZ52zftZoeBf8NfYALxWqjQMMpump

Unit Tests Passing

∞

Capital Efficiency

~4KB

Slab State (v0)

On-Chain Programs

THE KILLER PROOF$0
margin required for zero net exposure

                Instead of $10,000 on traditional exchanges!
            

Overview

Percolator is a sharded perpetual exchange protocol for Solana that achieves infinite capital efficiency through cross-slab portfolio margin. Users can execute offsetting positions across multiple markets with zero margin requirement when net exposure is zero.

v0 Architecture

Router Program
Global Coordinator
Portfolio Margin

↓

Slab A
BTC-PERP
$50,000

Slab B
BTC-PERP
$50,010

Slab C
ETH-PERP
$3,000

The Proof: Capital Efficiency

❌ Traditional Exchange

Long 1 BTC @ $50,000
Margin: $5,000

Short 1 BTC @ $50,010
Margin: $5,000

Total Capital Required: $10,000
Profit: $10
ROI: 0.1%

✓ Percolator

Long 1 BTC Slab A @ $50,000

Short 1 BTC Slab B @ $50,010

Net Exposure: 0 BTC

Total Capital Required: $0
Profit: $10
ROI: ∞

Capital Efficiency Savings: $10,000 (100%)

Architecture

1. Router Program

Program ID: RoutR1VdCpHqj89WEMJhb6TkGT9cPfr1rVjhM3e2YQr

The global coordinator managing collateral, portfolio margin, and cross-slab routing.

State Structures:

Vault - Collateral custody per asset mint
Portfolio - Cross-margin tracking with exposure aggregation across slabs
SlabRegistry - Governance-controlled registry with version validation

2. Slab Program

Program ID: SLabZ6PsDLh2X6HzEoqxFDMqCVcJXDKCNEYuPzUvGPk

LP-run perp engines with ~4KB state in v0 (10MB budget for v1).

struct SlabState {
    header: SlabHeader,       // 256 bytes - metadata + seqno
    quote_cache: QuoteCache,  // 256 bytes - best 4 bid/ask levels
    book: BookArea,           // 3KB - price-time order queues
}
            

3. v0 Instructions

Initialize - Setup registry and slabs
InitializePortfolio - Create user portfolio
Deposit/Withdraw - Collateral management
ExecuteCrossSlab - Main v0 instruction (Router)
CommitFill - Execute fill on slab

Key Features

⚡

Sharded Architecture

Multiple independent "slabs" run by LPs, coordinated by the Router. Unlimited scalability.

💰

Portfolio Margin

Margin calculated on net exposure across all slabs, not per-market. Capital efficient.

🔒

Atomic Execution

Order splits and commits across multiple slabs in a single transaction.

🛡️

Security by Design

Slabs cannot access Router vaults directly. Complete isolation between markets.

📊

Proven Concept

54 unit tests passing, covering all critical scenarios including capital efficiency proof.

🚀

v0 Simplified

Streamlined architecture (~1000 LOC) that proves the core thesis.

Project Status

✓Completed

DONE v0 simplified architecture (Router + Slab programs)
DONE 54 unit tests passing (100%)
DONE Portfolio exposure tracking across slabs
DONE Net exposure calculation
DONE Margin requirements based on net exposure
DONE QuoteCache and FillReceipt structures
DONE Rust build system working

🚧 In Progress

WIP Solana CLI and Platform Tools installation
WIP v0 integration tests
WIP Real CPIs Router → Slab

📋 Next Steps

Compile with cargo build-sbf
Deploy to local validator
Complete end-to-end tests
Client SDK (TypeScript/Rust)
Web trading interface
Security audits

Test Coverage

$ cargo test

running 54 tests

percolator-common (27 tests)
✓ VWAP calculations
✓ PnL calculations
✓ Funding payments
✓ Tick/lot alignment
✓ Margin calculations

percolator-router (7 tests)
✓ Vault operations
✓ Portfolio tracking
✓ Margin aggregation
✓ Exposure tracking

percolator-slab (20 tests)
✓ Pool allocation
✓ Header validation
✓ Reserve operations
✓ Size constraint (≤10 MB)

test result: ok. 54 passed; 0 failed; 0 ignored
            

v0 Critical Tests

Capital Efficiency Test - Proves long + short = $0 IM
Atomic Split Test - Multi-slab atomic execution
Portfolio Netting Test - Net exposure calculation
Margin Requirements Test - Requirement verification
Order Validation Test - Order validation logic

Technology Stack

Blockchain: Solana
Framework: Pinocchio v0.9.2 (zero-dependency Solana SDK)
Language: Rust (no_std, zero allocations, panic = abort)
Build: cargo build-sbf
Tests: 54 unit tests + integration test templates

Code Reduction~5,000 LOC
Complex Initial Design
→
~1,000 LOC
v0 Simplified

                80% reduction while proving the core concept!
            

Why Percolator?

Maximum Capital Efficiency: Enable arbitrage and hedging strategies with near-zero margin
Scalability: Sharded architecture allows unlimited slab additions
Security: Complete isolation between slabs, no cross-contamination risk
Flexibility: Each LP can innovate on their slab independently
Performance: Fast atomic execution on Solana

📚 Documentation & Getting Started

Quick Start

1. Clone the repository:
git clone https://github.com/TheMasterPump/Percolatorv0.git

2. Build the project:
cargo build --release

3. Run the tests:
cargo test

4. Run the demo:
demo.bat (Windows) or ./demo.sh (Mac/Linux)

Program IDs

Router Program:
RoutR1VdCpHqj89WEMJhb6TkGT9cPfr1rVjhM3e2YQr

Slab Program:
SLabZ6PsDLh2X6HzEoqxFDMqCVcJXDKCNEYuPzUvGPk

Key Features

Cross-Slab Portfolio Margin: Zero margin for offsetting positions
Time-Limited Capabilities: Security through expiring permissions
Atomic Execution: All-or-nothing transaction guarantees
Slab Isolation: Complete independence between markets
LP Flexibility: Each LP controls their own slab parameters

Resources & Files

📄 README.md - Complete technical documentation
🚀 START_HERE.md - Quick start guide
🧪 HOW_TO_TEST.md - Testing instructions
📊 PRESENTATION.md - Full presentation
📋 plan.md - Detailed technical specification
🏗️ V0_DESIGN.md - Simplified v0 design
🌐 DEPLOY_TO_GITHUB.md - GitHub Pages setup

Development Roadmap

✅ Step 1 - v0 (Current)

Core router and slab programs
Portfolio margin calculation
54 unit tests passing
Documentation and demo

🔄 Step 2 - Testnet

Deploy to Solana devnet
Community testing
UI development
Security audit preparation

⏳ Step 3 - Mainnet

Professional security audits
Mainnet deployment
LP onboarding
Public launch