# Proxies & Upgradeability ## Pattern Every stateful River contract is a **UUPS proxy** (`ERC1967Proxy` + `UUPSUpgradeable` implementation). Upgrade authorization is enforced in the implementation's `_authorizeUpgrade`, which requires `UPGRADER_ROLE` in the relevant `RiverAccessControls` — held by the timelocked governance authority, so every upgrade is delayed and visible before execution. See [Timelock & Authority](/governance). ## Storage: ERC-7201 namespaces All mutable state lives in ERC-7201 namespaced storage: ```solidity /// @custom:storage-location erc7201:river.storage..v1 bytes32 internal constant STORAGE_LOCATION = bytes32(uint256(erc7201("river.storage..v1"))); ``` This eliminates storage-collision risk across upgrades and inheritance changes, and makes each contract's state auditable as a single struct. New fields are **appended** to the namespace struct only — layout positions are never reordered. ## Immutable-after-init configuration Some storage is set at `initialize` and deliberately has **no setter**. These are behavioral commitments: | Contract | Field | Why it must never change | | --- | --- | --- | | Wrapper | `underlying` | The exit-coupon clock assumes one monotonic `cumCashIndex` series; repointing would corrupt every live exit | | Wrapper | `controllerProxyImpl` | Exit-bucket addresses are CREATE2-predicted from it; repointing would strand in-flight exits | | Wrapper / tokens | `asset`, `decimalsOffset` | Unit-of-account and share-scale commitments | | Structure | `accessControls`, pinned `pricingMode` | Authorization root and valuation basis for the deal's life | A planned migration path exists anyway — the UUPS upgrade itself — which is timelocked, unlike a setter would be. ## Upgrade constraints (operational) * An upgrade of the **class token** must preserve `CouponLedgerLib` semantics — in particular `cumCashIndex` monotonicity. Wrappers pinned to it depend on the series never resetting or re-basing. * Implementations are deployed with `_disableInitializers()` in the constructor — raw implementations cannot be initialized or hijacked. * Each wrapper deploys and binds its own `ControllerProxy` implementation at initialize; clones are bound to the wrapper atomically at first use (no front-run window).