Project Documentation

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

View on GitHub

Architecture

PERColator consists of four specialized on-chain Solana programs:

Router Program

RoutqcxkpVH8jJ2cULG9u6WbdRskQwXkJe8CqZehcyr

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

  • Multi-slab atomic swaps with optimal routing
  • Vault custody & collateral management
  • Portfolio margin tracking across all slabs
  • Liquidation engine & risk monitoring
  • Cross-market capital efficiency

Slab Program

SLAB98WHcToiuUMMX9NQSg5E5iB8CjpK21T4h9ZXiep

Per-market order book and matching engine (v0: ~4KB, v1: 10MB unified account)

  • Price-time priority matching engine
  • Fill receipts for atomic settlement
  • Anti-toxicity protection (Kill Band, JIT)
  • O(1) freelist memory operations
  • Risk calculations (IM/MM)

AMM Program

AMMjkEeFdasQ8fs9a9HQyJdciPHtDHVEat8yxiXrTP6p

Automated market maker with constant product formula (x·y=k)

  • LP token minting & rewards distribution
  • Dynamic fee optimization
  • Deep liquidity pools for popular pairs
  • Impermanent loss protection mechanisms
  • Integration with Router for hybrid liquidity

Oracle Program

oracpooXY8Nnpx2JTLkrLiJsDaMefERUFFRktkAZ3ki

Real-time price feed aggregation with multi-source verification

  • Multi-source oracle aggregation
  • Mark price calculation for liquidations
  • Funding rate computation
  • Price verification & outlier detection
  • Cross-slab basis alignment

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 sourceprograms/amm/src/ - AMM program sourceprograms/oracle/src/ - Oracle program sourcesdk/typescript/ - TypeScript SDK for frontendcli/ - Rust CLI 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