# Wrapper Integration `DistributingVault4626` is River's composability surface: an ERC-4626 vault whose price accrues as class coupon is funded. This page is written for smart-contract integrators (markets, aggregators, routers). :::info\[Step-by-step] **Enter:** 1. **Get your contract gated** for `WRAP` (and `RECEIVE` if shares will be transferred to you). 2. **Quote** — `previewDeposit(underlying.convertToAssets(shares))`. 3. **Execute** — `wrap(underlyingShares, receiver, minShares)` with your quote as the floor. **Exit:** 1. **Quote** — `convertToAssets(shares)` is the full redeemable value; `cashAllowanceOf(holder)` is how much of it pays instantly. 2. **Execute** — `requestUnwrap(shares, receiver, minCash)`; ticket `0` means fully cash-settled. 3. **Claim the queued remainder** later — `claimUnwrap(holder, receiver)` (permissionless). ::: ## Interface ```solidity // Entry (synchronous; the caller must hold + approve distributing class tokens) function wrap(uint256 underlyingShares, address receiver, uint256 minShares) external returns (uint256 shares); // Exit (cash-first; underlyingTicket == 0 means fully settled in cash, nothing queued) function requestUnwrap(uint256 shares, address receiver, uint256 minCash) external returns (uint256 underlyingTicket); // Settle a queued exit: pays fill-priced principal + coupon earned while queued. Permissionless. function claimUnwrap(address holder, address receiver) external returns (uint256 assets, uint256 coupon); // Unwind an unfilled exit back to class-token shares (+ queued-interval coupon) function cancelUnwrap(address receiver, uint256 underlyingTicket) external returns (uint256 underlyingShares); // Reads — conservative / redeemable side (SAFE for collateral pricing) function totalAssets() external view returns (uint256); function convertToAssets(uint256 shares) external view returns (uint256); function convertToShares(uint256 assets) external view returns (uint256); // Reads — gross / mint side (what wrap() prices at; includes optimism × pending accrual) function grossTotalAssets() external view returns (uint256); function previewDeposit(uint256 assets) external view returns (uint256); // Position introspection function cashAllowanceOf(address holder) external view returns (uint256); // instant-cash ration function lockedSharesOf(address holder, address receiver) external view returns (uint256); function owedCouponOf(address holder, address receiver) external view returns (uint256); function exitCouponOwed() external view returns (uint256); ``` ## Notes for implementers * **Collateral pricing: use `convertToAssets`.** It is the realized-only, conservative valuation — unfunded accrual and coupon owed to in-flight exiters are excluded by construction. The gross figure can never be redeemed against and must never mark collateral. * **Slippage floors are load-bearing.** Servicer actions (accrue, fund, settle) between quote and execution legitimately move both prices. `minShares` on `wrap` and `minCash` on `requestUnwrap` turn "silently worse execution" into a revert (`SlippageExceeded`). Setting `minCash = convertToAssets(shares)` *enforces* atomic cash settlement by reverting when the request would otherwise open a queued position. * **The cash ration transfers pro-rata with shares.** If your contract pools user deposits, ration accounting passes through mechanically: transferring wrapper shares out of your pool carries the proportional ration with them. Fresh mints start at zero ration. * **`(holder, receiver)` is the exit bucket key.** All of one holder's unwraps to the same receiver aggregate into one claimable bucket, drained in aggregate by `claimUnwrap` — partial and out-of-order fills need no per-ticket tracking. Use distinct receivers only when you need segregated payout addresses. * **Liquidations**: seized wrapper shares are ordinary ERC-20 transfers (the liquidator address must pass the `RECEIVE` gate) and carry their pro-rata ration; exit via `requestUnwrap` as normal. * **Events**: `Wrapped`, `UnwrapRequested` (with `cashPaid` and `underlyingTicket`), `UnwrapClaimed`, `UnwrapCancelled` carry everything needed for off-chain accounting. ## Sync mutator behavior (standards compliance) `deposit`, `mint`, `withdraw`, `redeem` revert with `SyncFlowDisabled`; `maxDeposit`, `maxMint`, `maxWithdraw`, `maxRedeem` return 0. ERC-4626 tooling that respects `max*` will treat the vault as read-only, which is correct.