# Settlement & Conservation ## Overview The `Structure` is the accounting brain of a deal: it owns each class's NAV and the rules by which NAV may change. There are exactly three ways class NAV moves: 1. **Serviced deposits** (+) — new principal joins its class directly; no waterfall runs. 2. **Processed exits** (−) — filled redemptions debit their class at the conservative price. 3. **Settlement** (±) — reporter deltas since the last checkpoint, routed through the waterfall. Every other operation is required to be value-neutral; any deviation reverts. ## Settlement, step by step ```mermaid flowchart LR R["Reporters
per-strategy values"] --> D["Deltas vs stored
checkpoints"] D --> W["Waterfall
split(flows, classNavs)"] W --> N["New class NAVs
written + checkpoints advanced"] ``` 1. Each strategy's reporter is read in the deal's pinned pricing mode. **Stale reports and version rollbacks revert** — settlement cannot proceed on bad data. 2. Deltas against the stored checkpoints are decomposed into flows: pro-rata value (idle yield), waterfall value (credit performance), and impairment signal. 3. The waterfall allocates the credit delta across classes by seniority — losses junior-tier first, recoveries senior-tier first against the absorbed-loss ledger, residual gains to the junior tier (interest never routes here; it is off-chain, paid as coupon). 4. The `Structure` verifies **conservation**: the class deltas must sum exactly to the delta given. `WaterfallNotConserved` reverts otherwise; the waterfall module supplies policy while the `Structure` enforces authority. 5. New NAVs and checkpoints are written atomically. **Settlement-first everywhere**: deposit servicing, exit processing, and every strategy movement run settlement before pricing, so no one ever transacts at a stale mark. ## Value-neutral movements Moving capital between the deal's cash and a strategy is a mechanical movement: ``` fundStrategy(id, 100): reported strategy value must rise by exactly 100 observed asset outflow must equal exactly 100 → any deviation reverts (MovementCreatedValue / MovementShortfall / AssetMovementMismatch) ``` The checkpoint is re-baselined at the post-movement report, so the next settlement sees a clean gain/loss baseline. River charges no entry or movement fees; a clean movement lands exactly on expectation. ## Rounding and residuals Pro-rata gains round down per class; pro-rata losses round up per class (bounded by remaining loss); the residual in both directions lands on the most junior class. Allocation is exactly conservative: applied deltas always sum to the input delta, to the wei. ## Worked example Senior interest is off-chain (paid as coupon through the distributing class token), so a reported gain is the junior residual and senior NAV stays at par until a loss pierces the cushion. ``` Classes: Senior 80 / Junior 20 (total 100). Strategy reports +6 waterfall value. Waterfall (junior residual): Senior: +0 → Senior NAV 80 (par principal; its interest is coupon) Residual to junior: +6 → Junior NAV 26 Conservation check: 0 + (26-20) = 6 = reported delta ✓ Next report: −30 (realized credit loss). Junior absorbs first: −26 → Junior NAV 26 → 0 (the whole cushion, residual included) Senior absorbs rest: −4 → Senior NAV 80 → 76 Conservation check: −26 + −4 = −30 ✓ (the −26/−4 split is recorded as absorbed loss per class, so a later recovery restores senior-first against exactly it) ``` More scenarios, including recoveries and multi-tier stacks, in [Waterfall Scenarios](/waterfall/scenarios) and [Accounting Examples](/accounting/examples).