# Table of Contents - [What is Fira | Fira Docs](#what-is-fira-fira-docs) - [How It Works | Fira Docs](#how-it-works-fira-docs) - [Markets Overview | Fira Docs](#markets-overview-fira-docs) - [Borrower Guide | Fira Docs](#borrower-guide-fira-docs) - [Lender Guide | Fira Docs](#lender-guide-fira-docs) - [Token Mechanics | Fira Docs](#token-mechanics-fira-docs) - [Architecture Overview | Fira Docs](#architecture-overview-fira-docs) - [FAQ | Fira Docs](#faq-fira-docs) - [Fixed-Rate Markets | Fira Docs](#fixed-rate-markets-fira-docs) - [LP Guide | Fira Docs](#lp-guide-fira-docs) - [Curation Vaults | Fira Docs](#curation-vaults-fira-docs) - [Liquidation Risk | Fira Docs](#liquidation-risk-fira-docs) - [Rehypothecation | Fira Docs](#rehypothecation-fira-docs) - [Audits | Fira Docs](#audits-fira-docs) - [Liquidations | Fira Docs](#liquidations-fira-docs) - [Interest Rate Risk | Fira Docs](#interest-rate-risk-fira-docs) - [Smart Contract Risk | Fira Docs](#smart-contract-risk-fira-docs) - [Protocol Primer | Fira Docs](#protocol-primer-fira-docs) - [Risk Framework | Fira Docs](#risk-framework-fira-docs) - [Architecture | Fira Docs](#architecture-fira-docs) - [Security Overview | Fira Docs](#security-overview-fira-docs) - [Bad Debt Risk | Fira Docs](#bad-debt-risk-fira-docs) - [Tech Hub | Fira Docs](#tech-hub-fira-docs) - [Token Contracts | Fira Docs](#token-contracts-fira-docs) - [Fixed-Rate Lending | Fira Docs](#fixed-rate-lending-fira-docs) - [FiraMarket | Fira Docs](#firamarket-fira-docs) - [Liquidity Risk | Fira Docs](#liquidity-risk-fira-docs) - [Router Architecture | Fira Docs](#router-architecture-fira-docs) - [Liquidity Injector | Fira Docs](#liquidity-injector-fira-docs) - [Features | Fira Docs](#features-fira-docs) - [Collateral Risk | Fira Docs](#collateral-risk-fira-docs) - [Floating-Rate Markets | Fira Docs](#floating-rate-markets-fira-docs) - [YieldContractFactory | Fira Docs](#yieldcontractfactory-fira-docs) - [Core | Fira Docs](#core-fira-docs) - [Rehypothecation | Fira Docs](#rehypothecation-fira-docs) - [Bond Token | Fira Docs](#bond-token-fira-docs) - [FiraERC20 | Fira Docs](#firaerc20-fira-docs) - [Yield Contracts | Fira Docs](#yield-contracts-fira-docs) - [Bond Token | Fira Docs](#bond-token-fira-docs) - [Protocol Contracts | Fira Docs](#protocol-contracts-fira-docs) - [FW (FiraWrapped) | Fira Docs](#fw-firawrapped-fira-docs) - [ActionSwapBT | Fira Docs](#actionswapbt-fira-docs) - [ActionMisc | Fira Docs](#actionmisc-fira-docs) - [Contract Deployments | Fira Docs](#contract-deployments-fira-docs) - [MarketMathCore | Fira Docs](#marketmathcore-fira-docs) - [ActionSwapCT | Fira Docs](#actionswapct-fira-docs) - [Coupon Token (CT) | Fira Docs](#coupon-token-ct-fira-docs) - [Liquidity Injector | Fira Docs](#liquidity-injector-fira-docs) - [Coupon Token | Fira Docs](#coupon-token-fira-docs) - [Bond Token (BT) | Fira Docs](#bond-token-bt-fira-docs) - [Utility Contracts | Fira Docs](#utility-contracts-fira-docs) - [Helpers | Fira Docs](#helpers-fira-docs) - [Libraries | Fira Docs](#libraries-fira-docs) - [Oracles | Fira Docs](#oracles-fira-docs) - [FiraMarketFactory | Fira Docs](#firamarketfactory-fira-docs) - [ActionAddRemoveLiq | Fira Docs](#actionaddremoveliq-fira-docs) - [Rehypothecation Module | Fira Docs](#rehypothecation-module-fira-docs) - [Risk Disclaimers | Fira Docs](#risk-disclaimers-fira-docs) - [Fira Market AMM | Fira Docs](#fira-market-amm-fira-docs) - [Solvency Oracle | Fira Docs](#solvency-oracle-fira-docs) - [LP Oracle | Fira Docs](#lp-oracle-fira-docs) - [ActionSimple | Fira Docs](#actionsimple-fira-docs) - [Lending | Fira Docs](#lending-fira-docs) - [Audits | Fira Docs](#audits-fira-docs) - [BC Oracle | Fira Docs](#bc-oracle-fira-docs) - [Variable-Rate Lending | Fira Docs](#variable-rate-lending-fira-docs) - [FW Tokens | Fira Docs](#fw-tokens-fira-docs) - [ActionBorrow | Fira Docs](#actionborrow-fira-docs) - [Coupon Token | Fira Docs](#coupon-token-fira-docs) - [Glossary | Fira Docs](#glossary-fira-docs) - [Math | Fira Docs](#math-fira-docs) - [Repay Fixed Rate | Fira Docs](#repay-fixed-rate-fira-docs) - [Events & Indexing | Fira Docs](#events-indexing-fira-docs) - [Interfaces | Fira Docs](#interfaces-fira-docs) - [Provide Liquidity | Fira Docs](#provide-liquidity-fira-docs) - [Security Practices | Fira Docs](#security-practices-fira-docs) - [Integrations | Fira Docs](#integrations-fira-docs) - [Glossary | Fira Docs](#glossary-fira-docs) - [Whitepaper | Fira Docs](#whitepaper-fira-docs) - [Repay Variable Rate | Fira Docs](#repay-variable-rate-fira-docs) - [Remove Liquidity | Fira Docs](#remove-liquidity-fira-docs) - [Router | Fira Docs](#router-fira-docs) - [Integrations | Fira Docs](#integrations-fira-docs) - [User Flows | Fira Docs](#user-flows-fira-docs) - [FW Deposit & Redeem | Fira Docs](#fw-deposit-redeem-fira-docs) - [Contracts & Addresses | Fira Docs](#contracts-addresses-fira-docs) - [Trade BT/CT | Fira Docs](#trade-bt-ct-fira-docs) - [Event Table | Fira Docs](#event-table-fira-docs) - [Borrow Fixed Rate | Fira Docs](#borrow-fixed-rate-fira-docs) - [Pre/Post Expiry Exits | Fira Docs](#pre-post-expiry-exits-fira-docs) - [Terms of Use | Fira Docs](#terms-of-use-fira-docs) - [Reward Measurement | Fira Docs](#reward-measurement-fira-docs) - [Bug Bounty | Fira Docs](#bug-bounty-fira-docs) - [Variable Rate Lending | Fira Docs](#variable-rate-lending-fira-docs) - [Security Design | Fira Docs](#security-design-fira-docs) - [Privacy Policy | Fira Docs](#privacy-policy-fira-docs) - [Deployment | Fira Docs](#deployment-fira-docs) - [Email Protection | Cloudflare](#email-protection-cloudflare) --- # What is Fira | Fira Docs Fira is a fixed-rate lending and borrowing protocol. It introduces maturity-based credit as a native onchain primitive — something DeFi has lacked since inception. [hashtag](https://docs.fira.money/#the-problem-defi-has-no-time-dimension) The Problem: DeFi Has No Time Dimension ----------------------------------------------------------------------------------------------------------------------- Over $60B sits in onchain lending markets. More than 99% of that exposure is floating-rate. Rates change every block. No maturities. No yield curve. This creates three structural gaps: * **Borrowers** cannot lock in their cost of capital * **Lenders** cannot predict returns with certainty * **Treasuries** cannot match assets to future obligations Traditional credit markets operate on $145T of fixed-rate instruments — mortgages, corporate bonds, sovereign debt. These work because they have defined terms and known rates. DeFi has none of this. [hashtag](https://docs.fira.money/#what-fira-does) What Fira Does ---------------------------------------------------------------------- Fira adds the missing dimension to onchain credit: **time**. Every Fira loan has a defined maturity, a fixed rate locked at origination, and composable tokens that represent the position: * **Bond Tokens (BTs)** represent the claim on principal at maturity. They trade at a discount before maturity and redeem 1:1 at term. * **Coupon Tokens (CTs)** represent the yield portion. They accrue interest over time and can be sold for upfront yield. * **FiraWrapped (FW)** tokens standardize yield-bearing collateral assets for use across Fira markets. These tokens are tradable and composable. They create an onchain yield curve — a rate structure across maturities that DeFi has never had. [hashtag](https://docs.fira.money/#how-it-works) How It Works ------------------------------------------------------------------ 1. **Deposit collateral** into a Fira market 2. **Borrow at a fixed rate** — the rate is locked at origination, visible before execution 3. **At maturity**, BTs redeem 1:1. The borrower repays principal plus the accrued fee. The lender receives their principal back. No variable rates. No surprise costs. The terms are set at entry. > [Detailed mechanics](https://docs.fira.money/getting-started/how-it-works) [hashtag](https://docs.fira.money/#markets) Markets -------------------------------------------------------- Fira is infrastructure, not a single product. Each **market** is an independent instance with its own collateral, loan token, parameters, and risk profile. > [Markets Overview](https://docs.fira.money/guides/overview) [hashtag](https://docs.fira.money/#security) Security ---------------------------------------------------------- Six independent audits before launch. Up to $500K bug bounty. Immutable interest rate contracts. > [Security overview](https://docs.fira.money/security-and-risk/security-overview) > · [Audits](https://docs.fira.money/security-and-risk/audits) > · [Bug bounty](https://docs.fira.money/security-and-risk/bug-bounty) [hashtag](https://docs.fira.money/#links) Links ---------------------------------------------------- * [Apparrow-up-right](https://app.fira.money/) * [Simulatorarrow-up-right](https://simulator.fira.money/) * [DeFiLlamaarrow-up-right](https://defillama.com/protocol/tvl/fira) * [Dune Dashboardarrow-up-right](https://dune.com/usual_team/fira) [NextHow It Workschevron-right](https://docs.fira.money/getting-started/how-it-works) Last updated 1 day ago --- # How It Works | Fira Docs Fira is a fixed-rate lending protocol. Borrowers lock a rate for a defined period. Lenders earn predictable yield through Bond Tokens (BTs). Every position has a maturity date and a rate set at origination. [hashtag](https://docs.fira.money/getting-started/how-it-works#the-core-loop) The Core Loop ------------------------------------------------------------------------------------------------ 1. **Deposit collateral** — A borrower deposits an accepted collateral asset into a Fira market. 2. **Borrow at a fixed rate** — The protocol mints Bond Tokens (BTs) and Coupon Tokens (CTs). The borrower receives the loan token. The rate is locked. 3. **Maturity** — At the end of the term, BTs redeem 1:1. The borrower repays principal + accrued fee. The lender receives their principal back. This loop runs the same way in every Fira market. The collateral, loan token, rate, and maturity change — the structure does not. [hashtag](https://docs.fira.money/getting-started/how-it-works#fixed-rates-vs.-floating-rates) Fixed Rates vs. Floating Rates ---------------------------------------------------------------------------------------------------------------------------------- Floating-rate DeFi lending Fira **Rate** Changes every block based on utilization Fixed at origination for the full term **Term** Open-ended — no maturity Defined maturity date **Predictability** None — rates can spike 10x in a day Full — cost and yield known at entry **Position tokens** Vault/Market Tokens BT (principal) + CT (yield) — composable, tradable [hashtag](https://docs.fira.money/getting-started/how-it-works#key-concepts) Key Concepts ---------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/getting-started/how-it-works#bond-token-bt) Bond Token (BT) Represents a claim on principal at maturity. Analogous to a zero-coupon bond. Trades at a discount before maturity and redeems 1:1 at term. ### [hashtag](https://docs.fira.money/getting-started/how-it-works#coupon-token-ct) Coupon Token (CT) Represents the yield portion of a lending position. Accrues interest over time. Can be sold early for upfront yield or held to maturity. ### [hashtag](https://docs.fira.money/getting-started/how-it-works#firawrapped-fw) FiraWrapped (FW) Wrapped yield-bearing tokens that standardize different collateral assets for use in Fira markets. FW tokens make any yield-bearing asset compatible with Fira's lending infrastructure. ### [hashtag](https://docs.fira.money/getting-started/how-it-works#markets) Markets Each Fira market is an independent instance defined by a collateral asset, a loan asset, and a set of parameters (LTV, oracle, fee, maturity). > [Full token mechanics](https://docs.fira.money/protocol/token-mechanics) > · [Architecture overview](https://docs.fira.money/protocol/architecture-overview) [hashtag](https://docs.fira.money/getting-started/how-it-works#for-different-users) For Different Users ------------------------------------------------------------------------------------------------------------ **Borrowers** borrow at a known cost. No surprise rate hikes. The total cost of the loan is visible before execution. > [Borrower Guide](https://docs.fira.money/guides/borrower-guide) **Lenders** earn predictable yield by purchasing BTs at a discount. The return is set at purchase — not subject to utilization changes. > [Lender Guide](https://docs.fira.money/guides/lender-guide) **LPs** provide liquidity to the rate discovery AMM and earn trading fees plus rehypothecation yield. > [LP Guide](https://docs.fira.money/guides/lp-guide) [PreviousWhat is Firachevron-left](https://docs.fira.money/) [NextFAQchevron-right](https://docs.fira.money/getting-started/faq) Last updated 1 day ago --- # Markets Overview | Fira Docs Fira is modular lending infrastructure. Each **market** is an independent instance with its own collateral, loan token, parameters, and risk profile. [hashtag](https://docs.fira.money/guides/overview#what-defines-a-market) What Defines a Market --------------------------------------------------------------------------------------------------- Every Fira market is defined by: Parameter Description **Collateral asset** The token deposited by borrowers **Loan asset** The token borrowed against collateral **Max LTV (Loan-to-Value)** Maximum borrowing ratio **LLTV** Liquidation LTV — the threshold at which positions can be liquidated **Oracle** Price feed determining collateral value **Maturity** Term length for fixed-rate positions **Protocol fee** Fee charged by the protocol (in APR) **IRM** Interest Rate Model governing rate discovery This modular design means Fira can support any pair of assets — stablecoins, yield-bearing tokens, LSTs, or governance tokens — each with parameters calibrated to the specific risk profile of that pair. [hashtag](https://docs.fira.money/guides/overview#v1-market-types) V1 Market Types --------------------------------------------------------------------------------------- Fira V1 introduces three market types, each serving different credit needs: ### [hashtag](https://docs.fira.money/guides/overview#fixed-rate-markets) Fixed-Rate Markets Borrowers and lenders lock rates for a defined maturity via Bond Tokens (BTs). BTs trade at a discount before maturity on the fixed-rate AMM. The discount determines the implied rate. > [Fixed-Rate Markets — Protocol](https://docs.fira.money/protocol/fixed-rate-markets) ### [hashtag](https://docs.fira.money/guides/overview#floating-rate-markets) Floating-Rate Markets Variable-rate borrowing and lending without maturity constraints. Rates adjust dynamically based on utilization — similar to existing DeFi lending protocols, but integrated into Fira's infrastructure. > [Floating-Rate Markets — Protocol](https://docs.fira.money/protocol/floating-rate-markets) ### [hashtag](https://docs.fira.money/guides/overview#dynamic-lending) Dynamic Lending LPs provide liquidity to the fixed-rate AMM while unused liquidity is rehypothecated to floating-rate vaults. LPs earn both trading fees and lending yield. Coupon Tokens (CTs) represent the yield portion and are tradable. > [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) > · [Fixed-Rate Markets — Protocol](https://docs.fira.money/protocol/fixed-rate-markets) > · [Floating-Rate Markets — Protocol](https://docs.fira.money/protocol/floating-rate-markets) [hashtag](https://docs.fira.money/guides/overview#related) Related ----------------------------------------------------------------------- * [Architecture Overview](https://docs.fira.money/protocol/architecture-overview) — How markets connect to the broader system * [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) — BT, CT, and FW token mechanics * [Risk Framework](https://docs.fira.money/security-and-risk/risk-framework) — How risk is assessed per market [PreviousFAQchevron-left](https://docs.fira.money/getting-started/faq) [NextBorrower Guidechevron-right](https://docs.fira.money/guides/borrower-guide) Last updated 1 day ago * [What Defines a Market](https://docs.fira.money/guides/overview#what-defines-a-market) * [V1 Market Types](https://docs.fira.money/guides/overview#v1-market-types) * [Fixed-Rate Markets](https://docs.fira.money/guides/overview#fixed-rate-markets) * [Floating-Rate Markets](https://docs.fira.money/guides/overview#floating-rate-markets) * [Dynamic Lending](https://docs.fira.money/guides/overview#dynamic-lending) * [Related](https://docs.fira.money/guides/overview#related) --- # Borrower Guide | Fira Docs [hashtag](https://docs.fira.money/guides/borrower-guide#the-problem-with-variable-rates) The Problem with Variable Rates ----------------------------------------------------------------------------------------------------------------------------- On Aave or Compound, your borrowing rate changes every block. You open a position at 3% and wake up to 15%. There is no way to plan, budget, or manage the cost of capital over time. In traditional finance, $145 trillion of credit operates at fixed rates. In DeFi, less than 1% does. Fira closes this gap. [hashtag](https://docs.fira.money/guides/borrower-guide#how-fira-fixes-your-rate) How Fira Fixes Your Rate --------------------------------------------------------------------------------------------------------------- Fira uses **Bond Tokens (BT)** — zero-coupon bonds that trade at a discount before maturity and converge to par (face value) at maturity. The borrowing cost is not an interest rate applied on top of your loan. It is embedded in the discount at which you receive liquidity. **The discount IS the rate. There is no hidden interest.** ### [hashtag](https://docs.fira.money/guides/borrower-guide#how-it-works) How It Works 1. You post collateral 2. The protocol mints BT against your collateral 3. You swap BT for USDC (via FW-USDC) at a discount 4. At maturity, you repay the BT at par value to unlock your collateral The difference between what you received and what you repay is your total, fixed cost of borrowing — known from the moment you open the position. [hashtag](https://docs.fira.money/guides/borrower-guide#concrete-example-fixed-rate-borrowing) Concrete Example: Fixed-Rate Borrowing ------------------------------------------------------------------------------------------------------------------------------------------ **Scenario:** You want to borrow USDC against collateral on the June 25, 2026 maturity market. Step Action Amount 1 Post collateral (e.g., PT-reUSD) Sufficient for desired borrow 2 Mint 100 BT-USDC 100 BT-USDC 3 Swap 100 BT-USDC for FW-USDC, then unwrap to USDC Receive ~95 USDC 4 At maturity (June 25), repay 100 BT-USDC Repay 100 USDC equivalent **Result:** * You received 95 USDC today * You repay 100 at maturity * **Fixed cost = 5 USDC, known from day 1** * Annualized: approximately 5.26% on a ~4-month term — locked at origination No rate changes. No surprises. No variable rate volatility. [hashtag](https://docs.fira.money/guides/borrower-guide#v1-new-features-for-borrowers) V1: New Features for Borrowers -------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/guides/borrower-guide#pendle-pt-collateral) Pendle PT Collateral V1 introduces **Pendle PT tokens** as accepted collateral for fixed-rate borrowing: If you already hold Pendle PTs, you can now borrow at a fixed rate against them on Fira — no need to sell your PT position. ### [hashtag](https://docs.fira.money/guides/borrower-guide#multiple-maturities) Multiple Maturities V1 launches with the ability to add any set of maturity markets: Choose the maturity that matches your investment horizon. Shorter maturities carry lower duration risk. Longer maturities may offer different implied rates. ### [hashtag](https://docs.fira.money/guides/borrower-guide#fixed-rate-markets) Fixed-Rate Markets V1 fixed-rate markets use market-discovered rates. You choose a maturity, the AMM discovers the rate through supply and demand. The rate you get at the moment of your swap is your fixed rate for the duration. ### [hashtag](https://docs.fira.money/guides/borrower-guide#floating-rate-markets) Floating-Rate Markets Floating rate markets are available on Fira as well and are designed similarly to other protocols. These rates are spot and floating as they can dynamically changes based on the utilization of supplied assets in the market. [hashtag](https://docs.fira.money/guides/borrower-guide#fira-fixed-rate-vs.-variable-rate-protocols) Fira Fixed Rate vs. Variable Rate Protocols ----------------------------------------------------------------------------------------------------------------------------------------------------- Feature Fira (Fixed Rate) Aave / Compound (Variable Rate) **Rate predictability** Fixed at origination. Known from day 1. Changes every block based on utilization. **Rate mechanism** Discount on zero-coupon bond (BT). No explicit interest charge. Utilization curve. Interest accrues continuously at variable rate. **Cost visibility** Total cost known upfront in USDC terms. Total cost unknown until position is closed. **Maturity** Defined. None. Open-ended. **Early repayment** Possible at any time. Effective rate may differ from initial rate. Always at current variable rate. **Rate spikes** Position is immune to rate spikes after origination. Exposed to sudden rate increases (can jump 3% to 15% in one block). [hashtag](https://docs.fira.money/guides/borrower-guide#risk-disclosure) Risk Disclosure --------------------------------------------------------------------------------------------- Borrowing on Fira carries material risks. Read this section carefully before committing capital. ### [hashtag](https://docs.fira.money/guides/borrower-guide#liquidation-risk) Liquidation Risk If the health factor of your position drops below 1, your collateral becomes eligible for liquidation. The health factor depends on the Loan-to-Value ratio relative to the Liquidation LTV threshold. * **V1 fixed-rate markets:** Collateral value depends on oracle pricing. PT collateral carries price exposure. Market movements can trigger liquidation before maturity. Liquidators receive a bonus (Liquidation Incentive Factor up to 1.15x depending on LLTV), meaning you lose more collateral than the debt repaid. For full liquidation mechanics, see [Liquidations](https://docs.fira.money/protocol/liquidations) . ### [hashtag](https://docs.fira.money/guides/borrower-guide#early-repayment-does-not-lock-the-fixed-rate) Early Repayment Does Not Lock the Fixed Rate The fixed rate is only realized **if you hold the position to maturity**. If you repay early: * You still repay the original BT amount (no reduction in principal) * But the effective rate may be higher or lower than the rate at origination, depending on the BT/FW-USDC exchange rate at the time of early repayment Early repayment always costs less than or equal to the maximum cost at maturity, but the effective annualized rate is unpredictable. ### [hashtag](https://docs.fira.money/guides/borrower-guide#smart-contract-risk) Smart Contract Risk Fira is a newly deployed protocol. Despite six independent external audits, an extended internal review, and a bug bounty program up to $500K, residual risk of bugs, exploits, or loss of funds remains. For audit details, see [Audits](https://docs.fira.money/security-and-risk/audits) . ### [hashtag](https://docs.fira.money/guides/borrower-guide#additional-risks) Additional Risks * **Slippage risk:** Large swaps on the AMM may incur price impact, especially in low-liquidity conditions * **Oracle risk:** V1 markets rely on external price feeds (Chainlink, Redstone) for collateral valuation * **One-way migration:** Positions migrated from Euler to Fira cannot be sent back For the complete risk framework, see [Risk Framework](https://docs.fira.money/security-and-risk/risk-framework) . [hashtag](https://docs.fira.money/guides/borrower-guide#related) Related ----------------------------------------------------------------------------- * [Fixed Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) - Detailed explanation of the mechanics behind fixed rate markets * [Floating Rate Markets](https://docs.fira.money/protocol/floating-rate-markets) - Detailed explanation of the mechanics behind floating rate markets * [Liquidations](https://docs.fira.money/protocol/liquidations) — Position health and liquidation mechanics _This document is for informational purposes only and does not constitute financial advice. DeFi participation carries risk of partial or total loss of funds. All parameters are subject to governance approval._ [PreviousMarkets Overviewchevron-left](https://docs.fira.money/guides/overview) [NextLender Guidechevron-right](https://docs.fira.money/guides/lender-guide) Last updated 1 day ago * [The Problem with Variable Rates](https://docs.fira.money/guides/borrower-guide#the-problem-with-variable-rates) * [How Fira Fixes Your Rate](https://docs.fira.money/guides/borrower-guide#how-fira-fixes-your-rate) * [How It Works](https://docs.fira.money/guides/borrower-guide#how-it-works) * [Concrete Example: Fixed-Rate Borrowing](https://docs.fira.money/guides/borrower-guide#concrete-example-fixed-rate-borrowing) * [V1: New Features for Borrowers](https://docs.fira.money/guides/borrower-guide#v1-new-features-for-borrowers) * [Pendle PT Collateral](https://docs.fira.money/guides/borrower-guide#pendle-pt-collateral) * [Multiple Maturities](https://docs.fira.money/guides/borrower-guide#multiple-maturities) * [Fixed-Rate Markets](https://docs.fira.money/guides/borrower-guide#fixed-rate-markets) * [Floating-Rate Markets](https://docs.fira.money/guides/borrower-guide#floating-rate-markets) * [Fira Fixed Rate vs. Variable Rate Protocols](https://docs.fira.money/guides/borrower-guide#fira-fixed-rate-vs.-variable-rate-protocols) * [Risk Disclosure](https://docs.fira.money/guides/borrower-guide#risk-disclosure) * [Liquidation Risk](https://docs.fira.money/guides/borrower-guide#liquidation-risk) * [Early Repayment Does Not Lock the Fixed Rate](https://docs.fira.money/guides/borrower-guide#early-repayment-does-not-lock-the-fixed-rate) * [Smart Contract Risk](https://docs.fira.money/guides/borrower-guide#smart-contract-risk) * [Additional Risks](https://docs.fira.money/guides/borrower-guide#additional-risks) * [Related](https://docs.fira.money/guides/borrower-guide#related) --- # Lender Guide | Fira Docs [hashtag](https://docs.fira.money/guides/lender-guide#the-missing-piece-in-defi-lending) The Missing Piece in DeFi Lending ------------------------------------------------------------------------------------------------------------------------------- On existing DeFi lending platforms, your yield changes every block. You deposit at 5% APR and a week later it is 2%. Or 12%. There is no way to know what you will earn over a defined period. Global fixed-income markets represent $145 trillion. DeFi lending holds approximately $64 billion — roughly 0.04% penetration. The gap is not yield. It is predictability. Fira introduces fixed-rate lending onchain, where the return is known at the moment of purchase, not revealed after the fact. [hashtag](https://docs.fira.money/guides/lender-guide#how-fixed-rate-lending-works-on-fira) How Fixed-Rate Lending Works on Fira ------------------------------------------------------------------------------------------------------------------------------------- Fira uses **Bond Tokens (BT)** — zero-coupon bonds that trade at a discount before maturity and redeem at par (face value) when the maturity date is reached. As a lender, you buy BT at a discount. At maturity, each BT redeems for 1 unit of the underlying asset. **The discount is your fixed yield.** There is no interest rate that accrues daily. There is no utilization curve. You buy below par, you redeem at par. The difference is your return, known in advance. ### [hashtag](https://docs.fira.money/guides/lender-guide#step-by-step) Step-by-Step 1. Wrap USDC into FW-USDC (Fira Wrapped USDC) 2. Use FW-USDC to buy BT-USDC on the fixed-rate AMM at a discount 3. Hold BT-USDC until maturity 4. At maturity, redeem BT-USDC for FW-USDC at par (1:1) 5. Unwrap FW-USDC back to USDC The yield is locked at step 2 — the moment you purchase BT at its market price. [hashtag](https://docs.fira.money/guides/lender-guide#concrete-example-lending-at-a-fixed-rate) Concrete Example: Lending at a Fixed Rate ---------------------------------------------------------------------------------------------------------------------------------------------- **Scenario:** You want to earn a fixed return on the May 14, 2026 maturity market. Step Action Amount 1 Wrap 95 USDC into FW-USDC 95 FW-USDC (at 1:1 initial rate) 2 Buy 100 BT-USDC on the AMM Pay 95 FW-USDC, receive 100 BT-USDC 3 Hold until maturity — 4 Redeem 100 BT-USDC at par Receive 100 FW-USDC 5 Unwrap FW-USDC to USDC Receive ~100 USDC **Result:** * You deposited 95 USDC * You received 100 USDC at maturity * **Fixed yield = 5 USDC, known at the moment of purchase** * Annualized: approximately 5.26% on a ~2-month term The return is determined by the BT price at purchase. Once bought, rate movements in the broader market do not affect your position. You hold to maturity, you receive par. [hashtag](https://docs.fira.money/guides/lender-guide#bt-a-composable-fixed-income-primitive) BT: A Composable Fixed-Income Primitive ------------------------------------------------------------------------------------------------------------------------------------------ BT-USDC is not locked or staked. It is a standard **ERC-20 token** that can be: * **Held to maturity** for the fixed yield * **Sold before maturity** on the Fira AMM at the current market price * **Transferred** to any Ethereum address * **Used as collateral** in other DeFi protocols that accept ERC-20 tokens * **Integrated** into structured strategies (e.g., fixed-rate tranches, hedging instruments) BT is the onchain equivalent of a zero-coupon bond. It is the building block for fixed-income strategies in DeFi. For full token mechanics, see [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) . [hashtag](https://docs.fira.money/guides/lender-guide#two-ways-to-lend) Two Ways to Lend --------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/guides/lender-guide#option-1-fixed-rates-direct-bt-purchase) Option 1: Fixed Rates - Direct BT Purchase Buy BT-USDC directly on the fixed-rate AMM. You choose the maturity, you see the price, you know the return. Full control over entry timing and maturity selection. **Best for:** Advanced users, DAO treasuries with specific maturity targets, investors who want to manage duration actively. **Token received:** BT-USDC — a tradable ERC-20 token. BT can be held, sold on the AMM before maturity (at market price), or used in other DeFi strategies. It is composable. ### [hashtag](https://docs.fira.money/guides/lender-guide#option-2-floating-rates-supply-to-market-vault) Option 2: Floating Rates (Supply to Market/Vault) Deposit USDC into a **floating rate market or** **curated vault.** By depositing directly into a market, the user earns the lending rate from that market and is exposed to any risk associated with that market (bad debt risk). On the other hand, the curated vault has a professional curator allocates capital across floating-rate markets on your behalf. The curator manages maturity selection, rate optimization, and risk parameters within DAO-approved constraints. **How it works:** * Deposit USDC into the market or vault * _Curated vault_: The curator allocates across available maturities and market types * The market or vault share appreciates as yield accrues * Withdraw at any time (subject to vault liquidity) For more on curation and floating rate markets, see [Curation Vaults](https://docs.fira.money/protocol/curation-vaults) or [Floating Rate Markets](https://docs.fira.money/protocol/floating-rate-markets) . [hashtag](https://docs.fira.money/guides/lender-guide#what-fira-is-not) What Fira Is Not --------------------------------------------------------------------------------------------- To set expectations accurately: Misconception Reality "Fixed yield means no risk" Fixed rate means the return is predictable **if held to maturity**. Other risks (smart contract, bad debt) remain. "I can exit anytime at the fixed rate" Exiting before maturity means selling BT at market price. The effective yield may be higher or lower than the implied rate at purchase. "The rate is set by the protocol" Rates are discovered by market supply and demand in the AMM. The protocol does not set rates. "This is a savings account" This is a DeFi lending position with smart contract risk, bad debt risk, and market risk. [hashtag](https://docs.fira.money/guides/lender-guide#risk-disclosure) Risk Disclosure ------------------------------------------------------------------------------------------- Lending on Fira carries material risks. Read this section carefully before depositing capital. ### [hashtag](https://docs.fira.money/guides/lender-guide#fixed-rate-applies-only-at-maturity) Fixed Rate Applies Only at Maturity The fixed rate is the return you receive **if you hold BT to maturity and redeem at par**. If you sell BT before maturity: * You sell at the current AMM market price * The effective yield may be higher or lower than the rate implied at purchase * In a rising-rate environment, BT prices drop (you sell at a loss relative to par) * In a falling-rate environment, BT prices rise (you realize a gain before maturity) **The word "fixed" does not mean "risk-free." It means the return is known in advance if held to the defined maturity.** ### [hashtag](https://docs.fira.money/guides/lender-guide#bad-debt-risk) Bad Debt Risk If borrowers' collateral cannot be liquidated for enough value to cover outstanding loans, the shortfall is socialized among lenders. This reduces the FW-USDC/USDC exchange rate, meaning your redemption at maturity may return less than par. Bad debt can originate from: * Fixed-rate borrowers whose collateral drops in value faster than liquidation can execute * Rehypothecated reserves in variable-rate vaults Overcollateralization and liquidation incentives (LIF up to 1.15x) reduce but do not eliminate this risk. For details, see [Bad Debt Risk](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) . ### [hashtag](https://docs.fira.money/guides/lender-guide#smart-contract-risk) Smart Contract Risk Fira is a newly deployed protocol. Despite six independent external audits, an extended internal review, and a bug bounty program up to $500K, residual risk of bugs, exploits, or vulnerabilities remains. Participation in any DeFi protocol carries the risk of partial or total loss of funds. For audit details, see [Audits](https://docs.fira.money/security-and-risk/audits) . ### [hashtag](https://docs.fira.money/guides/lender-guide#liquidity-risk) Liquidity Risk A portion of FW-USDC reserves is rehypothecated into variable-rate vaults. If a large withdrawal coincides with high vault utilization, temporary withdrawal restrictions may apply until the rehypothecation module rebalances. The reserve ratio target is 90%, with only approximately 10% of reserves rehypothecated at any time. For more, see [Liquidity Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk) . [hashtag](https://docs.fira.money/guides/lender-guide#related) Related --------------------------------------------------------------------------- * [Fixed-Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) — How the fixed-rate AMM works * [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) — BT, CT, and FW token design * [Curation Vaults](https://docs.fira.money/protocol/curation-vaults) — Curated vault architecture * [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) — How FW-USDC reserves generate yield * [Audits](https://docs.fira.money/security-and-risk/audits) — Six independent external audits * [Risk Framework](https://docs.fira.money/security-and-risk/risk-framework) — Full risk overview _This document is for informational purposes only and does not constitute financial advice. Returns described are projections based on market mechanics and are not assured. DeFi participation carries risk of partial or total loss of funds. All parameters are subject to governance approval._ [PreviousBorrower Guidechevron-left](https://docs.fira.money/guides/borrower-guide) [NextLP Guidechevron-right](https://docs.fira.money/guides/lp-guide) Last updated 1 day ago * [The Missing Piece in DeFi Lending](https://docs.fira.money/guides/lender-guide#the-missing-piece-in-defi-lending) * [How Fixed-Rate Lending Works on Fira](https://docs.fira.money/guides/lender-guide#how-fixed-rate-lending-works-on-fira) * [Step-by-Step](https://docs.fira.money/guides/lender-guide#step-by-step) * [Concrete Example: Lending at a Fixed Rate](https://docs.fira.money/guides/lender-guide#concrete-example-lending-at-a-fixed-rate) * [BT: A Composable Fixed-Income Primitive](https://docs.fira.money/guides/lender-guide#bt-a-composable-fixed-income-primitive) * [Two Ways to Lend](https://docs.fira.money/guides/lender-guide#two-ways-to-lend) * [Option 1: Fixed Rates - Direct BT Purchase](https://docs.fira.money/guides/lender-guide#option-1-fixed-rates-direct-bt-purchase) * [Option 2: Floating Rates (Supply to Market/Vault)](https://docs.fira.money/guides/lender-guide#option-2-floating-rates-supply-to-market-vault) * [What Fira Is Not](https://docs.fira.money/guides/lender-guide#what-fira-is-not) * [Risk Disclosure](https://docs.fira.money/guides/lender-guide#risk-disclosure) * [Fixed Rate Applies Only at Maturity](https://docs.fira.money/guides/lender-guide#fixed-rate-applies-only-at-maturity) * [Bad Debt Risk](https://docs.fira.money/guides/lender-guide#bad-debt-risk) * [Smart Contract Risk](https://docs.fira.money/guides/lender-guide#smart-contract-risk) * [Liquidity Risk](https://docs.fira.money/guides/lender-guide#liquidity-risk) * [Related](https://docs.fira.money/guides/lender-guide#related) --- # Token Mechanics | Fira Docs Comprehensive reference for Fira's core token types. Fira's fixed-rate markets operate with three primary tokens — BT, CT, and FW — governed by the fundamental invariant: 1FW\=μs(t)BT+μs(t)CT1 \\hspace{0.1cm} \\text{FW} = \\mu\_{s}(t) \\hspace{0.1cm} \\text{BT} + \\mu\_s(t) \\hspace{0.1cm} \\text{CT}1FW\=μs​(t)BT+μs​(t)CT. [hashtag](https://docs.fira.money/protocol/token-mechanics#token-overview) Token Overview ---------------------------------------------------------------------------------------------- Token Full Name Role **FW-XXXX** **Fira Wrapped Asset** Standard asset wrapped within Fira. Mintable and redeemable frictionlessly at any time. Each FW can be deconstructed into one BT and one CT, separating principal and interest components of a fixed-rate position. **BT-XXXX** **Bond Token** Zero-coupon bond representing a borrowed position that must be repaid at or before maturity. BT trades at a discount to FW — the discount reflects the fixed interest cost. At maturity, BT redeems 1:1 for the underlying asset. **CT-XXXX** **Coupon Token** Yield token representing the present value of unrealized interest. When BT is borrowed and swapped for FW at a discount, CT captures the remaining value. CT holders accrue interest and rewards from the underlying yield. * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#wrapping-rate) Wrapping Rate -------------------------------------------------------------------------------------------- All tokens are connected by a single fundamental invariant: μ(t)Underlying\=1FW\=μs(t)BT+μs(t)CT\\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}μ(t)Underlying\=1FW\=μs​(t)BT+μs​(t)CT The wrapping rate μ(t)\\mu(t)μ(t) specifically relates to the relationship between the underlying asset and the wrapped version (FW). We then have a modified version of this rate which is gross of bad debt loss. These two rates are computed as follows: μ(t)\=Reserve(t)Supplied(t)\\mu (t) = \\frac{Reserve(t)}{Supplied(t)}μ(t)\=Supplied(t)Reserve(t)​ Such that μ(t)\\mu(t)μ(t) is initialized at 1 and grows based on the earnings from rehypothecation (see [Rehypothecation](https://docs.fira.money/protocol/token-mechanics#rehypothecation) ). As bad debt is incurred, μ(t)\\mu(t)μ(t) will decrease in value as FW is redeemable for less of the underlying asset. However, the modified wrapping rate μs(t)\\mu \_s(t)μs​(t) will not decrease. This is computed as follows: μs(t)\=max(μ(t),μs(t))\\mu\_s(t) = max(\\mu(t),\\mu\_s(t))μs​(t)\=max(μ(t),μs​(t)) Therefore the modified wrapping rate does not decrease. Specifically we do this for the accounting of yield distributed to CT (see [Rehypothecation](https://docs.fira.money/protocol/token-mechanics#rehypothecation) ) as well as adapting the exchange rate from BT to FW based on this value (see [Fixed Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) ). See the [Whitepaper](https://docs.fira.money/resources/whitepaper) for a full explanation. * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#bond-token-bt) Bond Token (BT) ---------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/protocol/token-mechanics#overview) Overview BT (Bond Token) is an ERC-20 token representing the principal component of a fixed-rate position. Each BT redeems 1:1 into the underlying asset at expiry. ### [hashtag](https://docs.fira.money/protocol/token-mechanics#key-properties) Key Properties * **Standard**: ERC-20 (based on `FiraERC20.sol` -- reentrancy-safe ERC20 base) * **Redemption**: 1:1 for the underlying asset at maturity * **Minting**: Only the corresponding CT contract or the LiquidityInjector can mint or burn BT * **Trading**: Traded in the FiraMarket AMM, borrowed/lent in the lending market * **Stored data**: Associated yield-token address (`FW`), expiry date * **Contract**: [BondToken.solarrow-up-right](https://github.com/usual-dao/fira/blob/master/src/fira_bonding/core/YieldContracts/BondToken.sol) ### [hashtag](https://docs.fira.money/protocol/token-mechanics#price-behavior) Price Behavior BT trades at a discount to FW before maturity. The discount reflects the implied fixed yield (see [Fixed Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) ). As maturity approaches, BT price converges toward 1:1 with the underlying. This convergence mechanism is what creates the fixed-rate dynamic: * Borrowers sell BT at a discount now and repay at par later (the discount is their interest cost) * Lenders buy BT at a discount and redeem at par later (the discount is their fixed yield) > For the full mathematical treatment of fixed-rate pricing, see [Whitepaper](https://docs.fira.money/resources/whitepaper) > . ### [hashtag](https://docs.fira.money/protocol/token-mechanics#creation-methods) Creation Methods 1. **Deconstruction from FW**: Depositing FW into a Fira yield contract splits it into equal quantities of BT + CT 2. **Collateralized borrowing**: Borrowing BT through the LendingMarket against collateral (e.g. WBTC, WETH) 3. **LiquidityInjector minting**: Protocol-authorized contract that can mint BT to seed fixed-rate lending markets, ensuring market liquidity without relying on external actors * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#coupon-token-ct) Coupon Token (CT) -------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/protocol/token-mechanics#overview-1) Overview CT (Coupon Token) is an ERC-20 token that tracks all interest and yield due on a given BT line. CT holders accrue interest and rewards from the underlying yield. ### [hashtag](https://docs.fira.money/protocol/token-mechanics#key-properties-1) Key Properties * **Standard**: ERC-20 (based on `FiraERC20.sol`) * **Function**: Represents the right to yield generated by the principal until maturity * **Parent contract**: `InterestManagerCT.sol` -- handles calculation and distribution of yield from FW based on its exchange rate * **Contract**: [CouponToken.solarrow-up-right](https://github.com/usual-dao/fira/blob/master/src/fira_bonding/core/YieldContracts/CouponToken.sol) * **Interest Manager**: [InterestManagerCT.solarrow-up-right](https://github.com/usual-dao/fira/blob/master/src/fira_bonding/core/YieldContracts/InterestManagerCT.sol) ### [hashtag](https://docs.fira.money/protocol/token-mechanics#yield-mechanics) Yield Mechanics CT increases in value as FW accrues yield (i.e., as the redemption value of FW > 1 underlying). CT holders can: * Hold CT until maturity and redeem for FW gains * Sell CT earlier if market conditions are favorable ### [hashtag](https://docs.fira.money/protocol/token-mechanics#value-proposition) Value Proposition CT represents the present value of unrealized gains from fixed-rate loans. When BT tokens are borrowed and exchanged for their corresponding wrapped assets at a discount, CT tokens can be sold to realize the difference -- capturing the portion of value that was not initially extracted in the BT swap. * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#firawrapped-token-fw) FiraWrapped Token (FW) ------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/protocol/token-mechanics#overview-2) Overview FW (FiraWrapped) is a yield-bearing wrapper for the underlying asset. For example, FW-USDC (also written `USDCFW`) wraps USDC. ### [hashtag](https://docs.fira.money/protocol/token-mechanics#key-properties-2) Key Properties * **Standard**: ERC-20 / ERC-4626 compliant * **Minting**: Users deposit the base asset (e.g. USDC) to mint FW tokens * **Redemption**: FW can be redeemed back for the base asset at any time (frictionless) * **Decomposition**: Each FW can be split into 1 BT + 1 CT via yield contracts * **Exchange rate**: Tracks an exchange rate reflecting yield earned -- 1 FW gradually represents more underlying over time as interest accrues * **Contract**: [USDCFW.solarrow-up-right](https://github.com/usual-dao/fira/blob/master/src/fira_bonding/StandardizedYield/implementations/USDCFW.sol) ### [hashtag](https://docs.fira.money/protocol/token-mechanics#rehypothecation) Rehypothecation FW tokens internally invest a portion of deposited assets to earn yield via the **RehypothecationModule**. Idle USDC from FW is rehypothecated into variable-rate markets to generate yield. The rehypothecation is governed by three parameters: Parameter Description `phiMin` Minimum allowed idle ratio `phiMax` Maximum allowed idle ratio `phiTarget` Target idle ratio to rebalance toward The rebalancing logic moves deposited USDC between two states: * **Idle** USDC held in the FW contract (readily redeemable) * **Invested** USDC as shares in a **SisuVault**, where it earns variable yield by supplying to LendingMarkets Rehypothecation is triggered on FW deposit or redeem function calls, and can also be triggered manually by the FW owner. > For the formal treatment of rehypothecation mechanics, see [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) > and the [Whitepaper](https://docs.fira.money/resources/whitepaper) > . ### [hashtag](https://docs.fira.money/protocol/token-mechanics#role-in-the-amm) Role in the AMM FW serves as the quote asset in the FiraMarket AMM. The AMM pricing of BT relative to FW determines the implied fixed interest rate for a given expiry. * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#token-strategy-summary) Token Strategy Summary -------------------------------------------------------------------------------------------------------------- Token Exposure Strategy **BT** Fixed yield Buy at discount, hold to maturity, redeem 1:1. No exposure to future rate changes. **CT** Floating yield Benefits from rising interest/yield rates. Value increases as FW accrues yield. **FW** Underlying + yield Passive yield from rehypothecation. Can be split into BT+CT for more targeted strategies. **LP** BT + FW (AMM) Exposure to both fixed-yield assets (BT) and yield-bearing tokens (FW), plus trading fee collection. * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#contract-reference) Contract Reference ------------------------------------------------------------------------------------------------------ Component Contract Role BondToken `BondToken.sol` ERC-20 zero-coupon bond, matures 1:1 with underlying CouponToken `CouponToken.sol` ERC-20 yield token, accrues interest from FW FiraWrapped `USDCFW.sol` Yield-bearing wrapper with rehypothecation FiraMarket `FiraMarket.sol` AMM for BT/FW trading and rate discovery LendingMarket `LendingMarket.sol` Core lending vault, collateral, liquidations SisuVault `SisuVault.sol` ERC-4626 vault for rehypothecation * * * [hashtag](https://docs.fira.money/protocol/token-mechanics#further-reading) Further Reading ------------------------------------------------------------------------------------------------ * [Contracts & Addresses](https://docs.fira.money/resources/contracts-addresses) — Deployed contract addresses on Ethereum Mainnet * [Whitepaper](https://docs.fira.money/resources/whitepaper) — Full mathematical treatment [PreviousArchitecture Overviewchevron-left](https://docs.fira.money/protocol/architecture-overview) [NextFixed-Rate Marketschevron-right](https://docs.fira.money/protocol/fixed-rate-markets) Last updated 1 day ago * [Token Overview](https://docs.fira.money/protocol/token-mechanics#token-overview) * [Wrapping Rate](https://docs.fira.money/protocol/token-mechanics#wrapping-rate) * [Bond Token (BT)](https://docs.fira.money/protocol/token-mechanics#bond-token-bt) * [Overview](https://docs.fira.money/protocol/token-mechanics#overview) * [Key Properties](https://docs.fira.money/protocol/token-mechanics#key-properties) * [Price Behavior](https://docs.fira.money/protocol/token-mechanics#price-behavior) * [Creation Methods](https://docs.fira.money/protocol/token-mechanics#creation-methods) * [Coupon Token (CT)](https://docs.fira.money/protocol/token-mechanics#coupon-token-ct) * [Overview](https://docs.fira.money/protocol/token-mechanics#overview-1) * [Key Properties](https://docs.fira.money/protocol/token-mechanics#key-properties-1) * [Yield Mechanics](https://docs.fira.money/protocol/token-mechanics#yield-mechanics) * [Value Proposition](https://docs.fira.money/protocol/token-mechanics#value-proposition) * [FiraWrapped Token (FW)](https://docs.fira.money/protocol/token-mechanics#firawrapped-token-fw) * [Overview](https://docs.fira.money/protocol/token-mechanics#overview-2) * [Key Properties](https://docs.fira.money/protocol/token-mechanics#key-properties-2) * [Rehypothecation](https://docs.fira.money/protocol/token-mechanics#rehypothecation) * [Role in the AMM](https://docs.fira.money/protocol/token-mechanics#role-in-the-amm) * [Token Strategy Summary](https://docs.fira.money/protocol/token-mechanics#token-strategy-summary) * [Contract Reference](https://docs.fira.money/protocol/token-mechanics#contract-reference) * [Further Reading](https://docs.fira.money/protocol/token-mechanics#further-reading) --- # Architecture Overview | Fira Docs 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. [hashtag](https://docs.fira.money/protocol/architecture-overview#system-layers) System Layers -------------------------------------------------------------------------------------------------- Copy ┌─────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────┘ [hashtag](https://docs.fira.money/protocol/architecture-overview#token-layer) 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: μ(t)Underlying\=1FW\=μs(t)BT+μs(t)CT\\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}μ(t)Underlying\=1FW\=μs​(t)BT+μs​(t)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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#fixed-rate-amm) 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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#lending-market) 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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#rehypothecation-module) 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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#curation-vaults-sisuvault) 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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#router) 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. [hashtag](https://docs.fira.money/protocol/architecture-overview#interest-rate-models) 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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#oracles) 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) . [hashtag](https://docs.fira.money/protocol/architecture-overview#liquidity-injector) 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. [hashtag](https://docs.fira.money/protocol/architecture-overview#how-the-layers-connect) 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. [hashtag](https://docs.fira.money/protocol/architecture-overview#related) 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 [PreviousLP Guidechevron-left](https://docs.fira.money/guides/lp-guide) [NextToken Mechanicschevron-right](https://docs.fira.money/protocol/token-mechanics) Last updated 1 day ago * [System Layers](https://docs.fira.money/protocol/architecture-overview#system-layers) * [Token Layer](https://docs.fira.money/protocol/architecture-overview#token-layer) * [Fixed-Rate AMM](https://docs.fira.money/protocol/architecture-overview#fixed-rate-amm) * [Lending Market](https://docs.fira.money/protocol/architecture-overview#lending-market) * [Rehypothecation Module](https://docs.fira.money/protocol/architecture-overview#rehypothecation-module) * [Curation Vaults (SisuVault)](https://docs.fira.money/protocol/architecture-overview#curation-vaults-sisuvault) * [Router](https://docs.fira.money/protocol/architecture-overview#router) * [Interest Rate Models](https://docs.fira.money/protocol/architecture-overview#interest-rate-models) * [Oracles](https://docs.fira.money/protocol/architecture-overview#oracles) * [Liquidity Injector](https://docs.fira.money/protocol/architecture-overview#liquidity-injector) * [How the Layers Connect](https://docs.fira.money/protocol/architecture-overview#how-the-layers-connect) * [Related](https://docs.fira.money/protocol/architecture-overview#related) --- # FAQ | Fira Docs [hashtag](https://docs.fira.money/getting-started/faq#general) General --------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/getting-started/faq#what-is-fira) What is Fira? Fira is a lending and borrowing protocol that brings fixed-rate, maturity-based credit markets onchain. It adds the missing dimension to DeFi lending: time. ### [hashtag](https://docs.fira.money/getting-started/faq#why-does-defi-need-fixed-rates) Why does DeFi need fixed rates? Variable-rate lending requires constant monitoring. Rates shift with every block. Fira enables borrowers to lock a rate at entry and know their cost upfront — the same certainty that defines traditional credit markets, built natively onchain. ### [hashtag](https://docs.fira.money/getting-started/faq#who-built-fira) Who built Fira? Fira was initiated by Steady Labs. ### [hashtag](https://docs.fira.money/getting-started/faq#how-does-fira-work) How does Fira work? Fira decomposes yield-bearing assets into tradable components — Bond Tokens (BT) for principal and Coupon Tokens (CT) for yield. The discount at which BT trades determines the implied fixed rate. See [How It Works](https://docs.fira.money/getting-started/how-it-works) for the full mechanism. ### [hashtag](https://docs.fira.money/getting-started/faq#which-blockchain-is-fira-deployed-on) Which blockchain is Fira deployed on? Ethereum mainnet. Contract addresses are listed on the [Contracts & Addresses](https://docs.fira.money/resources/contracts-addresses) page. [hashtag](https://docs.fira.money/getting-started/faq#features) Features ----------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/getting-started/faq#how-does-fixed-rate-borrowing-work) How does fixed-rate borrowing work? Post collateral, borrow BT, and swap BT for the underlying asset. The exchange rate at the time of the swap locks your effective borrow cost. The router handles all steps in a single transaction. See the [Borrower Guide](https://docs.fira.money/guides/borrower-guide) . ### [hashtag](https://docs.fira.money/getting-started/faq#can-i-lend-at-a-fixed-rate) Can I lend at a fixed rate? Yes — in V1 fixed-rate markets. Lenders swap the underlying for BT at a discount. At maturity, BT redeems 1:1, and the discount is the lender's fixed yield. ### [hashtag](https://docs.fira.money/getting-started/faq#does-fira-offer-variable-rate-markets) Does Fira offer variable-rate markets? Yes. Fira offers variable-rate markets which it calls Floating-Rate Markets. These markets have similar mechanics to other onchain credit protocols such that the rates are spot rates and rely on utilization of the supplied assets to the market. [hashtag](https://docs.fira.money/getting-started/faq#security) Security ----------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/getting-started/faq#is-fira-audited) Is Fira audited? Six independent external audits were completed before launch — by Sherlock (×2), Spearbit/Cantina, yAudit (×2), and Hexens. All findings were resolved before deployment. Full reports are available on the [Security](https://docs.fira.money/security-and-risk/security-overview) page. ### [hashtag](https://docs.fira.money/getting-started/faq#is-there-a-bug-bounty) Is there a bug bounty? Yes. Fira maintains a live bug bounty program through Sherlock with rewards up to $500K for critical vulnerabilities. See [Bug Bounty](https://docs.fira.money/security-and-risk/bug-bounty) . ### [hashtag](https://docs.fira.money/getting-started/faq#where-can-i-verify-the-smart-contracts) Where can I verify the smart contracts? All deployed contracts are verified on Etherscan. Addresses are listed on the [Contracts & Addresses](https://docs.fira.money/resources/contracts-addresses) page. [hashtag](https://docs.fira.money/getting-started/faq#support) Support --------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/getting-started/faq#where-can-i-get-help) Where can I get help? * **Documentation**: This GitBook covers all protocol mechanics, features, and risk information. Further, for a full explanation of all mechanics, see the [Whitepaper](https://docs.fira.money/resources/whitepaper) . * **Email**: [\[email protected\]](https://docs.fira.money/cdn-cgi/l/email-protection) for direct support * **Security issues**: Report through the [Sherlock Bug Bounty](https://docs.fira.money/security-and-risk/bug-bounty) platform [PreviousHow It Workschevron-left](https://docs.fira.money/getting-started/how-it-works) [NextMarkets Overviewchevron-right](https://docs.fira.money/guides/overview) Last updated 1 day ago * [General](https://docs.fira.money/getting-started/faq#general) * [What is Fira?](https://docs.fira.money/getting-started/faq#what-is-fira) * [Why does DeFi need fixed rates?](https://docs.fira.money/getting-started/faq#why-does-defi-need-fixed-rates) * [Who built Fira?](https://docs.fira.money/getting-started/faq#who-built-fira) * [How does Fira work?](https://docs.fira.money/getting-started/faq#how-does-fira-work) * [Which blockchain is Fira deployed on?](https://docs.fira.money/getting-started/faq#which-blockchain-is-fira-deployed-on) * [Features](https://docs.fira.money/getting-started/faq#features) * [How does fixed-rate borrowing work?](https://docs.fira.money/getting-started/faq#how-does-fixed-rate-borrowing-work) * [Can I lend at a fixed rate?](https://docs.fira.money/getting-started/faq#can-i-lend-at-a-fixed-rate) * [Does Fira offer variable-rate markets?](https://docs.fira.money/getting-started/faq#does-fira-offer-variable-rate-markets) * [Security](https://docs.fira.money/getting-started/faq#security) * [Is Fira audited?](https://docs.fira.money/getting-started/faq#is-fira-audited) * [Is there a bug bounty?](https://docs.fira.money/getting-started/faq#is-there-a-bug-bounty) * [Where can I verify the smart contracts?](https://docs.fira.money/getting-started/faq#where-can-i-verify-the-smart-contracts) * [Support](https://docs.fira.money/getting-started/faq#support) * [Where can I get help?](https://docs.fira.money/getting-started/faq#where-can-i-get-help) --- # Fixed-Rate Markets | Fira Docs Fixed-rate markets are the core innovation in Fira. Borrowers lock a rate at origination. Lenders earn predictable yield. Both sides know their terms before executing. The mechanism is built on zero-coupon bond mechanics: Bond Tokens (BTs) trade at a discount before maturity and converge to par at term. The discount is the rate. [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#how-fixed-rate-borrowing-works) How Fixed-Rate Borrowing Works --------------------------------------------------------------------------------------------------------------------------------- 1. **Post collateral** — The borrower deposits an approved collateral asset. 2. **Mint BTs** — The protocol creates Bond Tokens backed by that collateral. Each BT has a face value of 1 unit of the loan token. 3. **Swap BT for loan token** — The borrower swaps BTs for FiraWrapped tokens (FW) through the AMM, then unwraps FW into the underlying asset (e.g., USDC). 4. **Repay at maturity** — The borrower returns the same number of BTs borrowed, regardless of how much they received at origination. The interest cost is not charged explicitly. It is embedded in the discount at which BTs trade. A borrower who receives 0.95 USDC per BT and repays 1.00 USDC per BT at maturity has paid a fixed rate proportional to that 5% spread over the holding period. ### [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#fixed-rate-guarantee) Fixed-Rate Guarantee This mechanism delivers a fixed-rate loan **when held to maturity**. Both the repayment amount and the maturity date are set at origination. Early repayment is always possible but does not guarantee the same effective rate — the BT/USDC exchange rate fluctuates before maturity, so closing early may result in a higher or lower realized cost. [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#how-fixed-rate-lending-works) How Fixed-Rate Lending Works ----------------------------------------------------------------------------------------------------------------------------- Lenders provide the other side of the AMM. By supplying FiraWrapped tokens (FW) to the liquidity pool, they enable borrowers to swap BTs for loan tokens. When FW enters the pool, it is decomposed into its two components: 1FW\=μs(t)BT+μs(t)CT1 \\hspace{0.1cm} \\text{FW} = \\mu\_{s}(t) \\hspace{0.1cm} \\text{BT} + \\mu\_s(t) \\hspace{0.1cm} \\text{CT}1FW\=μs​(t)BT+μs​(t)CT * **BT** remains in the pool to facilitate borrowing * **CT** (Coupon Token) goes to the LP and represents the yield portion Lenders who buy BTs at a discount and hold to maturity earn the difference — a fixed yield locked at purchase. [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#rate-discovery) Rate Discovery ------------------------------------------------------------------------------------------------- Rates are not set by governance. They emerge from supply and demand in the BT/FW AMM. We define a BT/FW exchange rate (exchange rate expressed as BT acquired per 1 FW) as follows: exchangeRate(t)\=μs(t)⋅(ln⁡ ⁣(p(t)1−p(t))rateScalar(t)+rateAnchor(t))\\text{exchangeRate}(t) = \\mu\_s(t)\\cdot\\left( \\frac{\\ln\\!\\left( \\tfrac{p(t)}{1 - p(t)} \\right)}{\\text{rateScalar}(t)} + \\text{rateAnchor}(t) \\right)exchangeRate(t)\=μs​(t)⋅​rateScalar(t)ln(1−p(t)p(t)​)​+rateAnchor(t)​ Where: * μs(t)\\mu\_s (t)μs​(t) is the modified wrapping rate (see [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) ). * p(t)\=nBT(t)/(nBT(t)+nFW(t))p(t) =n\_{\\text{BT}}(t) /(n\_{\\text{BT}}(t) + n\_{\\text{FW}}(t))p(t)\=nBT​(t)/(nBT​(t)+nFW​(t)), such that nBT(t), nFW(t)n\_{BT}(t) , \\space n\_{FW}(t)nBT​(t), nFW​(t) are the number of BT and FW in the pool. * rateScalar(t)\=rootScalar/timeToExpiry(t)rateScalar(t)=rootScalar / timeToExpiry(t)rateScalar(t)\=rootScalar/timeToExpiry(t), such that rootScalarrootScalarrootScalar is a DAO set concentration parameter (and timeToExpiry(t)timeToExpiry(t)timeToExpiry(t) is the time to expiry, in years, for the fixed-rate market at time ttt). * rateAnchor(t)rateAnchor(t)rateAnchor(t) is a DAO set concentration parameter that drifts with the realized implied fixed-rate of the AMM (see [Whitepaper](https://docs.fira.money/resources/whitepaper) ). Using the AMM, borrowers can swap to FW from BT (or vice versa for lenders). Using FW, they can then unwrap to the underlying asset at the wrapping rate: 1FW-USDC\=μ(t)USDC1 \\hspace{0.1cm} \\text{FW-USDC}= \\mu (t)\\hspace{0.1cm} \\text{USDC}1FW-USDC\=μ(t)USDC Therefore the full conversion rate from BT to the underlying asset is: conversionRate(t)\=μ(t)⋅exchangeRate(t)−1\=μ(t)μs(t)(ln⁡ ⁣(p(t)1−p(t))rateScalar(t)+rateAnchor(t))conversionRate(t)=\\mu(t)\\cdot exchangeRate(t)^{-1}=\\frac{\\mu(t)}{\\mu\_s(t)}\\left(\\frac{\\ln\\!\\left( \\tfrac{p(t)}{1 - p(t)} \\right)}{\\text{rateScalar}(t)} + \\text{rateAnchor}(t)\\right)conversionRate(t)\=μ(t)⋅exchangeRate(t)−1\=μs​(t)μ(t)​​rateScalar(t)ln(1−p(t)p(t)​)​+rateAnchor(t)​ Meaning the implied fixed borrowing/lending rate is: impliedRate(t)\=(conversionRate(t)−1−1)1timeToExpiry(t)impliedRate(t)=\\left( conversionRate(t)^{-1} -1 \\right) ^{\\frac{1}{timeToExpiry(t)}}impliedRate(t)\=(conversionRate(t)−1−1)timeToExpiry(t)1​ #### [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#settlement-at-maturity) Settlement at Maturity To simplify loan repayment at maturity, users can mint BT-USDC using USDC (via FW-USDC). Conversely, holders of BT-USDC can redeem their tokens for USDC (also via FW-USDC) after maturity. This creates a robust primary market for loan settlement and avoids potential inefficiencies or liquidity shortages that might arise from relying solely on secondary market pricing through the AMM. However, it should be noted that the wrapping rate is modified after maturity and is fixed based on the last wrapping rate before maturity. Therefore the loan technically accrues some minimal interest while users wait to repay after maturity. This comes from the difference between the actual wrapping rate (from USDC to FW-USDC) and the now fixed modified wrapping rate (from FW-USDC to BT-USDC and CT-USDC). [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#firawrapped-tokens-fw) FiraWrapped Tokens (FW) ----------------------------------------------------------------------------------------------------------------- FW tokens wrap the underlying loan asset (e.g., FW-USDC wraps USDC). The wrapping rate is not constant — it reflects the total reserve value relative to FW supply: μ(t)\=Reserve(t)SupplyFW(t)\\mu (t) = \\frac{Reserve(t)}{Supply\_{FW}(t)}μ(t)\=SupplyFW​(t)Reserve(t)​ At protocol initialization, 1 FW = 1 USDC. Over time, as reserves earn yield through [rehypothecation](https://docs.fira.money/protocol/rehypothecation) , the rate increases. This means FW gradually represents more underlying per token. Borrowers receive FW and unwrap it to USDC. To repay, they rewrap USDC into FW before settlement. [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#coupon-token-ct-trading) Coupon Token (CT) Trading --------------------------------------------------------------------------------------------------------------------- CTs represent the yield component of decomposed FW. They are tradable in the fixed-rate market through flash loan mechanisms: * **Buy CT**: Flash-borrow FW → decompose into BT + CT → swap BT back to FW to repay the loan → keep CT * **Sell CT**: Flash-borrow BT → combine with CT to reconstruct FW → swap portion to BT to repay → keep remaining FW These operations execute atomically. LPs can also sell their CT positions early to realize yield upfront while adding liquidity to the pool. [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#maturity-settlement) Maturity Settlement ----------------------------------------------------------------------------------------------------------- At maturity, BTs redeem 1:1 for the underlying asset (via FW). Holders can: * Redeem BT for USDC through FW * Mint BT using USDC (via FW) to repay loans This primary market settlement avoids dependence on secondary AMM liquidity at maturity. [hashtag](https://docs.fira.money/protocol/fixed-rate-markets#related) Related ----------------------------------------------------------------------------------- * [Floating-Rate Markets](https://docs.fira.money/protocol/floating-rate-markets) — Variable-rate borrowing without maturity * [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) — BT, CT, and FW token reference * [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) — How idle reserves earn yield * [Whitepaper](https://docs.fira.money/resources/whitepaper) — Full mathematical treatment [PreviousToken Mechanicschevron-left](https://docs.fira.money/protocol/token-mechanics) [NextFloating-Rate Marketschevron-right](https://docs.fira.money/protocol/floating-rate-markets) Last updated 1 day ago * [How Fixed-Rate Borrowing Works](https://docs.fira.money/protocol/fixed-rate-markets#how-fixed-rate-borrowing-works) * [Fixed-Rate Guarantee](https://docs.fira.money/protocol/fixed-rate-markets#fixed-rate-guarantee) * [How Fixed-Rate Lending Works](https://docs.fira.money/protocol/fixed-rate-markets#how-fixed-rate-lending-works) * [Rate Discovery](https://docs.fira.money/protocol/fixed-rate-markets#rate-discovery) * [FiraWrapped Tokens (FW)](https://docs.fira.money/protocol/fixed-rate-markets#firawrapped-tokens-fw) * [Coupon Token (CT) Trading](https://docs.fira.money/protocol/fixed-rate-markets#coupon-token-ct-trading) * [Maturity Settlement](https://docs.fira.money/protocol/fixed-rate-markets#maturity-settlement) * [Related](https://docs.fira.money/protocol/fixed-rate-markets#related) --- # LP Guide | Fira Docs [hashtag](https://docs.fira.money/guides/lp-guide#the-lps-structural-role) The LP's Structural Role -------------------------------------------------------------------------------------------------------- On Fira, the liquidity provider is not a traditional lender. The LP provides the capital that makes fixed-rate markets function. Without LPs, there is no pool, no BT/FW exchange, and no market-discovered rates. DeFi lending today holds approximately $64 billion. Global fixed-rate debt exceeds $145 trillion. The structural gap is not yield — it is time. Fira introduces maturity-based markets where rates are discovered through supply and demand, not dictated by utilization curves. LPs are the actors who make this rate discovery possible. An LP position on Fira is a dynamic portfolio of FW-USDC (cash equivalent) and BT-USDC (fixed-maturity bonds). The LP earns from three independent yield sources. All LP operations — minting, swapping, redeeming, migrating — carry **zero fees**. [hashtag](https://docs.fira.money/guides/lp-guide#key-parameters) Key Parameters ------------------------------------------------------------------------------------- Parameter Value Base asset USDC Wrapped asset FW-USDC (Fira Wrapped USDC) Market type Fixed-rate AMM (BT-USDC / FW-USDC) V1 maturities May 7, 2026 (to be expanded) Borrower collateral Pendle PTs (PT-USDe, PT-sUSDe) Projected LP yield 6-14% APR Fees charged to LP 0% on all operations Rehypothecation reserve target 90% (bounds: 89.89% min, 91% max) Chain Ethereum Mainnet [hashtag](https://docs.fira.money/guides/lp-guide#how-it-works) How It Works --------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/guides/lp-guide#id-1.-entry) 1\. Entry Deposit USDC into Fira. The protocol mints FW-USDC (Fira Wrapped USDC) at the current exchange rate. Then deposit FW-USDC into a fixed-rate market by selecting a specific maturity. Upon deposit, FW-USDC is decomposed according to the pool's current composition: The LP receives an **LP token** representing their share of the pool. Any CT-USDC minted during this process belongs to the LP and can be managed independently. ### [hashtag](https://docs.fira.money/guides/lp-guide#id-2.-yield-accrual) 2\. Yield Accrual The LP token accrues value over time from three distinct yield sources (detailed below). Yield is realized upon redemption — the LP token appreciates in price as the pool accumulates fees and interest. ### [hashtag](https://docs.fira.money/guides/lp-guide#id-3.-rolling-maturities) 3\. Rolling Maturities If a market matures before the LP's desired exit date, the LP redeems their position and redeposits into a subsequent maturity market. This roll must be completed within 48 hours of the prior market's maturity. Multiple rolls are possible across V1's available maturities. ### [hashtag](https://docs.fira.money/guides/lp-guide#id-4.-exit) 4\. Exit The LP redeems the LP token and receives FW-USDC and BT-USDC proportional to the pool's composition at withdrawal. * **At maturity:** BT-USDC redeems 1:1 for the underlying asset. No slippage. Full value returned. * **Before maturity:** BT-USDC trades at a discount to FW-USDC. Selling BT-USDC on the AMM incurs slippage proportional to time remaining and available liquidity. The LP may alternatively hold BT-USDC until maturity to avoid slippage — BT converges to par as maturity approaches. After collecting FW-USDC, the LP unwraps it to USDC at the current exchange rate. [hashtag](https://docs.fira.money/guides/lp-guide#three-yield-sources) Three Yield Sources ----------------------------------------------------------------------------------------------- LP yield on Fira is a composite of three independent sources. Each has distinct drivers and risk profiles. ### [hashtag](https://docs.fira.money/guides/lp-guide#source-1-swap-fees) Source 1: Swap Fees Every trade in the BT-USDC / FW-USDC AMM generates fees collected by LPs. Swap fee revenue is a direct function of trading volume in the pool — borrower entries, lender purchases, arbitrage activity, and rollovers all contribute. **Driver:** Trade volume. ### [hashtag](https://docs.fira.money/guides/lp-guide#source-2-net-lending-interest) Source 2: Net Lending Interest When borrowers mint and swap BT-USDC in the AMM, the LP's pool composition shifts toward holding more BT-USDC. At maturity, each BT-USDC redeems 1:1 for the underlying asset. The difference between the discounted acquisition price in the pool and the par redemption value is the net lending interest earned. **Driver:** The implied fixed rate of the pool. Higher rates produce larger BT discounts, which translate to higher lending interest at settlement. ### [hashtag](https://docs.fira.money/guides/lp-guide#source-3-rehypothecation-yield) Source 3: Rehypothecation Yield Fira deploys a portion of FW-USDC reserves into variable-rate vaults (SisuVault). These vaults lend USDC against crypto collateral (WBTC, WETH) on Fira's floating-rate markets. The interest earned accrues to CT-USDC holders and flows through to the FW-USDC exchange rate. For the reserve allocation model and rebalancing mechanics, see [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) . **Driver:** Variable-rate borrowing demand and utilization in the rehypothecation vaults. **Reserve allocation:** The protocol maintains a 90% target reserve ratio, with bounds at 89.89% (min) and 91% (max). When the ratio drifts outside these bounds, the protocol rebalances automatically. Only approximately 10% of reserves are rehypothecated at any time. ### [hashtag](https://docs.fira.money/guides/lp-guide#yield-summary) Yield Summary Component Driver Swap fees + Net lending interest Trading volume and implied fixed rate in the AMM Rehypothecation yield Variable-rate borrowing demand in rehypothecation vaults **Projected combined yield: 6-14% APR** (LP yield + deal rewards for early participants during bootstrapping phase). [hashtag](https://docs.fira.money/guides/lp-guide#token-mechanics) Token Mechanics --------------------------------------------------------------------------------------- Fira's fixed-rate markets operate with four token types. The fundamental invariant: 1FW\=μs(t)BT+μs(t)CT1 \\hspace{0.1cm} \\text{FW} = \\mu\_{s}(t) \\hspace{0.1cm} \\text{BT} + \\mu\_s(t) \\hspace{0.1cm} \\text{CT}1FW\=μs​(t)BT+μs​(t)CT Token Role Behavior **FW-USDC** Wrapped USDC (cash equivalent) Mintable and redeemable for USDC at any time. Exchange rate appreciates over time as rehypothecation generates yield. ERC-20 / ERC-4626 compliant. **BT-USDC** Zero-coupon bond (principal) Trades at a discount to FW-USDC before maturity. Redeems 1:1 at expiry with the underlying. The discount reflects the implied fixed rate. **CT-USDC** Yield token (interest) Accrues rehypothecation yield from FW-USDC reserves. Tradable before maturity. **LP Token** Pool share Represents the LP's proportional claim on the AMM pool (mix of BT-USDC and FW-USDC). Accrues swap fees and lending interest. For detailed token design, wrapping rate mechanics, and decomposition/reconstruction formulas, see [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) . ### [hashtag](https://docs.fira.money/guides/lp-guide#ct-optionality-the-lps-strategic-choice) CT Optionality: The LP's Strategic Choice When depositing FW-USDC, the pool decomposes it into BT-USDC and CT-USDC. The CT-USDC is returned to the LP. Two options: **Option A — Hold CT to maturity.** Collect all rehypothecation yield accrued over the period. The yield flows from the variable-rate vault interest, distributed proportionally to CT holders. **Option B — Sell CT immediately.** Monetize the present value of expected future rehypothecation yield upfront. Selling CT returns FW-USDC to the pool, increasing available liquidity. This is economically equivalent to locking in a yield rate today rather than bearing floating-rate exposure. CT is a hybrid instrument: its cash flows depend on floating-rate markets (rehypothecation), but it trades in a fixed-rate market. A pricing equilibrium exists where the market price of CT equals the discounted expected value of its remaining rehypothecation yield. [hashtag](https://docs.fira.money/guides/lp-guide#lp-behavior-under-rate-changes) LP Behavior Under Rate Changes --------------------------------------------------------------------------------------------------------------------- An LP position is not a pure fixed-rate lending position. It is a dynamic portfolio of cash (FW-USDC) and bonds (BT-USDC). As market rates evolve: * **Rates stay low:** Portfolio holds proportionally more FW-USDC (cash) * **Rates increase:** Portfolio shifts toward more BT-USDC at lower prices This rebalancing is economically similar to impermanent loss on Curve: the portfolio adjusts as the market moves. ### [hashtag](https://docs.fira.money/guides/lp-guide#the-critical-difference) The Critical Difference Unlike Curve impermanent loss, **this unrealized loss is only realized if the LP withdraws before maturity.** If the LP holds until maturity, BT-USDC converges to par, offsetting the unrealized loss from rate changes. ### [hashtag](https://docs.fira.money/guides/lp-guide#lp-vs.-lender-rate-spike-comparison) LP vs. Lender: Rate Spike Comparison A fixed-rate lender holding pure BT-USDC has concentrated exposure to interest rate movements. An LP holds a diversified portfolio of cash and bonds, which naturally dampens the impact. **Scenario: entry at 4% implied rate, rate spikes to 10%** Actor Exposure Max drawdown **Lender** (pure BT holder) Full rate exposure ~5x higher than LP **LP** (BT + FW portfolio) Dampened by cash component ~5x lower than lender The LP's diversified composition absorbs rate shocks. The lender's concentrated BT position amplifies them. [hashtag](https://docs.fira.money/guides/lp-guide#zero-operational-fees) Zero Operational Fees --------------------------------------------------------------------------------------------------- Operation Fee FW-USDC minting (USDC wrapping) 0% FW-USDC redemption (USDC unwrapping) 0% LP deposit (FW decomposition) 0% LP withdrawal (FW reconstruction) 0% AMM swaps Swap fee accrues to LPs Rehypothecation 0% All protocol-level operations are fee-free for LPs. Swap fees generated by trading activity accrue entirely to the LP pool. Standard Ethereum gas costs apply. [hashtag](https://docs.fira.money/guides/lp-guide#risk-factors) Risk Factors --------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/guides/lp-guide#id-1.-duration-risk) 1\. Duration Risk Exiting before maturity means the LP redeems the LP token for FW-USDC and BT-USDC proportional to the pool's current composition. Selling BT-USDC for FW-USDC before maturity incurs slippage correlated to time remaining. Longer maturities carry higher duration risk. **Mitigation:** Select maturities aligned with the investment horizon. Hold to maturity to eliminate duration risk. BT converges to par as maturity approaches — illiquidity does not imply loss. ### [hashtag](https://docs.fira.money/guides/lp-guide#id-2.-bad-debt-risk) 2\. Bad Debt Risk LPs can incur bad debt from two sources: * **Fixed-rate borrowers:** If collateral liquidation does not cover outstanding loans (extreme price decline, insufficient liquidation incentive), LPs absorb the shortfall. Bad debt reduces the FW-USDC/USDC exchange rate. * **Rehypothecated reserves:** Variable-rate vault borrowers (WBTC/USDC, WETH/USDC) may also generate bad debt, similarly reducing the FW-USDC exchange rate. **Mitigation:** All borrowing is overcollateralized. LLTV is set at conservative levels for variable-rate markets. Liquidation incentives (LIF up to 1.15x) compensate liquidators. Variable-rate vault caps ($5M per market) limit rehypothecation exposure. However, extreme market conditions can bypass these protections. For details, see [Bad Debt Risk](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) . ### [hashtag](https://docs.fira.money/guides/lp-guide#id-3.-liquidity-risk) 3\. Liquidity Risk Reserve rehypothecation means not all USDC backing FW-USDC is liquid at all times. If a large withdrawal coincides with high vault utilization, the LP may face temporary withdrawal restrictions until the rehypothecation module rebalances. **Mitigation:** Reserve ratio maintained at 90% target with automatic rebalancing. Only approximately 10% of reserves are rehypothecated. Variable-rate vault caps ($5M each) limit total exposure. See [Liquidity Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk) . ### [hashtag](https://docs.fira.money/guides/lp-guide#id-4.-smart-contract-risk) 4\. Smart Contract Risk Fira is a newly deployed protocol. Smart contract risk includes coding errors, bugs, and potential exploits that could lead to partial or total loss of deposited funds. **Mitigation:** Six independent external audits (Sherlock ×2, Spearbit/Cantina, yAudit ×2, Hexens), an extended internal review, and a bug bounty program up to $500K. Contracts deployed with transparent proxies on Ethereum Mainnet. These measures reduce but do not eliminate smart contract risk. For details, see [Audits](https://docs.fira.money/security-and-risk/audits) . ### [hashtag](https://docs.fira.money/guides/lp-guide#id-5.-rehypothecation-risk) 5\. Rehypothecation Risk A portion of FW-USDC reserves is lent through variable-rate vaults. The yield from this activity accrues to CT holders, but the underlying loans carry their own risk profile. If variable-rate borrowers default and liquidation proceeds are insufficient, the resulting bad debt reduces the FW-USDC exchange rate for all holders. **Mitigation:** Conservative reserve parameters (90% target ratio). Vault caps of $5M per market. DAO governance over all rehypothecation parameters. See [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) . [hashtag](https://docs.fira.money/guides/lp-guide#related) Related ----------------------------------------------------------------------- * [Fixed-Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) — AMM mechanics and pricing * [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) — BT, CT, FW, and LP token design * [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) — Reserve allocation model * [Curation Vaults](https://docs.fira.money/protocol/curation-vaults) — Curated vault architecture * [Liquidations](https://docs.fira.money/protocol/liquidations) — Position health and liquidation mechanics * [Contracts & Addresses](https://docs.fira.money/resources/contracts-addresses) — Deployed contract addresses * [UZR Simulatorarrow-up-right](https://simulator.fira.money/) — Stress-test market parameters _This document is for informational purposes only and does not constitute financial advice. Projected yields are estimates based on modeling assumptions and are not assured. DeFi participation carries risk of partial or total loss of funds. All parameters are subject to governance approval._ [PreviousLender Guidechevron-left](https://docs.fira.money/guides/lender-guide) [NextArchitecture Overviewchevron-right](https://docs.fira.money/protocol/architecture-overview) Last updated 1 day ago * [The LP's Structural Role](https://docs.fira.money/guides/lp-guide#the-lps-structural-role) * [Key Parameters](https://docs.fira.money/guides/lp-guide#key-parameters) * [How It Works](https://docs.fira.money/guides/lp-guide#how-it-works) * [1\. Entry](https://docs.fira.money/guides/lp-guide#id-1.-entry) * [2\. Yield Accrual](https://docs.fira.money/guides/lp-guide#id-2.-yield-accrual) * [3\. Rolling Maturities](https://docs.fira.money/guides/lp-guide#id-3.-rolling-maturities) * [4\. Exit](https://docs.fira.money/guides/lp-guide#id-4.-exit) * [Three Yield Sources](https://docs.fira.money/guides/lp-guide#three-yield-sources) * [Source 1: Swap Fees](https://docs.fira.money/guides/lp-guide#source-1-swap-fees) * [Source 2: Net Lending Interest](https://docs.fira.money/guides/lp-guide#source-2-net-lending-interest) * [Source 3: Rehypothecation Yield](https://docs.fira.money/guides/lp-guide#source-3-rehypothecation-yield) * [Yield Summary](https://docs.fira.money/guides/lp-guide#yield-summary) * [Token Mechanics](https://docs.fira.money/guides/lp-guide#token-mechanics) * [CT Optionality: The LP's Strategic Choice](https://docs.fira.money/guides/lp-guide#ct-optionality-the-lps-strategic-choice) * [LP Behavior Under Rate Changes](https://docs.fira.money/guides/lp-guide#lp-behavior-under-rate-changes) * [The Critical Difference](https://docs.fira.money/guides/lp-guide#the-critical-difference) * [LP vs. Lender: Rate Spike Comparison](https://docs.fira.money/guides/lp-guide#lp-vs.-lender-rate-spike-comparison) * [Zero Operational Fees](https://docs.fira.money/guides/lp-guide#zero-operational-fees) * [Risk Factors](https://docs.fira.money/guides/lp-guide#risk-factors) * [1\. Duration Risk](https://docs.fira.money/guides/lp-guide#id-1.-duration-risk) * [2\. Bad Debt Risk](https://docs.fira.money/guides/lp-guide#id-2.-bad-debt-risk) * [3\. Liquidity Risk](https://docs.fira.money/guides/lp-guide#id-3.-liquidity-risk) * [4\. Smart Contract Risk](https://docs.fira.money/guides/lp-guide#id-4.-smart-contract-risk) * [5\. Rehypothecation Risk](https://docs.fira.money/guides/lp-guide#id-5.-rehypothecation-risk) * [Related](https://docs.fira.money/guides/lp-guide#related) Copy 1 FW-USDC --> proportional BT-USDC (stays in pool) + CT-USDC (LP receives) --- # Curation Vaults | Fira Docs Curation is how lender capital gets allocated across Fira's floating rate markets. Lenders deposit assets into curated vaults. A designated curator decides where that capital goes — which markets, what allocation, under what constraints. Depositors earn yield passively. Curators earn fees for their oversight. [hashtag](https://docs.fira.money/protocol/curation-vaults#curators) Curators ---------------------------------------------------------------------------------- A curator manages one or more vaults with the objective of optimizing risk-adjusted returns for depositors. The role is strategic, not operational: Responsibility Description **Strategy definition** Establishing the vault's mandate — which assets, markets, and strategies are eligible **Risk framework** Setting exposure caps, concentration limits, and risk constraints **Allocator appointment** Designating who executes portfolio adjustments within the strategy. The curator may also act as allocator. **Vault parameters** Defining fee structures, access controls, and compliance requirements Curator-initiated changes are subject to a **timelock**. Depositors have time to review proposed changes and withdraw if they disagree. [hashtag](https://docs.fira.money/protocol/curation-vaults#how-vaults-work) How Vaults Work ------------------------------------------------------------------------------------------------ 1. **Depositor** provides assets (e.g., USDC) to a curated vault 2. **Curator** defines the allocation strategy across eligible markets 3. **Allocator** executes capital deployment according to the strategy 4. **Yield** accrues from multiple sources — trading fees, fixed-rate spreads, floating-rate interest, rehypothecation 5. **Depositor** can withdraw at any time, subject to available liquidity The vault issues shares representing the depositor's proportional claim on the total assets under management. [hashtag](https://docs.fira.money/protocol/curation-vaults#related) Related -------------------------------------------------------------------------------- * [Floating-Rate Markets](https://docs.fira.money/protocol/floating-rate-markets) — Variable-rate lending * [Whitepaper](https://docs.fira.money/resources/whitepaper) — Complete description [PreviousLiquidationschevron-left](https://docs.fira.money/protocol/liquidations) [NextSecurity Overviewchevron-right](https://docs.fira.money/security-and-risk/security-overview) Last updated 1 day ago * [Curators](https://docs.fira.money/protocol/curation-vaults#curators) * [How Vaults Work](https://docs.fira.money/protocol/curation-vaults#how-vaults-work) * [Related](https://docs.fira.money/protocol/curation-vaults#related) --- # Liquidation Risk | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#core-risk) Core Risk ------------------------------------------------------------------------------------------------------------- Borrowing on Fira, whether in fixed-maturity or floating-rate markets, requires collateral and carries material liquidation risk. Liquidations can proceed rapidly, automatically, and without notice, potentially resulting in substantial or complete loss of collateral holdings. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#how-liquidations-occur) How Liquidations Occur --------------------------------------------------------------------------------------------------------------------------------------- Positions become vulnerable when a borrower's Loan-to-Value (LTV) ratio exceeds the Liquidation LTV (LLTV) threshold. This triggers eligibility for liquidators to seize collateral in exchange for debt repayment. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#triggers) Triggers * Collateral value declines * Borrowed asset appreciation * Volatility shifts * Pricing disruptions [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#real-world-scenarios) Real-World Scenarios ----------------------------------------------------------------------------------------------------------------------------------- Liquidation materializes quickly in these circumstances: * Sharp market movements * Liquidity constraints * Network congestion * Oracle failures * Cascading liquidations during broader market stress [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#mitigation-strategies-with-caveats) Mitigation Strategies (With Caveats) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Users may employ defensive tactics: * Conservative initial leverage * Active position monitoring * Partial debt repayment * Independent risk assessment These are not guarantees. Interface warnings and any automated features provide indicative guidance only and may fail during stressed conditions. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#key-takeaway) Key Takeaway ------------------------------------------------------------------------------------------------------------------- Liquidation represents an inherent feature of collateralized borrowing. Users should not assume timely intervention opportunities exist during extreme volatility. [PreviousInterest Rate Riskchevron-left](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk) [NextBad Debt Riskchevron-right](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) Last updated 1 day ago * [Core Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#core-risk) * [How Liquidations Occur](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#how-liquidations-occur) * [Triggers](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#triggers) * [Real-World Scenarios](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#real-world-scenarios) * [Mitigation Strategies (With Caveats)](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#mitigation-strategies-with-caveats) * [Key Takeaway](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk#key-takeaway) --- # Rehypothecation | Fira Docs Rehypothecation is Fira's mechanism for making idle reserves productive. A portion of FW-USDC held in fixed-rate market pools is allocated to a variable-rate vault, where it earns floating yield. That yield flows to Coupon Token (CT) holders. This creates the bridge between Fira's fixed-rate and floating-rate layers: LPs provide liquidity to the fixed-rate AMM, and the unused portion earns floating-rate yield in the background. [hashtag](https://docs.fira.money/protocol/rehypothecation#reserve-allocation-model) Reserve Allocation Model ------------------------------------------------------------------------------------------------------------------ The system manages reserves through a **reserve ratio φ** — the fraction of liquid (unrehypothecated) reserves relative to total FW-USDC in the pool: Three parameters control the allocation: Parameter Role φmin\\varphi \_{min}φmin​ Minimum reserve ratio — below this, the system withdraws from the vault φmax\\varphi \_{max}φmax​ Maximum reserve ratio — above this, the system deposits into the vault φtarget\\varphi \_{target}φtarget​ Target ratio — rebalancing restores φ to this value Currently, these are respectively set to 89.89%, 91% and 90%. ### [hashtag](https://docs.fira.money/protocol/rehypothecation#how-rebalancing-works) How Rebalancing Works The reserve ratio is checked on every market swap. If φ falls outside \[φ\_min, φ\_max\]: * φ<φmin\\varphi < \\varphi \_{min}φ<φmin​ — Too much capital is rehypothecated. The system withdraws FW-USDC from the variable-rate vault back to liquid reserves. * φ\>φmax\\varphi > \\varphi \_{max}φ\>φmax​ — Too much capital sits idle. The system deposits excess FW-USDC into the variable-rate vault. In both cases, the system restores φ to φ\_target. [hashtag](https://docs.fira.money/protocol/rehypothecation#how-ct-holders-earn-yield) How CT Holders Earn Yield -------------------------------------------------------------------------------------------------------------------- All interest earned by rehypothecated liquidity is distributed to outstanding Coupon Token (CT) holders. The mechanism: 1. Rehypothecated USDC earns floating yield in the variable-rate vault 2. This yield increases the FW wrapping rate μ(t) — each FW represents more underlying over time 3. CT holders can claim the difference between the current and previous wrapping rates ### [hashtag](https://docs.fira.money/protocol/rehypothecation#claimable-yield) Claimable Yield CTclaim(t)\=(1−μs(t∗)μs(t))×BalanceCT(t)μs(t∗)\\text{CT}\_{\\text{claim}}(t) = \\left(1 - \\frac{\\mu\_s(t^\*)}{\\mu\_s(t)}\\right) \\times \\frac{\\text{Balance}\_{\\text{CT}}(t)}{\\mu\_s (t\*)}CTclaim​(t)\=(1−μs​(t)μs​(t∗)​)×μs​(t∗)BalanceCT​(t)​ Where μs(t)\\mu \_s(t)μs​(t) is the modified wrapping rate (see [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) ) at the last update and μ(t) is the current rate. The yield is distributed proportionally to CT balances, paid in FW-USDC. After maturity, CT no longer accrues rehypothecation yield — only active markets generate returns. [hashtag](https://docs.fira.money/protocol/rehypothecation#ct-price-dynamics) CT Price Dynamics ---------------------------------------------------------------------------------------------------- CT is a hybrid instrument: its cash flows come from a floating-rate source, but it trades in the fixed-rate market. Regardless, a natural price equilibrium can be achieved: * **CT overpriced** relative to expected future yield → holders sell → FW supply increases in pool → more capital for rehypothecation → higher future yields for remaining CT → price adjusts down * **CT underpriced** → buyers enter → FW supply decreases → less rehypothecation → lower future yields → price adjusts up In equilibrium, the CT market price equals the discounted expected value of remaining rehypothecation yield. [hashtag](https://docs.fira.money/protocol/rehypothecation#governance) Governance -------------------------------------------------------------------------------------- All rehypothecation parameters (φ\_min, φ\_max, φ\_target) are set by the DAO. Key principles: * **Liquidity first** — The DAO prioritizes redemption availability over yield maximization * **Conservative by design** — Parameters are chosen through stress testing to ensure sufficient liquidity under adverse conditions * **Manual updates** — Parameters are not automated; updates happen no more than monthly or quarterly * **Future delegation** — The DAO may delegate parameter management to a curator [hashtag](https://docs.fira.money/protocol/rehypothecation#related) Related -------------------------------------------------------------------------------- * [Fixed-Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) — Where rehypothecated reserves originate * [Floating-Rate Markets](https://docs.fira.money/protocol/floating-rate-markets) — Where rehypothecated capital earns yield * [Token Mechanics](https://docs.fira.money/protocol/token-mechanics) — CT token properties and behavior * [Whitepaper](https://docs.fira.money/resources/whitepaper) — Full mathematical treatment [PreviousFloating-Rate Marketschevron-left](https://docs.fira.money/protocol/floating-rate-markets) [NextLiquidationschevron-right](https://docs.fira.money/protocol/liquidations) Last updated 1 day ago * [Reserve Allocation Model](https://docs.fira.money/protocol/rehypothecation#reserve-allocation-model) * [How Rebalancing Works](https://docs.fira.money/protocol/rehypothecation#how-rebalancing-works) * [How CT Holders Earn Yield](https://docs.fira.money/protocol/rehypothecation#how-ct-holders-earn-yield) * [Claimable Yield](https://docs.fira.money/protocol/rehypothecation#claimable-yield) * [CT Price Dynamics](https://docs.fira.money/protocol/rehypothecation#ct-price-dynamics) * [Governance](https://docs.fira.money/protocol/rehypothecation#governance) * [Related](https://docs.fira.money/protocol/rehypothecation#related) --- # Audits | Fira Docs Fira has undergone a comprehensive security review process consisting of six independent external audits and an extended internal review. These audits focused on the Fira smart contracts and associated lending/borrowing infrastructure deployed on Ethereum mainnet. [hashtag](https://docs.fira.money/security-and-risk/audits#external-audits) External Audits ------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/security-and-risk/audits#id-1.-sherlock-fira-uzr-audit-nov25) 1\. Sherlock — "Fira UZR Audit Nov25" * **Auditor:** Sherlock * **Audit Name:** Fira UZR Audit Nov25 * **Date:** November 2025 * **Scope:** Fira UZR module smart contracts * **Status:** Done * **Description:** Sherlock conducted a competitive audit of the Fira UZR contracts, leveraging their community of independent security researchers to identify vulnerabilities across the codebase. The audit covered the core lending vault, oracle adapters, interest rate models, and supporting infrastructure contracts. file-pdf 992KB [Sherlock - Fira UZR Audit Nov25.pdf](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-0e54b2fd3302e5b39a812d04da8f38df2743ac0b%2FSherlock%20-%20Fira%20UZR%20Audit%20Nov25.pdf?alt=media) PDF downloadDownload[arrow-up-right-from-squareOpen](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-0e54b2fd3302e5b39a812d04da8f38df2743ac0b%2FSherlock%20-%20Fira%20UZR%20Audit%20Nov25.pdf?alt=media) * * * ### [hashtag](https://docs.fira.money/security-and-risk/audits#id-2.-spearbit-cantina-cantina-code-fira-uzr-audit-nov25) 2\. Spearbit / Cantina — "Cantina code - Fira UZR Audit Nov25" * **Auditor:** Spearbit (via Cantina platform) * **Audit Name:** Cantina code - Fira UZR Audit Nov25 * **Date:** November 2025 * **Scope:** Fira UZR module smart contracts * **Status:** Done * **Description:** Spearbit conducted a focused security review through the Cantina platform. The audit examined the Fira UZR codebase for logic errors, access control issues, economic attack vectors, and integration risks. file-pdf 519KB [Cantinacode - Fira UZR Audit Nov25.pdf](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-2e55243e2c80f4574b96f599d6f58ea327cb2aa8%2FCantinacode%20-%20Fira%20UZR%20Audit%20Nov25.pdf?alt=media) PDF downloadDownload[arrow-up-right-from-squareOpen](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-2e55243e2c80f4574b96f599d6f58ea327cb2aa8%2FCantinacode%20-%20Fira%20UZR%20Audit%20Nov25.pdf?alt=media) * * * ### [hashtag](https://docs.fira.money/security-and-risk/audits#id-3.-yaudit-fira-uzr-audit-dec-25) 3\. yAudit — "Fira UZR Audit Dec 25" * **Auditor:** yAudit * **Audit Name:** Fira UZR Audit Dec 25 * **Date:** December 2025 * **Scope:** Fira UZR module smart contracts * **Status:** Done * **Description:** yAudit performed an independent security assessment of the Fira UZR contracts. This audit provided a third perspective on the codebase, focusing on edge cases, mathematical precision, and potential exploit paths that may not have been covered by the earlier reviews. file-pdf 3MB [yAudit - Fira UZR Audit Dec 25.pdf](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-49aa88712501071eb47f480f9b7812073e1e54e2%2FyAudit%20-%20Fira%20UZR%20Audit%20Dec%2025.pdf?alt=media) PDF downloadDownload[arrow-up-right-from-squareOpen](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-49aa88712501071eb47f480f9b7812073e1e54e2%2FyAudit%20-%20Fira%20UZR%20Audit%20Dec%2025.pdf?alt=media) * * * ### [hashtag](https://docs.fira.money/security-and-risk/audits#id-4.-sherlock-fira-v1-audit-feb26) 4\. Sherlock — "Fira V1 Audit Feb26" * **Auditor:** Sherlock * **Audit Name:** Fira V1 Audit Feb26 * **Date:** February 2026 * **Scope:** Fira V1 full protocol (fixed-rate markets, variable-rate lending, AMM, router, tokens, rehypothecation, oracles) * **Status:** Done * **Description:** Sherlock conducted a comprehensive competitive audit of the full Fira V1 protocol, covering the complete system including FiraLendingMarket, VariableLendingMarket, FiraMarket AMM, FiraRouterV4, token layer (BT/CT/FW), RehypothecationModule, oracle pipeline, and LiquidityInjector. * * * ### [hashtag](https://docs.fira.money/security-and-risk/audits#id-5.-hexens-fira-v1-audit-feb26) 5\. Hexens — "Fira V1 Audit Feb26" * **Auditor:** Hexens * **Audit Name:** Fira V1 Audit Feb26 * **Date:** February 2026 * **Scope:** Fira V1 full protocol * **Status:** Done * **Description:** Hexens performed an independent security audit of the Fira V1 smart contracts, providing deep analysis of the protocol's fixed-rate and variable-rate lending infrastructure, curation vaults, and associated components. file-pdf 7MB [Hexens - Fira V1 Audit Feb26.pdf](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-6d09a49e52e729cafea883d9f8ea0b8c0536b0dc%2Fhexens-fira-feb-26.pdf?alt=media) PDF downloadDownload[arrow-up-right-from-squareOpen](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-6d09a49e52e729cafea883d9f8ea0b8c0536b0dc%2Fhexens-fira-feb-26.pdf?alt=media) * * * ### [hashtag](https://docs.fira.money/security-and-risk/audits#id-6.-yaudit-fira-v1-audit-mar26) 6\. yAudit — "Fira V1 Audit Mar26" * **Auditor:** yAudit * **Audit Name:** Fira V1 Audit Mar26 * **Date:** March 2026 * **Scope:** Fira V1 full protocol * **Status:** Done * **Description:** yAudit performed a follow-up independent assessment of the complete Fira V1 protocol, building on their earlier UZR-focused review to cover the expanded system including variable-rate markets, curation vaults, and the full oracle pipeline. * * * [hashtag](https://docs.fira.money/security-and-risk/audits#internal-review) Internal Review ------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/security-and-risk/audits#steady-labs-internal-review) Steady Labs Internal Review * **Reviewer:** Steady Labs engineering team * **Duration:** Approximately one month * **Scope:** Full Fira codebase and deployment configuration * **Description:** In addition to the six external audits, the Steady Labs team conducted an extended month-long internal security review. This review covered code quality, deployment procedures, parameter configurations, access control setups, and operational security considerations. The internal review complemented the external audits by providing deep domain-specific knowledge of the protocol's intended behavior and design assumptions. * * * [hashtag](https://docs.fira.money/security-and-risk/audits#summary) Summary -------------------------------------------------------------------------------- Audit Auditor Date Type Fira UZR Audit Nov25 Sherlock November 2025 External (competitive) Cantina code - Fira UZR Audit Nov25 Spearbit / Cantina November 2025 External (focused review) Fira UZR Audit Dec 25 yAudit December 2025 External (independent) Fira V1 Audit Feb26 Sherlock February 2026 External (competitive) Fira V1 Audit Feb26 Hexens February 2026 External (independent) Fira V1 Audit Mar26 yAudit March 2026 External (independent) Internal Review Steady Labs Nov 2025 – Mar 2026 Internal All audit reports and findings have informed the final deployed versions of the Fira contracts on Ethereum mainnet. The combination of six independent external audits plus an extended internal review represents a thorough security review process for the protocol's smart contract infrastructure. [PreviousSecurity Overviewchevron-left](https://docs.fira.money/security-and-risk/security-overview) [NextBug Bountychevron-right](https://docs.fira.money/security-and-risk/bug-bounty) Last updated 1 day ago * [External Audits](https://docs.fira.money/security-and-risk/audits#external-audits) * [1\. Sherlock — "Fira UZR Audit Nov25"](https://docs.fira.money/security-and-risk/audits#id-1.-sherlock-fira-uzr-audit-nov25) * [2\. Spearbit / Cantina — "Cantina code - Fira UZR Audit Nov25"](https://docs.fira.money/security-and-risk/audits#id-2.-spearbit-cantina-cantina-code-fira-uzr-audit-nov25) * [3\. yAudit — "Fira UZR Audit Dec 25"](https://docs.fira.money/security-and-risk/audits#id-3.-yaudit-fira-uzr-audit-dec-25) * [4\. Sherlock — "Fira V1 Audit Feb26"](https://docs.fira.money/security-and-risk/audits#id-4.-sherlock-fira-v1-audit-feb26) * [5\. Hexens — "Fira V1 Audit Feb26"](https://docs.fira.money/security-and-risk/audits#id-5.-hexens-fira-v1-audit-feb26) * [6\. yAudit — "Fira V1 Audit Mar26"](https://docs.fira.money/security-and-risk/audits#id-6.-yaudit-fira-v1-audit-mar26) * [Internal Review](https://docs.fira.money/security-and-risk/audits#internal-review) * [Steady Labs Internal Review](https://docs.fira.money/security-and-risk/audits#steady-labs-internal-review) * [Summary](https://docs.fira.money/security-and-risk/audits#summary) --- # Liquidations | Fira Docs Liquidation is the enforcement mechanism that keeps Fira's lending markets solvent. When a borrower's collateral value drops below the required threshold relative to their debt, the position becomes eligible for liquidation. Third-party liquidators repay the debt and receive the borrower's collateral at a bonus. [hashtag](https://docs.fira.money/protocol/liquidations#when-liquidation-happens) When Liquidation Happens --------------------------------------------------------------------------------------------------------------- Every borrowing position has two key ratios: * **LTV (Loan-to-Value)** — Current debt divided by collateral value * **LLTV (Liquidation LTV)** — The threshold set by the market. If LTV exceeds LLTV, the position is liquidatable. ### [hashtag](https://docs.fira.money/protocol/liquidations#health-factor) Health Factor H\=LLTVLTVH=\\frac{LLTV}{LTV}H\=LTVLLTV​ * **Health factor >= 1** — Position is healthy * **Health factor < 1** — Position is liquidatable A position's health changes when collateral value moves (via oracle price updates) or when debt grows (via interest accrual). [hashtag](https://docs.fira.money/protocol/liquidations#oracles) Oracles ----------------------------------------------------------------------------- Each market is configured with an oracle that prices collateral relative to the debt asset. Fira supports three oracle types: Oracle Type Description Example **Price Feed** External price feeds (Chainlink, Redstone) ETH/USDC, BTC/USDC **Exchange Rate** Deterministic rates for wrapped or rebasing tokens stETH/ETH **Fixed Price** Constant price — no fluctuation USD0/bUSD0 (1:1) ### [hashtag](https://docs.fira.money/protocol/liquidations#bond-token-oracle) Bond Token Oracle In fixed-rate markets, Bond Tokens (BTs) are priced at face value for liquidation purposes. A Fixed-Price Oracle values 1 BT-USDC = 1 USDC, regardless of the current market discount. This means collateral is always valued in units of the underlying debt asset. [hashtag](https://docs.fira.money/protocol/liquidations#liquidation-incentive-factor-lif) Liquidation Incentive Factor (LIF) --------------------------------------------------------------------------------------------------------------------------------- Liquidators receive a bonus on the collateral they seize, calculated by the LIF formula: LIF\=min⁡ ⁣(LIFmax⁡,  1δ⋅LLTV+(1−δ))\\text{LIF} = \\min\\!\\left(\\text{LIF}\_{\\max},\\; \\frac{1}{\\delta \\cdot \\text{LLTV} + (1 - \\delta)}\\right)LIF\=min(LIFmax​,δ⋅LLTV+(1−δ)1​) Parameter Current Value Description LIFmaxLIF\_{max}LIFmax​ 1.15 Maximum bonus (15% cap) δ\\deltaδ 0.3 Sensitivity to LLTV Higher LLTV markets produce lower LIF — the bonus is calibrated to the risk of each market. ### [hashtag](https://docs.fira.money/protocol/liquidations#collateral-seized) Collateral Seized Collateralseized\=min(Collateral,LIF×DebtrepaidPriceOracle)Collateral\_{seized}=min\\left(Collateral,LIF\\times\\frac{Debt\_{repaid}}{Price\_{Oracle}}\\right)Collateralseized​\=min(Collateral,LIF×PriceOracle​Debtrepaid​​) The liquidator repays part or all of the debt and receives collateral worth the repaid amount multiplied by the LIF. Any remaining collateral is returned to the borrower. [hashtag](https://docs.fira.money/protocol/liquidations#bad-debt) Bad Debt ------------------------------------------------------------------------------- Bad debt occurs when seized collateral is worth less than the outstanding debt after accounting for execution costs (slippage, fees, price impact). The shortfall is socialized among lenders. ### [hashtag](https://docs.fira.money/protocol/liquidations#fixed-rate-markets) Fixed-Rate Markets Bad debt reduces the FW wrapping rate μ(t). The modified wrapping rate μ\_s(t) used for BT/CT decomposition remains at the pre-loss level, socializing the loss across LPs and token holders. ### [hashtag](https://docs.fira.money/protocol/liquidations#floating-rate-markets) Floating-Rate Markets Bad debt reduces the vault share price. Since the "owed" portion decreases by more than "unutilized" increases, existing lenders absorb the loss proportionally through reduced share value. [hashtag](https://docs.fira.money/protocol/liquidations#forced-liquidation-at-maturity) Forced Liquidation at Maturity --------------------------------------------------------------------------------------------------------------------------- Fira supports **forced liquidation at maturity for fixed rate markets**, triggerable by the DAO even if a position is otherwise healthy. This is by design: when collateral reaches its maturity date, all remaining positions can be closed to enable collateral redemption. Such positions are also subject to LIF values determined per market independently of LLTV. Borrowers should close positions before the maturity date. Open positions past maturity may be force-liquidated regardless of their health factor. [hashtag](https://docs.fira.money/protocol/liquidations#related) Related ----------------------------------------------------------------------------- * [Risk Framework](https://docs.fira.money/security-and-risk/risk-framework) — How risk is assessed per market * [Liquidation Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk) — Risks specific to liquidation mechanics * [Bad Debt Risk](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) — Bad debt scenarios and mitigation * [Whitepaper](https://docs.fira.money/resources/whitepaper) — Full mathematical treatment [PreviousRehypothecationchevron-left](https://docs.fira.money/protocol/rehypothecation) [NextCuration Vaultschevron-right](https://docs.fira.money/protocol/curation-vaults) Last updated 1 day ago * [When Liquidation Happens](https://docs.fira.money/protocol/liquidations#when-liquidation-happens) * [Health Factor](https://docs.fira.money/protocol/liquidations#health-factor) * [Oracles](https://docs.fira.money/protocol/liquidations#oracles) * [Bond Token Oracle](https://docs.fira.money/protocol/liquidations#bond-token-oracle) * [Liquidation Incentive Factor (LIF)](https://docs.fira.money/protocol/liquidations#liquidation-incentive-factor-lif) * [Collateral Seized](https://docs.fira.money/protocol/liquidations#collateral-seized) * [Bad Debt](https://docs.fira.money/protocol/liquidations#bad-debt) * [Fixed-Rate Markets](https://docs.fira.money/protocol/liquidations#fixed-rate-markets) * [Floating-Rate Markets](https://docs.fira.money/protocol/liquidations#floating-rate-markets) * [Forced Liquidation at Maturity](https://docs.fira.money/protocol/liquidations#forced-liquidation-at-maturity) * [Related](https://docs.fira.money/protocol/liquidations#related) --- # Interest Rate Risk | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#overview) Overview ------------------------------------------------------------------------------------------------------------- Fira's fixed-maturity and floating-rate markets face exposure to interest rate volatility. This disclosure is not exhaustive and should be read alongside broader risk disclosures. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#fixed-maturity-markets) Fixed-Maturity Markets ----------------------------------------------------------------------------------------------------------------------------------------- The "fixed" rate operates through market-driven pricing of BT (Bond Token) relative to underlying assets. Market conditions — including liquidity, borrowing demand, and risk appetite — can widen or tighten the discount. Users who exit before maturity may experience realized rates that differ significantly from entry rates. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#floating-rate-markets) Floating-Rate Markets --------------------------------------------------------------------------------------------------------------------------------------- Borrowing rates depend directly on utilization (borrowed liquidity divided by supplied liquidity). Supply or demand shocks can cause utilization to spike rapidly, potentially increasing borrowing costs sharply and keeping them elevated until conditions normalize. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#risk-manifestation) Risk Manifestation --------------------------------------------------------------------------------------------------------------------------------- * Early exits from fixed-maturity positions may yield higher or lower realized rates than anticipated * Floating-rate markets can experience rapid and material rate increases when large liquidity withdrawals or borrowing spikes occur [hashtag](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#mitigations-with-limitations) Mitigations (With Limitations) ------------------------------------------------------------------------------------------------------------------------------------------------------- * Fixed-maturity markets employ liquidity concentration around reasonable rate ranges, though slippage and material movements remain possible * Floating-rate markets rely on curator-managed liquidity reserves and parameters, but curators may be unable to respond adequately during stress [hashtag](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#key-warnings) Key Warnings --------------------------------------------------------------------------------------------------------------------- * Users should not assume fixed-maturity rates remain locked before maturity * Anticipate potential rate spikes in floating markets * Displayed rates are indicative and may not reflect actual execution prices [PreviousRisk Frameworkchevron-left](https://docs.fira.money/security-and-risk/risk-framework) [NextLiquidation Riskchevron-right](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk) Last updated 1 day ago * [Overview](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#overview) * [Fixed-Maturity Markets](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#fixed-maturity-markets) * [Floating-Rate Markets](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#floating-rate-markets) * [Risk Manifestation](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#risk-manifestation) * [Mitigations (With Limitations)](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#mitigations-with-limitations) * [Key Warnings](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk#key-warnings) --- # Smart Contract Risk | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#core-risk) Core Risk ---------------------------------------------------------------------------------------------------------------- Fira operates as a blockchain protocol with inherent smart contract vulnerabilities. Code may contain vulnerabilities, bugs, design flaws, or unintended behaviors potentially resulting in complete asset loss. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#risk-sources) Risk Sources ---------------------------------------------------------------------------------------------------------------------- * Implementation errors * Faulty assumptions about external integrations (tokens, oracles, bridges, DEXs) * Market edge cases * Permissioning mechanisms * Governance decisions * Cross-contract interactions On-chain transactions are irreversible, meaning losses may be permanent. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#mitigations) Mitigations -------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#third-party-audits) Third-Party Audits Fira has engaged security firms (Sherlock, Spearbit Cantina, yAudit) for code review. Audits do not guarantee secure or defect-free code — vulnerabilities can persist undetected. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#operational-controls) Operational Controls The system may pause or restrict functions during suspected incidents. Tradeoffs include service disruption, reduced liquidity, and withdrawal delays. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#recovery-attempts) Recovery Attempts Fira may investigate incidents and pursue recovery actions, but any recovery is uncertain and potentially impossible. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#user-acknowledgment) User Acknowledgment ------------------------------------------------------------------------------------------------------------------------------------ Users must recognize that: * Fira represents experimental and adversarial environments * The protocol may malfunction * Assets face total loss risk * No safety guarantees exist absent written commitments [PreviousLiquidity Riskchevron-left](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk) [NextRisk Disclaimerschevron-right](https://docs.fira.money/security-and-risk/risk-disclaimers) Last updated 1 day ago * [Core Risk](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#core-risk) * [Risk Sources](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#risk-sources) * [Mitigations](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#mitigations) * [Third-Party Audits](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#third-party-audits) * [Operational Controls](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#operational-controls) * [Recovery Attempts](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#recovery-attempts) * [User Acknowledgment](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk#user-acknowledgment) --- # Protocol Primer | Fira Docs [hashtag](https://docs.fira.money/developers/fira-protocol-primer#what-is-fira-eli5-version) What is Fira? (ELI5 version) ------------------------------------------------------------------------------------------------------------------------------ Fira is a DeFi protocol that lets you **split yield-bearing assets into separate fixed-rate and floating-rate components**, and then **trade, lend, and provide liquidity** with those components on Ethereum. Think of it this way: if you have a yield-bearing stablecoin (like USDC deposited in a vault), Fira wraps it into a standardized token called **FW** (Fira Wrapped), then lets you split that FW into two pieces: * **Bond Token (BT)** — a fixed-rate principal claim. You know exactly what it's worth at maturity. * **Coupon Token (CT)** — a floating-yield claim. Its value depends on how much yield the underlying asset generates. ### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#why-does-this-matter) Why does this matter? In traditional finance, separating principal from yield is a well-established concept (zero-coupon bonds, interest rate strips). Fira brings this to DeFi, enabling: * **Fixed-rate borrowing** — Borrowers get predictable costs instead of volatile variable rates. * **Yield speculation** — Traders can go long or short on future yield without holding the full underlying asset. * **Capital efficiency** — LPs can provide liquidity in the BT/FW pool while simultaneously earning floating yield via CT. ### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#the-core-elements-of-fira) The core elements of Fira #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#fw-fira-wrapped) **FW (Fira Wrapped)** FW tokens are ERC-20 wrappers around yield-bearing assets. They expose a standardized deposit/redeem interface so the rest of the protocol doesn't need to know the specifics of the underlying vault. The first implementation is **USDCFW**, which wraps USDC through an ERC-4626 vault. **Key features:** * Standardized interface for any yield-bearing asset * Exchange rate increases as yield accrues * Rehypothecation — idle liquidity is deployed to vaults for yield while maintaining enough reserves for redemptions #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#bond-token-bt) **Bond Token (BT)** BT is the fixed-rate side of the yield split. Each BT represents a claim on 1 unit of underlying at maturity. Before maturity, BT trades at a discount — the discount is the implied fixed rate. **Key features:** * Fixed-rate principal claim * Trades at a discount to FW in the AMM * Used as the loan token in fixed-rate lending markets #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#coupon-token-ct) **Coupon Token (CT)** CT is the floating-rate side. Holding CT entitles you to the yield generated by the underlying FW between now and expiry. **Key features:** * Floating yield exposure * Interest accrues automatically and can be claimed at any time * Post-expiry, remaining yield flows to the protocol treasury #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#fira-market-amm) **Fira Market (AMM)** The AMM is a specialized BT/FW pool with time-decaying implied-rate pricing based on a logit curve. As maturity approaches, BT converges toward FW in value. **Key features:** * BT/FW trading pool with LP tokens * TWAP oracle for pricing BT, CT, and LP tokens * Swaps and mints revert after expiry; burns work at any time #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#fixed-rate-lending) **Fixed-Rate Lending** Borrowers post collateral (e.g., Pendle PT tokens) and borrow BT at a fixed rate. The router automatically swaps BT to FW and then to USDC, so borrowers receive stablecoins in a single transaction. #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#variable-rate-lending) **Variable-Rate Lending** A separate lending market (powered by SisuVault, an ERC-4626 vault) allows standard variable-rate borrowing with collateral like wstETH and cbBTC. #### [hashtag](https://docs.fira.money/developers/fira-protocol-primer#router) **Router** The router is the single entry point for all user operations. It uses a diamond-like proxy pattern where each function is delegated to a specialized facet contract. Users never interact with the underlying contracts directly — everything goes through the router. [PreviousTech Hubchevron-left](https://docs.fira.money/developers/developers) [NextFeatureschevron-right](https://docs.fira.money/developers/features) Last updated 1 day ago * [What is Fira? (ELI5 version)](https://docs.fira.money/developers/fira-protocol-primer#what-is-fira-eli5-version) * [Why does this matter?](https://docs.fira.money/developers/fira-protocol-primer#why-does-this-matter) * [The core elements of Fira](https://docs.fira.money/developers/fira-protocol-primer#the-core-elements-of-fira) --- # Risk Framework | Fira Docs Fira risk management is structured around six primary user-facing risk categories plus legal and operational disclaimers. [hashtag](https://docs.fira.money/security-and-risk/risk-framework#risk-categories) Risk Categories -------------------------------------------------------------------------------------------------------- 1. Interest rate risk 2. Liquidation risk 3. Bad debt risk 4. Collateral risk 5. Liquidity risk 6. Smart contract risk [hashtag](https://docs.fira.money/security-and-risk/risk-framework#mitigation-layers) Mitigation Layers ------------------------------------------------------------------------------------------------------------ * Multi-auditor security process * Live bug bounty coverage * Conservative collateral and liquidation parameters * Oracle controls and fallback logic * Governance-based parameter updates * Progressive rollout strategy for new product surfaces [hashtag](https://docs.fira.money/security-and-risk/risk-framework#read-by-category) Read By Category ---------------------------------------------------------------------------------------------------------- * [Interest Rate Risk](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk) * [Liquidation Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk) * [Bad Debt Risk](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) * [Collateral Risk](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk) * [Liquidity Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk) * [Smart Contract Risk](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk) * [Risk Disclaimers](https://docs.fira.money/security-and-risk/risk-disclaimers) [hashtag](https://docs.fira.money/security-and-risk/risk-framework#security-references) Security References ---------------------------------------------------------------------------------------------------------------- * [Security Overview](https://docs.fira.money/security-and-risk/security-overview) * [Audits](https://docs.fira.money/security-and-risk/audits) * [Bug Bounty](https://docs.fira.money/security-and-risk/bug-bounty) [hashtag](https://docs.fira.money/security-and-risk/risk-framework#important) Important -------------------------------------------------------------------------------------------- Risk cannot be eliminated in DeFi systems. This framework helps users assess tradeoffs and failure modes, but does not constitute financial, legal, or tax advice. [PreviousBug Bountychevron-left](https://docs.fira.money/security-and-risk/bug-bounty) [NextInterest Rate Riskchevron-right](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk) Last updated 1 day ago * [Risk Categories](https://docs.fira.money/security-and-risk/risk-framework#risk-categories) * [Mitigation Layers](https://docs.fira.money/security-and-risk/risk-framework#mitigation-layers) * [Read By Category](https://docs.fira.money/security-and-risk/risk-framework#read-by-category) * [Security References](https://docs.fira.money/security-and-risk/risk-framework#security-references) * [Important](https://docs.fira.money/security-and-risk/risk-framework#important) --- # Architecture | Fira Docs [hashtag](https://docs.fira.money/developers/architecture#system-overview) System overview ----------------------------------------------------------------------------------------------- The Fira protocol is organized into a layered architecture where each module has a clear responsibility and well-defined dependencies. Solid arrows = primary dependencies. Dashed purple arrows = support modules. [hashtag](https://docs.fira.money/developers/architecture#module-dependency-graph) Module dependency graph --------------------------------------------------------------------------------------------------------------- The dependency flow is: **Router → Market + YieldContracts → FW → Underlying Vault** * The **Router** holds no state of its own (beyond selector mappings). Each action facet reads market and yield contract state, orchestrates token transfers, and calls into the market or CT contract to execute operations. * The **Market** depends on CT for the BC index (needed for pricing) and on the factory for fee configuration. * **CT** depends on FW for the exchange rate (to compute the BC index) and on BT for mint/burn gating. * **FW** tokens wrap external yield sources (ERC-4626 vaults) and expose a standardized deposit/redeem interface. * The **RehypothecationModule** controls how much of FW's underlying sits idle vs. deployed in the vault. [hashtag](https://docs.fira.money/developers/architecture#cross-cutting-concerns) Cross-cutting concerns ------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/architecture#reentrancy) Reentrancy Every external entry point uses `nonReentrant` from `FiraERC20`. The router relies on the market and CT contracts for reentrancy protection — the router itself has no reentrancy guard because it delegates all state-changing calls to contracts that do. ### [hashtag](https://docs.fira.money/developers/architecture#access-control) Access control Component Owner controls Factory Market fee configuration CT Factory Interest fee configuration, treasury address FW Pausing, rehypothecation module assignment Router Selector-to-facet mappings LiquidityInjector BT injection and withdrawal ### [hashtag](https://docs.fira.money/developers/architecture#upgradability) Upgradability * **Markets and yield contracts** are **not upgradeable** — deployed via factories and immutable once created. * The **Router** is pseudo-upgradeable — the owner can point selectors at new facet addresses, effectively upgrading logic without migrating state. * **FW tokens** use `BoringOwnableUpgradeable` and the `initializer` pattern for proxy-based upgradability. [hashtag](https://docs.fira.money/developers/architecture#related-pages) Related pages ------------------------------------------------------------------------------------------- * [Router Architecture](https://docs.fira.money/developers/architecture/router-architecture) — Diamond proxy pattern details * [Features](https://docs.fira.money/developers/features) — Individual feature descriptions * [Protocol Contracts](https://docs.fira.money/developers/protocol-contracts) — Contract-level documentation [PreviousLiquidity Injectorchevron-left](https://docs.fira.money/developers/features/liquidity-injector) [NextRouter Architecturechevron-right](https://docs.fira.money/developers/architecture/router-architecture) Last updated 1 day ago * [System overview](https://docs.fira.money/developers/architecture#system-overview) * [Module dependency graph](https://docs.fira.money/developers/architecture#module-dependency-graph) * [Cross-cutting concerns](https://docs.fira.money/developers/architecture#cross-cutting-concerns) * [Reentrancy](https://docs.fira.money/developers/architecture#reentrancy) * [Access control](https://docs.fira.money/developers/architecture#access-control) * [Upgradability](https://docs.fira.money/developers/architecture#upgradability) * [Related pages](https://docs.fira.money/developers/architecture#related-pages) --- # Security Overview | Fira Docs Fira treats security as a structural requirement. Before any user funds were accepted, Fira smart contracts underwent six independent external audits, an extended internal security review, and a live bug bounty program was established. Every deployed contract is verified on Etherscan. [hashtag](https://docs.fira.money/security-and-risk/security-overview#audit-coverage) Audit Coverage --------------------------------------------------------------------------------------------------------- Six independent audits were conducted on Fira contracts between November 2025 and March 2026: Audit Auditor Date Type Fira UZR Audit Nov25 Sherlock November 2025 Competitive audit Fira UZR Audit Nov25 Spearbit / Cantina November 2025 Focused security review Fira UZR Audit Dec25 yAudit December 2025 Independent assessment Fira V1 Audit Feb26 Sherlock February 2026 Competitive audit Fira V1 Audit Feb26 Hexens February 2026 Independent audit Fira V1 Audit Mar26 yAudit March 2026 Independent assessment All findings were addressed before deployment. Full reports and methodology details are on the [Audits](https://docs.fira.money/security-and-risk/audits) page. In addition, the Steady Labs engineering team conducted an extended internal security review covering code quality, deployment procedures, parameter configurations, access controls, and operational security. [hashtag](https://docs.fira.money/security-and-risk/security-overview#bug-bounty) Bug Bounty ------------------------------------------------------------------------------------------------- Fira maintains a live bug bounty program through Sherlock with rewards up to **$500K** for critical vulnerabilities. The program covers all deployed Fira V1 contracts on Ethereum mainnet. For the full scope, reward tiers, and submission process, see the [Bug Bounty](https://docs.fira.money/security-and-risk/bug-bounty) page. [hashtag](https://docs.fira.money/security-and-risk/security-overview#smart-contract-architecture) Smart Contract Architecture ----------------------------------------------------------------------------------------------------------------------------------- Fira's system is composed of three core modules: * **Lending Market** — Core lending vault, collateral management, liquidations, interest accrual, and ERC-4626 curation vaults * **Fixed-Rate AMM and Tokenization** — BT/CT/FW token system, fixed-rate price discovery AMM, and rehypothecation module * **Router** — Diamond-style proxy dispatching to modular action contracts for single-transaction user flows Access control is enforced through role-based permissions and multisig governance. For the full architecture, see [Architecture Overview](https://docs.fira.money/protocol/architecture-overview) . [hashtag](https://docs.fira.money/security-and-risk/security-overview#risk-framework) Risk Framework --------------------------------------------------------------------------------------------------------- Fira documents six primary risk categories: 1. [Interest Rate Risk](https://docs.fira.money/security-and-risk/risk-framework/interest-rate-risk) 2. [Liquidation Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk) 3. [Bad Debt Risk](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) 4. [Collateral Risk](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk) 5. [Liquidity Risk](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk) 6. [Smart Contract Risk](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk) For the full risk index, see [Risk Framework](https://docs.fira.money/security-and-risk/risk-framework) . For legal disclaimers, see [Risk Disclaimers](https://docs.fira.money/security-and-risk/risk-disclaimers) . [hashtag](https://docs.fira.money/security-and-risk/security-overview#key-principle) Key Principle ------------------------------------------------------------------------------------------------------- Audits, reviews, and bounties reduce certain risks but do not eliminate them. Fira is experimental software. Users should understand all risk categories before interacting with the protocol. [PreviousCuration Vaultschevron-left](https://docs.fira.money/protocol/curation-vaults) [NextAuditschevron-right](https://docs.fira.money/security-and-risk/audits) Last updated 1 day ago * [Audit Coverage](https://docs.fira.money/security-and-risk/security-overview#audit-coverage) * [Bug Bounty](https://docs.fira.money/security-and-risk/security-overview#bug-bounty) * [Smart Contract Architecture](https://docs.fira.money/security-and-risk/security-overview#smart-contract-architecture) * [Risk Framework](https://docs.fira.money/security-and-risk/security-overview#risk-framework) * [Key Principle](https://docs.fira.money/security-and-risk/security-overview#key-principle) --- # Bad Debt Risk | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#definition) Definition ------------------------------------------------------------------------------------------------------------ Bad debt emerges when a borrower's collateral cannot be liquidated for enough value to fully repay the outstanding debt. The shortfall between liquidation proceeds (minus execution costs) and outstanding obligations becomes the bad debt burden. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#triggers) Triggers -------------------------------------------------------------------------------------------------------- * Swift collateral value declines exceeding liquidation speed * Market depth deterioration causing substantial slippage during asset sales * Liquidations becoming economically unviable due to fees, MEV, or thin liquidity * Network disruptions preventing timely liquidation or inflating transaction costs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#loss-distribution) Loss Distribution -------------------------------------------------------------------------------------------------------------------------- Bad debt typically affects lenders through socialized losses across liquidity providers rather than concentrating on single parties. This reduces total available assets or diminishes realized yields. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#mitigations) Mitigations -------------------------------------------------------------------------------------------------------------- Fira employs liquidation thresholds and exposure caps using conservative, data-informed methodologies based on historical price volatility and execution data. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#limitations) Limitations * Extreme price gaps can bypass protections * Sudden liquidity disappearance * Oracle failures * Smart contract issues [hashtag](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#key-risk) Key Risk -------------------------------------------------------------------------------------------------------- Lenders face credit-like risk comparable to borrower defaults, with losses most likely during stress periods when market volatility peaks and liquidity contracts simultaneously. [PreviousLiquidation Riskchevron-left](https://docs.fira.money/security-and-risk/risk-framework/liquidation-risk) [NextCollateral Riskchevron-right](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk) Last updated 1 day ago * [Definition](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#definition) * [Triggers](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#triggers) * [Loss Distribution](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#loss-distribution) * [Mitigations](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#mitigations) * [Limitations](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#limitations) * [Key Risk](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk#key-risk) --- # Tech Hub | Fira Docs Technical documentation for developers building on or integrating with Fira Protocol — a modular fixed-rate and variable-rate lending infrastructure on Ethereum. [hashtag](https://docs.fira.money/developers/developers#start-here) Start Here ----------------------------------------------------------------------------------- [Protocol Primerchevron-right](https://docs.fira.money/developers/fira-protocol-primer) [hashtag](https://docs.fira.money/developers/developers#explore) Explore ----------------------------------------------------------------------------- [](https://docs.fira.money/developers/features) **Features** Fixed-rate lending, variable-rate lending, BT/CT/FW tokens, AMM, rehypothecation, and liquidity injection [](https://docs.fira.money/developers/architecture) **Architecture** System layers, module dependencies, reentrancy, access control, and upgradability [](https://docs.fira.money/developers/protocol-contracts) **Smart Contracts** Protocol contracts, token contracts, utility contracts, oracles, and math libraries [](https://docs.fira.money/developers/user-flows) **User Flows** Step-by-step transaction flows for borrowing, lending, LPing, and trading [](https://docs.fira.money/developers/deployment) **Deployment** All mainnet addresses, market IDs, oracle pipelines, router facets, and key roles [](https://docs.fira.money/developers/events-and-indexing) **Events & Indexing** On-chain event reference and reward measurement methodology [](https://docs.fira.money/developers/integrations) **Integrations** Interfaces and integration patterns for building on Fira [](https://docs.fira.money/developers/security-and-audits) **Security & Audits** Security design principles, six independent audits, and bug bounty [hashtag](https://docs.fira.money/developers/developers#quick-reference) Quick Reference --------------------------------------------------------------------------------------------- Resource Link **Mainnet Contracts** [Deployment](https://docs.fira.money/developers/deployment) **Source Code** [github.com/usual-dao/firaarrow-up-right](https://github.com/usual-dao/fira) **Lending Market Source** [github.com/usual-dao/fira-lending-marketarrow-up-right](https://github.com/usual-dao/fira-lending-market) **Bug Bounty** [Sherlock Program](https://docs.fira.money/security-and-risk/bug-bounty) **Glossary** [Developer Glossary](https://docs.fira.money/developers/glossary) **Whitepaper** [Fira Whitepaper](https://docs.fira.money/resources/whitepaper) [hashtag](https://docs.fira.money/developers/developers#key-facts) Key Facts --------------------------------------------------------------------------------- Parameter Value Chain Ethereum Mainnet Router `0xFF615E63aAF2d1B1EE4AdFD34a5840747185d8A0` FW-USDC `0x62F5366C9E21A95326C461a098a408e034e017b3` BT Expiry (V1) May 7, 2026 Fixed-Rate Collateral PT-USDe, PT-sUSDe Variable-Rate Collateral wstETH, cbBTC Audits 6 independent external + internal review [PreviousRisk Disclaimerschevron-left](https://docs.fira.money/security-and-risk/risk-disclaimers) [NextProtocol Primerchevron-right](https://docs.fira.money/developers/fira-protocol-primer) Last updated 1 day ago * [Start Here](https://docs.fira.money/developers/developers#start-here) * [Explore](https://docs.fira.money/developers/developers#explore) * [Quick Reference](https://docs.fira.money/developers/developers#quick-reference) * [Key Facts](https://docs.fira.money/developers/developers#key-facts) --- # Token Contracts | Fira Docs * [FW Tokens](https://docs.fira.money/developers/token-contracts/fw-tokens) — FW base contracts and USDCFW implementation * [BondToken](https://docs.fira.money/developers/token-contracts/bond-token) — BT token contract * [CouponToken](https://docs.fira.money/developers/token-contracts/coupon-token) — CT token contract * [FiraERC20](https://docs.fira.money/developers/token-contracts/fira-erc20) — Custom ERC-20 base with reentrancy guard and permit [PreviousLiquidity Injectorchevron-left](https://docs.fira.money/developers/protocol-contracts/liquidity-injector) [NextFiraERC20chevron-right](https://docs.fira.money/developers/token-contracts/fira-erc20) Last updated 1 day ago --- # Fixed-Rate Lending | Fira Docs [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#overview) Overview ------------------------------------------------------------------------------------------------ Fira's fixed-rate lending allows borrowers to post collateral and borrow at a known, fixed rate. The mechanism works by using **Bond Token (BT)** as the loan token in a dedicated lending market. Since BT is redeemable for a known value at maturity, the borrowing cost is determined by the BT discount at the time of borrowing. circle-info The fixed-rate lending market has **no interest rate model** (`IRM = address(0)`). The rate is implicit in the BT discount — the difference between the BT price at borrow time and its face value at maturity is the borrower's fixed cost. [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#how-it-works) How it works -------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#borrowing) Borrowing The router's `supplyAndBorrowSingleToken` function handles the full flow in a single transaction: 1. **Supply collateral** — Collateral tokens (e.g., Pendle PT tokens) are deposited into the lending market 2. **Borrow BT** — BT is borrowed from the lending market (supplied by the LiquidityInjector) 3. **Swap BT → FW** — BT is swapped to FW via the Fira Market AMM 4. **Redeem FW → USDC** — FW is redeemed for the desired output token The borrower receives USDC (or another token) and holds a fixed-rate debt position denominated in BT. ### [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#repaying) Repaying **Pre-expiry:** Input token → FW (mint) → BT (AMM swap) → repay lending market. **Post-expiry:** Input token → FW (mint) → BT+CT (mint via CT contract) → repay with BT. CT is minted but has zero economic value post-expiry. ### [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#collateral-types) Collateral types Fixed-rate markets currently support Pendle Principal Tokens (PT) as collateral: * **PT-USDe** (Ethena USDe, May 7 2026 expiry) * **PT-sUSDe** (Ethena sUSDe, May 7 2026 expiry) ### [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#liquidation) Liquidation Positions that fall below the liquidation LTV (`LLTV`) can be liquidated. The liquidator repays part of the debt and receives collateral plus a liquidation incentive. [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#key-features) Key features -------------------------------------------------------------------------------------------------------- * **Predictable costs** — Fixed rate determined at borrow time * **Single-transaction flow** — Collateral supply, BT borrow, swap, and redemption in one call * **Whitelist-gated supply** — Only the LiquidityInjector can supply BT to fixed-rate markets * **Maturity grace period** — 24-hour grace period after BT expiry before liquidations are enforced [hashtag](https://docs.fira.money/developers/features/fixed-rate-lending#related-pages) Related pages ---------------------------------------------------------------------------------------------------------- * [Borrow at Fixed Rate (User Flow)](https://docs.fira.money/developers/user-flows/borrow-fixed-rate) * [Repay Fixed-Rate Debt (User Flow)](https://docs.fira.money/developers/user-flows/repay-fixed-rate) * [Liquidity Injector](https://docs.fira.money/developers/features/liquidity-injector) * [ActionBorrow](https://docs.fira.money/developers/protocol-contracts/router/action-borrow) [PreviousFeatureschevron-left](https://docs.fira.money/developers/features) [NextVariable-Rate Lendingchevron-right](https://docs.fira.money/developers/features/variable-rate-lending) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/fixed-rate-lending#overview) * [How it works](https://docs.fira.money/developers/features/fixed-rate-lending#how-it-works) * [Borrowing](https://docs.fira.money/developers/features/fixed-rate-lending#borrowing) * [Repaying](https://docs.fira.money/developers/features/fixed-rate-lending#repaying) * [Collateral types](https://docs.fira.money/developers/features/fixed-rate-lending#collateral-types) * [Liquidation](https://docs.fira.money/developers/features/fixed-rate-lending#liquidation) * [Key features](https://docs.fira.money/developers/features/fixed-rate-lending#key-features) * [Related pages](https://docs.fira.money/developers/features/fixed-rate-lending#related-pages) --- # FiraMarket | Fira Docs circle-info **Source:** `src/fira_bonding/core/Market/v3/FiraMarket.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#contract-summary) Contract summary ------------------------------------------------------------------------------------------------------------------------ `FiraMarket` extends `FiraERC20` — the LP token _is_ the market contract itself. It holds BT and FW reserves and tracks internal balances separately from actual token balances to prevent interference from direct transfers. Key state is packed into `MarketStorage` for gas: `totalBt`, `totalFw` (int128), `lastLnImpliedRate` (uint96), and oracle observation indices (uint16 each). [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#functionality) Functionality ------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#mint-add-liquidity) Mint (add liquidity) `mint(receiver, netFwDesired, netBtDesired)` loads state into memory, calls `MarketMathCore.addLiquidity`, and writes back. On first deposit it locks `MINIMUM_LIQUIDITY` (1000 wei of LP) to `address(1)` to prevent the first-depositor rounding attack. Subsequent deposits mint LP proportional to the limiting token. Tokens must be transferred to the market before calling `mint` — the contract does not pull. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#burn-remove-liquidity) Burn (remove liquidity) `burn(receiverFw, receiverBt, netLpToBurn)` burns LP from `address(this)`, computes proportional FW and BT outputs, and transfers them out. LP must be sent to the market before calling. Works both pre- and post-expiry. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#swaps) Swaps * `**swapExactBtForFw**` — Flash-callback pattern: sends FW out first, then verifies BT repayment via callback. * `**swapFwForExactBt**` — Sends BT out first, calls back, checks FW repayment. Both swap functions send the reserve fee portion to the treasury and are gated by `notExpired`. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#oracle) Oracle Every call to `_writeState` writes a new observation to the `OracleLib` ring buffer. `observe(secondsAgos)` returns cumulative `ln(impliedRate)` values for TWAP calculations. `increaseObservationsCardinalityNext` lets anyone pre-allocate observation slots. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#skim) Skim `skim()` sends any excess BT or FW (above internal totals) to the treasury. This prevents direct transfers from affecting pool pricing. [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market#invariants) Invariants ------------------------------------------------------------------------------------------------------------ * Internal `totalBt` and `totalFw` are never affected by direct transfers * Exchange rate is always >= 1.0 (BT trades at a discount to FW) * `address(0)` and `address(this)` never have reward or balance accounting * Swaps and mints revert after expiry; burns work at any time [PreviousCorechevron-left](https://docs.fira.money/developers/protocol-contracts/core) [NextFiraMarketFactorychevron-right](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/core/fira-market#contract-summary) * [Functionality](https://docs.fira.money/developers/protocol-contracts/core/fira-market#functionality) * [Mint (add liquidity)](https://docs.fira.money/developers/protocol-contracts/core/fira-market#mint-add-liquidity) * [Burn (remove liquidity)](https://docs.fira.money/developers/protocol-contracts/core/fira-market#burn-remove-liquidity) * [Swaps](https://docs.fira.money/developers/protocol-contracts/core/fira-market#swaps) * [Oracle](https://docs.fira.money/developers/protocol-contracts/core/fira-market#oracle) * [Skim](https://docs.fira.money/developers/protocol-contracts/core/fira-market#skim) * [Invariants](https://docs.fira.money/developers/protocol-contracts/core/fira-market#invariants) --- # Liquidity Risk | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#definition) Definition ------------------------------------------------------------------------------------------------------------- Liquidity risk is the potential inability to enter, exit, repay, or unwind a position at a reasonable price within expected timeframes due to insufficient market liquidity. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#three-primary-risk-categories) Three Primary Risk Categories --------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#fixed-maturity-borrowing) Fixed-Maturity Borrowing Early loan settlement through AMM swaps may result in unfavorable pricing due to slippage and price impact, or complete inability to execute, potentially forcing holders to wait until maturity. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#floating-rate-lending) Floating-Rate Lending Lenders can withdraw unutilized assets, but redemptions may become dependent on borrowers repaying, creating potential withdrawal delays when utilization is high. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#liquidity-providers) Liquidity Providers Reserve rehypothecation means not all reserves may be liquid at all times, potentially causing temporary withdrawal restrictions. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#risk-scenarios) Risk Scenarios --------------------------------------------------------------------------------------------------------------------- * AMM liquidity depletion during volatility * Rapid withdrawal runs causing utilization spikes * Rehypothecation lockups * Correlated stress events that simultaneously impact multiple risk factors [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#mitigations-with-caveats) Mitigations (With Caveats) ------------------------------------------------------------------------------------------------------------------------------------------- Fira employs liquidity incentives and rate responses, but these are not guarantees and may not work under stress. Alternative settlement pathways exist but become costly or unavailable during stress conditions. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#key-warnings) Key Warnings ----------------------------------------------------------------------------------------------------------------- * Assume liquidity can disappear rapidly * Treat fixed-maturity early exits as risky * Recognize that floating-rate withdrawals lack guaranteed timing * Avoid relying on interface estimates during market stress [PreviousCollateral Riskchevron-left](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk) [NextSmart Contract Riskchevron-right](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk) Last updated 1 day ago * [Definition](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#definition) * [Three Primary Risk Categories](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#three-primary-risk-categories) * [Fixed-Maturity Borrowing](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#fixed-maturity-borrowing) * [Floating-Rate Lending](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#floating-rate-lending) * [Liquidity Providers](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#liquidity-providers) * [Risk Scenarios](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#risk-scenarios) * [Mitigations (With Caveats)](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#mitigations-with-caveats) * [Key Warnings](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk#key-warnings) --- # Router Architecture | Fira Docs [hashtag](https://docs.fira.money/developers/architecture/router-architecture#overview) Overview ----------------------------------------------------------------------------------------------------- The `FiraRouterV4` is the single entry point for all user-facing protocol operations. It extends OpenZeppelin's `Proxy` and uses a selector-to-facet mapping to delegate every call to the appropriate action contract. circle-info Since the proxy uses `delegatecall`, all facets share the same storage. `RouterStorage` uses ERC-7201 storage namespacing (a hashed storage slot) to avoid collisions with any facet's own storage layout. [hashtag](https://docs.fira.money/developers/architecture/router-architecture#how-it-works) How it works ------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/architecture/router-architecture#call-routing) Call routing When a user calls any function on the router: 1. The `fallback()` function reads `msg.sig` (the 4-byte function selector) 2. Looks up the registered facet address in `CoreStorage.selectorToFacet[msg.sig]` 3. If no facet is registered, reverts with `INVALID_SELECTOR` 4. Otherwise, `delegatecall`s into the facet contract ### [hashtag](https://docs.fira.money/developers/architecture/router-architecture#initialization) Initialization The constructor takes two arguments: the owner address and the `ActionStorageV4` facet address. It hard-wires the `setSelectorToFacets` and `selectorToFacet` selectors to the storage facet so the owner can configure all other mappings post-deployment. ### [hashtag](https://docs.fira.money/developers/architecture/router-architecture#upgrading) Upgrading The owner can update selector-to-facet mappings at any time via `ActionStorageV4.setSelectorToFacets`. This allows: * **Adding new features** — Register new selectors pointing to new facet contracts * **Fixing bugs** — Point existing selectors to updated facet implementations * **Removing features** — Set a selector's facet to `address(0)` to disable it No state migration is needed because all facets share the router's storage via `delegatecall`. [hashtag](https://docs.fira.money/developers/architecture/router-architecture#facet-contracts) Facet contracts ------------------------------------------------------------------------------------------------------------------- Facet Responsibility **ActionSwapBTV3** BT swaps — token/FW to/from BT **ActionSwapCTV3** CT swaps — synthesized via BT pool + mint/redeem **ActionAddRemoveLiqV3** Liquidity operations — dual, single-sided, keep-CT variants **ActionMiscV3** FW/BC minting, position exits, multicall, simulate **ActionBorrow** Fixed-rate borrow and repay via lending markets **ActionSimple** Gas-optimized operations using on-chain approximation **ActionCallbackV3** Flash-style swap callbacks from the market **ActionStorageV4** Admin — ownership transfer, selector management [hashtag](https://docs.fira.money/developers/architecture/router-architecture#ct-swap-synthesis) CT swap synthesis ----------------------------------------------------------------------------------------------------------------------- CT is not directly traded in the AMM (the pool only has BT and FW). CT swaps are synthesized using the flash-callback pattern: **Buy CT (FW → CT):** **Sell CT (CT → FW):** The reverse — buy BT from market with FW, pair with user's CT, redeem BT+CT for FW. [hashtag](https://docs.fira.money/developers/architecture/router-architecture#on-chain-vs-off-chain-approximation) On-chain vs off-chain approximation ----------------------------------------------------------------------------------------------------------------------------------------------------------- The router supports two modes for calculating swap amounts: * **Off-chain hint** (`guessOffchain != 0`) — Binary search using `MarketApproxLibV2` with a hint provided by the caller. More gas-efficient for complex operations. * **On-chain approximation** (`guessOffchain == 0`) — Closed-form approximation using `MarketApproxLibOnchain`. Simpler code path, lower gas cost, used automatically when no hint is provided and no limit orders are present. [hashtag](https://docs.fira.money/developers/architecture/router-architecture#related-contracts) Related contracts ----------------------------------------------------------------------------------------------------------------------- * [`FiraRouterV4.sol`](https://docs.fira.money/developers/protocol-contracts/router) — Router contract details * [Router Facets](https://docs.fira.money/developers/protocol-contracts/router) — Individual facet documentation * [Contract Deployments](https://docs.fira.money/developers/contract-deployments) — Deployed facet addresses [PreviousArchitecturechevron-left](https://docs.fira.money/developers/architecture) [NextProtocol Contractschevron-right](https://docs.fira.money/developers/protocol-contracts) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/architecture/router-architecture#overview) * [How it works](https://docs.fira.money/developers/architecture/router-architecture#how-it-works) * [Call routing](https://docs.fira.money/developers/architecture/router-architecture#call-routing) * [Initialization](https://docs.fira.money/developers/architecture/router-architecture#initialization) * [Upgrading](https://docs.fira.money/developers/architecture/router-architecture#upgrading) * [Facet contracts](https://docs.fira.money/developers/architecture/router-architecture#facet-contracts) * [CT swap synthesis](https://docs.fira.money/developers/architecture/router-architecture#ct-swap-synthesis) * [On-chain vs off-chain approximation](https://docs.fira.money/developers/architecture/router-architecture#on-chain-vs-off-chain-approximation) * [Related contracts](https://docs.fira.money/developers/architecture/router-architecture#related-contracts) --- # Liquidity Injector | Fira Docs [hashtag](https://docs.fira.money/developers/features/liquidity-injector#overview) Overview ------------------------------------------------------------------------------------------------ Fixed-rate lending markets need BT as the loan token, but BT can normally only be created by splitting FW through the yield tokenization process. The Liquidity Injector solves this chicken-and-egg problem by having a special privilege to mint BT directly, without backing FW. circle-info The "unbacked" BT minted by the Liquidity Injector is safe because the lending market requires borrowers to post collateral. When borrowers repay their loans, the BT is burned. The injector is simply the bootstrap mechanism. [hashtag](https://docs.fira.money/developers/features/liquidity-injector#how-it-works) How it works -------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/liquidity-injector#inject-liquidity) Inject liquidity `injectLiquidity(params, amount)`: 1. Validates the market is a fixed-rate market (`params.irm == address(0)`) 2. Mints BT via `BondToken.mintByLI()` — the only way to create BT outside the normal FW→BT+CT path 3. Supplies the BT to the lending market via `lendingMarket.supply()` 4. Tracks the injection amount in `marketStats[marketId]` ### [hashtag](https://docs.fira.money/developers/features/liquidity-injector#withdraw-liquidity) Withdraw liquidity `withdrawLiquidity(params, amount)`: 1. Checks available liquidity (total supply minus total borrows) 2. Withdraws BT from the lending market 3. Burns the BT via `BondToken.burnByLI()` 4. Updates `marketStats[marketId]` The available liquidity check prevents withdrawal from disrupting existing borrows. [hashtag](https://docs.fira.money/developers/features/liquidity-injector#key-features) Key features -------------------------------------------------------------------------------------------------------- * **Owner-only operation** — Only the protocol owner can inject or withdraw * **No resting state** — BT is either in the lending market or burned; the injector never holds BT idly * **Per-market tracking** — `marketStats` records net injected amounts per market * **Self-balancing** — Borrowers must repay BT, which is then burned, closing the loop [hashtag](https://docs.fira.money/developers/features/liquidity-injector#risk-considerations) Risk considerations ---------------------------------------------------------------------------------------------------------------------- The unbacked BT creates a soft protocol liability: if the underlying FW exchange rate rises significantly, BT becomes more valuable than when it was minted. However, since borrowers must post collateral and repay in BT, the system is self-balancing. [hashtag](https://docs.fira.money/developers/features/liquidity-injector#related-contracts) Related contracts ------------------------------------------------------------------------------------------------------------------ * [`LiquidityInjector.sol`](https://docs.fira.money/developers/protocol-contracts/liquidity-injector) — Contract details * [`BondToken.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) — BT contract with `mintByLI`/`burnByLI` [PreviousRehypothecationchevron-left](https://docs.fira.money/developers/features/rehypothecation) [NextArchitecturechevron-right](https://docs.fira.money/developers/architecture) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/liquidity-injector#overview) * [How it works](https://docs.fira.money/developers/features/liquidity-injector#how-it-works) * [Inject liquidity](https://docs.fira.money/developers/features/liquidity-injector#inject-liquidity) * [Withdraw liquidity](https://docs.fira.money/developers/features/liquidity-injector#withdraw-liquidity) * [Key features](https://docs.fira.money/developers/features/liquidity-injector#key-features) * [Risk considerations](https://docs.fira.money/developers/features/liquidity-injector#risk-considerations) * [Related contracts](https://docs.fira.money/developers/features/liquidity-injector#related-contracts) --- # Features | Fira Docs [](https://docs.fira.money/developers/features/fw-fira-wrapped) **FW (Fira Wrapped)** [](https://docs.fira.money/developers/features/bond-token-bt) **Bond Token (BT)** [](https://docs.fira.money/developers/features/coupon-token-ct) **Coupon Token (CT)** [](https://docs.fira.money/developers/features/fira-market-amm) **Fira Market (AMM)** [](https://docs.fira.money/developers/features/fixed-rate-lending) **Fixed-Rate Lending** [](https://docs.fira.money/developers/features/variable-rate-lending) **Variable-Rate Lending** [](https://docs.fira.money/developers/features/rehypothecation) **Rehypothecation** [](https://docs.fira.money/developers/features/liquidity-injector) **Liquidity Injector** [PreviousProtocol Primerchevron-left](https://docs.fira.money/developers/fira-protocol-primer) [NextFixed-Rate Lendingchevron-right](https://docs.fira.money/developers/features/fixed-rate-lending) Last updated 1 day ago --- # Collateral Risk | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#definition) Definition -------------------------------------------------------------------------------------------------------------- Collateral risk represents a subset of bad debt risk involving the potential decline in value and/or liquidity of collateral to levels that cannot adequately secure outstanding borrowing positions. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#risk-mechanisms) Risk Mechanisms ------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#price-and-liquidity-deterioration) Price and Liquidity Deterioration Collateral risk primarily arises from adverse price movements and/or liquidity shortfalls under standard market conditions. Even when liquidation-eligible, positions may clear at unfavorable prices due to market friction, resulting in protocol bad debt. ### [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#asset-specific-failures) Asset-Specific Failures Certain assets — particularly stablecoins, wrapped tokens, and bridged assets — face idiosyncratic risks. Triggering events include: * Smart contract exploits * Governance failures * Issuer misconduct * Redemption halts * Blacklisting * Structural weaknesses Such scenarios can cause collateral value to deteriorate rapidly and potentially irreversibly. [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#specific-risk-scenarios) Specific Risk Scenarios ---------------------------------------------------------------------------------------------------------------------------------------- 1. Sharp price crashes between oracle updates 2. Liquidity disappearance despite maintained pricing 3. Stablecoin de-pegging or redemption impairment 4. Issuer-enforced blacklisting preventing asset transfers [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#mitigation) Mitigation -------------------------------------------------------------------------------------------------------------- Fira implements a conservative collateral selection framework emphasizing blue-chip assets evaluated for: * Liquidity * Price history * Redemption mechanisms * Smart contract security * Governance * Protocol resilience [hashtag](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#limitations) Limitations ---------------------------------------------------------------------------------------------------------------- "Blue-chip" designation provides no guarantee against severe drawdowns. Due diligence cannot predict all failure modes, and external dependencies remain uncontrollable. Lenders may bear losses from resulting bad debt, even in conservatively collateralized markets. [PreviousBad Debt Riskchevron-left](https://docs.fira.money/security-and-risk/risk-framework/bad-debt-risk) [NextLiquidity Riskchevron-right](https://docs.fira.money/security-and-risk/risk-framework/liquidity-risk) Last updated 1 day ago * [Definition](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#definition) * [Risk Mechanisms](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#risk-mechanisms) * [Price and Liquidity Deterioration](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#price-and-liquidity-deterioration) * [Asset-Specific Failures](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#asset-specific-failures) * [Specific Risk Scenarios](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#specific-risk-scenarios) * [Mitigation](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#mitigation) * [Limitations](https://docs.fira.money/security-and-risk/risk-framework/collateral-risk#limitations) --- # Floating-Rate Markets | Fira Docs Floating-rate markets provide variable-rate borrowing and lending without maturity constraints. Rates adjust continuously based on utilization. These markets serve two purposes in Fira: standalone variable-rate lending, and the foundation for [rehypothecation](https://docs.fira.money/protocol/rehypothecation) of fixed-rate market reserves. [hashtag](https://docs.fira.money/protocol/floating-rate-markets#how-it-works) How It Works ------------------------------------------------------------------------------------------------ * Lenders deposit assets into a pool and earn variable yield * Borrowers post collateral and borrow from the pool, accruing interest continuously * Both sides can enter and exit at any time — no maturity date * Rates move with utilization: more borrowing means higher rates ### [hashtag](https://docs.fira.money/protocol/floating-rate-markets#lend-rate) Lend Rate LendAPR\=Borrowrate×UtilizationLend\_{APR} = Borrow\_{rate}\\times UtilizationLendAPR​\=Borrowrate​×Utilization Because both rates are volatile, floating-rate markets suit short- to medium-term positions. [hashtag](https://docs.fira.money/protocol/floating-rate-markets#interest-rate-model-irm) Interest Rate Model (IRM) ------------------------------------------------------------------------------------------------------------------------ The borrow rate is determined by a utilization-based Interest Rate Model. The core formula: r(t)\=rT(t)×curve(u(t))r(t)=r\_T(t)\\times curve(u(t))r(t)\=rT​(t)×curve(u(t)) Where: * r(t)r(t)r(t) is the instantaneous spot borrowing rate * rT(t)r\_T(t)rT​(t) is the rate target — the rate when utilization equals the target * curve(u(t))curve(u(t))curve(u(t)) shapes how rates respond to utilization deviations ### [hashtag](https://docs.fira.money/protocol/floating-rate-markets#utilization) Utilization Represented as the fraction of supplied liquidity currently borrowed. u(t)\=Borrowed(t)Supplied(t)u(t)=\\frac{Borrowed(t)}{Supplied(t)}u(t)\=Supplied(t)Borrowed(t)​ Further, using utilization, we compute an abstract value from our utility function e(u)e(u)e(u). e(u)\={u−utargetutargetif u≤utargetu−utarget1−utargetif u\>utargete(u) = \\begin{cases} \\dfrac{u - u\_{\\text{target}}}{u\_{\\text{target}}} & \\text{if } u \\leq u\_{\\text{target}} \\\\\[8pt\] \\dfrac{u - u\_{\\text{target}}}{1 - u\_{\\text{target}}} & \\text{if } u > u\_{\\text{target}} \\end{cases}e(u)\=⎩⎨⎧​utarget​u−utarget​​1−utarget​u−utarget​​​if u≤utarget​if u\>utarget​​ ### [hashtag](https://docs.fira.money/protocol/floating-rate-markets#rate-target) Rate Target The rate target starts at a configured value and evolves dynamically: rT(t)\=rT(t∗)×exp(kp×e(u)×(t−t∗))r\_T(t) = r\_T(t\*) × exp(k\_p × e(u) × (t-t\*))rT​(t)\=rT​(t∗)×exp(kp​×e(u)×(t−t∗)) When utilization exceeds the target, the rate target increases — making borrowing more expensive and encouraging repayment. When utilization is below target, the rate target decreases — making borrowing cheaper and encouraging demand. The utility function e(u)e(u)e(u) symmetrically scales deviations above and below the target utilization utargetu\_{target}utarget​. ### [hashtag](https://docs.fira.money/protocol/floating-rate-markets#utilization-curve) Utilization Curve The curve function adds a second layer of rate responsiveness. Below target utilization, rates decrease gradually. Above target, rates increase sharply — creating natural pressure to keep utilization near the target. curve(u)\={(1−1kd)⋅e(u)+1if u≤utarget(kd−1)⋅e(u)+1if u\>utarget\\text{curve}(u) = \\begin{cases} \\left(1 - \\dfrac{1}{k\_d}\\right) \\cdot e(u) + 1 & \\text{if } u \\leq u\_{\\text{target}} \\\\\[8pt\] (k\_d - 1) \\cdot e(u) + 1 & \\text{if } u > u\_{\\text{target}} \\end{cases}curve(u)\=⎩⎨⎧​(1−kd​1​)⋅e(u)+1(kd​−1)⋅e(u)+1​if u≤utarget​if u\>utarget​​ The slope is controlled by kdk\_dkd​, the curve steepness parameter. ### [hashtag](https://docs.fira.money/protocol/floating-rate-markets#rate-bounds) Rate Bounds Rates are bounded between rminr\_{min}rmin​ and rmaxr\_{max}rmax​ to prevent extreme values: r(t)\=max⁡ ⁣(min⁡ ⁣(rT(t)⋅curve(u(t)),  rmax⁡),  rmin⁡)r(t) = \\max\\!\\bigl(\\min\\!\\bigl(r\_T(t) \\cdot \\text{curve}(u(t)),\\; r\_{\\max}\\bigr),\\; r\_{\\min}\\bigr)r(t)\=max(min(rT​(t)⋅curve(u(t)),rmax​),rmin​) [hashtag](https://docs.fira.money/protocol/floating-rate-markets#parameters) Parameters -------------------------------------------------------------------------------------------- All IRM parameters are global across floating-rate markets and governed by the DAO: Parameter Description utargetu\_{target}utarget​ Target utilization ratio kpk\_pkp​ Speed of rate target adjustment kdk\_dkd​ Steepness of the utilization curve rT(0)r\_T(0)rT​(0) Initial rate target at market launch rminr\_{min}rmin​ , rmaxr\_{max}rmax​ Rate floor and ceiling [hashtag](https://docs.fira.money/protocol/floating-rate-markets#role-in-firas-architecture) Role in Fira's Architecture ----------------------------------------------------------------------------------------------------------------------------- Floating-rate markets integrate with the rest of Fira through: * **Rehypothecation** — Idle reserves from fixed-rate markets (FW tokens) are deployed into floating-rate vaults to earn yield, which flows to CT holders * **Curation** — Curated vaults can allocate capital across both fixed-rate and floating-rate markets * **Composability** — The same collateral types and oracle infrastructure serve both market types [hashtag](https://docs.fira.money/protocol/floating-rate-markets#related) Related -------------------------------------------------------------------------------------- * [Fixed-Rate Markets](https://docs.fira.money/protocol/fixed-rate-markets) — Maturity-based borrowing with locked rates * [Rehypothecation](https://docs.fira.money/protocol/rehypothecation) — How fixed-rate reserves earn floating yield * [Curation Vaults](https://docs.fira.money/protocol/curation-vaults) — Multi-layer capital allocation * [Whitepaper](https://docs.fira.money/resources/whitepaper) — Full mathematical treatment [PreviousFixed-Rate Marketschevron-left](https://docs.fira.money/protocol/fixed-rate-markets) [NextRehypothecationchevron-right](https://docs.fira.money/protocol/rehypothecation) Last updated 1 day ago * [How It Works](https://docs.fira.money/protocol/floating-rate-markets#how-it-works) * [Lend Rate](https://docs.fira.money/protocol/floating-rate-markets#lend-rate) * [Interest Rate Model (IRM)](https://docs.fira.money/protocol/floating-rate-markets#interest-rate-model-irm) * [Utilization](https://docs.fira.money/protocol/floating-rate-markets#utilization) * [Rate Target](https://docs.fira.money/protocol/floating-rate-markets#rate-target) * [Utilization Curve](https://docs.fira.money/protocol/floating-rate-markets#utilization-curve) * [Rate Bounds](https://docs.fira.money/protocol/floating-rate-markets#rate-bounds) * [Parameters](https://docs.fira.money/protocol/floating-rate-markets#parameters) * [Role in Fira's Architecture](https://docs.fira.money/protocol/floating-rate-markets#role-in-firas-architecture) * [Related](https://docs.fira.money/protocol/floating-rate-markets#related) --- # YieldContractFactory | Fira Docs circle-info **Source:** `src/fira_bonding/core/YieldContracts/YieldContractFactory.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#contract-summary) Contract summary ---------------------------------------------------------------------------------------------------------------------------------------------- Creates BT/CT pairs for a given FW and expiry. BT is deployed with `Create2`, CT with the split-code factory pattern (because CT bytecode exceeds 24KB). [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#validations) Validations ------------------------------------------------------------------------------------------------------------------------------------ * Expiry must be in the future and divisible by `expiryDivisor` * Duplicate FW+expiry pairs revert [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#storage) Storage ---------------------------------------------------------------------------------------------------------------------------- After deployment, the factory stores lookup mappings: * `getBT[FW][expiry]` / `getCT[FW][expiry]` — Address discovery * `isBT[addr]` / `isCT[addr]` — Validation [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#fee-configuration) Fee configuration ------------------------------------------------------------------------------------------------------------------------------------------------ * `interestFeeRate` and `rewardFeeRate` (max 20% each) * `treasury` address for fee collection * `liquidityInjector` address, propagated to BT on creation [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#initialization) Initialization ------------------------------------------------------------------------------------------------------------------------------------------ After deployment, BT is initialized with the CT address, establishing the one-to-one pairing. [PreviousCoupon Tokenchevron-left](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) [NextRehypothecation Modulechevron-right](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#contract-summary) * [Validations](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#validations) * [Storage](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#storage) * [Fee configuration](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#fee-configuration) * [Initialization](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory#initialization) --- # Core | Fira Docs The core module houses the contracts users interact with (through the router) to trade, provide liquidity, and split yield into fixed and floating components. [hashtag](https://docs.fira.money/developers/protocol-contracts/core#how-market-and-yieldcontracts-interact) How Market and YieldContracts interact -------------------------------------------------------------------------------------------------------------------------------------------------------- The two subsystems are tightly coupled. A `FiraMarket` is parameterized by a BT address, and every swap queries the associated CT contract for the current BC index (via `CT.newIndex()`). The BC index determines how BT (denominated in asset units) should price against FW. When the BC index rises (because the underlying vault earns yield), BT becomes cheaper in FW terms. The AMM incorporates this automatically: `getMarketPreCompute` converts FW reserves to asset terms before computing the exchange rate, so the pricing curve always reflects the current yield environment. At expiry, the market freezes: swaps and new deposits revert. Burns still work, letting LPs exit. Post-expiry exits go through `CT.redeemBC()` rather than AMM swaps. [hashtag](https://docs.fira.money/developers/protocol-contracts/core#state-management-pattern) State management pattern ---------------------------------------------------------------------------------------------------------------------------- Both the market and yield contracts use a **read-modify-write pattern** with in-memory structs. The market loads `MarketState` into memory via `readState`, mutates it through `MarketMathCore` library calls, and persists it through `_writeState`. This avoids repeated SLOAD/SSTORE operations and keeps the math library pure. [hashtag](https://docs.fira.money/developers/protocol-contracts/core#contracts) Contracts ---------------------------------------------------------------------------------------------- * [FiraMarket](https://docs.fira.money/developers/protocol-contracts/core/fira-market) — BT/FW AMM with LP tokens * [FiraMarketFactory](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory) — Split-code CREATE2 market deployment * [MarketMathCore](https://docs.fira.money/developers/protocol-contracts/core/market-math-core) — Pricing curve and trade execution math [PreviousProtocol Contractschevron-left](https://docs.fira.money/developers/protocol-contracts) [NextFiraMarketchevron-right](https://docs.fira.money/developers/protocol-contracts/core/fira-market) Last updated 1 day ago * [How Market and YieldContracts interact](https://docs.fira.money/developers/protocol-contracts/core#how-market-and-yieldcontracts-interact) * [State management pattern](https://docs.fira.money/developers/protocol-contracts/core#state-management-pattern) * [Contracts](https://docs.fira.money/developers/protocol-contracts/core#contracts) --- # Rehypothecation | Fira Docs [hashtag](https://docs.fira.money/developers/features/rehypothecation#overview) Overview --------------------------------------------------------------------------------------------- FW tokens hold their underlying assets in two places: **idle reserves** (for instant redemptions) and an **ERC-4626 vault** (for yield generation). The RehypothecationModule defines the parameters that govern this balance. circle-info Rehypothecation ensures FW always has enough idle liquidity for redemptions while maximizing yield by deploying the rest into the underlying vault. [hashtag](https://docs.fira.money/developers/features/rehypothecation#how-it-works) How it works ----------------------------------------------------------------------------------------------------- The RehypothecationModule defines three parameters (in basis points): Parameter Purpose `phiMin` Minimum idle ratio — if idle drops below this, assets are withdrawn from vault `phiMax` Maximum idle ratio — if idle exceeds this, excess is deposited into vault `phiTarget` Target idle ratio — used by `forceRehypothecation()` to rebalance ### [hashtag](https://docs.fira.money/developers/features/rehypothecation#triggering-rebalance) Triggering rebalance * `**triggerRehypothecation()**` — Callable by anyone. Deposits excess to vault if `idleRatio > phiMax`, or withdraws from vault if `idleRatio < phiMin`. No-ops if the ratio is within bounds. * `**forceRehypothecation()**` — Owner-only. Always rebalances to `phiTarget` regardless of current ratio. ### [hashtag](https://docs.fira.money/developers/features/rehypothecation#example) Example If `phiMin = 10%`, `phiMax = 30%`, `phiTarget = 20%`: * FW holds 100 USDC total, 5 USDC idle (5% idle ratio → below `phiMin`) * Anyone calls `triggerRehypothecation()` → vault withdraws USDC to bring idle up * After rebalance: ~20 USDC idle, ~80 USDC in vault [hashtag](https://docs.fira.money/developers/features/rehypothecation#key-features) Key features ----------------------------------------------------------------------------------------------------- * **Automatic yield optimization** — Excess idle funds are deployed for yield * **Redemption guarantees** — Minimum idle ratio ensures users can always redeem * **Permissionless triggers** — Anyone can call `triggerRehypothecation()` when out of bounds * **Owner-controlled force rebalance** — Protocol can rebalance to target at any time [hashtag](https://docs.fira.money/developers/features/rehypothecation#related-contracts) Related contracts --------------------------------------------------------------------------------------------------------------- * [`RehypothecationModule.sol`](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module) — Contract details * [`FWBase.sol`](https://docs.fira.money/developers/token-contracts/fw-tokens) — FW base contract that uses the module [PreviousFira Market AMMchevron-left](https://docs.fira.money/developers/features/fira-market-amm) [NextLiquidity Injectorchevron-right](https://docs.fira.money/developers/features/liquidity-injector) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/rehypothecation#overview) * [How it works](https://docs.fira.money/developers/features/rehypothecation#how-it-works) * [Triggering rebalance](https://docs.fira.money/developers/features/rehypothecation#triggering-rebalance) * [Example](https://docs.fira.money/developers/features/rehypothecation#example) * [Key features](https://docs.fira.money/developers/features/rehypothecation#key-features) * [Related contracts](https://docs.fira.money/developers/features/rehypothecation#related-contracts) --- # Bond Token | Fira Docs circle-info **Source:** `src/fira_bonding/core/YieldContracts/BondToken.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#contract-summary) Contract summary ---------------------------------------------------------------------------------------------------------------------------------- BondToken is intentionally minimal. It stores immutable references to FW, factory, and expiry. The CT address is set once during `initialize()`, and the LiquidityInjector address is stored as a configurable variable. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#access-control) Access control ------------------------------------------------------------------------------------------------------------------------------ * `**mintByCT**` **/** `**burnByCT**` — Only the paired CouponToken can call these * `**mintByLI**` **/** `**burnByLI**` — Only the LiquidityInjector can call these * No other address can mint or burn BT This strict access prevents principal inflation outside the yield-split lifecycle. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#expiry) Expiry -------------------------------------------------------------------------------------------------------------- `isExpired()` delegates to `MiniHelpers.isCurrentlyExpired`. BT has no post-expiry logic itself — all post-expiry behavior lives in the CouponToken contract. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#inherited-contracts) Inherited contracts ---------------------------------------------------------------------------------------------------------------------------------------- * `FiraERC20` — ERC-20 with reentrancy guard [PreviousYield Contractschevron-left](https://docs.fira.money/developers/protocol-contracts/yield-contracts) [NextCoupon Tokenchevron-right](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#contract-summary) * [Access control](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#access-control) * [Expiry](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#expiry) * [Inherited contracts](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token#inherited-contracts) --- # FiraERC20 | Fira Docs circle-info **Source:** `src/fira_bonding/erc20/FiraERC20.sol`, `FiraERC20Permit.sol`, `FiraERC20Upg.sol`, `FiraERC20PermitUpg.sol` [hashtag](https://docs.fira.money/developers/token-contracts/fira-erc20#variants) Variants ----------------------------------------------------------------------------------------------- Contract Permit Upgradeable Used by `FiraERC20` No No BT, FiraMarket (LP) `FiraERC20Permit` EIP-2612 No — `FiraERC20Upg` No Yes (Initializable) — `FiraERC20PermitUpg` EIP-2612 Yes (Initializable) FW tokens [hashtag](https://docs.fira.money/developers/token-contracts/fira-erc20#reentrancy-guard) Reentrancy guard --------------------------------------------------------------------------------------------------------------- A `_reentrancyStatus` slot flips between `_NOT_ENTERED` (1) and `_ENTERED` (2). The `nonReentrant` modifier is available to all contracts that inherit `FiraERC20`. This means `FiraMarket` (which extends `FiraERC20` as its LP token) gets reentrancy protection without extra inheritance. [hashtag](https://docs.fira.money/developers/token-contracts/fira-erc20#transfer-hooks) Transfer hooks ----------------------------------------------------------------------------------------------------------- * `_beforeTokenTransfer` — Virtual, overridden by CT (distributes interest) and FW (enforces pause) * `_afterTokenTransfer` — Virtual, available for derived contracts [hashtag](https://docs.fira.money/developers/token-contracts/fira-erc20#permit-eip-2612) Permit (EIP-2612) --------------------------------------------------------------------------------------------------------------- `FiraERC20Permit` adds gasless approvals via `permit(owner, spender, value, deadline, v, r, s)`. Uses EIP-712 typed data for domain separation. The `DOMAIN_SEPARATOR` is computed at construction time and cached. [hashtag](https://docs.fira.money/developers/token-contracts/fira-erc20#design-decisions) Design decisions --------------------------------------------------------------------------------------------------------------- * No `receive` or `fallback` — only contracts that need ETH (FWBase, Router) add `receive()` * Storage layout matches between upgradeable and non-upgradeable variants [PreviousToken Contractschevron-left](https://docs.fira.money/developers/token-contracts) [NextBond Tokenchevron-right](https://docs.fira.money/developers/token-contracts/bond-token) Last updated 1 day ago * [Variants](https://docs.fira.money/developers/token-contracts/fira-erc20#variants) * [Reentrancy guard](https://docs.fira.money/developers/token-contracts/fira-erc20#reentrancy-guard) * [Transfer hooks](https://docs.fira.money/developers/token-contracts/fira-erc20#transfer-hooks) * [Permit (EIP-2612)](https://docs.fira.money/developers/token-contracts/fira-erc20#permit-eip-2612) * [Design decisions](https://docs.fira.money/developers/token-contracts/fira-erc20#design-decisions) --- # Yield Contracts | Fira Docs Yield contracts are the mechanism by which FW is split into its fixed-rate and floating-rate components. BT/CT pairs are minted 1:1 at the BC index rate and can be recombined to recover FW until (and after) expiry. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts#contracts) Contracts --------------------------------------------------------------------------------------------------------- * [BondToken](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) — Fixed-rate principal claim, mintable/burnable by CT and LiquidityInjector * [CouponToken](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) — Floating-yield leg with interest tracking and post-expiry handling * [YieldContractFactory](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory) — Creates BT/CT pairs per FW + expiry [PreviousActionMiscchevron-left](https://docs.fira.money/developers/protocol-contracts/router/action-misc) [NextBond Tokenchevron-right](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) Last updated 1 day ago --- # Bond Token | Fira Docs circle-info **Source:** `src/fira_bonding/core/YieldContracts/BondToken.sol` [hashtag](https://docs.fira.money/developers/token-contracts/bond-token#token-details) Token details --------------------------------------------------------------------------------------------------------- Property Value Standard ERC-20 (FiraERC20) Symbol BT Decimals 6 Permit No [hashtag](https://docs.fira.money/developers/token-contracts/bond-token#minting-and-burning) Minting and burning --------------------------------------------------------------------------------------------------------------------- * `mintByCT(receiver, amount)` — Only callable by the paired CouponToken * `burnByCT(user, amount)` — Only callable by the paired CouponToken * `mintByLI(receiver, amount)` — Only callable by the LiquidityInjector * `burnByLI(amount)` — Only callable by the LiquidityInjector No other address can create or destroy BT. [hashtag](https://docs.fira.money/developers/token-contracts/bond-token#immutable-references) Immutable references ----------------------------------------------------------------------------------------------------------------------- * `FW` — The Fira Wrapped token address * `factory` — The YieldContractFactory that created this BT * `expiry` — Unix timestamp when BT matures [hashtag](https://docs.fira.money/developers/token-contracts/bond-token#related-pages) Related pages --------------------------------------------------------------------------------------------------------- * [BondToken (Protocol Contract)](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) * [Bond Token (Feature)](https://docs.fira.money/developers/features/bond-token-bt) [PreviousFiraERC20chevron-left](https://docs.fira.money/developers/token-contracts/fira-erc20) [NextCoupon Tokenchevron-right](https://docs.fira.money/developers/token-contracts/coupon-token) Last updated 1 day ago * [Token details](https://docs.fira.money/developers/token-contracts/bond-token#token-details) * [Minting and burning](https://docs.fira.money/developers/token-contracts/bond-token#minting-and-burning) * [Immutable references](https://docs.fira.money/developers/token-contracts/bond-token#immutable-references) * [Related pages](https://docs.fira.money/developers/token-contracts/bond-token#related-pages) --- # Protocol Contracts | Fira Docs [](https://docs.fira.money/developers/protocol-contracts/core) **Core (AMM + Math)** [](https://docs.fira.money/developers/protocol-contracts/yield-contracts) **Yield Contracts (BT + CT)** [](https://docs.fira.money/developers/protocol-contracts/router) **Router (Action Facets)** [](https://docs.fira.money/developers/protocol-contracts/lending) **Lending Markets** [](https://docs.fira.money/developers/protocol-contracts/liquidity-injector) **Liquidity Injector** [](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module) **Rehypothecation Module** [PreviousRouter Architecturechevron-left](https://docs.fira.money/developers/architecture/router-architecture) [NextCorechevron-right](https://docs.fira.money/developers/protocol-contracts/core) Last updated 1 day ago --- # FW (FiraWrapped) | Fira Docs [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#overview) Overview --------------------------------------------------------------------------------------------- FW tokens wrap yield-bearing assets (e.g., USDC in an ERC-4626 vault) into a standardized ERC-20 interface. The FW token is the foundation of the protocol — BT and CT are minted from FW, and the AMM trades BT against FW. circle-info The first FW implementation is **USDCFW**, which wraps USDC through the SisuVault (an ERC-4626 vault). The FW exchange rate increases over time as yield accrues from the underlying vault. [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#how-it-works) How it works ----------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#deposit) Deposit Users deposit a supported token (e.g., USDC) and receive FW shares. The number of shares depends on the current exchange rate. Deposits are validated against `isValidTokenIn` and protected by a `minSharesOut` slippage guard. ### [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#redeem) Redeem Users burn FW shares and receive the underlying token. The amount returned depends on the current exchange rate, which increases as yield accrues. Redemptions are validated against `isValidTokenOut` and protected by a `minTokenOut` slippage guard. ### [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#exchange-rate) Exchange rate The FW exchange rate is the ratio of total underlying assets to total FW shares. It monotonically increases as the underlying vault generates yield. This property is critical: it ensures that BT+CT always represent at least as much underlying as the FW used to create them. [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#key-features) Key features ----------------------------------------------------------------------------------------------------- * **Standardized interface** — Any yield-bearing asset can be wrapped into FW, allowing the rest of the protocol to work with a uniform API. * **Yield accrual** — The exchange rate increases over time as the underlying vault earns yield. * **Pause controls** — Three independent pause mechanisms: deposits-only, redemptions-only, or global pause (blocks all transfers). * **Rehypothecation** — Underlying tokens are split between idle reserves (for instant redemptions) and vault deployment (for yield). See [Rehypothecation](https://docs.fira.money/developers/features/rehypothecation) . [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#bc-index) BC Index --------------------------------------------------------------------------------------------- The **BC Index** is derived from the FW exchange rate and is used throughout the protocol for yield tokenization. It is defined as: The BC Index is monotonically non-decreasing, which guarantees that BT+CT always represent at least as much underlying as the FW that was used to create them, even if the FW exchange rate temporarily dips. [hashtag](https://docs.fira.money/developers/features/fw-fira-wrapped#related-contracts) Related contracts --------------------------------------------------------------------------------------------------------------- * [`FWBase.sol`](https://docs.fira.money/developers/token-contracts/fw-tokens) — Abstract base contract * [`USDCFW.sol`](https://docs.fira.money/developers/token-contracts/fw-tokens) — USDC implementation * [`BCIndex.sol`](https://docs.fira.money/developers/utility-contracts/libraries/helpers) — Type wrapper and conversion functions [PreviousCoupon Token (CT)chevron-left](https://docs.fira.money/developers/features/coupon-token-ct) [NextFira Market AMMchevron-right](https://docs.fira.money/developers/features/fira-market-amm) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/fw-fira-wrapped#overview) * [How it works](https://docs.fira.money/developers/features/fw-fira-wrapped#how-it-works) * [Deposit](https://docs.fira.money/developers/features/fw-fira-wrapped#deposit) * [Redeem](https://docs.fira.money/developers/features/fw-fira-wrapped#redeem) * [Exchange rate](https://docs.fira.money/developers/features/fw-fira-wrapped#exchange-rate) * [Key features](https://docs.fira.money/developers/features/fw-fira-wrapped#key-features) * [BC Index](https://docs.fira.money/developers/features/fw-fira-wrapped#bc-index) * [Related contracts](https://docs.fira.money/developers/features/fw-fira-wrapped#related-contracts) Copy BCIndex = max(FW.exchangeRate(), previousBCIndex) --- # ActionSwapBT | Fira Docs circle-info **Source:** `src/fira_bonding/router/ActionSwapBTV3.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt#functions) Functions --------------------------------------------------------------------------------------------------------------- * `**swapExactTokenForBt**` — User token → FW (mint) → FW sent to market → swap for BT * `**swapExactFwForBt**` — FW → BT via market swap * `**swapExactBtForToken**` — BT → FW (market swap) → redeem to user token * `**swapExactBtForFw**` — BT → FW via market swap [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt#swap-amount-calculation) Swap amount calculation ------------------------------------------------------------------------------------------------------------------------------------------- The FW→BT direction uses `MarketApproxBtOutLibV2.approxSwapExactFwForBtV2` with binary search and an off-chain hint (`guessOffchain`). This is needed because the market only supports exact-output BT swaps (`swapFwForExactBt`), so the approximation library finds the BT amount that uses exactly the available FW. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt#on-chain-fallback) On-chain fallback ------------------------------------------------------------------------------------------------------------------------------- If `guessOffchain == 0` and no limit orders are present, the facet delegates to `ActionSimple` which uses `MarketApproxLibOnchain` for a closed-form approximation instead. [PreviousRouterchevron-left](https://docs.fira.money/developers/protocol-contracts/router) [NextActionSwapCTchevron-right](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct) Last updated 1 day ago * [Functions](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt#functions) * [Swap amount calculation](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt#swap-amount-calculation) * [On-chain fallback](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt#on-chain-fallback) --- # ActionMisc | Fira Docs circle-info **Source:** `src/fira_bonding/router/ActionMiscV3.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-misc#functions) Functions ------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-misc#btct-lifecycle) BT+CT lifecycle * `**mintBcFromToken**` **/** `**mintBcFromFw**` — Convert tokens or FW into equal BT + CT * `**redeemBcToToken**` **/** `**redeemBcToFw**` — Recombine BT + CT back to tokens or FW ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-misc#position-exits) Position exits * `**exitPreExpToToken**` **/** `**exitPreExpToFw**` — Exit all positions (LP + BT + CT) pre-expiry. First matches BT with CT for direct redemption (cheapest path), then swaps any remaining unmatched tokens via the AMM. * `**exitPostExpToToken**` **/** `**exitPostExpToFw**` — Post-expiry exit. Burns LP, sends BT to CT contract, redeems via `CT.redeemBC()`. CT is not burned post-expiry. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-misc#utility) Utility * `**multicall**` — Batches multiple router calls via `delegatecall` to self. Each sub-call can be marked `allowFailure`. * `**simulate**` — Executes a call and reverts with the result bytes. Used by off-chain code to preview transaction outcomes without sending a real transaction. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-misc#rewards) Rewards * `**redeemDueInterestAndRewardsV2**` — Collects interest from CT + rewards from FW + rewards from markets, optionally swapping reward tokens via an aggregator. [PreviousActionSimplechevron-left](https://docs.fira.money/developers/protocol-contracts/router/action-simple) [NextYield Contractschevron-right](https://docs.fira.money/developers/protocol-contracts/yield-contracts) Last updated 1 day ago * [Functions](https://docs.fira.money/developers/protocol-contracts/router/action-misc#functions) * [BT+CT lifecycle](https://docs.fira.money/developers/protocol-contracts/router/action-misc#btct-lifecycle) * [Position exits](https://docs.fira.money/developers/protocol-contracts/router/action-misc#position-exits) * [Utility](https://docs.fira.money/developers/protocol-contracts/router/action-misc#utility) * [Rewards](https://docs.fira.money/developers/protocol-contracts/router/action-misc#rewards) --- # Contract Deployments | Fira Docs For the complete list of deployed contract addresses, market configurations, oracle pipelines, router facets, and key roles, see the dedicated deployment page: [Deploymentchevron-right](https://docs.fira.money/developers/deployment) [PreviousHelperschevron-left](https://docs.fira.money/developers/utility-contracts/libraries/helpers) [NextUser Flowschevron-right](https://docs.fira.money/developers/user-flows) Last updated 1 day ago --- # MarketMathCore | Fira Docs circle-info **Source:** `src/fira_bonding/core/Market/MarketMathCore.sol`, `src/fira_bonding/core/Market/OracleLib.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#marketmathcore) MarketMathCore ------------------------------------------------------------------------------------------------------------------------- This library operates entirely on in-memory `MarketState` structs for gas efficiency. It never reads from or writes to storage directly. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#pricing-model) Pricing model The AMM prices BT relative to FW using a logit curve: Copy exchangeRate = ln(proportion / (1 - proportion)) / rateScalar + rateAnchor Where `proportion = totalBt / (totalBt + totalAsset)` and `totalAsset` is FW reserves converted to underlying asset units via the BC index. * `**rateScalar**` scales inversely with time-to-expiry (`scalarRoot × 365 days / timeToExpiry`), making the curve steeper near maturity. * `**rateAnchor**` is recalculated after each trade so that the current pool proportion yields the last recorded implied rate. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#liquidity-math) Liquidity math * **First deposit:** Mints `sqrt(fw × bt) - MINIMUM_LIQUIDITY` LP tokens, locking 1000 wei permanently. * **Subsequent deposits:** Mints proportional to the limiting token. * **Removal:** Returns proportional shares of both reserves. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#trade-execution) Trade execution `executeTradeCore` loads pre-computed values, calculates the FW amount from the exchange rate, applies fees, and updates state. Fees are split between the swapper (as worse pricing) and the reserve (as a percentage of the fee). The post-trade implied rate is recalculated and stored. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#key-invariants) Key invariants * Exchange rate is always >= 1e18 (reverts otherwise) * BT proportion cannot exceed `MAX_MARKET_PROPORTION` (96%) * Implied rate is always > 0 after a trade * `MINIMUM_LIQUIDITY` prevents the first-depositor attack [hashtag](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#oraclelib) OracleLib --------------------------------------------------------------------------------------------------------------- Adapted from Uniswap V3's oracle. Stores `Observation` structs (timestamp + cumulative `ln(impliedRate)` + initialized flag) in a fixed-size array of 65,535 slots. * `**write()**` — Appends a new observation if the block timestamp differs from the last * `**grow()**` — Pre-initializes storage slots to reduce gas during swaps * `**observe()**` — Returns cumulative values at requested time offsets using binary search * **TWAP** is computed by the caller as `(cumulative[now] - cumulative[ago]) / duration` [PreviousFiraMarketFactorychevron-left](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory) [NextLendingchevron-right](https://docs.fira.money/developers/protocol-contracts/lending) Last updated 1 day ago * [MarketMathCore](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#marketmathcore) * [Pricing model](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#pricing-model) * [Liquidity math](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#liquidity-math) * [Trade execution](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#trade-execution) * [Key invariants](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#key-invariants) * [OracleLib](https://docs.fira.money/developers/protocol-contracts/core/market-math-core#oraclelib) --- # ActionSwapCT | Fira Docs circle-info **Source:** `src/fira_bonding/router/ActionSwapCTV3.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#overview) Overview ------------------------------------------------------------------------------------------------------------- CT is not directly traded in the AMM — the pool only has BT and FW. CT swaps are synthesized: ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#buy-ct-fw-ct) Buy CT (FW → CT) Send FW to CT contract → mint BT+CT → sell BT back to market for FW → net output is CT. The callback mechanism handles this atomically: the market sends FW to the router first (flash-loan style), the router mints BT+CT using that FW to repay the BT debt. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#sell-ct-ct-fw) Sell CT (CT → FW) Buy BT from the market using FW → pair with user's CT → redeem BT+CT for FW → net output is FW minus the BT cost. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#functions) Functions --------------------------------------------------------------------------------------------------------------- * `**swapExactTokenForCt**` — User token → FW → CT (via synthesis) * `**swapExactFwForCt**` — FW → CT * `**swapExactCtForToken**` — CT → FW → user token * `**swapExactCtForFw**` — CT → FW [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#callback-handling) Callback handling ------------------------------------------------------------------------------------------------------------------------------- The flash-style swaps use `ActionCallbackV3` to handle the market's callback. The callback data encodes the action type and parameters, and the callback contract performs the BT+CT minting or redemption needed to settle the flash swap. [PreviousActionSwapBTchevron-left](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt) [NextActionAddRemoveLiqchevron-right](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#overview) * [Buy CT (FW → CT)](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#buy-ct-fw-ct) * [Sell CT (CT → FW)](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#sell-ct-ct-fw) * [Functions](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#functions) * [Callback handling](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct#callback-handling) --- # Coupon Token (CT) | Fira Docs [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#overview) Overview --------------------------------------------------------------------------------------------- CT represents the floating-yield component of the yield split. Holding CT entitles you to the yield generated by the underlying FW between the time of minting and expiry. Interest accrues automatically and can be claimed at any time. circle-info CT is the stateful contract that drives the entire BT/CT lifecycle. It manages minting, redemption, interest accounting, and post-expiry behavior. [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#how-it-works) How it works ----------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#interest-accrual) Interest accrual CT uses a per-user interest tracking system. On every CT transfer (including mints and burns), interest is distributed to both sender and receiver. The interest formula is: Copy interest = principal × (currentIndex - prevIndex) / (prevIndex × currentIndex) Users can claim accrued interest at any time via `redeemDueInterestAndRewards`. A configurable `interestFeeRate` is deducted at claim time and sent to the treasury. ### [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#bc-index-caching) BC Index caching If `doCacheIndexSameBlock` is enabled, the BC Index is only updated once per block. This prevents sandwich attacks where the FW exchange rate is manipulated within a block to extract value from CT holders. ### [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#post-expiry-behavior) Post-expiry behavior On the first interaction after expiry, the CT contract snapshots the BC Index and freezes it. After this point: * **Interest index is frozen** — No new yield accrues to CT holders * **Post-expiry yield flows to treasury** — Any yield generated after expiry belongs to the protocol * **CT is not burned on redemption** — Post-expiry, only BT is required for redemption; CT has zero economic value [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#key-features) Key features ----------------------------------------------------------------------------------------------------- * **Floating yield exposure** — Earn variable yield from the underlying asset * **Automatic interest tracking** — Interest is distributed on every transfer * **Post-expiry treasury sweep** — Unclaimed post-expiry yield can be swept to treasury * **Reentrancy protected** — All external mutating functions use `nonReentrant` [hashtag](https://docs.fira.money/developers/features/coupon-token-ct#related-contracts) Related contracts --------------------------------------------------------------------------------------------------------------- * [`CouponToken.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) — Contract details * [`InterestManagerCT.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) — Interest accrual logic * [`BondToken.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) — Paired BT contract [PreviousBond Token (BT)chevron-left](https://docs.fira.money/developers/features/bond-token-bt) [NextFW (FiraWrapped)chevron-right](https://docs.fira.money/developers/features/fw-fira-wrapped) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/coupon-token-ct#overview) * [How it works](https://docs.fira.money/developers/features/coupon-token-ct#how-it-works) * [Interest accrual](https://docs.fira.money/developers/features/coupon-token-ct#interest-accrual) * [BC Index caching](https://docs.fira.money/developers/features/coupon-token-ct#bc-index-caching) * [Post-expiry behavior](https://docs.fira.money/developers/features/coupon-token-ct#post-expiry-behavior) * [Key features](https://docs.fira.money/developers/features/coupon-token-ct#key-features) * [Related contracts](https://docs.fira.money/developers/features/coupon-token-ct#related-contracts) --- # Liquidity Injector | Fira Docs circle-info **Source:** `src/liquidityInjector/LiquidityInjector.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#contract-summary) Contract summary -------------------------------------------------------------------------------------------------------------------------- The LiquidityInjector has a special privilege to call `BondToken.mintByLI()` to create BT without backing FW. This is the only way BT can be minted outside the normal FW→BT+CT yield-split path. [hashtag](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#functions) Functions ------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#injectliquidity-params-amount) `injectLiquidity(params, amount)` 1. Validates `params.irm == address(0)` (fixed-rate market identifier) 2. Calls `BondToken.mintByLI(address(this), amount)` to create BT 3. Approves and supplies BT to the lending market via `lendingMarket.supply()` 4. Increments `marketStats[marketId]` ### [hashtag](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#withdrawliquidity-params-amount) `withdrawLiquidity(params, amount)` 1. Checks available liquidity (total supply − total borrows, capped by balance) 2. Withdraws BT from the lending market 3. Burns BT via `BondToken.burnByLI()` 4. Decrements `marketStats[marketId]` [hashtag](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#invariants) Invariants -------------------------------------------------------------------------------------------------------------- * Owner-only for inject and withdraw * BT is never held in a resting state — always in the lending market or burned * `marketStats` tracks net injected amount per market * Available liquidity check prevents disrupting existing borrows [PreviousRehypothecation Modulechevron-left](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module) [NextToken Contractschevron-right](https://docs.fira.money/developers/token-contracts) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#contract-summary) * [Functions](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#functions) * [injectLiquidity(params, amount)](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#injectliquidity-params-amount) * [withdrawLiquidity(params, amount)](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#withdrawliquidity-params-amount) * [Invariants](https://docs.fira.money/developers/protocol-contracts/liquidity-injector#invariants) --- # Coupon Token | Fira Docs circle-info **Source:** `src/fira_bonding/core/YieldContracts/CouponToken.sol`, `src/fira_bonding/core/YieldContracts/InterestManagerCT.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#contract-summary) Contract summary ------------------------------------------------------------------------------------------------------------------------------------ CT extends `InterestManagerCT` and `FiraERC20`. Like BT, the FW, BT, factory, expiry, and `doCacheIndexSameBlock` fields are all immutable. All external mutating functions use `nonReentrant`. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#minting-btct) Minting BT+CT ----------------------------------------------------------------------------------------------------------------------------- `mintBC(receiverBT, receiverCT)` takes FW that has been pre-transferred to the CT contract, converts the FW amount to underlying asset units via the BC index, and mints equal BT and CT. The BC index is `max(FW.exchangeRate(), storedIndex)` — monotonically non-decreasing. `mintBCMulti` does the same for multiple receivers in one call. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#redeeming-btct) Redeeming BT+CT --------------------------------------------------------------------------------------------------------------------------------- `redeemBC(receiver)` burns BT from `address(this)` (must be pre-transferred) and burns CT if not expired. FW is returned based on the current BC index. **Post-expiry:** The redeemable FW amount is calculated at the _current_ BC index, but the excess between the post-expiry first index and the current index accrues as treasury interest. Post-expiry yield goes to the protocol, not to redeemers. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#interest-accounting) Interest accounting ------------------------------------------------------------------------------------------------------------------------------------------ `InterestManagerCT` tracks per-user interest via `UserInterest { index, accrued }`. On every CT transfer (`_beforeTokenTransfer`), interest is distributed to both sender and receiver: Copy interest = principal × (currentIndex - prevIndex) / (prevIndex × currentIndex) Claims go through `_doTransferOutInterest`, which deducts `interestFeeRate` and sends the fee to treasury. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#key-design-decisions) Key design decisions * Interest is based on CT balance, not FW balance * Protocol fees are taken at claim time, not at accrual time * `_distributeInterestForTwo` skips `address(0)` and `address(this)` to avoid phantom accounting [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#bc-index-caching) BC index caching ------------------------------------------------------------------------------------------------------------------------------------ If `doCacheIndexSameBlock` is true, the BC index is only updated once per block. This prevents sandwich attacks where the FW exchange rate is manipulated within a block to extract value from CT holders. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#post-expiry-state) Post-expiry state -------------------------------------------------------------------------------------------------------------------------------------- `_setPostExpiryData()` is called on the first interaction after expiry. It snapshots the BC index and reward indices. After this, the interest index is frozen to `postExpiry.firstBCIndex`, and all subsequent yield flows to treasury. `redeemInterestAndRewardsPostExpiryForTreasury()` sweeps all post-expiry interest to the treasury. [hashtag](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#inherited-contracts) Inherited contracts ------------------------------------------------------------------------------------------------------------------------------------------ * `InterestManagerCT` — Per-user interest tracking * `FiraERC20` — ERC-20 with reentrancy guard [PreviousBond Tokenchevron-left](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) [NextYieldContractFactorychevron-right](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#contract-summary) * [Minting BT+CT](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#minting-btct) * [Redeeming BT+CT](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#redeeming-btct) * [Interest accounting](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#interest-accounting) * [Key design decisions](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#key-design-decisions) * [BC index caching](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#bc-index-caching) * [Post-expiry state](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#post-expiry-state) * [Inherited contracts](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token#inherited-contracts) --- # Bond Token (BT) | Fira Docs [hashtag](https://docs.fira.money/developers/features/bond-token-bt#overview) Overview ------------------------------------------------------------------------------------------- BT represents a fixed-rate claim on the underlying asset. Each BT is redeemable for 1 unit of underlying at maturity. Before maturity, BT trades at a discount in the AMM — the discount reflects the implied fixed rate. circle-info BT and CT are always minted and burned in pairs. You cannot create BT without also creating CT, and vice versa. This ensures the total claims always match the underlying FW. [hashtag](https://docs.fira.money/developers/features/bond-token-bt#how-it-works) How it works --------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/bond-token-bt#minting) Minting BT is created through the CouponToken's `mintBC` function. FW is deposited into the CT contract, and equal amounts of BT and CT are minted based on the current BC Index. The conversion rate ensures that `BT amount + CT amount` always equals the underlying value of the FW deposited. ### [hashtag](https://docs.fira.money/developers/features/bond-token-bt#redemption) Redemption **Pre-expiry:** Both BT and CT must be provided. They are burned together and FW is returned. **Post-expiry:** Only BT is required. The CT is not burned (it has zero economic value post-expiry). FW is returned at the current BC Index rate, with any post-expiry yield accrual going to the protocol treasury. ### [hashtag](https://docs.fira.money/developers/features/bond-token-bt#trading) Trading BT trades against FW in the Fira Market AMM. As expiry approaches, the BT/FW exchange rate converges toward 1:1 (at the BC Index rate), since BT becomes redeemable for full underlying value at maturity. [hashtag](https://docs.fira.money/developers/features/bond-token-bt#key-features) Key features --------------------------------------------------------------------------------------------------- * **Fixed-rate principal** — Predictable value at maturity * **Strict access control** — Only the paired CouponToken and the LiquidityInjector can mint or burn BT * **Used as loan token** — In fixed-rate lending markets, borrowers receive BT which is swapped to USDC via the router * **Immutable references** — FW address, factory, and expiry are set at creation and cannot be changed [hashtag](https://docs.fira.money/developers/features/bond-token-bt#related-contracts) Related contracts ------------------------------------------------------------------------------------------------------------- * [`BondToken.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/bond-token) — Contract details * [`CouponToken.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) — Paired CT contract * [`YieldContractFactory.sol`](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory) — Factory that deploys BT/CT pairs [PreviousVariable-Rate Lendingchevron-left](https://docs.fira.money/developers/features/variable-rate-lending) [NextCoupon Token (CT)chevron-right](https://docs.fira.money/developers/features/coupon-token-ct) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/bond-token-bt#overview) * [How it works](https://docs.fira.money/developers/features/bond-token-bt#how-it-works) * [Minting](https://docs.fira.money/developers/features/bond-token-bt#minting) * [Redemption](https://docs.fira.money/developers/features/bond-token-bt#redemption) * [Trading](https://docs.fira.money/developers/features/bond-token-bt#trading) * [Key features](https://docs.fira.money/developers/features/bond-token-bt#key-features) * [Related contracts](https://docs.fira.money/developers/features/bond-token-bt#related-contracts) --- # Utility Contracts | Fira Docs * [Oracles](https://docs.fira.money/developers/utility-contracts/oracles) — TWAP pricing for BT, CT, LP tokens and solvency checks * [Libraries](https://docs.fira.money/developers/utility-contracts/libraries) — Math, token helpers, error definitions, and deployment utilities [PreviousFW Tokenschevron-left](https://docs.fira.money/developers/token-contracts/fw-tokens) [NextOracleschevron-right](https://docs.fira.money/developers/utility-contracts/oracles) Last updated 1 day ago --- # Helpers | Fira Docs circle-info **Source:** `src/fira_bonding/libraries/` [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/helpers#errors.sol) Errors.sol ------------------------------------------------------------------------------------------------------------ Central registry of all custom error types. Errors are prefixed by module (`Market*`, `YC*`, `FW*`, `Router*`). Using custom errors instead of string reverts saves gas and makes off-chain decoding straightforward. [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/helpers#tokenhelper.sol) TokenHelper.sol ---------------------------------------------------------------------------------------------------------------------- Safe ERC20 transfer wrappers with native ETH handling: * `_transferIn(token, from, amount)` — Handles ETH by checking `msg.value` and wrapping via WETH * `_transferOut(token, to, amount)` — Handles ETH by unwrapping WETH * `_selfBalance(token)` — Balance accounting for native ETH * `_safeApproveInf(token, spender)` — Infinite approval only if current allowance is low The `NATIVE` sentinel address (`0x000...000`) represents ETH in `TokenInput`/`TokenOutput` structs. [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/helpers#boringownableupgradeable.sol) BoringOwnableUpgradeable.sol ------------------------------------------------------------------------------------------------------------------------------------------------ Two-step ownership transfer: `transferOwnership(newOwner, direct, renounce)` either transfers immediately or sets a pending owner who must call `claimOwnership()`. Used by FW tokens and factories. [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/helpers#basesplitcodefactory-codedeployer) BaseSplitCodeFactory / CodeDeployer ------------------------------------------------------------------------------------------------------------------------------------------------------------ Works around the 24KB EVM contract size limit (EIP-170): 1. At factory deployment, creation bytecode is split into two chunks, each deployed as a "code storage" contract 2. At creation time, bytecode is concatenated in memory and deployed via CREATE2 Used by both `FiraMarketFactory` and `YieldContractFactory` since `FiraMarket` and `CouponToken` exceed the size limit. [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/helpers#other-helpers) Other helpers ------------------------------------------------------------------------------------------------------------------ * `**MiniHelpers.sol**` — `isCurrentlyExpired(expiry)`, `ensureNotExpired()` — used everywhere for pre/post-expiry gating * `**ExpiryUtilsLib.sol**` **/** `**StringLib.sol**` — Generate deterministic token names like `FW-USDC-BT-07MAY2026` from symbols and expiry timestamps * `**ArrayLib.sol**` — `create(a, b)` returns a 2-element `address[]`; `sum(arr)` sums a `uint256[]` [PreviousMathchevron-left](https://docs.fira.money/developers/utility-contracts/libraries/math) [NextContract Deploymentschevron-right](https://docs.fira.money/developers/contract-deployments) Last updated 1 day ago * [Errors.sol](https://docs.fira.money/developers/utility-contracts/libraries/helpers#errors.sol) * [TokenHelper.sol](https://docs.fira.money/developers/utility-contracts/libraries/helpers#tokenhelper.sol) * [BoringOwnableUpgradeable.sol](https://docs.fira.money/developers/utility-contracts/libraries/helpers#boringownableupgradeable.sol) * [BaseSplitCodeFactory / CodeDeployer](https://docs.fira.money/developers/utility-contracts/libraries/helpers#basesplitcodefactory-codedeployer) * [Other helpers](https://docs.fira.money/developers/utility-contracts/libraries/helpers#other-helpers) --- # Libraries | Fira Docs * [Math](https://docs.fira.money/developers/utility-contracts/libraries/math) — Fixed-point arithmetic (PMath) and logarithm/exponentiation (LogExpMath) * [Helpers](https://docs.fira.money/developers/utility-contracts/libraries/helpers) — Token transfers, error definitions, ownership, and deployment utilities [PreviousBC Oraclechevron-left](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle) [NextMathchevron-right](https://docs.fira.money/developers/utility-contracts/libraries/math) Last updated 1 day ago --- # Oracles | Fira Docs * [BC Oracle](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle) — TWAP pricing for BT and CT tokens * [LP Oracle](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle) — LP token pricing via hypothetical rebalancing * [Solvency Oracle](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle) — FW solvency-adjusted pricing for lending markets [PreviousUtility Contractschevron-left](https://docs.fira.money/developers/utility-contracts) [NextSolvency Oraclechevron-right](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle) Last updated 1 day ago --- # FiraMarketFactory | Fira Docs circle-info **Source:** `src/fira_bonding/core/Market/v3/FiraMarketFactory.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#contract-summary) Contract summary -------------------------------------------------------------------------------------------------------------------------------- Deploys markets using split-code CREATE2 (because `FiraMarket` exceeds the 24KB EVM contract size limit). Markets are keyed by `BT + scalarRoot + initialAnchor + lnFeeRateRoot` — creating the same combination twice reverts. [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#functionality) Functionality -------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#market-creation) Market creation The factory validates that the BT comes from the registered `YieldContractFactory` and is not expired, then deploys the market using the split-code pattern (bytecode is split across two storage contracts and concatenated at deploy time). ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#fee-management) Fee management The factory stores: * **Treasury address** — Receives reserve fees from swaps * **Reserve fee percent** — Portion of swap fees sent to treasury * **Router-specific fee overrides** — Must be strictly less than the market's base fee `getMarketConfig(market, router)` is called by the market on every `readState` to load treasury, fee overrides, and reserve percent. This means fee changes take effect on the next trade without redeployment. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#duplicate-prevention) Duplicate prevention Markets are uniquely identified by their BT address and curve parameters. Attempting to create a duplicate reverts. [PreviousFiraMarketchevron-left](https://docs.fira.money/developers/protocol-contracts/core/fira-market) [NextMarketMathCorechevron-right](https://docs.fira.money/developers/protocol-contracts/core/market-math-core) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#contract-summary) * [Functionality](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#functionality) * [Market creation](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#market-creation) * [Fee management](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#fee-management) * [Duplicate prevention](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory#duplicate-prevention) --- # ActionAddRemoveLiq | Fira Docs circle-info **Source:** `src/fira_bonding/router/ActionAddRemoveLiqV3.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#add-liquidity-variants) Add liquidity variants ------------------------------------------------------------------------------------------------------------------------------------------------ Function Input Strategy `addLiquidityDualTokenAndBt` Token + BT Mint FW from token, add with BT `addLiquidityDualFwAndBt` FW + BT Direct dual-sided add `addLiquiditySingleToken` Token only Mint FW, swap portion to BT, add both `addLiquiditySingleBt` BT only Swap portion to FW, add both `addLiquiditySingleFw` FW only Swap portion to BT, add both `addLiquiditySingleTokenKeepCt` Token only Mint FW, mint BT+CT, use BT for LP, keep CT `addLiquiditySingleFwKeepCt` FW only Same keep-CT strategy ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#keep-ct-strategy) Keep-CT strategy Instead of swapping FW to BT, the router mints BT+CT from FW. BT goes to the market for liquidity, CT goes to the user. This way the user gets LP exposure plus floating yield from CT simultaneously. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#remove-liquidity-variants) Remove liquidity variants ------------------------------------------------------------------------------------------------------------------------------------------------------ Function Output `removeLiquidityDualFwAndBt` FW + BT separately `removeLiquidityDualTokenAndBt` Token (from FW redeem) + BT `removeLiquiditySingleBt` BT only (FW swapped to BT) `removeLiquiditySingleFw` FW only (BT swapped to FW, or redeemed via CT post-expiry) `removeLiquiditySingleToken` Token (everything converted) ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#post-expiry-removal) Post-expiry removal Since the market doesn't allow swaps post-expiry, single-FW removal sends BT to the CT contract and redeems via `CT.redeemBC()`. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#core-mechanics) Core mechanics -------------------------------------------------------------------------------------------------------------------------------- All add operations ultimately call `FiraMarket.mint(receiver, netFwUsed, netBtUsed)`. Single-sided adds use approximation libraries to calculate how much to swap before depositing both sides. All remove operations call `FiraMarket.burn`. [PreviousActionSwapCTchevron-left](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct) [NextActionBorrowchevron-right](https://docs.fira.money/developers/protocol-contracts/router/action-borrow) Last updated 1 day ago * [Add liquidity variants](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#add-liquidity-variants) * [Keep-CT strategy](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#keep-ct-strategy) * [Remove liquidity variants](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#remove-liquidity-variants) * [Post-expiry removal](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#post-expiry-removal) * [Core mechanics](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq#core-mechanics) --- # Rehypothecation Module | Fira Docs circle-info **Source:** `src/fira_bonding/RehypothecationModule.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module#contract-summary) Contract summary ------------------------------------------------------------------------------------------------------------------------------ A configuration contract that stores three parameters (in basis points) controlling the FW idle ratio: Parameter Purpose `phiMin` Minimum idle ratio — triggers vault withdrawal if breached `phiMax` Maximum idle ratio — triggers vault deposit if breached `phiTarget` Target idle ratio — used by `forceRehypothecation()` [hashtag](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module#how-its-used) How it's used ----------------------------------------------------------------------------------------------------------------------- FW tokens reference this module when `triggerRehypothecation()` or `forceRehypothecation()` is called. The FW contract reads `phiMin`, `phiMax`, and `phiTarget` from the module and rebalances accordingly. The module is set on the FW token by the owner. Setting it to `address(0)` disables rehypothecation entirely. [hashtag](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module#related-pages) Related pages ------------------------------------------------------------------------------------------------------------------------ * [Rehypothecation (Feature)](https://docs.fira.money/developers/features/rehypothecation) * [FW Tokens](https://docs.fira.money/developers/token-contracts/fw-tokens) [PreviousYieldContractFactorychevron-left](https://docs.fira.money/developers/protocol-contracts/yield-contracts/yield-contract-factory) [NextLiquidity Injectorchevron-right](https://docs.fira.money/developers/protocol-contracts/liquidity-injector) Last updated 1 day ago * [Contract summary](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module#contract-summary) * [How it's used](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module#how-its-used) * [Related pages](https://docs.fira.money/developers/protocol-contracts/rehypothecation-module#related-pages) --- # Risk Disclaimers | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#risks-and-security-considerations) Risks and Security Considerations ---------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#important-notice) Important Notice This section highlights material risks associated with using Fira and interacting with Fira smart contracts. **Fira is experimental and involves significant risk**, including the risk of **partial or total loss of funds**. This section is provided for informational purposes only, is **not exhaustive**, and does not constitute financial, legal, tax, or other professional advice. You should only use Fira if you understand decentralized finance ("DeFi"), smart contracts, and collateralized lending/borrowing, and if you can bear the risk of losing all funds you provide or receive through the protocol. Fira is **non-custodial**: users control their own wallets and private keys. Transactions executed on a blockchain are generally **irreversible**, and losses may be permanent. ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#risk-summary-non-exhaustive) Risk Summary (Non-Exhaustive) Using Fira may expose you to one or more of the following categories of risk: * **Smart contract and technical risk** * **Blockchain/network and infrastructure risk** * **Third-party dependency risk** (tokens, oracles, DEX liquidity, RPC providers, bridges, etc.) * **Interest rate risk** (fixed-maturity and floating-rate markets) * **Liquidity and exit risk** (slippage, inability to unwind or withdraw) * **Liquidation risk** (including maturity-driven liquidation mechanics) * **Bad debt risk / lender loss risk** * **Collateral and asset-specific risk** (volatility, centralization, issuer/admin controls) * **Stablecoin and wrapping risk** (e.g., USDC and wrapped representations) * **AMM pricing / market manipulation risk** * **Coupon token and yield-trading risk** (CT dynamics, valuation uncertainty, illiquidity) * **Rehypothecation / strategy risk** (reserve allocation to variable-rate vaults) * **Governance and parameter-change risk** * **MEV and transaction execution risk** (front-running, sandwich attacks) * **Regulatory, legal, and tax risk** The subsections below describe these risks in more detail. **No single mitigation eliminates risk**, and multiple risks can materialize simultaneously, especially during periods of market stress. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#smart-contract-and-technical-risk) Smart Contract and Technical Risk Fira relies on smart contracts and supporting software. Smart contracts may contain **vulnerabilities, bugs, logic errors, design flaws, or unintended behaviors**, whether known or unknown at the time of deployment. Any such issue, whether exploited by third parties or triggered by unforeseen conditions, may result in **partial or total loss of funds**, including loss, theft, misallocation, inability to withdraw, forced liquidations, or broader disruption of protocol operations. Fira also relies on complex flows related to fixed-maturity lending/borrowing, including the issuance and exchange of protocol-specific tokens and market interactions, which may increase implementation and integration risk. Fira's fixed-maturity design involves **BT** (bond tokens) that trade at a discount and converge toward par at maturity, and **CT** (coupon tokens) representing claims on yield, with additional mechanisms for CT trading and reserve management. These mechanisms may introduce additional attack surfaces and edge cases. (See Fira Litepaper for a conceptual overview.) **Mitigations (not guarantees)** may include audits, testing, monitoring, and (where supported) operational controls such as pausing or restricting certain functions. **Audits and reviews do not guarantee safety**, and recovery of funds after an incident may be impossible or incomplete. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#blockchain-network-and-infrastructure-risk) Blockchain, Network, and Infrastructure Risk Fira runs on public blockchains and depends on their continued operation. Networks may experience congestion, reorgs, forks, downtime, censorship, or changes in operating rules. Such events can cause failed or delayed transactions, unexpected execution outcomes, inability to refinance or repay in time, and increased liquidation risk. Users bear the risk of adverse network conditions, including elevated transaction fees ("gas"). * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#third-party-dependency-risk-tokens-oracles-dexs-rpcs-bridges) Third-Party Dependency Risk (Tokens, Oracles, DEXs, RPCs, Bridges) Fira may depend on third-party systems and assets, including stablecoins (e.g., USDC), collateral tokens, oracles, DEX liquidity, RPC infrastructure, and potentially bridges (if deployed across networks). Third-party dependencies can fail, be compromised, change their rules, pause functionality, become insolvent, or restrict transfers (e.g., blacklisting/freezing), which can result in losses or disruptions to Fira users. Fira generally cannot control or guarantee the availability, correctness, or resilience of third-party systems. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#interest-rate-risk-fixed-maturity-and-floating-rate-markets) Interest Rate Risk (Fixed-Maturity and Floating-Rate Markets) Fira markets, both fixed-maturity ("fixed-rate") and floating-rate, are exposed to interest rate volatility. * In **fixed-maturity markets**, "fixed" borrowing costs are **implied by market pricing**, primarily through the relative price (discount) of **BT** versus its underlying asset (e.g., FW-USDC). Because BT pricing is market-driven, the implied fixed rate may change over time. Borrowers who settle or unwind **before maturity** may realize a different effective rate than expected at origination. * In **floating-rate markets**, borrowing rates typically depend on **utilization** (borrowed vs. supplied liquidity). Sudden shifts in supply or demand, such as large withdrawals or borrowing spikes, can cause utilization (and rates) to increase sharply, potentially leading to abrupt and sustained increases in borrowing costs. Mitigations such as liquidity concentration, parameterization, and curated liquidity management may reduce (not eliminate) extreme outcomes. **Rates can still move materially**, especially under stress. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#liquidity-and-exit-risk) Liquidity and Exit Risk Liquidity conditions can change rapidly. Users may be unable to enter, exit, repay, or unwind positions at reasonable prices or within expected timeframes. * In fixed-maturity markets, early settlement often requires accessing liquidity (e.g., exchanging cash for BT) and may be costly or impractical when liquidity is thin, leading to high slippage or unfavorable implied rates. * In floating-rate markets, lender withdrawals may be constrained if liquidity becomes highly utilized; withdrawals may depend on borrower repayments. * Liquidity providers may face additional constraints if any reserves are allocated elsewhere as part of protocol design. Liquidity risk may be amplified during volatility, depegs, network congestion, oracle disruptions, or when participants de-risk simultaneously. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#liquidation-risk-borrowers) Liquidation Risk (Borrowers) Borrowers must post collateral and maintain sufficient collateralization. If a borrower's risk metrics breach protocol-defined thresholds (e.g., LTV/LLTV), the position may become liquidatable. Liquidations may occur **rapidly and without notice**, especially during volatile markets or when network conditions prevent timely management of positions. Fira's fixed-maturity design includes maturity-based mechanics in which positions that are not repaid by maturity may be subject to liquidation, potentially resulting in forced execution at unfavorable times. Borrowers may lose some or all of their collateral, and liquidation costs, penalties, slippage, MEV, and transaction fees can materially worsen outcomes. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#bad-debt-risk-lenders) Bad Debt Risk (Lenders) Bad debt occurs when seized collateral cannot be liquidated for sufficient value to cover outstanding debt (net of execution costs). Bad debt may result in **losses for lenders** in affected markets and can reduce lender principal and/or realized yield. Bad debt risk is higher during extreme volatility, liquidity evaporation, oracle failures, or network congestion that prevents profitable or timely liquidations. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#collateral-and-asset-specific-risk) Collateral and Asset-Specific Risk Collateral assets may experience sharp price declines, liquidity collapse, depegs, or protocol/issuer failures. Certain assets may have centralization or administrative controls (e.g., blacklist/freeze/upgrade authorities), creating risks that are not present in fully permissionless assets. A collateral asset can "break" suddenly for idiosyncratic reasons (exploit, governance capture, regulatory action, redemption impairment), leaving insufficient time for orderly liquidation and increasing bad debt risk. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#stablecoin-and-wrapping-risk-e.g.-usdc-and-fw-usdc) Stablecoin and Wrapping Risk (e.g., USDC and FW-USDC) Fira may use a stablecoin unit (e.g., USDC) and may wrap it into an internal unit of account (e.g., FW-USDC). Stablecoins may lose their peg, experience redemption impairment, be frozen/blacklisted, or be impacted by issuer, banking, or regulatory risks. Wrapping introduces additional smart-contract and operational dependencies, and any failure in wrap/unwrap mechanisms may cause loss, delays, or inability to exit. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#amm-pricing-and-market-manipulation-risk) AMM Pricing and Market Manipulation Risk Fira's implied fixed rates rely on market pricing (e.g., BT/FW exchange dynamics) which may be affected by liquidity conditions and trading behavior. AMMs can be subject to slippage, price impact, and manipulation, particularly in thin liquidity conditions. Attackers may attempt to manipulate prices around critical moments (settlements, liquidations, large trades), potentially harming borrowers, lenders, and liquidity providers. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#coupon-token-and-yield-trading-risk-ct) Coupon Token and Yield-Trading Risk (CT) Fira may support yield-trading via coupon tokens ("CT"), which represent an economic claim on interest/coupon components. CT value may be highly sensitive to assumptions about rates, time to maturity, liquidity, and protocol behavior. CT markets may be thin, volatile, or illiquid, and users may be unable to buy or sell CT at expected prices. Any mechanisms that enable CT trading (including advanced transaction flows) may introduce additional technical and execution risks. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#rehypothecation-strategy-risk-reserve-allocation) Rehypothecation / Strategy Risk (Reserve Allocation) Fira may allocate ("rehypothecate") a portion of liquidity reserves into variable-rate strategies or vaults to enhance the economics of holding CT and/or improve capital efficiency. Rehypothecation introduces additional risks, including: * strategy or vault losses (smart-contract, market, or operational failures), * delayed liquidity return when users seek to exit, * dependency on third-party protocols or integrations, and * increased complexity and attack surface. Any returns from rehypothecation are **not guaranteed**, and rehypothecation may increase the likelihood of liquidity stress during adverse conditions. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#governance-and-parameter-change-risk) Governance and Parameter-Change Risk Protocol parameters (collateral eligibility, risk thresholds, caps, reserve allocation targets, fee parameters, etc.) may change through governance or authorized roles, where applicable. Changes may alter the risk profile of markets, affect liquidity, or trigger unintended consequences. Governance processes can be attacked, captured, or mismanaged, and administrative keys or role permissions can introduce additional risk. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#mev-and-transaction-execution-risk) MEV and Transaction Execution Risk On public blockchains, transactions can be front-run, sandwiched, or otherwise exploited (MEV). This can lead to worse execution prices, higher slippage, failed transactions, and increased costs, especially for swaps, liquidations, and large trades. Users may not be able to reliably predict execution outcomes at the time they submit transactions. * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#regulatory-legal-and-tax-risk) Regulatory, Legal, and Tax Risk The legal and regulatory treatment of DeFi and crypto-assets is evolving and may change rapidly. Fira may not be available in all jurisdictions, and users are responsible for compliance with applicable laws (including sanctions and restrictions). Users are also responsible for determining and meeting tax reporting and payment obligations arising from their activities (including swaps, interest/coupon income, and gains/losses). * * * ### [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#no-guarantee-risk-mitigation-is-not-assurance) No Guarantee; Risk Mitigation Is Not Assurance Fira may implement security and risk controls (e.g., audits, monitoring, parameter constraints, curated liquidity practices). **These measures reduce certain risks but do not eliminate them.** Users should assume that adverse events, including exploits, depegs, liquidity runs, and rapid market moves, can occur and may result in **complete loss**. **You should not use Fira unless you fully understand the risks and can bear the loss of all funds you supply, borrow, or otherwise expose to the protocol.** * * * [hashtag](https://docs.fira.money/security-and-risk/risk-disclaimers#general-disclaimer) General Disclaimer ---------------------------------------------------------------------------------------------------------------- By accessing Fira, you interact with a **non-custodial DeFi protocol** (smart contracts) enabling **variable-rate lending/borrowing** and **fixed-maturity "fixed-rate" borrowing** via Fira tokens. * **Risk of total loss:** bugs/exploits, user errors, cyberattacks, oracle or network failures, and market events may result in partial or total loss of funds. **On-chain transactions are irreversible.** * **Liquidation:** borrower positions may be liquidated if collateral value drops and **may be automatically liquidated at maturity** if not repaid. * **"Fixed rate" mechanics:** the cost is linked to the **BT/FW discount**; **early repayment** may change the effective cost (no guarantee of a "fixed rate" unless repaid at maturity). * Fira provides **no advice** (financial/legal/tax), offers **no yield guarantee**, and **does not custody** your funds. **Network (gas) fees** and/or third-party fees may apply. * You confirm you are **of legal age**, not subject to **sanctions**, not in a **restricted jurisdiction**, and you accept the documents below. * You confirm that you have read the documents relating to **Risks & Security and accept the consequences.** [PreviousSmart Contract Riskchevron-left](https://docs.fira.money/security-and-risk/risk-framework/smart-contract-risk) [NextTech Hubchevron-right](https://docs.fira.money/developers/developers) Last updated 1 day ago * [Risks and Security Considerations](https://docs.fira.money/security-and-risk/risk-disclaimers#risks-and-security-considerations) * [Important Notice](https://docs.fira.money/security-and-risk/risk-disclaimers#important-notice) * [Risk Summary (Non-Exhaustive)](https://docs.fira.money/security-and-risk/risk-disclaimers#risk-summary-non-exhaustive) * [Smart Contract and Technical Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#smart-contract-and-technical-risk) * [Blockchain, Network, and Infrastructure Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#blockchain-network-and-infrastructure-risk) * [Third-Party Dependency Risk (Tokens, Oracles, DEXs, RPCs, Bridges)](https://docs.fira.money/security-and-risk/risk-disclaimers#third-party-dependency-risk-tokens-oracles-dexs-rpcs-bridges) * [Interest Rate Risk (Fixed-Maturity and Floating-Rate Markets)](https://docs.fira.money/security-and-risk/risk-disclaimers#interest-rate-risk-fixed-maturity-and-floating-rate-markets) * [Liquidity and Exit Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#liquidity-and-exit-risk) * [Liquidation Risk (Borrowers)](https://docs.fira.money/security-and-risk/risk-disclaimers#liquidation-risk-borrowers) * [Bad Debt Risk (Lenders)](https://docs.fira.money/security-and-risk/risk-disclaimers#bad-debt-risk-lenders) * [Collateral and Asset-Specific Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#collateral-and-asset-specific-risk) * [Stablecoin and Wrapping Risk (e.g., USDC and FW-USDC)](https://docs.fira.money/security-and-risk/risk-disclaimers#stablecoin-and-wrapping-risk-e.g.-usdc-and-fw-usdc) * [AMM Pricing and Market Manipulation Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#amm-pricing-and-market-manipulation-risk) * [Coupon Token and Yield-Trading Risk (CT)](https://docs.fira.money/security-and-risk/risk-disclaimers#coupon-token-and-yield-trading-risk-ct) * [Rehypothecation / Strategy Risk (Reserve Allocation)](https://docs.fira.money/security-and-risk/risk-disclaimers#rehypothecation-strategy-risk-reserve-allocation) * [Governance and Parameter-Change Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#governance-and-parameter-change-risk) * [MEV and Transaction Execution Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#mev-and-transaction-execution-risk) * [Regulatory, Legal, and Tax Risk](https://docs.fira.money/security-and-risk/risk-disclaimers#regulatory-legal-and-tax-risk) * [No Guarantee; Risk Mitigation Is Not Assurance](https://docs.fira.money/security-and-risk/risk-disclaimers#no-guarantee-risk-mitigation-is-not-assurance) * [General Disclaimer](https://docs.fira.money/security-and-risk/risk-disclaimers#general-disclaimer) --- # Fira Market AMM | Fira Docs [hashtag](https://docs.fira.money/developers/features/fira-market-amm#overview) Overview --------------------------------------------------------------------------------------------- The Fira Market is a BT/FW liquidity pool with a pricing curve specifically designed for fixed-rate instruments. As expiry approaches, BT converges toward FW in value — the AMM's logit-based curve naturally handles this convergence. circle-info Each Fira Market is specific to a single BT and curve configuration (`scalarRoot`, `initialAnchor`, `lnFeeRateRoot`). Markets are deployed via the FiraMarketFactory using CREATE2 for deterministic addresses. [hashtag](https://docs.fira.money/developers/features/fira-market-amm#how-it-works) How it works ----------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/fira-market-amm#adding-liquidity) Adding liquidity Liquidity providers deposit BT and FW in the correct ratio and receive LP tokens. On the first deposit, `MINIMUM_LIQUIDITY` (1000 wei) is locked to `address(1)` to prevent the first-depositor rounding attack. Subsequent deposits mint LP proportional to the limiting token. Tokens must be transferred to the market before calling `mint` — the contract does not pull tokens. ### [hashtag](https://docs.fira.money/developers/features/fira-market-amm#removing-liquidity) Removing liquidity LP tokens are burned in exchange for proportional BT and FW. LP must be sent to the market before calling `burn`. This works both pre- and post-expiry. ### [hashtag](https://docs.fira.money/developers/features/fira-market-amm#swaps) Swaps The market supports two swap directions: * `**swapExactBtForFw**` — Sell BT for FW. Uses a flash-callback pattern: the market sends FW first, then verifies BT repayment. * `**swapFwForExactBt**` — Buy BT with FW. Sends BT out first, calls back, and checks FW repayment. Both swap functions are gated by `notExpired` — no swaps are allowed after the BT expiry date. ### [hashtag](https://docs.fira.money/developers/features/fira-market-amm#twap-oracle) TWAP Oracle Every state write records a new observation in a ring buffer (if the block timestamp differs from the last). The `observe(secondsAgos)` function returns cumulative `ln(impliedRate)` values for time-weighted average price calculations. Anyone can pre-allocate observation slots via `increaseObservationsCardinalityNext` to support longer TWAP windows. [hashtag](https://docs.fira.money/developers/features/fira-market-amm#key-features) Key features ----------------------------------------------------------------------------------------------------- * **Time-decaying pricing** — Logit curve ensures BT converges to FW value as expiry approaches * **Flash-callback swaps** — Tokens are sent before verification, enabling atomic multi-step operations * **Built-in TWAP oracle** — Ring buffer of implied rate observations for external price feeds * **Reserve fees** — A portion of swap fees goes to the protocol treasury * **Immutable markets** — Once deployed, market parameters cannot be changed (fee overrides are managed by the factory) [hashtag](https://docs.fira.money/developers/features/fira-market-amm#invariants) Invariants ------------------------------------------------------------------------------------------------- * Internal `totalBt` and `totalFw` are never affected by direct transfers — `skim()` sends excess to treasury * Exchange rate is always >= 1.0 (BT trades at a discount to FW) * Swaps and mints revert after expiry; burns work at any time [hashtag](https://docs.fira.money/developers/features/fira-market-amm#related-contracts) Related contracts --------------------------------------------------------------------------------------------------------------- * [`FiraMarket.sol`](https://docs.fira.money/developers/protocol-contracts/core/fira-market) — AMM contract details * [`FiraMarketFactory.sol`](https://docs.fira.money/developers/protocol-contracts/core/fira-market-factory) — Factory contract * [`MarketMathCore.sol`](https://docs.fira.money/developers/protocol-contracts/core/market-math-core) — Pricing math [PreviousFW (FiraWrapped)chevron-left](https://docs.fira.money/developers/features/fw-fira-wrapped) [NextRehypothecationchevron-right](https://docs.fira.money/developers/features/rehypothecation) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/fira-market-amm#overview) * [How it works](https://docs.fira.money/developers/features/fira-market-amm#how-it-works) * [Adding liquidity](https://docs.fira.money/developers/features/fira-market-amm#adding-liquidity) * [Removing liquidity](https://docs.fira.money/developers/features/fira-market-amm#removing-liquidity) * [Swaps](https://docs.fira.money/developers/features/fira-market-amm#swaps) * [TWAP Oracle](https://docs.fira.money/developers/features/fira-market-amm#twap-oracle) * [Key features](https://docs.fira.money/developers/features/fira-market-amm#key-features) * [Invariants](https://docs.fira.money/developers/features/fira-market-amm#invariants) * [Related contracts](https://docs.fira.money/developers/features/fira-market-amm#related-contracts) --- # Solvency Oracle | Fira Docs circle-info **Source:** `src/fira_bonding/oracles/FiraSolvencyOracle.sol` [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#overview) Overview -------------------------------------------------------------------------------------------------------------- The FiraSolvencyOracle provides collateral-to-loan-token pricing for fixed-rate lending markets. It sits at the top of a 3-layer oracle pipeline: Copy AaveToChainlinkAdapter → ChainlinkOracleV2 → FiraSolvencyOracle → FiraLendingMarket [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#oracle-pipeline) Oracle pipeline ---------------------------------------------------------------------------------------------------------------------------- Layer Purpose **AaveToChainlinkAdapter** Adapts Aave/Pendle price feeds to a Chainlink-compatible interface **ChainlinkOracleV2** Combines two Chainlink feeds to produce a collateral/USDC price **FiraSolvencyOracle** Adjusts the price for BT solvency and provides to lending market [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#deployed-instances) Deployed instances ---------------------------------------------------------------------------------------------------------------------------------- Market FiraSolvencyOracle PT-USDe/BT [`0xeB30b33A...`arrow-up-right](https://etherscan.io/address/0xeB30b33A1aC175e0305853636D0eF3898eb530f3) PT-sUSDe/BT [`0xB9bAA3D5...`arrow-up-right](https://etherscan.io/address/0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb) [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#related-pages) Related pages ------------------------------------------------------------------------------------------------------------------------ * [Contract Deploymentsarrow-up-right](https://github.com/Pi-2lavega/fira-gitbook-sync-final/blob/main/developers/smart-contracts/smart-contracts/contract-deployments.md) — Full oracle pipeline addresses [PreviousOracleschevron-left](https://docs.fira.money/developers/utility-contracts/oracles) [NextLP Oraclechevron-right](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#overview) * [Oracle pipeline](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#oracle-pipeline) * [Deployed instances](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#deployed-instances) * [Related pages](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle#related-pages) --- # LP Oracle | Fira Docs circle-info **Source:** `src/fira_bonding/oracles/LpOracleLib.sol` [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle#overview) Overview -------------------------------------------------------------------------------------------------------- LP token pricing is more complex than BT/CT because LP represents a share of a pool with two assets (BT + FW) in varying proportions. [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle#pricing-method) Pricing method -------------------------------------------------------------------------------------------------------------------- The library simulates a hypothetical rebalancing trade: 1. Compute the market's current `rateScalar` and `rateAnchor` 2. Compute `cParam = exp(rateScalar × (rateOracle - rateAnchor))` — where the pool "should" be according to the oracle 3. Calculate the hypothetical trade size to move the pool to the oracle-implied proportion 4. Sum total asset value after the trade: FW reserves (in asset terms) plus BT reserves, adjusted by post-trade rates 5. Divide by total LP supply The hypothetical trade rate is the average of the oracle TWAP rate and the last trade rate, dampening the impact of stale oracle data. ### [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle#post-expiry) Post-expiry LP pricing simplifies: 1 BT = 1 asset, so `LP value = (totalBt + fwToAsset(totalFw)) / totalLp`. [PreviousSolvency Oraclechevron-left](https://docs.fira.money/developers/utility-contracts/oracles/solvency-oracle) [NextBC Oraclechevron-right](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle#overview) * [Pricing method](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle#pricing-method) * [Post-expiry](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle#post-expiry) --- # ActionSimple | Fira Docs circle-info **Source:** `src/fira_bonding/router/ActionSimple.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-simple#overview) Overview ------------------------------------------------------------------------------------------------------------ A parallel set of swap and liquidity functions that use `MarketApproxLibOnchain` instead of the off-chain binary search approximation. These are called internally by the main action facets when `guessOffchain == 0` and no limit orders are present. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-simple#when-its-used) When it's used ----------------------------------------------------------------------------------------------------------------------- The main facets (ActionSwapBTV3, ActionSwapCTV3, etc.) check `canUseOnchainApproximation()` in `ActionDelegateBase`. If true, they delegate to `ActionSimple` via `address(this).delegatecall(...)`, which runs ActionSimple's code in the router's storage context. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-simple#functions) Functions -------------------------------------------------------------------------------------------------------------- * `swapExactFwForBtSimple` — FW → BT using on-chain closed-form approximation * `swapExactTokenForBtSimple` — Token → FW → BT * `swapExactTokenForCtSimple` / `swapExactCtForTokenSimple` — CT swaps * `addLiquiditySingleBtSimple` / `addLiquiditySingleFwSimple` — Single-sided LP * `addLiquiditySingleTokenSimple` / `addLiquiditySingleTokenKeepCtSimple` — Token-based LP [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-simple#trade-offs) Trade-offs ---------------------------------------------------------------------------------------------------------------- On-chain approximation provides a simpler code path with lower gas cost for straightforward operations, at the expense of slightly less precise swap amounts compared to the off-chain binary search method. [PreviousActionBorrowchevron-left](https://docs.fira.money/developers/protocol-contracts/router/action-borrow) [NextActionMiscchevron-right](https://docs.fira.money/developers/protocol-contracts/router/action-misc) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/protocol-contracts/router/action-simple#overview) * [When it's used](https://docs.fira.money/developers/protocol-contracts/router/action-simple#when-its-used) * [Functions](https://docs.fira.money/developers/protocol-contracts/router/action-simple#functions) * [Trade-offs](https://docs.fira.money/developers/protocol-contracts/router/action-simple#trade-offs) --- # Lending | Fira Docs [hashtag](https://docs.fira.money/developers/protocol-contracts/lending#overview) Overview ----------------------------------------------------------------------------------------------- Fira uses two lending market deployments: ### [hashtag](https://docs.fira.money/developers/protocol-contracts/lending#firalendingmarket-fixed-rate) FiraLendingMarket (Fixed-Rate) * **Loan token:** BT (Bond Token) * **Collateral:** Pendle PT tokens (PT-USDe, PT-sUSDe) * **Interest rate model:** None (`IRM = address(0)`) — the rate is implicit in the BT discount * **Supply:** Whitelist-gated to the LiquidityInjector only * **Oracle:** FiraSolvencyOracle (3-layer oracle pipeline) ### [hashtag](https://docs.fira.money/developers/protocol-contracts/lending#variablelendingmarket-variable-rate) VariableLendingMarket (Variable-Rate) * **Loan token:** USDC * **Collateral:** wstETH, cbBTC * **Interest rate model:** AdaptiveCurveIrm (adjusts based on utilization) * **Supply:** Permissionless via SisuVault (ERC-4626) * **Oracle:** Morpho wstETH/USDC, ChainlinkOracleV2 for cbBTC/USDC [hashtag](https://docs.fira.money/developers/protocol-contracts/lending#sisuvault) SisuVault ------------------------------------------------------------------------------------------------- The SisuVault is an ERC-4626 vault that aggregates USDC deposits and supplies them to variable-rate lending markets. It is managed by a curator and allocator (Markov Labs) who control market allocation. Vault shares (`mkUSDC`) represent proportional claims on the underlying USDC plus accrued interest. [hashtag](https://docs.fira.money/developers/protocol-contracts/lending#key-functions) Key functions --------------------------------------------------------------------------------------------------------- Function Description `supplyCollateral(params, amount, user, data)` Deposit collateral `borrow(params, assets, shares, user, receiver)` Borrow loan token `repay(params, assets, shares, onBehalf, data)` Repay debt `withdrawCollateral(params, amount, user, receiver)` Withdraw collateral `liquidate(params, borrower, seizedAssets)` Liquidate undercollateralized position `getUserPosition(params, user)` View full position details `accrueInterest(params)` Update interest state [hashtag](https://docs.fira.money/developers/protocol-contracts/lending#related-pages) Related pages --------------------------------------------------------------------------------------------------------- * [Fixed-Rate Lending (Feature)arrow-up-right](https://github.com/Pi-2lavega/fira-gitbook-sync-final/blob/main/developers/smart-contracts/overview/features/fixed-rate-lending.md) * [Variable-Rate Lending (Feature)arrow-up-right](https://github.com/Pi-2lavega/fira-gitbook-sync-final/blob/main/developers/smart-contracts/overview/features/variable-rate-lending.md) * [Contract Deploymentsarrow-up-right](https://github.com/Pi-2lavega/fira-gitbook-sync-final/blob/main/developers/smart-contracts/protocol-contracts/contract-deployments.md) [PreviousMarketMathCorechevron-left](https://docs.fira.money/developers/protocol-contracts/core/market-math-core) [NextRouterchevron-right](https://docs.fira.money/developers/protocol-contracts/router) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/protocol-contracts/lending#overview) * [FiraLendingMarket (Fixed-Rate)](https://docs.fira.money/developers/protocol-contracts/lending#firalendingmarket-fixed-rate) * [VariableLendingMarket (Variable-Rate)](https://docs.fira.money/developers/protocol-contracts/lending#variablelendingmarket-variable-rate) * [SisuVault](https://docs.fira.money/developers/protocol-contracts/lending#sisuvault) * [Key functions](https://docs.fira.money/developers/protocol-contracts/lending#key-functions) * [Related pages](https://docs.fira.money/developers/protocol-contracts/lending#related-pages) --- # Audits | Fira Docs For the complete list of audits, reports, and security review details, see the main audits page: [Auditschevron-right](https://docs.fira.money/security-and-risk/audits) [PreviousSecurity Designchevron-left](https://docs.fira.money/developers/security-and-audits/security-practices) [NextDeploymentchevron-right](https://docs.fira.money/developers/deployment) Last updated 1 day ago --- # BC Oracle | Fira Docs circle-info **Source:** `src/fira_bonding/oracles/BCOracleLib.sol`, `src/fira_bonding/oracles/BCLpOracle.sol` [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#bcoraclelib) BCOracleLib -------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#bt-pricing) BT pricing Pre-expiry, BT price is derived from the TWAP `ln(impliedRate)`: Copy btToAssetRate = 1 / exp(lnImpliedRate × timeToExpiry / YEAR) This is the present value of 1 unit of underlying, discounted at the TWAP implied rate. Post-expiry, BT is worth exactly 1 asset unit. ### [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#ct-pricing) CT pricing CT value is `1 - btToAssetRate`. Since BT + CT = 1 asset unit by construction, CT captures the remainder. ### [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#fw-solvency-adjustment) FW solvency adjustment If the FW exchange rate drops below the BC index, the FW wrapper is insolvent. In this case, BT and CT rates are scaled down by `fwIndex / bcIndex`, preventing the oracle from reporting prices that assume full solvency. ### [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#twap-calculation) TWAP calculation `getMarketLnImpliedRate(market, duration)` queries two cumulative observations, takes the difference, and divides by duration for a manipulation-resistant time-weighted average. [hashtag](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#bclporacle) BCLpOracle ------------------------------------------------------------------------------------------------------------ A convenience contract wrapping both `BCOracleLib` and `LpOracleLib` as external view functions. Deployed once per chain to save bytecode in contracts that need oracle prices. Provides `getOracleState(market, duration)` to check whether a market has enough observation cardinality for the requested TWAP window and whether the oldest observation is old enough. [PreviousLP Oraclechevron-left](https://docs.fira.money/developers/utility-contracts/oracles/lp-oracle) [NextLibrarieschevron-right](https://docs.fira.money/developers/utility-contracts/libraries) Last updated 1 day ago * [BCOracleLib](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#bcoraclelib) * [BT pricing](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#bt-pricing) * [CT pricing](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#ct-pricing) * [FW solvency adjustment](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#fw-solvency-adjustment) * [TWAP calculation](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#twap-calculation) * [BCLpOracle](https://docs.fira.money/developers/utility-contracts/oracles/bc-oracle#bclporacle) --- # Variable-Rate Lending | Fira Docs [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#overview) Overview --------------------------------------------------------------------------------------------------- Fira's variable-rate market operates alongside the fixed-rate system. Borrowers post collateral (wstETH, cbBTC) and borrow USDC at a variable rate that adjusts based on utilization. Lenders deposit USDC into the **SisuVault** (an ERC-4626 vault) to earn variable yield. circle-info FW tokens rehypothecate part of their underlying into the variable-rate market on the supply side. This means FW depositors indirectly earn variable-rate lending yield in addition to any other yield sources. [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#how-it-works) How it works ----------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#lending-supplying) Lending (supplying) Users deposit USDC into the SisuVault and receive vault shares (`mkUSDC`). The vault aggregates deposits and supplies them across lending markets. Yield accrues as borrowers pay interest, increasing the vault's share price over time. ### [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#borrowing) Borrowing Borrowers interact directly with the Variable Rate LendingMarket: 1. **Approve** collateral token to the lending market 2. **Supply collateral** via `supplyCollateral(marketParams, amount, user, "")` 3. **Borrow** via `borrow(marketParams, usdcToBorrow, 0, user, receiver)` Interest accrues continuously based on the `AdaptiveCurveIrm` interest rate model, which adjusts rates based on utilization. ### [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#repaying) Repaying Borrowers approve USDC to the lending market and call `repay(marketParams, assets, 0, user, "")`. The position's borrow balance is reduced accordingly. ### [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#supported-collateral) Supported collateral Collateral LTV LLTV Oracle wstETH 87% 89% Morpho wstETH/USDC cbBTC 88% 90% ChainlinkOracleV2 (BTC/USD + USDC/USD) [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#key-features) Key features ----------------------------------------------------------------------------------------------------------- * **Variable yield for lenders** — Earn yield proportional to vault share ownership * **Multiple collateral types** — wstETH and cbBTC supported * **Adaptive interest rates** — Rates adjust based on market utilization * **Permissionless** — No whitelist required for variable-rate markets * **ERC-4626 vault** — Standard vault interface for composability [hashtag](https://docs.fira.money/developers/features/variable-rate-lending#related-pages) Related pages ------------------------------------------------------------------------------------------------------------- * [Variable-Rate Lending (User Flow)](https://docs.fira.money/developers/user-flows/variable-rate-lending) * [Repay Variable-Rate Debt (User Flow)](https://docs.fira.money/developers/user-flows/repay-variable-rate) * [Lending Contracts](https://docs.fira.money/developers/protocol-contracts/lending) [PreviousFixed-Rate Lendingchevron-left](https://docs.fira.money/developers/features/fixed-rate-lending) [NextBond Token (BT)chevron-right](https://docs.fira.money/developers/features/bond-token-bt) Last updated 1 day ago * [Overview](https://docs.fira.money/developers/features/variable-rate-lending#overview) * [How it works](https://docs.fira.money/developers/features/variable-rate-lending#how-it-works) * [Lending (supplying)](https://docs.fira.money/developers/features/variable-rate-lending#lending-supplying) * [Borrowing](https://docs.fira.money/developers/features/variable-rate-lending#borrowing) * [Repaying](https://docs.fira.money/developers/features/variable-rate-lending#repaying) * [Supported collateral](https://docs.fira.money/developers/features/variable-rate-lending#supported-collateral) * [Key features](https://docs.fira.money/developers/features/variable-rate-lending#key-features) * [Related pages](https://docs.fira.money/developers/features/variable-rate-lending#related-pages) --- # FW Tokens | Fira Docs circle-info **Source:** `src/fira_bonding/StandardizedYield/FWBase.sol`, `src/fira_bonding/StandardizedYield/implementations/USDCFW.sol` [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#fwbase) FWBase ------------------------------------------------------------------------------------------ Abstract base that all FW tokens inherit. Extends `FiraERC20Permit`, `TokenHelper`, `BoringOwnableUpgradeable`, and `Pausable`. ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#deposit-flow) Deposit flow 1. Validate input token via `isValidTokenIn` 2. Transfer tokens in via `_transferIn` 3. Call `_deposit(tokenIn, amount)` — abstract, implemented by derived contracts 4. Mint FW shares to receiver 5. Check `minSharesOut` slippage guard ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#redeem-flow) Redeem flow 1. Validate output token via `isValidTokenOut` 2. Burn FW shares (or from `address(this)` if `burnFromInternalBalance`) 3. Call `_redeem(receiver, tokenOut, shares)` — abstract 4. Check `minTokenOut` slippage guard ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#pause-controls) Pause controls Three independent mechanisms: `depositsPaused`, `redemptionsPaused`, and global `pause()` (blocks all transfers). [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#usdcfw) USDCFW ------------------------------------------------------------------------------------------ The production FW implementation. Wraps USDC and earns yield by deploying a portion into an ERC-4626 vault. ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#state) State * `yieldToken` — USDC address (immutable) * `vault` — ERC-4626 vault (immutable) * `idleAssets` / `vaultShares` — Tracked explicitly to prevent donation-based manipulation ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#exchange-rate) Exchange rate Where `totalUnderlying = idleAssets + vault.convertToAssets(vaultShares)`. ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#deposit) Deposit USDC deposits are added to `idleAssets`. Vault share deposits are converted to equivalent USDC. First deposit mints 1:1. The market is seeded on deployment to prevent ERC-4626 inflation attacks. ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#redeem) Redeem Draws from idle USDC first, then from the vault if needed, minimizing gas costs. ### [hashtag](https://docs.fira.money/developers/token-contracts/fw-tokens#rehypothecation) Rehypothecation `triggerRehypothecation()` (permissionless) and `forceRehypothecation()` (owner-only) rebalance between idle and vault based on the RehypothecationModule parameters. [PreviousCoupon Tokenchevron-left](https://docs.fira.money/developers/token-contracts/coupon-token) [NextUtility Contractschevron-right](https://docs.fira.money/developers/utility-contracts) Last updated 1 day ago * [FWBase](https://docs.fira.money/developers/token-contracts/fw-tokens#fwbase) * [Deposit flow](https://docs.fira.money/developers/token-contracts/fw-tokens#deposit-flow) * [Redeem flow](https://docs.fira.money/developers/token-contracts/fw-tokens#redeem-flow) * [Pause controls](https://docs.fira.money/developers/token-contracts/fw-tokens#pause-controls) * [USDCFW](https://docs.fira.money/developers/token-contracts/fw-tokens#usdcfw) * [State](https://docs.fira.money/developers/token-contracts/fw-tokens#state) * [Exchange rate](https://docs.fira.money/developers/token-contracts/fw-tokens#exchange-rate) * [Deposit](https://docs.fira.money/developers/token-contracts/fw-tokens#deposit) * [Redeem](https://docs.fira.money/developers/token-contracts/fw-tokens#redeem) * [Rehypothecation](https://docs.fira.money/developers/token-contracts/fw-tokens#rehypothecation) Copy exchangeRate = totalUnderlying / totalSupply --- # ActionBorrow | Fira Docs circle-info **Source:** `src/fira_bonding/router/ActionBorrow.sol` [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#functions) Functions -------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#supplyandborrowsingletoken) `supplyAndBorrowSingleToken` Supply collateral → borrow BT → swap BT to FW → redeem FW to desired token. All in one transaction. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#borrowsingletoken) `borrowSingleToken` Same flow but assumes collateral is already supplied. ### [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#repay) `repay` Converts input token to BT and repays the lending market: * **Pre-expiry:** Input token → FW (mint) → BT (AMM swap) → repay. Refunds excess BT. * **Post-expiry:** Input token → FW (mint) → BT+CT (via `CT.mintBC`) → repay with BT. CT is minted but has zero value post-expiry. [hashtag](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#key-details) Key details ------------------------------------------------------------------------------------------------------------------ * The borrow position is owned by `msg.sender`, but the router is the token receiver — BT is held transiently and swapped immediately. * `tokensToRepay` must be ≤ current debt, otherwise reverts with `"AB: repay too much"`. * Requires the user to have authorized the router on the LendingMarket (`setAuthorization(router, true)`). [PreviousActionAddRemoveLiqchevron-left](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq) [NextActionSimplechevron-right](https://docs.fira.money/developers/protocol-contracts/router/action-simple) Last updated 1 day ago * [Functions](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#functions) * [supplyAndBorrowSingleToken](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#supplyandborrowsingletoken) * [borrowSingleToken](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#borrowsingletoken) * [repay](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#repay) * [Key details](https://docs.fira.money/developers/protocol-contracts/router/action-borrow#key-details) --- # Coupon Token | Fira Docs circle-info **Source:** `src/fira_bonding/core/YieldContracts/CouponToken.sol` [hashtag](https://docs.fira.money/developers/token-contracts/coupon-token#token-details) Token details ----------------------------------------------------------------------------------------------------------- Property Value Standard ERC-20 (FiraERC20) Symbol CT Decimals 6 Permit No [hashtag](https://docs.fira.money/developers/token-contracts/coupon-token#key-view-functions) Key view functions --------------------------------------------------------------------------------------------------------------------- Function Returns `bcIndexStored()` Last cached BC index `bcIndexCurrent()` Current BC index (may trigger update) `isExpired()` Whether BT/CT have expired `FW()` Associated FW token address `BT()` Associated BT token address `getPostExpiryData()` Snapshot data from first post-expiry interaction [hashtag](https://docs.fira.money/developers/token-contracts/coupon-token#interest-tracking) Interest tracking ------------------------------------------------------------------------------------------------------------------- Interest is distributed on every transfer via `_beforeTokenTransfer`. Users claim via `redeemDueInterestAndRewards`. The `interestFeeRate` is deducted at claim time. [hashtag](https://docs.fira.money/developers/token-contracts/coupon-token#related-pages) Related pages ----------------------------------------------------------------------------------------------------------- * [CouponToken (Protocol Contract)](https://docs.fira.money/developers/protocol-contracts/yield-contracts/coupon-token) * [Coupon Token (Feature)](https://docs.fira.money/developers/features/coupon-token-ct) [PreviousBond Tokenchevron-left](https://docs.fira.money/developers/token-contracts/bond-token) [NextFW Tokenschevron-right](https://docs.fira.money/developers/token-contracts/fw-tokens) Last updated 1 day ago * [Token details](https://docs.fira.money/developers/token-contracts/coupon-token#token-details) * [Key view functions](https://docs.fira.money/developers/token-contracts/coupon-token#key-view-functions) * [Interest tracking](https://docs.fira.money/developers/token-contracts/coupon-token#interest-tracking) * [Related pages](https://docs.fira.money/developers/token-contracts/coupon-token#related-pages) --- # Glossary | Fira Docs [hashtag](https://docs.fira.money/resources/glossary#protocol-specific-terms) Protocol-Specific Terms ---------------------------------------------------------------------------------------------------------- Term Definition **BT (Bond Token)** ERC-20 zero-coupon bond that redeems 1:1 into the underlying asset at expiry. Traded in the AMM, borrowed/lent in the lending market. **CT (Coupon Token)** ERC-20 token that tracks all interest/yield due on a given BT line. CT holders accrue interest/rewards from the underlying yield. **FW (FiraWrapped)** Yield-bearing wrapper for underlying assets. The base unit of account in Fira markets. Mintable and redeemable frictionlessly. [hashtag](https://docs.fira.money/resources/glossary#technical-terms) Technical Terms ------------------------------------------------------------------------------------------ Term Definition **LTV (Loan-to-Value)** Ratio of debt to collateral value. UZR uses 88% LTV. **LLTV (Liquidation LTV)** Threshold above which positions become eligible for liquidation. **IRM (Interest Rate Model)** Smart contract that determines borrowing rates. UZR uses a fixed rate IRM at 0.10% APR. **AMM (Automated Market Maker)** Decentralized exchange mechanism used for BT trading in Fira V1. **Maturity** The date at which a BT redeems at par (1:1 with underlying). **Par Value** The face value of a BT at maturity (1 underlying). **Discount** The difference between current BT price and par value. This discount represents the implied fixed rate. **Rehypothecation** Reuse of deposited liquidity in secondary markets (variable-rate vaults). **Health Factor** Metric indicating how close a position is to liquidation. [PreviousContracts & Addresseschevron-left](https://docs.fira.money/resources/contracts-addresses) [NextIntegrationschevron-right](https://docs.fira.money/resources/integrations) Last updated 1 day ago * [Protocol-Specific Terms](https://docs.fira.money/resources/glossary#protocol-specific-terms) * [Technical Terms](https://docs.fira.money/resources/glossary#technical-terms) --- # Math | Fira Docs circle-info **Source:** `src/fira_bonding/libraries/math/PMath.sol`, `src/fira_bonding/libraries/math/LogExpMath.sol` [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/math#pmath) PMath ----------------------------------------------------------------------------------------------- Core fixed-point math used throughout the protocol. Constants: `ONE = 1e18`, `IONE = int256(1e18)`. ### [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/math#key-operations) Key operations Function Description Rounding `mulDown(a, b)` `(a × b) / 1e18` Toward zero (conservative for user) `divDown(a, b)` `(a × 1e18) / b` Toward zero `rawDivUp(a, b)` `(a + b - 1) / b` Up (conservative for protocol) `abs(a)` Absolute value of int256 — `neg(a)` Negation (BT/FW flows are signed) — `subNoNeg(a, b)` `a - b`, reverts if negative — `sqrt(x)` Babylonian method integer square root — `Int()` / `Uint()` Safe int256 ↔ uint256 casting — `Int128()` / `Uint96()` Narrowing casts for storage packing — [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/math#logexpmath) LogExpMath --------------------------------------------------------------------------------------------------------- Ported from Balancer's math library. Implements `ln(x)` and `exp(x)` for signed 256-bit integers at 1e18 scale. ### [hashtag](https://docs.fira.money/developers/utility-contracts/libraries/math#usage-in-the-protocol) Usage in the protocol * `**exp(x)**` — Converts between implied rates and exchange rates: `exchangeRate = exp(lnImpliedRate × timeToExpiry / YEAR)` * `**ln(x)**` — After computing a post-trade exchange rate, converts back to log-space implied rate for storage and TWAP tracking Both functions use lookup tables and polynomial approximations. They revert on out-of-bounds inputs (e.g., `ln(0)` or overflow in `exp`). Precision is critical — rounding errors in `exp` compound over many trades and could allow arbitrage. [PreviousLibrarieschevron-left](https://docs.fira.money/developers/utility-contracts/libraries) [NextHelperschevron-right](https://docs.fira.money/developers/utility-contracts/libraries/helpers) Last updated 1 day ago * [PMath](https://docs.fira.money/developers/utility-contracts/libraries/math#pmath) * [Key operations](https://docs.fira.money/developers/utility-contracts/libraries/math#key-operations) * [LogExpMath](https://docs.fira.money/developers/utility-contracts/libraries/math#logexpmath) * [Usage in the protocol](https://docs.fira.money/developers/utility-contracts/libraries/math#usage-in-the-protocol) --- # Repay Fixed Rate | Fira Docs **Key references**: `ActionBorrow.repay`. [hashtag](https://docs.fira.money/developers/user-flows/repay-fixed-rate#details) Details ---------------------------------------------------------------------------------------------- * **Goal**: Repay debt using an input token; router converts to BT as needed. * **Preconditions**: * Existing borrow: else `"AB: no borrow"`. * `tokensToRepay` must be ≤ current debt: else `"AB: repay too much"`. * Input token approval to router. * **Expiry handling**: * **Pre-expiry**: Input token → FW (mint) → BT (AMM swap via FiraMarket). Repay, refund excess BT. * **Post-expiry**: Input token → FW (mint to CT contract) → `CT.mintBC` produces BT + CT. Only BT is used for repayment. CT is minted but NOT burned — it stays in the router with zero economic value. [hashtag](https://docs.fira.money/developers/user-flows/repay-fixed-rate#views-and-events) Views and events ---------------------------------------------------------------------------------------------------------------- **Views** * Lending: `getUserPosition` (pre/post), `position(id, user)`. * Market: `isExpired()`. * FW: `previewDeposit`, `bcIndexStored()` for estimation on expired paths. **Events** * Lending: `EventsLib.Repay` (assets, shares), possibly `EventsLib.AccrueInterest`. * Router/Misc: `MintFwFromToken`, `MintBcFromFw` when conversions occur. [PreviousBorrow Fixed Ratechevron-left](https://docs.fira.money/developers/user-flows/borrow-fixed-rate) [NextVariable Rate Lendingchevron-right](https://docs.fira.money/developers/user-flows/variable-rate-lending) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/repay-fixed-rate#details) * [Views and events](https://docs.fira.money/developers/user-flows/repay-fixed-rate#views-and-events) --- # Events & Indexing | Fira Docs The Fira incentive system computes weekly time-weighted average (TWAP) exposures across **8 role buckets**. Positions are piecewise-constant, updated on relevant on-chain events. This section documents the event-to-role mapping and reward share formulas. circle-info Positions are piecewise-constant between events. The indexer must track each event to maintain an accurate TWAP of user exposure per role bucket over each epoch. [hashtag](https://docs.fira.money/developers/events-and-indexing#role-buckets) Role buckets ------------------------------------------------------------------------------------------------ Bucket Full name Market **BFR** Borrow Fixed Rate Fixed Rate **BT** Held BT Fixed Rate **CT** Coupon Token holders Fixed Rate **LP** Liquidity Providers Fixed Rate **VRB** Variable Rate Borrow Variable Rate **VRL** Variable Rate Lend Variable Rate **USLC** USL Collateral USL Migrator **USLL** USL Loan USL Migrator [hashtag](https://docs.fira.money/developers/events-and-indexing#source-contracts) Source contracts -------------------------------------------------------------------------------------------------------- Contract Events defined in Emitted by **LendingMarket** `lib/fira-lending-market/src/libraries/EventsLib.sol` `LendingMarket.sol` **BondToken** ERC20 events via FiraERC20 `BondToken.sol` **CouponToken** Custom + ERC20 events `CouponToken.sol` **FiraMarket** `src/interfaces/IPMarket.sol` `FiraMarket.sol` **SisuVault** ERC4626 Deposit/Withdraw `SisuVault.sol` [hashtag](https://docs.fira.money/developers/events-and-indexing#pages) Pages ---------------------------------------------------------------------------------- * [Event Table](https://docs.fira.money/developers/events-and-indexing/event-table) — Corrected event-to-role mapping with issue analysis * [Reward Measurement](https://docs.fira.money/developers/events-and-indexing/reward-measurement) — Per-role reward share formulas and function calls [PreviousPre/Post Expiry Exitschevron-left](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits) [NextEvent Tablechevron-right](https://docs.fira.money/developers/events-and-indexing/event-table) Last updated 1 day ago * [Role buckets](https://docs.fira.money/developers/events-and-indexing#role-buckets) * [Source contracts](https://docs.fira.money/developers/events-and-indexing#source-contracts) * [Pages](https://docs.fira.money/developers/events-and-indexing#pages) --- # Interfaces | Fira Docs All interfaces live in `src/interfaces/`. They are the canonical reference for integrators. [hashtag](https://docs.fira.money/developers/integrations/interfaces#fw-fira-wrapped) FW (Fira Wrapped) ------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ifirawrappedstandardized) IFiraWrappedStandardized The yield-bearing wrapper token (e.g. USDCFW wrapping USDC into a SisuVault). Copy function deposit(address receiver, address tokenIn, uint256 amountTokenToDeposit, uint256 minSharesOut) external payable returns (uint256 amountSharesOut); function redeem(address receiver, uint256 amountSharesToRedeem, address tokenOut, uint256 minTokenOut, bool burnFromInternalBalance) external returns (uint256 amountTokenOut); function exchangeRate() external view returns (uint256); function previewDeposit(address tokenIn, uint256 amountTokenToDeposit) external view returns (uint256); function previewRedeem(address tokenOut, uint256 amountSharesToRedeem) external view returns (uint256); function claimRewards(address user) external returns (uint256[] memory); function accruedRewards(address user) external view returns (uint256[] memory); function getTokensIn() external view returns (address[] memory); function getTokensOut() external view returns (address[] memory); function assetInfo() external view returns (AssetType, address, uint8); [hashtag](https://docs.fira.money/developers/integrations/interfaces#market) Market ---------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipmarket) IPMarket The BT/FW AMM pool. Also an ERC-20 (LP token). ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipmarketfactoryv3) IPMarketFactoryV3 ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipmarketswapcallback) IPMarketSwapCallback Implement this if calling FiraMarket swap functions directly (not via Router). [hashtag](https://docs.fira.money/developers/integrations/interfaces#yield-contracts) Yield contracts ---------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ibondtoken) IBondToken Fixed-rate principal token. ERC-20 with restricted mint/burn. ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ibctoken-coupontoken) IBCToken (CouponToken) Floating-yield token with interest accrual. Inherits `IPInterestManagerCT`. ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ibccontractfactory) IBCContractFactory [hashtag](https://docs.fira.money/developers/integrations/interfaces#router-facets) Router facets ------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipactionswapbtv3) IPActionSwapBTV3 ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipactionswapctv3) IPActionSwapCTV3 ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipactionaddremoveliqv3) IPActionAddRemoveLiqV3 ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipactionmiscv3) IPActionMiscV3 ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipactionborrow) IPActionBorrow ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ipactionsimple) IPActionSimple On-chain approximation variants that avoid the need for off-chain `ApproxParams` computation. [hashtag](https://docs.fira.money/developers/integrations/interfaces#shared-types-ipallactiontypev3) Shared types (IPAllActionTypeV3) ------------------------------------------------------------------------------------------------------------------------------------------ [hashtag](https://docs.fira.money/developers/integrations/interfaces#utility-interfaces) Utility interfaces ---------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#irehypothecationmodule) IRehypothecationModule ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#iliquidityinjector) ILiquidityInjector ### [hashtag](https://docs.fira.money/developers/integrations/interfaces#ioracle) IOracle [PreviousIntegrationschevron-left](https://docs.fira.money/developers/integrations) [NextSecurity Practiceschevron-right](https://docs.fira.money/developers/security-and-audits) Last updated 1 day ago * [FW (Fira Wrapped)](https://docs.fira.money/developers/integrations/interfaces#fw-fira-wrapped) * [IFiraWrappedStandardized](https://docs.fira.money/developers/integrations/interfaces#ifirawrappedstandardized) * [Market](https://docs.fira.money/developers/integrations/interfaces#market) * [IPMarket](https://docs.fira.money/developers/integrations/interfaces#ipmarket) * [IPMarketFactoryV3](https://docs.fira.money/developers/integrations/interfaces#ipmarketfactoryv3) * [IPMarketSwapCallback](https://docs.fira.money/developers/integrations/interfaces#ipmarketswapcallback) * [Yield contracts](https://docs.fira.money/developers/integrations/interfaces#yield-contracts) * [IBondToken](https://docs.fira.money/developers/integrations/interfaces#ibondtoken) * [IBCToken (CouponToken)](https://docs.fira.money/developers/integrations/interfaces#ibctoken-coupontoken) * [IBCContractFactory](https://docs.fira.money/developers/integrations/interfaces#ibccontractfactory) * [Router facets](https://docs.fira.money/developers/integrations/interfaces#router-facets) * [IPActionSwapBTV3](https://docs.fira.money/developers/integrations/interfaces#ipactionswapbtv3) * [IPActionSwapCTV3](https://docs.fira.money/developers/integrations/interfaces#ipactionswapctv3) * [IPActionAddRemoveLiqV3](https://docs.fira.money/developers/integrations/interfaces#ipactionaddremoveliqv3) * [IPActionMiscV3](https://docs.fira.money/developers/integrations/interfaces#ipactionmiscv3) * [IPActionBorrow](https://docs.fira.money/developers/integrations/interfaces#ipactionborrow) * [IPActionSimple](https://docs.fira.money/developers/integrations/interfaces#ipactionsimple) * [Shared types (IPAllActionTypeV3)](https://docs.fira.money/developers/integrations/interfaces#shared-types-ipallactiontypev3) * [Utility interfaces](https://docs.fira.money/developers/integrations/interfaces#utility-interfaces) * [IRehypothecationModule](https://docs.fira.money/developers/integrations/interfaces#irehypothecationmodule) * [ILiquidityInjector](https://docs.fira.money/developers/integrations/interfaces#iliquidityinjector) * [IOracle](https://docs.fira.money/developers/integrations/interfaces#ioracle) Copy function mint(address receiver, uint256 netFwDesired, uint256 netBtDesired) external returns (uint256 netLpOut, uint256 netFwUsed, uint256 netBtUsed); function burn(address receiverFw, address receiverBt, uint256 netLpToBurn) external returns (uint256 netFwOut, uint256 netBtOut); function swapExactBtForFw(address receiver, uint256 exactBtIn, bytes calldata data) external returns (uint256 netFwOut, uint256 netFwFee); function swapFwForExactBt(address receiver, uint256 exactBtOut, bytes calldata data) external returns (uint256 netFwIn, uint256 netFwFee); function readState(address router) external view returns (MarketState memory); function readTokens() external view returns (IFiraWrappedStandardized, IBondToken, IBCToken); function observe(uint32[] memory secondsAgos) external view returns (uint216[] memory); function isExpired() external view returns (bool); function expiry() external view returns (uint256); Copy function createNewMarket(address BT, int256 scalarRoot, int256 initialAnchor, uint80 lnFeeRateRoot) external returns (address market); function isValidMarket(address market) external view returns (bool); Copy function swapCallback(int256 btToAccount, int256 fwToAccount, bytes calldata data) external; Copy function mint(address to, uint256 amount) external; function burn(address from, uint256 amount) external; Copy function mintBC(address receiverBT, address receiverCT) external returns (uint256 amountBCOut); function redeemBC(address receiver) external returns (uint256 amountFwOut); function redeemDueInterestAndRewards(address user, bool redeemInterest, bool redeemRewards) external returns (uint256 interestOut, uint256[] memory rewardsOut); function bcIndexCurrent() external returns (uint256); function bcIndexStored() external view returns (uint256); function isExpired() external view returns (bool); function expiry() external view returns (uint256); function FW() external view returns (address); function BT() external view returns (address); Copy function createBCContract(address fw, uint256 expiry) external returns (address BT, address CT); Copy function swapExactBtForFw(address receiver, address market, uint256 exactBtIn, TokenOutput calldata output, LimitOrderData calldata limit) external returns (uint256 netFwOut, uint256 netFwFee); function swapExactFwForBt(address receiver, address market, uint256 exactFwIn, ApproxParams calldata guessBtOut, TokenInput calldata input, LimitOrderData calldata limit) external returns (uint256 netBtOut, uint256 netFwFee); Copy function swapExactFwForCt(address receiver, address market, uint256 exactFwIn, TokenInput calldata input, ApproxParams calldata guessCTOut, LimitOrderData calldata limit) external returns (uint256 netCtOut, uint256 netFwFee); function swapExactCtForFw(address receiver, address market, uint256 exactCtIn, TokenOutput calldata output, LimitOrderData calldata limit) external returns (uint256 netFwOut, uint256 netFwFee); Copy function addLiquidityDualFwAndBt(address receiver, address market, TokenInput calldata input, uint256 netBtDesired, uint256 minLpOut) external returns (uint256 netLpOut, uint256 netFwUsed, uint256 netBtUsed); function removeLiquidityDualFwAndBt(address receiver, address market, uint256 netLpToRemove, TokenOutput calldata output, uint256 minBtOut) external returns (uint256 netFwOut, uint256 netBtOut); Copy function mintBcFromFw(address receiver, address CT, uint256 netFwIn, uint256 minBcOut) external returns (uint256 netBcOut); function redeemBcToFw(address receiver, address CT, uint256 netBcIn, TokenOutput calldata output) external returns (uint256 netFwOut); function redeemDueInterestAndRewards(address receiver, address[] calldata CTs, address[] calldata FWs, address[] calldata markets) external; function exitPreExpiry(address receiver, address market, uint256 netBtIn, uint256 netCtIn, uint256 netLpIn, TokenOutput calldata output) external returns (uint256 totalFwOut); function exitPostExpiry(address receiver, address market, uint256 netBtIn, uint256 netCtIn, uint256 netLpIn, TokenOutput calldata output) external returns (uint256 totalFwOut); function multicall(bytes[] calldata data) external payable returns (bytes[] memory results); Copy function borrow(address market, MarketParams calldata marketParams, uint256 amount, uint256 shares, address onBehalf, address receiver) external returns (uint256 assetsOut, uint256 sharesOut); function repay(address market, MarketParams calldata marketParams, uint256 amount, uint256 shares, address onBehalf, bytes calldata data) external returns (uint256 assetsRepaid, uint256 sharesRepaid); Copy function swapExactFwForBtSimple(address receiver, address market, uint256 exactFwIn, uint256 minBtOut) external returns (uint256 netBtOut, uint256 netFwFee); function addLiquiditySingleFwSimple(address receiver, address market, uint256 netFwIn, uint256 minLpOut) external returns (uint256 netLpOut); Copy struct TokenInput { address tokenIn; uint256 netTokenIn; address tokenMintFw; address firaSwap; SwapData swapData; } struct TokenOutput { address tokenOut; uint256 minTokenOut; address tokenRedeemFw; address firaSwap; SwapData swapData; } struct ApproxParams { uint256 guessMin; uint256 guessMax; uint256 guessOffchain; uint256 maxIteration; uint256 eps; } struct SwapData { SwapType swapType; address extRouter; bytes extCalldata; bool needScale; } Copy function rebalance() external; function phiMin() external view returns (uint256); function phiMax() external view returns (uint256); function phiTarget() external view returns (uint256); Copy function injectLiquidity(uint256 btAmount, uint256 fwAmount) external returns (uint256 lpOut); function withdrawLiquidity(uint256 lpAmount) external returns (uint256 fwOut, uint256 btOut); Copy function price() external view returns (uint256); --- # Provide Liquidity | Fira Docs **Key references**: `ActionAddRemoveLiqV3.addLiquidityDualTokenAndBt`, `addLiquidityDualFwAndBt`, `addLiquiditySingleToken`, `addLiquiditySingleBt`, `addLiquiditySingleFw`, `addLiquiditySingleTokenKeepCt`, `addLiquiditySingleFwKeepCt`. [hashtag](https://docs.fira.money/developers/user-flows/provide-liquidity#details) Details ----------------------------------------------------------------------------------------------- * **Goal**: Provide liquidity to BT/FW market and receive LP. * **Preconditions**: * Approvals for all inputs (`tokenIn`, `BT`, and/or `FW`). * Set `minLpOut` and approximation params when single-sided. * **Additional entrypoints**: * `addLiquiditySingleBt` — BT only, swaps portion to FW. * `addLiquiditySingleFw` — FW only, swaps portion to BT. * `addLiquiditySingleFwKeepCt` — FW + keep CT variant. [hashtag](https://docs.fira.money/developers/user-flows/provide-liquidity#views-and-events) Views and events ----------------------------------------------------------------------------------------------------------------- **Views** * Market: `readTokens()`, `isExpired()`, `readState(router)`, `observe(secondsAgos)`. * LP: `balanceOf(user)`, `totalSupply()` (derive proportional share of `totalBt/totalFw`). **Events** * Router: `AddLiquidityDualTokenAndBt`, `AddLiquidityDualFwAndBt`, `AddLiquiditySingleBt`, `AddLiquiditySingleFw`, `AddLiquiditySingleToken`, `AddLiquiditySingleTokenKeepCt`, `AddLiquiditySingleFwKeepCt`. * Market: `Mint`, `Swap` (during balancing), `UpdateImpliedRate`. [hashtag](https://docs.fira.money/developers/user-flows/provide-liquidity#reward-share-lp) Reward share (LP) ----------------------------------------------------------------------------------------------------------------- * Suggested formula: `lpBalance / totalSupply()` over the epoch (TWAP). * Functions to call: * `IERC20(market).balanceOf(user)`, `IERC20(market).totalSupply()` * `FiraMarket.readState(router)` → `totalBt`, `totalFw`, `totalLp` (for underlying attribution) [PreviousTrade BT/CTchevron-left](https://docs.fira.money/developers/user-flows/trade-bt-ct) [NextRemove Liquiditychevron-right](https://docs.fira.money/developers/user-flows/remove-liquidity) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/provide-liquidity#details) * [Views and events](https://docs.fira.money/developers/user-flows/provide-liquidity#views-and-events) * [Reward share (LP)](https://docs.fira.money/developers/user-flows/provide-liquidity#reward-share-lp) --- # Security Practices | Fira Docs [hashtag](https://docs.fira.money/developers/security-and-audits#security-approach) Security approach ---------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/security-and-audits#multi-layered-security-strategy) Multi-layered security strategy 1. **Secure development practices** — All Fira contracts follow battle-tested Solidity patterns from OpenZeppelin, with strict adherence to the checks-effects-interactions pattern and consistent use of custom errors for gas-efficient revert reasons. 2. **Access control** — Sensitive state changes are gated behind `BoringOwnableUpgradeable` ownership checks at the contract level and role-based function selectors in the Router facet architecture. 3. **Reentrancy protection** — State-mutating entry points in FWBase, FiraMarket, CouponToken, and the LiquidityInjector are protected by OpenZeppelin's `ReentrancyGuard` (`nonReentrant` modifier). 4. **Pause controls** — FW token contracts implement `whenNotPaused` guards, allowing the owner to freeze deposits and redemptions during incidents without requiring a contract upgrade. 5. **Upgrade mechanisms** — Contracts use the `Initializable` pattern with upgradeable proxies, enabling hotfixes while preserving storage layout. The Router uses a diamond-like facet system with versioned selectors. 6. **Oracle safety** — A multi-layer oracle pipeline (Aave → Chainlink adapter → Fira solvency oracle → BC/LP oracle) provides defence-in-depth for price feeds, with staleness checks at every layer. 7. **Continuous monitoring** — On-chain events are designed for real-time indexing, supporting anomaly detection across all role buckets (see [Events & Indexing](https://docs.fira.money/developers/events-and-indexing) ). circle-info For detailed information on each security mechanism and how it applies across the contract stack, see [Security Design](https://docs.fira.money/developers/security-and-audits/security-practices) . [hashtag](https://docs.fira.money/developers/security-and-audits#pages) Pages ---------------------------------------------------------------------------------- * [Security Design](https://docs.fira.money/developers/security-and-audits/security-practices) — In-depth coverage of access control, reentrancy, pause, and upgrade patterns * [Audits](https://docs.fira.money/developers/security-and-audits/audits) — Chronological overview of completed security audits [PreviousInterfaceschevron-left](https://docs.fira.money/developers/integrations/interfaces) [NextSecurity Designchevron-right](https://docs.fira.money/developers/security-and-audits/security-practices) Last updated 1 day ago * [Security approach](https://docs.fira.money/developers/security-and-audits#security-approach) * [Multi-layered security strategy](https://docs.fira.money/developers/security-and-audits#multi-layered-security-strategy) * [Pages](https://docs.fira.money/developers/security-and-audits#pages) --- # Integrations | Fira Docs This section is aimed at developers who want to build on top of the Fira Protocol — whether you are a DeFi aggregator routing swaps, a lending protocol using Fira yield tokens as collateral, or a front-end displaying position data. circle-info All Fira contracts are deployed on Ethereum mainnet. See [Deployment](https://docs.fira.money/developers/deployment) for addresses. [hashtag](https://docs.fira.money/developers/integrations#quick-start) Quick start --------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/integrations#id-1.-identify-the-entry-point) 1\. Identify the entry point Goal Contract Key interface Wrap USDC into yield-bearing FW USDCFW `IFiraWrappedStandardized` Swap BT ↔ FW FiraMarket `IPMarket` Mint / redeem BT + CT CouponToken `IBCToken` Add / remove LP liquidity FiraRouter `IPActionAddRemoveLiqV3` Borrow at fixed rate FiraRouter `IPActionBorrow` Read market state & oracle FiraMarket `IPMarket.readState`, `observe` ### [hashtag](https://docs.fira.money/developers/integrations#id-2.-approve-tokens) 2\. Approve tokens All Fira entry points pull tokens from `msg.sender` via `transferFrom`. Before calling any state-mutating function, approve the target contract (or the Router) for the relevant ERC-20. ### [hashtag](https://docs.fira.money/developers/integrations#id-3.-use-the-router-or-call-contracts-directly) 3\. Use the Router or call contracts directly The **FiraRouter** aggregates most user-facing actions behind a single address with typed facet interfaces. Integrators can: * Call **Router facets** for complex multi-step flows (swap + borrow, add liquidity with single-sided input, etc.). * Call **individual contracts** (FiraMarket, USDCFW, CouponToken) directly for simpler interactions. circle-exclamation If calling FiraMarket swap functions directly (not via Router), you must implement the `IPMarketSwapCallback` interface. The market uses a flash-callback pattern: it transfers tokens to you first, then calls your callback to pull payment. [hashtag](https://docs.fira.money/developers/integrations#common-patterns) Common patterns ----------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/integrations#reading-prices-and-rates) Reading prices and rates ### [hashtag](https://docs.fira.money/developers/integrations#previewing-deposits-and-redeems) Previewing deposits and redeems ### [hashtag](https://docs.fira.money/developers/integrations#checking-expiry) Checking expiry Post-expiry, BT redeems 1:1 for FW and CT stops accruing. LP positions should be exited before expiry for optimal value. [hashtag](https://docs.fira.money/developers/integrations#amount-conventions) Amount conventions ----------------------------------------------------------------------------------------------------- * **FW, BT, CT amounts** — Native token decimals (matching the underlying, e.g. 6 for USDC-backed FW). * **Exchange rates, indices, proportions** — 1e18 fixed-point. * **Signed integers (**`**int256**`**)** — Used for swap amounts. Negative = paying, positive = receiving. * **Slippage** — Always the caller's responsibility via `minOut` / `minSharesOut` parameters. The contracts will revert if the minimum is not met. [hashtag](https://docs.fira.money/developers/integrations#pages) Pages --------------------------------------------------------------------------- * [Interfaces & API Surface](https://docs.fira.money/developers/integrations/interfaces) — Complete reference of all Fira interfaces, grouped by module [PreviousReward Measurementchevron-left](https://docs.fira.money/developers/events-and-indexing/reward-measurement) [NextInterfaceschevron-right](https://docs.fira.money/developers/integrations/interfaces) Last updated 1 day ago * [Quick start](https://docs.fira.money/developers/integrations#quick-start) * [1\. Identify the entry point](https://docs.fira.money/developers/integrations#id-1.-identify-the-entry-point) * [2\. Approve tokens](https://docs.fira.money/developers/integrations#id-2.-approve-tokens) * [3\. Use the Router or call contracts directly](https://docs.fira.money/developers/integrations#id-3.-use-the-router-or-call-contracts-directly) * [Common patterns](https://docs.fira.money/developers/integrations#common-patterns) * [Reading prices and rates](https://docs.fira.money/developers/integrations#reading-prices-and-rates) * [Previewing deposits and redeems](https://docs.fira.money/developers/integrations#previewing-deposits-and-redeems) * [Checking expiry](https://docs.fira.money/developers/integrations#checking-expiry) * [Amount conventions](https://docs.fira.money/developers/integrations#amount-conventions) * [Pages](https://docs.fira.money/developers/integrations#pages) Copy // Current FW exchange rate (1e18 scale) uint256 rate = IFiraWrappedStandardized(fw).exchangeRate(); // Market state including implied rate, reserves, TWAP MarketState memory state = IPMarket(market).readState(router); // BC Index (yield accrual factor for CT) uint256 bcIndex = IBCToken(ct).bcIndexCurrent(); // TWAP observations (array of secondsAgo offsets) uint32[] memory secs = new uint32[](2); secs[0] = 1800; // 30 min ago secs[1] = 0; // now uint216[] memory cumRates = IPMarket(market).observe(secs); Copy // How many FW shares for a given USDC deposit uint256 fwOut = IFiraWrappedStandardized(fw).previewDeposit(usdc, amount); // How much USDC for redeeming a given amount of FW uint256 usdcOut = IFiraWrappedStandardized(fw).previewRedeem(usdc, fwAmount); Copy bool expired = IPMarket(market).isExpired(); uint256 expiryTs = IPMarket(market).expiry(); --- # Glossary | Fira Docs [hashtag](https://docs.fira.money/developers/glossary#protocol-tokens) Protocol tokens ------------------------------------------------------------------------------------------- Term Definition **FW (Fira Wrapped)** An ERC-20 yield-bearing wrapper token. FW wraps an underlying asset (e.g. USDC) through a SisuVault and appreciates over time as yield accrues. The canonical implementation is USDCFW. **BT (Bond Token)** A fixed-rate principal token. Each BT is redeemable 1:1 for FW at expiry. Before expiry, BT trades at a discount on the FiraMarket AMM — the discount determines the implied fixed rate. **CT (Coupon Token)** A floating-yield token. CT holders receive the yield generated by the underlying FW between now and expiry. CT accrues interest continuously via the BC Index. BT and CT are always minted and burned in equal pairs. **LP Token** The ERC-20 token representing a liquidity provider's share of a FiraMarket BT/FW pool. **mkUSDC** The SisuVault share token (Markov USDC Prime). Represents a pro-rata claim on the vault's total USDC assets. [hashtag](https://docs.fira.money/developers/glossary#core-concepts) Core concepts --------------------------------------------------------------------------------------- Term Definition **BC Index** The yield accrual factor for CT. It tracks the cumulative exchange rate growth of the underlying FW since the CT was created. `bcIndexCurrent()` returns the live value; `bcIndexStored()` returns the last cached value. **Exchange rate** The ratio of underlying assets to FW shares. Monotonically non-decreasing. `exchangeRate() = totalAssets / totalFwSupply`, scaled to 1e18. **Expiry** The UNIX timestamp at which BT becomes redeemable 1:1 for FW and CT stops accruing yield. All BT, CT, and FiraMarket pools share the same expiry within a market set. **Implied rate** The annualised fixed rate implied by the BT/FW price on the AMM. Derived from the logit pricing curve. A lower BT price implies a higher fixed rate. **TWAP (Time-Weighted Average Price)** A manipulation-resistant price average computed from on-chain oracle observations. FiraMarket stores cumulative `lnImpliedRate` observations that can be queried via `observe()`. [hashtag](https://docs.fira.money/developers/glossary#architecture) Architecture ------------------------------------------------------------------------------------- Term Definition **FiraRouter / FiraRouterV4** The main entry point for users. A diamond-like proxy that delegates calls to specialised facets (swap, liquidity, borrow, misc). **Facet** A standalone contract containing a subset of the Router's logic. The Router dispatches to facets based on function selector mappings. **FiraMarket** The BT/FW AMM pool. Uses a time-decaying logit pricing curve. Also serves as the LP token contract. **SisuVault** An ERC-4626 vault that aggregates USDC across variable-rate lending markets and other yield sources. FW deposits are routed into the vault. **YieldContractFactory** Deploys BT/CT pairs for a given FW token and expiry. Controls minting privileges and fee/treasury configuration. **FiraMarketFactory** Deploys FiraMarket AMM pools and validates market addresses. **LiquidityInjector (LI)** Bootstraps fixed-rate markets by minting unbacked BT and pairing it with FW to provide initial AMM liquidity. The sole whitelisted BT supplier to FiraLendingMarket. **RehypothecationModule** Manages the split between idle reserves in FW and deployed capital in the SisuVault. Maintains the reserve ratio within `[phiMin, phiMax]` by triggering `rebalance()`. [hashtag](https://docs.fira.money/developers/glossary#lending) Lending --------------------------------------------------------------------------- Term Definition **Fixed-rate lending** Borrowing where BT is the loan token. The borrower supplies Pendle PT tokens as collateral, borrows BT, swaps BT for FW, and redeems FW for USDC. The discount at which BT was acquired determines the effective fixed rate. **Variable-rate lending** Borrowing USDC from the SisuVault at a floating rate set by the AdaptiveCurveIrm. Collateral types include wstETH and cbBTC. **LTV (Loan-to-Value)** The maximum ratio of borrowed value to collateral value. Exceeding LTV prevents new borrows. **LLTV (Liquidation LTV)** The threshold at which a position becomes eligible for liquidation. Always slightly above LTV. **MarketParams** A struct identifying a lending market: `(loanToken, collateralToken, oracle, irm, lltv)`. The market ID is the keccak256 hash of this struct. **AdaptiveCurveIrm** The interest rate model for variable-rate markets. Adjusts rates based on utilisation using a sigmoid curve. **Maturity Grace Period** A window after BT expiry during which fixed-rate borrowers can repay without liquidation (24 hours). [hashtag](https://docs.fira.money/developers/glossary#oracle) Oracle ------------------------------------------------------------------------- Term Definition **AaveToChainlinkAdapter** Wraps an Aave V3 oracle price feed to expose the Chainlink `AggregatorV3Interface`, enabling reuse in the Fira oracle pipeline. **ChainlinkOracleV2** Consumes one or two Chainlink feeds, applies staleness checks and optional L2 sequencer-down checks, and returns a normalised price. **FiraSolvencyOracle** Validates solvency ratios for fixed-rate markets. Sits between ChainlinkOracleV2 and the LendingMarket. **BCLpOracle** Computes fair prices for BC (BT+CT) and LP tokens using FiraMarket spot and TWAP data. [hashtag](https://docs.fira.money/developers/glossary#math-and-utilities) Math & utilities ----------------------------------------------------------------------------------------------- Term Definition **PMath** Fira's fixed-point math library. Operates on 1e18-scaled `uint256` values for multiplication, division, and comparison. **LogExpMath** Provides `ln()` and `exp()` functions for 1e18-scaled integers. Used by the logit pricing curve in the AMM. **MarketMathCore** Core AMM math library implementing the time-decaying logit curve, swap calculations, and implied rate derivation. **scalarRoot** A market parameter controlling the steepness of the logit pricing curve. Higher values produce a flatter curve (tighter spread). **initialAnchor** The initial anchor point for the logit curve, representing the implied exchange rate at market creation. **lnFeeRateRoot** The natural log of the base swap fee rate. Applied to the FW side of every swap. [hashtag](https://docs.fira.money/developers/glossary#events-and-indexing) Events & indexing ------------------------------------------------------------------------------------------------- Term Definition **Role bucket** One of 8 categories in the Fira incentive system: BFR, BT, CT, LP, VRB, VRL, USLC, USLL. Rewards are computed per bucket. **Epoch** A time window (typically one week) over which TWAP exposures are measured for reward distribution. **Piecewise-constant position** A position value that remains constant between on-chain events. The indexer reconstructs the TWAP by integrating these constant segments over the epoch. [hashtag](https://docs.fira.money/developers/glossary#standards) Standards ------------------------------------------------------------------------------- Term Definition **ERC-20** The standard fungible token interface. All Fira tokens (FW, BT, CT, LP) implement ERC-20. **ERC-4626** The tokenized vault standard. SisuVault implements ERC-4626, providing `deposit`, `withdraw`, `convertToAssets`, and `convertToShares`. **EIP-170** The 24 KB contract size limit. Fira uses library extraction and split-code deployment to stay within this limit. **Diamond pattern** A proxy architecture (EIP-2535) where a single proxy delegates to multiple implementation contracts (facets). FiraRouter uses a simplified variant. [PreviousDeploymentchevron-left](https://docs.fira.money/developers/deployment) [NextWhitepaperchevron-right](https://docs.fira.money/resources/whitepaper) Last updated 1 day ago * [Protocol tokens](https://docs.fira.money/developers/glossary#protocol-tokens) * [Core concepts](https://docs.fira.money/developers/glossary#core-concepts) * [Architecture](https://docs.fira.money/developers/glossary#architecture) * [Lending](https://docs.fira.money/developers/glossary#lending) * [Oracle](https://docs.fira.money/developers/glossary#oracle) * [Math & utilities](https://docs.fira.money/developers/glossary#math-and-utilities) * [Events & indexing](https://docs.fira.money/developers/glossary#events-and-indexing) * [Standards](https://docs.fira.money/developers/glossary#standards) --- # Whitepaper | Fira Docs The whitepaper is a full detailed explanation of the methodology, mechanics and motivation behind the protocol. file-pdf 339KB [Fira Whitepaper.pdf](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-d8af9899ef32ba31367a3323fb41ad17b0df4fca%2FFira%20Whitepaper.pdf?alt=media) PDF downloadDownload[arrow-up-right-from-squareOpen](https://3843788673-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyxyZTdJaHRBrumzCYheB%2Fuploads%2Fgit-blob-d8af9899ef32ba31367a3323fb41ad17b0df4fca%2FFira%20Whitepaper.pdf?alt=media) [PreviousGlossarychevron-left](https://docs.fira.money/developers/glossary) [NextContracts & Addresseschevron-right](https://docs.fira.money/resources/contracts-addresses) Last updated 1 day ago --- # Repay Variable Rate | Fira Docs [hashtag](https://docs.fira.money/developers/user-flows/repay-variable-rate#details) Details ------------------------------------------------------------------------------------------------- * **Goal**: Repay outstanding variable-rate USDC debt. * **Preconditions**: USDC approval to LendingMarket. [hashtag](https://docs.fira.money/developers/user-flows/repay-variable-rate#function-call) Function call ------------------------------------------------------------------------------------------------------------- Copy repay(marketParamsUSDC, assets, shares, onBehalf, data) * For asset-based repay: set `assets = usdcToRepay`, `shares = 0`, `onBehalf = user`, `data = ""` * To repay max via shares: set `shares` to the user's borrow shares and `assets = 0` [hashtag](https://docs.fira.money/developers/user-flows/repay-variable-rate#views-and-events) Views and events ------------------------------------------------------------------------------------------------------------------- **Views** * `LendingMarket.getUserPosition(marketParamsUSDC, user)` (pre/post) → `borrowAssets` * `LendingMarket.market(idUSDC)` → `totalBorrowAssets` (consider `accrueInterest(marketParamsUSDC)` before reading) * `LendingMarket.position(idUSDC, user)` (optional) **Events** * `EventsLib.Repay` (assets, shares) * `EventsLib.AccrueInterest` (optional, if triggered) [PreviousVariable Rate Lendingchevron-left](https://docs.fira.money/developers/user-flows/variable-rate-lending) [NextTrade BT/CTchevron-right](https://docs.fira.money/developers/user-flows/trade-bt-ct) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/repay-variable-rate#details) * [Function call](https://docs.fira.money/developers/user-flows/repay-variable-rate#function-call) * [Views and events](https://docs.fira.money/developers/user-flows/repay-variable-rate#views-and-events) --- # Remove Liquidity | Fira Docs **Key references**: `FiraMarket.burn`. [hashtag](https://docs.fira.money/developers/user-flows/remove-liquidity#details) Details ---------------------------------------------------------------------------------------------- * **Goal**: Burn LP to withdraw proportional FW and BT. * **Preconditions**: Transfer LP to market before calling `burn`; decide receivers for FW/BT. * **Notes**: Router provides additional remove methods: * `removeLiquidityDualFwAndBt` / `removeLiquidityDualTokenAndBt` * `removeLiquiditySingleBt` / `removeLiquiditySingleFw` / `removeLiquiditySingleToken` * Single-FW removal post-expiry: BT is sent to CT contract and redeemed via `CT.redeemBC`. [hashtag](https://docs.fira.money/developers/user-flows/remove-liquidity#views-and-events) Views and events ---------------------------------------------------------------------------------------------------------------- **Views** * Market: `readTokens()`, `isExpired()`. **Events** * Market: `Burn(receiverFw, receiverBt, netLpToBurn, netFwOut, netBtOut)`. [PreviousProvide Liquiditychevron-left](https://docs.fira.money/developers/user-flows/provide-liquidity) [NextFW Deposit & Redeemchevron-right](https://docs.fira.money/developers/user-flows/fw-deposit-redeem) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/remove-liquidity#details) * [Views and events](https://docs.fira.money/developers/user-flows/remove-liquidity#views-and-events) --- # Router | Fira Docs The router is the single entry point for all user-facing protocol operations. It uses a diamond-like proxy pattern where each function selector maps to an action facet contract via `delegatecall`. circle-info Since all facets share storage via `delegatecall`, `RouterStorage` uses ERC-7201 storage namespacing to avoid collisions. [hashtag](https://docs.fira.money/developers/protocol-contracts/router#firarouterv4) FiraRouterV4 ------------------------------------------------------------------------------------------------------ Extends OpenZeppelin's `Proxy` and overrides `_implementation()` to look up `CoreStorage.selectorToFacet[msg.sig]`. If no facet is registered, it reverts with `INVALID_SELECTOR`. The constructor hard-wires the `setSelectorToFacets` and `selectorToFacet` selectors to the `ActionStorageV4` facet, allowing the owner to configure all other mappings post-deployment. [hashtag](https://docs.fira.money/developers/protocol-contracts/router#facet-contracts) Facet contracts ------------------------------------------------------------------------------------------------------------ * [ActionBorrow](https://docs.fira.money/developers/protocol-contracts/router/action-borrow) — Fixed-rate borrow and repay * [ActionSwapBT](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt) — BT swap operations * [ActionSwapCT](https://docs.fira.money/developers/protocol-contracts/router/action-swap-ct) — Synthesized CT swaps * [ActionAddRemoveLiq](https://docs.fira.money/developers/protocol-contracts/router/action-add-remove-liq) — Liquidity operations * [ActionMisc](https://docs.fira.money/developers/protocol-contracts/router/action-misc) — FW/BC minting, exits, multicall * [ActionSimple](https://docs.fira.money/developers/protocol-contracts/router/action-simple) — Gas-optimized on-chain approximation [hashtag](https://docs.fira.money/developers/protocol-contracts/router#shared-base-contracts) Shared base contracts ------------------------------------------------------------------------------------------------------------------------ All facets inherit from `ActionBase`, which provides: * FW mint/redeem orchestration * BT/CT swap orchestration with limit order support * Flash-callback encoding/decoding via `CallbackHelper` * Delegation to `ActionSimple` when on-chain approximation suffices [PreviousLendingchevron-left](https://docs.fira.money/developers/protocol-contracts/lending) [NextActionSwapBTchevron-right](https://docs.fira.money/developers/protocol-contracts/router/action-swap-bt) Last updated 1 day ago * [FiraRouterV4](https://docs.fira.money/developers/protocol-contracts/router#firarouterv4) * [Facet contracts](https://docs.fira.money/developers/protocol-contracts/router#facet-contracts) * [Shared base contracts](https://docs.fira.money/developers/protocol-contracts/router#shared-base-contracts) --- # Integrations | Fira Docs [hashtag](https://docs.fira.money/resources/integrations#analytics-and-dashboards) Analytics and Dashboards ---------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/resources/integrations#defillama) DeFiLlama Fira is listed on DeFiLlama for TVL tracking and protocol analytics. ### [hashtag](https://docs.fira.money/resources/integrations#dune-dashboard) Dune Dashboard Steady Labs maintains a dedicated Dune Analytics dashboard for Fira metrics and on-chain data: * **Dune Dashboard**: [https://dune.com/usual\_team/firaarrow-up-right](https://dune.com/usual_team/fira) [hashtag](https://docs.fira.money/resources/integrations#protocol-integrations) Protocol Integrations ---------------------------------------------------------------------------------------------------------- _This section will be expanded as additional DeFi integrations are established._ [PreviousGlossarychevron-left](https://docs.fira.money/resources/glossary) [NextTerms of Usechevron-right](https://docs.fira.money/legal/terms-of-use) Last updated 1 day ago * [Analytics and Dashboards](https://docs.fira.money/resources/integrations#analytics-and-dashboards) * [DeFiLlama](https://docs.fira.money/resources/integrations#defillama) * [Dune Dashboard](https://docs.fira.money/resources/integrations#dune-dashboard) * [Protocol Integrations](https://docs.fira.money/resources/integrations#protocol-integrations) --- # User Flows | Fira Docs These pages document the end-to-end transaction flows for each user-facing operation in the Fira protocol. Each flow includes a Mermaid sequence diagram, preconditions, relevant view functions, emitted events, and reward share formulas where applicable. circle-info All user operations go through the **FiraRouterV4** (except variable-rate lending, which interacts with the LendingMarket directly). Users must approve the relevant tokens to the router before calling. [hashtag](https://docs.fira.money/developers/user-flows#common-parameter-structs) Common parameter structs --------------------------------------------------------------------------------------------------------------- Struct Fields `MarketParams` `loanToken`, `collateralToken`, `oracle`, `irm`, `ltv`, `lltv`, `whitelist` `TokenInput` `tokenIn`, `netTokenIn`, `tokenMintFw`, `firaSwap`, `swapData` `TokenOutput` `tokenOut`, `minTokenOut`, `tokenRedeemFw`, `firaSwap`, `swapData` `LimitOrderData` Pricing limits for BT/FW market swap (interface compat, not used in current version) [hashtag](https://docs.fira.money/developers/user-flows#flows) Flows ------------------------------------------------------------------------- * [Borrow at Fixed Rate](https://docs.fira.money/developers/user-flows/borrow-fixed-rate) * [Repay Fixed-Rate Debt](https://docs.fira.money/developers/user-flows/repay-fixed-rate) * [Variable-Rate Lending](https://docs.fira.money/developers/user-flows/variable-rate-lending) * [Repay Variable-Rate Debt](https://docs.fira.money/developers/user-flows/repay-variable-rate) * [FW Deposit & Redeem](https://docs.fira.money/developers/user-flows/fw-deposit-redeem) * [Provide Liquidity](https://docs.fira.money/developers/user-flows/provide-liquidity) * [Remove Liquidity](https://docs.fira.money/developers/user-flows/remove-liquidity) * [Trade BT & CT](https://docs.fira.money/developers/user-flows/trade-bt-ct) * [Pre/Post-Expiry Exits](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits) [PreviousContract Deploymentschevron-left](https://docs.fira.money/developers/contract-deployments) [NextBorrow Fixed Ratechevron-right](https://docs.fira.money/developers/user-flows/borrow-fixed-rate) Last updated 1 day ago * [Common parameter structs](https://docs.fira.money/developers/user-flows#common-parameter-structs) * [Flows](https://docs.fira.money/developers/user-flows#flows) --- # FW Deposit & Redeem | Fira Docs **Key references**: `FWBase.deposit`, `FWBase.redeem` (and `FWBaseUpg` variants). [hashtag](https://docs.fira.money/developers/user-flows/fw-deposit-redeem#details) Details ----------------------------------------------------------------------------------------------- * **Goal**: Earn yield via FW shares; redeem later for base tokens. * **Preconditions**: * `isValidTokenIn(tokenIn)` and `isValidTokenOut(tokenOut)` must be true for the chosen FW. * Approve `tokenIn` to FW; set `minSharesOut` to guard slippage. * **Notes**: * Exchange rate increases from underlying yield; shares track proportional claim. * FW rehypothecates liquidity; see specific implementation (e.g., `USDCFW`). [hashtag](https://docs.fira.money/developers/user-flows/fw-deposit-redeem#views-and-events) Views and events ----------------------------------------------------------------------------------------------------------------- **Views** * FW: `balanceOf(user)`, `totalSupply()`, `exchangeRate()`, `previewDeposit(tokenIn, amount)`, `previewRedeem(tokenOut, shares)`, `accruedRewards(user)`. **Events** * FW: `Deposit`, `Redeem`, `ClaimRewards`. [PreviousRemove Liquiditychevron-left](https://docs.fira.money/developers/user-flows/remove-liquidity) [NextPre/Post Expiry Exitschevron-right](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/fw-deposit-redeem#details) * [Views and events](https://docs.fira.money/developers/user-flows/fw-deposit-redeem#views-and-events) --- # Contracts & Addresses | Fira Docs ### [hashtag](https://docs.fira.money/resources/contracts-addresses#ethereum-mainnet-deployments) Ethereum Mainnet Deployments All smart contracts are deployed on **Ethereum mainnet** with verified source code. Contract ownership is assigned to designated multisig addresses for operational security. * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#core-protocol-addresses) Core Protocol Addresses --------------------------------------------------------------------------------------------------------------------- Role Address Deployer `0x7Da82CBD315923d75dbb2C62F099392705FF97f9` Treasury / Fee Recipient `0x97fD565B913b439Ff16774Da152B1f71F05A82F1` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#core-contracts) Core Contracts --------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/resources/contracts-addresses#lending-markets) Lending Markets Contract Address Variable LendingMarket `0xc8Db629192a96D6840e88a8451F17655880A2e4D` Fixed FiraLendingMarket `0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e` AdaptiveCurveIRM `0x73C288826347af3718e6F09c2A24AaFDA77684cD` * * * ### [hashtag](https://docs.fira.money/resources/contracts-addresses#router) Router Contract Address FiraRouterV4 `0xFF615E63aAF2d1B1EE4AdFD34a5840747185d8A0` ActionStorage `0x0386685eA7d37c61dDb8F2e2E8c45f6a81d4A3C8` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#vaults) Vaults ----------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/resources/contracts-addresses#markov-usdc-prime) Markov USDC Prime Field Value Vault `0x50791a5cA041b9D6Dd03e64E3Fa0e34a376759AC` Vault Factory `0xe77E0f97A864558e5513209323e4169FcEAC6981` Name Markov USDC Prime Symbol mkUSDC Allocator `0x4E700A14868620a9Bba0669721F1945c410c7571` Curator `0xc02B0D1ca7B986E63cf1599F9c32e8A96c2D4Cff` Fee Recipient `0x97fD565B913b439Ff16774Da152B1f71F05A82F1` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#token-contracts) Token Contracts ----------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/resources/contracts-addresses#wrapped-collateral-token) Wrapped Collateral Token Field Value Token `0x62F5366C9E21A95326C461a098a408e034e017b3` Name Fira Wrapped USDC Symbol FW-USDC Rehypothecation Module `0xad332515d9c82438BBa0e9FAA9486B52A33a7Ac8` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#factories) Factories ----------------------------------------------------------------------------------------- Factory Address YieldContractFactory `0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be` FiraMarketFactory `0xBF1EfC2199ae9EE1B6f5060a45D4440157E49744` ChainlinkOracleV2Factory `0x7783fF7bE856C7A82bC5497Fb3CC8F7E8802D8dC` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#modules) Modules ------------------------------------------------------------------------------------- Module Address RehypothecationModule `0xad332515d9c82438BBa0e9FAA9486B52A33a7Ac8` LiquidityInjector `0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#oracles) Oracles ------------------------------------------------------------------------------------- Oracle Address cbBTC / USDC `0x698253A24CC4926090f841B38D31d6342A00a82C` PT-USDe / BT `0x2ED527087B740530562754EFCd608290eCCdBe2e` PT-sUSDe / BT `0xD6f5D9102007A737D9EDE6543262516d5c2fc8f8` BCLpOracle `0xfEAAEC9124FB007d7c44Ed704A08d24b264de921` * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#fixed-rate-markets) Fixed Rate Markets ----------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/resources/contracts-addresses#may-7-expiry) May 7 Expiry #### [hashtag](https://docs.fira.money/resources/contracts-addresses#core-tokens) Core Tokens Token Address BT `0x57FFbb88f0c69283531a751BE6FF0741348371bA` CT `0x93635d34fAd5A9fA7065a645691100b2E23C93cd` FiraMarket (AMM) `0xde00b5edb255078dd42ee94fd97f473d1c9c055d` * * * ### [hashtag](https://docs.fira.money/resources/contracts-addresses#pt-usde-bt-market) PT-USDe / BT Market **Market ID** Parameter Value Loan Token `0x57FFbb88f0c69283531a751BE6FF0741348371bA` Collateral Token `0xaebf0bb9f57e89260d57f31af34eb58657d96ce0` Oracle `0xeB30b33A1aC175e0305853636D0eF3898eb530f3` LTV 89% LLTV 90% Liquidation Incentive 3.1% * * * ### [hashtag](https://docs.fira.money/resources/contracts-addresses#pt-susde-bt-market) PT-sUSDe / BT Market **Market ID** Parameter Value Loan Token `0x57FFbb88f0c69283531a751BE6FF0741348371bA` Collateral Token `0x3de0ff76e8b528c092d47b9dac775931cef80f49` Oracle `0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb` LTV 89% LLTV 90% Liquidation Incentive 3.1% * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#variable-rate-markets) Variable Rate Markets ----------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/resources/contracts-addresses#wsteth-usdc) wstETH / USDC **Market ID** Parameter Value LendingMarket `0xc8Db629192a96D6840e88a8451F17655880A2e4D` Loan Token `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` Collateral Token `0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0` Oracle `0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2` IRM `0x73C288826347af3718e6F09c2A24AaFDA77684cD` LTV 87% LLTV 89% * * * ### [hashtag](https://docs.fira.money/resources/contracts-addresses#cbbtc-usdc) cbBTC / USDC **Market ID** Parameter Value LendingMarket `0xc8Db629192a96D6840e88a8451F17655880A2e4D` Loan Token `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` Collateral Token `0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf` Oracle `0x698253A24CC4926090f841B38D31d6342A00a82C` IRM `0x73C288826347af3718e6F09c2A24AaFDA77684cD` LTV 88% LLTV 90% * * * [hashtag](https://docs.fira.money/resources/contracts-addresses#market-id-verification) Market ID Verification ------------------------------------------------------------------------------------------------------------------- Market IDs are computed deterministically using: Users can reproduce this calculation using **Foundry (chisel)** or other Solidity tooling to verify market identifiers. [PreviousWhitepaperchevron-left](https://docs.fira.money/resources/whitepaper) [NextGlossarychevron-right](https://docs.fira.money/resources/glossary) Last updated 1 day ago * [Ethereum Mainnet Deployments](https://docs.fira.money/resources/contracts-addresses#ethereum-mainnet-deployments) * [Core Protocol Addresses](https://docs.fira.money/resources/contracts-addresses#core-protocol-addresses) * [Core Contracts](https://docs.fira.money/resources/contracts-addresses#core-contracts) * [Lending Markets](https://docs.fira.money/resources/contracts-addresses#lending-markets) * [Router](https://docs.fira.money/resources/contracts-addresses#router) * [Vaults](https://docs.fira.money/resources/contracts-addresses#vaults) * [Markov USDC Prime](https://docs.fira.money/resources/contracts-addresses#markov-usdc-prime) * [Token Contracts](https://docs.fira.money/resources/contracts-addresses#token-contracts) * [Wrapped Collateral Token](https://docs.fira.money/resources/contracts-addresses#wrapped-collateral-token) * [Factories](https://docs.fira.money/resources/contracts-addresses#factories) * [Modules](https://docs.fira.money/resources/contracts-addresses#modules) * [Oracles](https://docs.fira.money/resources/contracts-addresses#oracles) * [Fixed Rate Markets](https://docs.fira.money/resources/contracts-addresses#fixed-rate-markets) * [May 7 Expiry](https://docs.fira.money/resources/contracts-addresses#may-7-expiry) * [PT-USDe / BT Market](https://docs.fira.money/resources/contracts-addresses#pt-usde-bt-market) * [PT-sUSDe / BT Market](https://docs.fira.money/resources/contracts-addresses#pt-susde-bt-market) * [Variable Rate Markets](https://docs.fira.money/resources/contracts-addresses#variable-rate-markets) * [wstETH / USDC](https://docs.fira.money/resources/contracts-addresses#wsteth-usdc) * [cbBTC / USDC](https://docs.fira.money/resources/contracts-addresses#cbbtc-usdc) * [Market ID Verification](https://docs.fira.money/resources/contracts-addresses#market-id-verification) Copy 0xC48C055110D1692EDA1D45975BD80C75EE5E4D0AB6A5B6FFB949F2252C1B7791 Copy 0xCA309C3ECE0FA3341779D8319F28BD9E08D3E08889E8AC58B4AC9001FBE458F3 Copy 0xb3152ac00687cc9502b78ab452956f85cc89ac210deefda5dbff09f7f167b544 Copy 0x39d3bdd30bf4bcf4a4d3547f2484abe1e30a2dcd41ed83788b40e2720357ab76 Copy bytes32 id = keccak256( abi.encode( loanToken, collateralToken, oracle, irm, ltv, lltv, whitelist )); --- # Trade BT/CT | Fira Docs **Key references**: `IPActionMiscV3.mintBcFromToken`, `mintBcFromFw`, `redeemBcToToken`, `redeemBcToFw`. [hashtag](https://docs.fira.money/developers/user-flows/trade-bt-ct#details) Details ----------------------------------------------------------------------------------------- * **Goal**: Split FW into BT + CT and later unwind back to base token. * **Preconditions**: * Approvals for `tokenIn` to Router. * Set `minBcOut` / `minTokenOut` thresholds. * **Minting**: `mintBcFromToken` / `mintBcFromFw` — always produces equal BT + CT, both pre- and post-expiry. Post-expiry uses frozen `postExpiry.firstBCIndex` for the conversion rate. * **Redemption pre-expiry**: Both BT and CT must be provided. `CT.redeemBC()` burns both and returns FW. No AMM swap involved. * **Redemption post-expiry**: Only BT is required. `CT.redeemBC()` burns BT only; CT is NOT burned. FW returned at the current `bcIndex`, and any post-expiry yield accrual goes to the treasury. [hashtag](https://docs.fira.money/developers/user-flows/trade-bt-ct#views-and-events) Views and events ----------------------------------------------------------------------------------------------------------- **Views** * CT (`IBCToken`): `bcIndexStored()`, `bcIndexCurrent()`; `FW()`, `BT()`; `isExpired()`, `balanceOf(user)`. * BT (`IBondToken`): `balanceOf(user)`, `FW()`, `CT()`, `expiry()`, `isExpired()`. * FW: `previewDeposit`, `previewRedeem`. **Events** * Router: `MintBcFromToken`, `MintBcFromFw`, `RedeemBcToToken`, `RedeemBcToFw`. * CT: `Mint`, `Burn`, `RedeemInterest`. [hashtag](https://docs.fira.money/developers/user-flows/trade-bt-ct#reward-share-ct) Reward share (CT) ----------------------------------------------------------------------------------------------------------- * Suggested formula: `userCt / totalCt` over the epoch (TWAP). * Functions to call: * `IBCToken(CT).balanceOf(user)`, `IERC20(CT).totalSupply()` * Exclude expired CT. Post-expiry CT is minted but never burned, inflating `totalSupply()` — consider filtering by excluding known router/contract addresses. [hashtag](https://docs.fira.money/developers/user-flows/trade-bt-ct#reward-share-bt) Reward share (BT) ----------------------------------------------------------------------------------------------------------- * Suggested formula: `userBt / totalBt` where: * `userBt = IBondToken(BT).balanceOf(user) - getUserPosition(marketParamsBT, user).borrowAssets` * `totalBt = IERC20(BT).totalSupply() - IBondToken(BT).balanceOf(market) - IBondToken(BT).balanceOf(lendingMarket)` * Over the epoch (TWAP). [PreviousRepay Variable Ratechevron-left](https://docs.fira.money/developers/user-flows/repay-variable-rate) [NextProvide Liquiditychevron-right](https://docs.fira.money/developers/user-flows/provide-liquidity) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/trade-bt-ct#details) * [Views and events](https://docs.fira.money/developers/user-flows/trade-bt-ct#views-and-events) * [Reward share (CT)](https://docs.fira.money/developers/user-flows/trade-bt-ct#reward-share-ct) * [Reward share (BT)](https://docs.fira.money/developers/user-flows/trade-bt-ct#reward-share-bt) --- # Event Table | Fira Docs [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#fixed-rate-market) Fixed Rate Market ---------------------------------------------------------------------------------------------------------------------- Role Event Contract Purpose BFR Borrow LendingMarket Position increase BFR Repay LendingMarket Position decrease BFR Liquidate LendingMarket Forced position closure BFR Swap FiraMarket BFR qualification check BT Transfer BondToken All balance changes (mint, burn, transfer) BT Borrow LendingMarket For "subtract borrowed" rule BT Repay LendingMarket For "subtract borrowed" adjustment CT Transfer CouponToken (ERC20) All balance changes (mint, burn, transfer) CT RedeemInterest CouponToken Interest redemption LP Mint FiraMarket LP creation LP Burn FiraMarket LP destruction LP Transfer FiraMarket LP token transfers [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#variable-rate-market) Variable Rate Market ---------------------------------------------------------------------------------------------------------------------------- Role Event Contract Purpose VRB Borrow LendingMarket Position increase VRB Repay LendingMarket Position decrease VRB AccrueInterest LendingMarket Shares-to-USDC conversion update VRB Liquidate LendingMarket Forced position closure VRL Deposit SisuVault Position increase (ERC4626) VRL Withdraw SisuVault Position decrease (ERC4626) VRL Transfer SisuVault Vault share transfers [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#usl-migrator) USL Migrator ------------------------------------------------------------------------------------------------------------ Role Event Contract Purpose USLC SupplyCollateral LendingMarket Position increase USLC WithdrawCollateral LendingMarket Position decrease USLC Liquidate LendingMarket Collateral seizure USLL Borrow LendingMarket Position increase USLL Repay LendingMarket Position decrease USLL Liquidate LendingMarket Forced position closure [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#issues-found-and-corrected) Issues found and corrected ---------------------------------------------------------------------------------------------------------------------------------------- Change Detail **Removed** BT / Mint / FiraMarket — wrong contract; FiraMarket.Mint is for LP tokens **Removed** BT / Burn / FiraMarket — wrong contract; same reason **Removed** CT / Mint / CouponToken — redundant with CT Transfer (from=0x0) **Removed** CT / Burn / CouponToken — redundant with CT Transfer (to=0x0) **Added** BFR / Swap / FiraMarket — required for BFR qualification per spec **Added** BFR / Liquidate / LendingMarket **Added** LP / Transfer / FiraMarket **Added** VRB / Liquidate / LendingMarket **Added** VRL / Transfer / SisuVault **Added** USLC / Liquidate / LendingMarket **Added** USLL / Liquidate / LendingMarket ### [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#key-corrections-explained) Key corrections explained **BT Mint/Burn: Wrong contract (Critical)** — The original table listed BT Mint/Burn on FiraMarket, but BT is created/destroyed by `CouponToken.mintBC()` / `CouponToken.redeemBC()`. FiraMarket `Mint`/`Burn` events are about LP tokens, not BT. The ERC20 `Transfer` event on BondToken already captures mints (`from = address(0)`), burns (`to = address(0)`), and transfers. **BFR qualification requires Swap** — The spec states borrowers must be verified by tracking both the borrow event and a swap event plus USDC transfer. The `Swap` event from FiraMarket confirms the borrower actually swapped BT for USDC. **Liquidate event missing** — `EventsLib.Liquidate` fires on forced position closure and impacts BFR, VRB, USLC, and USLL. Without it, the TWAP will be incorrect for liquidated users. [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#event-signatures-reference) Event signatures reference ---------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#lendingmarket-eventslib) LendingMarket (EventsLib) ### [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#bondtoken-coupontoken-erc20) BondToken / CouponToken (ERC20) ### [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#coupontoken-ibctoken) CouponToken (IBCToken) ### [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#firamarket-ipmarket) FiraMarket (IPMarket) ### [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#sisuvault-erc4626) SisuVault (ERC4626) [hashtag](https://docs.fira.money/developers/events-and-indexing/event-table#implementation-notes) Implementation notes ---------------------------------------------------------------------------------------------------------------------------- * **Market ID filtering**: All LendingMarket events carry `Id indexed id`. The indexer must filter by the correct market IDs to distinguish BFR vs VRB vs USLL markets. * **No double counting**: BT/CT held inside LP pool addresses or router addresses must be excluded from BT/CT buckets. Maintain a set of excluded addresses. * **AccrueInterest for BFR/USLL**: If position value must reflect accrued interest (not just principal), add AccrueInterest to those roles. * **CT in LP pools**: If external AMM pools exist for CT (not FiraMarket), additional pool-specific events would be needed. [PreviousEvents & Indexingchevron-left](https://docs.fira.money/developers/events-and-indexing) [NextReward Measurementchevron-right](https://docs.fira.money/developers/events-and-indexing/reward-measurement) Last updated 1 day ago * [Fixed Rate Market](https://docs.fira.money/developers/events-and-indexing/event-table#fixed-rate-market) * [Variable Rate Market](https://docs.fira.money/developers/events-and-indexing/event-table#variable-rate-market) * [USL Migrator](https://docs.fira.money/developers/events-and-indexing/event-table#usl-migrator) * [Issues found and corrected](https://docs.fira.money/developers/events-and-indexing/event-table#issues-found-and-corrected) * [Key corrections explained](https://docs.fira.money/developers/events-and-indexing/event-table#key-corrections-explained) * [Event signatures reference](https://docs.fira.money/developers/events-and-indexing/event-table#event-signatures-reference) * [LendingMarket (EventsLib)](https://docs.fira.money/developers/events-and-indexing/event-table#lendingmarket-eventslib) * [BondToken / CouponToken (ERC20)](https://docs.fira.money/developers/events-and-indexing/event-table#bondtoken-coupontoken-erc20) * [CouponToken (IBCToken)](https://docs.fira.money/developers/events-and-indexing/event-table#coupontoken-ibctoken) * [FiraMarket (IPMarket)](https://docs.fira.money/developers/events-and-indexing/event-table#firamarket-ipmarket) * [SisuVault (ERC4626)](https://docs.fira.money/developers/events-and-indexing/event-table#sisuvault-erc4626) * [Implementation notes](https://docs.fira.money/developers/events-and-indexing/event-table#implementation-notes) Copy event Borrow(Id indexed id, address caller, address indexed onBehalf, address indexed receiver, uint256 assets, uint256 shares); event Repay(Id indexed id, address indexed caller, address indexed onBehalf, uint256 assets, uint256 shares); event SupplyCollateral(Id indexed id, address indexed caller, address indexed onBehalf, uint256 assets); event WithdrawCollateral(Id indexed id, address caller, address indexed onBehalf, address indexed receiver, uint256 assets); event AccrueInterest(Id indexed id, uint256 prevBorrowRate, uint256 interest, uint256 feeShares); event Liquidate(Id indexed id, address indexed caller, address indexed borrower, uint256 repaidAssets, uint256 repaidShares, uint256 seizedAssets, uint256 badDebtAssets, uint256 badDebtShares); Copy event Transfer(address indexed from, address indexed to, uint256 value); Copy event RedeemInterest(address indexed user, uint256 interestOut); Copy event Mint(address indexed receiver, uint256 netLpMinted, uint256 netFwUsed, uint256 netBtUsed); event Burn(address indexed receiverFw, address indexed receiverBt, uint256 netLpBurned, uint256 netFwOut, uint256 netBtOut); event Swap(address indexed caller, address indexed receiver, int256 netBtOut, int256 netFwOut, uint256 netFwFee, uint256 netFwToReserve); Copy event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares); event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares); event Transfer(address indexed from, address indexed to, uint256 value); --- # Borrow Fixed Rate | Fira Docs **Also available**: `borrowSingleToken` — same flow but skips the collateral supply step (assumes collateral already supplied). **Key references**: `src/fira_bonding/router/ActionBorrow.sol::supplyAndBorrowSingleToken`, `borrowSingleToken`. [hashtag](https://docs.fira.money/developers/user-flows/borrow-fixed-rate#details) Details ----------------------------------------------------------------------------------------------- * **Goal**: Supply collateral and receive a target token in one transaction (via BT→FW→token path). * **Preconditions**: * User approved `collateralToken` to the router. * `tokensToBorrow > 0`, `collateralAmount > 0`, `receiver != 0x0`. * Market is initialized; `firaMarket` and `lendingMarket` set. * User must have authorized the router on the LendingMarket (`setAuthorization(router, true)`). * **Parameters** (high level): * `marketParams` (Fira Lending), `collateralAmount`, `tokensToBorrow` (BT), * `output` (TokenOutput: `tokenOut`, `tokenRedeemFw`, `minTokenOut`, `firaSwap`, `swapData`), * `limitOrderData` (kept for interface compatibility, orderbook not used in current version). [hashtag](https://docs.fira.money/developers/user-flows/borrow-fixed-rate#views-and-events) Views and events ----------------------------------------------------------------------------------------------------------------- **Views** * Lending: `getUserPosition(marketParams, user)` → `supplyAssets`, `supplyShares`, `borrowAssets`, `borrowShares`, `collateralAssets`. * Lending: `position(id, user)`, `market(id)`. * Market (fixed-rate): `readTokens()`, `isExpired()`. **Events** * Lending: `EventsLib.SupplyCollateral`, `EventsLib.Borrow`. * Market: `Swap` (BT→FW), `UpdateImpliedRate`. * FW: `Deposit` (tokenIn→FW), `Redeem` (FW→tokenOut). [hashtag](https://docs.fira.money/developers/user-flows/borrow-fixed-rate#reward-share-fixed-rate-borrow) Reward share (fixed-rate borrow) ----------------------------------------------------------------------------------------------------------------------------------------------- * Suggested formula: `userBorrowBT / totalBorrowBT` over the epoch (TWAP). * Functions to call: * `LendingMarket.getUserPosition(marketParamsBT, user)` → `borrowAssets` (userBorrowBT) * `LendingMarket.market(idBT).totalBorrowAssets` → `totalBorrowBT` (consider `accrueInterest(marketParamsBT)` before reading) * `FiraMarket.readTokens()` → BT address; `FiraMarket.isExpired()` * Events to index: `EventsLib.Borrow`, `FiraMarket.Swap` (BT→FW), `IFiraWrappedStandardized.Redeem` [PreviousUser Flowschevron-left](https://docs.fira.money/developers/user-flows) [NextRepay Fixed Ratechevron-right](https://docs.fira.money/developers/user-flows/repay-fixed-rate) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/borrow-fixed-rate#details) * [Views and events](https://docs.fira.money/developers/user-flows/borrow-fixed-rate#views-and-events) * [Reward share (fixed-rate borrow)](https://docs.fira.money/developers/user-flows/borrow-fixed-rate#reward-share-fixed-rate-borrow) --- # Pre/Post Expiry Exits | Fira Docs **Key references**: `IPActionMiscV3.exitPreExpToToken/Fw`, `exitPostExpToToken/Fw`. [hashtag](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits#details) Details --------------------------------------------------------------------------------------------------- * **Goal**: Unwind LP/BT/CT positions to a single token or FW. * **Pre-expiry**: Router first matches BT with CT for redemption (cheaper than swapping), then swaps any remaining unmatched BT or CT to FW via the AMM. Finally redeems FW to desired token. * **Post-expiry**: BT is sent to the CT contract. `CT.redeemBC()` burns only BT (not CT). FW returned at current `bcIndex` rate. Post-expiry yield accrual goes to treasury, not the redeemer. circle-info **Implementation note**: `exitPostExpToFw` has a parameter named `netFwOut` that should be `netBtIn` (naming bug in implementation, no functional impact). [hashtag](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits#views-and-events) Views and events --------------------------------------------------------------------------------------------------------------------- **Views** * Market: `isExpired()`, `readTokens()`, `observe(...)`. * Lending: `getUserPosition` if exiting borrow-adjacent strategies. **Events** * Router: `ExitPreExpToToken`, `ExitPreExpToFw`, `ExitPostExpToToken`, `ExitPostExpToFw`. * Market: `Burn`, subsequent `Swap` if executed. * CT: `Burn` (for BC redemption step). [PreviousFW Deposit & Redeemchevron-left](https://docs.fira.money/developers/user-flows/fw-deposit-redeem) [NextEvents & Indexingchevron-right](https://docs.fira.money/developers/events-and-indexing) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits#details) * [Views and events](https://docs.fira.money/developers/user-flows/pre-post-expiry-exits#views-and-events) --- # Terms of Use | Fira Docs **Version: 01/13/2026** * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-1.-purpose-acceptance) 1\. Purpose – Acceptance ------------------------------------------------------------------------------------------------------------ **1.1** These Terms of Use (the "Terms") govern access to and use of: * (i) the website * (ii) the front-end application and/or APIs * (iii) the content/documentation made available (together, the "Services") **1.2** By clicking "Accept", connecting a wallet, or using the Services, you acknowledge that you have read, understood, and accepted these Terms and the [Risks & Security](https://docs.fira.money/security-and-risk/risk-disclaimers) documentation, which is incorporated by reference. **1.3** If you do not agree, do not use the Services. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-2.-definitions) 2\. Definitions -------------------------------------------------------------------------------------------- Term Definition **Fira Protocol** The set of smart contracts deployed on one or more public blockchains enabling lending/borrowing operations **Fira Interface** The front-end and/or API that allows you to submit transactions to the Protocol **USDC** A third-party stablecoin (issued and administered by a third party) **FW** The wrapped form used by Fira as the unit of account **BT** Synthetic tokens associated with borrowing, designed to converge to 1 FW at maturity **CT** Tokens representing an economic claim on the "interest/coupon" component arising from the pool structure **Maturity** The pool/market expiry at which certain conversions/redemptions may apply **User / You** Any person accessing or using the Services **Wallet** A self-custodial wallet (EOA or smart wallet) controlled by you * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-3.-services-description-scope) 3\. Services Description – Scope ---------------------------------------------------------------------------------------------------------------------------- **3.1** The Services primarily provide: * (a) an interface to read information * (b) a way to submit transactions to the Protocol through your Wallet **3.2** **Non-custodial:** You retain control of your private keys and Wallet at all times. The Fira Interface Operator does not hold your assets, cannot initiate transactions on your behalf, and cannot reverse a transaction confirmed on a blockchain. **3.3** **Protocol ≠ Operator:** Unless expressly stated, the Fira Interface Operator does not guarantee the continuous operation of any blockchain network, oracle, bridge, third-party token, or the availability of any smart contract. **3.4** Information displayed (rates, prices, APY, health metrics, etc.) is indicative and may be delayed, inaccurate, or incomplete. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-4.-nature-of-information-no-advice) 4\. Nature of Information – No Advice -------------------------------------------------------------------------------------------------------------------------------------- **4.1** Nothing in the Services constitutes financial, investment, credit, legal, tax, or accounting advice, nor any personalized recommendation. **4.2** You are solely responsible for your decisions and your own risk assessment, including whether the Protocol is appropriate for you. **4.3** You acknowledge that crypto-assets and DeFi involve volatility and risks that may not be suitable for all users. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-5.-eligibility-sanctions-restricted-jurisdictions) 5\. Eligibility – Sanctions – Restricted Jurisdictions ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- **5.1** You represent that you are of legal age and have the legal capacity to use the Services. **5.2** You represent that you are: * Not located, resident, incorporated, or acting on behalf of a person located in a Restricted Jurisdiction * Not subject to sanctions (OFAC, EU, UN, UK, etc.), and not listed on any sanctions list :::danger\[Restricted Jurisdictions\] Afghanistan, Albania, Angola, Azerbaijan, Bosnia Herzegovina, Bahamas, Barbados, Burma, Botswana, Burkina Faso, Burundi, Cambodia, Cameroon, Crimea (Ukraine), Chad, China, Congo, Democratic Republic of Congo, Cuba, Ethiopia, Eritrea, Fiji, Palau, Ghana, Guinea, Guinea-Bissau, Haiti, Iran, Iraq, Jamaica, Jordan, Lao People's Democratic Republic, Uganda, Liberia, Libya, Madagascar, Mali, Malta, Morocco, Mozambique, Nicaragua, Nigeria, North Korea, Pakistan, Panama, Philippines, Puerto Rico, Russia, Senegal, Somalia, Sri Lanka, Sudan, Syria, Tajikistan, Trinidad and Tobago, Turkey, Turkmenistan, **United States**, Uzbekistan, Vanuatu, Venezuela, Virgin Islands, Yemen, Zimbabwe, and any resident or national of a country otherwise subject to a U.S. Government embargo. ::: **5.3** Any attempt to circumvent restrictions (VPN, proxy, etc.) may result in restriction or suspension of access. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-6.-economic-mechanics-key-reminders) 6\. Economic Mechanics (Key Reminders) ---------------------------------------------------------------------------------------------------------------------------------------- **6.1** **Wrapping:** Fira V1 uses USDC and operates with FW-USDC (wrap/unwrap) for certain operations. **6.2** **Borrowing:** Borrowing may involve minting BT-USDC against collateral and swapping BT-USDC→FW-USDC at a discount. The economic cost is embedded in that discount. **6.3** **Fixed-maturity "fixed rate":** Predictability is designed for holding until maturity; early repayment may change the effective cost. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-7.-fees) 7\. Fees ------------------------------------------------------------------------------ **7.1** **Network fees:** You pay blockchain transaction fees (gas), which are non-refundable. **7.2** **Protocol/third-party fees:** Certain markets may include fees (swaps, liquidations, performance/management, bridges, etc.) set on-chain or by third parties. **7.3** Any displayed fees/rates are indicative; you must verify details before signing. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-8.-assumption-of-risk) 8\. Assumption of Risk ---------------------------------------------------------------------------------------------------------- **8.1** By using the Services, you acknowledge and accept the risks described in [Risks & Security](https://docs.fira.money/security-and-risk/risk-disclaimers) . **8.2** This documentation is not exhaustive; other known or unknown risks may exist. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-9.-user-obligations) 9\. User Obligations ------------------------------------------------------------------------------------------------------ **9.1** Secure your private keys/seed phrase, devices, access, and approvals. **9.2** Verify smart contract addresses, networks, tokens, amounts, and recipients before signing. **9.3** Do not use the Services for illegal activity (money laundering, terrorist financing, fraud, etc.). **9.4** Do not attempt to attack, exploit, reverse engineer, or interfere with the Services/contracts. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-10.-third-party-services-dependencies) 10\. Third-Party Services – Dependencies -------------------------------------------------------------------------------------------------------------------------------------------- **10.1** The Services may rely on third parties (RPCs, oracles, bridges, analytics, wallets, DEXs, protocols used for rehypothecation, etc.). **10.2** Such third parties have their own terms and may fail, be compromised, or change rules. The Fira Interface Operator is not responsible for them. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-11.-intellectual-property-license) 11\. Intellectual Property – License ------------------------------------------------------------------------------------------------------------------------------------ **11.1** Unless otherwise indicated, the Interface content is protected (branding, UI, text, etc.). **11.2** A limited, revocable, non-exclusive license is granted to you to use the Services in compliance with these Terms. **11.3** Smart contracts may be open-source under specific licenses. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-12.-disclaimer-of-warranties) 12\. Disclaimer of Warranties ------------------------------------------------------------------------------------------------------------------------ **12.1** The Services are provided "as is" and "as available." **12.2** No warranties are given regarding error-free operation, uptime, security, performance, solvency, liquidity, or returns. * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-13.-limitation-of-liability) 13\. Limitation of Liability ---------------------------------------------------------------------------------------------------------------------- **13.1** To the maximum extent permitted by law, the Fira Interface Operator will not be liable for indirect damages (loss of profit, data, opportunity, etc.). * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-14.-indemnification) 14\. Indemnification ------------------------------------------------------------------------------------------------------ You agree to indemnify and hold harmless the Fira Interface Operator from any claim arising out of: * (i) your breach of these Terms * (ii) your illegal use of the Services * (iii) your violation of applicable law * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-15.-suspension-termination) 15\. Suspension – Termination ---------------------------------------------------------------------------------------------------------------------- **15.1** You may stop using the Services at any time. **15.2** The Fira Interface Operator may suspend/restrict access (including for sanctions compliance, illegal activity, security risk, or legal obligations). * * * [hashtag](https://docs.fira.money/legal/terms-of-use#id-16.-governing-law-dispute-resolution) 16\. Governing Law – Dispute Resolution ------------------------------------------------------------------------------------------------------------------------------------------ **16.1** **Governing law:** France **16.2** **Jurisdiction/Arbitration:** France * * * [hashtag](https://docs.fira.money/legal/terms-of-use#contact) Contact -------------------------------------------------------------------------- **Interface Operator:** Steady Labs **Email:** [\[email protected\]](https://docs.fira.money/cdn-cgi/l/email-protection) [PreviousIntegrationschevron-left](https://docs.fira.money/resources/integrations) [NextPrivacy Policychevron-right](https://docs.fira.money/legal/privacy-policy) Last updated 1 day ago * [1\. Purpose – Acceptance](https://docs.fira.money/legal/terms-of-use#id-1.-purpose-acceptance) * [2\. Definitions](https://docs.fira.money/legal/terms-of-use#id-2.-definitions) * [3\. Services Description – Scope](https://docs.fira.money/legal/terms-of-use#id-3.-services-description-scope) * [4\. Nature of Information – No Advice](https://docs.fira.money/legal/terms-of-use#id-4.-nature-of-information-no-advice) * [5\. Eligibility – Sanctions – Restricted Jurisdictions](https://docs.fira.money/legal/terms-of-use#id-5.-eligibility-sanctions-restricted-jurisdictions) * [6\. Economic Mechanics (Key Reminders)](https://docs.fira.money/legal/terms-of-use#id-6.-economic-mechanics-key-reminders) * [7\. Fees](https://docs.fira.money/legal/terms-of-use#id-7.-fees) * [8\. Assumption of Risk](https://docs.fira.money/legal/terms-of-use#id-8.-assumption-of-risk) * [9\. User Obligations](https://docs.fira.money/legal/terms-of-use#id-9.-user-obligations) * [10\. Third-Party Services – Dependencies](https://docs.fira.money/legal/terms-of-use#id-10.-third-party-services-dependencies) * [11\. Intellectual Property – License](https://docs.fira.money/legal/terms-of-use#id-11.-intellectual-property-license) * [12\. Disclaimer of Warranties](https://docs.fira.money/legal/terms-of-use#id-12.-disclaimer-of-warranties) * [13\. Limitation of Liability](https://docs.fira.money/legal/terms-of-use#id-13.-limitation-of-liability) * [14\. Indemnification](https://docs.fira.money/legal/terms-of-use#id-14.-indemnification) * [15\. Suspension – Termination](https://docs.fira.money/legal/terms-of-use#id-15.-suspension-termination) * [16\. Governing Law – Dispute Resolution](https://docs.fira.money/legal/terms-of-use#id-16.-governing-law-dispute-resolution) * [Contact](https://docs.fira.money/legal/terms-of-use#contact) --- # Reward Measurement | Fira Docs [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#fixed-rate-market) Fixed Rate Market ----------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#bfr-borrow-fixed-rate) BFR (Borrow Fixed Rate) * **What to measure**: Net outstanding principal, expressed in USDC (par: 1 BT ≈ 1 USDC). * **Qualification rule**: Must match a Fira Lending `Borrow` event AND a FiraMarket `Swap` BT→FW plus `FW.Redeem` to USDC in the borrow flow. * **User value**: `userBorrowBT = LendingMarket.getUserPosition(marketParamsBT, user).borrowAssets` * **Total value**: `totalBorrowBT = LendingMarket.market(idBT).totalBorrowAssets` (consider calling `accrueInterest(marketParamsBT)` before reading) * **Reward share**: `userBorrowBT / totalBorrowBT` * **Function calls**: * Lending: `getUserPosition(marketParamsBT, user)`, `position(idBT, user)`, `market(idBT)`; `idBT = marketParamsBT.id()` * Tokens/Market: `FiraMarket.readTokens()` → BT address; Market `isExpired()` for status * **Events to index**: `EventsLib.Borrow`, `FiraMarket.Swap` (BT→FW), `IFiraWrappedStandardized.Redeem` ### [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#bt-held-bt) BT (Held BT) * **What to measure**: Net long BT held outside LP and lending markets; subtract borrowed BT; unit BT. * **User value**: `userBt = IBondToken(BT).balanceOf(user) - LendingMarket.getUserPosition(marketParamsBT, user).borrowAssets` * **Total value**: `totalBt = IERC20(BT).totalSupply() - IBondToken(BT).balanceOf(market) - IBondToken(BT).balanceOf(lendingMarket)` (exclude BT in LP and lending) * **Reward share**: `userBt / totalBt` over the epoch (TWAP) * **Function calls**: * Tokens: `IBondToken(BT).balanceOf(user)`, `IERC20(BT).totalSupply()`, `IBondToken(BT).balanceOf(market)`, `IBondToken(BT).balanceOf(lendingMarket)` * Lending: `getUserPosition(marketParamsBT, user).borrowAssets` ### [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#ct-traders-and-lps) CT (Traders and LPs) * **What to measure**: Net long CT held outside LP/router addresses; unit CT. * **User value**: `userCt = IBCToken(CT).balanceOf(user)` (subtract CT known to be held in LP/router escrows) * **Total value**: `totalCt = IERC20(CT).totalSupply()` * **Reward share**: `userCt / totalCt` * **Function calls**: * Tokens: `IBCToken(CT).balanceOf(user)`, `IERC20(CT).totalSupply()`; `IBCToken(CT).bcIndexStored()` if including index context; `isExpired()` for status circle-exclamation Exclude expired CT. Post-expiry CT is minted but never burned, inflating `totalSupply()`. Consider filtering by excluding known router/contract addresses. ### [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#lp-firamarket-bt-fw-pool) LP (FiraMarket BT/FW pool) * **What to measure**: LP tokens in BT/FW FiraMarket pools; unit LP (market LPT). * **User value**: `lpUser = IERC20(market).balanceOf(user)` limited to `market` addresses * **Total value**: `lpTotal = IERC20(market).totalSupply()` per market * **Reward share**: `lpUser / lpTotal` (optionally weight by underlying share using `readState(router)` totals) * **Function calls**: * Market: `FiraMarket.readTokens()`, `readState(router)` → totals; `observe(...)` if you need rate context; `isExpired()` * LP token: `IERC20(market).balanceOf(user)`, `IERC20(market).totalSupply()` [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#variable-rate-market) Variable Rate Market ----------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#vrb-variable-rate-borrow) VRB (Variable Rate Borrow) * **What to measure**: USDC borrowed; unit USDC. * **User value**: `userVrb = LendingMarket.getUserPosition(marketParamsUSDC, user).borrowAssets` * **Total value**: `totalVrb = LendingMarket.market(idUSDC).totalBorrowAssets` (consider calling `accrueInterest(marketParamsUSDC)` before reading) * **Reward share**: `userVrb / totalVrb` * **Function calls**: * Lending (views): `getUserPosition(marketParamsUSDC, user)`, `position(idUSDC, user)`, `market(idUSDC)`; `idUSDC = marketParamsUSDC.id()` * Optional: `accrueInterest(marketParamsUSDC)` to update totals before reading `market(idUSDC)` * Oracle: `IOracle.price()` (used for health checks; optional for rewards) ### [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#vrl-variable-rate-lending-via-vault) VRL (Variable Rate Lending via vault) * **What to measure**: USDC lent into the variable-rate vault; unit USDC. * **User value**: `userVrl = ISisuVault.convertToAssets(ISisuVault.balanceOf(user))` * **Total value**: `totalVrl = ISisuVault.totalAssets()` (or Σ users' assets for sub-set accounting) * **Reward share**: `userVrl / totalVrl` * **Function calls**: `ISisuVault.balanceOf(user)`, `convertToAssets(shares)`, `totalAssets()`, `totalSupply()` [hashtag](https://docs.fira.money/developers/events-and-indexing/reward-measurement#indexing-notes) Indexing notes ----------------------------------------------------------------------------------------------------------------------- * Lending market functions use `MarketParams` and derive `Id` via `marketParams.id()` off-chain or in-contract; to query data you can use `idToMarketParams(id)`. * For indexing, include `user` as indexed topic when available (e.g., FW `Deposit/Redeem`, Lending events include `onBehalf`/`borrower`). * CT interface is `IBCToken` (not `IPYieldToken`). Key view functions: `bcIndexStored()`, `bcIndexCurrent()`, `isExpired()`, `getPostExpiryData()`. [PreviousEvent Tablechevron-left](https://docs.fira.money/developers/events-and-indexing/event-table) [NextIntegrationschevron-right](https://docs.fira.money/developers/integrations) Last updated 1 day ago * [Fixed Rate Market](https://docs.fira.money/developers/events-and-indexing/reward-measurement#fixed-rate-market) * [BFR (Borrow Fixed Rate)](https://docs.fira.money/developers/events-and-indexing/reward-measurement#bfr-borrow-fixed-rate) * [BT (Held BT)](https://docs.fira.money/developers/events-and-indexing/reward-measurement#bt-held-bt) * [CT (Traders and LPs)](https://docs.fira.money/developers/events-and-indexing/reward-measurement#ct-traders-and-lps) * [LP (FiraMarket BT/FW pool)](https://docs.fira.money/developers/events-and-indexing/reward-measurement#lp-firamarket-bt-fw-pool) * [Variable Rate Market](https://docs.fira.money/developers/events-and-indexing/reward-measurement#variable-rate-market) * [VRB (Variable Rate Borrow)](https://docs.fira.money/developers/events-and-indexing/reward-measurement#vrb-variable-rate-borrow) * [VRL (Variable Rate Lending via vault)](https://docs.fira.money/developers/events-and-indexing/reward-measurement#vrl-variable-rate-lending-via-vault) * [Indexing notes](https://docs.fira.money/developers/events-and-indexing/reward-measurement#indexing-notes) --- # Bug Bounty | Fira Docs [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#introduction) Introduction ---------------------------------------------------------------------------------------------- Steady Labs is launching a bug bounty program for **Fira** deployed on **Ethereum mainnet**. Fira is a modular lending protocol that combines fixed-rate markets, floating-rate lending, curated vaults, tokenized market primitives (BT, CT, FW), rehypothecation, a multi-layer oracle infrastructure, and protocol-controlled liquidity seeding into a single system. Fira is composed of the following independent layers: * **Router (FiraRouterV4):** Diamond-style proxy that dispatches user calls to modular Action contracts (facets), combining multi-step operations into a single transaction. * **Fixed-Rate AMM (FiraMarket):** Pendle-style AMM supporting BT/FW trading and fixed-rate price discovery. * **Lending Markets:** Two separate lending contracts — **FiraLendingMarket** for fixed-rate markets with post-maturity settlement and liquidation logic, and **VariableLendingMarket** for variable-rate lending with collateral management, interest accrual, liquidation, and flash loans. * **Curation Vault (SisuVault):** ERC-4626 vault that allocates pooled capital across variable-rate markets using curator, allocator, and guardian roles with timelocked configuration changes. * **Token Layer:** BT (Bond Token), CT (Coupon Token), FW (FiraWrapped), and LP tokens — ERC-20 tokens implementing fixed-rate yield separation and AMM liquidity positions. * **Rehypothecation Module:** Controls the ratio of idle vs. invested reserves within the FW contract, rebalancing between liquid USDC and variable-rate vault positions. * **Oracle Pipeline:** Multi-layer oracle stack including ChainlinkOracleV2, AaveToChainlinkAdapters, FiraSolvencyOracles, and a BCLpOracle for LP pricing. * **Interest Rate Models:** AdaptiveCurveIrm for variable-rate markets (utilization-based) and `address(0)` for fixed-rate markets (no IRM — rate is determined by AMM pricing). * **Liquidity Injector:** Protocol-controlled contract that mints BT and supplies it to fixed-rate lending markets. Only the LiquidityInjector can supply BT to these markets (whitelist-gated). This bug bounty covers vulnerabilities in the **Fira smart contracts and associated protocol-owned components** that could compromise funds, accounting integrity, solvency, liquidation safety, or protocol availability. Only contracts currently deployed on Ethereum mainnet and listed below are in scope. All deployed contracts are verified on Etherscan. Ownership is assigned to designated multisig addresses at three security tiers (9/15, 5/10, and 4/9 threshold schemes). [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#reward-amounts) Reward Amounts -------------------------------------------------------------------------------------------------- **Critical:** Up to **$500,000** maximum payout, not to exceed **10% of the funds at risk at the time of submission**. Critical findings result in a definite and significant loss of funds or an irreversible locking of funds on a systemic level. Minimum payout for a valid Critical issue: **$50,000**. **High:** Discretionary. Steady Labs determines High-severity payouts on a case-by-case basis considering impact and severity. **Medium:** Discretionary. Steady Labs determines Medium-severity payouts on a case-by-case basis considering impact and severity. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#general-notes) General Notes All reporters should consult **Sherlock's Criteria for Issue Validity** for general guidance on severity and out-of-scope issues. A working **Proof of Concept (PoC)** exploit is highly recommended and may be required for complex issues. Include clear reproduction steps and any setup instructions necessary for validation. All standard **Sherlock Bug Bounty Platform Rules** and safe harbor provisions apply to this program. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#scope) Scope -------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#chain) Chain **Ethereum mainnet only.** Smart contracts deployed on any other network, testnet, sidechain, or staging environment are out of scope. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#in-scope-contracts-ethereum-mainnet) In-Scope Contracts (Ethereum Mainnet) All currently deployed and verified Fira contracts listed below are in scope, including associated implementations and proxies where applicable. Can also be found here: [Contracts & Addresses | Fira Docsarrow-up-right](https://docs.fira.money/resources/contracts-addresses) ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#core-protocol) Core Protocol Contract Address FiraLendingMarket (fixed-rate) `0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e` VariableLendingMarket (variable-rate) `0xc8Db629192a96D6840e88a8451F17655880A2e4D` FiraMarket (AMM) `0xde00b5edb255078dd42ee94fd97f473d1c9c055d` FiraRouterV4 `0xFF615E63aAF2d1B1EE4AdFD34a5840747185d8A0` LiquidityInjector `0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5` ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#router-facets) Router Facets FiraRouterV4 dispatches calls to modular Action contracts via selector-based routing: Facet Address ActionSwapBTV3 `0xab2383692ed8e0836e25b71988c925dfd94ed2fe` ActionSwapCTV3 `0xdb7a722ae7baf83d3d8b9e812952916326d6656b` ActionAddRemoveLiqV3 `0x286bbc5519cd421011e7e1c092e1d6a72edb4d30` ActionCallbackV3 `0x2dead5b19935d7299d7077c52f2e2860370278a5` ActionSimple `0x4474886d003abcb53c307324894c074ce5176f75` ActionMiscV3 `0x967234d7a4416380107da653e5d3afc9c7bf8874` ActionBorrow `0x66f5853cf6c36b97e754f074397d00b78253ef03` ActionStorageV4 `0x0386685eA7d37c61dDb8F2e2E8c45f6a81d4A3C8` ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#vault) Vault Contract Address Description SisuVault (Markov USDC Prime) `0x50791a5cA041b9D6Dd03e64E3Fa0e34a376759AC` ERC-4626 vault curated by Markov Labs, allocating USDC across variable-rate lending markets ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#token-layer) Token Layer Token Address Decimals FW-USDC (USDCFW) `0x62F5366C9E21A95326C461a098a408e034e017b3` 18 BT (Bond Token) `0x57FFbb88f0c69283531a751BE6FF0741348371bA` 6 CT (Coupon Token) `0x93635d34fAd5A9fA7065a645691100b2E23C93cd` 6 BT and CT share the same expiry (May 7, 2026 — unix `1778112000`) and are minted/burned in pairs via the YieldContractFactory. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#modules) Modules Contract Address RehypothecationModule `0xad332515d9c82438BBa0e9FAA9486B52A33a7Ac8` YieldContractFactory `0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be` ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#oracles) Oracles **Fixed-rate markets** use a 4-layer oracle pipeline: Layer PT-USDe Market PT-sUSDe Market AaveToChainlinkAdapter `0xc42F003F9eCD3DdDF704556E82Cdd9271818171F` `0x3d7346578be9B82E0227D027bd86F6De59BA3C91` ChainlinkOracleV2 `0x2ED527087B740530562754EFCd608290eCCdBe2e` `0xD6f5D9102007A737D9EDE6543262516d5c2fc8f8` FiraSolvencyOracle `0xeB30b33A1aC175e0305853636D0eF3898eb530f3` `0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb` FiraSolvencyOracle contracts are immutable after deployment — no admin functions, no owner. **Variable-rate markets:** Market Oracle Type wstETH/USDC `0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2` Morpho oracle (pre-deployed) cbBTC/USDC `0x698253A24CC4926090f841B38D31d6342A00a82C` ChainlinkOracleV2 (BTC/USD + USDC/USD feeds) **Other:** Contract Address BCLpOracle `0xfEAAEC9124FB007d7c44Ed704A08d24b264de921` ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#interest-rate-models) Interest Rate Models Contract Address Used By AdaptiveCurveIrm `0x73C288826347af3718e6F09c2A24AaFDA77684cD` Variable-rate markets (utilization-based) Fixed-rate markets use `address(0)` as their IRM. The borrowing rate is determined at the time of BT issuance through AMM pricing, not through an interest rate model. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#live-fixed-rate-markets) Live Fixed-Rate Markets All live fixed-rate markets operate on the **FiraLendingMarket** at `0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e`. BT is the loan token. Only the LiquidityInjector can supply BT (whitelist-gated). Both markets expire **May 7, 2026**. **PT-USDe / BT Market** Field Value Market ID `0xC48C055110D1692EDA1D45975BD80C75EE5E4D0AB6A5B6FFB949F2252C1B7791` Loan Token BT — `0x57FFbb88f0c69283531a751BE6FF0741348371bA` Collateral PT-USDe (May 7 2026) — `0xAeBf0Bb9f57E89260d57f31AF34eB58657d96Ce0` Oracle FiraSolvencyOracle — `0xeB30b33A1aC175e0305853636D0eF3898eb530f3` IRM `0x0000000000000000000000000000000000000000` (none — fixed rate) LTV / LLTV 89% / 90% Liquidation Incentive 3.1% Whitelist LiquidityInjector — `0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5` Maturity Grace Period 86400 (24h) **PT-sUSDe / BT Market** Field Value Market ID `0xCA309C3ECE0FA3341779D8319F28BD9E08D3E08889E8AC58B4AC9001FBE458F3` Loan Token BT — `0x57FFbb88f0c69283531a751BE6FF0741348371bA` Collateral PT-sUSDe (May 7 2026) — `0x3de0ff76E8b528C092d47b9DaC775931cef80F49` Oracle FiraSolvencyOracle — `0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb` IRM `0x0000000000000000000000000000000000000000` (none — fixed rate) LTV / LLTV 89% / 90% Liquidation Incentive 3.1% Whitelist LiquidityInjector — `0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5` Maturity Grace Period 86400 (24h) ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#live-variable-rate-markets) Live Variable-Rate Markets All live variable-rate markets operate on the **VariableLendingMarket** at `0xc8Db629192a96D6840e88a8451F17655880A2e4D`. **wstETH / USDC** Field Value Market ID `0xB3152AC00687CC9502B78AB452956F85CC89AC210DEEFDA5DBFF09F7F167B544` Loan Token USDC — `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` Collateral wstETH — `0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0` Oracle `0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2` (Morpho wstETH/USDC) IRM AdaptiveCurveIrm — `0x73C288826347af3718e6F09c2A24AaFDA77684cD` LTV / LLTV 87% / 89% **cbBTC / USDC** Field Value Market ID `0x39D3BDD30BF4BCF4A4D3547F2484ABE1E30A2DCD41ED83788B40E2720357AB76` Loan Token USDC — `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` Collateral cbBTC — `0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf` Oracle `0x698253A24CC4926090f841B38D31d6342A00a82C` (ChainlinkOracleV2 cbBTC/USDC) IRM AdaptiveCurveIrm — `0x73C288826347af3718e6F09c2A24AaFDA77684cD` LTV / LLTV 88% / 90% ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#critical-high-medium-eligibility) Critical / High / Medium Eligibility Critical findings typically affect the **core, live, value-bearing layers** of Fira: * FiraLendingMarket and VariableLendingMarket * FiraMarket (AMM) * FiraRouterV4 and Action facets * Token layer accounting and redemption logic (BT, CT, FW) * RehypothecationModule * Oracle pipeline (FiraSolvencyOracle, ChainlinkOracleV2, adapters) * SisuVault with user funds * LiquidityInjector, where a flaw could directly compromise live assets or protocol solvency ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#only-eligible-for-high-medium) Only Eligible for High / Medium The following are in scope but findings are generally capped at **High** or **Medium** unless they directly compromise live funds in a core deployed market: Contract Address YieldContractFactory `0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be` FiraMarketFactory `0xBF1EfC2199ae9EE1B6f5060a45D4440157E49744` SisuVaultFactory `0xe77E0f97A864558e5513209323e4169FcEAC6981` ChainlinkOracleV2Factory `0x7783fF7bE856C7A82bC5497Fb3CC8F7E8802D8dC` Deployment and configuration helper contracts, and non-custodial support contracts that do not themselves hold or control meaningful live value, are also capped at High or Medium. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#scope-note) Scope Note This bounty covers **Fira contracts and protocol-owned infrastructure only**. Other products, protocols, or systems outside the Fira deployment are out of scope unless the vulnerability arises from Fira's own on-chain logic or integration handling. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#out-of-scope) Out of Scope ---------------------------------------------------------------------------------------------- No rewards will be awarded for reports that fall solely into the following categories. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#undeployed-or-non-mainnet-code) Undeployed or Non-Mainnet Code Code, contracts, modules, or features **not currently deployed on Ethereum mainnet** are out of scope. This includes draft code, future upgrades, staging deployments, local testing contracts, and testnets. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#previously-known-issues) Previously Known Issues Issues already identified in prior audits (Sherlock, Spearbit/Cantina, Hexens, yAudit), internal reviews, documentation, or acknowledged by Steady Labs before submission are not eligible. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#frontend-website-and-ui) Frontend, Website, and UI Issues limited to the web application, user interface, dashboards, websites, or other frontend layers are out of scope. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#third-party-protocol-or-token-risks) Third-Party Protocol or Token Risks Vulnerabilities in third-party systems that Fira interacts with but does not control are out of scope. This includes bugs or failures in external protocols, vaults, bridges, or token implementations. Examples of external dependencies not in scope: * **USDC** (Circle) * **wstETH** (Lido) * **cbBTC** (Coinbase) * **USDe / sUSDe** (Ethena) * **PT-USDe / PT-sUSDe** (Pendle) * Any third-party wrapped asset, oracle, or off-chain issuer * **Oracles** not deployed and maintained by the Protocol Team itself, e.g. Chainlink Feeds. If a report depends on these systems failing rather than on a flaw in Fira's own smart contract logic or validation, it is not in scope. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#external-oracle-failures) External Oracle Failures Pure failures of third-party oracle infrastructure, feed operators, or data providers are out of scope unless the vulnerability is specifically in **Fira's oracle integration, validation, or fallback logic** — including the AaveToChainlinkAdapter, ChainlinkOracleV2, or FiraSolvencyOracle contracts. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#off-chain-legal-or-custodial-risks) Off-Chain, Legal, or Custodial Risks Issues arising purely from off-chain custody, legal enforceability, issuer solvency, governance coordination outside the contracts, or real-world asset processes are out of scope. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#intended-admin-or-multisig-powers) Intended Admin or Multisig Powers Behavior that requires proper use of intended administrative, governance, curator, allocator, or multisig permissions is out of scope. Examples of authorized actions, when performed by properly authorized actors: * Adjusting LTV, LLTV, or fee parameters * Pausing or unpausing contracts (USDCFW pause flags: `depositPaused`, `withdrawPaused`, `transferPaused`) * Updating supply caps on SisuVault markets * Rebalancing vault allocations within configured permissions and timelocks * Operating the LiquidityInjector (minting/burning BT, supplying/withdrawing from lending markets) * Executing timelocked curator or allocator actions * Triggering manual rehypothecation via `forceRehypothecation` However, **bypassing or impersonating those permissions** is in scope. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#protocol-intended-behaviors) Protocol-Intended Behaviors The following behaviors are not vulnerabilities when they occur according to design: * Liquidation of unhealthy positions according to configured **LTV / LLTV** and the 3.1% liquidation incentive * Forced post-maturity settlement or liquidation of expired positions (after the 24-hour grace period) * BT/FW convergence to par near maturity * AMM pricing, slippage, or discount/premium behavior consistent with the FiraMarket pricing model * Reserve rebalancing by the RehypothecationModule according to configured `phiMin`, `phiMax`, and `phiTarget` ratios * Yield accruing to CT holders as designed (via InterestManagerCT) * Vault allocation and reallocation inside configured caps and timelocks * Router execution that follows the documented action flow and Diamond-style facet dispatch ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#pure-economic-attacks-without-a-code-vulnerability) Pure Economic Attacks Without a Code Vulnerability Pure market behavior or economic outcomes that do not rely on a contract bug are out of scope: * Market manipulation within intended protocol rules * Liquidity withdrawal by users * Slippage or adverse execution under expected market conditions * Rate movement, basis trading, or maturity-driven repricing * Honest liquidations after genuine collateral price moves * Losses caused solely by external market volatility ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#minor-gas-efficiency-or-documentation-issues) Minor Gas, Efficiency, or Documentation Issues The following are out of scope unless they create a real and material security impact: * Gas optimizations * Minor inefficiencies * Cosmetic or documentation issues * NatSpec mismatches, comment or spelling errors * Minor rounding or precision issues with no material effect on funds or solvency ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#theoretical-or-unrealistic-attacks) Theoretical or Unrealistic Attacks Attacks that require impractical brute force, extreme assumptions, or unrealistic coordination are out of scope. Reports must describe a credible and reproducible exploit path. If you are unsure whether a finding is in scope, focus on **technical, on-chain vulnerabilities in the deployed Fira contracts and live market infrastructure**. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#protocol-resources) Protocol Resources ---------------------------------------------------------------------------------------------------------- Resource Location Fira Documentation [docs.fira.moneyarrow-up-right](https://docs.fira.money/) Contracts & Audits [docs.fira.money/security-and-risk/auditsarrow-up-right](https://docs.fira.money/security-and-risk/audits) Source Code (fira) [github.com/usual-dao/firaarrow-up-right](https://github.com/usual-dao/fira) Source Code (fira-lending-market) [github.com/usual-dao/fira-lending-marketarrow-up-right](https://github.com/usual-dao/fira-lending-market) The ultimate scope of this bounty is defined by the **deployed Ethereum mainnet contracts** listed above. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#judging-and-severity-assessment) Judging and Severity Assessment ------------------------------------------------------------------------------------------------------------------------------------ Sherlock's security team triages and validates all submissions. Sherlock coordinates issue verification and determines validity and severity based on the criteria in this program and Sherlock's platform rules. Steady Labs may be consulted during validation. **Sherlock makes the final determination** on issue validity, severity, and payout eligibility. In case of dispute or ambiguity, Sherlock's assessment is the deciding factor. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#disclosure-policy) Disclosure Policy -------------------------------------------------------------------------------------------------------- This bounty follows Sherlock's standard disclosure policy with additional requirements for serious vulnerabilities. Critical and high-impact findings must **not** be disclosed publicly or to any third party until all of the following conditions are met: 1. Steady Labs has been notified through the official submission process 2. The issue has been acknowledged 3. A fix or mitigation has been deployed, or explicit written permission to disclose has been granted 4. Sherlock has completed or approved the disclosure process Premature disclosure of an exploit path or a live unpatched vulnerability may disqualify the submission from any reward. Report vulnerabilities **promptly** — ideally within **24 hours of discovery** — through the official Sherlock submission flow. Do not exploit vulnerabilities on the live network. Do not steal funds, manipulate users, destroy data, or disrupt service. Any exploit activity beyond what is strictly necessary to demonstrate a vulnerability in a controlled manner may lead to disqualification and possible legal consequences. If you believe a vulnerability is already being exploited or may soon be exploited, notify Sherlock and Steady Labs immediately through the approved reporting process. Do not make it public. Steady Labs may, at its discretion, offer additional bonuses for especially novel, impactful, or responsibly handled reports. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#eligibility) Eligibility -------------------------------------------------------------------------------------------- To be eligible for a reward, you must meet all of the following conditions: * **No sanctions:** You are not located in a sanctioned jurisdiction and are not on any prohibited party list. * **No affiliation with Steady Labs:** You are not a current or former employee, core contributor, or immediate family member of someone directly affiliated with Steady Labs or the Fira development effort. * **Legal capacity:** You are legally able to participate in bug bounty programs and receive rewards in your jurisdiction. * **No prior paid audit conflict:** You have not been paid to audit or review this exact codebase in an official capacity, and you did not materially contribute to the in-scope contracts. You may request an exception directly from Steady Labs. * **Follow program rules:** You agree to follow all program rules, scope restrictions, disclosure requirements, and platform terms. By submitting a report, you affirm that you meet these eligibility requirements. Steady Labs and Sherlock reserve the right to verify eligibility and disqualify participants who do not meet these conditions. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#testing-guidelines-and-safe-harbor) Testing Guidelines and Safe Harbor ------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#do-not-test-destructively-on-mainnet) Do Not Test Destructively on Mainnet Do not perform destructive testing on Ethereum mainnet. Use a **local environment, simulation, or mainnet fork** to test exploit scenarios. All in-scope contracts are verified on Etherscan. Researchers can reproduce behavior using **Foundry** or **Hardhat**. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#use-accounts-you-control) Use Accounts You Control Use only wallets, keys, and accounts you control. Do not interfere with other users' positions, balances, or funds. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#no-mainnet-denial-of-service) No Mainnet Denial of Service Do not spam, grief, or attempt denial-of-service against live contracts, users, or infrastructure. Demonstrate any blocking or service-degradation vulnerability in a controlled environment. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#maintain-confidentiality) Maintain Confidentiality Do not share exploit details outside the official submission process before a fix is deployed and disclosure is authorized. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#no-social-engineering-or-off-chain-intrusion) No Social Engineering or Off-Chain Intrusion This bounty covers smart contract and technical security issues only. Social engineering, phishing, credential attacks, or attempts to gain access through non-technical means are strictly prohibited. ### [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#responsible-testing) Responsible Testing Avoid high-volume or risky testing on live systems. If a testing approach might affect real funds or real users, do not perform it on mainnet. As long as you act in good faith, stay within these rules, and report vulnerabilities responsibly, Steady Labs intends for this program to operate under a safe-harbor framework for legitimate security research. [hashtag](https://docs.fira.money/security-and-risk/bug-bounty#closing) Closing ------------------------------------------------------------------------------------ Steady Labs values the work of independent security researchers and the broader white-hat community. Your efforts strengthen the safety and resilience of Fira's fixed-rate, floating-rate, and curated lending infrastructure. Thank you for participating in the **Fira Bug Bounty**. Happy Hunting! [PreviousAuditschevron-left](https://docs.fira.money/security-and-risk/audits) [NextRisk Frameworkchevron-right](https://docs.fira.money/security-and-risk/risk-framework) Last updated 1 day ago * [Introduction](https://docs.fira.money/security-and-risk/bug-bounty#introduction) * [Reward Amounts](https://docs.fira.money/security-and-risk/bug-bounty#reward-amounts) * [General Notes](https://docs.fira.money/security-and-risk/bug-bounty#general-notes) * [Scope](https://docs.fira.money/security-and-risk/bug-bounty#scope) * [Chain](https://docs.fira.money/security-and-risk/bug-bounty#chain) * [In-Scope Contracts (Ethereum Mainnet)](https://docs.fira.money/security-and-risk/bug-bounty#in-scope-contracts-ethereum-mainnet) * [Core Protocol](https://docs.fira.money/security-and-risk/bug-bounty#core-protocol) * [Router Facets](https://docs.fira.money/security-and-risk/bug-bounty#router-facets) * [Vault](https://docs.fira.money/security-and-risk/bug-bounty#vault) * [Token Layer](https://docs.fira.money/security-and-risk/bug-bounty#token-layer) * [Modules](https://docs.fira.money/security-and-risk/bug-bounty#modules) * [Oracles](https://docs.fira.money/security-and-risk/bug-bounty#oracles) * [Interest Rate Models](https://docs.fira.money/security-and-risk/bug-bounty#interest-rate-models) * [Live Fixed-Rate Markets](https://docs.fira.money/security-and-risk/bug-bounty#live-fixed-rate-markets) * [Live Variable-Rate Markets](https://docs.fira.money/security-and-risk/bug-bounty#live-variable-rate-markets) * [Critical / High / Medium Eligibility](https://docs.fira.money/security-and-risk/bug-bounty#critical-high-medium-eligibility) * [Only Eligible for High / Medium](https://docs.fira.money/security-and-risk/bug-bounty#only-eligible-for-high-medium) * [Scope Note](https://docs.fira.money/security-and-risk/bug-bounty#scope-note) * [Out of Scope](https://docs.fira.money/security-and-risk/bug-bounty#out-of-scope) * [Undeployed or Non-Mainnet Code](https://docs.fira.money/security-and-risk/bug-bounty#undeployed-or-non-mainnet-code) * [Previously Known Issues](https://docs.fira.money/security-and-risk/bug-bounty#previously-known-issues) * [Frontend, Website, and UI](https://docs.fira.money/security-and-risk/bug-bounty#frontend-website-and-ui) * [Third-Party Protocol or Token Risks](https://docs.fira.money/security-and-risk/bug-bounty#third-party-protocol-or-token-risks) * [External Oracle Failures](https://docs.fira.money/security-and-risk/bug-bounty#external-oracle-failures) * [Off-Chain, Legal, or Custodial Risks](https://docs.fira.money/security-and-risk/bug-bounty#off-chain-legal-or-custodial-risks) * [Intended Admin or Multisig Powers](https://docs.fira.money/security-and-risk/bug-bounty#intended-admin-or-multisig-powers) * [Protocol-Intended Behaviors](https://docs.fira.money/security-and-risk/bug-bounty#protocol-intended-behaviors) * [Pure Economic Attacks Without a Code Vulnerability](https://docs.fira.money/security-and-risk/bug-bounty#pure-economic-attacks-without-a-code-vulnerability) * [Minor Gas, Efficiency, or Documentation Issues](https://docs.fira.money/security-and-risk/bug-bounty#minor-gas-efficiency-or-documentation-issues) * [Theoretical or Unrealistic Attacks](https://docs.fira.money/security-and-risk/bug-bounty#theoretical-or-unrealistic-attacks) * [Protocol Resources](https://docs.fira.money/security-and-risk/bug-bounty#protocol-resources) * [Judging and Severity Assessment](https://docs.fira.money/security-and-risk/bug-bounty#judging-and-severity-assessment) * [Disclosure Policy](https://docs.fira.money/security-and-risk/bug-bounty#disclosure-policy) * [Eligibility](https://docs.fira.money/security-and-risk/bug-bounty#eligibility) * [Testing Guidelines and Safe Harbor](https://docs.fira.money/security-and-risk/bug-bounty#testing-guidelines-and-safe-harbor) * [Do Not Test Destructively on Mainnet](https://docs.fira.money/security-and-risk/bug-bounty#do-not-test-destructively-on-mainnet) * [Use Accounts You Control](https://docs.fira.money/security-and-risk/bug-bounty#use-accounts-you-control) * [No Mainnet Denial of Service](https://docs.fira.money/security-and-risk/bug-bounty#no-mainnet-denial-of-service) * [Maintain Confidentiality](https://docs.fira.money/security-and-risk/bug-bounty#maintain-confidentiality) * [No Social Engineering or Off-Chain Intrusion](https://docs.fira.money/security-and-risk/bug-bounty#no-social-engineering-or-off-chain-intrusion) * [Responsible Testing](https://docs.fira.money/security-and-risk/bug-bounty#responsible-testing) * [Closing](https://docs.fira.money/security-and-risk/bug-bounty#closing) Copy Chainlink Price Feed → AaveToChainlinkAdapter → ChainlinkOracleV2 → FiraSolvencyOracle → FiraLendingMarket --- # Variable Rate Lending | Fira Docs **Key references**: `src/LendingMarket.sol` (`supplyCollateral`, `borrow`, `getUserPosition`). [hashtag](https://docs.fira.money/developers/user-flows/variable-rate-lending#details) Details --------------------------------------------------------------------------------------------------- * **Goal**: Supply collateral and borrow variable-rate assets (e.g., USDC) directly from the lending market. * **Preconditions**: * Market created with `loanToken = USDC`, appropriate `oracle`, `ltv/lltv` enabled. * Approvals for `collateralToken` to LendingMarket. * **Notes**: * FW deposits may be rehypothecated into this market on the supply side, while borrowers take variable-rate loans. [hashtag](https://docs.fira.money/developers/user-flows/variable-rate-lending#views-and-events) Views and events --------------------------------------------------------------------------------------------------------------------- **Views** * Lending: `getUserPosition(marketParamsUSDC, user)` → `supplyAssets`, `supplyShares`, `borrowAssets`, `borrowShares`, `collateralAssets`. * Lending: `position(id, user)`, `market(id)`. * Oracle: `price()` (via marketParams' oracle) for health checks. **Events** * Lending: `EventsLib.SupplyCollateral`, `EventsLib.Borrow`, `EventsLib.AccrueInterest`. [hashtag](https://docs.fira.money/developers/user-flows/variable-rate-lending#reward-share-variable-rate-borrow) Reward share (variable-rate borrow) --------------------------------------------------------------------------------------------------------------------------------------------------------- * Formula: `userBorrowAssets / totalBorrowAssets` over the epoch (TWAP). * Functions to call: * `LendingMarket.getUserPosition(marketParamsUSDC, user)` → `borrowAssets` * `LendingMarket.position(idUSDC, user)`, `LendingMarket.market(idUSDC)` (optional) * Index events: `EventsLib.Borrow`, `EventsLib.AccrueInterest` [hashtag](https://docs.fira.money/developers/user-flows/variable-rate-lending#reward-share-variable-rate-lend) Reward share (variable-rate lend) ----------------------------------------------------------------------------------------------------------------------------------------------------- * Formula: `userVaultAssets / totalVaultAssets` over the epoch (TWAP). * Functions to call: * `ISisuVault.balanceOf(user)`; `ISisuVault.convertToAssets(shares)` → `userVaultAssets` * `ISisuVault.totalAssets()` (denominator); `ISisuVault.totalSupply()` (optional) * Index events (optional): vault `Deposit`/`Withdraw` if exposed [PreviousRepay Fixed Ratechevron-left](https://docs.fira.money/developers/user-flows/repay-fixed-rate) [NextRepay Variable Ratechevron-right](https://docs.fira.money/developers/user-flows/repay-variable-rate) Last updated 1 day ago * [Details](https://docs.fira.money/developers/user-flows/variable-rate-lending#details) * [Views and events](https://docs.fira.money/developers/user-flows/variable-rate-lending#views-and-events) * [Reward share (variable-rate borrow)](https://docs.fira.money/developers/user-flows/variable-rate-lending#reward-share-variable-rate-borrow) * [Reward share (variable-rate lend)](https://docs.fira.money/developers/user-flows/variable-rate-lending#reward-share-variable-rate-lend) --- # Security Design | Fira Docs [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#access-control) Access control ----------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#ownership-model) Ownership model All privileged Fira contracts inherit `BoringOwnableUpgradeable`, which provides: * Single `owner` with a two-step transfer (`transferOwnership` → `claimOwnership`) to prevent accidental misassignment. * `onlyOwner` modifier gating admin functions (pause, parameter updates, upgrades). ### [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#router-selector-guards) Router selector guards The `FiraRouterV4` uses a diamond-like facet dispatch table. Each facet registers its function selectors during `initialize()`. Calls to unregistered selectors revert with `Errors.RouterInvalidAction`. This ensures that only explicitly whitelisted facets can be invoked through the Router. ### [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#minting-privileges) Minting privileges BondToken and CouponToken restrict `mintBC()` and `redeemBC()` to the `YieldContractFactory` address set at initialization, preventing arbitrary minting. The LiquidityInjector holds a separate minting privilege on BondToken via the `LIQUIDITY_INJECTOR` role, constrained by the `injectLiquidityLimit` cap. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#reentrancy-protection) Reentrancy protection ------------------------------------------------------------------------------------------------------------------------------------- Fira applies the `nonReentrant` modifier (OpenZeppelin `ReentrancyGuard`) to all external state-mutating functions across: Contract Protected functions **FWBase** `deposit`, `redeem`, `claimRewards` **FiraMarket** `mint`, `burn`, `swapExactBtForFw`, `swapFwForExactBt` **CouponToken** `mintBC`, `redeemBC`, `redeemInterest`, `redeemInterestAndTransfer` **LiquidityInjector** `injectLiquidity`, `withdrawLiquidity` **RehypothecationModule** `rebalance` The Router's `_safeTransferWithFeeExtraction` and callback patterns (flash swaps) are additionally protected by the facet-level lock state in `ActionStorageV4`. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#pause-controls) Pause controls ----------------------------------------------------------------------------------------------------------------------- FW token contracts (`FWBase`, `USDCFW`) inherit OpenZeppelin's `PausableUpgradeable`: * `**pause()**` — Owner freezes all deposit and redeem operations. * `**unpause()**` — Owner resumes normal operations. * `**whenNotPaused**` modifier — Applied to `deposit()`, `redeem()`, and related transfer functions. circle-exclamation Pause does not affect BT/CT trading on FiraMarket. Market operations remain available to allow users to exit positions even during an FW pause. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#upgrade-patterns) Upgrade patterns --------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#initializable-contracts) Initializable contracts All upgradeable contracts use OpenZeppelin's `Initializable` with `initializer` / `reinitializer(n)` modifiers to prevent double-initialization attacks. ### [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#router-versioning) Router versioning The Router facet system supports additive upgrades: 1. Deploy a new facet contract. 2. Call `Router.addToSelectorMapping(selectors, facetAddress)` to register new selectors. 3. Existing selectors can be overwritten to point to the new facet, enabling in-place upgrades without redeploying the Router proxy. Old facets remain deployed on-chain but become unreachable once their selectors are reassigned. ### [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#storage-layout-safety) Storage layout safety Upgradeable contracts follow the "storage gap" convention and use dedicated storage slots (e.g., `ActionStorageV4.STORAGE_SLOT`) to avoid slot collisions across upgrades. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#oracle-defence-in-depth) Oracle defence-in-depth ----------------------------------------------------------------------------------------------------------------------------------------- The Fira oracle pipeline stacks multiple validation layers: Each layer can reject stale or invalid data independently. `ChainlinkOracleV2` enforces a configurable `heartbeat` and reverts with `StalePrice` if the feed has not updated within the window. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#fixed-point-arithmetic-safety) Fixed-point arithmetic safety ----------------------------------------------------------------------------------------------------------------------------------------------------- All yield and pricing math uses the `PMath` and `LogExpMath` libraries with 18-decimal fixed-point representation. Key invariants: * **No division by zero** — All divisors are checked or guaranteed non-zero by prior validation. * **Overflow protection** — Solidity 0.8.x built-in overflow checks apply; `LogExpMath` additionally validates input ranges before exponentiation. * **Rounding direction** — Deposit/mint operations round against the user (ceiling); redeem/burn operations round in favor of the protocol (floor), preventing rounding exploits. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#contract-size-management) Contract size management ------------------------------------------------------------------------------------------------------------------------------------------- Several Fira contracts approach the EIP-170 24 KB limit. The codebase uses two mitigation strategies: 1. **Library extraction** — Heavy logic is moved to external libraries (e.g., `MarketMathCore`, `MarketApproxPtInLib`) that are deployed separately and linked via `DELEGATECALL`. 2. **Split-code deployment** — The `FiraMarket` factory uses a two-part deployment (`MarketMathCore` + `FiraMarketV3`) to keep each deployment unit under the size limit. [hashtag](https://docs.fira.money/developers/security-and-audits/security-practices#invariants-summary) Invariants summary ------------------------------------------------------------------------------------------------------------------------------- Invariant Enforced by FW exchange rate monotonically non-decreasing `FWBase._afterUpdateBCIndex` + rehyp rebalance BT total supply = minted via Factory + LI inject `BondToken.mintBC` access control CT interest accrual ≥ 0 `CouponToken._updateAndDistributeInterest` LP pool BT + FW reserves ≥ total LP supply FiraMarket mint/burn invariant checks Rehyp ratio stays within `[phiMin, phiMax]` `RehypothecationModule.rebalance` bounds check Lending market solvency LendingMarket liquidation + oracle health checks [PreviousSecurity Practiceschevron-left](https://docs.fira.money/developers/security-and-audits) [NextAuditschevron-right](https://docs.fira.money/developers/security-and-audits/audits) Last updated 1 day ago * [Access control](https://docs.fira.money/developers/security-and-audits/security-practices#access-control) * [Ownership model](https://docs.fira.money/developers/security-and-audits/security-practices#ownership-model) * [Router selector guards](https://docs.fira.money/developers/security-and-audits/security-practices#router-selector-guards) * [Minting privileges](https://docs.fira.money/developers/security-and-audits/security-practices#minting-privileges) * [Reentrancy protection](https://docs.fira.money/developers/security-and-audits/security-practices#reentrancy-protection) * [Pause controls](https://docs.fira.money/developers/security-and-audits/security-practices#pause-controls) * [Upgrade patterns](https://docs.fira.money/developers/security-and-audits/security-practices#upgrade-patterns) * [Initializable contracts](https://docs.fira.money/developers/security-and-audits/security-practices#initializable-contracts) * [Router versioning](https://docs.fira.money/developers/security-and-audits/security-practices#router-versioning) * [Storage layout safety](https://docs.fira.money/developers/security-and-audits/security-practices#storage-layout-safety) * [Oracle defence-in-depth](https://docs.fira.money/developers/security-and-audits/security-practices#oracle-defence-in-depth) * [Fixed-point arithmetic safety](https://docs.fira.money/developers/security-and-audits/security-practices#fixed-point-arithmetic-safety) * [Contract size management](https://docs.fira.money/developers/security-and-audits/security-practices#contract-size-management) * [Invariants summary](https://docs.fira.money/developers/security-and-audits/security-practices#invariants-summary) Copy Aave V3 Oracle ↓ AaveToChainlinkAdapter (normalizes to Chainlink AggregatorV3 interface) ↓ ChainlinkOracleV2 (staleness check, sequencer-down check on L2) ↓ FiraSolvencyOracle (solvency ratio validation) ↓ BCLpOracle (fair LP token pricing using BT/FW spot + TWAP) --- # Privacy Policy | Fira Docs **Last Updated: 01/14/2026** * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-1.-who-we-are) 1\. Who We Are -------------------------------------------------------------------------------------------- **ADDU** (hereinafter "ADDU", "we", "us" or "our") is a **French non-profit association** (Association loi 1901) governed by French law, with its registered office at: **10 rue de la Paix, 75002 Paris, France** ADDU operates websites and interfaces enabling access to certain functionalities related to digital assets and smart contracts (the "Services"), in particular through: * fira.money * app.fira.money (together, the "Site") * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-2.-purpose-of-this-privacy-policy) 2\. Purpose of This Privacy Policy ------------------------------------------------------------------------------------------------------------------------------------ This Privacy Policy explains: * What personal data we collect * Why and on what legal basis we process it * With whom we share it * How long we retain it * Your GDPR rights and how to exercise them * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-3.-definitions) 3\. Definitions ---------------------------------------------------------------------------------------------- Term Definition **Personal Data** Any information relating to an identified or identifiable natural person (e.g., email address, IP address, online identifier, a wallet address if it can identify a person) **Processing** Any operation performed on personal data (collection, storage, consultation, deletion, etc.) **Controller** The entity that determines the purposes and means of the processing (ADDU for the processing described here, except for blockchain processing) * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-4.-eligibility-minors) 4\. Eligibility (Minors) -------------------------------------------------------------------------------------------------------------- The Services are not intended for individuals under 18 and we do not knowingly collect personal data from children. If we become aware that a minor has provided us with personal data, we will delete it as soon as reasonably possible, subject to our legal obligations. * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-5.-what-data-do-we-collect) 5\. What Data Do We Collect? ----------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-5.1-data-you-provide-to-us) 5.1 Data You Provide to Us * **Identity and contact data:** first and last name, email address, nationality (if provided) * **Communications:** content of messages sent to our support (e.g., feedback, questions, job applications, requests) ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-5.2-technical-and-usage-data) 5.2 Technical and Usage Data * **Connection data:** IP address, logs, date/time, browser information * **Device and configuration data:** version, time zone, settings, language * **Audience and performance measurement:** technical errors, interactions with the Site, usage events ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-5.3-web3-related-data) 5.3 Web3-Related Data Depending on how the dApp operates, we may process: * Wallet address(es) (public key) * Transaction identifiers (hash) * Network * Relevant smart contract(s) * Data necessary for operations, security, and support :::note Some of this information may also exist on-chain (see Section 10). ::: ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-5.4-cookies-and-trackers) 5.4 Cookies and Trackers We use cookies and similar technologies (see Section 11). * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-6.-why-do-we-process-your-data) 6\. Why Do We Process Your Data? ------------------------------------------------------------------------------------------------------------------------------- In accordance with the GDPR, we process personal data only when we have a legal basis. ### [hashtag](https://docs.fira.money/legal/privacy-policy#main-purposes) Main Purposes Purpose Data Legal Basis Support and Communications Name, email, communications content Performance of contract / Legitimate interests / Consent Providing, Maintaining and Improving the Services Technical data, logs, usage events Legitimate interests / Performance of contract Security, Fraud and Abuse Prevention Logs, IP address, technical signals Legitimate interests / Legal obligations Legal and Regulatory Compliance Any data necessary Legal obligation Non-Essential Cookies Cookie identifiers, audience measurement Consent * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-7.-who-do-we-share-your-data-with) 7\. Who Do We Share Your Data With? ------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-7.1-internal-recipients) 7.1 Internal Recipients Access is restricted to personnel who need to know (support, engineering, security). ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-7.2-processors-service-providers) 7.2 Processors (Service Providers) We may share data with service providers acting as processors (hosting, support tools, analytics if enabled, security tooling, communications). ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-7.3-authorities-and-legal-requirements) 7.3 Authorities and Legal Requirements We may disclose data where required to do so by law. ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-7.4-partners) 7.4 Partners If personal data is shared with corporate partners, such sharing must be limited and framed. * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-8.-international-transfers) 8\. International Transfers ---------------------------------------------------------------------------------------------------------------------- Your data may be processed outside the European Economic Area. Where that happens, we implement appropriate safeguards: * Standard Contractual Clauses approved by the European Commission * Additional measures where required (encryption, minimization, access controls) * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-9.-data-retention) 9\. Data Retention ---------------------------------------------------------------------------------------------------- We retain personal data only as long as necessary for the purposes described above. Data Type Retention Period Support/communications As long as needed + up to 5 years for archiving Account/relationship data 5 years after account closure Transaction-related data 5 years from transaction date Security logs A few months (unless incident requires longer) :::warning\[Blockchain Data\] Data recorded on a public blockchain may be non-erasable. ::: * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-10.-blockchain-specific-notice) 10\. Blockchain-Specific Notice ------------------------------------------------------------------------------------------------------------------------------ :::danger\[Important\] Public blockchains provide transaction transparency. Some information (e.g., wallet addresses, amounts, transaction hashes) may be recorded **permanently** on-chain. ::: ADDU does not control public blockchains (decentralized networks) and is not responsible for processing carried out by such networks nor for on-chain persistence. As a result, certain rights (in particular erasure and rectification) may be technically limited for on-chain data. **Recommendation:** Do not insert directly identifying personal data (e.g., name, email) into public transaction fields or metadata. * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-11.-cookies-and-similar-technologies) 11\. Cookies and Similar Technologies ------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-11.1-what-is-a-cookie) 11.1 What is a Cookie? A cookie/tracker is a file or identifier stored/read on your device to enable technical functionality, measure audience, store preferences, etc. ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-11.2-strictly-necessary-cookies-no-consent-required) 11.2 Strictly Necessary Cookies (No Consent Required) We may use technical cookies essential to operate the Site (e.g., session management, security, load balancing). ### [hashtag](https://docs.fira.money/legal/privacy-policy#id-11.3-non-essential-cookies-consent-required) 11.3 Non-Essential Cookies (Consent Required) Analytics, advanced personalization, or advertising cookies (if used) generally require your prior consent. * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-12.-security) 12\. Security ------------------------------------------------------------------------------------------ We implement reasonable technical and organizational measures to protect your data: * Access controls * Minimization * Logging * Backups * Application security :::note No method provides absolute security, and a residual risk cannot be entirely eliminated. ::: * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-13.-your-gdpr-rights) 13\. Your GDPR Rights ---------------------------------------------------------------------------------------------------------- Subject to legal conditions and limitations, you have the right to: Right Description **Access** Access your data **Rectification** Rectify your data **Erasure** Erase your data (in certain cases) **Restriction** Restrict processing **Object** Object to processing based on legitimate interests **Portability** Data portability (where applicable) **Withdraw Consent** Withdraw consent at any time **Post-mortem Instructions** Under French law :::warning\[Blockchain Limitation\] The exercise of certain rights may be limited for on-chain data. ::: * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-14.-how-to-exercise-your-rights) 14\. How to Exercise Your Rights -------------------------------------------------------------------------------------------------------------------------------- You may contact us: **By email:** [\[email protected\]](https://docs.fira.money/cdn-cgi/l/email-protection) **By post:** ADDU – 10 rue de la Paix, 75002 Paris, France * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-15.-complaints-with-a-supervisory-authority) 15\. Complaints with a Supervisory Authority -------------------------------------------------------------------------------------------------------------------------------------------------------- If you believe your rights are not respected, you may lodge a complaint with the **CNIL** (France): **CNIL – 3 Place de Fontenoy – TSA 80715 – 75334 Paris Cedex 07** * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-16.-third-party-links) 16\. Third-Party Links ------------------------------------------------------------------------------------------------------------ The Site may contain links to third-party websites. We do not control those sites and this Privacy Policy does not apply to them. * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-17.-changes-to-this-privacy-policy) 17\. Changes to This Privacy Policy -------------------------------------------------------------------------------------------------------------------------------------- We may update this Privacy Policy at any time. Where changes are material, we will post a notice on the Site and the updated version will apply as of publication. * * * [hashtag](https://docs.fira.money/legal/privacy-policy#id-18.-contact) 18\. Contact ---------------------------------------------------------------------------------------- If you have any questions about privacy, please contact: **[\[email protected\]](https://docs.fira.money/cdn-cgi/l/email-protection) ** [PreviousTerms of Usechevron-left](https://docs.fira.money/legal/terms-of-use) Last updated 1 day ago * [1\. Who We Are](https://docs.fira.money/legal/privacy-policy#id-1.-who-we-are) * [2\. Purpose of This Privacy Policy](https://docs.fira.money/legal/privacy-policy#id-2.-purpose-of-this-privacy-policy) * [3\. Definitions](https://docs.fira.money/legal/privacy-policy#id-3.-definitions) * [4\. Eligibility (Minors)](https://docs.fira.money/legal/privacy-policy#id-4.-eligibility-minors) * [5\. What Data Do We Collect?](https://docs.fira.money/legal/privacy-policy#id-5.-what-data-do-we-collect) * [5.1 Data You Provide to Us](https://docs.fira.money/legal/privacy-policy#id-5.1-data-you-provide-to-us) * [5.2 Technical and Usage Data](https://docs.fira.money/legal/privacy-policy#id-5.2-technical-and-usage-data) * [5.3 Web3-Related Data](https://docs.fira.money/legal/privacy-policy#id-5.3-web3-related-data) * [5.4 Cookies and Trackers](https://docs.fira.money/legal/privacy-policy#id-5.4-cookies-and-trackers) * [6\. Why Do We Process Your Data?](https://docs.fira.money/legal/privacy-policy#id-6.-why-do-we-process-your-data) * [Main Purposes](https://docs.fira.money/legal/privacy-policy#main-purposes) * [7\. Who Do We Share Your Data With?](https://docs.fira.money/legal/privacy-policy#id-7.-who-do-we-share-your-data-with) * [7.1 Internal Recipients](https://docs.fira.money/legal/privacy-policy#id-7.1-internal-recipients) * [7.2 Processors (Service Providers)](https://docs.fira.money/legal/privacy-policy#id-7.2-processors-service-providers) * [7.3 Authorities and Legal Requirements](https://docs.fira.money/legal/privacy-policy#id-7.3-authorities-and-legal-requirements) * [7.4 Partners](https://docs.fira.money/legal/privacy-policy#id-7.4-partners) * [8\. International Transfers](https://docs.fira.money/legal/privacy-policy#id-8.-international-transfers) * [9\. Data Retention](https://docs.fira.money/legal/privacy-policy#id-9.-data-retention) * [10\. Blockchain-Specific Notice](https://docs.fira.money/legal/privacy-policy#id-10.-blockchain-specific-notice) * [11\. Cookies and Similar Technologies](https://docs.fira.money/legal/privacy-policy#id-11.-cookies-and-similar-technologies) * [11.1 What is a Cookie?](https://docs.fira.money/legal/privacy-policy#id-11.1-what-is-a-cookie) * [11.2 Strictly Necessary Cookies (No Consent Required)](https://docs.fira.money/legal/privacy-policy#id-11.2-strictly-necessary-cookies-no-consent-required) * [11.3 Non-Essential Cookies (Consent Required)](https://docs.fira.money/legal/privacy-policy#id-11.3-non-essential-cookies-consent-required) * [12\. Security](https://docs.fira.money/legal/privacy-policy#id-12.-security) * [13\. Your GDPR Rights](https://docs.fira.money/legal/privacy-policy#id-13.-your-gdpr-rights) * [14\. How to Exercise Your Rights](https://docs.fira.money/legal/privacy-policy#id-14.-how-to-exercise-your-rights) * [15\. Complaints with a Supervisory Authority](https://docs.fira.money/legal/privacy-policy#id-15.-complaints-with-a-supervisory-authority) * [16\. Third-Party Links](https://docs.fira.money/legal/privacy-policy#id-16.-third-party-links) * [17\. Changes to This Privacy Policy](https://docs.fira.money/legal/privacy-policy#id-17.-changes-to-this-privacy-policy) * [18\. Contact](https://docs.fira.money/legal/privacy-policy#id-18.-contact) --- # Deployment | Fira Docs **Network:** Ethereum Mainnet **Deployed:** March 13–15, 2026 **Bond Token Expiry:** May 7, 2026 00:00 UTC (`1778112000`) * * * [hashtag](https://docs.fira.money/developers/deployment#external-tokens) External tokens --------------------------------------------------------------------------------------------- Token Symbol Decimals Address USDC USDC 6 [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`arrow-up-right](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) Wrapped stETH wstETH 18 [`0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0`arrow-up-right](https://etherscan.io/address/0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0) Coinbase Wrapped BTC cbBTC 8 [`0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf`arrow-up-right](https://etherscan.io/address/0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf) PT Ethena USDe 7MAY2026 PT-USDe 18 [`0xAeBf0Bb9f57E89260d57f31AF34eB58657d96Ce0`arrow-up-right](https://etherscan.io/address/0xAeBf0Bb9f57E89260d57f31AF34eB58657d96Ce0) PT Ethena sUSDe 7MAY2026 PT-sUSDe 18 [`0x3de0ff76E8b528C092d47b9DaC775931cef80F49`arrow-up-right](https://etherscan.io/address/0x3de0ff76E8b528C092d47b9DaC775931cef80F49) [hashtag](https://docs.fira.money/developers/deployment#fira-tokens) Fira tokens ------------------------------------------------------------------------------------- Token Symbol Decimals Address Fira Wrapped USDC FW-USDC 18 [`0x62F5366C9E21A95326C461a098a408e034e017b3`arrow-up-right](https://etherscan.io/address/0x62F5366C9E21A95326C461a098a408e034e017b3) Bond Token BT 6 [`0x57FFbb88f0c69283531a751BE6FF0741348371bA`arrow-up-right](https://etherscan.io/address/0x57FFbb88f0c69283531a751BE6FF0741348371bA) Coupon Token CT 6 [`0x93635d34fAd5A9fA7065a645691100b2E23C93cd`arrow-up-right](https://etherscan.io/address/0x93635d34fAd5A9fA7065a645691100b2E23C93cd) Markov USDC Prime (SisuVault) mkUSDC 18 [`0x50791a5cA041b9D6Dd03e64E3Fa0e34a376759AC`arrow-up-right](https://etherscan.io/address/0x50791a5cA041b9D6Dd03e64E3Fa0e34a376759AC) BT and CT share the same expiry (May 7, 2026) and are minted/burned in pairs via the YieldContractFactory. [hashtag](https://docs.fira.money/developers/deployment#core-protocol-contracts) Core protocol contracts ------------------------------------------------------------------------------------------------------------- Contract Address Description FiraRouterV4 [`0xFF615E63aAF2d1B1EE4AdFD34a5840747185d8A0`arrow-up-right](https://etherscan.io/address/0xFF615E63aAF2d1B1EE4AdFD34a5840747185d8A0) Main entry point for all user operations USDCFW (FW) [`0x62F5366C9E21A95326C461a098a408e034e017b3`arrow-up-right](https://etherscan.io/address/0x62F5366C9E21A95326C461a098a408e034e017b3) Wrapped Standardized Yield token for USDC SisuVault [`0x50791a5cA041b9D6Dd03e64E3Fa0e34a376759AC`arrow-up-right](https://etherscan.io/address/0x50791a5cA041b9D6Dd03e64E3Fa0e34a376759AC) ERC-4626 vault aggregating yield across markets LiquidityInjector [`0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5`arrow-up-right](https://etherscan.io/address/0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5) Sole BT supplier to fixed-rate markets RehypothecationModule [`0xad332515d9c82438BBa0e9FAA9486B52A33a7Ac8`arrow-up-right](https://etherscan.io/address/0xad332515d9c82438BBa0e9FAA9486B52A33a7Ac8) Controls phi ratios for rebalancing YieldContractFactory [`0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be`arrow-up-right](https://etherscan.io/address/0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be) Deploys BT/CT pairs FiraMarketFactory [`0xBF1EfC2199ae9EE1B6f5060a45D4440157E49744`arrow-up-right](https://etherscan.io/address/0xBF1EfC2199ae9EE1B6f5060a45D4440157E49744) Deploys AMM markets BCLpOracle [`0xfEAAEC9124FB007d7c44Ed704A08d24b264de921`arrow-up-right](https://etherscan.io/address/0xfEAAEC9124FB007d7c44Ed704A08d24b264de921) Oracle for BC/LP pricing AdaptiveCurveIrm [`0x73C288826347af3718e6F09c2A24AaFDA77684cD`arrow-up-right](https://etherscan.io/address/0x73C288826347af3718e6F09c2A24AaFDA77684cD) Interest rate model for variable-rate markets FIRA Yield Treasury [`0x97fD565B913b439Ff16774Da152B1f71F05A82F1`arrow-up-right](https://etherscan.io/address/0x97fD565B913b439Ff16774Da152B1f71F05A82F1) Fee recipient [hashtag](https://docs.fira.money/developers/deployment#lending-markets) Lending markets --------------------------------------------------------------------------------------------- Contract Address Description VariableLendingMarket [`0xc8Db629192a96D6840e88a8451F17655880A2e4D`arrow-up-right](https://etherscan.io/address/0xc8Db629192a96D6840e88a8451F17655880A2e4D) Variable-rate lending (wstETH, cbBTC collateral) FiraLendingMarket [`0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e`arrow-up-right](https://etherscan.io/address/0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e) Fixed-rate lending (PT collateral, BT loan token) [hashtag](https://docs.fira.money/developers/deployment#amm-market) AMM market ----------------------------------------------------------------------------------- Field Value FiraMarket [`0xde00b5edb255078dd42ee94fd97f473d1c9c055d`arrow-up-right](https://etherscan.io/address/0xde00b5edb255078dd42ee94fd97f473d1c9c055d) BT [`0x57FFbb88f0c69283531a751BE6FF0741348371bA`arrow-up-right](https://etherscan.io/address/0x57FFbb88f0c69283531a751BE6FF0741348371bA) FW [`0x62F5366C9E21A95326C461a098a408e034e017b3`arrow-up-right](https://etherscan.io/address/0x62F5366C9E21A95326C461a098a408e034e017b3) Expiry May 7, 2026 (`1778112000`) scalarRoot `102406700000000000000` initialAnchor `1008276800000000000` lnFeeRateRoot `2996000000000000` [hashtag](https://docs.fira.money/developers/deployment#variable-rate-markets) Variable-rate markets --------------------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/deployment#wsteth-usdc) wstETH / USDC Field Value Lending Market [`0xc8Db629192a96D6840e88a8451F17655880A2e4D`arrow-up-right](https://etherscan.io/address/0xc8Db629192a96D6840e88a8451F17655880A2e4D) Market ID `0xB3152AC00687CC9502B78AB452956F85CC89AC210DEEFDA5DBFF09F7F167B544` Loan Token USDC ([`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`arrow-up-right](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) ) Collateral Token wstETH ([`0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0`arrow-up-right](https://etherscan.io/address/0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0) ) Oracle [`0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2`arrow-up-right](https://etherscan.io/address/0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2) (Morpho wstETH/USDC) IRM [`0x73C288826347af3718e6F09c2A24AaFDA77684cD`arrow-up-right](https://etherscan.io/address/0x73C288826347af3718e6F09c2A24AaFDA77684cD) (AdaptiveCurveIrm) LTV 87% LLTV 89% Whitelist None (permissionless) ### [hashtag](https://docs.fira.money/developers/deployment#cbbtc-usdc) cbBTC / USDC Field Value Lending Market [`0xc8Db629192a96D6840e88a8451F17655880A2e4D`arrow-up-right](https://etherscan.io/address/0xc8Db629192a96D6840e88a8451F17655880A2e4D) Market ID `0x39D3BDD30BF4BCF4A4D3547F2484ABE1E30A2DCD41ED83788B40E2720357AB76` Loan Token USDC ([`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`arrow-up-right](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) ) Collateral Token cbBTC ([`0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf`arrow-up-right](https://etherscan.io/address/0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf) ) Oracle [`0x698253A24CC4926090f841B38D31d6342A00a82C`arrow-up-right](https://etherscan.io/address/0x698253A24CC4926090f841B38D31d6342A00a82C) (ChainlinkOracleV2 cbBTC/USDC) IRM [`0x73C288826347af3718e6F09c2A24AaFDA77684cD`arrow-up-right](https://etherscan.io/address/0x73C288826347af3718e6F09c2A24AaFDA77684cD) (AdaptiveCurveIrm) LTV 88% LLTV 90% Whitelist None (permissionless) [hashtag](https://docs.fira.money/developers/deployment#fixed-rate-markets) Fixed-rate markets --------------------------------------------------------------------------------------------------- Both fixed-rate markets use the FiraLendingMarket at [`0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e`arrow-up-right](https://etherscan.io/address/0x280ddD897F39C33fEf1CbF863B386Cb9a8e53a0e) . BT is the loan token. Only the LiquidityInjector can supply BT (whitelist-gated). ### [hashtag](https://docs.fira.money/developers/deployment#pt-usde-bt) PT-USDe / BT Field Value Loan Token BT ([`0x57FFbb88f0c69283531a751BE6FF0741348371bA`arrow-up-right](https://etherscan.io/address/0x57FFbb88f0c69283531a751BE6FF0741348371bA) ) Collateral Token PT-USDe ([`0xAeBf0Bb9f57E89260d57f31AF34eB58657d96Ce0`arrow-up-right](https://etherscan.io/address/0xAeBf0Bb9f57E89260d57f31AF34eB58657d96Ce0) ) Oracle [`0xeB30b33A1aC175e0305853636D0eF3898eb530f3`arrow-up-right](https://etherscan.io/address/0xeB30b33A1aC175e0305853636D0eF3898eb530f3) (FiraSolvencyOracle) IRM `0x0000000000000000000000000000000000000000` (none — fixed rate) LTV 89% LLTV 90% Whitelist [`0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5`arrow-up-right](https://etherscan.io/address/0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5) (LiquidityInjector) Maturity Grace Period 86400 (24h) Liquidation Incentive 3.1% BT Liquidity 350 BT supplied by LI ### [hashtag](https://docs.fira.money/developers/deployment#pt-susde-bt) PT-sUSDe / BT Field Value Loan Token BT ([`0x57FFbb88f0c69283531a751BE6FF0741348371bA`arrow-up-right](https://etherscan.io/address/0x57FFbb88f0c69283531a751BE6FF0741348371bA) ) Collateral Token PT-sUSDe ([`0x3de0ff76E8b528C092d47b9DaC775931cef80F49`arrow-up-right](https://etherscan.io/address/0x3de0ff76E8b528C092d47b9DaC775931cef80F49) ) Oracle [`0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb`arrow-up-right](https://etherscan.io/address/0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb) (FiraSolvencyOracle) IRM `0x0000000000000000000000000000000000000000` (none — fixed rate) LTV 89% LLTV 90% Whitelist [`0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5`arrow-up-right](https://etherscan.io/address/0x2104f638a839Ca7260180d9Ee7f4865C92Df4cE5) (LiquidityInjector) Maturity Grace Period 86400 (24h) Liquidation Incentive 3.1% BT Liquidity 350 BT supplied by LI [hashtag](https://docs.fira.money/developers/deployment#oracle-pipeline) Oracle pipeline --------------------------------------------------------------------------------------------- ### [hashtag](https://docs.fira.money/developers/deployment#variable-rate-oracles) Variable-rate oracles Market Oracle Type wstETH/USDC [`0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2`arrow-up-right](https://etherscan.io/address/0x48F7E36EB6B826B2dF4B2E630B62Cd25e89E40e2) Morpho v1 oracle (pre-deployed, reused) cbBTC/USDC [`0x698253A24CC4926090f841B38D31d6342A00a82C`arrow-up-right](https://etherscan.io/address/0x698253A24CC4926090f841B38D31d6342A00a82C) ChainlinkOracleV2 (BTC/USD + USDC/USD feeds) ### [hashtag](https://docs.fira.money/developers/deployment#fixed-rate-oracle-pipeline) Fixed-rate oracle pipeline Fixed-rate markets use a 3-layer oracle stack: Layer PT-USDe PT-sUSDe AaveToChainlinkAdapter [`0xc42F003F9eCD3DdDF704556E82Cdd9271818171F`arrow-up-right](https://etherscan.io/address/0xc42F003F9eCD3DdDF704556E82Cdd9271818171F) [`0x3d7346578be9B82E0227D027bd86F6De59BA3C91`arrow-up-right](https://etherscan.io/address/0x3d7346578be9B82E0227D027bd86F6De59BA3C91) ChainlinkOracleV2 [`0x2ED527087B740530562754EFCd608290eCCdBe2e`arrow-up-right](https://etherscan.io/address/0x2ED527087B740530562754EFCd608290eCCdBe2e) [`0xD6f5D9102007A737D9EDE6543262516d5c2fc8f8`arrow-up-right](https://etherscan.io/address/0xD6f5D9102007A737D9EDE6543262516d5c2fc8f8) FiraSolvencyOracle [`0xeB30b33A1aC175e0305853636D0eF3898eb530f3`arrow-up-right](https://etherscan.io/address/0xeB30b33A1aC175e0305853636D0eF3898eb530f3) [`0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb`arrow-up-right](https://etherscan.io/address/0xB9bAA3D58E1431776218F39919fd21AeD3e69aBb) ### [hashtag](https://docs.fira.money/developers/deployment#chainlink-feeds) Chainlink feeds Feed Address BTC/USD [`0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c`arrow-up-right](https://etherscan.io/address/0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c) USDC/USD [`0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6`arrow-up-right](https://etherscan.io/address/0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6) [hashtag](https://docs.fira.money/developers/deployment#router-facets) Router facets ----------------------------------------------------------------------------------------- The FiraRouterV4 uses a facet-based (diamond-like) architecture. All user-facing calls go through the Router, which delegates to the appropriate facet. Facet Address Functions ActionSwapBTV3 [`0xab2383692ed8e0836e25b71988c925dfd94ed2fe`arrow-up-right](https://etherscan.io/address/0xab2383692ed8e0836e25b71988c925dfd94ed2fe) BT swaps ActionSwapCTV3 [`0xdb7a722ae7baf83d3d8b9e812952916326d6656b`arrow-up-right](https://etherscan.io/address/0xdb7a722ae7baf83d3d8b9e812952916326d6656b) CT swaps ActionAddRemoveLiqV3 [`0x286bbc5519cd421011e7e1c092e1d6a72edb4d30`arrow-up-right](https://etherscan.io/address/0x286bbc5519cd421011e7e1c092e1d6a72edb4d30) Liquidity add/remove ActionCallbackV3 [`0x2dead5b19935d7299d7077c52f2e2860370278a5`arrow-up-right](https://etherscan.io/address/0x2dead5b19935d7299d7077c52f2e2860370278a5) Internal swap callbacks ActionSimple [`0x4474886d003abcb53c307324894c074ce5176f75`arrow-up-right](https://etherscan.io/address/0x4474886d003abcb53c307324894c074ce5176f75) Simple token transfers ActionMiscV3 [`0x967234d7a4416380107da653e5d3afc9c7bf8874`arrow-up-right](https://etherscan.io/address/0x967234d7a4416380107da653e5d3afc9c7bf8874) FW/BC minting, simulate ActionBorrow [`0x66f5853cf6c36b97e754f074397d00b78253ef03`arrow-up-right](https://etherscan.io/address/0x66f5853cf6c36b97e754f074397d00b78253ef03) Borrow/repay ActionStorageV4 [`0x0386685eA7d37c61dDb8F2e2E8c45f6a81d4A3C8`arrow-up-right](https://etherscan.io/address/0x0386685eA7d37c61dDb8F2e2E8c45f6a81d4A3C8) Router admin [hashtag](https://docs.fira.money/developers/deployment#factory-contracts) Factory contracts ------------------------------------------------------------------------------------------------- Contract Address ChainlinkOracleV2Factory [`0x7783fF7bE856C7A82bC5497Fb3CC8F7E8802D8dC`arrow-up-right](https://etherscan.io/address/0x7783fF7bE856C7A82bC5497Fb3CC8F7E8802D8dC) SisuVaultFactory [`0xe77E0f97A864558e5513209323e4169FcEAC6981`arrow-up-right](https://etherscan.io/address/0xe77E0f97A864558e5513209323e4169FcEAC6981) YieldContractFactory [`0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be`arrow-up-right](https://etherscan.io/address/0xcdB83Abb9121c04589567A4106C3cFaf65DB68Be) FiraMarketFactory [`0xBF1EfC2199ae9EE1B6f5060a45D4440157E49744`arrow-up-right](https://etherscan.io/address/0xBF1EfC2199ae9EE1B6f5060a45D4440157E49744) [hashtag](https://docs.fira.money/developers/deployment#key-roles) Key roles --------------------------------------------------------------------------------- Role Address SisuVault Curator [`0xc02B0D1ca7B986E63cf1599F9c32e8A96c2D4Cff`arrow-up-right](https://etherscan.io/address/0xc02B0D1ca7B986E63cf1599F9c32e8A96c2D4Cff) (Markov Labs) SisuVault Allocator [`0x4E700A14868620a9Bba0669721F1945c410c7571`arrow-up-right](https://etherscan.io/address/0x4E700A14868620a9Bba0669721F1945c410c7571) (Markov Labs) FIRA Yield Treasury [`0x97fD565B913b439Ff16774Da152B1f71F05A82F1`arrow-up-right](https://etherscan.io/address/0x97fD565B913b439Ff16774Da152B1f71F05A82F1) Deployer EOA [`0x7Da82CBD315923d75dbb2C62F099392705FF97f9`arrow-up-right](https://etherscan.io/address/0x7Da82CBD315923d75dbb2C62F099392705FF97f9) [PreviousAuditschevron-left](https://docs.fira.money/developers/security-and-audits/audits) [NextGlossarychevron-right](https://docs.fira.money/developers/glossary) Last updated 1 day ago * [External tokens](https://docs.fira.money/developers/deployment#external-tokens) * [Fira tokens](https://docs.fira.money/developers/deployment#fira-tokens) * [Core protocol contracts](https://docs.fira.money/developers/deployment#core-protocol-contracts) * [Lending markets](https://docs.fira.money/developers/deployment#lending-markets) * [AMM market](https://docs.fira.money/developers/deployment#amm-market) * [Variable-rate markets](https://docs.fira.money/developers/deployment#variable-rate-markets) * [wstETH / USDC](https://docs.fira.money/developers/deployment#wsteth-usdc) * [cbBTC / USDC](https://docs.fira.money/developers/deployment#cbbtc-usdc) * [Fixed-rate markets](https://docs.fira.money/developers/deployment#fixed-rate-markets) * [PT-USDe / BT](https://docs.fira.money/developers/deployment#pt-usde-bt) * [PT-sUSDe / BT](https://docs.fira.money/developers/deployment#pt-susde-bt) * [Oracle pipeline](https://docs.fira.money/developers/deployment#oracle-pipeline) * [Variable-rate oracles](https://docs.fira.money/developers/deployment#variable-rate-oracles) * [Fixed-rate oracle pipeline](https://docs.fira.money/developers/deployment#fixed-rate-oracle-pipeline) * [Chainlink feeds](https://docs.fira.money/developers/deployment#chainlink-feeds) * [Router facets](https://docs.fira.money/developers/deployment#router-facets) * [Factory contracts](https://docs.fira.money/developers/deployment#factory-contracts) * [Key roles](https://docs.fira.money/developers/deployment#key-roles) Copy AaveToChainlinkAdapter → ChainlinkOracleV2 → FiraSolvencyOracle → FiraLendingMarket --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address docs.fira.money ----------------------------------------------------------- The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/) * [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/) Cloudflare Ray ID: **9de825d56b4987a3** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) ---