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.

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.

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.

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.

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.

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.

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.

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 — BT/FW AMM mechanics and rate discovery

• Floating-Rate Markets — Variable-rate lending and IRM

• Rehypothecation — Reserve allocation and CT yield

• Liquidations — Enforcement and oracle integration

• Curation Vaults — Multi-layer capital allocation

• Token Mechanics — BT, CT, FW specifications

• Contracts & Addresses — Deployed contract addresses