# The Tiered Waterfall `TieredWaterfall` allocates waterfall-bucket losses and recoveries across classes. Interest is handled entirely **off-chain**. This module allocates credit losses and their reversals. Classes are grouped into contiguous seniority **tiers**. Losses consume the most junior tier to exhaustion before reaching a more senior one. Recoveries restore the most senior tier first. Classes inside the same tier are **pari-passu**: a loss or recovery hitting that tier is split pro-rata among them. Residual income, when any reaches this module, flows to the most junior tier. For numeric examples, see [Waterfall Scenarios](/waterfall/scenarios). ## Parameters | Parameter | Set | Meaning | | --- | --- | --- | | `tierSizes[]` | Deployment | Class count per seniority tier, ordered most senior first. Each entry must be non-zero; their sum is the Structure's class count. `[2, 1]` is a two-class pari-passu senior tier over a single junior class. A tier of size 1 degenerates to strict-sequential behavior. | Loan interest is collected off-chain by the servicer and funded on-chain as a cash coupon through the distributing class token. On-chain class NAV tracks principal at par and moves **down only on loss** and back up on recovery. Class order comes from the `Structure`: index 0 is most senior, and the last index is most junior, matching the Structure's class registration order. ## Allocation Flow The module receives decomposed `Flows` — `income` (non-credit P\&L) and `impairment` (the signed credit signal) — and applies them in a fixed order. ```mermaid flowchart TB F["Flows: income + impairment"] REC{"impairment > 0?"} R["Recovery:
restore absorbed loss
senior tier first, capped per class"] INC{"Income sign"} IP["Positive income:
residual to most junior tier,
pro-rata by NAV"] IN["Negative income:
consume NAV junior tier first
(no loss recorded)"] LOSS{"impairment < 0?"} L["New loss:
consume NAV junior tier first,
record absorbed loss"] X["If loss exceeds total NAV:
revert"] F --> REC REC -->|"yes"| R --> INC REC -->|"no"| INC INC -->|"positive"| IP --> LOSS INC -->|"negative"| IN --> LOSS INC -->|"zero"| LOSS LOSS -->|"yes"| L --> X ``` In normal operation `income` is zero — interest is off-chain — so this branch only conserves stray non-credit P\&L. Recovery surplus beyond the recorded absorbed-loss ledger folds back into income. ## Rules | Rule | Meaning | | --- | --- | | Losses are absorbed junior first. | New loss consumes the most junior tier to exhaustion before reaching a more senior tier. | | Recoveries restore senior first. | A positive credit signal restores previously absorbed loss to the most senior tier first, capped per class by what it absorbed. | | Pari-passu inside a tier. | A loss or recovery hitting a multi-class tier is split pro-rata: by available NAV for losses, by absorbed loss for recoveries. | | Absorbed loss is recorded. | Each class's absorbed principal loss is stored so a later recovery reverses it senior-first. | | Residual income goes to the most junior tier. | **This is not interest** — loan interest never routes through the waterfall (it is off-chain, paid as coupon). `income` here is a conservation backstop: stray non-credit P\&L plus recovery surplus beyond the absorbed-loss ledger, zero in normal operation. When any does reach this module, it is shared pro-rata by NAV across the most junior tier; if that tier holds no NAV, the most junior class takes it all. | | Coupon handled elsewhere. | Interest accrual and coupon payment live in the distributing class token. | ## Audit Properties | Property | How it works | | --- | --- | | Stateless module | Mutable state is the per-class absorbed-loss ledger, encoded as bytes and threaded by the Structure. The module persists nothing; it stores only immutable tier configuration. | | Called every settlement | The Structure calls the waterfall on every settlement, including zero-flow ones, and settles before every NAV-changing operation. | | Preview-safe | The Structure commits the returned state only on a real settlement and discards it on a preview, so an off-mode price preview cannot mutate the absorbed-loss ledger. | | Conservation checked outside | The caller verifies that returned class deltas sum exactly to `income + impairment`, so value is never created, destroyed, or diverted outside the class set. | | Bounded loss | A loss that exceeds total available NAV reverts with `LossExceedsNav`; class NAV can never go negative. | ## Related Mechanics | Mechanic | Handled by | | --- | --- | | Interest and coupons | Collected off-chain by the servicer, funded on-chain as a cash coupon via the distributing class token. | | Senior exit priority | Exit queue and liquidity policy. See [Withdrawals & Exits](/lenders/withdrawals). | | Cash and idle value | Pro-rata allocation inside the `Structure`. See [Settlement & Conservation](/accounting/settlement). | | Gross gain and gross loss inside one settlement | The `Structure` nets waterfall-bucket flows per settlement. See [scenario N1](/waterfall/scenarios#n1-netting-simultaneous-gain-and-loss). |