Architecture

​

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.

​

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.
• 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