# Glossary ## 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. | ## 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()`. | ## 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()`. | ## 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). | ## 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. | ## 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. | ## Events & indexing | Term | Definition | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Role bucket** | One of 8 position categories used to measure user exposure across Fira markets: BFR, BT, CT, LP, VRB, VRL, USLC, USLL. Used for analytics and potential future incentive programs. | | **Epoch** | A time window (typically one week) over which TWAP exposures are measured for position tracking and analytics. | | **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. | ## 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. |