# Overview

## Kairos Protocol Documentation

Kairos is a decentralized interest rate swap AMM. Traders open positions that pay or receive a stream of interest payments indexed to an on-chain rate oracle; LPs supply the collateral that backs the other side of those payments.

This documentation is written for the people who interact with the protocol on-chain:

* **Traders / buyers** — how to open a swap, manage it, settle it at expiry, or exit early.
* **LPs** — how the shared pool works, how shares are priced, and what gates sit in front of deposits and withdrawals.
* **Market creators** — how to create a BUY\_FIXED / BUY\_FLOATING market pair and manage ownership over time.
* **Integrators** — how the `onBehalfOf` authorization pattern lets bundlers, routers, wrappers, and vault adapters act on behalf of end users.
* **Keepers / liquidators** — what to watch for and how to settle or liquidate positions.
* **Indexers** — the events emitted across every lifecycle transition.

## SwapCore

`SwapCore.sol` is the heart of Kairos. It owns the full lifecycle of an interest rate swap: market creation, liquidity provisioning, opening positions, settlement, early exit, and liquidation. Everything a user, LP, keeper, or integrator does on-chain flows through one of its \~28 external functions.

This chapter is a function-by-function reference. Start here for the mental model, then jump to the page that matches your role.

### What SwapCore does

Kairos is a **decentralized interest rate swap AMM**. Traders enter positions that pay or receive a stream of interest payments indexed to an on-chain rate oracle, and LPs supply the collateral that backs the other side of those payments.

Every rate market that SwapCore creates is actually a **pair**:

* **BUY\_FIXED** — the buyer pays a locked-in fixed rate and receives the floating rate (from the reference rate oracle). Useful for hedging variable-rate exposure or speculating that rates will rise.
* **BUY\_FLOATING** — the buyer pays the floating rate and receives a locked-in fixed rate. Useful for locking in a yield or speculating that rates will fall.

Both sides of the pair share the same reference rate oracle, base rate oracle, collateral token, swap term, and leverage multiplier. LPs supply collateral to a single, share-based pool per market; buyers post their own collateral when they open a swap. The pool uses **time buckets** (`numBuckets` × `bucketInterval`) to aggregate mark-to-market P\&L so share prices stay tractable even with many open positions.

Three inputs determine the all-in rate a buyer locks in at `buySwap`:

1. **Base rate** from the base swap rate oracle (tenor-dependent)
2. **Utilization fee** — a kinked curve integrated over the range `[uPre, uPost]` as the swap consumes pool capacity
3. **Risk premium** — an optional oracle-supplied markup, different per side of the pair

### Actors

| Actor                       | What they do                                                                                                                                                                | Key functions                                                                                                                                                                                                                                                                      |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Market owner**            | Creates a market pair, optionally manages an LP whitelist, can terminate the market (stop new swaps). Receives a share of protocol fees if creator fee is configured.       | [`createMarket`](/protocol/market-admin.md#createmarket), [`transferMarketOwnership`](/protocol/market-admin.md#transfermarketownership), [`terminateMarket`](/protocol/market-admin.md#terminatemarket), [`setMarketLpWhitelist`](/protocol/market-admin.md#setmarketlpwhitelist) |
| **Liquidity Provider (LP)** | Deposits the market's collateral token into the pool, receives shares priced at the pool's current mark-to-market value, earns yield from swap fees and settlement inflows. | [`supplyCollateral`](/protocol/liquidity.md#supplycollateral), [`withdrawCollateral`](/protocol/liquidity.md#withdrawcollateral)                                                                                                                                                   |
| **Buyer**                   | Opens a swap by posting collateral, holds the position until expiry, and receives the net payment (or pays it) at settlement. Can transfer or (if enabled) exit early.      | [`buySwap`](/protocol/swaps.md#buyswap), [`transferSwapPosition`](/protocol/swaps.md#transferswapposition), [`exitSwapEarly`](/protocol/swaps.md#exitswapearly), [`claimEscrow`](/protocol/swaps.md#claimescrow)                                                                   |
| **Keeper**                  | Permissionless role. Settles swaps at expiry in batches to keep the pool's accounting current. Anyone can do this — there is no keeper whitelist.                           | [`makePayment`](/protocol/swaps.md#makepayment), [`updateMarketRateIndex`](/protocol/views.md#updatemarketrateindex)                                                                                                                                                               |
| **Liquidator**              | Permissionless role. Calls `liquidateSwap` on an underwater position to recover the shortfall and collect the market's `liquidationIncentive`.                              | [`liquidateSwap`](/protocol/swaps.md#liquidateswap)                                                                                                                                                                                                                                |
| **Integrator / bundler**    | Contracts that act on behalf of end users (vault adapters, wrappers, routers). Must be pre-authorized by the end user via `setAuthorization` for any `onBehalfOf` call.     | [`setAuthorization`](/protocol/authorization.md#setauthorization), all `onBehalfOf` entry points                                                                                                                                                                                   |

### End-to-end lifecycle

A swap's life runs through five phases. The function names below link to their reference entries.

#### 1. Market setup

The market owner calls [`createMarket`](/protocol/market-admin.md#createmarket) with oracle addresses, collateral token, leverage, swap term, fee-curve parameters, bucket configuration, and optional whitelist flag. SwapCore deploys **both** sides of the market pair (BUY\_FIXED + BUY\_FLOATING) atomically, charges the protocol's market creation fee (if configured in `Admin`), and initializes the pool, buckets, and rate index for each side.

Ownership can be handed off later via [`transferMarketOwnership`](/protocol/market-admin.md#transfermarketownership) + [`acceptMarketOwnership`](/protocol/market-admin.md#acceptmarketownership) (2-step), or the market can be permanently closed to new swaps via [`terminateMarket`](/protocol/market-admin.md#terminatemarket).

#### 2. LP provisioning

LPs call [`supplyCollateral`](/protocol/liquidity.md#supplycollateral) to deposit the market's collateral token. Shares are minted at the current mark-to-market share price (floor `WAD` for an empty pool, `getPoolSharePrice(marketId)` otherwise). A 1-block deposit lock prevents same-block deposit+withdraw flash-loan attacks.

Withdrawals happen through [`withdrawCollateral`](/protocol/liquidity.md#withdrawcollateral), which burns shares and transfers the proportional amount of underlying collateral. The withdrawal is blocked if the pool has **expired unsettled swaps** (because the share price would be stale) or if the pool has **active swaps and is underwater at `MIN_SHARE_PRICE`** (to prevent dilution attacks).

The last LP cannot take the pool's share count to zero while there are still active swaps — a single share is retained to keep accounting alive.

#### 3. Opening a swap

A buyer calls [`buySwap`](/protocol/swaps.md#buyswap) with the target market, notional amount, and two slippage guards:

* `rateBound` — ceiling on the locked-in rate for BUY\_FIXED, floor on the base rate for BUY\_FLOATING. Pass `type(int256).max` to disable.
* `maxMarkup` — ceiling on `utilFee + riskPremium`. Pass `0` to disable.

SwapCore reads the base rate and reference rate from their oracles, computes the utilization fee by integrating the kinked fee curve across the capacity the new swap consumes, adds the risk premium, and produces the final `swapRate`. It then derives the required **buyer collateral** (sized to cover the buyer's maximum payment) and **LP collateral backing** (sized to cover the LP's maximum payment), checks that both are at least `minCollateral`, pulls the buyer's collateral in, and reserves the LP backing from `pool.lockedCollateral`.

The new swap is assigned to a time bucket (`(entryTimestamp / bucketInterval) % numBuckets`) so that future share-price calculations only need to iterate over buckets instead of all open swaps.

#### 4. Swap management (during the term)

* [`getSwapNetAmount`](/protocol/views.md#getswapnetamount) / [`getFreshSwapNetAmount`](/protocol/views.md#getfreshswapnetamount) — query the net payment obligation at any time.
* [`updateMarketRateIndex`](/protocol/views.md#updatemarketrateindex) — permissionlessly refresh the on-chain rate index. Anyone can call this before reading P\&L or settling.
* [`transferSwapPosition`](/protocol/swaps.md#transferswapposition) — reassign ownership of an open swap to another address.

#### 5. Swap closure

Three paths take a swap to `settled = true`. All three release collateral, zero out the bucket slot, decrement the expiry-epoch counter, and emit `SwapClosed`:

* **Normal expiry —** [**`makePayment`**](/protocol/swaps.md#makepayment)**.** Permissionless. Called after `entryTimestamp + swapTerm`. Computes the fixed and floating legs over the full term, nets them, and transfers the net to the winner. If the buyer's token transfer fails (e.g. blacklisted address), the payout is held in `escrowedCollateral[swapId]` and can be pulled later via [`claimEscrow`](/protocol/swaps.md#claimescrow). `makePayment` accepts an array of swap IDs — keepers batch.
* **Early exit —** [**`exitSwapEarly`**](/protocol/swaps.md#exitswapearly)**.** Only the swap owner (or an authorized delegate). Requires `market.earlyExitAllowed = true`. Settles using the current index, applies the market's `earlyExitFee`, and enforces per-swap `minExitAmount` slippage protection.
* **Liquidation —** [**`liquidateSwap`**](/protocol/swaps.md#liquidateswap)**.** Permissionless. Triggered when **accrued** (not projected) payments exceed the buyer's collateral balance or the LP's pool backing. The liquidator receives the market's `liquidationIncentive` out of the liquidated side's remaining collateral.

After closure the buyer can call [`claimEscrow`](/protocol/swaps.md#claimescrow) if their settlement transfer failed. Funds always go back to the original `swap.userAddress` — no admin can redirect them.

### Happy-path sequence

```mermaid
sequenceDiagram
    participant Owner as Market Owner
    participant LP
    participant Buyer
    participant SC as SwapCore
    participant Keeper

    Owner->>SC: createMarket(...)
    SC-->>Owner: (fixedMarketId, floatingMarketId)

    LP->>SC: supplyCollateral(marketId, amount, lp, minShares)
    SC-->>LP: CollateralSupplied

    Buyer->>SC: buySwap(marketId, notional, buyer, rateBound, maxMarkup)
    SC-->>Buyer: SwapCreated (swapId)

    Note over SC: swap accrues P&L against oracle index

    Keeper->>SC: updateMarketRateIndex(marketId)
    Keeper->>SC: makePayment([swapId])
    SC-->>Buyer: net payment (or LP, depending on direction)
    SC-->>Keeper: SwapClosed
```

### Data structures you'll see in this chapter

All defined in `Types.sol`:

* **`Market`** — full market config: oracles, pool, fee curve, risk settings, whitelist flag, market owner, termination flag
* **`Pool`** — `(totalShares, totalCollateral, lockedCollateral)`
* **`SwapPosition`** — the swap record: marketId, owner, settled + isEarlyExit flags, collateral, notional, rates, entry timestamp, entry index, bucket backing, utilFee, riskPremium
* **`LpPosition`** — `(shares, lastDepositBlock)`
* **`Bucket`** — per-bucket aggregates (lpNotional, weighted rates/entry time/inverse index, weighted fees, totalBuyerCollateral, totalPoolBacking)
* **`ExitRequest`** — `(swapId, minExitAmount)` input to `exitSwapEarly`
* **`SettlementResult`** — `(settlementAmount, netRecipient)` returned by `makePayment` / `exitSwapEarly`
* **`RateConvention`** — how the reference rate oracle reports data: `Cumulative`, `SpotRate`, or `SpotCompoundRate`
* **`RateType`** — `BUY_FIXED = 0`, `BUY_FLOATING = 1`

### Chapter layout

| Page                                               | Covers                                                                                                                           |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [Market administration](/protocol/market-admin.md) | `createMarket`, `transferMarketOwnership`, `acceptMarketOwnership`, `terminateMarket`, `setMarketLpWhitelist`, `getAllMarketIds` |
| [Liquidity provision](/protocol/liquidity.md)      | `supplyCollateral`, `withdrawCollateral`, and all LP/pool view functions                                                         |
| [Swaps](/protocol/swaps.md)                        | `buySwap`, `makePayment`, `exitSwapEarly`, `liquidateSwap`, `transferSwapPosition`, `claimEscrow`                                |
| [Authorization](/protocol/authorization.md)        | `setAuthorization`, `isAuthorized`, and the `onBehalfOf` pattern                                                                 |
| [Views](/protocol/views.md)                        | Read-only P\&L, liquidity, oracle-index, and mapping getters                                                                     |
| [Events](/protocol/events.md)                      | Integrator-facing events emitted across the lifecycle                                                                            |


---

# Agent Instructions: 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:

```
GET https://docs.kairosswap.com/protocol/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.