# Protocol Architecture This is the deep protocol map. A River deal is one `Structure` plus a set of attached modules. The `Structure` owns the core ledger: class NAV, cash, settlement, deposits, exits, and strategy movement. Modules express policy around it: who can enter, how losses are allocated, which exits are processed, and how off-chain credit marks become on-chain values. The boundary is deliberate. The core ledger enforces conservation. Modules can be replaced or specialized by deal without giving them custody of class NAV. ## System map ```mermaid flowchart TB LND["Lenders"] WR["DistributingVault4626
accumulating wrapper"] CT["DistributingClassToken
one per class"] Q["Exit queues
FIFO / selective"] ST[["Structure
NAV ledger / settlement / cash"]] WF["Waterfall
losses / recoveries"] G["Gates
eligibility"] S["Strategies
Facility / idle capital"] RP["Reporters
signed marks"] AC["RiverAccessControls"] LND --> CT LND --> WR WR --> CT CT -- "deposits / exits / coupon" --> ST ST -- "sequence exits" --> Q ST -. "allocate deltas" .-> WF ST -- "fund / request / claim" --> S S -. "metrics" .-> RP RP -. "reports" .-> ST CT -. "gate checks" .-> G WR -. "gate checks" .-> G ST -. "roles" .-> AC ``` Solid arrows move value or state. Dashed arrows are checks, reports, or read-only policy calls. ## One deal, many classes Every class in a deal has its own `DistributingClassToken`. The class token is the lender-facing position: it accepts deposit requests, tracks redemption requests, exposes ERC-4626-style reads, and pays cash coupon. The `Structure` holds the class NAV ledger. Class tokens read value from the `Structure`. That separation gives River a simple invariant: ```text class token balances represent ownership Structure NAV represents value settlement is the only path that changes deal value ``` ## Structure `Structure` is the accounting core for a deal. It is responsible for: * class NAV ledgers; * liquid deal cash; * settlement from strategy reports; * deposit servicing; * exit processing; * strategy funding and return claims; * conservation checks; * role checks through `RiverAccessControls`. The `Structure` is intentionally narrow. Eligibility, tranche policy, and facility valuation live in modules. See [Settlement & Conservation](/accounting/settlement). ## Class tokens `ClassTokenBase` and `DistributingClassToken` are the class-level investor tokens. They provide: * asynchronous deposit requests; * cancellable pending deposits; * queued redemptions that keep shares locked in place; * claim pools for paid exits; * cash coupon accrual, funding, and claims; * ERC-4626-style reads for price and supply. Class token asset balances are segmented into pending deposits, coupon cash, exit claim pools, and other accounting buckets. That segmentation keeps token-held cash out of free NAV. See [Class Token Integration](/integrate/class-token) and [The Coupon Ledger](/accounting/coupon-ledger). ## Accumulating wrapper `DistributingVault4626` is an ERC-4626 wrapper over a class token. It collects coupon from the underlying class and retains it in the wrapper price. The wrapper is detached from the rest of the deal. It knows the class token alone, which makes it behave like an external protocol integration and keeps the wrapper accounting independently auditable. The wrapper supports: * synchronous wrapping; * cash-first unwrapping; * permissionless unwrap claims; * isolated exit buckets through deterministic `ControllerProxy` clones; * standard ERC-4626 reads for integrators. See [The Accumulating Wrapper](/lenders/wrapper) and [Wrapper Accounting](/accounting/wrapper). ## Waterfalls Waterfalls allocate value changes across classes. The `Structure` sends the waterfall a value delta and receives per-class deltas back. Then the `Structure` checks that the allocation conserved the input exactly. `TieredWaterfall` allocates junior-tier-first losses and senior-tier-first recoveries, with pari-passu tiers for classes that share the same seniority (a tier of size 1 is strict sequential). Interest never routes through it — it is off-chain, paid as coupon via the distributing class token. The waterfall has no asset custody and no value-creation path. A non-conserving split makes settlement revert. See [Tiered Waterfall](/waterfall). ## Strategies and reporters Strategies are where deal capital can be deployed. Reporters state what those strategies are worth. Keeping the two separate is important: * strategies move assets; * reporters state value; * the `Structure` checks strategy movement against observed balance changes. The flagship strategy is the borrowing-base `Facility`. Its reporter supplies signed marks for collateral, drawn amount, expected loss, realized loss, and related credit state. Facility draws are bounded by headroom. See [Strategies & Reporters](/technical/strategies). ## Exit queues Exit queues determine order. Pricing remains in the `Structure`. `FifoExitQueue` processes requests by arrival order. `SelectiveExitQueue` lets the servicer select which requests to fill. In both cases, the `Structure` bounds the payout by available cash and current price. Queues are non-custodial and have no independent fund movement path. ## Gates Gates are eligibility modules. They answer whether an address may perform a specific action: * deposit; * wrap; * request redemption; * receive a transfer. Claims and cancels bypass gates, so eligibility changes leave owed funds reachable. See [Actors: Roles & Permissions](/technical/actors). ## Governance and access control `RiverAccessControls` is the shared role registry. `RiverGovAuthority` executes governed actions through a timelock. `RiverPause` provides emergency pause controls. Deal economics such as class order, pricing mode, waterfall policy, and covenant terms are meant to be set at initialization. Changes to those economics should happen through explicit migration or a new deal. See [Timelock & Authority](/governance). ## Value buckets A strategy report separates value into accounting buckets. | Bucket | Typical value | Allocated by | Rule | | --- | --- | --- | --- | | Pro-rata | Cash-like yield, idle cash movement, neutral movement effects | `Structure` | By class NAV | | Waterfall | Credit losses, impairments, recoveries, facility value changes | `Waterfall` | By tranche policy | This lets a deal hold cash-like assets and credit exposure side by side without accidentally sending every cash movement through the credit waterfall. ## Custody model Assets sit in distinct custody and accounting locations. | Asset location | Where it sits | How it is valued | | --- | --- | --- | | Liquid deal cash | `Structure` | Direct balance | | Pending deposits | Class token | Outside NAV until accepted | | Coupon cash | Class token | Claimable income, outside principal NAV | | Exit claim pools | Class token | Paid proceeds, outside NAV | | Strategy capital | Strategy or downstream recipient | Reporter value settled by `Structure` | ## Upgradeability Stateful contracts use UUPS implementations behind `ERC1967Proxy`, with ERC-7201 namespaced storage and role-gated upgrade authorization. See [Proxies & Upgradeability](/technical/proxies).