# Architecture Overview

Fira is a modular protocol composed of independent layers that combine to deliver fixed-rate, floating-rate, and curated lending. Each layer handles one responsibility. The layers connect through shared token standards and a unified router.

## System Layers

```
┌─────────────────────────────────────────────────────┐
│                   Router (Zapper)                   │
│         Multi-step user flows in one transaction    │
├──────────────┬───────────────┬──────────────────────┤
│  Fixed-Rate  │ Floating-Rate │     Curation         │
│    AMM       │   Lending     │      Vaults          │
│ (FiraMarket) │(LendingMarket)│   (SisuVault)        │
├──────────────┴───────────────┴──────────────────────┤
│                 Token Layer                         │
│           BT · CT · FW · LP Token                   │
├─────────────────────────────────────────────────────┤
│              Rehypothecation Module                 │
│          Reserve allocation between layers          │
├─────────────────────────────────────────────────────┤
│           Oracles · Interest Rate Models            │
│         Price feeds · Utilization-based IRM         │
└─────────────────────────────────────────────────────┘
```

## Token Layer

Three tokens form the foundation of every Fira market:

| Token  | Full Name    | Role                                                                                                                                                             |
| ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **FW** | FiraWrapped  | Wrapped yield-bearing representation of the underlying asset (e.g., FW-USDC wraps USDC). Exchange rate appreciates over time as rehypothecation generates yield. |
| **BT** | Bond Token   | Principal token. Redeems 1:1 for the underlying at maturity. Trades at a discount before maturity — the discount is the implied fixed rate.                      |
| **CT** | Coupon Token | Yield token. Accrues rehypothecation yield from FW reserves. Tradable before maturity.                                                                           |

The core invariant across all markets:

$$
\mu(t) \hspace{0.1cm} \text{Underlying} = 1 \hspace{0.1cm} \text{FW} = \mu\_{s}(t) \hspace{0.1cm} \text{BT} + \mu\_s(t) \hspace{0.1cm} \text{CT}
$$

FW decomposes into BT + CT on deposit. BT + CT recombine into FW on redemption. All three are standard ERC-20 tokens.

For full token specifications, see [Token Mechanics](https://docs.fira.money/protocol/token-mechanics).

## Fixed-Rate AMM

**FiraMarket** is the automated market maker for BT/FW trading. It is the mechanism through which fixed rates are discovered.

* LPs deposit FW into the pool, which decomposes into BT (stays in pool) + CT (returned to LP)
* Borrowers swap BT for FW — the exchange rate determines the fixed borrow rate
* Lenders swap FW for BT — the discount determines the fixed lending yield
* LP token holders earn swap fees and lending interest

The AMM uses an exchange-rate-based pricing formula that adjusts dynamically. As maturity approaches, BT price converges to par. Key parameters include `scalarRoot` (liquidity concentration) and `rateAnchor` (tracks the most recent implied rate).

For rate mechanics, see [Fixed-Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets).

## Lending Market

**LendingMarket** is the core lending engine, managing collateral, borrowing, interest accrual, and liquidation across multiple markets. It handles:

* **Supply and borrow** — Positions tracked per market, per user
* **Collateral management** — LTV and LLTV enforcement per market configuration
* **Interest accrual** — Continuous, per-second interest calculation
* **Liquidation** — Third-party liquidators repay debt and seize collateral at a bonus
* **Flash loans** — Atomic borrow-and-repay within a single transaction
* **Post-maturity settlement** — Forced liquidation of expired positions

Each market is defined by a collateral asset, a loan asset (as BT), an oracle, and risk parameters (LTV, LLTV, liquidation incentives). The same LendingMarket contract serves both fixed-rate and floating-rate markets.

For liquidation mechanics, see [Liquidations](https://docs.fira.money/protocol/liquidations).

## Rehypothecation Module

The **RehypothecationModule** attaches to each FW token implementation and controls how idle reserves are allocated between liquid holdings and variable-rate vaults.

Three parameters govern the allocation:

* **φ\_min** — Below this ratio, reserves are withdrawn from the vault
* **φ\_max** — Above this ratio, excess reserves are deposited into the vault
* **φ\_target** — The ratio restored on every rebalance

Rebalancing triggers on every FW deposit or redemption, or manually by the FW owner. Yield from rehypothecated reserves accrues to CT holders.

For the full mechanism, see [Rehypothecation](https://docs.fira.money/protocol/rehypothecation).

## Curation Vaults (SisuVault)

**SisuVault** is an ERC-4626 vault that allocates pooled capital across LendingMarket instances. It supports role-based access:

| Role          | Responsibility                                        |
| ------------- | ----------------------------------------------------- |
| **Owner**     | Top-level vault governance                            |
| **Curator**   | Defines strategy, supply caps, and market eligibility |
| **Allocator** | Executes capital deployment across markets            |
| **Guardian**  | Emergency controls and parameter timelocks            |

Curators set per-market supply caps and risk constraints. Allocators rebalance capital within those constraints. Configuration changes are subject to timelocks.

For vault mechanics, see [Curation Vaults](https://docs.fira.money/protocol/curation-vaults).

## Router

**FiraRouter** is the protocol's transaction aggregator. It dispatches user calls to modular action contracts, combining multi-step flows into single transactions:

| Action Module          | Function                                              |
| ---------------------- | ----------------------------------------------------- |
| **ActionBorrow**       | Collateral deposit → BT borrow → swap to output token |
| **ActionSimple**       | Direct swaps between tokens, BT, and CT               |
| **ActionAddRemoveLiq** | LP deposits and withdrawals                           |
| **ActionSwapCT**       | Complex swaps involving Coupon Tokens                 |
| **ActionMisc**         | FW minting, reward redemption, utility operations     |

From the user's perspective, the router is the single entry point. Complex operations — deposit collateral, borrow, swap, and receive USDC — execute in one transaction.

## Interest Rate Models

Fira supports two interest rate strategies:

| Model                       | Used For              | Behavior                                              |
| --------------------------- | --------------------- | ----------------------------------------------------- |
| **Fixed Rate (address(0))** | Markets like UZR      | No interest accrual — rate is embedded in BT discount |
| **AdaptiveCurveIRM**        | Variable-rate markets | Dynamically adjusts borrow rate based on utilization  |

The AdaptiveCurveIRM uses a rate target that evolves over time, combined with a utilization curve that steepens above target utilization. For the full IRM specification, see [Floating-Rate Markets](https://docs.fira.money/protocol/floating-rate-markets).

## Oracles

Price oracles feed collateral valuations into the LendingMarket for LTV checks and liquidation triggers:

| Oracle Type                    | Use Case                                       |
| ------------------------------ | ---------------------------------------------- |
| **Chainlink / Redstone feeds** | Market-priced collateral (ETH, BTC, PT tokens) |
| **Exchange rate oracles**      | Wrapped or rebasing tokens (stETH/ETH)         |
| **Fixed-price oracles**        | Pegged pairs (USD0/bUSD0 at 1:1)               |

For how oracles interact with liquidations, see [Liquidations](https://docs.fira.money/protocol/liquidations).

## Liquidity Injector

The **LiquidityInjector** is a protocol-controlled contract that can mint BT on demand and supply it to the LendingMarket. This seeds fixed-rate lending markets without relying on external capital at launch. Only the authorized multisig can operate this contract. The injector can also withdraw and burn BT to reduce supply.

## How the Layers Connect

A typical fixed-rate borrowing flow illustrates how layers interact:

1. **Token Layer** — User wraps USDC into FW-USDC
2. **LendingMarket** — User supplies collateral, borrows BT
3. **Fixed-Rate AMM** — User swaps BT for FW-USDC at a discount
4. **Token Layer** — User unwraps FW-USDC to USDC
5. **Rehypothecation** — Idle FW reserves earn floating yield in variable-rate vaults
6. **Curation** — Curated vaults may allocate capital across multiple markets and maturities

The router compresses steps 1–4 into a single transaction.

## Related

* [Fixed-Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) — BT/FW AMM mechanics and rate discovery
* [Floating-Rate Markets](https://docs.fira.money/protocol/floating-rate-markets) — Variable-rate lending and IRM
* [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) — Reserve allocation and CT yield
* [Liquidations](https://docs.fira.money/protocol/liquidations) — Enforcement and oracle integration
* [Curation Vaults](https://docs.fira.money/protocol/curation-vaults) — Multi-layer capital allocation
* [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) — BT, CT, FW specifications
* [Contracts & Addresses](https://docs.fira.money/resources/contracts-addresses) — Deployed contract addresses