Integration Architecture

System architecture and data flow

The complete technical architecture of PercoSec - from on-chain programs to frontend interfaces, with data flow specifications.

System Architecture Diagram

The architecture separates concerns across four layers: interface, application, data, and on-chain execution. On-chain programs are the canonical source of truth.

graph TD
  subgraph Interface ["Interface Layer"]
    FE[Frontend<br/>Next.js + TypeScript]
  end

  subgraph Application ["Application Layer"]
    API[API Gateway<br/>REST + WebSocket]
  end

  subgraph Data ["Data Layer"]
    IDX[Indexer<br/>Rust + PostgreSQL]
    RPC[Solana RPC Node]
  end

  subgraph Execution ["Execution Layer (Off-chain)"]
    KPR[Keeper Network<br/>Permissionless]
  end

  subgraph OnChain ["On-chain Programs (Solana)"]
    RE[Risk Engine<br/>Program]
    PM[Premium<br/>Manager]
    IP[Insurance Pool<br/>Program]
    IH[Insolvency<br/>Handler]
    ORACLE[Pyth Network<br/>Oracle]
  end

  FE -->|REST / WS| API
  API -->|Query| IDX
  API -->|Direct RPC| RPC
  IDX -->|Subscribe events| RPC
  KPR -->|Execute IX| RE
  KPR -->|Liquidate / Settle| IP
  RE -->|Read price| ORACLE
  RE -->|Trigger rates| PM
  PM -->|Route premiums| IP
  IP -->|Claim evaluation| IH
  IH -->|Payout| IP
  RPC -->|Program state| IDX

Diagram format: Mermaid graph TD. Render at mermaid.live or integrate with documentation tooling.

Insolvency Claim Data Flow

sequenceDiagram
  participant K as Keeper
  participant PP as Perp Market Program
  participant RE as Risk Engine
  participant IP as Insurance Pool
  participant IH as Insolvency Handler
  participant IDX as Indexer

  K->>PP: check_liquidation(position_id)
  PP-->>K: returns: position breaches margin
  K->>PP: execute_liquidation(position_id)
  PP->>PP: compute_fill_price()
  PP->>PP: compute_deficit = entry - fill
  PP->>IH: report_deficit(market_id, deficit_amount)
  IH->>IH: check deficit > threshold
  alt deficit > threshold
    IH->>IP: request_payout(market_id, deficit)
    IP->>IP: verify_pool_balance()
    IP->>IH: release_funds(amount)
    IH->>PP: cover_deficit(amount)
    IH->>IDX: emit ClaimEvent
  else deficit <= threshold
    IH->>IDX: emit NoClaim log
  end
  IDX->>IDX: store claim history

Component Specifications

Frontend

Interface

Next.js, TypeScript

Web application providing market dashboards, pool management UI, risk score displays, and real-time position monitoring. Connects to the API layer for data aggregation.

depends on:API Gateway

API Gateway

Application

Node.js, REST + WebSocket

Aggregates data from the on-chain indexer, exposes RESTful endpoints for pool state queries, and broadcasts real-time updates via WebSocket connections. Stateless - all canonical state lives on-chain.

depends on:IndexerRPC Node

Indexer

Data

Rust, PostgreSQL

Subscribes to Solana program event logs and parses all PercoSec-emitted instructions. Maintains a queryable off-chain replica of pool states, position histories, risk scores, and claim events.

depends on:Solana RPCRisk Engine Program

Keeper Network

Execution

Rust, Solana SDK

Distributed network of bots responsible for triggering on-chain liquidations, epoch settlements, and premium calculations when conditions are met. Permissionless - any party can run a keeper and earn fees.

depends on:Insurance Pool ProgramRisk Engine Program

Risk Engine Program

On-chain

Anchor (Rust), Solana

Core Solana program that computes and stores risk scores for each market. Reads oracle prices, open interest, leverage data, and funding history to produce composite risk scores on a per-epoch basis.

depends on:Pyth OraclePremium Manager

Premium Manager

On-chain

Anchor (Rust), Solana

Manages premium rate calculations based on current risk scores. Routes premium inflows from market accounts to the corresponding insurance pool. Updates rates on each epoch cycle.

depends on:Risk Engine ProgramInsurance Pool Program

Insurance Pool Program

On-chain

Anchor (Rust), Solana

Manages capital provider deposits and withdrawals, maintains per-market pool balances, tracks provider shares, and enforces epoch-based lock periods. The primary fund custody program.

depends on:Insolvency HandlerPremium Manager

Insolvency Handler

On-chain

Anchor (Rust), Solana

Evaluates insolvency claims, verifies deficit thresholds against on-chain market state, and executes the waterfall payout logic. Emits claim events consumed by the indexer for historical tracking.

depends on:Insurance Pool Program

Data Flow Specifications

Data flow specifications for key system events
Event	Data Path	Frequency	Latency
Market Price Update	Pyth Oracle → Risk Engine Program → Risk Score Account → Indexer → API → Frontend	Every 400ms (Solana slot)	<1s end-to-end
Position Liquidation	Keeper detects breach → Liquidation IX → Insurance Pool deficit check → Insolvency Handler (if deficit) → Indexer logs claim	Event-driven	<1 block (~400ms)
Premium Accrual	Market fee account → Premium Manager → Pool balance update → Indexer → API	Per epoch (15 min)	1 epoch
Capital Deposit	User wallet → Insurance Pool Program → Share issuance → Indexer → API balance update	On-demand	~400ms (1 block)
Risk Score Recalculation	Risk Engine Program reads oracle + OI data → Computes weighted score → Writes to risk account → Triggers premium recalculation	Every epoch	1 epoch

On-chain Account Model

All PercoSec state is stored in Program Derived Accounts (PDAs) seeded by market IDs, provider pubkeys, and epoch numbers. The account structure is designed for composability.

classDiagram
  class MarketConfig {
    +Pubkey market_id
    +Pubkey oracle_feed
    +u64 max_leverage
    +u64 insolvency_threshold
    +u64 min_reserve_ratio
    +bool active
  }

  class InsurancePool {
    +Pubkey market_id
    +u64 total_deposits
    +u64 available_balance
    +u64 epoch_premium_accrued
    +u64 utilization_rate
    +u64 last_update_epoch
  }

  class ProviderPosition {
    +Pubkey provider
    +Pubkey market_id
    +u64 deposited_amount
    +u64 shares
    +u64 entry_epoch
    +u64 unlock_epoch
  }

  class RiskScore {
    +Pubkey market_id
    +u64 composite_score
    +u64 leverage_factor
    +u64 oi_ratio_factor
    +u64 volatility_factor
    +u64 funding_variance_factor
    +i64 last_updated_at
  }

  class ClaimRecord {
    +Pubkey market_id
    +u64 deficit_amount
    +u64 payout_amount
    +i64 timestamp
    +bool fully_covered
  }

  MarketConfig "1" --> "1" InsurancePool
  MarketConfig "1" --> "1" RiskScore
  InsurancePool "1" --> "*" ProviderPosition
  InsurancePool "1" --> "*" ClaimRecord