LUMINA.

1. Resumen Ejecutivo

Lumina Protocol es un sistema de seguros paramétricos on-chain desplegado sobre Base. Paga automáticamente cuando un oráculo confirma un evento medible —una caída de precio, una pérdida de paridad de un stablecoin, un alza sostenida de tasas de préstamo— sin peritos, sin votaciones y sin intervención humana.

El protocolo se construye sobre cuatro primitivas:

• 6 Flash Shields paramétricos que cubren desplomes de BTC y ETH en tres ventanas cada uno (1h, 24h, 48h). El strike es el spot capturado en createPolicy y el disparo se produce cuando el activo cae el umbral configurado desde ese strike.
• Un único BondVault inmutable que custodia 70 millones de $LUMINA como reserva del protocolo. Cuando una póliza se dispara, el comprador recibe ClaimBonds: bonos cupón-cero ERC-1155 con valor nominal fijo de USD 1 cada uno, redimibles en $LUMINA al vencimiento (730 días). El payout es 80% de la cobertura (deductible 20%, DEDUCTIBLE_BPS = 2000).
• Un token deflacionario (LUMINA, suministro fijo de 100M). Cada prima en USDC y cada comisión del marketplace secundario se enrutan al TWAPBurner, que compra $LUMINA en Uniswap V3 y lo quema enviándolo a 0xdead. No existe función de mint.
• Una API con relayer que permite a los agentes de IA autónomos comprar, redimir e intercambiar pólizas mediante una sola llamada HTTP firmada, sin necesidad de tener ETH para gas.

La arquitectura actual está plenamente operativa en Base Sepolia: seis Flash Shields activos, las primas fluyen al motor de quema, el marketplace está abierto (3% de fee burn — 1.5% vendedor + 1.5% comprador — settlement en USDC), el oráculo Chainlink (BTC/USD + ETH/USD) alimenta los shields a través del bridge UUPS FlashShieldAdapter, y un endpoint de onboarding self-service permite a los agentes generar API keys con una sola firma de wallet.

Este whitepaper documenta lo que está desplegado al día de hoy en V5.3. Las afirmaciones prospectivas se confinan a la Sección 14 (Roadmap) y la Sección 15 (Riesgos). Cada cifra, dirección de contrato y firma de función está fundada en el código fuente del protocolo y en el endpoint en vivo /health de la API productiva.

2. Introducción

2.1 El problema: DeFi sin protección para agentes autónomos

Las finanzas descentralizadas han madurado hacia una economía programable donde los bots y agentes de IA ejecutan ya la mayoría del volumen on-chain. Pueden prestar, tomar prestado, hacer swaps, cubrirse y rebalancear, pero no pueden asegurarse contra los pocos eventos que liquidan estrategias enteras en un solo bloque: desplomes flash, pérdidas de paridad de stablecoins, picos de tasa que fuerzan liquidaciones.

Los seguros cripto existentes —Nexus Mutual, InsurAce, Sherlock— se estructuran sobre siniestros discrecionales: se reporta el evento, un comité vota, el pago se emite (o se deniega) días o semanas después. Eso es fundamentalmente incompatible con agentes autónomos que requieren una respuesta determinística y de menos de un minuto.

2.2 Lo que hace Lumina de forma distinta

Lumina es paramétrico: cada póliza especifica una condición objetiva de disparo (por ejemplo, "BTC cae ≥ 5% en cualquier ventana móvil de 1 hora"). Cuando un oráculo confirma la condición, el pago se dispara automáticamente dentro de la misma transacción. No hay formulario de siniestro, no hay comité, no hay demora, no existe la posibilidad de denegación subjetiva.

Lumina también es agent-first. La API expone un patrón de relayer (POST /api/v1/policies) en el cual el protocolo paga el gas y el agente solo necesita un encabezado x-api-key. Mantener 24 archivos de skill individuales que estandarizan las operaciones más frecuentes permite a un agente integrarse de extremo a extremo con Lumina en menos de una hora.

3. Arquitectura del Protocolo

3.1 Mapa de componentes

Doce contratos inteligentes colaboran para conformar el protocolo en vivo. Se agrupan en cinco áreas:

3.2 Flujo de compra de póliza

El flujo de extremo a extremo desde la perspectiva del comprador consta de cuatro pasos:

1. El comprador consulta CoverRouterV2.quotePremium(productId, coverageAmount), que devuelve la prima esperada y el pago.
2. El comprador aprueba al router para gastar la prima en USDC.
3. El comprador llama a CoverRouterV2.purchasePolicy(productId, coverageAmount, asset) (o a purchasePolicyFor(...) a través del relayer).
4. El router cobra la prima en USDC, la reenvía en su totalidad al TWAPBurner y luego invoca PolicyManagerV2.recordPolicy(...) para registrar la póliza. Se emite PolicyCreated.

3.3 Flujo de disparo y pago

Los disparos son permisionless: cualquiera puede enviar una prueba válida del oráculo.

1. Un firmante off-chain (operado por Lumina o por un keeper externo) lee los feeds de precio de Chainlink.
2. Construye una prueba EIP-712 PriceProof(int256 price, bytes32 asset, uint256 verifiedAt) y la firma con la oracleKey de confianza.
3. Cualquier dirección llama a CoverRouterV2.submitTrigger(productId, policyId, oracleProof).
4. El router delega en PolicyManagerV2.triggerPayout, que invoca verifyAndCalculate del shield. El shield verifica la firma EIP-712 contra LuminaOracleV2.oracleKey(), valida la ventana temporal de la prueba, el activo, la ventana de cobertura de la póliza y la condición de disparo.
5. Si todo pasa, BondVault.issueBond(buyer, payoutUSD) emite ClaimBonds ERC-1155 al comprador en el epoch de vencimiento correspondiente.

3.4 Flujo de redención de bonos

Los bonos vencen exactamente 730 días después de su emisión. Tras el vencimiento:

1. El tenedor llama a BondVault.redeemBond(epochId, usdAmount).
2. La bóveda quema el balance ERC-1155 del tenedor para ese epoch.
3. Transfiere el equivalente en $LUMINA de usdAmount al precio TWAP vigente (leído de CapacityOracle).

Los bonos son transferibles a través del marketplace secundario antes del vencimiento. Una vez vencidos, ya no pueden listarse (la función list() del marketplace rechaza bonos vencidos).

4. Productos de Seguro — los 6 Flash Shields

Lumina V5.3 ofrece seis productos Flash paramétricos: tres ventanas de drawdown de BTC y tres de ETH. Cada shield es un proxy UUPS que hereda de BaseFlashShield e implementa su disparo en _doVerifyAndCalculate. El registro on-chain de productos usa nombres canónicos del estilo FLASHBTC1H-001; el productId que pasa el llamador es keccak256(canonicalName).

El FlashShieldAdapter (UUPS) es un contrato bridge: expone los shields Flash de la línea T-30a a través de la superficie legacy IShieldV2 que PolicyManagerV2 sigue invocando, de modo que los nuevos shields enchufan en el core sin redesplegarlo.

4.1 Flash Shields de BTC (3 ventanas)

Pagan cuando el spot de BTC cae desde el strike capturado en createPolicy por el umbral configurado dentro de la ventana de la póliza. La prima se publica por cada USD 1.000 de cobertura (payout = USD 800 en $LUMINA por cada USD 1.000 de cobertura, ya restado el deductible del 20%).

4.2 Flash Shields de ETH (3 ventanas)

4.3 Parámetros comunes (todos los shields)

Los builds anteriores V5.1 de testnet exponían también una ventana Flash BTC 4h, un shield de Micro Depeg de USDT y un shield de Rate Shock de Aave USDC. En V5.3 esos productos no son user-facing: la ventana de 4h se retiró, el Micro Depeg se eliminó y el Rate Shock permanece pausado on-chain a la espera del cableado real con Aave.

5. Modelo de Precios y Primas

5.1 Cotización de la prima

V5.3 publica una prima fija por cada USD 1.000 de cobertura para cada shield. La superficie expuesta al comprador es:

El protocolo sigue aplicando una carga de riesgo determinística dentro del shield (marginBps = 20000, es decir 2,00×) antes de computar el payout; la cifra publicada de $/$1k ya incluye esa carga. No se expone ningún factor de probabilidad al llamador: solo necesita leer la prima por $1k y el multiplicador.

• cobertura: monto de cobertura del comprador en unidades base de USDC (6 decimales).
• premiumPer1k: prima canónica por USD 1.000 de cobertura tomada de la Sección 4.
• payout en disparo: cobertura × (10000 - DEDUCTIBLE_BPS) / 10000 = 80% de la cobertura (deductible 20%).
• marginBps: 20000 (multiplicador económico efectivo ~1,60× después de aplicar el deductible al payout).

Si la fórmula da cero (coberturas muy pequeñas), el contrato impone un piso de prima de 1 micro-USDC (USD 0.000001).

5.2 Verificación de capacidad

Antes de registrar una póliza, PolicyManagerV2 consulta BondVault.availableCapacityUSD(). Si el pago potencial de la póliza llevaría a la bóveda por debajo de su piso de respaldo (comprometido ≤ 50% del valor de reserva, ~200% de respaldo), la compra revierte con InsufficientCapacity.

La capacidad se computa sobre un TWAP de 1 hora del precio de LUMINA, no sobre el precio spot. Esta salvaguarda anti-MEV impide que un atacante manipule el spot, ya sea para denegar cobertura o para empujar al protocolo a reservas escasas.

BondVault aplica un throttle adicional sobre quemas/redenciones: cap de 1,08% por semana, cola FIFO, de modo que un solo bloque no puede vaciar la reserva incluso si un gran cohorte se dispara simultáneamente.

5.3 Disyuntor de auto-pausa

Si el TWAP del precio de LUMINA cae por debajo de USD 0.005, isProtocolAutoPaused() devuelve true y las nuevas compras revierten. El disyuntor usa histéresis: una vez activado, requiere que el precio se recupere por encima de USD 0.008 (el RESET_PRICE_FOR_NEW_POLICIES) para volver a armarse. Esto evita oscilaciones cerca del umbral.

5.4 Tabla de calibración (Sepolia actual, V5.3)

6. BondVault, ClaimBond y Vencimiento

6.1 El modelo de bóveda única

Versiones anteriores de Lumina usaban cuatro bóvedas separadas (una por clase de activo). La arquitectura actual las unifica en un único BondVault que custodia 70 millones de $LUMINA. La bóveda nunca se financia directamente con depósitos de usuarios; recibe su asignación en LuminaTokenV2.initialize() como parte de la distribución génesis.

La bóveda solo expone dos superficies con efecto de estado:

• issueBond(buyer, payoutUSD): invocado por PolicyManagerV2 cuando una póliza se dispara. Emite ClaimBonds ERC-1155 en el epoch de vencimiento correspondiente a now + 730 días.
• redeemBond(epochId, usdAmount): invocado por los tenedores tras el vencimiento. Quema el balance ERC-1155 del tenedor y transfiere $LUMINA al precio vigente.

6.2 ClaimBond — cupón-cero ERC-1155

Los ClaimBonds son tokens ERC-1155 agrupados por epoch mensual de vencimiento. El tokenId es el identificador del epoch, calculado como year × 100 + month (por ejemplo, 202805 = mayo de 2028). Todos los bonos que vencen en el mismo mes calendario comparten el mismo tokenId y son fungibles dentro de ese epoch.

Críticamente, 1 token = USD 1 de valor nominal al vencimiento. Las cantidades son dólares enteros, NO unidades base de USDC con 6 decimales. Una posición con balance 4000 representa USD 4.000 de valor nominal, no USD 0.004.

Los bonos son no transferibles peer-to-peer por diseño. El contrato sobrescribe _update para permitir solo emisiones (from == 0), quemas (to == 0) y transferencias vía operadores autorizados. El LuminaBondMarketplace es el único operador autorizado, lo que asegura que el protocolo capture la comisión por trading secundario.

6.3 Período de vencimiento

BOND_MATURITY_SECONDS = 730 días. Un bono emitido hoy por una póliza disparada vence exactamente dos años después. El vencimiento se fija en la emisión y no cambia si el bono se vende en el marketplace: el comprador redime en la misma fecha.

6.4 Piso de solvencia

El protocolo lleva la cuenta de totalCommittedUSD (suma de bonos emitidos) y totalReservedUSD (suma de reservas de capacidad de pólizas activas). Su suma nunca puede exceder SAFETY_FACTOR_BPS × reserveValueUSD / 10000. burnFromReserves —ruta administrativa para retirar colateral excedente— está limitada al 5% de las reservas de la bóveda por transacción.

7. Oráculo y Verificación

7.1 LuminaOracleV2 (Chainlink real en Base Sepolia)

El oráculo de los shields es LuminaOracleV2.sol en 0x9bfa2f7A5098C89b8740D1694d1f716A0Bd871dD (Base Sepolia). Lee directamente los feeds reales de Chainlink BTC/USD y ETH/USD; no se requiere un firmante off-chain EIP-712 para el camino activo. El verificador EIP-712 legacy queda en el contrato por compatibilidad de upgrade y para feeds futuros que carezcan de un agregador Chainlink.

El envelope EIP-712 legacy (mantenido por compatibilidad) es:

Para Flash BTC y Flash ETH el shield invoca el camino latestRoundData() de Chainlink dentro de FlashShieldAdapter; el camino EIP-712 legacy solo se usa cuando el activo no tiene feed nativo de Chainlink.

7.2 Tipo PriceProof

El shield invoca IOracleV2(oracle).verifyPriceProofEIP712(price, asset, verifiedAt, signature) dentro de _doVerifyAndCalculate. El firmante recuperado debe coincidir con la oracleKey() del oráculo.

7.3 Servicio de firma off-chain

El servicio lumina-api expone POST /api/v1/oracle/sign-proof, que:

1. Lee el feed de Chainlink correspondiente al activo solicitado.
2. Construye el envelope EIP-712 con verifiedAt = now.
3. Firma con la ORACLE_PRIVATE_KEY almacenada en el secret store de Railway.
4. Devuelve el oracleProof codificado en ABI listo para pasar a submitTrigger.

La dirección del firmante es auditable on-chain mediante LuminaOracleV2.oracleKey(). Cualquier agente puede consultarla en GET /api/v1/oracle/signer antes de enviar un disparo.

7.4 Envío de disparos sin permisos

submitTrigger no tiene control de acceso. El argumento es exclusivamente la prueba criptográfica; una prueba forjada o vencida revierte en la verificación del shield. Esto significa que cualquiera (el comprador de la póliza, un keeper bot, un buscador MEV) puede enviar una prueba válida y disparar el pago. El comprador de la póliza sigue siendo el único beneficiario, sin importar quién haga la llamada.

7.5 Oráculo de capacidad y oráculo de solvencia

Dos oráculos adicionales sirven necesidades internas del protocolo:

• CapacityOracle.getLuminaPrice(): provee un TWAP de 1 hora del precio spot de LUMINA, usado por las verificaciones de capacidad y solvencia.
• SolvencyOracle: monitorea el ratio de solvencia del BondVault (bandas 200/100/70%); lo consume burnFromReserves para bloquear quemas que comprometerían la solvencia.

8. Tokenomics

8.1 Suministro y estándar

$LUMINA es un token ERC-20 + ERC-20Burnable desplegado tras un proxy UUPS. El suministro máximo es 100_000_000 * 1e18, fijado en construcción. No existe función mint. El suministro solo decrece por quema.

El constructor refuerza assert(totalSupply() == MAX_SUPPLY) tras la distribución génesis, y totalBurned() devuelve MAX_SUPPLY - totalSupply().

8.2 Distribución inicial (100M)

Se acuña por única vez en initialize() a través de cinco direcciones inmutables como argumentos:

8.3 BURNER_ROLE

Solo el contrato TWAPBurner ostenta BURNER_ROLE sobre el token. Este rol permite invocar burnFrom sobre cualquier dirección, lo que es necesario porque el burner extrae $LUMINA de los buffers intermedios del protocolo y lo quema. DEFAULT_ADMIN_ROLE administra las asignaciones de roles. Renunciar a DEFAULT_ADMIN_ROLE bloquea de forma permanente la administración de BURNER_ROLE; el desplegador solo debería renunciar tras confirmarse el despliegue final del TWAPBurner.

8.4 FounderVesting V2 (8M, tres rutas independientes)

La asignación del fundador (8M) se desbloquea mediante FounderVesting V2: tres compuertas independientes, gana la primera que se dispare, y luego se liberan tres tramos de ~3,333M cada uno cada 31 días.

• RUTA 1: 2-de-3 compuertas AltSeason sostenidas durante 1 día: (A) ratio ETH/BTC > 0,050, (B) ETH/USD > USD 4.000, (C) tasa de préstamo USDC en Aave V3 > 7% APY.
• RUTA 2: ETH/USD > USD 5.000 sostenido durante 1 día (override independiente de la RUTA 1).
• RUTA 3: Fallback temporal a 1.095 días (3 años) desde el deploy. Con deploy el 2026-05-14, el backstop absoluto es el 2029-05-13.

FounderVesting V2 está desplegado en 0xfF4Db529bBCd4E3CC091E07b7845241EB4762832 y se cablea contra LuminaOracleV2 para las lecturas en vivo de ETH/USD y ETH/BTC.

8.5 TreasuryVesting (3M, drip)

• Lock inicial: 180 días desde el deploy.
• Liberación máxima mensual: 250.000 $LUMINA.
• Implicancia matemática: 12 meses de drip + 6 meses de lock = 18 meses mínimo para drenar la totalidad.

Las liberaciones son onlyOwner; una liberación por ventana de 30 días, con tope en el máximo mensual.

9. Distribución Adaptativa de Quema

El 100% del USDC enrutado al TWAPBurner no siempre se quema directamente. Antes de comprar y quemar $LUMINA, el burner consulta a AdaptiveFeeDistributor para decidir cómo dividir el USDC entrante en cuatro buckets:

• Quema (Burn): convierte USDC en $LUMINA en Uniswap V3 y lo envía a 0xdead (presión deflacionaria).
• Reserva de Buyback: acumula USDC para futuras compras de $LUMINA; se activa con más fuerza cuando el momentum es bajista.
• Operaciones: tesorería para gas de keepers, subsidios de oráculos y costos operativos.
• Mantenimiento: financia infraestructura de shields, auditorías y mantenimiento rutinario.

El split no es estático. Adapta sobre dos ejes: solvencia del protocolo y momentum de mercado de LUMINA. El producto 4×4 de estos dos ejes produce 16 distribuciones posibles, cada una pre-calibrada para un régimen específico. La matriz completa se implementa en AdaptiveFeeDistributor._lookupDistribution(sLevel, mLevel) y está verificada por tests unitarios que cubren los 16 cuadrantes.

9.1 Los dos ejes

Niveles de solvencia: computados por SolvencyOracle como el ratio entre (reserva LUMINA del BondVault × precio spot) y obligaciones totales comprometidas en USD, expresado en basis points:

• ULTRA (sLevel 0): profundamente sobrecapitalizado; el sistema puede permitirse máxima presión deflacionaria.
• HEALTHY (sLevel 1): cómodamente solvente; régimen operativo por defecto.
• STRESSED (sLevel 2): reservas bajo presión; quema lenta, ahorro de USDC para defensa.
• CRISIS (sLevel 3): cerca de subcapitalización; halt de quema, acumulación de USDC para defender el precio en la recuperación.

Buckets de momentum: computados a partir del ratio entre el TWAP de ventana corta (30 minutos) y el TWAP de ventana larga (1 día) del precio spot de LUMINA:

• RALLY (mLevel 0): ratio > 1.05; precio en tendencia alcista — quema agresiva mientras el sentimiento es fuerte.
• STABLE (mLevel 1): 0.95 – 1.05; lateral — split por defecto.
• DECLINE (mLevel 2): 0.85 – 0.95; precio cediendo — redirige más USDC a la reserva de buyback.
• CRASH (mLevel 3): ratio < 0.85; drawdown agudo — halt total de quema, todo el USDC va a reserva de buyback para sostener la recuperación.

9.2 La matriz de 16 cuadrantes

Cada celda muestra los basis points enrutados a quema / buyback / operaciones / mantenimiento, sumando 10000 (100%):

Celda en negrita = HEALTHY/STABLE = régimen operativo por defecto. Las cuatro constantes FALLBACK_*_BPS en TWAPBurner espejan esta celda como red de seguridad si el distributor revierte.

9.3 Ejemplos prácticos

• ULTRA × RALLY → 95% quema, 0% buyback. Reservas profundas, precio subiendo: deflación máxima. Cada USDC de prima se traduce en LUMINA comprado y quemado, amplificando la tendencia alcista.
• HEALTHY × STABLE → 85/8/2/5. Régimen por defecto: la mayor parte de la prima quema LUMINA, una pequeña fracción se acumula como reserva de buyback, el resto cubre operaciones y mantenimiento.
• STRESSED × DECLINE → 38% quema, 55% buyback. Solvencia ajustada y precio cediendo: la matriz pivota: la mayoría del USDC se retiene como reserva de buyback, menos del 40% se quema. La presión de quema se preserva, pero el capital se reserva para una intervención defensiva futura.
• CRISIS × CRASH → 0% quema, 96% buyback. Régimen de máxima tensión: toda quema se detiene, casi todo el USDC entrante va a la reserva de buyback. El protocolo prioriza capital de recuperación sobre señalización deflacionaria.

9.4 Estado de implementación (testnet Sepolia)

9.5 Referencias

• AdaptiveFeeDistributor.sol: implementación de la matriz.
• SolvencyOracle.sol: clasificación de solvencia y momentum (momentum actualmente stubbed).
• AdaptiveFeeDistributorTest.t.sol: tests de los 16 cuadrantes.

10. Motor de Quema y Flujo Deflacionario

9.1 Dos rutas de quema

Cada USDC que entra al protocolo se enruta a través del TWAPBurner:

1. Primas: CoverRouterV2._purchase invoca twapBurner.receivePremium(premium) tras cada compra de póliza. La transferencia es atómica respecto de la compra.
2. Comisiones de marketplace: LuminaBondMarketplace.executeBuy deduce una comisión del 3% en cada trade secundario, también enrutada vía receivePremium.

Los USDC se acumulan dentro del burner hasta que se invoca executeBurn().

9.2 Parámetros de executeBurn

9.3 Distribución de fallback en 4 buckets

El bucket de Burn compra $LUMINA en Uniswap V3 (con Aerodrome como fallback secuencial) y lo envía a 0xdead. Cada quema exitosa emite:

9.4 Caller permisionless

executeBurn es external nonReentrant: no hay onlyAuthorized. Cualquier wallet puede llamarla. El cooldown limita la frecuencia, y los topes mínimo/máximo limitan el slippage por llamada. Cualquiera puede ser el keeper de quema.

11. Marketplace Secundario

10.1 Propósito

Los ClaimBonds vencen a 730 días. Los tenedores que necesitan liquidez antes los venden en el mercado secundario con descuento; los compradores obtienen un yield implícito esperando al vencimiento. El mercado es permisionless y on-chain.

10.2 Flujo de listing

1. El vendedor ejecuta ClaimBond.setApprovalForAll(marketplace, true) (una sola vez por familia de epoch).
2. El vendedor llama LuminaBondMarketplace.list(epochId, amount, priceUSDC). El contrato verifica balanceOf(seller, epochId) ≥ amount y que block.timestamp < maturityDate(epochId).
3. El marketplace extrae la cantidad ERC-1155 vía safeTransferFrom, almacena la struct Listing y emite Listed(listingId, seller, epochId, amount, priceUSDC).

10.3 Flujo de compra

1. El comprador aprueba USDC al marketplace por priceUSDC.
2. El comprador invoca executeBuy(listingId).
3. El marketplace transfiere USDC desde el comprador, deduce un 3% de comisión (enrutado al TWAPBurner), paga al vendedor y transfiere la cantidad ERC-1155 al comprador.
4. El vencimiento no cambia: el comprador redime en la fecha original, igual que lo haría el tenedor original.

10.4 Flujo de cancelación

El vendedor puede cancelar cualquiera de sus propios listings vía cancel(listingId). El bono regresa al wallet del vendedor. No hay enforcement on-chain de auto-compra, pero el frontend deshabilita el botón Buy cuando seller == wallet conectado.

10.5 BuybackEngine (anti-MEV por commit-reveal)

Un BuybackEngine separado consume el bucket de buyback del TWAPBurner usando un esquema de commit-reveal para impedir front-running. Las operaciones se baten en lotes y se revelan en una transacción separada; se recomienda enrutamiento por mempool privado del lado de operaciones.

12. Modelo de Seguridad

11.1 Upgradeability

Todos los contratos del núcleo son upgradeables UUPS con _authorizeUpgrade protegido por DEFAULT_ADMIN_ROLE. Los upgrades hoy requieren un único firmante y migrarán a multisig antes de mainnet (ver Roadmap).

11.2 Postura de auditoría

Los reportes de auditoría interna son públicos:

• docs/SECURITY-AUDIT-V5.md: última auditoría interna que cubre la arquitectura actual.
• docs/audit/v5.1-uups/: análisis por capítulo: aristas matemáticas, riesgo de claves admin, condiciones de carrera, dependencias temporales, integración del oráculo.
• docs/audit/PHASE4-AUDIT-REPORT.md: flujo de bonos + marketplace.

El protocolo lleva una nota de riesgo aceptado: no hay auditoría de tercero Tier-1 previa al mainnet. La bug bounty del fundador + multisig + clave en cold storage entran en vigor en T+30d posterior al deploy de mainnet.

11.3 Matriz de control de acceso

docs/ACCESS-CONTROL-MATRIX.md documenta cada rol privilegiado, su tenedor actual y la política de rotación. Roles clave:

• DEFAULT_ADMIN_ROLE en cada contrato UUPS: wallet del desplegador hoy, multisig en mainnet.
• BURNER_ROLE en LuminaTokenV2: solo el TWAPBurner.
• onlyRouter en PolicyManagerV2: solo CoverRouterV2.
• oracleKey en LuminaOracleV2: la dirección del firmante off-chain (rotable).

11.4 Modelo de amenazas

Documentado en docs/audit/THREAT-MODEL.md. Mayores riesgos residuales:

• Dependencia de Chainlink. Los shields Flash BTC y Flash ETH confían en los feeds Chainlink BTC/USD y ETH/USD en Base. Una desviación o staleness del feed puede provocar disparos espurios o denegados. Mitigación: BaseFlashShield verifica cada round (respuesta positiva, updatedAt fresco, consistencia del round) y revierte ante datos viejos; el L2 sequencer uptime feed también se valida en Base mainnet (address(0) → no-op en Sepolia).
• Concentración en una sola bóveda. Un único BondVault custodia 70M LUMINA. Un bug de reentrancy o corrupción de storage allí es existencial. Mitigación: testing extenso, invariantes con fuente única de verdad, cadencia continua de auditoría, throttle FIFO de 1,08% por semana sobre los flujos salientes.

13. Para Agentes de IA

12.1 Onboarding self-service

Un agente autónomo puede generar su propia API key sin intervención humana. El flujo consta de dos operaciones en línea:

1. Firmar el envelope EIP-191 "Lumina onboarding for {wallet} at {timestamp}" con la wallet del agente.
2. POST /api/v1/agent/onboard con {walletAddress, label?, signature, timestamp}.

La API verifica la firma, acuña una key lk_<64hex> (hasheada con SHA-256 en reposo) y devuelve el plaintext una sola vez. Límites: máximo 3 keys activas por wallet, 10 intentos de onboard por IP por hora.

12.2 Compra de pólizas con relayer

La feature distintiva para agentes: POST /api/v1/policies. El wallet relayer de la API firma purchasePolicyFor on-chain en nombre del agente. El agente no necesita ETH para gas; solo USDC para la prima (custodiado por el wallet del agente, extraído por el contrato). Las idempotency keys impiden el doble-gasto en reintentos.

12.3 Skill files

El repo lumina-api ships 24 skill files en docs/skills/: uno por operación frecuente. Cada archivo sigue una estructura fija: un bloque "What this does" en lenguaje llano, un prompt LLM listo para copiar-pegar, variables de entorno, ejemplos en curl + TypeScript + Python, esquemas de request/response y códigos de error. Diseñados para insertarse directamente en la lista de tools o el system prompt de un agente.

12.4 Superficie de endpoints

14. Roadmap

Fases 1-4 — V5.3 desplegada ✅ (Base Sepolia, 2026-05-14)

• 6 Flash shields (BTC y ETH; 1h, 24h, 48h) activos tras FlashShieldAdapter.
• Chainlink BTC/USD y ETH/USD activos; L2 sequencer feed cableado (no-op en Sepolia).
• BondVault único con throttle FIFO 1,08%/semana activo.
• Marketplace V5.3 activo: 3% fee burn (1.5% vendedor + 1.5% comprador), settlement en USDC.
• FounderVesting V2 con tres rutas independientes activo.
• Onboarding self-service de agentes + 24 skill files publicados.

Fase 5 — Uso real en testnet (actual)

• Uso real y stress-tests en testnet con agentes integradores.
• Bootstrap de liquidez en el marketplace.
• Dashboards de observabilidad para la matriz adaptativa de quema.

Fase 6 — Hardening pre-mainnet

• Auditoría externa Tier-1.
• Multisig reemplaza al admin de firmante único (Gnosis Safe, 2-de-3 inicialmente).
• Custodia en cold storage para cualquier clave de oráculo rotable.
• Bug bounty activa en T+30d.

Fase 7 — Lanzamiento mainnet

• Despliegue de los contratos en Base (chainId 8453).
• Activar el check de L2 sequencer uptime con la dirección real del feed Chainlink.
• Expansión cross-chain a L2s adicionales.
• Nuevos productos shield (depeg de LSTs mayores, falla de pool Curve, staleness de oráculo, shields a medida para builders).

15. Riesgos y Aviso Legal

14.1 Riesgo de smart contracts

El protocolo no está auditado por una firma Tier-1 al momento de redacción. Las auditorías internas son públicas pero no sustituyen una externa. Un bug de reentrancy, colisión de storage o manipulación de oráculo en el BondVault o en la ruta de un shield podría resultar en pérdida total del colateral.

14.2 Riesgo de oráculo

Los disparos dependen de pruebas EIP-712 firmadas por un firmante off-chain. Si su clave se compromete, todas las pólizas activas pueden dispararse falsamente, drenando el BondVault. Las mitigaciones son ítems del roadmap (HSM, firmante multisig).

14.3 Riesgo de liquidez

La redención de bonos paga en $LUMINA al precio TWAP vigente. Si la liquidez secundaria de LUMINA es escasa en el momento de la redención, los tenedores pueden recibir menos USD-equivalente que el valor nominal del bono.

14.4 Riesgo regulatorio

El seguro paramétrico on-chain es novedoso. Puede ser clasificado como valor, derivado o producto de seguro regulado en algunas jurisdicciones. El uso del protocolo es por cuenta y riesgo legal del usuario.

14.5 Aviso legal

Este whitepaper describe el protocolo tal como está desplegado al 14 de mayo de 2026 en Base Sepolia (V5.3). No constituye una oferta de venta ni una solicitud de compra de ningún token, valor o producto de seguro. Se provee con propósitos técnicos y educativos. Las afirmaciones prospectivas en la Sección 14 son aspiracionales; nada en este documento es garantía de despliegue futuro, fusión de funcionalidades o retorno financiero.

16. Marco Legal

15.1 Estructura del protocolo

Lumina Protocol es software de código abierto publicado bajo licencia MIT en github.com/org-lumina. Los contratos están desplegados y operados por el equipo fundador durante el testnet; en mainnet, la gobernanza y autoridad sobre parámetros migran a un multisig y, en última instancia, a una gobernanza on-chain.

15.2 Naturaleza del producto

Los ClaimBonds son instrumentos paramétricos de pago, no contratos de seguro en el sentido regulado. No hay perito, no hay underwriter, no hay acuerdo de tomador de póliza. Un disparo es un evento on-chain determinístico; un pago es una transferencia on-chain determinística.

15.3 Naturaleza del token

$LUMINA es un token de utilidad con tres usos programáticos: (i) es el activo pagado por las redenciones de ClaimBond; (ii) el motor de quema del protocolo lo destruye permanentemente a medida que las primas y comisiones de marketplace fluyen; (iii) es la unidad de cuenta para la solvencia del BondVault. No está diseñado ni comercializado como inversión; cualquier trading especulativo queda fuera del propósito del protocolo.

15.4 Jurisdicción

El protocolo no apunta a usuarios de ninguna jurisdicción específica. Operadores, integradores y usuarios finales son responsables de su propio cumplimiento regulatorio.

Apéndice A — Direcciones Desplegadas (Base Sepolia, chainId 84532)

V5.3 mantiene las direcciones del core V5.2 (sin redeploy de BondVault, PolicyManager, etc.) y agrega seis nuevos adapters de shield. La fuente canónica es siempre https://lumina-api-production-ac85.up.railway.app/health; si alguna dirección difiere de /health, /health manda.

Núcleo del protocolo (direcciones V5.2 vigentes)

Split del AdaptiveFeeDistributor: 85% Burn / 8% Buyback / 2% Operations / 5% Maintenance.

Adapters de Flash shield (V5.3, desplegados 2026-05-14)

API + relayer

Apéndice B — Glosario

Apéndice C — Referencias

Toda afirmación técnica de este whitepaper se trazea a alguna de estas fuentes:

• Código fuente: github.com/org-lumina/LUMINA-PROTOCOL/tree/main/src
• Tokenomics canónica: docs/TOKENOMICS.md
• Visión arquitectónica: SECURITY.md
• Integración Aave V3: docs/architecture/AAVE-INTEGRATION.md
• Deep dive del Oráculo V2: docs/architecture/ORACLE-V2.md
• Referencia de endpoints de la API: README de lumina-api
• 24 skill files: lumina-api/docs/skills
• Estado de deploy en vivo: /health
• Block explorer: sepolia.basescan.org