Project Documentation

Complete technical overview of PERColator - A sharded perpetual exchange protocol on Solana

View on GitHub

Architecture

PERColator consists of two main on-chain Solana programs:

Router Program

RoutR1VdCpHqj89WEMJhb6TkGT9cPfr1rVjhM3e2YQr

Global coordinator managing collateral, portfolio margin, and cross-slab routing

  • Vault - Collateral custody per asset
  • Escrow - Per-user pledges with anti-replay nonces
  • Cap - Time-limited debit authorization tokens (2min TTL)
  • Portfolio - Cross-margin tracking across slabs
  • SlabRegistry - Governance-controlled registry

Slab Program

SLabZ6PsDLh2X6HzEoqxFDMqCVcJXDKCNEYuPzUvGPk

Per-market order book and matching engine in a single 10MB account

  • SlabState - Header + 5 memory pools (64KB each)
  • Order book with price-time priority
  • CLOB matching engine
  • Risk calculations (IM/MM)
  • Anti-toxicity mechanisms (Kill Band, JIT Penalty, ARG)

Completed Features

Core data structures (Router & Slab)
Memory pools with O(1) freelists
Order book management
Reserve & Commit operations
Risk calculations (IM/MM)
Capability system (scoped debits)
Funding rate system
Instruction handlers
Router orchestration (multi-slab)
Liquidation engine
Account initialization helpers
BPF deployment scripts
TypeScript SDK
CLI Tools
140+ passing tests
Integration tests (Surfpool)

Technology Stack

Pinocchio v0.9.2

Zero-dependency Solana SDK for on-chain programs

Surfpool

Local Solana test validator with mainnet state

Rust (no_std)

Zero allocations, panic = abort for BPF

Key Files & Documentation

README.md - Complete project documentationplan.md - Full protocol specificationprograms/router/src/ - Router program sourceprograms/slab/src/ - Slab program sourcesdk/typescript/ - TypeScript SDK for frontendcli/ - Command-line toolsbuild-bpf.sh - Build script for Solana BPFdeploy-devnet.sh - Deployment script

Design Invariants

Safety

Slabs cannot access Router vaults directly
Slabs can only debit via unexpired Caps
Total debits ≤ min(cap.remaining, escrow.balance)
No cross-contamination between users/slabs

Matching

Price-time priority strictly maintained
Reserved qty ≤ available qty always
Book links acyclic and consistent
Pending orders never match before promotion

Anti-Toxicity Mechanisms

Kill Band

Reject orders if mark price moved beyond threshold since batch open

JIT Penalty

DLP orders posted after batch_open get no rebate, discouraging toxic flow

ARG Tax

Roundtrip trades within the same batch are taxed/clipped to prevent gaming

← Back to Home