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

# How Lumina works

> Parametric insurance for autonomous agents: 5 actors, one deterministic flow.

<Note>
  See [/concepts/lifecycle](/concepts/lifecycle) for the end-to-end flow (policy → trigger → bond → wait/sell decision).
</Note>

## What is LUMINA (for non-coders)

LUMINA is insurance that pays you automatically when a crypto price crashes
by a set percentage. You buy cover, and if the price drops by the agreed
amount within the time window, you get paid — there is no claims form, no
adjuster, and no waiting on a human to approve anything. It all runs on the
Base testnet today.

Lumina is **parametric insurance** for crypto-native agents and humans. A
buyer pays a small **USDC premium** for cover against a public, verifiable
on-chain event (e.g. "BTC drops 2.5% from the purchase-time price within
1 hour"). When the event fires, the protocol mints an ERC-1155
**ClaimBond** that the holder can redeem in **LUMINA** at maturity or sell
on the marketplace for USDC today.

## The 5 actors

| Actor       | Role                                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Agents**  | Autonomous programs that buy cover programmatically via the SDK/API. The primary user of Lumina.                               |
| **Humans**  | Wallet users buying cover through the hosted UI ([lumina-org.com/app/human](https://www.lumina-org.com/app/human)).            |
| **Relayer** | Pays gas and submits `purchasePolicyFor` on behalf of buyers, so buyers spend only USDC, no ETH.                               |
| **Oracle**  | `LuminaOracleV2` aggregates Chainlink BTC/USD + ETH/USD feeds, requires 3 confirmations 60s apart, signs EIP-712 price proofs. |
| **Founder** | Governance + vesting recipient (`FounderVestingV2`, three release paths — ETH/\$5000, sustained price, 3-year fallback).       |

## Purchase → trigger → bond → redeem

```
        Buyer (agent or human)
               │  premium (USDC)
               ▼
   ┌─────────────────────────┐
   │      CoverRouterV2      │ ◄──── Relayer pays gas (purchasePolicyFor)
   └────────┬────────────────┘
            ▼
   ┌────────────────────────────────────┐
   │      AdaptiveFeeDistributor        │ 85% burn / 8% buyback / 2% ops / 5% maintenance
   └────────┬───────────────────────────┘
            ▼
   ┌─────────────────────────┐
   │     PolicyManagerV2     │ records policy, snapshots strike + LUMINA price
   └────────┬────────────────┘
            ▼
   ┌─────────────────────────┐
   │   FlashShieldAdapter    │ legacy IShieldV2 surface (UUPS, one per product)
   └────────┬────────────────┘
            ▼
   ┌─────────────────────────┐
   │   BaseFlashShield       │ verifies oracle, drop vs strike, time window
   └────────┬────────────────┘
            ▼  (when triggered)
   ┌─────────────────────────┐
   │       BondVault         │ mints ERC-1155 bond ($800 face / $1k cover)
   └────────┬────────────────┘
            ▼
   ┌─────────────────────────┐
   │      ClaimBond          │ hold 730d → LUMINA, or sell on Marketplace (3% fee: 1.5% seller + 1.5% buyer)
   └─────────────────────────┘
```

## Concept index

| Concept                                            | What it is                                                                                                                                 |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [Shield](/concepts/shields)                        | One parametric product (e.g. "BTC drops 2.5% in 1h"). All 6 V5.4 shields share the slim `BaseFlashShield` logic.                           |
| [Adapter](/concepts/adapters)                      | `FlashShieldAdapter` — UUPS proxy that bridges `PolicyManagerV2`'s legacy `IShieldV2` ABI to the slim `BaseFlashShield`. One per product.  |
| Policy                                             | The buyer's coverage. Stored in `PolicyManagerV2`, indexed by `(productId, policyId)`. Snapshots the asset's **strike price at purchase**. |
| [Trigger](/concepts/triggers)                      | Oracle proof that the condition fired. `BaseFlashShield` verifies signature + 3 confirmations + drop vs strike + window.                   |
| [Claim Bond](/concepts/claimbonds)                 | The payout. ERC-1155, \$1 face per token, **730-day maturity**. Redeem for LUMINA or sell on the marketplace.                              |
| [BondVault throttle](/concepts/bondvault-throttle) | `MAX_REDEMPTION_PER_EPOCH_BPS = 108` — 1.08%/week cap per epoch, FIFO queue post-throttle. Anti bond-run.                                  |
| [LUMINA token](/concepts/lumina-token)             | 100M hard cap, 85% of premiums burned via TWAP.                                                                                            |

## Why parametric (not actuarial)

Traditional insurance pays based on a claims-adjuster reading documents.
That model breaks for autonomous agents — they can't fax in a damage
report.

Lumina pays based on a public, verifiable condition: a price feed crossed
a threshold by X% from the strike snapshotted at purchase, within the
cover window. The oracle *observes* the condition (3 Chainlink reads, 60s
apart) and signs an EIP-712 proof; the shield *verifies* the proof and
pays. There is no human in the middle, by design.

## Why ERC-1155 bonds (not direct payouts)

A direct payout would be operationally simpler, but it has two problems:

1. **BondVault liquidity.** A flash of simultaneous triggers could drain
   USDC reserves if every payout settled in cash on the spot. ERC-1155
   bonds let the protocol queue redemption against a maturity date (730d)
   and a per-epoch throttle (1.08%/week), and let bond holders exit *now*
   against another buyer's wallet on the marketplace instead of the vault.
2. **Settlement flexibility.** A bond that hasn't matured yet can be sold
   on the marketplace for **USDC** today (usually at a small discount), or
   held to maturity and **redeemed for LUMINA**. The holder picks the
   asset, not the protocol.

See [contracts/architecture](/contracts/architecture) for the full diagram,
and [the lifecycle page](/concepts/lifecycle) for a worked example.