> For the complete documentation index, see [llms.txt](https://docs.firelight.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firelight.finance/protocol-architecture/on-chain-components.md).

# On-Chain Components

Firelight's on-chain surface is the set of smart contracts that hold collateral, issue coverage, record incidents, and execute payouts. This page summarizes each component, what it stores, and who interacts with it.

### Component summary

<table data-search="false"><thead><tr><th width="243">Component</th><th>Contract</th><th>Role</th><th>Primary actors</th></tr></thead><tbody><tr><td>Cover Registry</td><td>CoverOrderAllocator</td><td>Publishes per-market base premium rate and available limits</td><td>Pricing service (write). Program operators and wallets (read)</td></tr><tr><td>Cover Agent</td><td>CoverOrderAllocator</td><td>Quotes and issues coverage tokens</td><td>Program operators</td></tr><tr><td>Firelight Vault</td><td>FirelightVault</td><td>Holds FXRP and tracks stXRP positions, executes slashing</td><td>Stakers</td></tr><tr><td>First-Loss Buffer</td><td>Custodial Wallet</td><td>Stablecoin reserve that absorbs the first tranche of validated losses</td><td>Network (top-up), Claims Registry (draw-down)</td></tr><tr><td>Cover Token</td><td>CoverNFT</td><td>ERC-7621 token representing an active coverage position</td><td>Program operators</td></tr><tr><td>Claims Registry</td><td>IncidentManager</td><td>On-chain record of incidents, auto-included coverage, consortium votes, and slash instructions</td><td>Risk Consortium, protocol</td></tr><tr><td>Fee Distributor</td><td>VaultRewardDistributor</td><td>Distributes premiums and vault emission boosts into two flows that auto-compound to stXRP</td><td>Matching pipeline (input). protocol and reward emissions (output)</td></tr><tr><td>Price Feed</td><td>FtsoChainlinkAdapter</td><td>Supplies the XRP/USD price used to value staked FXRP for capacity and payout calculations</td><td>Cover Agent, Claims Registry</td></tr></tbody></table>

### Cover Registry

**Contract:** `CoverOrderAllocator`

The source of truth for market-level coverage parameters.

**Stored state:** approved markets (chain, protocol, market, optional pool), base premium rate per market, and the available limit per protocol.

**Updates:** refreshed every 30 days at period boundaries from the off-chain pricing service under access control.

**Reads:** any program operator or integrating system can read current coverage parameters.

### Cover Agent

**Contract:** `CoverOrderAllocator`

The entry point for enabling cover on a vault.

1. An onboarded program operator requests a quote for specified markets and amounts.
2. Cover Agent queries the Cover Registry and matching engine for available limits.
3. A quote is returned with per-market rates, a blended rate, premium amount, and validity.
4. On confirmation and period-boundary matching, Cover Agent pulls premium via the program operator's approval.
5. Cover Agent issues a CoverNFT to the program operator with the coverage metadata.

### Firelight Protocol

**Contract:** `FirelightVault`

Holds FXRP and tracks staker positions in stXRP under the ERC-4626 standard. Core functions cover deployments, withdrawal requests, post-cooldown claims, state queries, and blocklist/pause controls for compliance. The vault exposes slashing hooks triggered by the Claims Registry on a validated claim. All capital in the protocol is utilized in coverage.

### First-Loss Buffer

A protocol-owned stablecoin reserve that sits between claims and staker collateral and absorbs the earliest tranche of any validated loss. It is funded by Network top-ups (and, in some configurations, a portion of premium flow), and replenished by recovered assets in reverse waterfall order. The wallet grants the Claims Registry an allowance to draw on it. On a validated claim, the Claims Registry pulls the first tranche directly from the buffer before requesting any remainder from the vault. The buffer's balance also counts toward coverage capacity.

### CoverNFT

**Contract:** `CoverNFT`

An ERC-721 token representing an active coverage position. It is a non-fungible record of coverage. Full metadata structure is in [Cover Tokens](/for-program-operators/cover-tokens.md). The token remains in the program operator's wallet. There is no escrow or receipt-token step.

### Claims Registry

**Contract:** `IncidentManager`

The Claims Registry replaces the older submit-and-escrow claims flow. It is the on-chain record for the auto-inclusion model:

* **Incident record:** when an incident is confirmed and reported, it is recorded here.
* **Auto-inclusion:** the protocol identifies active CoverNFTs exposed to the incident and records the included set, program operators do not submit anything.
* **Consortium decision:** approving or rejecting an assessment is restricted to the Risk Consortium's 3-of-5 multisig, so the quorum is enforced by the multisig's signing threshold. The registry records each assessment round and its outcome.
* **Slash instruction:** on approval, the registry generates slash instructions specifying the payout. The waterfall is debited sequentially. First-Loss Buffer, then the vault, with a concurrency guard preventing overlapping slashes.
* **Settlement:** proceeds are released per the calculation logic in [Claims Process](/for-program-operators/claims-process.md). CoverNFTs are marked SETTLED when fully consumed.

### Fee Distributor

**Contract:** `VaultRewardDistributor`

Premium and vault emission boosts flow into the Fee Distributor, which auto-compounds them into the vault. Distribution proceeds on a regular streaming cadence rather than a single period-end distribution.

#### Price Feed

**Contract:** `FtsoChainlinkAdapter`

Supplies the XRP/USD price from Flare's FTSO oracle through a Chainlink-compatible interface. The Cover Agent reads it to value staked FXRP in USD when computing capacity, and the Claims Registry reads it when valuing payouts.

#### Flare mainnet deployments

All addresses below are on Flare mainnet (chain ID 14). FirelightVault, CoverNFT, CoverOrderAllocator, IncidentManager and VaultRewardDistributor are upgradeable proxies. The listed addresses are the proxy addresses, which stay the same across upgrades. Source code for every contract is verified on the Flare explorer. The First-Loss Buffer is a custodial wallet, not a contract.

| Contract                                  | Address                                                                                                                                 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| FirelightVault (stXRP)                    | [`0x4C18Ff3C89632c3Dd62E796c0aFA5c07c4c1B2b3`](https://flare-explorer.flare.network/address/0x4C18Ff3C89632c3Dd62E796c0aFA5c07c4c1B2b3) |
| CoverNFT                                  | [`0x366c04e2EA7967f8ea72877f441D71D047441c78`](https://flare-explorer.flare.network/address/0x366c04e2EA7967f8ea72877f441D71D047441c78) |
| CoverOrderAllocator                       | [`0x462790656e03DA468c1b939a5c3F7AD6F0Cd30aE`](https://flare-explorer.flare.network/address/0x462790656e03DA468c1b939a5c3F7AD6F0Cd30aE) |
| IncidentManager                           | [`0xE9041819be57C22f985Dc4237ba0B448e6Bb86aD`](https://flare-explorer.flare.network/address/0xE9041819be57C22f985Dc4237ba0B448e6Bb86aD) |
| VaultRewardDistributor                    | [`0x62db69e2214e88d584fcB7dF38903059a364807a`](https://flare-explorer.flare.network/address/0x62db69e2214e88d584fcB7dF38903059a364807a) |
| FtsoChainlinkAdapter (XRP/USD price feed) | [`0x51de9778367BF7A2632fdDbC5aD710f2B79CF20D`](https://flare-explorer.flare.network/address/0x51de9778367BF7A2632fdDbC5aD710f2B79CF20D) |
| First-Loss Buffer (USDT0)                 | [`0xF948c82b0ecdFa75DAE72F135163C7c038405649`](https://flare-explorer.flare.network/address/0xF948c82b0ecdFa75DAE72F135163C7c038405649) |

### Where to read next

* [Off-Chain Components](/protocol-architecture/off-chain-components.md) for the services that feed the on-chain surface.
* [Claims Liquidation](/protocol-architecture/claims-liquidation.md) for what happens after a validated slash.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.firelight.finance/protocol-architecture/on-chain-components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.