Technical reference and integration guides

Insurance Pools - Each perpetual market has a dedicated, isolated pool of USDC capital provided by liquidity providers (LPs). This capital acts as a backstop: if a market becomes insolvent, the pool covers the deficit. LPs earn yield (denominated in basis points APY) in exchange for providing this capital.

Risk Scoring - A four-factor composite risk score is computed on-chain for each market every epoch. The score reflects the current risk state of the market and drives premium rates. Higher-risk markets pay more to the insurance pool. The four factors are: leverage ratio, open interest to liquidity ratio, price volatility, and funding rate variance.

Premium Routing - A portion of each perpetual market's trading fees is routed to PercoSec as insurance premiums. The Premium Manager program collects these fees and distributes them to LP shareholders at the end of each epoch proportional to their share of the pool.

Insolvency Handling - When a market reports a deficit that exceeds its margin buffer, the Insolvency Handler is invoked. It executes a deterministic waterfall: first drawing from the market's isolated pool, then (in future phases) from shared and reinsurance layers. Payouts are on-chain and auditable.

LP deposits USDC
  → InsurancePool mints LP shares to depositor
  → USDC held in pool PDA vault

Perp market generates trading fees
  → PremiumManager collects protocol fee share
  → At epoch end: fees distributed pro-rata to LP shareholders

Market insolvency event
  → InsolvencyHandler receives deficit report
  → Waterfall draws from InsurancePool vault
  → LP NAV decreases proportionally
  → Event emitted on-chain for transparency

PercoSec is built on Solana for three reasons: transaction throughput (400ms finality for keeper operations), low fees (keeper bots remain economically viable at scale), and Anchor's account model which makes per-market PDA isolation clean and auditable. The entire risk pipeline - from oracle read to premium settlement - executes on-chain.

deposit(amount: u64) - Transfers USDC from the caller's wallet into the pool vault. Mints LP shares proportional to current NAV. NAV per share = (total_deposits - pending_claims) / total_shares. If this is the first deposit, 1 share = 1 USDC.

withdraw(shares: u64) - Burns the specified LP shares and returns proportional USDC. Enforces epoch lock: withdrawals are only permitted if the depositor's lock period has elapsed. If utilization is above min_reserve_bps, partial withdrawals up to the available liquid reserve are permitted.

cover_deficit(amount: u64) - Called only by the Insolvency Handler via CPI. Transfers USDC from the vault to cover a market deficit. Reduces total_deposits and recalculates NAV.

update_apy(apy_bps: u16) - Called by the Premium Manager after epoch settlement to update the recorded APY for UI display.

// Pool PDA seeds
seeds = [
  b"insurance_pool",
  market_address.as_ref()
]
bump = canonical bump

// Vault PDA (token account)
seeds = [
  b"pool_vault",
  insurance_pool.key().as_ref()
]

The pool always maintains a minimum liquid reserve defined by min_reserve_bps. For example, at 800 bps (8%), a pool with $100,000 USDC must keep $8,000 unlocked at all times. Withdrawals that would breach this floor are rejected. This protects against a bank-run scenario where LPs attempt to exit before an insolvency event.

The composite score is a weighted sum of four normalized factors:

composite_score = (
  leverage_bps * 0.35 +
  oi_ratio_bps * 0.25 +
  volatility_bps * 0.20 +
  funding_variance_bps * 0.20
)

Grade bands:
  0    – 3000 bps  → Low      (green)
  3001 – 5500 bps  → Moderate (yellow)
  5501 – 7500 bps  → High     (orange)
  7501 – 10000 bps → Extreme  (red)

update_score(market, oracle_data) - Reads current oracle prices and market state, recomputes all four factors, updates the RiskMetrics account, and emits a ScoreUpdated event. Called by keepers every epoch.

set_premium_rate(market) - Reads the latest composite score and writes the new premium rate to the PremiumManager. Called immediately after update_score by the same keeper transaction.

Premium rates are expressed in basis points per epoch and are derived directly from the market's composite risk score. A market with a composite score of 4800 bps (Moderate) pays a higher premium rate than one at 2700 bps (Low). The premium rate function is monotonically increasing with the composite score.

// Approximate premium rate formula
premium_rate_bps = base_rate + (composite_score_bps * multiplier)

// Example at composite_score = 4800 bps:
// base_rate = 200 bps/epoch
// multiplier = 0.25
// premium_rate = 200 + (4800 * 0.25) = 1400 bps/epoch

At the end of each epoch, the keeper triggers settle_epoch. The program:

1. Reads total premiums collected from all market fee accounts
2. Calculates pro-rata distribution per LP share
3. Transfers USDC from fee vault to pool vault (compounding LP NAV)
4. Updates the pool's recorded APY based on last 7-day average
5. Emits an EpochSettled event with breakdown

An insolvency event is triggered when a keeper calls report_deficit with a deficit amount that exceeds the market's insolvency_threshold. Below the threshold, small deficits are absorbed by the market's own margin buffer. Above the threshold, the insurance pool is tapped.

1. Market margin buffer (held by perp market itself)
   ↓ if exhausted
2. Isolated Insurance Pool (PercoSec - per market)
   ↓ [Phase 2+] if exhausted
3. Cross-market shared pool
   ↓ [Phase 3+] if exhausted
4. Reinsurance tier (institutional backstop)
   ↓ if exhausted
5. Socialized loss (last resort - prevented in normal operation)

In Phase 1 (current), only the isolated pool exists. The handler calls cover_deficit on the InsurancePool via CPI, transferring USDC from the pool vault to the market. If the pool vault has insufficient funds, the remaining deficit is flagged as an UncoveredDeficit event - it does not silently socialize.

report_deficit(market, deficit_amount) - Called by a keeper or the perp market itself. Validates the deficit against the threshold, then initiates the waterfall. Emits InsolvencyEvent with full breakdown.

verify_deficit(market) - Read-only instruction that keepers use to check whether a market currently has a reportable deficit before submitting the full transaction.

• A deployed perp market program on Solana devnet or mainnet
• A funded deployer keypair with SOL for account rent
• The PercoSec program IDs set in your environment
• Anchor CLI and @coral-xyz/anchor installed

import { Program, AnchorProvider } from "@coral-xyz/anchor";
import { PublicKey } from "@solana/web3.js";

const INSURANCE_POOL_PROGRAM_ID = new PublicKey(
  "6qaEQCxNtrJLjPE8tepcsJykC1KWzoiGeo3UqdYEs8Bk"
);

// Derive the pool PDA
const [poolPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("insurance_pool"), marketAddress.toBuffer()],
  INSURANCE_POOL_PROGRAM_ID
);

await program.methods
  .initializePool({
    minReserveBps: 800,        // 8% minimum reserve
    insolvencyThreshold: 50_000_000_000, // 50,000 USDC (6 decimals)
    epochDuration: 100,        // epochs in slots
  })
  .accounts({
    pool: poolPda,
    market: marketAddress,
    authority: provider.wallet.publicKey,
    systemProgram: SystemProgram.programId,
  })
  .rpc();

const RISK_ENGINE_PROGRAM_ID = new PublicKey(
  "9Kg5ThbWTJh4UqGRB2aW9Ru6B6EpbA7B5SxGsB4hvcC3"
);

const [riskPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("risk_metrics"), marketAddress.toBuffer()],
  RISK_ENGINE_PROGRAM_ID
);

await riskEngineProgram.methods
  .initializeRiskMetrics()
  .accounts({
    riskMetrics: riskPda,
    market: marketAddress,
    authority: provider.wallet.publicKey,
    systemProgram: SystemProgram.programId,
  })
  .rpc();

const PREMIUM_MANAGER_ID = new PublicKey(
  "ucnc5EhhEUDjztqUdfLhb3bCrP3MWFUVZKYZULzYYRE"
);

await premiumManagerProgram.methods
  .initializePremiumState({
    epochDuration: 100,
  })
  .accounts({
    premiumState: premiumStatePda,
    pool: poolPda,
    market: marketAddress,
    authority: provider.wallet.publicKey,
    systemProgram: SystemProgram.programId,
  })
  .rpc();

After initialization, confirm all accounts are live on explorer:

• Pool PDA account exists and is_active = true
• RiskMetrics account exists with initial scores at 0
• PremiumState account linked to correct pool
• Run the first keeper tick to compute an initial risk score

import { getAssociatedTokenAddress } from "@solana/spl-token";

const USDC_MINT = new PublicKey(process.env.NEXT_PUBLIC_COLLATERAL_MINT);
const amount = 1_000_000_000; // 1,000 USDC (6 decimals)

// Get LP's USDC token account
const depositorUsdcAccount = await getAssociatedTokenAddress(
  USDC_MINT,
  wallet.publicKey
);

// Get pool vault address
const [poolVault] = PublicKey.findProgramAddressSync(
  [Buffer.from("pool_vault"), poolPda.toBuffer()],
  INSURANCE_POOL_PROGRAM_ID
);

await insurancePoolProgram.methods
  .deposit(new BN(amount))
  .accounts({
    pool: poolPda,
    vault: poolVault,
    depositorTokenAccount: depositorUsdcAccount,
    depositor: wallet.publicKey,
    tokenProgram: TOKEN_PROGRAM_ID,
  })
  .rpc();

// Fetch pool state
const pool = await insurancePoolProgram.account.insurancePool.fetch(poolPda);

// Your LP share balance (from your share token account)
const shareBalance = await connection.getTokenAccountBalance(yourShareAccount);

// NAV per share calculation
const navPerShare = pool.totalDeposits.toNumber() / pool.totalShares.toNumber();

// Your USDC value
const yourUsdcValue = shareBalance.value.uiAmount * navPerShare;

console.log({
  shares: shareBalance.value.uiAmount,
  navPerShare,
  usdcValue: yourUsdcValue,
  apyBps: pool.apyBps,
  utilizationBps: pool.utilizationRateBps,
});

Withdrawals are subject to the epoch lock period. If you deposited in epoch N, you can withdraw starting epoch N + lock_duration. The UI shows your unlock timestamp. Partial withdrawals are allowed as long as the pool maintains its minimum reserve ratio after the withdrawal.

const sharesToRedeem = new BN(500_000_000); // 500 shares

await insurancePoolProgram.methods
  .withdraw(sharesToRedeem)
  .accounts({
    pool: poolPda,
    vault: poolVault,
    depositorShareAccount: yourShareAccount,
    depositorTokenAccount: depositorUsdcAccount,
    depositor: wallet.publicKey,
    tokenProgram: TOKEN_PROGRAM_ID,
  })
  .rpc();

• LP capital can be reduced by insolvency events - NAV decreases proportionally
• High utilization markets carry higher risk of a claim reducing your position
• Lock periods prevent immediate exit - plan your liquidity accordingly
• Higher risk grade markets offer higher APY to compensate for higher expected loss

# Install dependencies
npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token dotenv

# .env for keeper
SOLANA_RPC_URL=https://api.devnet.solana.com
KEEPER_KEYPAIR_PATH=/path/to/keeper.json
INSURANCE_POOL_PROGRAM_ID=6qaEQCxNtrJLjPE8tepcsJykC1KWzoiGeo3UqdYEs8Bk
RISK_ENGINE_PROGRAM_ID=9Kg5ThbWTJh4UqGRB2aW9Ru6B6EpbA7B5SxGsB4hvcC3
PREMIUM_MANAGER_PROGRAM_ID=ucnc5EhhEUDjztqUdfLhb3bCrP3MWFUVZKYZULzYYRE
INSOLVENCY_HANDLER_PROGRAM_ID=5Gy6MyuJ8uyyK2ySsHQ8e8k27BMr848tY8iC71ymW13T

import { Connection, Keypair } from "@solana/web3.js";
import * as fs from "fs";

const EPOCH_SLOTS = 100;

async function keeperLoop() {
  const connection = new Connection(process.env.SOLANA_RPC_URL!);
  const keypair = Keypair.fromSecretKey(
    Uint8Array.from(JSON.parse(fs.readFileSync(process.env.KEEPER_KEYPAIR_PATH!).toString()))
  );

  let lastEpoch = 0;

  while (true) {
    const slot = await connection.getSlot();
    const currentEpoch = Math.floor(slot / EPOCH_SLOTS);

    if (currentEpoch > lastEpoch) {
      console.log(`Epoch ${currentEpoch} - running keeper tasks`);

      for (const market of ACTIVE_MARKETS) {
        await updateRiskScore(market, keypair);
        await setPremiumRate(market, keypair);

        if (currentEpoch % 1 === 0) {
          await settleEpoch(market, keypair);
        }

        await checkAndReportDeficit(market, keypair);
      }

      lastEpoch = currentEpoch;
    }

    await sleep(2000); // poll every 2 seconds
  }
}

keeperLoop().catch(console.error);

Each keeper instruction that successfully executes earns a small fee from the protocol treasury. The fee is sized to cover transaction costs plus a margin. Running a keeper is permissionless - no registration required. If your keeper is too slow and another bot submits first, the transaction will fail (account state already updated) and you pay only the failed transaction fee (~0.000005 SOL).

// GET /rest/v1/markets
// Returns all active markets with pool and risk data

SELECT
  markets.*,
  insurance_pools!market_id(*),
  risk_metrics!market_id(*),
  apy_snapshots!market_id(apy_bps, recorded_at)
FROM markets
WHERE active = true
ORDER BY created_at DESC;

// Response shape
{
  id: string,
  name: string,              // "BTC-PERP"
  base_token: string,        // "BTC"
  quote_token: string,       // "USDC"
  oracle_feed: string,       // "BTC/USD"
  max_leverage: number,
  insurance_pools: [{
    total_deposits_usdc: number,
    utilization_rate_bps: number,
    apy_bps: number,
    is_active: boolean,
  }],
  risk_metrics: [{
    composite_score_bps: number,
    grade: "Low" | "Moderate" | "High" | "Extreme",
    open_interest: number,
    liquidity: number,
  }]
}

// GET /rest/v1/oracle_snapshots?market_id=eq.{id}
{
  market_id: string,
  price_usd: number,
  confidence_interval_usd: number,
  slot: number,
  is_stale: boolean,
  recorded_at: string  // ISO timestamp
}

// GET /rest/v1/apy_snapshots?pool_id=eq.{id}&order=recorded_at.desc&limit=30
{
  pool_id: string,
  market_id: string,
  apy_bps: number,
  premiums_collected_7d: number,
  recorded_at: string
}

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

// Subscribe to risk metric changes
const channel = supabase
  .channel("risk-updates")
  .on(
    "postgres_changes",
    { event: "UPDATE", schema: "public", table: "risk_metrics" },
    (payload) => {
      console.log("Risk score updated:", payload.new);
    }
  )
  .subscribe();

• All programs are written in Anchor with full account constraint validation
• No unchecked arithmetic - all math uses checked operations
• CPI calls are authority-gated - only InsolvencyHandler can call cover_deficit
• No admin upgrade key on mainnet - programs will be immutable post-audit
• All state transitions emit events for off-chain monitoring

In scope:

• All four Anchor programs (Insurance Pool, Risk Engine, Premium Manager, Insolvency Handler)
• PDA derivation and account constraint logic
• Cross-program invocation authority checks
• Premium calculation and epoch settlement math

Out of scope:

• Frontend UI bugs (unless they expose a smart contract vulnerability)
• Denial of service via transaction spam
• Issues requiring a compromised admin keypair
• Third-party oracle failures (Pyth)

To submit a vulnerability, contact the PercoSec team through the official communication channels listed in the documentation. Include a clear description of the vulnerability, steps to reproduce, proof-of-concept code if applicable, and your assessment of impact and severity. Do not publicly disclose vulnerabilities before the team has had 7 days to respond. Responsible disclosures that follow this process are eligible for the full bounty reward.