> For the complete documentation index, see [llms.txt](https://docs.kairosswap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kairosswap.com/market-architecture.md). # Market Architecture This section covers the high-level architecture for the Kairos V1 Protocol. Please view the protocol section for more details. **Market Creation** Markets are created in pairs via a public contract call, enabling the caller to create a set of corresponding markets (one sells fixed-rate swaps and the other floating-leg swaps). When a market pair is created, the market creator must pass values for the required markets parameters. The required parameters are: 1. referenceRateOracle: oracle address used to read the floating-leg index for the market. Subject to the rateConvention semantics below. 2. baseSwapRateOracle: tenor-aware oracle (getRateByTenor) used to price the fixed leg at entry and on early exits. 3. swapToken: the ERC20 used as collateral and settlement currency for the market (both sides post in this token). 4. leverageMultiplier: multiplier that determines how much LP-side notional capacity is available per unit of pool collateral. 5. swapTerm: length of swaps in seconds (uint32). All buys in this market run for exactly this duration. 6. utilFeeSlopeWad: slope (WAD) of the linear portion of the utilization fee curve — fee per unit utilization below the kink. 7. kinkUtilization: utilization level (WAD, e.g. 0.7e18 = 70%) at which the fee curve transitions from linear to quadratic. 8. maxKinkFeeWad: maximum additional fee (WAD) contributed by the quadratic portion above the kink. 9. earlyExitAllowed: boolean toggle. If false, exitSwapEarly is disabled for the market. 10. earlyExitFee: convenience fee applied at early exit. Accrues to the LP pool. 11. liquidationIncentive: portion of collateral (WAD, e.g. 0.05e18 = 5%) prefunded as the liquidator bounty. Returned to the buyer at normal expiry if the swap is never liquidated. 12. numBuckets: number of time buckets (uint32) used to aggregate active swaps for MTM / share-price math. Bucket IDs cycle via modulo over (entryTimestamp / bucketInterval). 13. bucketInterval: width of each bucket in seconds (uint32). Must satisfy bucketInterval × MAX\_ACTIVE\_WINDOWS ≥ swapTerm, with MAX\_ACTIVE\_WINDOWS = 7 (E729) — a **floor** on bucketInterval that caps how many windows can be active at once, bounding the O(occupied buckets) withdraw scan. Combined with E704 (bucketInterval ≤ swapTerm, and ≥ 1200), the valid range is roughly \[max(1200, swapTerm ÷ 7), swapTerm]. 14. fixedRiskPremiumOracle / floatingRiskPremiumOracle: optional per-side oracles (address(0) = no premium) that add a risk premium to the buyer's swap rate at entry. The two sides can have independent premium curves. 15. lpWhitelistEnabled: if true, only addresses on the per-market LP whitelist may supply collateral. 16. minCollateral: minimum collateral (uint88, in swap-token decimals) required from both the buyer and LP per swap. Must be > 0. 17. rateConvention: enum specifying how referenceRateOracle exposes its data — Cumulative (oracle returns a monotone index directly), SpotRate (oracle returns an instantaneous rate; library accumulates via simple interest), or SpotCompoundRate (oracle returns an instantaneous rate; library accumulates via continuous compounding). Set per-oracle on first use and immutable thereafter. Once initialized, all market parameters are immutable. The only post-creation mutations are administrative: ownership transfer (transferMarketOwnership / acceptMarketOwnership), termination (terminateMarket, which blocks new buys but does not change any economic parameter), and per-address entries on the LP whitelist when lpWhitelistEnabled was set true at creation. The parameters are the same for each pair of corresponding markets, with two exceptions. The first is that one of the markets will have a rateType of 0 (buyers purchase fixed-rate swaps) and the other 1 (buyers purchase floating-rate swaps). The second is the RiskPremiumOracle which compensates LPs for supplying liquidity to each side of a trade. **Market Liquidity** LPs provide liquidity by supplying the market's collateral token. The notional liquidity an LP's deposit supports is poolCollateral × leverageMultiplier × SECONDS\_IN\_YEAR / (|baseRate| × swapTerm), where leverageMultiplier is set at market creation and baseRate is read from the market's baseRate oracle for the configured swapTerm. Because each market only allows one direction of swap (fixed-payer or floating-payer) and is paired with a corresponding market for the opposite side, LPs choose which direction of rate exposure to take, rather than supplying both sides equally. This lets LPs more precisely manage their own interest-rate risk. **Fee Structure - Fixed-Rate Swaps (BUY\_FIXED)** A buyer in a BUY\_FIXED markets pays a fixed rate of baseRate + utilizationFee + riskPremium for the swap term and receives the realized floating rate. All three components are locked in at entry; the buyer's collateral is sized accordingly. * Base rate: * Utilization fee: a piecewise function of pool utilization, with a utilFeeSlopeWad linear region up to kinkUtilization and a quadratic region adding up to maxKinkFeeWad above the kink. The fee for a trade is the path-independent integral of this curve from pre-trade utilization to post-trade utilization, so splitting a trade across multiple transactions does not reduce the total fee. The shape incentivizes LPs to supply markets that are near the kink or above it. * Risk premium: an optional flat rate read from a per-side riskPremiumOracle (set to address(0) to disable). Allows market creators to price idiosyncratic risk (e.g. credit, oracle, or basis risk) on top of the base rate. **Fee Structure - Floating-Rate Swaps** Buyers pay the swap rate for each swap they purchase. The swap rate for floating-rate swaps is the sum of the reference rate, utilization fee, and fee spread for the markets. This swap rate is fixed for the term of the swap. * **Reference Rate:** The current reference rate derived from the market's oracle. Since the reference rate can change over the course of a swap term, the final rate reference rate used in the swap rate is calculated as the average floating rate over the course of the swap as derived from the market's reference rate index. * **Utilization Fee:** The purpose of the utilization fee is to calculate how much of the market's available liquidity will be consumed by the proposed trade and return a fee that accounts for the impact. This fee serves to incentivize LPs to supply additional liquidity to markets with low available liquidity. * **Fee Spread:** This fee is set during market creation and is a static fee added to every swap. This incentive LPs to supply liquidity regardless of available liquidity or market conditions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kairosswap.com/market-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.