@venusprotocol/liquidity-hub 0.0.0

package/contracts/Hub/HubStorage.sol

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IHub } from "../interfaces/IHub.sol";
+
+/**
+ * @title HubStorage
+ * @notice Hub state, isolated in a base contract so future upgrades can extend without
+ *         disturbing the inheritance linearisation. Add new fields after `__gap` is shrunk
+ *         by the same number of slots; never reorder, never prepend.
+ *
+ *         Slot layout (Hub's own contribution; upstream contracts have their own slots
+ *         before this):
+ *
+ *           Slot  Used (bytes)  Field
+ *           ----  ------------  -----
+ *             0   1+1           _hubPaused, _decimalsOffsetStored
+ *             1   32            _maxWithdrawalSize
+ *             2   32            _registeredYieldGroups
+ *             3   32            _yieldGroupIndex
+ *             4   32            _yieldGroups
+ *             5   32            _outerDepositQueue
+ *             6   32            _outerWithdrawQueue
+ *             7   2+2+20+2      _managementFeeBps, _performanceFeeBps, _feeRecipient, _redeemFeeBps
+ *             8   32            _highWaterMarkPerShare
+ *             9   8+8+8         _lastFeeAccrualTimestamp, _pauseStart, _lastFeeAccrualBlock
+ *         10..49  32 × 40       __gap
+ */
+abstract contract HubStorage {
+    // Slot 0: lifecycle + decimals offset.
+
+    /// @notice True while the Hub is paused.
+    bool internal _hubPaused;
+
+    /// @notice ERC-4626 inflation-defense offset; returned by `_decimalsOffset()`. Set once at init.
+    uint8 internal _decimalsOffsetStored;
+
+    // Slot 1: per-tx withdraw cap.
+
+    /// @notice Max asset units any single withdraw / redeem can move out of the Hub.
+    uint256 internal _maxWithdrawalSize;
+
+    // Slot 2-4: YieldGroup registry.
+
+    /// @notice Canonical set of registered YieldGroups.
+    address[] internal _registeredYieldGroups;
+
+    /// @notice 1-indexed position in `_registeredYieldGroups` (0 = not registered). Enables O(1) removal.
+    mapping(address yieldGroup => uint256 indexPlusOne) internal _yieldGroupIndex;
+
+    /// @notice Per-YieldGroup config (caps, pause, registered flag).
+    mapping(address yieldGroup => IHub.YieldGroupConfig config) internal _yieldGroups;
+
+    // Slot 5-6: routing queues.
+
+    /// @notice Deposit cascading order. Set by Operator.
+    address[] internal _outerDepositQueue;
+
+    /// @notice Withdraw pulling order. Independent of the deposit queue.
+    address[] internal _outerWithdrawQueue;
+
+    // Slot 7: fee parameters (packed).
+
+    /// @notice Management fee rate in BPS.
+    uint16 internal _managementFeeBps;
+
+    /// @notice Performance fee rate in BPS.
+    uint16 internal _performanceFeeBps;
+
+    /// @notice Recipient of newly-minted fee shares.
+    address internal _feeRecipient;
+
+    /// @notice Exit (withdraw/redeem) fee in BPS, RETAINED in the vault (socialised to remaining
+    ///         LPs as a price-per-share uplift, not minted to a recipient). Default 0; a governance
+    ///         anti sandwich lever for discrete settlement YieldGroups - friction against racing out
+    ///         ahead of a downward settlement reprice (e.g. an FRV settling below its accrued mark on a
+    ///         shortfall). Packed into the existing fee slot, so it consumes no additional storage slot.
+    uint16 internal _redeemFeeBps;
+
+    // Slot 8: performance HWM.
+
+    /// @notice High-water mark in share-price units (`totalAssets × 1e18 / totalSupply`).
+    uint256 internal _highWaterMarkPerShare;
+
+    // Slot 9: fee-accrual cursors.
+
+    /// @notice Block timestamp of last fee accrual. Drives management-fee proration only (elapsed
+    ///         wall-clock time); it is not the per-block idempotence key (see `_lastFeeAccrualBlock`).
+    uint64 internal _lastFeeAccrualTimestamp;
+
+    /// @notice Block timestamp when the Hub was paused. `unpauseHub` advances
+    ///         `_lastFeeAccrualTimestamp` by the pause duration so the frozen window is excluded
+    ///         from management-fee accrual. Packed into slot 9 alongside `_lastFeeAccrualTimestamp`,
+    ///         so it consumes no additional storage slot.
+    uint64 internal _pauseStart;
+
+    /// @notice Block number of last fee accrual, the once-per-block idempotence key for `_accrueFees`.
+    ///         Resource NAV (a Core vToken's `exchangeRateStored`) is block-lazy: it can only change
+    ///         when `block.number` advances. Keying idempotence off the block, not the timestamp,
+    ///         means a fresh block always refreshes resources even when two consecutive blocks share a
+    ///         timestamp (routine on sub-second chains). Packed into slot 9, so it adds no slot.
+    uint64 internal _lastFeeAccrualBlock;
+
+    /// @dev Reserved slots for upgrades. Shrink by the number of slots a new field consumes.
+    uint256[40] private __gap;
+}

package/contracts/Hub/lib/HubAdminLib.sol

@@ -0,0 +1,292 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+import { IHub } from "../../interfaces/IHub.sol";
+import { IYieldGroupBase } from "../../interfaces/IYieldGroupBase.sol";
+
+/**
+ * @title HubAdminLib
+ * @author Venus
+ * @notice Governance/operator-only ("cold") registry and queue logic for the {Hub}, extracted
+ *         into a delegatecall-linked library to keep the Hub implementation under the EIP-170
+ *         24,576-byte limit.
+ * @dev Every function is invoked via DELEGATECALL from the Hub, so `address(this)`, the storage
+ *      slots reached through the passed `storage` references, and the event emitter all remain
+ *      the Hub. The logic here is a near-verbatim relocation of the former in-Hub bodies, and
+ *      emitted events are unchanged. Only `removeYieldGroup` differs: its gate now nets the
+ *      YieldGroup's idle asset balance out of `totalAssets()`. The library holds NO state, so
+ *      the Hub's storage layout (see {HubStorage}) and upgrade-safety are unaffected. Access
+ *      control (`_checkAccessAllowed`) stays in the Hub's thin wrappers, never here.
+ */
+library HubAdminLib {
+    /// @notice BPS denominator (`10_000` = 100%); mirrors `Hub.BPS_DENOMINATOR`.
+    uint16 internal constant BPS_DENOMINATOR = 10_000;
+
+    // ============================== YieldGroup registry ===========================
+
+    /**
+     * @notice Add a YieldGroup to the registry with initial caps. Verbatim relocation of the former
+     *         `Hub.addYieldGroup` body.
+     * @param yieldGroups Hub's per-YieldGroup config mapping (storage ref).
+     * @param registeredYieldGroups Hub's registry array (storage ref).
+     * @param yieldGroupIndex Hub's 1-indexed position mapping (storage ref).
+     * @param yieldGroup YieldGroup contract address (must implement IYieldGroupBase).
+     * @param absoluteCap Initial absolute cap in asset units.
+     * @param percentageCapBps Initial percentage cap in BPS (≤ 10_000).
+     * @param hubAsset The Hub's own `asset()`, supplied by the wrapper for the match check.
+     */
+    function addYieldGroup(
+        mapping(address => IHub.YieldGroupConfig) storage yieldGroups,
+        address[] storage registeredYieldGroups,
+        mapping(address => uint256) storage yieldGroupIndex,
+        address yieldGroup,
+        uint256 absoluteCap,
+        uint16 percentageCapBps,
+        address hubAsset
+    ) external {
+        if (yieldGroup == address(0)) revert IHub.ZeroAddress();
+        if (yieldGroups[yieldGroup].registered) revert IHub.YieldGroupAlreadyRegistered(yieldGroup);
+        if (percentageCapBps > BPS_DENOMINATOR || absoluteCap == type(uint256).max) {
+            revert IHub.InvalidCap(absoluteCap, percentageCapBps);
+        }
+
+        address yieldGroupAsset = IYieldGroupBase(yieldGroup).asset();
+        if (yieldGroupAsset != hubAsset) revert IHub.YieldGroupAssetMismatch(yieldGroup, yieldGroupAsset, hubAsset);
+
+        registeredYieldGroups.push(yieldGroup);
+        yieldGroupIndex[yieldGroup] = registeredYieldGroups.length;
+        yieldGroups[yieldGroup] = IHub.YieldGroupConfig({
+            absoluteCap: absoluteCap, percentageCapBps: percentageCapBps, paused: false, registered: true
+        });
+
+        emit IHub.YieldGroupAdded(yieldGroup, absoluteCap, percentageCapBps);
+    }
+
+    /**
+     * @notice Remove a YieldGroup from the registry: swap-and-pop the registry array and
+     *         cascade-strip the YieldGroup from both outer queues.
+     * @param yieldGroups Hub's per-YieldGroup config mapping (storage ref).
+     * @param registeredYieldGroups Hub's registry array (storage ref).
+     * @param yieldGroupIndex Hub's 1-indexed position mapping (storage ref).
+     * @param outerDepositQueue Hub's deposit queue (storage ref).
+     * @param outerWithdrawQueue Hub's withdraw queue (storage ref).
+     * @param yieldGroup YieldGroup to remove.
+     * @param hubAsset The Hub's own `asset()`, supplied by the wrapper to net idle balance out of the gate.
+     */
+    function removeYieldGroup(
+        mapping(address => IHub.YieldGroupConfig) storage yieldGroups,
+        address[] storage registeredYieldGroups,
+        mapping(address => uint256) storage yieldGroupIndex,
+        address[] storage outerDepositQueue,
+        address[] storage outerWithdrawQueue,
+        address yieldGroup,
+        address hubAsset
+    ) external {
+        IHub.YieldGroupConfig storage cfg = yieldGroups[yieldGroup];
+        if (!cfg.registered) revert IHub.YieldGroupNotRegistered(yieldGroup);
+
+        // Normal path: refuse removal while the YieldGroup still custodies resource-backed value.
+        // `totalAssets()` reports that value plus any idle asset-token balance sitting directly on the
+        // YieldGroup. The idle term is netted out here: anyone can push dust straight to a drained
+        // YieldGroup, and counting it would let a 1-wei transfer block deregistration indefinitely.
+        // Residual idle is handled out-of-band.
+        //
+        // Emergency path: if the YieldGroup's own `totalAssets()` reverts (a bricked / buggy
+        // YieldGroup), removal is permitted anyway so a misbehaving YieldGroup can be evicted without
+        // a Hub upgrade, again with any residual value handled out-of-band.
+        bool balanceReadable;
+        uint256 yieldGroupBal;
+        try IYieldGroupBase(yieldGroup).totalAssets() returns (uint256 v) {
+            balanceReadable = true;
+            // Net out idle asset held directly by the YieldGroup. Only YieldGroupBase defines
+            // `totalAssets()` (resource-backed value + this idle balance), so the difference is
+            // exactly the resource-backed value. `v >= idle` always holds; the guard is defensive.
+            uint256 idle = IERC20(hubAsset).balanceOf(yieldGroup);
+            yieldGroupBal = v > idle ? v - idle : 0;
+        } catch {
+            balanceReadable = false;
+        }
+        if (balanceReadable && yieldGroupBal != 0) revert IHub.YieldGroupHasBalance(yieldGroup, yieldGroupBal);
+
+        uint256 idxPlusOne = yieldGroupIndex[yieldGroup];
+        uint256 idx = idxPlusOne - 1;
+        uint256 lastIdx = registeredYieldGroups.length - 1;
+        if (idx != lastIdx) {
+            address last = registeredYieldGroups[lastIdx];
+            registeredYieldGroups[idx] = last;
+            yieldGroupIndex[last] = idxPlusOne;
+        }
+        registeredYieldGroups.pop();
+        delete yieldGroupIndex[yieldGroup];
+
+        _removeFromQueue(outerDepositQueue, yieldGroup);
+        _removeFromQueue(outerWithdrawQueue, yieldGroup);
+
+        delete yieldGroups[yieldGroup];
+
+        emit IHub.YieldGroupRemoved(yieldGroup);
+    }
+
+    /**
+     * @notice Raise or lower a YieldGroup's caps. Merges the former symmetric `Hub.raiseYieldGroupCap`
+     *         and `Hub.lowerYieldGroupCap` bodies behind a direction flag; the shrink/grow guard and
+     *         the emitted event are selected by `raising`. Behavior is identical to the originals.
+     * @param yieldGroups Hub's per-YieldGroup config mapping (storage ref).
+     * @param yieldGroup YieldGroup whose caps are being changed.
+     * @param absoluteCap New absolute cap in asset units.
+     * @param percentageCapBps New percentage cap in BPS.
+     * @param raising True for the raise path (reverts NotIncreasing), false for lower (NotDecreasing).
+     */
+    function setYieldGroupCap(
+        mapping(address => IHub.YieldGroupConfig) storage yieldGroups,
+        address yieldGroup,
+        uint256 absoluteCap,
+        uint16 percentageCapBps,
+        bool raising
+    ) external {
+        IHub.YieldGroupConfig storage cfg = yieldGroups[yieldGroup];
+        if (!cfg.registered) revert IHub.YieldGroupNotRegistered(yieldGroup);
+        if (percentageCapBps > BPS_DENOMINATOR || absoluteCap == type(uint256).max) {
+            revert IHub.InvalidCap(absoluteCap, percentageCapBps);
+        }
+        // Reject the wrong-direction move AND a full no-op: at least one dimension must strictly
+        // change in the requested direction, so a successful call always changes state and the
+        // emitted event is never spurious.
+        if (raising) {
+            if (
+                absoluteCap < cfg.absoluteCap || percentageCapBps < cfg.percentageCapBps
+                    || (absoluteCap == cfg.absoluteCap && percentageCapBps == cfg.percentageCapBps)
+            ) {
+                revert IHub.NotIncreasing();
+            }
+        } else {
+            if (
+                absoluteCap > cfg.absoluteCap || percentageCapBps > cfg.percentageCapBps
+                    || (absoluteCap == cfg.absoluteCap && percentageCapBps == cfg.percentageCapBps)
+            ) {
+                revert IHub.NotDecreasing();
+            }
+        }
+
+        cfg.absoluteCap = absoluteCap;
+        cfg.percentageCapBps = percentageCapBps;
+        if (raising) {
+            emit IHub.YieldGroupCapRaised(yieldGroup, absoluteCap, percentageCapBps);
+        } else {
+            emit IHub.YieldGroupCapLowered(yieldGroup, absoluteCap, percentageCapBps);
+        }
+    }
+
+    // ============================== Outer queues ==============================
+
+    /**
+     * @notice Validate a candidate deposit routing queue (every entry registered, no duplicates).
+     *         The caller (Hub) performs the storage assignment + event, since a calldata array
+     *         cannot be copied through a storage-pointer parameter here.
+     * @param yieldGroups Hub's per-YieldGroup config mapping (storage ref) for the registered check.
+     * @param queue Candidate queue in deposit-priority order.
+     */
+    function validateDepositQueue(
+        mapping(address => IHub.YieldGroupConfig) storage yieldGroups,
+        address[] calldata queue
+    ) external view {
+        _validateQueue(yieldGroups, queue);
+    }
+
+    /**
+     * @notice Validate a candidate withdraw routing queue: valid (registered, no duplicates) AND
+     *         covering every funded registered YieldGroup. The caller (Hub) performs the storage
+     *         assignment + event.
+     * @param yieldGroups Hub's per-YieldGroup config mapping (storage ref) for the registered check.
+     * @param registeredYieldGroups Hub's registry array (storage ref) for the funded-coverage check.
+     * @param queue Candidate queue in withdraw-priority order.
+     */
+    function validateWithdrawQueue(
+        mapping(address => IHub.YieldGroupConfig) storage yieldGroups,
+        address[] storage registeredYieldGroups,
+        address[] calldata queue
+    ) external view {
+        _validateQueue(yieldGroups, queue);
+        _requireWithdrawQueueCoversFundedYieldGroups(registeredYieldGroups, queue);
+    }
+
+    // ============================== Internal helpers ==========================
+
+    /**
+     * @notice Remove the first occurrence of `target` from `queue` via swap-and-pop.
+     * @param queue Storage array to mutate.
+     * @param target Address to remove (no-op if absent).
+     */
+    function _removeFromQueue(address[] storage queue, address target) private {
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            if (queue[i] == target) {
+                if (i != len - 1) {
+                    queue[i] = queue[len - 1];
+                }
+                queue.pop();
+                return;
+            }
+        }
+    }
+
+    /**
+     * @notice Revert if the candidate withdraw queue omits any registered YieldGroup that still
+     *         custodies a balance. A YieldGroup whose `totalAssets()` reverts is treated as funded.
+     * @param registeredYieldGroups Hub's registry array (storage ref).
+     * @param queue Candidate withdraw queue.
+     */
+    function _requireWithdrawQueueCoversFundedYieldGroups(
+        address[] storage registeredYieldGroups,
+        address[] calldata queue
+    ) private view {
+        uint256 rlen = registeredYieldGroups.length;
+        for (uint256 i; i < rlen; ++i) {
+            address yieldGroup = registeredYieldGroups[i];
+            bool funded;
+            try IYieldGroupBase(yieldGroup).totalAssets() returns (uint256 v) {
+                funded = v > 0;
+            } catch {
+                funded = true;
+            }
+            if (funded && !_queueContains(queue, yieldGroup)) {
+                revert IHub.WithdrawQueueOmitsFundedYieldGroup(yieldGroup);
+            }
+        }
+    }
+
+    /**
+     * @notice Validate a routing queue: every entry registered, no duplicates.
+     * @param yieldGroups Hub's per-YieldGroup config mapping (storage ref).
+     * @param queue Candidate queue.
+     */
+    function _validateQueue(mapping(address => IHub.YieldGroupConfig) storage yieldGroups, address[] calldata queue)
+        private
+        view
+    {
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            address yieldGroup = queue[i];
+            if (!yieldGroups[yieldGroup].registered) revert IHub.YieldGroupNotRegistered(yieldGroup);
+            for (uint256 j = i + 1; j < len; ++j) {
+                if (queue[j] == yieldGroup) revert IHub.InvalidQueue();
+            }
+        }
+    }
+
+    /**
+     * @notice Linear membership test over a calldata address array.
+     * @param queue Array to scan.
+     * @param target Address to find.
+     * @return found True iff `target` appears in `queue`.
+     */
+    function _queueContains(address[] calldata queue, address target) private pure returns (bool found) {
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            if (queue[i] == target) return true;
+        }
+        return false;
+    }
+}

package/contracts/YieldGroup/YieldGroup.sol

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
+import { IYieldGroup } from "../interfaces/IYieldGroup.sol";
+import { IYieldGroupBase } from "../interfaces/IYieldGroupBase.sol";
+import { YieldGroupBase } from "./base/YieldGroupBase.sol";
+
+/**
+ * @title YieldGroup
+ * @author Venus
+ * @notice The generic concrete YieldGroup, shared by the synchronous families. "Core" (Venus
+ *         vTokens) and "Flux" (Fluid fTokens) are the same contract behind different beacons; a
+ *         family is a *deployment identity* — which adapter + resources + per-resource caps +
+ *         `blocksPerYear` value get wired into the proxy — not a code difference.
+ * @dev Adds to {YieldGroupBase}: the optional per-resource deposit cap (the cap-aware
+ *      `_resourceDepositRoom` override + its raise/lower governance surface), the `blocksPerYear`
+ *      annualiser used by `spotAPYBps`, and the `accrue()` poke loop that settles block-lazy
+ *      interest before the Hub reads NAV. Lifecycle families (FRV) use {YieldGroupFRV} instead.
+ *      Inheritance order is load-bearing for upgrade safety — do not reorder.
+ */
+contract YieldGroup is YieldGroupBase, IYieldGroup {
+    // ============================== External — mutating =======================
+    // -- Initialisation --
+
+    /// @inheritdoc IYieldGroup
+    function initialize(address hub_, address asset_, uint256 blocksPerYear_, address acm_) external initializer {
+        __YieldGroupBase_init(hub_, asset_, blocksPerYear_, acm_);
+    }
+
+    // -- Resource caps (asymmetric) --
+
+    /// @inheritdoc IYieldGroup
+    function raiseResourceCap(address resource, uint256 newCap) external override {
+        _checkAccessAllowed("raiseResourceCap(address,uint256)");
+        if (!_resourcesConfig[resource].registered) revert ResourceNotRegistered(resource);
+        // `0` = unbounded, so compare in effective terms: a raise must be strictly looser.
+        if (_effectiveResourceCap(newCap) <= _effectiveResourceCap(_resourceCap[resource])) {
+            revert NotIncreasing();
+        }
+        _resourceCap[resource] = newCap;
+        emit ResourceCapRaised(resource, newCap);
+    }
+
+    /// @inheritdoc IYieldGroup
+    function lowerResourceCap(address resource, uint256 newCap) external override {
+        _checkAccessAllowed("lowerResourceCap(address,uint256)");
+        if (!_resourcesConfig[resource].registered) revert ResourceNotRegistered(resource);
+        // A lower must set a real (non-zero) cap strictly tighter than the current one;
+        // `0` means unbounded, which is a raise, not a lower.
+        if (newCap == 0 || _effectiveResourceCap(newCap) >= _effectiveResourceCap(_resourceCap[resource])) {
+            revert NotDecreasing();
+        }
+        _resourceCap[resource] = newCap;
+        emit ResourceCapLowered(resource, newCap);
+    }
+
+    // -- Blocks-per-year annualiser (governance) --
+
+    /// @inheritdoc IYieldGroup
+    function setBlocksPerYear(uint256 newBlocksPerYear) external override {
+        _checkAccessAllowed("setBlocksPerYear(uint256)");
+        uint256 old = _blocksPerYear;
+        _blocksPerYear = newBlocksPerYear;
+        emit BlocksPerYearSet(old, newBlocksPerYear);
+    }
+
+    // -- IYieldGroupBase: accrue --
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Pokes every registered resource (the same set {totalAssets} sums, paused included) to
+    ///      settle interest up to this block. Best-effort: a resource whose accrual reverts is
+    ///      skipped and left at its last-settled rate rather than bubbling and bricking the Hub's
+    ///      fee accrual. Resources whose NAV is a live preview (Fluid) make each call a no-op.
+    function accrue() external override(YieldGroupBase, IYieldGroupBase) onlyHub {
+        address[] storage list = _resources;
+        uint256 len = list.length;
+        for (uint256 i; i < len; ++i) {
+            address adapter = _resourcesConfig[list[i]].adapter;
+            try IResourceAdapter(adapter).accrue(list[i]) { }
+            catch {
+                emit ResourceAccrualFailed(list[i], adapter);
+            }
+        }
+    }
+
+    // ============================== External — view ==========================
+
+    /// @inheritdoc IYieldGroup
+    function blocksPerYear() external view override returns (uint256) {
+        return _blocksPerYear;
+    }
+
+    /// @inheritdoc IYieldGroup
+    function resourceCap(address resource) external view override returns (uint256) {
+        return _resourceCap[resource];
+    }
+
+    // ============================== Internal — view ==========================
+
+    /**
+     * @inheritdoc YieldGroupBase
+     * @dev Clamps the protocol-level headroom by this YieldGroup's optional per-resource cap.
+     *      When no cap is set (`0`), returns the protocol headroom directly and skips the balance
+     *      lookup entirely — the cap feature is zero-cost when unused. When set, the operator
+     *      headroom is `cap − our current balance` (floored at zero).
+     */
+    function _resourceDepositRoom(address resource, address adapter) internal view override returns (uint256 room) {
+        uint256 protocolRoom = IResourceAdapter(adapter).maxDeposit(resource);
+        uint256 cap = _resourceCap[resource];
+        if (cap == 0) return protocolRoom;
+
+        uint256 held = IResourceAdapter(adapter).totalAssets(resource, address(this));
+        uint256 operatorRoom = cap > held ? cap - held : 0;
+        return protocolRoom < operatorRoom ? protocolRoom : operatorRoom;
+    }
+
+    /**
+     * @notice Map the stored cap sentinel to a comparable value: `0` (unset) becomes the max
+     *         uint, so an unbounded cap sorts above every finite cap in the raise/lower
+     *         comparisons and never binds in the deposit-room math.
+     * @param storedCap Raw value from `_resourceCap`.
+     * @return effective `type(uint256).max` when `storedCap == 0`, else `storedCap`.
+     */
+    function _effectiveResourceCap(uint256 storedCap) private pure returns (uint256 effective) {
+        return storedCap == 0 ? type(uint256).max : storedCap;
+    }
+}

package/contracts/YieldGroup/YieldGroupFRV.sol

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
+import { IYieldGroupBase } from "../interfaces/IYieldGroupBase.sol";
+import { IYieldGroupFRV } from "../interfaces/IYieldGroupFRV.sol";
+import { IFRVVault } from "../interfaces/external/IFRVVault.sol";
+import { YieldGroupBase } from "./base/YieldGroupBase.sol";
+
+/**
+ * @title YieldGroupFRV
+ * @author Venus
+ * @notice Per-asset YieldGroup that aggregates one or more Venus Fixed Rate Vaults behind the
+ *         standard `IYieldGroupBase` Hub boundary; deployed behind a proxy, one per (Hub, asset).
+ * @dev A thin subclass of {YieldGroupBase}. FRV-specific concerns, all expressed by overriding the
+ *      base's virtual hooks:
+ *        - Each vault has a lifecycle state machine (`Fundraising → Lock → Matured / Closed`).
+ *          `_prepareResource` advances it via `vault.updateVaultState()` before every
+ *          deposit/withdraw sizing read, so capacity / liquidity reflect current state.
+ *        - `_minDeposit` returns the vault's `minSupplierDeposit`, so a sub-floor non-tail deposit
+ *          is skipped (cascade) or rejected cleanly (targeted) instead of failing inside the vault.
+ *      FRV has no per-resource cap (it inherits the base's raw `_resourceDepositRoom`) and no
+ *      `blocksPerYear` (it initialises it to `0`; `AdapterFRV` ignores the annualiser). It adds the
+ *      `forceRemoveResource` escape hatch for orphaning a permanently un-drainable (Closed) vault.
+ *      Inheritance order is load-bearing for upgrade safety — do not reorder.
+ */
+contract YieldGroupFRV is YieldGroupBase, IYieldGroupFRV {
+    // ============================== External — mutating =======================
+    // -- Initialisation --
+
+    /// @inheritdoc IYieldGroupFRV
+    function initialize(address hub_, address asset_, address acm_) external initializer {
+        // FRV has no per-block rate to annualise, so `blocksPerYear` is 0.
+        __YieldGroupBase_init(hub_, asset_, 0, acm_);
+    }
+
+    // -- Resource registry (governance) --
+
+    // -- IYieldGroupBase: accrue --
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Poke every registered vault's state so the Hub's NAV read sees the current state, not a
+    ///      stale `Fundraising` (valued at principal, no coupon). Best-effort: a reverting poke is
+    ///      skipped, not bubbled.
+    function accrue() external override(YieldGroupBase, IYieldGroupBase) onlyHub {
+        address[] storage list = _resources;
+        uint256 len = list.length;
+        for (uint256 i; i < len; ++i) {
+            try IFRVVault(list[i]).updateVaultState() { }
+            catch {
+                emit ResourceAccrualFailed(list[i], _resourcesConfig[list[i]].adapter);
+            }
+        }
+    }
+
+    /// @inheritdoc IYieldGroupFRV
+    function forceRemoveResource(address resource) external override {
+        _checkAccessAllowed("forceRemoveResource(address)");
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+
+        // A resource may only be force-orphaned once it holds no realizable value (NAV == 0), which
+        // for FRV is true only of a Closed vault's residual shares (`AdapterFRV.totalAssets` values
+        // a Closed position at 0). Note the gate is NAV, not `maxWithdraw`: a live FRV vault is
+        // non-withdrawable (`maxWithdraw == 0`) all through Fundraising, Lock and PendingSettlement
+        // while still backing real funds, so withdrawability would wrongly pass a healthy vault.
+        uint256 nav = IResourceAdapter(cfg.adapter).totalAssets(resource, address(this));
+        if (nav != 0) revert ResourceHasValue(resource, nav);
+
+        uint256 orphaned = IResourceAdapter(cfg.adapter).receiptBalance(resource, address(this));
+
+        uint256 idxPlusOne = _resourceIndex[resource];
+        uint256 idx = idxPlusOne - 1;
+        uint256 lastIdx = _resources.length - 1;
+        if (idx != lastIdx) {
+            address last = _resources[lastIdx];
+            _resources[idx] = last;
+            _resourceIndex[last] = idxPlusOne;
+        }
+        _resources.pop();
+        delete _resourceIndex[resource];
+
+        _removeFromQueue(_innerDepositQueue, resource);
+        _removeFromQueue(_innerWithdrawQueue, resource);
+
+        delete _resourcesConfig[resource];
+
+        emit ResourceForceRemoved(resource, orphaned);
+    }
+
+    // ============================== Internal — virtual hooks =================
+
+    /// @dev Advance the FRV vault's lifecycle state machine before each sizing read. Without this,
+    ///      a vault past its fundraising window would report stale capacity and the deposit call
+    ///      inside the adapter would revert instead of gracefully skipping. Invoked outside the
+    ///      cascade try/catch — a poke failure is a genuinely broken vault, not the skip class.
+    function _prepareResource(address resource) internal override {
+        IFRVVault(resource).updateVaultState();
+    }
+
+    /// @dev FRV's per-resource minimum deposit floor. A vault rejects a deposit below
+    ///      `minSupplierDeposit` unless it exactly fills the vault's remaining capacity (the
+    ///      residual tail), which the base routing handles via this floor.
+    function _minDeposit(address resource) internal view override returns (uint256) {
+        return IFRVVault(resource).config().minSupplierDeposit;
+    }
+}