Technical Documents
Summary
The perpetual futures protocol consists of three main layers:
- Self Hosted - Services we run: Web App, API Server, Indexer, Keeper Bot, PostgreSQL, and Redis
- External Services - Third-party services we use: RPC Provider and Oracle (Hermes/Pyth)
- On-chain Programs - Smart contracts deployed on Solana: Perps Program and Vault Program
The Web App connects users to the protocol. The API Server handles order submission and real-time data, serving from a PostgreSQL database that the Indexer keeps in sync with on-chain state. The Indexer subscribes to program account changes and logs via RPC, writes history records to PostgreSQL, and publishes Pub/Sub events to Redis. The API caches live state (balances, open positions, vault TVL) in Redis on RPC miss. Smart contracts on Solana execute the core protocol logic.
The protocol launches with two system vaults managed by the team: a Market-Making Vault that provides order book depth, and a Liquidation Vault that covers insolvent positions. External managers can create additional vaults using the same on-chain mechanism.
Service Architecture
Self Hosted (Run)
| Service | Description |
|---|---|
| Web App | Trading interface - connects wallet, displays order book, positions, and real-time prices |
| API Server | Serves REST endpoints and WebSocket streams. Reads history from PostgreSQL and live state from Redis (fetches from RPC on cache miss). Fetches VAAs from Hermes to build unsigned transactions for the frontend |
| Indexer | Subscribes to program account changes and logs via RPC. Writes history records (trades, closed positions, filled/canceled orders, account transactions) to PostgreSQL. Publishes Pub/Sub events to Redis to trigger WebSocket broadcasts. Runs hourly stats and leaderboard cron jobs |
| Redis | Two roles: (1) Pub/Sub broker - Indexer publishes events, API subscribes and broadcasts to WebSocket clients. (2) Live state cache - API caches RPC reads (balances, open positions, vault state) with a short TTL |
| Keeper Bot | Monitors open positions and submits liquidate_position for underwater accounts. Matching is fully on-chain (inline in place_order), not handled by the keeper |
External Services (Used)
| Service | Description |
|---|---|
| RPC Provider | Solana RPC connection for submitting transactions and subscribing to on-chain account changes (Helius, QuickNode) |
| Oracle / Hermes | Pyth price feed API - serves signed VAAs that are embedded in transactions and verified on-chain |
On-chain Programs (Deploy)
| Program | Description |
|---|---|
| Perps Program | Core protocol logic: order book (slab), position management, margin, funding rate, liquidations |
| Vault Program | Capital management: vault creation, deposits, withdrawals, LP share minting, NAV calculation |
Transaction Flow
This diagram shows how a user order flows through the system, from intent to on-chain execution.
Indexer Flow
This diagram shows how on-chain state changes propagate to the database and to connected clients.
Real-time / WebSocket
Notification Flow
After writing to the database, the Indexer publishes an event to Redis. All API instances subscribe to the same Redis channel and route each event to their connected WebSocket clients.
WebSocket Channels
| Channel | Trigger |
|---|---|
market:{symbol} | Market data update |
candles:{symbol}:{interval} | Candle close / live update |
orderbook:{symbol} | Order placed / filled / canceled |
trades:{symbol} | Fill event |
account:{id} | Account balance change |
positions:{wallet} | Position upserted |
orders:{wallet} | Order status change |
vault:{id} | Vault TVL / APR update |
All channels are public, no auth required to subscribe. This mirrors Solana itself: all on-chain account data is publicly readable. The API serves as a convenience layer over indexed state.