📚 Documentation
Every contract, every endpoint, every audit — public on GitHub. Browse by category below or jump straight to the org.
🚀 Getting Started
Protocol README
High-level overview of the Lumina parametric insurance protocol and how the V5.1 contracts fit together.
API server README
How to run the lumina-api locally, environment variables, and the public + agent endpoint surface.
AI Agent Quick Start
Five-minute path from zero to first policy purchase via the API. Read this before anything else if you operate a bot.
🤖 For AI Agents
SKILL spec (canonical)
The full canonical skill specification consumed by AI agents. Lists every operation an agent can perform.
Configure API client
Env vars, base URL, x-api-key header, retry strategy. The setup any agent needs before calling other endpoints.
Generate API key
How to obtain an agent API key (admin-only today, self-service on roadmap). Format, storage, rate limits.
Buy policy as Agent
Relayer pattern: agent posts an authenticated request; the API pays gas and calls purchasePolicyFor on-chain.
Redeem matured bond via API
Agent-side BondVault.redeemBond — POST /api/v1/redeem with epochId + usdAmount. Returns LUMINA to the holder.
Health check
Public unauthenticated endpoint for monitors and uptime probes. Use it on startup before issuing real calls.
📜 Smart Contracts (source)
LuminaTokenV2.sol
ERC-20 + ERC-20Burnable + UUPS proxy. 100M fixed supply, no mint, BURNER_ROLE for TWAPBurner.
FounderVesting.sol
8M LUMINA locked behind 2-of-3 AltSeason conditions sustained 7 days, then 3 tranches every 31 days. 4-year fallback.
TreasuryVesting.sol
3M LUMINA, 180-day lock then max 250k/month drip release. UUPS upgradeable.
BondVault.sol
Single ERC-1155 vault holding the 70M LUMINA reserve. Backs every claim payout in the protocol.
ClaimBond.sol
ERC-1155 bond representation. 1 token = $1 face value (integer dollars, not 6-dec USDC).
PolicyManagerV2.sol
Buy / redeem / cancel policies. Computes premium = cover × payoutRatio × triggerProb × margin.
CoverRouterV2.sol
Routes premium USDC into the TWAPBurner and updates capacity counters atomically.
TWAPBurner.sol
Receives USDC from premiums + marketplace fees, executes multi-DEX buy & burn of LUMINA. Adaptive distribution.
AdaptiveFeeDistributor.sol
Dynamic 4-bucket distribution (burn / buyback / ops / maintenance) consumed by TWAPBurner when adaptive mode is on.
LuminaBondMarketplace.sol
Secondary marketplace for bonds. 3% fee on every trade routes back through TWAPBurner.
BuybackEngine.sol
Commit-reveal MEV-protected buyback executor. Pulls from buybackReserve when conditions trigger.
LuminaOracleV2.sol
EIP-712 signed price proofs from the off-chain signer. Verifies signatures against the trusted oracleKey. The 9 V5.1 shields call verifyPriceProofEIP712 here in their _doVerifyAndCalculate path. Replaces the pre-launch MockShieldOracle.
CapacityOracle.sol
Reads available BondVault capacity in USD using a 1h TWAP of LUMINA price (not spot — anti-MEV).
SolvencyOracle.sol
Monitors the BondVault solvency floor (125%). Used by burnFromReserves to block insolvent burns.
ShieldKeeper.sol
Chainlink Automation keeper that expires policies and triggers payouts when oracle conditions are met.
UniswapV3Adapter.sol
IDexRouter implementation for Uniswap V3. Used by TWAPBurner for the primary buy & burn route.
AerodromeAdapter.sol
IDexRouter implementation for Aerodrome (Base-native DEX). Sequential fallback if Uniswap leg fails.
BaseShield.sol
Abstract base for every shield product. Holds shared payout, pause, and replay-protection logic.
FlashBTCShield1h.sol
Flash crash protection for BTC over a 1-hour window. Triggers on % drop vs reference price.
FlashBTCShield4h.sol
Flash crash protection for BTC over a 4-hour window.
FlashBTCShield24h.sol
Flash crash protection for BTC over a 24-hour window.
FlashBTCShield48h.sol
Flash crash protection for BTC over a 48-hour window.
FlashETHShield1h.sol
Flash crash protection for ETH over a 1-hour window.
FlashETHShield24h.sol
Flash crash protection for ETH over a 24-hour window.
FlashETHShield48h.sol
Flash crash protection for ETH over a 48-hour window.
MicroDepegShield.sol
Micro-depeg protection for USDT (and similar). Triggers on small but sustained price deviation.
RateShockShield.sol
Rate-shock protection — triggers when Aave V3 USDC borrow rate exceeds 10% APY.
CEXLiquidityReserve.sol
Holds the 14M LUMINA earmarked for CEX/DEX liquidity provisioning at launch.
MaintenanceReserve.sol
Receives the maintenance bucket from TWAPBurner adaptive distribution. Funds operational upkeep.
🔐 Architecture & Integrations
Aave V3 integration
How V5.1 uses Aave V3 read-only as price oracle (RateShockShield + FounderVesting Condition C). NOT for yield.
Cross-contract integration map
How the 9 shields, BondVault, ClaimBond, and CoverRouterV2 connect. Auditor reference.
Aave audit chapter
Audit deep-dive on the Aave V3 integration. Covers manipulation surfaces and 2-of-3 mitigation in FounderVesting.
🛡️ Security & Audits
Security policy
Reporting process, scope, bug bounty, V5.1 contracts in scope (single BondVault + 9 shields), Aave dependency.
Security audit V5
Latest internal audit report covering V5.1 architecture (renamed from SECURITY-AUDIT-V4 — content was already V5.1).
Phase 4 audit report
Phase 4 internal audit covering the bond + marketplace flow.
Threat model
Adversarial framing — who can attack what, oracle manipulation surfaces, governance assumptions.
Anti-fraud playbook
Operational guide for detecting and responding to abuse patterns (spam policies, oracle manipulation attempts).
🚢 Deployment
Deploy V5 checklist
Pre-deploy invariants and post-deploy verification for the V5.x family of contracts.
Deploy V5 order
Exact deployment sequence (token → vault → router → shields) with rationale for ordering.
Environment variables
All env vars needed for deploy + post-deploy. Includes the Aave V3 oracle address (read-only).
Mainnet deploy runbook
Step-by-step runbook for the production mainnet deployment, including go/no-go gates.
⚖️ Governance & Operations
Access control matrix
Every privileged role across the protocol — who can call what, who holds the keys, with rotation policies.
Roles and responsibilities
Governance + operational roles defined: who signs what, decision frameworks, escalation paths.
Multisig policies
Signing thresholds, quorum, timelocks, and key rotation for the governance multisig.
Daily operations runbook
Day-to-day operator tasks: monitoring, periodic verifications, alerts triage.
Incident response runbook
Step-by-step guide for triaging and recovering from production incidents (RPC down, oracle stale, contract pause).
📊 Tokenomics & Economics
Token distribution (100M LUMINA)
The five _mint() calls in LuminaTokenV2.initialize() that hardcode the 70 / 14 / 8 / 5 / 3 split (BondVault / CEX / Founder / LBP / Treasury).
Max supply + burn role
MAX_SUPPLY constant (100M × 1e18, fixed, no mint function) and the BURNER_ROLE granted only to the TWAPBurner contract.
Burn engine — fallback distribution
TWAPBurner default 4-bucket split when adaptive mode is off: 85% burn, 8% buyback, 5% maintenance, 2% ops (in BPS, sums to 10000).
Premium formula
CoverRouterV2.purchasePolicy: premium = coverage × payoutRatioBps × triggerProbBps × marginBps / 10000³, with a 1-unit USDC ($0.000001) floor.
Founder vesting (8M LUMINA)
All FounderVesting constants: 8M total, 3 tranches every 31 days, 2-of-3 oracle conditions sustained 7 days (ETH/BTC > 0.050, ETH > $4k, Aave borrow > 7%), 1460-day fallback.
Treasury vesting (3M LUMINA)
TreasuryVesting constants: 3M total, 180-day initial lock, then max 250k/month drip release. Math floor is 18 months until fully drawn.
Bond face value + maturity
ClaimBond NatSpec: 1 ERC-1155 token = $1 USD at maturity (integer dollars, not 6-dec USDC). Bonds vest 100% at maturity — no partial unlock.
Bond maturity period (730 days)
BondVault.BOND_MATURITY_SECONDS — every newly issued bond matures exactly 730 days (24 months) after issuance.
Premium math — edge cases (audit)
Audit deep-dive on the premium formula: rounding behavior, integer overflow surfaces, BPS-cube precision loss. Companion analysis to the on-chain formula above.
🗺️ Roadmap
📜 Historical
Changelog
Version-by-version change log. Older entries reference V1/V2/V4 by design — current architecture is V5.1.
V1 deprecated contracts
Inventory of legacy V1/V2/V4 contracts no longer in scope. Kept to prevent re-deployment of stale addresses.
Security audit V3 (final)
Historical V3 audit for reference. Most findings rolled forward into V4 and V5; check SECURITY-AUDIT-V5 for current.