# KairosSwap

> KairosSwap is a DeFi protocol for on-chain interest rate swaps on Base. Users trade interest rate movements with leverage, hedge interest rate risk, and lock in fixed yields. The protocol operates as a peer-to-pool model where buyers trade swaps against an LP (liquidity provider) pool.

## Overview

KairosSwap enables two-sided interest rate swap markets:

- **BUY_FIXED**: Buyer locks a fixed rate, LP receives floating rate
- **BUY_FLOATING**: Buyer locks a floating rate, LP receives fixed rate

Both sides are collateralized. Rates are sourced from on-chain oracles tracking lending protocol rates (Aave, Compound, Morpho) and off-chain rates (SOFR via Pyth).

- [Protocol Documentation](https://kairosswap.com/llms-full.txt)

## Key Pages

- [Markets (Home)](https://kairosswap.com/): Browse all active interest rate swap markets with live rates, liquidity, and APY data
- [Market Detail](https://kairosswap.com/market/{marketId}): View a specific market with rate charts, order widget, and open positions
- [Portfolio](https://kairosswap.com/portfolio): View your open and settled swap positions, P&L, collateral balances, and Krystals
- [Leaderboard](https://kairosswap.com/leaderboard): Trading leaderboard ranked by Krystals earned from successful trades
- [Earn (Vaults)](https://kairosswap.com/earn): Browse and deposit into LP vaults to earn yield by providing swap liquidity
- [Vault Detail](https://kairosswap.com/earn/{vaultAddress}): Deposit or withdraw from a specific LP vault, view allocation and performance
- [Faucet](https://kairosswap.com/faucet): Mint test tokens on testnet for development
- [Careers](https://kairosswap.com/careers): Open positions at KairosSwap
- [Terms](https://kairosswap.com/terms): Terms of service

## User Actions

### For Buyers (Traders)
- **Buy a Swap**: Choose a market direction (fixed or floating), set notional amount, deposit collateral
- **Monitor Positions**: Track open swaps, unrealized P&L, collateral health
- **Early Exit**: Close a swap before maturity (subject to discount factor and fees)
- **Settle**: Collect payout when a swap reaches maturity
- **Claim Krystals**: Earn KairosTimeKrystals tokens for completed swaps

### For LPs (Liquidity Providers)
- **Supply Collateral**: Deposit tokens into LP pool, receive shares priced mark-to-market
- **Withdraw Collateral**: Redeem shares for underlying tokens (subject to available liquidity)
- **Vault Deposits**: Use managed vaults that allocate across multiple markets

## Protocol Concepts

- **Notional Amount**: The face value of a swap used to calculate payments
- **Swap Rate**: The all-in rate locked by the buyer (base rate + utilization fee + risk premium)
- **Collateral**: Tokens deposited by both buyer and LP to back swap obligations
- **Liquidation Threshold**: The collateral ratio below which a position can be liquidated (permissionless)
- **Utilization Fee**: A kinked fee model that increases as LP pool utilization rises
- **Mark-to-Market Share Price**: LP shares are priced based on projected P&L of active swaps
- **Swap Term**: Duration of the swap in seconds (set per market)
- **Krystals**: Achievement tokens earned by completing swaps successfully

## Technical Details

- **Network**: Base (Ethereum L2)
- **Smart Contracts**: Solidity 0.8.20, deployed via Hardhat
- **Frontend**: Next.js 15, React 19, wagmi/viem for wallet interaction
- **Oracles**: Aave, Compound, Morpho on-chain rate oracles; Pyth for SOFR
- **Precision**: WAD (1e18) for all rates and factors
- **Settlement**: Permissionless - anyone can trigger settlement on mature swaps

## Resources

- [Documentation](https://docs.kairosswap.com): Protocol documentation and guides
- [What are Krystals?](https://docs.kairosswap.com/kairos-quests/time-krystals): Learn about the Krystals achievement system