Skip to main content

Architecture Overview

Runner Protocol is a Continuous Clearing Auction (CCA) system on Solana for fair token launches. It consists of three on-chain programs, an off-chain indexer, and a web frontend.

On-Chain Programs​

Launchpad (Orchestrator)​

Program ID: 8zfW4iLA7JagfotwCn8FT3SpdzUyGQ7CRSzjMwmJyK6F

The Launchpad program orchestrates the full lifecycle of a token launch:

  1. Token creation -- Mints a Token-2022 token with on-chain metadata (MetadataPointer extension)
  2. Escrow setup -- Creates escrow accounts for auction tokens, LP tokens, team allocation, proceeds, and fees
  3. CCA initialization -- Calls into CCA V2 via CPI to create the auction
  4. Settlement -- A four-step settlement flow: finalize auction, sweep proceeds, create Raydium CPMM pool, settle launch

The Launchpad enforces a state machine: Created -> EscrowsInitialized -> AuctionReady -> AuctionActive -> Finalized -> ProceedsSwept -> PoolCreated -> Settled.

CCA V2 (Auction Engine)​

Program ID: F5DdorN9nawhpQJZkfLYx2SpcWxSTZnwh3ZRyNtXP5do

The core auction engine implementing Uniswap's Continuous Clearing Auction mechanism. Key properties:

  • Single clearing price per block -- All fills within an auction block execute at the same price
  • Bid priority -- Higher maxPrice bids fill first; ties are resolved pro-rata
  • Price floor -- The clearing price never falls below the configured minimum (pMin)
  • Step-based supply schedule -- Tokens are released gradually according to configurable MPS (milli-basis points) steps
  • Epoch checkpoints -- Snapshots track cumulative supply unlocked and cleared at each auction block

The program manages six account types: AuctionConfig, AuctionState, SupplySchedule, Checkpoint, Tick, and Bid.

Raydium CPMM (DEX)​

After an auction graduates (raises sufficient currency), settlement creates a liquidity pool on Raydium's Constant Product Market Maker. The Launchpad program invokes Raydium CPMM via raw invoke_signed CPI.

Data Flow​

Creator                    Bidder                     Keeper/Anyone
  |                          |                            |
  | create_launch (3 txs)    | place_bid                  |
  |------------------------->|                            |
  |                          |--------------------------->|
  |                          | (auction active)           |
  |                          |                            |
  |                          | exit_bid / claim_tokens    |
  |                          |<---------------------------|
  |                                                       |
  | (after auction ends & graduates)                      |
  |                          finalize -> sweep ->          |
  |                          create_pool -> settle         |
  |<------------------------------------------------------|
  1. Launch Creation -- Creator submits three transactions to create a Token-2022 mint, set up escrows, and initialize the CCA auction
  2. Active Auction -- Bidders place bids with a max price and quote currency amount. The clearing price adjusts each auction block as supply unlocks
  3. Bid Management -- Bidders can withdraw out-of-range bids (below clearing price). In-range bids are locked until the auction ends
  4. Settlement -- After the auction ends or graduates, a permissionless four-step settlement creates a Raydium liquidity pool and distributes proceeds
  5. Trading -- The token trades on Raydium CPMM after settlement

Off-Chain Indexer​

The indexer watches both the CCA V2 and Launchpad programs via dual Solana WebSocket subscriptions and stores decoded account state in PostgreSQL.

  • Real-time updates via confirmed-commitment WebSocket subscriptions
  • Finality reconciliation re-fetches accounts at finalized commitment to ensure data integrity
  • REST API on port 3002 with endpoints for auctions, bids, launches, ticks, checkpoints, events, and stats
  • WebSocket endpoint at /ws for push-based updates to connected clients
  • Cursor-based pagination for list endpoints

Frontend​

The frontend is a Next.js 14 application using the App Router:

  • React Query v5 for server state management with smart polling intervals (10s for active auctions, 60s for ended)
  • Solana Wallet Adapter for wallet connectivity
  • SDK instruction builders for transaction construction (no @coral-xyz/anchor dependency)
  • Q96 transform pipeline for displaying prices: BigInt decode from on-chain data, decimal adjustment, human-readable formatting

Key Design Decisions​

  • No Anchor dependency in frontend/SDK -- Instructions use precomputed discriminators (sha256("global:<snake_case_name>")[..8]) and manual serialization to avoid Anchor version conflicts
  • Token-2022 -- All launched tokens use Token-2022 with MetadataPointer for on-chain metadata
  • Q96 fixed-point math -- Prices are stored as 128-bit fixed-point numbers with 96 fractional bits (price = value / 2^96)
  • Permissionless settlement -- The four-step settlement can be executed by any signer (keeper pattern)