> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumina-org.com/llms.txt > Use this file to discover all available pages before exploring further. # Architecture > How the V5.4 contracts fit together. See [/concepts/lifecycle](/concepts/lifecycle) for the end-to-end flow (purchase → trigger → bond → wait/sell decision) and [/concepts/adapters](/concepts/adapters) for why each slim shield is fronted by a `FlashShieldAdapter` UUPS proxy. ## High-level (V5.4) ``` Agent ──► API ──► Relayer ──► CoverRouterV2 ──► PolicyManagerV2 │ │ ▼ ▼ AdaptiveFeeDistributor FlashShieldAdapter (UUPS) (85% TWAPBurner / │ 8% buyback / ▼ 2% ops / BaseFlashShield (slim) 5% maintenance) ├ Chainlink BTC/ETH └ Sequencer uptime feed │ ▼ on trigger BondVault.issueBond │ ▼ ClaimBond ERC-1155 (730d maturity) │ ▼ redeem $LUMINA → holder (throttle 1.08%/wk) ``` ## Contracts ### CoverRouterV2 * Single entry point for policy purchases (both relayer-paid and direct). * `purchasePolicyFor(productId, cover, asset, buyer)` — relayer-only. * `purchasePolicy(productId, cover, asset)` — direct (msg.sender = buyer). * Maintains the relayer allowlist via `setRelayer(addr, true)`. * Routes the USDC premium through `AdaptiveFeeDistributor` on every purchase. * Dual pause: local `paused()` flag + global `GlobalPauseRegistry` (audit fix M-7). ### PolicyManagerV2 * Stores policy state (`policyId → buyer, cover, premium, priceSnapshot, …`). * `productShield(productId)` returns the **adapter** address (not the slim shield directly). * `removeProduct(bytes32)` (Sprint Cleanup, 2026-05-22) — swap-and-pop cleanup of the `productIds[]` array to drop duplicate or stale entries. * `productActive` mapping (audit fix H-5) — admin can deactivate products without touching the on-chain shield. ### FlashShieldAdapter (V5.4, NEW) * UUPS upgradeable proxy. One adapter per slim shield. * Bridges the legacy `PolicyManagerV2.IShieldV2` (struct-based) surface to the slim `BaseFlashShield` (positional-args) surface introduced in Sprint T-30a. * Holds its own `productId` and forwards `createPolicy` / `verifyAndCalculate` / `getPolicyInfo` to the underlying shield. See [Adapters](/concepts/adapters). ### BaseFlashShield + FlashBTC/ETHShield (per-product) * One slim shield per V5.4 product. 6 active: BTC × (1h / 24h / 48h) + ETH × (1h / 24h / 48h). * **Drop-from-purchase mechanic**: snapshots Chainlink spot at `createPolicy`; on `verifyAndCalculate` re-reads spot 3× in-tx and takes the MIN as the conservative reference. * `_triggerDropBps()` per shield: 250 / 600 / 1000 (BTC) and 400 / 850 / 1400 (ETH). * Sequencer-uptime guard (`whenSequencerActive`) — on Base mainnet the feed is `address(0)` (treated as up). * `MAX_PRICE_STALENESS = 3600s` (1 hour). ### BondVault * Holds the 70M LUMINA reserve backing bonds. * `issueBond(buyer, faceValueUSD)` — called by PolicyManagerV2 on trigger; emits `BondIssued`. * `redeemBond(epochId, usdAmount)` — mints \$LUMINA at current market price. * **Throttle**: `MAX_REDEMPTION_PER_EPOCH_BPS = 108` (1.08% of vault per 7-day epoch). Over-cap redemptions are FIFO-queued — bond burned at queue time, LUMINA paid by `processQueue()` in the target epoch. See [BondVault throttle](/concepts/bondvault-throttle). * `availableCapacityUSD()` — uses 1-hour TWAP (audit fix M-6) instead of spot. * `burnFromReserves` — capped at 5% of vault reserves per tx (audit fix M-11). ### ClaimBond * ERC-1155. `tokenId == epochId` (YYYYMM). * All bonds maturing the same month are interchangeable. \$1 face per unit. * Held by buyers, transferable, listable on marketplace. ### LuminaBondMarketplace * Secondary market for ClaimBonds. Address `0xfB3ec1B507DE8a7dB50691a26f872360F0EF71AB`. * `list(bondId, amount, totalPriceUsdc)` — anti-spam floor (audit fix M-3). * `buy(listingId)` — atomic purchase, USDC settlement. * 3% protocol fee (1.5% seller + 1.5% buyer; `SELLER_FEE_BPS=150` / `BUYER_FEE_BPS=150`) routed through `AdaptiveFeeDistributor` (same 85/8/2/5 split). ### LuminaOracleV2 * Chainlink BTC/USD + ETH/USD feeds on Base mainnet + a Lumina-signed proxy for non-Chainlink assets. V5.4 flash shields read Chainlink directly. ### AdaptiveFeeDistributor * Routes premiums + marketplace fees: **85% → TWAPBurner**, 8% → buyback, 2% → ops, 5% → MaintenanceReserve. * Healthy split is constant in V5.4; future versions may introduce solvency-aware splits. ### TWAPBurner V2 * Auto-burn on every \$500 in fees or every 50 purchases. * Sequential DEX fallback for resilience (audit fix M-12). * 1-hour TWAP swap to mitigate MEV. ### FounderVesting V2 * 8M LUMINA, non-proxy, three independent unlock paths (first to satisfy wins): * **PATH 1**: 2-of-3 conditions sustained 1 day — (A) ETH/BTC > 0.050, (B) ETH > \$4,000, (C) Aave V3 USDC variable borrow > 7% APY. * **PATH 2**: ETH > \$5,000 sustained 1 day (independent of PATH 1). * **PATH 3**: Fallback after 1,095 days (3 years) from deploy. * Release: 3 tranches of \~2.666M LUMINA each, 31 days apart from trigger. ## Audit-fix map | Fix | Affects | Description | | ----------- | ----------------- | -------------------------------------------------------------------- | | C-3 | BondVault | Min redeem price aligns with snapshot | | C-4, FIX#15 | CoverRouter | Pause registry plumbing preserved | | H-1 | LuminaToken | `burnFrom` allowance check | | H-5 | PolicyManager | `productActive` gating | | H-6 | PolicyManager | Snapshot LUMINA/USD on purchase | | M-3 | Marketplace | Anti-spam floor on `list()` | | M-6 | BondVault | 1-hour TWAP capacity calc | | M-7 | CoverRouter | Global pause registry | | M-8 | All shields | `MAX_PROOF_AGE` 900 → 86400 | | M-9 | Vesting / payouts | `MonthCalculator` shared library | | M-10 | BuybackEngine | Commit-reveal MEV protection | | M-11 | BondVault | 5%-per-tx burn cap on `burnFromReserves` | | M-12 | TWAPBurner | Sequential DEX fallback + `retryBurn` | | L-2 | EpochCalculator | Drift-free preventive library | | T-30a | Shields | Slim BaseFlashShield + drop-from-purchase mechanic + sequencer guard | | T-30b | Verification | Echidna 200k × 48 properties + Halmos 5 invariants | | T-30c | Deploy | 6 shields + 6 adapters live + register + configure (margin 20000) | | Cleanup | PolicyManagerV2 | `removeProduct` + array compaction (2026-05-22) | For the full audit history see [audits](/contracts/audits).