@venusprotocol/liquidity-hub 0.0.0

package/contracts/YieldGroup/base/YieldGroupBase.sol

@@ -0,0 +1,797 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { Address } from "@openzeppelin/contracts/utils/Address.sol";
+import {
+    ReentrancyGuardUpgradeable
+} from "@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol";
+
+import {
+    IAccessControlManagerV8
+} from "@venusprotocol/governance-contracts/contracts/Governance/IAccessControlManagerV8.sol";
+
+import { IHub } from "../../interfaces/IHub.sol";
+import { IYieldGroupBase } from "../../interfaces/IYieldGroupBase.sol";
+import { IResourceAdapter } from "../../interfaces/IResourceAdapter.sol";
+import { YieldGroupBaseStorage } from "./YieldGroupBaseStorage.sol";
+
+/**
+ * @title YieldGroupBase
+ * @author Venus
+ * @notice Shared base for every concrete YieldGroup — the generic `YieldGroup` (Core / Flux) and
+ *         the `YieldGroupFRV` subclass. Holds the entire registry / queue / pause / deposit /
+ *         withdraw / view machinery behind the standard `IYieldGroupBase` Hub boundary; deployed
+ *         behind a proxy, one per (Hub, asset).
+ * @dev Architecture: Hub → YieldGroup* → IResourceAdapter (via delegatecall) → resource.
+ *      The YieldGroup is **ABI-agnostic**: every protocol-specific concern (mint signature,
+ *      treasury-fee gross-up, supply-cap math, APY annualisation) lives in the adapter.
+ *      Inheritance order is load-bearing for upgrade safety — do not reorder.
+ *
+ *      Family divergence is captured by four `internal virtual` hooks, all defaulting here to the
+ *      simplest behavior; a concrete overrides only what its family needs:
+ *        - `_prepareResource`     (mutating) — advance a resource's internal state before sizing
+ *                                              (FRV: `updateVaultState()`); default no-op.
+ *        - `_minDeposit`          (view)     — per-resource minimum deposit floor (FRV:
+ *                                              `minSupplierDeposit`); default 0.
+ *        - `_resourceDepositRoom` (view)     — spare deposit room (generic: cap-aware); default the
+ *                                              raw protocol headroom.
+ *        - `accrue`               (external) — settle interest (generic: poke loop); default no-op.
+ *
+ *      Stateless shared adapters: each registered resource carries an adapter address. The
+ *      adapter is invoked via DELEGATECALL for mutating functions, so receipt tokens are
+ *      credited to / burned from this YieldGroup directly (`msg.sender` to the underlying
+ *      protocol is this contract, not the adapter). One adapter deployment per ABI family
+ *      serves every YieldGroup that registers a matching resource — no per-asset adapter
+ *      instances, no proxies, no clones.
+ *
+ *      Adding a new ABI family later (e.g. Core_V2): deploy a single new stateless adapter
+ *      and call `addResource(newResource, newAdapter)` on each affected YieldGroup. No
+ *      changes to this contract, to the Hub, or to existing adapters.
+ *
+ *      Delegatecall safety: adapter implementations MUST follow the storage-safety
+ *      invariants documented on {IResourceAdapter} (zero state variables, no `sstore` in
+ *      assembly, only trusted callees). `addResource` rejects EOAs to prevent silent
+ *      no-op delegatecalls; revert bubbling is handled by `Address.functionDelegateCall`.
+ */
+abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseStorage, IYieldGroupBase {
+    using SafeERC20 for IERC20;
+    using Address for address;
+
+    // ============================== Modifiers ================================
+
+    /// @notice Reverts {NotHub} when the caller is not the registered Hub.
+    modifier onlyHub() {
+        if (msg.sender != _hub) revert NotHub(msg.sender);
+        _;
+    }
+
+    // ============================== Constructor ==============================
+
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    // ============================== Internal — initialisation =================
+
+    /**
+     * @notice Shared initialiser invoked by each concrete's public `initialize`.
+     * @dev Validates `IHub(hub_).asset() == asset_` so a misconfigured deployment cannot
+     *      route the wrong underlying. There is intentionally no `blocksPerYear_ != 0` guard:
+     *      `blocksPerYear` only annualises the informational `spotAPYBps` view, and families whose
+     *      adapter pre-annualises (Flux) or has no per-block rate (FRV) initialise it to `0`.
+     * @param hub_ Hub authorised to call `deposit` / `withdraw`.
+     * @param asset_ Underlying ERC-20 (must match `Hub.asset()`).
+     * @param blocksPerYear_ Per-chain block cadence used only for spot-APY annualisation; `0` when
+     *        the family's adapter ignores it.
+     * @param acm_ AccessControlManagerV8 gating governance calls.
+     */
+    function __YieldGroupBase_init(address hub_, address asset_, uint256 blocksPerYear_, address acm_)
+        internal
+        onlyInitializing
+    {
+        if (hub_ == address(0) || asset_ == address(0) || acm_ == address(0)) revert ZeroAddress();
+        address hubAsset = IHub(hub_).asset();
+        if (hubAsset != asset_) revert HubAssetMismatch(asset_, hubAsset);
+
+        __ReentrancyGuard_init();
+
+        _hub = hub_;
+        _assetToken = asset_;
+        _blocksPerYear = blocksPerYear_;
+        _accessControlManager = acm_;
+    }
+
+    // ============================== External — mutating =======================
+    // -- Resource registry (governance) --
+
+    /// @inheritdoc IYieldGroupBase
+    function addResource(address resource, address adapter) external override {
+        _checkAccessAllowed("addResource(address,address)");
+        if (resource == address(0) || adapter == address(0)) revert ZeroAddress();
+        if (_resourcesConfig[resource].registered) revert ResourceAlreadyRegistered(resource);
+        if (resource.code.length == 0) revert ResourceNotContract(resource);
+        // Reject EOAs explicitly: delegatecall to an EOA returns success with empty data,
+        // which would silently no-op every deposit/withdraw through this resource.
+        if (adapter.code.length == 0) revert AdapterNotContract(adapter);
+
+        // The adapter is the only contract that knows the resource's ABI; routing
+        // asset-match validation through it keeps this YieldGroup family-agnostic.
+        address resourceAsset = IResourceAdapter(adapter).asset(resource);
+        if (resourceAsset != _assetToken) revert ResourceAssetMismatch(resource, resourceAsset, _assetToken);
+
+        // Let the adapter veto a resource that fails a protocol-specific precondition — e.g. a
+        // Core market whose Comptroller charges a non-zero treasuryPercent, an exit fee that
+        // leaves the pool on redeem without burning shares and so is unmodeled in the gross NAV.
+        IResourceAdapter(adapter).validateRegistration(resource);
+
+        _resources.push(resource);
+        _resourceIndex[resource] = _resources.length;
+        _resourcesConfig[resource] = ResourceConfig({ registered: true, paused: false, adapter: adapter });
+
+        emit ResourceAdded(resource, adapter);
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function removeResource(address resource) external override {
+        _checkAccessAllowed("removeResource(address)");
+        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));
+        if (held != 0) revert ResourceHasBalance(resource, held);
+
+        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);
+
+        // Clear the per-resource cap too: leaving it set would let a later re-`addResource` of the
+        // 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 _resourcesConfig[resource];
+
+        emit ResourceRemoved(resource);
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function updateResourceAdapter(address resource, address newAdapter) external override {
+        _checkAccessAllowed("updateResourceAdapter(address,address)");
+        if (newAdapter == address(0)) revert ZeroAddress();
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+        // Reject EOAs: delegatecall to an EOA succeeds with empty data and silently no-ops routing.
+        if (newAdapter.code.length == 0) revert AdapterNotContract(newAdapter);
+
+        // Validate the new adapter exactly as addResource does; the held balance and registry slot
+        // are untouched, only the adapter pointer changes.
+        address resourceAsset = IResourceAdapter(newAdapter).asset(resource);
+        if (resourceAsset != _assetToken) revert ResourceAssetMismatch(resource, resourceAsset, _assetToken);
+        IResourceAdapter(newAdapter).validateRegistration(resource);
+
+        address oldAdapter = cfg.adapter;
+        cfg.adapter = newAdapter;
+
+        emit ResourceAdapterUpdated(resource, oldAdapter, newAdapter);
+    }
+
+    // -- Inner queues (Operator) --
+
+    /// @inheritdoc IYieldGroupBase
+    function setInnerDepositQueue(address[] calldata queue) external override {
+        _checkAccessAllowed("setInnerDepositQueue(address[])");
+        _validateQueue(queue);
+        _innerDepositQueue = queue;
+        emit InnerDepositQueueSet(queue);
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function setInnerWithdrawQueue(address[] calldata queue) external override {
+        _checkAccessAllowed("setInnerWithdrawQueue(address[])");
+        _validateQueue(queue);
+        _requireWithdrawQueueCoversFundedResources(queue);
+        _innerWithdrawQueue = queue;
+        emit InnerWithdrawQueueSet(queue);
+    }
+
+    // -- Pause (asymmetric) --
+
+    /// @inheritdoc IYieldGroupBase
+    function pauseResource(address resource) external override {
+        _checkAccessAllowed("pauseResource(address)");
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+        // Idempotent: pausing an already-paused resource is a silent no-op (mirrors Hub.pauseYieldGroup).
+        if (!cfg.paused) {
+            cfg.paused = true;
+            emit ResourcePauseToggled(resource, true);
+        }
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function unpauseResource(address resource) external override {
+        _checkAccessAllowed("unpauseResource(address)");
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+        // Idempotent: unpausing an already-unpaused resource is a silent no-op (mirrors Hub).
+        if (cfg.paused) {
+            cfg.paused = false;
+            emit ResourcePauseToggled(resource, false);
+        }
+    }
+
+    // -- Sweep (governance) --
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Bars `asset()` (idle, counted in `totalAssets`) and every registered resource: in all
+    ///      current families the resource address *is* the receipt token this YieldGroup holds, so
+    ///      sweeping one would drain the backing. A removed resource is unregistered, so any residual
+    ///      it left behind is recoverable. Zero balance is a silent no-op.
+    function sweep(address token, address to) external override nonReentrant {
+        _checkAccessAllowed("sweep(address,address)");
+        if (to == address(0)) revert ZeroAddress();
+        if (token == _assetToken) revert SweepProtectedAsset();
+        if (_resourcesConfig[token].registered) revert SweepProtectedResource(token);
+
+        uint256 bal = IERC20(token).balanceOf(address(this));
+        if (bal > 0) {
+            IERC20(token).safeTransfer(to, bal);
+            emit Swept(token, to, bal);
+        }
+    }
+
+    // -- IYieldGroupBase: deposit / withdraw --
+
+    /// @inheritdoc IYieldGroupBase
+    function deposit(uint256 amount)
+        external
+        override(IYieldGroupBase)
+        onlyHub
+        nonReentrant
+        returns (uint256 deposited)
+    {
+        IERC20(_assetToken).safeTransferFrom(msg.sender, address(this), amount);
+
+        uint256 remaining = amount;
+        address[] storage queue = _innerDepositQueue;
+        uint256 len = queue.length;
+        for (uint256 i; i < len && remaining > 0; ++i) {
+            remaining -= _tryDepositOneResource(queue[i], remaining);
+        }
+
+        // Refund the unplaced remainder to the caller and return the amount actually placed.
+        // The Hub routes the refund on to the next YieldGroup in its queue.
+        if (remaining > 0) IERC20(_assetToken).safeTransfer(msg.sender, remaining);
+        return amount - remaining;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function withdraw(uint256 amount, address to) external override(IYieldGroupBase) onlyHub nonReentrant {
+        uint256 remaining = amount;
+
+        // Use idle first (free, no redeem). Idle accumulates from gross-up surplus on past
+        // withdrawals; consuming it before touching a resource keeps balances clean.
+        uint256 idle = IERC20(_assetToken).balanceOf(address(this));
+        if (idle > 0) {
+            uint256 fromIdle = idle < remaining ? idle : remaining;
+            IERC20(_assetToken).safeTransfer(to, fromIdle);
+            remaining -= fromIdle;
+        }
+
+        address[] storage queue = _innerWithdrawQueue;
+        uint256 len = queue.length;
+        for (uint256 i; i < len && remaining > 0; ++i) {
+            remaining -= _tryWithdrawOneResource(queue[i], remaining, to);
+        }
+
+        if (remaining > 0) revert ResourceLiquidityInsufficient(amount, amount - remaining);
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Base default: no-op. Block-lazy families (the generic `YieldGroup` serving Core)
+    ///      override this to poke each registered resource and settle interest up to this block;
+    ///      preview-NAV families (Flux, FRV) keep the no-op because their value is read live.
+    // solhint-disable-next-line no-empty-blocks
+    function accrue() external virtual override(IYieldGroupBase) onlyHub { }
+
+    // -- IYieldGroupBase: resource-targeted reallocation (Operator, via Hub) --
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Bypasses the inner deposit queue to place the full `amount` into one resource.
+    ///      Reverts on under-capacity rather than partial-filling, so the Hub's reallocate
+    ///      net-zero accounting holds. Refuses paused resources (do not route into a paused
+    ///      market — mirrors the queue path skipping them). The resource need not be in
+    ///      `_innerWithdrawQueue`: value placed outside it counts in `totalAssets()` but is not
+    ///      reached by the withdraw cascade until it is (re)added via {setInnerWithdrawQueue}.
+    function depositResource(address resource, uint256 amount)
+        external
+        override(IYieldGroupBase)
+        onlyHub
+        nonReentrant
+        returns (uint256 deposited)
+    {
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+        if (cfg.paused) revert ResourceIsPaused(resource);
+
+        IERC20(_assetToken).safeTransferFrom(msg.sender, address(this), amount);
+
+        _prepareResource(resource);
+
+        address adapter = cfg.adapter;
+        uint256 room = _resourceDepositRoom(resource, adapter);
+        if (amount > room) revert ResourceCapacityExceeded(amount, room);
+
+        // A subclass that imposes a per-resource minimum deposit (e.g. FRV's `minSupplierDeposit`)
+        // rejects a sub-minimum amount unless it is the exact residual tail (`amount == room`),
+        // which a resource always accepts. Reject it cleanly here rather than bubbling the
+        // resource's own opaque error. For the generic `YieldGroup`, `_minDeposit` is 0 and this
+        // block never triggers.
+        if (amount < room) {
+            uint256 minDeposit = _minDeposit(resource);
+            if (amount < minDeposit) revert ResourceBelowMinimumDeposit(resource, amount, minDeposit);
+        }
+
+        _dispatchDeposit(adapter, resource, amount);
+        return amount;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Bypasses both the idle-first path and the inner withdraw queue: redeems the full
+    ///      `amount` from one resource and delivers it to `to`, or reverts. Pulling from a
+    ///      paused resource is allowed (winding down a paused market is the intended use).
+    function withdrawResource(address resource, uint256 amount, address to)
+        external
+        override(IYieldGroupBase)
+        onlyHub
+        nonReentrant
+    {
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered) revert ResourceNotRegistered(resource);
+
+        _prepareResource(resource);
+
+        address adapter = cfg.adapter;
+        uint256 liquid = IResourceAdapter(adapter).maxWithdraw(resource, address(this));
+        if (amount > liquid) revert ResourceLiquidityInsufficient(amount, liquid);
+
+        uint256 received = _dispatchWithdraw(adapter, resource, amount, to);
+        if (received != amount) revert AdapterUnderfilled(resource, amount, received);
+    }
+
+    // ============================== External — view ==========================
+
+    /// @inheritdoc IYieldGroupBase
+    function hub() external view override returns (address) {
+        return _hub;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function accessControlManager() external view override returns (address) {
+        return _accessControlManager;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function resources() external view override returns (address[] memory) {
+        return _resources;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function resourceConfig(address resource)
+        external
+        view
+        override
+        returns (bool registered, bool paused, address adapter)
+    {
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        return (cfg.registered, cfg.paused, cfg.adapter);
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function innerDepositQueue() external view override returns (address[] memory) {
+        return _innerDepositQueue;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function innerWithdrawQueue() external view override returns (address[] memory) {
+        return _innerWithdrawQueue;
+    }
+
+    // -- IYieldGroupBase views --
+
+    /// @inheritdoc IYieldGroupBase
+    function asset() external view override(IYieldGroupBase) returns (address) {
+        return _assetToken;
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev `Σ resource value` (via each resource's adapter) plus any idle asset on the
+    ///      YieldGroup. Idle accrues from treasury-fee gross-up surplus on past withdrawals.
+    ///      `virtual` so a future family can override the valuation; today every family (the generic
+    ///      `YieldGroup` and `YieldGroupFRV`) shares this gross sum of per-resource adapter values.
+    function totalAssets() external view virtual override(IYieldGroupBase) returns (uint256 total) {
+        address[] storage list = _resources;
+        uint256 len = list.length;
+        for (uint256 i; i < len; ++i) {
+            address resource = list[i];
+            total += IResourceAdapter(_resourcesConfig[resource].adapter).totalAssets(resource, address(this));
+        }
+        total += IERC20(_assetToken).balanceOf(address(this));
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    function maxDeposit() external view override(IYieldGroupBase) returns (uint256 total) {
+        address[] storage queue = _innerDepositQueue;
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            address resource = queue[i];
+            ResourceConfig storage cfg = _resourcesConfig[resource];
+            if (cfg.registered && !cfg.paused) {
+                uint256 room = _resourceDepositRoom(resource, cfg.adapter);
+                // Only advertise capacity the cascade can actually place for any amount <= it. A
+                // subclass with a per-resource minimum deposit only accepts a sub-floor amount as
+                // the exact residual tail; reporting room below that floor would break the
+                // `deposit(maxDeposit())` honesty contract, so report 0 for such a resource. For
+                // the generic `YieldGroup`, `_minDeposit` is 0 and `room` always passes.
+                uint256 minDep = _minDeposit(resource);
+                // solhint-disable-next-line gas-strict-inequalities
+                total += room >= minDep ? room : 0;
+            }
+        }
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev Includes idle (deliverable without redeem) and each unpaused queue entry's
+    ///      net-of-protocol-fee redeemable amount.
+    function maxWithdraw() external view override(IYieldGroupBase) returns (uint256 total) {
+        address[] storage queue = _innerWithdrawQueue;
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            address resource = queue[i];
+            ResourceConfig storage cfg = _resourcesConfig[resource];
+            if (cfg.registered && !cfg.paused) {
+                total += IResourceAdapter(cfg.adapter).maxWithdraw(resource, address(this));
+            }
+        }
+        total += IERC20(_assetToken).balanceOf(address(this));
+    }
+
+    /// @inheritdoc IYieldGroupBase
+    /// @dev TVL-weighted across registered resources. Each adapter returns its own spot APY;
+    ///      we weight by underlying value held. Saturates at `uint64.max` to defend against
+    ///      a misreporting adapter.
+    function spotAPYBps() external view override(IYieldGroupBase) returns (uint64) {
+        uint256 totalVal;
+        uint256 weighted;
+        address[] storage list = _resources;
+        uint256 len = list.length;
+        uint256 bpy = _blocksPerYear;
+        for (uint256 i; i < len; ++i) {
+            address resource = list[i];
+            address adapter = _resourcesConfig[resource].adapter;
+            uint256 resVal = IResourceAdapter(adapter).totalAssets(resource, address(this));
+            if (resVal > 0) {
+                uint256 apy = IResourceAdapter(adapter).spotAPYBps(resource, bpy);
+                weighted += apy * resVal;
+                totalVal += resVal;
+            }
+        }
+        if (totalVal == 0) return 0;
+        uint256 spot = weighted / totalVal;
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return spot > type(uint64).max ? type(uint64).max : uint64(spot);
+    }
+
+    // ============================== Internal — view ==========================
+
+    /**
+     * @notice ACM check used by every governance-gated entry point.
+     * @param signature ACM role string to authorise against `msg.sender`.
+     */
+    function _checkAccessAllowed(string memory signature) internal view {
+        if (!IAccessControlManagerV8(_accessControlManager).isAllowedToCall(msg.sender, signature)) {
+            revert Unauthorized(msg.sender, signature);
+        }
+    }
+
+    // ============================== Private — mutating =======================
+
+    /**
+     * @notice Try to deposit up to `remaining` into one resource via its adapter. Skips
+     *         unregistered / paused.
+     * @dev Delegatecalls the adapter so receipt tokens (e.g. vTokens) are credited to this
+     *      YieldGroup, not the adapter. `Address.functionDelegateCall` validates the adapter
+     *      is a contract and bubbles any revert reason.
+     * @param resource Resource to deposit into.
+     * @param remaining Underlying units still needing placement.
+     * @return placed Underlying units placed into `resource`.
+     */
+    function _tryDepositOneResource(address resource, uint256 remaining) private returns (uint256 placed) {
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered || cfg.paused) return 0;
+
+        // Advance the resource's internal state (FRV: `updateVaultState()`) BEFORE sizing, so the
+        // room read reflects current state. Stays OUTSIDE the dispatch try/catch below — a poke
+        // failure is a genuinely broken resource, not the route-around-on-revert class.
+        _prepareResource(resource);
+
+        address adapter = cfg.adapter;
+        uint256 room = _resourceDepositRoom(resource, adapter);
+        uint256 toDeposit = remaining < room ? remaining : room;
+        if (toDeposit == 0) return 0;
+
+        // A subclass with a per-resource minimum deposit skips a sub-floor leg that is not the exact
+        // residual tail (`toDeposit == room`), so the cascade continues to the next resource instead
+        // of reverting with the resource's own minimum-deposit error. For the generic `YieldGroup`,
+        // `_minDeposit` is 0 and this is dead.
+        if (toDeposit < room && toDeposit < _minDeposit(resource)) return 0;
+
+        // Route around a resource whose deposit reverts (e.g. its external protocol paused it after
+        // the views certified capacity) instead of bubbling. The adapter's allowance is set inside
+        // the delegatecall and rolls back atomically on revert, so nothing to reset here. A skip
+        // returns 0, so the cascade's backstop still reverts the whole op when no healthy resource
+        // can absorb the full amount.
+        try this.dispatchDepositExternal(adapter, resource, toDeposit) returns (uint256 p) {
+            return p;
+        } catch {
+            emit ResourceSkipped(resource, true);
+            return 0;
+        }
+    }
+
+    /**
+     * @notice Try to withdraw up to `remaining` from one resource via its adapter. Skips
+     *         unregistered / paused.
+     * @dev Delegatecalls the adapter so `redeemUnderlying` (or equivalent) burns this
+     *      YieldGroup's receipt tokens and credits underlying to `to`. The recipient's balance
+     *      delta is measured and, in the success branch (outside the skip `catch`), asserted equal
+     *      to `toDeliver`; a shortfall reverts {AdapterUnderfilled} and halts the whole withdraw
+     *      rather than being silently routed around.
+     * @param resource Resource to pull from.
+     * @param remaining Underlying units still needing collection.
+     * @param to Recipient of the underlying.
+     * @return delivered Underlying units delivered to `to` from this resource.
+     */
+    function _tryWithdrawOneResource(address resource, uint256 remaining, address to)
+        private
+        returns (uint256 delivered)
+    {
+        ResourceConfig storage cfg = _resourcesConfig[resource];
+        if (!cfg.registered || cfg.paused) return 0;
+
+        // Advance the resource's internal state (FRV: `updateVaultState()`, which may unlock funds
+        // via a lifecycle transition) before reading liquidity. Outside the dispatch try/catch.
+        _prepareResource(resource);
+
+        address adapter = cfg.adapter;
+        uint256 liquid = IResourceAdapter(adapter).maxWithdraw(resource, address(this));
+        uint256 toDeliver = remaining < liquid ? remaining : liquid;
+        if (toDeliver == 0) return 0;
+
+        // Skip-on-revert for the withdraw leg (see `_tryDepositOneResource`): an external-protocol
+        // revert (pause, cap, reentrancy-blocked leg) lands in `catch` and routes around this
+        // resource. Under-delivery is OUR own accounting invariant, not a route-around case, so it
+        // is asserted in the success branch below; a revert there is not caught by the `catch` and
+        // propagates, halting the whole withdraw loudly. This mirrors the Hub's own YieldGroup
+        // underfill guard in `_tryWithdrawOneYieldGroup` and needs no error-selector matching.
+        try this.dispatchWithdrawExternal(adapter, resource, toDeliver, to) returns (uint256 received) {
+            if (received != toDeliver) revert AdapterUnderfilled(resource, toDeliver, received);
+            return received;
+        } catch {
+            emit ResourceSkipped(resource, false);
+            return 0;
+        }
+    }
+
+    /**
+     * @notice Delegatecall the adapter to deposit exactly `amount` into `resource` and emit
+     *         {DepositRouted}.
+     * @dev Shared by the inner-queue deposit path and the resource-targeted reallocate path.
+     *      Callers own the registration / pause / capacity checks and must ensure this
+     *      YieldGroup already holds `amount` of underlying. Delegatecall credits receipt
+     *      tokens to this YieldGroup; `Address.functionDelegateCall` bubbles adapter reverts.
+     * @param adapter Adapter bound to `resource`.
+     * @param resource Resource to deposit into.
+     * @param amount Underlying units to place (exact).
+     */
+    function _dispatchDeposit(address adapter, address resource, uint256 amount) private {
+        adapter.functionDelegateCall(abi.encodeCall(IResourceAdapter.deposit, (resource, amount)));
+        emit DepositRouted(resource, amount);
+    }
+
+    /**
+     * @notice Delegatecall the adapter to redeem `amount` from `resource` to `to`, emit
+     *         {WithdrawRouted}, and return the recipient's measured balance delta.
+     * @dev Shared by the inner-queue withdraw path and the resource-targeted reallocate path.
+     *      Callers own the registration / liquidity checks and the under-delivery invariant: this
+     *      returns the amount actually received so each caller can assert `received == amount` in
+     *      its own frame (a shortfall reverts {AdapterUnderfilled}). Deliberately does NOT revert on
+     *      a shortfall itself — doing so inside the cascade's external self-call frame would blur
+     *      our own invariant with an external-protocol revert and force selector-matching to tell
+     *      them apart. The delta is cheap defensive verification against a future-adapter regression.
+     * @param adapter Adapter bound to `resource`.
+     * @param resource Resource to pull from.
+     * @param amount Underlying units to deliver to `to` (exact).
+     * @param to Recipient of the underlying.
+     * @return received Underlying units actually delivered to `to`, measured by balance delta.
+     */
+    function _dispatchWithdraw(address adapter, address resource, uint256 amount, address to)
+        private
+        returns (uint256 received)
+    {
+        IERC20 assetToken = IERC20(_assetToken);
+        uint256 preBalTo = assetToken.balanceOf(to);
+        adapter.functionDelegateCall(abi.encodeCall(IResourceAdapter.withdraw, (resource, amount, to)));
+        received = assetToken.balanceOf(to) - preBalTo;
+
+        emit WithdrawRouted(resource, amount);
+    }
+
+    /**
+     * @notice External self-call shell so the inner deposit cascade can `try/catch` a per-resource
+     *         dispatch — a library delegatecall cannot be wrapped directly. Reverts unless the
+     *         caller is this YieldGroup itself.
+     * @dev Runs the shared {_dispatchDeposit} body in external context. `address(this)` stays the
+     *      YieldGroup, so the adapter's `onlyDelegateCall` check still passes. NOT `nonReentrant`
+     *      (the cascade self-call must not trip the guard held by the public entrypoint) and NOT
+     *      used by the strict reallocate path, which keeps calling `_dispatchDeposit` directly.
+     * @param adapter Adapter bound to `resource`.
+     * @param resource Resource to deposit into.
+     * @param amount Underlying units to place (exact).
+     * @return placed Underlying units placed (equals `amount` on success).
+     */
+    // solhint-disable-next-line ordering
+    function dispatchDepositExternal(address adapter, address resource, uint256 amount)
+        external
+        returns (uint256 placed)
+    {
+        if (msg.sender != address(this)) revert OnlySelf();
+        _dispatchDeposit(adapter, resource, amount);
+        return amount;
+    }
+
+    /**
+     * @notice External self-call shell so the inner withdraw cascade can `try/catch` a per-resource
+     *         dispatch. Same guard and context guarantees as {dispatchDepositExternal}.
+     * @param adapter Adapter bound to `resource`.
+     * @param resource Resource to pull from.
+     * @param amount Underlying units to deliver to `to` (exact).
+     * @param to Recipient of the underlying.
+     * @return received Underlying units actually delivered (the caller asserts `received == amount`
+     *         in its own frame; see {_tryWithdrawOneResource}).
+     */
+    // solhint-disable-next-line ordering
+    function dispatchWithdrawExternal(address adapter, address resource, uint256 amount, address to)
+        external
+        returns (uint256 received)
+    {
+        if (msg.sender != address(this)) revert OnlySelf();
+        return _dispatchWithdraw(adapter, resource, amount, to);
+    }
+
+    /**
+     * @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) internal {
+        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;
+            }
+        }
+    }
+
+    // ============================== Private — view ===========================
+
+    /**
+     * @notice Validate a routing queue: every entry registered, no duplicates.
+     * @param queue Candidate queue.
+     */
+    function _validateQueue(address[] calldata queue) private view {
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            address resource = queue[i];
+            if (!_resourcesConfig[resource].registered) revert ResourceNotRegistered(resource);
+            for (uint256 j = i + 1; j < len; ++j) {
+                if (queue[j] == resource) revert InvalidQueue();
+            }
+        }
+    }
+
+    /**
+     * @notice Revert if `queue` omits any registered resource that still holds receipt tokens.
+     * @param queue Candidate withdraw queue.
+     */
+    function _requireWithdrawQueueCoversFundedResources(address[] calldata queue) private view {
+        address[] storage list = _resources;
+        uint256 len = list.length;
+        for (uint256 i; i < len; ++i) {
+            address resource = list[i];
+            uint256 held = IResourceAdapter(_resourcesConfig[resource].adapter).receiptBalance(resource, address(this));
+            if (held != 0 && !_queueContains(queue, resource)) {
+                revert WithdrawQueueOmitsFundedResource(resource);
+            }
+        }
+    }
+
+    /**
+     * @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;
+    }
+
+    // ============================== Internal — virtual hooks =================
+    // These capture the entire per-family divergence; each concrete overrides only what it needs.
+
+    /**
+     * @notice Advance a resource's internal state before a deposit/withdraw sizing read.
+     * @dev Base default: no-op. `YieldGroupFRV` overrides to call `IFRVVault.updateVaultState()`.
+     *      Mutating, and invoked OUTSIDE the cascade try/catch so a poke failure halts the
+     *      operation rather than being routed around.
+     */
+    // solhint-disable-next-line no-empty-blocks
+    function _prepareResource(
+        address /* resource */
+    )
+        internal
+        virtual { }
+
+    /**
+     * @notice Per-resource minimum deposit floor.
+     * @dev Base default: `0` (no floor). `YieldGroupFRV` overrides to return the vault's
+     *      `minSupplierDeposit`. A non-zero floor makes a sub-floor non-tail deposit skip (cascade)
+     *      or revert (targeted) instead of failing inside the resource.
+     * @return minimum Minimum deposit in asset units (`0` = no floor).
+     */
+    function _minDeposit(
+        address /* resource */
+    )
+        internal
+        view
+        virtual
+        returns (uint256 minimum)
+    {
+        return 0;
+    }
+
+    /**
+     * @notice Spare deposit room for `resource` right now.
+     * @dev Base default: the resource's protocol-level headroom, unclamped. The generic
+     *      `YieldGroup` overrides this to further clamp by its optional per-resource cap; lifecycle
+     *      families (FRV) keep the raw headroom.
+     * @param resource Resource to size.
+     * @param adapter Adapter bound to `resource`.
+     * @return room Protocol-level deposit headroom for `resource`.
+     */
+    function _resourceDepositRoom(address resource, address adapter) internal view virtual returns (uint256 room) {
+        return IResourceAdapter(adapter).maxDeposit(resource);
+    }
+}