Glossary
Definitions of key terms, abbreviations, and concepts used throughout the Fira Protocol documentation.
Protocol tokens
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
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
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
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
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
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
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
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.
Last updated