@venusprotocol/liquidity-hub 2.1.0-dev.5 → 2.1.0-dev.7

package/README.md

@@ -195,9 +195,12 @@ Hub.totalAssets()
   = Σ YieldGroup.totalAssets()  +  Hub idle balance
         │
         └─ YieldGroup.totalAssets()
-             = Σ adapter.totalAssets(resource, yieldGroup)  +  YieldGroup idle balance
+             = Σ adapter.receiptValue(resource, trackedReceipt[resource])  +  YieldGroup idle balance
+               (Centrifuge keeps receipt tracking off and sums adapter.totalAssets(resource, yieldGroup) instead)
 ```
 
+- **Tracked receipts, not the wallet.** A tracking family prices only the receipts its own deposits minted. Receipt tokens that reach the YieldGroup any other way (a donation) sit in the wallet uncounted: they move neither NAV nor liquidity, never block removal, and are sweepable once the resource is removed. Governance can admit them into the ledger with `syncReceipt`, capped at the amount it reviewed, so receipts sent in while the VIP waits stay uncounted.
+
 - **Fails closed.** `totalAssets()` is the share-price denominator, so a YieldGroup whose `totalAssets()` view reverts is **not** isolated here — it halts share math rather than silently dropping that YieldGroup's funds from NAV (which would understate the price, under-pay redeemers and over-credit depositors until the value reappeared). The _quantity views_ (`maxWithdraw`, and `HubLens`'s capacity figure) and the deposit/withdraw routing **do** isolate a faulting YieldGroup (contribute 0 / skip) because failing conservatively there is safe — only on the price would it corrupt the conversion. A view-level revert is a YieldGroup-level bug (resource-level reverts are isolated inside the YieldGroup, so external pauses surface in `withdraw`/`deposit`, not here); recover via the runbook below.
 - Hub idle is normally zero (deposits route out atomically, withdrawals pull exact amounts, reallocate is balanced). A direct token donation persists and is intentionally counted into NAV (it accrues to LPs and is consumed first on withdraw) — the underlying cannot be swept.
 - YieldGroup idle accumulates from treasury-fee gross-up surplus and dust handling on past withdrawals; it is counted and consumed idle-first.
@@ -333,16 +336,16 @@ room = min( protocolHeadroom,  resourceCap − ourBalanceInResource )
 
 Every privileged call is gated by `AccessControlManagerV8` — the role is `keccak256(targetContract, roleString)`, where `roleString` is the literal function signature shown below. The contracts do not hard-code an operator-vs-governance branch; the asymmetry is entirely a matter of which addresses governance grants each role to. In v1 the Operator is the Venus Core multisig.
 
-| Action class                                                                                 |  Governance (VIP)  |      Operator      |
-| -------------------------------------------------------------------------------------------- | :----------------: | :----------------: |
-| Add / remove YieldGroup or Resource, **unpause**, set fees, `updateResourceAdapter`, `sweep` |         ✅         |         ❌         |
-| **Raise** caps, `emergencyReallocate`                                                        | ✅ (also Guardian) |         ❌         |
-| **Lower** caps, lower per-tx cap, **pause**, reorder queues                                  |         ✅         |         ✅         |
-| `reallocate` between YieldGroups / resources                                                 |         —          |         ✅         |
-| `pauseHub`                                                                                   |         ✅         | ✅ (also Guardian) |
-| `deposit` / `mint` / `withdraw` / `redeem`, `accrueFees`, views                              |   permissionless   |   permissionless   |
+| Action class                                                                                                |  Governance (VIP)  |      Operator      |
+| ----------------------------------------------------------------------------------------------------------- | :----------------: | :----------------: |
+| Add / remove YieldGroup or Resource, **unpause**, set fees, `updateResourceAdapter`, `sweep`, `syncReceipt` |         ✅         |         ❌         |
+| **Raise** caps, `emergencyReallocate`                                                                       | ✅ (also Guardian) |         ❌         |
+| **Lower** caps, lower per-tx cap, **pause**, reorder queues                                                 |         ✅         |         ✅         |
+| `reallocate` between YieldGroups / resources                                                                |         —          |         ✅         |
+| `pauseHub`                                                                                                  |         ✅         | ✅ (also Guardian) |
+| `deposit` / `mint` / `withdraw` / `redeem`, `accrueFees`, views                                             |   permissionless   |   permissionless   |
 
-**ACM role strings.** Hub: `addYieldGroup(address,uint256,uint16)`, `removeYieldGroup(address)`, `raiseYieldGroupCap(...)`, `lowerYieldGroupCap(...)`, `setOuterDepositQueue(address[])`, `setOuterWithdrawQueue(address[])`, `pauseHub()`, `unpauseHub()`, `pauseYieldGroup(address)`, `unpauseYieldGroup(address)`, `raiseMaxWithdrawalSize(uint256)`, `lowerMaxWithdrawalSize(uint256)`, `setManagementFeeBps(uint16)`, `setPerformanceFeeBps(uint16)`, `setRedeemFeeBps(uint16)`, `setFeeRecipient(address)`, `sweep(address,address)`, `reallocate(...)`, `emergencyReallocate(...)`. Each YieldGroup: `addResource(address,address)`, `removeResource(address)`, `updateResourceAdapter(address,address)` (governance-only, repoints a resource's delegatecall adapter), `setInnerDepositQueue(address[])`, `setInnerWithdrawQueue(address[])`, `pauseResource(address)`, `unpauseResource(address)`, `sweep(address,address)`, and — Core & Flux only — `raiseResourceCap(address,uint256)`, `lowerResourceCap(address,uint256)`, `setBlocksPerYear(uint256)`; — FRV & Centrifuge — `forceRemoveResource(address)`; and — Centrifuge only — `requestRedeem(address,uint256)`, `cancelDepositRequest(address)`, `cancelRedeemRequest(address)`, `claimDeposit(address)`, `claimRedeem(address)`, `claimCancelDeposit(address)`, `claimCancelRedeem(address)`, `setNavGuardRate(address,uint16,uint16,uint16,uint32,bool,bool)`, `setNavGuardSnapshot(address,uint128,uint64)`, `setNavGuardEnabled(address,bool,bool)`, `setSpotAPYBps(address,uint64)`. An onboarding VIP that skips the three `setNavGuard*` roles leaves that resource's NAV band unarmed for good: nothing else can arm it, and an unarmed band reports the counterparty's value to the Hub unclamped.
+**ACM role strings.** Hub: `addYieldGroup(address,uint256,uint16)`, `removeYieldGroup(address)`, `raiseYieldGroupCap(...)`, `lowerYieldGroupCap(...)`, `setOuterDepositQueue(address[])`, `setOuterWithdrawQueue(address[])`, `pauseHub()`, `unpauseHub()`, `pauseYieldGroup(address)`, `unpauseYieldGroup(address)`, `raiseMaxWithdrawalSize(uint256)`, `lowerMaxWithdrawalSize(uint256)`, `setManagementFeeBps(uint16)`, `setPerformanceFeeBps(uint16)`, `setRedeemFeeBps(uint16)`, `setFeeRecipient(address)`, `sweep(address,address)`, `reallocate(...)`, `emergencyReallocate(...)`. Each YieldGroup: `addResource(address,address)`, `removeResource(address)`, `updateResourceAdapter(address,address)` (governance-only, repoints a resource's delegatecall adapter), `setInnerDepositQueue(address[])`, `setInnerWithdrawQueue(address[])`, `pauseResource(address)`, `unpauseResource(address)`, `sweep(address,address)`, `syncReceipt(address,uint256)`, and — Core & Flux only — `raiseResourceCap(address,uint256)`, `lowerResourceCap(address,uint256)`, `setBlocksPerYear(uint256)`; — FRV & Centrifuge — `forceRemoveResource(address)`; and — Centrifuge only — `requestRedeem(address,uint256)`, `cancelDepositRequest(address)`, `cancelRedeemRequest(address)`, `claimDeposit(address)`, `claimRedeem(address)`, `claimCancelDeposit(address)`, `claimCancelRedeem(address)`, `setNavGuardRate(address,uint16,uint16,uint16,uint32,bool,bool)`, `setNavGuardSnapshot(address,uint128,uint64)`, `setNavGuardEnabled(address,bool,bool)`, `setSpotAPYBps(address,uint64)`. An onboarding VIP that skips the three `setNavGuard*` roles leaves that resource's NAV band unarmed for good: nothing else can arm it, and an unarmed band reports the counterparty's value to the Hub unclamped.
 
 ## Invariants & safety
 
@@ -350,7 +353,7 @@ Every privileged call is gated by `AccessControlManagerV8` — the role is `kecc
 - **Net-zero reallocate.** `Σ withdraws == Σ deposits`; the Operator can only move funds among registered routes, never in or out.
 - **Stateless adapters.** Adapters declare zero storage (only immutables), never `sstore`, and call only the resource, its `underlying()`, and its `comptroller()`. Mutating entry points revert outside a delegatecall context.
 - **Fault isolation.** A YieldGroup with a reverting `totalAssets()` view contributes 0 instead of bricking the Hub; it can still be removed as an emergency eviction.
-- **Removal safety.** `removeResource` / `removeYieldGroup` gate on a _raw receipt-token_ balance (not underlying value) so a sub-unit residual can't be rounded to zero and orphan tokens.
+- **Removal safety.** `removeResource` / `removeYieldGroup` gate on receipts the YieldGroup accounts for, in _receipt-token units_ (not underlying value) so a sub-unit residual can't be rounded to zero and orphan tokens. For a tracking family that is the tracked ledger, so donated receipts never block removal and are sweepable afterwards; for Centrifuge it is the wallet balance.
 - **Inflation defense.** ERC-4626 decimals offset (≤ 12) is set per asset at init; the deploy path is responsible for a non-zero value.
 - **Standard ERC-20 only.** Fee-on-transfer, deflationary, and rebasing underlyings are unsupported (deposits fail closed if a token delivers less than requested).
 - **Upgrade-safe storage.** Each contract isolates its state in a `*Storage` base with a reserved `__gap`; never reorder or prepend fields.
@@ -370,7 +373,7 @@ contracts/
   migrator/                  Migrator.sol (immutable Core→Hub one-click migration)
   registry/                  HubRegistry.sol (chain-level Hub directory, discovery root)
   interfaces/                IYieldGroupBase, IResourceAdapter, IHub, IHubLens, IHubRegistry, IYieldGroup*, IMigrator, IVToken, IVBep20, IWBNB, IFToken, IFRVVault, ...
-deploy/                      Foundry deploy scripts 01–14 + DeployBase + config/<network>.json
+deploy/                      Foundry deploy scripts 01–15 + DeployBase + config/<network>.json
 tests/foundry/               unit (Hub/, YieldGroup/{core,flux,frv}/, Registry/, lens/), Integration/, fork/
 deployments/<network>/       committed registry of deployed addresses (source of truth)
 lib/                         git-submodule dependencies
@@ -441,6 +444,7 @@ Beacon-proxy model: one `UpgradeableBeacon` **per family per chain** (Hub, Core,
 12_DeployHubImpl                                                    # upgrade only: new Hub impl behind the existing HubBeacon
 13_DeploySpoke                                                      # once per chain (Spoke adapter + impl + beacon)
 14_DeploySpokeSource                                                # per asset, backfills existing Hubs
+15_DeployReceiptLedger                                              # upgrade only: receipt-ledger YieldGroup impls + the four tracking adapters
 ```
 
 Scripts run in numeric order: beacons first, then the registry, then per-asset instances against both. Scripts only deploy + initialize — **ACM wiring, `addYieldGroup` / `addResource`, and queue configuration are governance (ACM-gated) actions done separately.**

package/contracts/YieldGroup/YieldGroup.sol

@@ -110,7 +110,7 @@ contract YieldGroup is YieldGroupBase, IYieldGroup {
         uint256 cap = _resourceCap[resource];
         if (cap == 0) return protocolRoom;
 
-        uint256 held = IResourceAdapter(adapter).totalAssets(resource, address(this));
+        uint256 held = _accountedAssetValue(resource, adapter);
         uint256 operatorRoom = cap > held ? cap - held : 0;
         return protocolRoom < operatorRoom ? protocolRoom : operatorRoom;
     }

package/contracts/YieldGroup/YieldGroupCentrifuge.sol

@@ -364,6 +364,13 @@ contract YieldGroupCentrifuge is YieldGroupBase, NavGuard, IYieldGroupCentrifuge
 
     // ============================== Internal — hooks ==========================
 
+    /// @dev Off for this family: Centrifuge mints the shares when it settles a request, outside our
+    ///      deposit call, so the base's balance delta around the dispatch would never see them. The
+    ///      NavGuard band bounds this family's valuation instead.
+    function _tracksReceipts() internal pure override returns (bool) {
+        return false;
+    }
+
     /// @dev Unlike `IResourceAdapter.maxDeposit`, `depositRoom` can inspect this YieldGroup's state
     ///      for the vault. It returns zero while this group has a deposit cancellation pending, so
     ///      the Hub does not advertise capacity that Centrifuge would reject.

package/contracts/YieldGroup/YieldGroupFRV.sol

@@ -83,6 +83,7 @@ contract YieldGroupFRV is YieldGroupBase, IYieldGroupFRV {
         _removeFromQueue(_innerDepositQueue, resource);
         _removeFromQueue(_innerWithdrawQueue, resource);
 
+        delete _trackedReceipt[resource];
         delete _resourcesConfig[resource];
 
         emit ResourceForceRemoved(resource, orphaned);

package/contracts/YieldGroup/base/YieldGroupBase.sol

@@ -140,9 +140,9 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         ResourceConfig storage cfg = _resourcesConfig[resource];
         if (!cfg.registered) revert ResourceNotRegistered(resource);
 
-        // Gate on the raw receipt-token balance, not the underlying value: a value-based check
-        // rounds a sub-unit residual to 0 and would let removal orphan dust receipt tokens.
-        uint256 held = IResourceAdapter(cfg.adapter).receiptBalance(resource, address(this));
+        // Gate on receipts the YieldGroup accounts for, not the wallet. Donated receipts were never counted and cannot
+        // be withdrawn, so they would pin a drained resource here; once unregistered, `sweep` recovers them.
+        uint256 held = _accountedReceipts(resource, cfg.adapter);
         if (held != 0) revert ResourceHasBalance(resource, held);
 
         uint256 idxPlusOne = _resourceIndex[resource];
@@ -163,6 +163,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         // same address silently inherit a stale value, since `addResource` never writes it and the
         // setter is registered-only. Removal restores a clean slate.
         delete _resourceCap[resource];
+        delete _trackedReceipt[resource];
         delete _resourcesConfig[resource];
         _onResourceRemoved(resource);
 
@@ -255,6 +256,24 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         }
     }
 
+    /// @inheritdoc IYieldGroupBase
+    /// @dev This is the only way a receipt-token donation reaches the Hub's share price, so it is
+    ///      governance deciding the tokens are worth what the resource says. A vToken of a market
+    ///      carrying unsocialised bad debt is not, and syncing it hands that loss to the Hub's LPs.
+    function syncReceipt(address resource, uint256 maxAdded) external override {
+        _checkAccessAllowed("syncReceipt(address,uint256)");
+        if (!_tracksReceipts()) revert ReceiptTrackingOff();
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+
+        uint256 held = IResourceAdapter(cfg.adapter).receiptBalance(resource, address(this));
+        uint256 old = _trackedReceipt[resource];
+        uint256 synced = held;
+        if (held > old && held - old > maxAdded) synced = old + maxAdded;
+        _trackedReceipt[resource] = synced;
+        emit ReceiptSynced(resource, old, synced);
+    }
+
     // -- IYieldGroupBase: deposit / withdraw --
 
     /// @inheritdoc IYieldGroupBase
@@ -367,7 +386,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         _prepareResource(resource);
 
         address adapter = cfg.adapter;
-        uint256 liquid = IResourceAdapter(adapter).maxWithdraw(resource, address(this));
+        uint256 liquid = _liquidAssetValue(resource, adapter);
         if (amount > liquid) revert ResourceLiquidityInsufficient(amount, liquid);
 
         uint256 received = _dispatchWithdraw(adapter, resource, amount, to);
@@ -402,6 +421,11 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         return (cfg.registered, cfg.paused, cfg.adapter);
     }
 
+    /// @inheritdoc IYieldGroupBase
+    function trackedReceipt(address resource) external view override returns (uint256) {
+        return _trackedReceipt[resource];
+    }
+
     /// @inheritdoc IYieldGroupBase
     function innerDepositQueue() external view override returns (address[] memory) {
         return _innerDepositQueue;
@@ -429,7 +453,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         uint256 len = list.length;
         for (uint256 i; i < len; ++i) {
             address resource = list[i];
-            total += IResourceAdapter(_resourcesConfig[resource].adapter).totalAssets(resource, address(this));
+            total += _accountedAssetValue(resource, _resourcesConfig[resource].adapter);
         }
         total += IERC20(_assetToken).balanceOf(address(this));
     }
@@ -465,7 +489,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
             address resource = queue[i];
             ResourceConfig storage cfg = _resourcesConfig[resource];
             if (cfg.registered && !cfg.paused) {
-                total += IResourceAdapter(cfg.adapter).maxWithdraw(resource, address(this));
+                total += _liquidAssetValue(resource, cfg.adapter);
             }
         }
         total += IERC20(_assetToken).balanceOf(address(this));
@@ -484,7 +508,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         for (uint256 i; i < len; ++i) {
             address resource = list[i];
             address adapter = _resourcesConfig[resource].adapter;
-            uint256 resVal = IResourceAdapter(adapter).totalAssets(resource, address(this));
+            uint256 resVal = _accountedAssetValue(resource, adapter);
             if (resVal > 0) {
                 uint256 apy = IResourceAdapter(adapter).spotAPYBps(resource, bpy);
                 weighted += apy * resVal;
@@ -579,7 +603,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         _prepareResource(resource);
 
         address adapter = cfg.adapter;
-        uint256 liquid = IResourceAdapter(adapter).maxWithdraw(resource, address(this));
+        uint256 liquid = _liquidAssetValue(resource, adapter);
         uint256 toDeliver = remaining < liquid ? remaining : liquid;
         if (toDeliver == 0) return 0;
 
@@ -626,7 +650,10 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
 
     /// @custom:oz-upgrades-unsafe-allow-reachable delegatecall
     function _dispatchDeposit(address adapter, address resource, uint256 amount) internal virtual {
+        bool tracks = _tracksReceipts();
+        uint256 before = tracks ? _totalReceipts(resource, adapter) : 0;
         adapter.functionDelegateCall(abi.encodeCall(IResourceAdapter.deposit, (resource, amount)));
+        if (tracks) _trackedReceipt[resource] += _totalReceipts(resource, adapter) - before;
         emit DepositRouted(resource, amount);
     }
 
@@ -657,9 +684,26 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
     {
         IERC20 assetToken = IERC20(_assetToken);
         uint256 preBalTo = assetToken.balanceOf(to);
+        bool tracks = _tracksReceipts();
+        uint256 preHeld = tracks ? _totalReceipts(resource, adapter) : 0;
         adapter.functionDelegateCall(abi.encodeCall(IResourceAdapter.withdraw, (resource, amount, to)));
         received = assetToken.balanceOf(to) - preBalTo;
 
+        // The vault burns from the wallet, which can hold receipts the ledger never counted. Callers
+        // size `amount` against the tracked value, so the burn stays within the tracked count unless
+        // the adapter burns more than asked: Spoke sweeps a worthless remainder whole, donated dust
+        // included. Floor at zero rather than revert, or that dust would block the withdrawal.
+        if (tracks) {
+            uint256 burned = preHeld - _totalReceipts(resource, adapter);
+            uint256 tracked = _trackedReceipt[resource];
+            uint256 left = burned < tracked ? tracked - burned : 0;
+            // Spoke decides whether to burn a worthless remainder by looking at the wallet, so a donation
+            // can leave receipts counted here that are worth 0. No withdrawal reaches them and they would
+            // block `removeResource`, so drop them; `sweep` recovers them from the wallet after removal.
+            if (left != 0 && IResourceAdapter(adapter).receiptValue(resource, left) == 0) left = 0;
+            _trackedReceipt[resource] = left;
+        }
+
         emit WithdrawRouted(resource, amount);
     }
 
@@ -749,7 +793,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         uint256 len = list.length;
         for (uint256 i; i < len; ++i) {
             address resource = list[i];
-            uint256 held = IResourceAdapter(_resourcesConfig[resource].adapter).receiptBalance(resource, address(this));
+            uint256 held = _accountedReceipts(resource, _resourcesConfig[resource].adapter);
             if (held != 0 && !_queueContains(queue, resource)) {
                 revert WithdrawQueueOmitsFundedResource(resource);
             }
@@ -816,4 +860,46 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
     function _resourceDepositRoom(address resource, address adapter) internal view virtual returns (uint256 room) {
         return IResourceAdapter(adapter).maxDeposit(resource);
     }
+
+    /**
+     * @notice Whether valuation counts only the receipt tokens this YieldGroup minted itself.
+     * @dev Base default: true. Holds for every family whose receipt balance moves only when this
+     *      contract deposits or redeems (Core, Spoke, Flux, FRV). `YieldGroupCentrifuge` overrides to
+     *      false: its shares are minted by Centrifuge when it settles a request, not inside our
+     *      deposit call, so a balance delta measured around the dispatch would miss them.
+     * @return tracks True to price `_trackedReceipt` through the adapter's `receiptValue` instead of
+     *         its holder-wide `totalAssets`.
+     */
+    function _tracksReceipts() internal view virtual returns (bool tracks) {
+        return true;
+    }
+
+    /// @dev Value of our position in `resource`: the tracked receipts priced by the adapter, or the
+    ///      whole wallet when this family does not track.
+    function _accountedAssetValue(address resource, address adapter) internal view returns (uint256) {
+        if (_tracksReceipts()) return IResourceAdapter(adapter).receiptValue(resource, _trackedReceipt[resource]);
+        return IResourceAdapter(adapter).totalAssets(resource, address(this));
+    }
+
+    /// @dev Withdrawable underlying from `resource` right now. The adapter's figure is what the vault
+    ///      will pay this wallet, so it is capped at what our tracked receipts are worth; untracked
+    ///      receipts never certify liquidity.
+    function _liquidAssetValue(address resource, address adapter) private view returns (uint256) {
+        uint256 liquid = IResourceAdapter(adapter).maxWithdraw(resource, address(this));
+        if (!_tracksReceipts()) return liquid;
+        uint256 worth = _accountedAssetValue(resource, adapter);
+        return worth < liquid ? worth : liquid;
+    }
+
+    /// @dev Every receipt in the wallet, counted or not.
+    function _totalReceipts(address resource, address adapter) private view returns (uint256) {
+        return IResourceAdapter(adapter).receiptBalance(resource, address(this));
+    }
+
+    /// @dev Receipts the Hub accounts for: the tracked ledger when the family tracks, the wallet otherwise.
+    ///      The registry gates read this so they agree with valuation on what "funded" means.
+    function _accountedReceipts(address resource, address adapter) private view returns (uint256) {
+        if (_tracksReceipts()) return _trackedReceipt[resource];
+        return _totalReceipts(resource, adapter);
+    }
 }

package/contracts/YieldGroup/base/YieldGroupBaseStorage.sol

@@ -29,7 +29,8 @@ import { IYieldGroupBase } from "../../interfaces/IYieldGroupBase.sol";
  *             7   32            _innerDepositQueue
  *             8   32            _innerWithdrawQueue
  *             9   32            _resourceCap            (generic only; never written by FRV)
- *         10..48  32 × 39       __gap
+ *            10   32            _trackedReceipt
+ *         11..48  32 × 38       __gap
  */
 abstract contract YieldGroupBaseStorage {
     /// @notice Hub authorised to call `deposit` / `withdraw`. Set at initialisation.
@@ -67,7 +68,14 @@ abstract contract YieldGroupBaseStorage {
     ///         generic `YieldGroup` reads / writes this; FRV leaves it `0`.
     mapping(address resource => uint256 cap) internal _resourceCap;
 
+    /// @notice Receipt tokens (vTokens, vault shares) this YieldGroup minted itself, per resource.
+    ///         Valuation counts these and ignores any surplus the resource's `balanceOf` shows, so
+    ///         receipt tokens sent here directly do not move the Hub's share price. Written only by
+    ///         the deposit / withdraw dispatch and `syncReceipt`, and cleared on removal; families
+    ///         whose receipts arrive asynchronously (Centrifuge) leave it unused.
+    mapping(address resource => uint256 shares) internal _trackedReceipt;
+
     /// @dev Reserved slots for future state. Shrink by the number of slots a new field
     ///      consumes when extending.
-    uint256[39] private __gap;
+    uint256[38] private __gap;
 }

package/contracts/adapters/AdapterCentrifuge.sol

@@ -81,6 +81,15 @@ contract AdapterCentrifuge is IAdapterCentrifuge {
      */
     error ZeroSharePrice(address resource);
 
+    /**
+     * @notice Thrown by {receiptValue}, which this family implements only to satisfy `IResourceAdapter`.
+     * @dev `YieldGroupCentrifuge` turns receipt tracking off because deposits and withdrawals are
+     *      asynchronous: Centrifuge mints the shares at settlement, after our deposit call has
+     *      returned, so the base never calls {receiptValue} here.
+     * @param resource Resource that was queried.
+     */
+    error ShareCountNotPriceable(address resource);
+
     // ============================== Modifiers =================================
 
     /// @dev Restricts mutating adapter functions to delegatecall execution.
@@ -211,7 +220,8 @@ contract AdapterCentrifuge is IAdapterCentrifuge {
     ///      `totalAssets()` for the figure the Hub sums, and this one for what the band is clamping.
     ///
     ///      Only the share-denominated buckets need a price, so a position holding none is valued
-    ///      without the feed at all.
+    ///      without the feed at all. Prices everything `holder` has at the vault; this family keeps
+    ///      receipt tracking off, so there is no tracked figure.
     function totalAssets(address resource, address holder) external view override returns (uint256 value) {
         (uint256 face, uint256 shares, address shareToken) = _assetAndShareTotals(resource, holder);
         value = face;
@@ -252,6 +262,11 @@ contract AdapterCentrifuge is IAdapterCentrifuge {
         return ICentrifugeAsyncVault(resource).maxWithdraw(holder);
     }
 
+    /// @inheritdoc IResourceAdapter
+    function receiptValue(address resource, uint256) external pure override returns (uint256) {
+        revert ShareCountNotPriceable(resource);
+    }
+
     /// @inheritdoc IResourceAdapter
     /// @dev Centrifuge publishes no rate on-chain — a fund's return arrives as a new NAV — so the
     ///      number comes from the YieldGroup holding the position, where governance publishes it

package/contracts/adapters/AdapterCoreV1.sol

@@ -166,20 +166,17 @@ contract AdapterCoreV1 is IResourceAdapter {
     }
 
     /// @inheritdoc IResourceAdapter
-    /// @dev Values the position at REALIZABLE (net-of-treasury) terms so NAV/PPS equal the value the
-    ///      position can actually deliver. `withdraw` already nets the Venus treasury exit cut, so
-    ///      valuing gross here would overstate NAV and let a first-out LP exit at the pre-fee price
-    ///      while the shortfall socialises onto the last-out LP. When the Comptroller fee is off
-    ///      (every registered market today) this returns the gross value unchanged.
+    /// @dev Priced net of the Comptroller's treasury exit fee, because `withdraw` burns extra vTokens
+    ///      to cover it. Valuing gross would overstate NAV and let early withdrawers leave the fee to
+    ///      the last ones out. With the fee at zero this is the plain stored-rate value.
+    ///      Prices everything `holder` has in the wallet, not the YieldGroup's tracked receipts.
     function totalAssets(address resource, address holder) external view override returns (uint256) {
-        uint256 vBal = IVToken(resource).balanceOf(holder);
-        if (vBal == 0) return 0;
-        uint256 gross = (vBal * IVToken(resource).exchangeRateStored()) / EXP_SCALE;
+        return _receiptValue(resource, IVToken(resource).balanceOf(holder));
+    }
 
-        uint256 treasuryPct = IComptroller(IVToken(resource).comptroller()).treasuryPercent();
-        if (treasuryPct == 0) return gross;
-        // The Comptroller setter enforces `treasuryPercent < 1e18`, so the subtraction cannot underflow.
-        return (gross * (MANTISSA_ONE - treasuryPct)) / MANTISSA_ONE;
+    /// @inheritdoc IResourceAdapter
+    function receiptValue(address resource, uint256 vBal) external view override returns (uint256) {
+        return _receiptValue(resource, vBal);
     }
 
     /// @inheritdoc IResourceAdapter
@@ -206,9 +203,9 @@ contract AdapterCoreV1 is IResourceAdapter {
 
     /// @inheritdoc IResourceAdapter
     /// @dev Three constraints: (a) what `holder` holds in the resource (vToken balance × ER),
-    ///      (b) what the vToken can pay out in cash (`getCash`), and (c) the treasury cut
-    ///      (`treasuryPercent`). The min of (a) and (b) is the gross redeemable; multiplying
-    ///      by `(1 − treasuryPct)` reflects what actually arrives at the recipient.
+    ///      (b) what the vToken can pay out in cash (`getCash` net of `totalReserves`), and (c)
+    ///      the treasury cut (`treasuryPercent`). The min of (a) and (b) is the gross redeemable;
+    ///      multiplying by `(1 − treasuryPct)` reflects what actually arrives at the recipient.
     function maxWithdraw(address resource, address holder) external view override returns (uint256) {
         IComptroller comptrollerContract = IComptroller(IVToken(resource).comptroller());
         // Action.REDEEM == 1 in the Venus Comptroller's enum.
@@ -221,6 +218,10 @@ contract AdapterCoreV1 is IResourceAdapter {
         if (ourValue == 0) return 0;
 
         uint256 cash = IVToken(resource).getCash();
+        // `accrueInterest` sends the reserves out of cash when a reduction is due.
+        uint256 reserves = IVToken(resource).totalReserves();
+        if (cash <= reserves) return 0;
+        cash -= reserves;
         // A redeem that would burn 0 vTokens is bumped to one whole vToken unit of underlying by
         // `_floorRedeemToOneVToken`. If the market's cash is below that unit, every non-zero redeem
         // the cascade could try exceeds cash and reverts in Venus `redeemFresh`. Report 0 liquidity
@@ -264,6 +265,19 @@ contract AdapterCoreV1 is IResourceAdapter {
         if (treasuryPct != 0) revert TreasuryFeeUnsupported(resource, treasuryPct);
     }
 
+    // ============================== Internal — view ==========================
+
+    /// @dev Realizable value of `vBal` vTokens: stored-rate gross, net of the Comptroller treasury cut.
+    function _receiptValue(address resource, uint256 vBal) internal view returns (uint256) {
+        if (vBal == 0) return 0;
+        uint256 gross = (vBal * IVToken(resource).exchangeRateStored()) / EXP_SCALE;
+
+        uint256 treasuryPct = IComptroller(IVToken(resource).comptroller()).treasuryPercent();
+        if (treasuryPct == 0) return gross;
+        // The Comptroller setter enforces `treasuryPercent < 1e18`, so the subtraction cannot underflow.
+        return (gross * (MANTISSA_ONE - treasuryPct)) / MANTISSA_ONE;
+    }
+
     // ============================== Private — view ===========================
 
     /**

package/contracts/adapters/AdapterFRV.sol

@@ -120,11 +120,16 @@ contract AdapterFRV is IResourceAdapter {
     }
 
     /// @inheritdoc IResourceAdapter
-    /// @dev Position value = principal slice + accrued-coupon slice; this is the Hub-facing NAV for
-    ///      the position. See the contract NatSpec for the valuation model.
+    /// @dev Position value = principal slice + accrued-coupon slice. See the contract NatSpec for
+    ///      the valuation model. Prices everything `holder` has in the wallet, not the YieldGroup's
+    ///      tracked receipts.
     function totalAssets(address resource, address holder) external view override returns (uint256) {
-        (uint256 principalValue, uint256 couponValueGross) = _breakdown(resource, holder);
-        return principalValue + couponValueGross;
+        return _receiptValue(resource, IFRVVault(resource).balanceOf(holder));
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function receiptValue(address resource, uint256 shares) external view override returns (uint256) {
+        return _receiptValue(resource, shares);
     }
 
     /// @inheritdoc IResourceAdapter
@@ -208,7 +213,13 @@ contract AdapterFRV is IResourceAdapter {
 
     // ============================== Internal — view ==========================
 
-    /// @dev Split the holder's position into (principalValue, couponValueGross), both in underlying.
+    /// @dev Principal slice plus accrued-coupon slice of `shares`, in underlying.
+    function _receiptValue(address resource, uint256 shares) internal view returns (uint256) {
+        (uint256 principalValue, uint256 couponValueGross) = _breakdown(resource, shares);
+        return principalValue + couponValueGross;
+    }
+
+    /// @dev Split `shares` of the vault into (principalValue, couponValueGross), both in underlying.
     ///      Branches by lifecycle state:
     ///        - no shares           -> (0, 0)
     ///        - Closed              -> (0, 0)  (stuck residual; valued at 0 = deliverable value)
@@ -217,13 +228,12 @@ contract AdapterFRV is IResourceAdapter {
     ///      Both slices use the vault's own +1/+1 floored ERC-4626 basis (decimalsOffset 0), so the
     ///      principal slice equals `previewRedeem(shares)` during non-terminal states and the gross
     ///      sum equals the post-Matured `previewRedeem` at `elapsed == lockDuration`.
-    function _breakdown(address resource, address holder)
+    function _breakdown(address resource, uint256 shares)
         internal
         view
         returns (uint256 principalValue, uint256 couponValueGross)
     {
         IFRVVault vault = IFRVVault(resource);
-        uint256 shares = vault.balanceOf(holder);
         if (shares == 0) return (0, 0);
 
         IFRVVault.FRVVaultRuntime memory rt = vault.runtime();

package/contracts/adapters/AdapterFlux.sol

@@ -112,10 +112,14 @@ contract AdapterFlux is IResourceAdapter {
     /// @inheritdoc IResourceAdapter
     /// @dev `previewRedeem(balanceOf(holder))` — the per-holder position value (shares × token
     ///      exchange price, including accrued rewards).
+    ///      Prices everything `holder` has in the wallet, not the YieldGroup's tracked receipts.
     function totalAssets(address resource, address holder) external view override returns (uint256) {
-        uint256 shares = IFToken(resource).balanceOf(holder);
-        if (shares == 0) return 0;
-        return IFToken(resource).previewRedeem(shares);
+        return _receiptValue(resource, IFToken(resource).balanceOf(holder));
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function receiptValue(address resource, uint256 shares) external view override returns (uint256) {
+        return _receiptValue(resource, shares);
     }
 
     /// @inheritdoc IResourceAdapter
@@ -176,4 +180,12 @@ contract AdapterFlux is IResourceAdapter {
         // YieldGroup's `asset()` probe and `code.length` check at registration time.
         resource;
     }
+
+    // ============================== Internal — view ==========================
+
+    /// @dev `previewRedeem(shares)`: shares at the token's exchange price, accrued rewards included.
+    function _receiptValue(address resource, uint256 shares) internal view returns (uint256) {
+        if (shares == 0) return 0;
+        return IFToken(resource).previewRedeem(shares);
+    }
 }

package/contracts/adapters/AdapterSpokeV1.sol

@@ -245,10 +245,14 @@ contract AdapterSpokeV1 is IResourceAdapter {
     /// @dev `balance x exchangeRateStored`: the market's own valuation of the tokens, and what
     ///      redeeming all of them would pay at the stored rate if the market had the cash. Includes
     ///      the position's share of `badDebt`; see the contract NatSpec.
+    ///      Prices everything `holder` has in the wallet, not the YieldGroup's tracked receipts.
     function totalAssets(address resource, address holder) external view override returns (uint256) {
-        uint256 vBal = IVTokenIsolated(resource).balanceOf(holder);
-        if (vBal == 0) return 0;
-        return (vBal * IVTokenIsolated(resource).exchangeRateStored()) / EXP_SCALE;
+        return _receiptValue(resource, IVTokenIsolated(resource).balanceOf(holder));
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function receiptValue(address resource, uint256 vBal) external view override returns (uint256) {
+        return _receiptValue(resource, vBal);
     }
 
     /// @inheritdoc IResourceAdapter
@@ -396,6 +400,14 @@ contract AdapterSpokeV1 is IResourceAdapter {
         }
     }
 
+    // ============================== Internal — view ==========================
+
+    /// @dev `vBal` vTokens at the market's stored exchange rate.
+    function _receiptValue(address resource, uint256 vBal) internal view returns (uint256) {
+        if (vBal == 0) return 0;
+        return (vBal * IVTokenIsolated(resource).exchangeRateStored()) / EXP_SCALE;
+    }
+
     // ============================== Private — pure ===========================
 
     /**

package/contracts/interfaces/IResourceAdapter.sol

@@ -103,6 +103,16 @@ interface IResourceAdapter {
      */
     function totalAssets(address resource, address holder) external view returns (uint256 value);
 
+    /**
+     * @notice Underlying value of `shares` receipt tokens of `resource`, priced exactly as
+     *         {totalAssets} prices a holder's balance. Lets the YieldGroup value the receipts it
+     *         minted itself rather than everything its wallet happens to hold.
+     * @param resource Underlying yield protocol address.
+     * @param shares Receipt-token amount to price, in the resource's own units.
+     * @return value Underlying units `shares` are worth.
+     */
+    function receiptValue(address resource, uint256 shares) external view returns (uint256 value);
+
     /**
      * @notice Spare deposit headroom on `resource` right now (capacity remaining before the
      *         resource rejects mint via its own caps or pause).
@@ -137,9 +147,8 @@ interface IResourceAdapter {
     /**
      * @notice Raw receipt-token balance `holder` owns via `resource` (vToken / fToken / FRV
      *         shares), in receipt-token units — NOT underlying value.
-     * @dev Used by `YieldGroup.removeResource` as a share-based emptiness gate. A value-based
-     *      check (`totalAssets`) rounds a small-but-non-zero receipt balance down to 0, which
-     *      would let removal orphan those receipt tokens; reading the raw balance closes that gap.
+     * @dev In share units so a sub-unit residual still reads as non-zero where a value read would
+     *      round it to 0.
      * @param resource Underlying yield protocol address.
      * @param holder Address whose receipt balance to read (the YieldGroup).
      * @return shares Receipt-token units `holder` holds in this resource.