> For the complete documentation index, see [llms.txt](https://knox-fi.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knox-fi.gitbook.io/docs/settlement-waterfall.md).

# Settlement Waterfall

The settlement waterfall is the algorithm that distributes pool assets to tranches at maturity. It's a two-phase priority system with floors and caps.

## Phase 1: Protocol Fee

Before any tranche receives assets, the protocol fee is deducted from total pool yield.

### Calculation

```
totalYield = withdrawnAssets - totalDeposits // floored at 0
protocolFee = totalYield × cProtocolFee /10000 // only if applyProtocolFees enabled
distributable = withdrawnAssets - protocolFee
```

### Key Points

* Fee is charged on total pool yield, not just junior/spectrum profits
* Fee is deducted before the waterfall runs
* If there's no yield (`withdrawnAssets ≤ totalDeposits`), fee is zero
* Fee cost is effectively borne by riskiest positions (highest spectrum + junior) since they get the residual

### Example

Scenario: $1M deposited, $1.1M withdrawn, 10% protocol fee

```
totalYield = $1.1M - $1M = $100k
protocolFee = $100k × 10% = $10k
distributable = $1.1M - $10k = $1.09M
```

The remaining $1.09M flows through the waterfall.

## Phase 2: Floor-Based Waterfall

The distributable amount is allocated in two steps: reserve floors, then distribute surplus.

### Step 1: Reserve Floors

Each tranche has a protected floor based on its collateral factor.

#### Floor Formulas

| Tranche  | Floor Calculation                   | Typical Value     |
| -------- | ----------------------------------- | ----------------- |
| Senior   | totalDeposits                       | 100% of deposits  |
| Spectrum | deposits × (1 − CF / 10000)         | 0-50% of deposits |
| Junior   | deposits × (1 − CF\_junior / 10000) | 0% (CF = 100%)    |

Collateral Factor (CF) is the portion of deposits pledged as backing for senior. The floor is the un-pledged portion.

#### Floor Allocation

If distributable ≥ sum of all floors:

* Each tranche gets at least its floor
* Proceed to Step 2 with remaining surplus

If distributable < sum of all floors:

* Floors are allocated pro-rata by size
* No surplus to distribute (skip Step 2)

### Step 2: Distribute Surplus Top-Down

After floors are reserved, remaining surplus is distributed from safest to riskiest:

#### Distribution Order

Senior → up to full compounded value

```
seniorCap =compoundAssets(totalDeposits + accumulatedYield, rSenior, elapsed, period)
```

Spectrum (lowest rate → highest) → each up to capped return

```
spectrumCap =compoundAssets(deposits, apyCap, elapsed, period)
```

Junior → all remaining surplus (unlimited)

#### Partial Fills

If surplus runs out mid-tranche:

* That tranche receives whatever remains
* All lower-priority tranches receive only their floor (if any)

## Waterfall Scenarios

### Scenario A: Strong Yield (Above All Caps)

Setup: $1M total deposits, underlying returns +15%, senior at 5%, spectrum at 10%, junior $200k

Withdrawals: $1.15M

Distribution:

* Protocol fee (10%): $15k × 10% = $1.5k → Fee beneficiary
* Distributable: $1.15M - $1.5k = $1.1485M
* Senior floor: $500k ✓ (covered)
* Spectrum floor: $150k × 50% = $75k ✓ (covered)
* Junior floor: $200k × 0% = $0 ✓ (covered)
* Senior cap: $500k × 1.05 = $525k → Senior gets $525k
* Spectrum cap: $150k × 1.10 = $165k → Spectrum gets $165k
* Junior residual: $1.1485M - $525k - $165k = $458.5k → Junior gets $458.5k

P\&L Summary:

* Senior: +$25k (5% achieved)
* Spectrum: +$15k (10% achieved)
* Junior: +$258.5k (129% return!)
* Protocol: +$1.5k fee

### Scenario B: Moderate Yield (Between Senior and Spectrum)

Setup: Same as above, underlying returns +7%

Withdrawals: $1.07M

Distribution:

* Protocol fee: $7k × 10% = $700
* Distributable: $1.07M - $700 = $1.0693M
* Floors: All covered ($575k total)
* Senior cap: $525k → Senior gets $525k
* Spectrum cap: $165k, but only $1.0693M - $525k = $544.3k left → Spectrum gets $165k
* Junior residual: $544.3k - $165k = $379.3k → Junior gets $379.3k

P\&L Summary:

* Senior: +$25k (5% achieved)
* Spectrum: +$15k (10% achieved)
* Junior: +$179.3k (89.7% return)
* Protocol: +$700 fee

### Scenario C: Below Senior Rate (Positive)

Setup: Same, underlying returns +3%

Withdrawals: $1.03M

Distribution:

* Protocol fee: $3k × 10% = $300
* Distributable: $1.03M - $300 = $1.0297M
* Floors: All covered
* Senior cap: $525k → Senior gets $525k
* Spectrum cap: $165k, but only $1.0297M - $525k = $504.7k left → Spectrum gets $165k
* Junior residual: $504.7k - $165k = $339.7k → Junior gets $339.7k

P\&L Summary:

* Senior: +$25k (5% achieved) ✓
* Spectrum: +$15k (10% achieved) ✓
* Junior: +$139.7k (69.9% return)
* Protocol: +$300 fee

Note: Even though market returned only 3%, senior gets its guaranteed 5% because junior absorbed the shortfall.

### Scenario D: Severe Loss

Setup: Same, underlying returns -20%

Withdrawals: $800k

Distribution:

* Protocol fee: $0 (no yield)
* Distributable: $800k
* Floors needed: $575k (senior $500k + spectrum $75k)
* Distributable < total floors → Pro-rata allocation:
  * Senior floor: $500k / $575k × $800k = $695.7k
  * Spectrum floor: $75k / $575k × $800k = $104.3k
  * Junior floor: $0 → Junior gets $0 (wiped out)

P\&L Summary:

* Senior: -$304.3k (-60.9% loss) — impaired!
* Spectrum: -$45.7k (-30.5% loss)
* Junior: -$200k (-100% loss, wiped out)
* Protocol: $0 fee

Loss absorption order: Junior wiped first, then spectrum (higher rates first), then senior.

## Loss Absorption Hierarchy

When the pool loses money, tranches absorb losses in reverse priority:

* Junior — wiped first (no floor if CF = 100%)
* Spectrum (highest rate → lowest) — absorb losses down to their floor
* Senior — only impaired in extreme scenarios

### Example: $1M pool, -30% loss, $700k withdrawn

Deposits: Senior $500k, Spectrum 10% $200k, Junior $300k

Floor allocation:

* Junior floor: $0 (CF = 100%)
* Spectrum floor: $200k × (1 - 0.75) = $50k (CF = 75%)
* Senior floor: $500k
* Total floors: $550k

Distributable: $700k (covers floors)

Distribution:

* Floors: Senior $500k, Spectrum $50k, Junior $0
* Surplus: $700k - $550k = $150k
* Senior cap: $525k, needs $25k more → gets $25k
* Spectrum cap: $220k, needs $170k more → gets $125k (partial fill)
* Junior: $0 (wiped)

Final payouts:

* Senior: $525k (full guaranteed return) ✓
* Spectrum: $175k (-$25k loss, -12.5%)
* Junior: $0 (-$300k loss, -100%)

## Visual Flow Diagram

```
Withdrawn Assets($X)
↓
Protocol Fee?(only ifyield>0&& feeSwitch =true)
↓
Distributable
↓
┌─────────────────┐
│ Step 1: Floors │
└─────────────────┘
↓
Enough to cover all?
↓
YES ─────→ Reserve all floors → Surplus
↓ ↓
NO ┌──────────────────┐
↓ │ Step 2: Surplus │
└→ Pro-rata floors └──────────────────┘
↓
Senior(up to cap)
↓
Spectrum low→high(up to cap)
↓
Junior(all remaining)
```

## Key Takeaways

* Two-phase: Protocol fee first (if active), then floor-based waterfall
* Floors protect: Each tranche has a minimum claim (except junior with CF=100%)
* Surplus priority: Senior → Spectrum (low to high) → Junior
* Loss absorption: Reverse order — Junior → Spectrum (high to low) → Senior
* Protocol fee: Taken from total yield, not just profits
* Time-weighted: All caps are compounded based on holding period