@venusprotocol/liquidity-hub 0.0.0

package/contracts/Hub/Hub.sol

@@ -0,0 +1,1614 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
+import { ERC4626Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC4626Upgradeable.sol";
+import { IERC4626Upgradeable } from "@openzeppelin/contracts-upgradeable/interfaces/IERC4626Upgradeable.sol";
+import {
+    ReentrancyGuardUpgradeable
+} from "@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol";
+import { SafeERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol";
+
+import { AccessControlledV8 } from "@venusprotocol/governance-contracts/contracts/Governance/AccessControlledV8.sol";
+
+import { IHub } from "../interfaces/IHub.sol";
+import { IYieldGroupBase } from "../interfaces/IYieldGroupBase.sol";
+import { HubStorage } from "./HubStorage.sol";
+import { HubAdminLib } from "./lib/HubAdminLib.sol";
+
+/**
+ * @title Hub
+ * @author Venus
+ * @notice Per-asset ERC-4626 vault that aggregates yield by routing deposits and withdrawals
+ *         across multiple YieldGroups (typed routers to Venus Core vTokens, Fluid markets, FRVs, ...).
+ * @dev Architecture: Hub → YieldGroup → Vault. Hub never reaches past a YieldGroup.
+ *      Atomic-or-revert: every deposit / withdraw / reallocate fully completes or reverts.
+ *      Inheritance order is load-bearing for upgrade safety — do not reorder.
+ *      Function ordering follows the Solidity style guide: external → public → internal →
+ *      private, mutating before view within each group.
+ */
+contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeable, HubStorage, IHub {
+    using SafeERC20Upgradeable for IERC20Upgradeable;
+
+    // ============================== State (constants) =========================
+
+    /// @notice BPS denominator (`10_000` = 100%).
+    uint16 public constant BPS_DENOMINATOR = 10_000;
+
+    /// @notice Fixed-point scale for share-price math.
+    uint256 public constant EXP_SCALE = 1e18;
+
+    /// @notice Maximum allowed inflation-defense decimals offset.
+    /// @dev Capped at 12 (not 18): above ~12 the performance-fee branch loses resolution
+    ///      because the HWM seed `EXP_SCALE / 10^offset` shrinks faster than realistic
+    ///      per-share gains can climb past it, silently zeroing the performance fee.
+    uint8 public constant MAX_DECIMALS_OFFSET = 12;
+
+    /// @notice Maximum fee rate in BPS (50%).
+    uint16 public constant MAX_FEE_BPS = 5000;
+
+    /// @notice Maximum exit (withdraw/redeem) fee rate in BPS (5%). Far tighter than `MAX_FEE_BPS`:
+    ///         an exit fee is a small anti-sandwich friction, never a primary revenue lever.
+    uint16 public constant MAX_REDEEM_FEE_BPS = 500;
+
+    /// @notice Ceiling on the management fee a single `_accrueFees` call may charge, as a
+    ///         fraction of `totalAssets()` in BPS (100%). At 100% the per-accrual clamp only
+    ///         binds once the elapsed-window fee would exceed 100% of TA, so a normal accrual
+    ///         charges its full elapsed-window fee with no intermediate smoothing.
+    /// @dev The backstop against a >100% drain is the mint guard in `_accrueFees`
+    ///      (`totalFee < totalAssets()`): an accrual whose combined management + performance fee
+    ///      reaches 100% of TA is skipped and forfeited, not minted, while the cursor still
+    ///      advances (the clamp caps `mgmtAssetFee` at TA and consumes only the window that
+    ///      produces it, so any excess beyond 100% defers to the next call). Reaching that point
+    ///      needs a near-max fee rate left un-accrued long enough for the owed fee to hit TA;
+    ///      fees accrue on every deposit / withdraw, so normal operation never approaches it.
+    uint16 public constant MAX_MGMT_FEE_PER_ACCRUAL_BPS = 10_000;
+
+    /// @notice Seconds per year, used for management fee proration.
+    uint256 public constant SECONDS_PER_YEAR = 365 days;
+
+    // ============================== Modifiers ================================
+
+    /// @notice Reverts {HubPaused} when the Hub is paused.
+    modifier whenNotHubPaused() {
+        if (_hubPaused) revert HubPaused();
+        _;
+    }
+
+    // ============================== Constructor ==============================
+
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    // ============================== External — mutating =======================
+
+    /**
+     * @notice Initialise the Hub
+     * @dev The underlying `asset_` MUST be a standard ERC-20: fee-on-transfer, deflationary, and
+     *      rebasing tokens are unsupported. The deposit path routes the full requested amount to
+     *      YieldGroups without measuring the received balance, so an asset that delivers less than
+     *      requested on transfer reverts the deposit (fails closed — no loss of funds).
+     * @param asset_ Underlying asset of the vault
+     * @param name_ ERC-20 name for the share token
+     * @param symbol_ ERC-20 symbol for the share token
+     * @param acm_ AccessControlManagerV8 instance gating governance functions
+     * @param decimalsOffset_ ERC-4626 inflation-defense offset. MUST be > 0 for EVERY asset
+     *        regardless of decimals (e.g. 6): a non-zero offset is what makes the first-deposit
+     *        inflation attack non-griefing, not merely non-profitable. Offset 0 would let a
+     *        donation attack zero a first depositor's shares, so it is rejected on-chain.
+     *        Bounded above by MAX_DECIMALS_OFFSET.
+     * @param initialMaxWithdrawalSize Initial per-transaction withdraw cap, in asset units
+     * @param feeRecipient_ Initial fee-share recipient (zero address disables fee minting)
+     * @custom:access Permissionless once (OZ `initializer` modifier prevents re-init)
+     * @custom:error Throws ZeroAddress if asset_ or acm_ is the zero address
+     * @custom:error Throws InvalidDecimalsOffset if decimalsOffset_ == 0 or > MAX_DECIMALS_OFFSET
+     * @custom:error Throws ZeroAmount if initialMaxWithdrawalSize == 0
+     */
+    function initialize(
+        IERC20Upgradeable asset_,
+        string calldata name_,
+        string calldata symbol_,
+        address acm_,
+        uint8 decimalsOffset_,
+        uint256 initialMaxWithdrawalSize,
+        address feeRecipient_
+    ) external initializer {
+        if (address(asset_) == address(0)) revert ZeroAddress();
+        if (acm_ == address(0)) revert ZeroAddress();
+        if (decimalsOffset_ == 0 || decimalsOffset_ > MAX_DECIMALS_OFFSET) revert InvalidDecimalsOffset();
+        if (initialMaxWithdrawalSize == 0) revert ZeroAmount();
+
+        __ERC20_init(name_, symbol_);
+        __ERC4626_init(asset_);
+        __AccessControlled_init(acm_);
+        __ReentrancyGuard_init();
+
+        _decimalsOffsetStored = decimalsOffset_;
+        _maxWithdrawalSize = initialMaxWithdrawalSize;
+        // `feeRecipient_ == address(0)` is permitted and disables fee-share minting in
+        // `_accrueFees` (the HWM and accrual timestamps still advance). Governance can
+        // later set a non-zero recipient via `setFeeRecipient`.
+        _feeRecipient = feeRecipient_;
+
+        uint64 nowTs = uint64(block.timestamp);
+        _lastFeeAccrualTimestamp = nowTs;
+        _lastFeeAccrualBlock = uint64(block.number);
+        // HWM is denominated as `totalAssets × EXP_SCALE / totalSupply`. With a non-zero
+        // `decimalsOffset_`, the very first deposit produces `ts = assets × 10^offset` so
+        // launch PPS = `EXP_SCALE / 10^offset`, not `EXP_SCALE`. Setting HWM to the
+        // launch PPS prevents the performance-fee branch from being permanently dead
+        // (PPS unable to climb past EXP_SCALE under realistic yields) when offset > 0.
+        _highWaterMarkPerShare = EXP_SCALE / (10 ** uint256(decimalsOffset_));
+    }
+
+    // -- YieldGroup registry (governance) --
+
+    /**
+     * @notice Add a YieldGroup to the registry with initial caps
+     * @dev Pause flag defaults to false. Does not auto-append to either outer queue —
+     *      governance must call setOuterDepositQueue / setOuterWithdrawQueue separately
+     *      to start routing flow to the new YieldGroup. Validates that the YieldGroup reports
+     *      the same underlying asset as the Hub.
+     * @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)
+     * @custom:access ACM-gated role "addYieldGroup(address,uint256,uint16)" (VIP)
+     * @custom:event Emits YieldGroupAdded on successful registration
+     * @custom:error Throws ZeroAddress if yieldGroup is the zero address
+     * @custom:error Throws YieldGroupAlreadyRegistered if yieldGroup is already in the registry
+     * @custom:error Throws InvalidCap if percentageCapBps > 10_000 or absoluteCap == type(uint256).max
+     * @custom:error Throws YieldGroupAssetMismatch if the YieldGroup's asset() does not match the Hub's
+     */
+    function addYieldGroup(address yieldGroup, uint256 absoluteCap, uint16 percentageCapBps) external override {
+        _checkAccessAllowed("addYieldGroup(address,uint256,uint16)");
+        HubAdminLib.addYieldGroup(
+            _yieldGroups, _registeredYieldGroups, _yieldGroupIndex, yieldGroup, absoluteCap, percentageCapBps, asset()
+        );
+    }
+
+    /**
+     * @notice Remove a YieldGroup from the registry
+     * @dev Requires the YieldGroup to hold zero resource-backed value when
+     *      `IYieldGroupBase.totalAssets()` is readable — drain via reallocate first. Idle asset
+     *      sitting directly on the YieldGroup (e.g. a dust donation anyone can make to a drained
+     *      group) is netted out of this check so it cannot block removal; any such residual is
+     *      handled out-of-band. If that view reverts (a bricked / buggy YieldGroup) removal is
+     *      permitted anyway as an emergency eviction, again with residual value handled out-of-band,
+     *      so a misbehaving YieldGroup can be evicted without a Hub upgrade. Uses swap-and-pop on
+     *      the registry array and cascade-strips the YieldGroup from both outer queues so callers
+     *      never observe a queue entry that points to an unregistered YieldGroup.
+     * @param yieldGroup YieldGroup to remove
+     * @custom:access ACM-gated role "removeYieldGroup(address)" (VIP)
+     * @custom:event Emits YieldGroupRemoved on successful removal
+     * @custom:error Throws YieldGroupNotRegistered if yieldGroup is not in the registry
+     * @custom:error Throws YieldGroupHasBalance if yieldGroup holds readable, non-zero resource-backed value
+     */
+    function removeYieldGroup(address yieldGroup) external override {
+        _checkAccessAllowed("removeYieldGroup(address)");
+        HubAdminLib.removeYieldGroup(
+            _yieldGroups,
+            _registeredYieldGroups,
+            _yieldGroupIndex,
+            _outerDepositQueue,
+            _outerWithdrawQueue,
+            yieldGroup,
+            asset()
+        );
+    }
+
+    /**
+     * @notice Raise a YieldGroup's caps
+     * @dev A YieldGroup's intake is bounded by two independent ceilings, and the binding limit is
+     *      whichever is lower:
+     *      - `absoluteCap`: a fixed ceiling in asset units.
+     *      - `percentageCapBps`: a ceiling relative to live `totalAssets()`, in BPS.
+     *      Effective cap = `min(absoluteCap, percentageCapBps × totalAssets() / 10_000)`, except
+     *      the sentinel `percentageCapBps == 10_000` (100%) disables the percentage dimension so
+     *      only `absoluteCap` binds. Because the percentage component tracks `totalAssets()`, a
+     *      YieldGroup's effective cap moves with Hub TVL even when neither stored value changes. See
+     *      `yieldGroupEffectiveCap` for the resolved live value.
+     *
+     *      Raise is monotonic: both dimensions must be ≥ their current values AND at least one
+     *      must strictly increase; a full no-op (both equal to current) reverts NotIncreasing so
+     *      the emitted YieldGroupCapRaised event always reflects a real state change.
+     * @param yieldGroup YieldGroup whose caps are being raised
+     * @param absoluteCap New absolute cap in asset units (≥ current)
+     * @param percentageCapBps New percentage cap in BPS (≥ current, ≤ 10_000; 10_000 = % disabled)
+     * @custom:access ACM-gated role "raiseYieldGroupCap(address,uint256,uint16)" (Guardian or VIP)
+     * @custom:event Emits YieldGroupCapRaised on successful update
+     * @custom:error Throws YieldGroupNotRegistered if yieldGroup is not in the registry
+     * @custom:error Throws InvalidCap if percentageCapBps > 10_000 or absoluteCap == type(uint256).max
+     * @custom:error Throws NotIncreasing if either new value is < its current value, or both are unchanged
+     */
+    function raiseYieldGroupCap(address yieldGroup, uint256 absoluteCap, uint16 percentageCapBps) external override {
+        _checkAccessAllowed("raiseYieldGroupCap(address,uint256,uint16)");
+        HubAdminLib.setYieldGroupCap(_yieldGroups, yieldGroup, absoluteCap, percentageCapBps, true);
+    }
+
+    /**
+     * @notice Lower a YieldGroup's caps
+     * @dev Caps are the two independent ceilings described on `raiseYieldGroupCap`: `absoluteCap`
+     *      (fixed, asset units) and `percentageCapBps` (relative to live `totalAssets()`), with
+     *      the binding limit being their min and `percentageCapBps == 10_000` disabling the
+     *      percentage dimension. Lowering either tightens intake immediately; existing balance
+     *      above the new cap is not force-unwound but the YieldGroup receives no new deposits until
+     *      it is back under cap. See `yieldGroupEffectiveCap` for the resolved live value.
+     *
+     *      Lower is monotonic: both dimensions must be ≤ their current values AND at least one
+     *      must strictly decrease; a full no-op (both equal to current) reverts NotDecreasing so
+     *      the emitted YieldGroupCapLowered event always reflects a real state change.
+     * @param yieldGroup YieldGroup whose caps are being lowered
+     * @param absoluteCap New absolute cap in asset units (≤ current)
+     * @param percentageCapBps New percentage cap in BPS (≤ current; 10_000 = % disabled)
+     * @custom:access ACM-gated role "lowerYieldGroupCap(address,uint256,uint16)" (Operator or VIP)
+     * @custom:event Emits YieldGroupCapLowered on successful update
+     * @custom:error Throws YieldGroupNotRegistered if yieldGroup is not in the registry
+     * @custom:error Throws InvalidCap if percentageCapBps > 10_000 or absoluteCap == type(uint256).max
+     * @custom:error Throws NotDecreasing if either new value is > its current value, or both are unchanged
+     */
+    function lowerYieldGroupCap(address yieldGroup, uint256 absoluteCap, uint16 percentageCapBps) external override {
+        _checkAccessAllowed("lowerYieldGroupCap(address,uint256,uint16)");
+        HubAdminLib.setYieldGroupCap(_yieldGroups, yieldGroup, absoluteCap, percentageCapBps, false);
+    }
+
+    // -- Outer queues (Operator) --
+
+    /**
+     * @notice Replace the deposit routing order
+     * @dev Validates the queue contains no duplicates and only registered YieldGroups. YieldGroups
+     *      that are registered but absent from the queue still contribute to `totalAssets()`
+     *      and remain withdrawable, but receive no new deposits. Pass an empty array to
+     *      effectively pause new-deposit routing without pausing the Hub.
+     *      Operator responsibility: keep every queue member in `_outerWithdrawQueue`. A member absent
+     *      from the withdraw queue is funded by deposits but not reached by the normal redeem path
+     *      until it is (re)added there. Recovery is one tx and lossless (re-set the withdraw queue,
+     *      or drain via reallocate); not enforced on-chain.
+     * @param queue Full replacement queue in deposit-priority order
+     * @custom:access ACM-gated role "setOuterDepositQueue(address[])" (Operator)
+     * @custom:event Emits OuterDepositQueueSet on successful update
+     * @custom:error Throws InvalidQueue if queue contains duplicates or unregistered YieldGroups
+     */
+    function setOuterDepositQueue(address[] calldata queue) external override {
+        _checkAccessAllowed("setOuterDepositQueue(address[])");
+        HubAdminLib.validateDepositQueue(_yieldGroups, queue);
+        _outerDepositQueue = queue;
+        emit OuterDepositQueueSet(queue);
+    }
+
+    /**
+     * @notice Replace the withdraw routing order
+     * @dev The replacement must keep every balance-holding registered YieldGroup reachable: a new
+     *      queue that omits a YieldGroup still custodying a balance is rejected, so the Operator
+     *      cannot strand redeemable value by dropping a funded YieldGroup. Drain a YieldGroup via
+     *      reallocate (it then reports a zero balance) before removing it from the queue.
+     * @param queue Full replacement queue in withdraw-priority order
+     * @custom:access ACM-gated role "setOuterWithdrawQueue(address[])" (Operator)
+     * @custom:event Emits OuterWithdrawQueueSet on successful update
+     * @custom:error Throws InvalidQueue if queue contains duplicates or unregistered YieldGroups
+     * @custom:error Throws WithdrawQueueOmitsFundedYieldGroup if the queue omits a funded registered YieldGroup
+     */
+    function setOuterWithdrawQueue(address[] calldata queue) external override {
+        _checkAccessAllowed("setOuterWithdrawQueue(address[])");
+        HubAdminLib.validateWithdrawQueue(_yieldGroups, _registeredYieldGroups, queue);
+        _outerWithdrawQueue = queue;
+        emit OuterWithdrawQueueSet(queue);
+    }
+
+    // -- Reallocate (Operator) / Emergency reallocate (governance) --
+
+    /**
+     * @notice Atomically rebalance assets across YieldGroups
+     * @dev Withdraw legs execute first, then deposit legs. `Σ withdraws == Σ deposits` is
+     *      strictly enforced — funds cannot enter or leave the system via reallocate.
+     *      Fees are accrued before any leg so the operation trades against the
+     *      post-accrual state. Each push leg honours per-YieldGroup caps and the destination's
+     *      pause flag. Reentrancy-guarded; reverts while the Hub is paused (use the
+     *      governance-gated {emergencyReallocate} to wind down a stressed position during a pause).
+     *      A push leg need not target a withdraw-queue member: funds placed in a YieldGroup outside
+     *      `_outerWithdrawQueue` count in `totalAssets()` but are not reached by user withdrawals until
+     *      the target is (re)added via {setOuterWithdrawQueue}.
+     * @param withdraws Ordered list of (yieldGroup, resource, amount) legs to pull from
+     * @param deposits Ordered list of (yieldGroup, resource, amount) legs to push into
+     * @custom:access ACM-gated role "reallocate((address,address,uint256)[],(address,address,uint256)[])" (Operator)
+     * @custom:event Emits WithdrawRouted per pull leg and DepositRouted per push leg
+     * @custom:event Emits FeesAccrued / HighWaterMarkUpdated as side effects of pre-leg accrual
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws YieldGroupNotRegistered if any leg targets an unregistered YieldGroup
+     * @custom:error Throws YieldGroupPaused if any deposit leg targets a paused YieldGroup
+     * @custom:error Throws YieldGroupUnderfilled if a YieldGroup returns fewer assets than requested on a leg
+     * @custom:error Throws HubCapacityExceeded if a deposit leg exceeds the destination's effective cap
+     * @custom:error Throws ReallocateImbalanced if Σ withdraws ≠ Σ deposits
+     */
+    function reallocate(IHub.ReallocateLeg[] calldata withdraws, IHub.ReallocateLeg[] calldata deposits)
+        external
+        override
+        nonReentrant
+        whenNotHubPaused
+    {
+        _checkAccessAllowed("reallocate((address,address,uint256)[],(address,address,uint256)[])");
+        _reallocate(withdraws, deposits);
+    }
+
+    /**
+     * @notice Emergency rebalance that remains callable while the Hub is paused, giving governance
+     *         a wind-down lever for exactly the conditions that prompt a pause.
+     * @dev Identical net-zero semantics to {reallocate}, but split by authority: {reallocate} is the
+     *      Operator's routine rebalancing lever and is frozen during a pause, whereas this is
+     *      governance's emergency lever that bypasses the pause. The two carry separate ACM roles so
+     *      governance can hold the pause-bypassing path without granting it to the Operator. Fee
+     *      accrual is skipped while the Hub is paused so the frozen window is never charged (the
+     *      accrual cursor stays put until {unpauseHub} resets it); called while unpaused it accrues
+     *      like {reallocate}. This is a routing and containment lever, not a way to force-unlock a
+     *      resource: every pull leg is still bound by the resource's own withdrawability, so a leg
+     *      against a locked FRV vault reverts (its adapter `maxWithdraw` is 0 all through Fundraising,
+     *      Lock, PendingSettlement and SettlementDeadlineExceeded, non-zero only at a terminal state).
+     *      Emergency reallocation can therefore route around FRV exposure and move liquid resources,
+     *      but cannot pull FRV principal out early, that capital is only reachable once the vault
+     *      reaches Matured / Failed / Liquidated.
+     * @param withdraws Ordered list of (yieldGroup, resource, amount) legs to pull from
+     * @param deposits Ordered list of (yieldGroup, resource, amount) legs to push into
+     * @custom:access ACM-gated role
+     *   "emergencyReallocate((address,address,uint256)[],(address,address,uint256)[])" (Guardian or VIP)
+     * @custom:event Emits WithdrawRouted per pull leg and DepositRouted per push leg
+     * @custom:event Emits FeesAccrued / HighWaterMarkUpdated when called while unpaused (skipped during a pause)
+     * @custom:error Throws YieldGroupNotRegistered if any leg targets an unregistered YieldGroup
+     * @custom:error Throws YieldGroupPaused if any deposit leg targets a paused YieldGroup
+     * @custom:error Throws YieldGroupUnderfilled if a YieldGroup returns fewer assets than requested on a leg
+     * @custom:error Throws HubCapacityExceeded if a deposit leg exceeds the destination's effective cap
+     * @custom:error Throws ReallocateImbalanced if Σ withdraws ≠ Σ deposits
+     */
+    function emergencyReallocate(IHub.ReallocateLeg[] calldata withdraws, IHub.ReallocateLeg[] calldata deposits)
+        external
+        override
+        nonReentrant
+    {
+        _checkAccessAllowed("emergencyReallocate((address,address,uint256)[],(address,address,uint256)[])");
+        _reallocate(withdraws, deposits);
+    }
+
+    // -- Pause --
+
+    /**
+     * @notice Pause the Hub
+     * @dev Blocks all ERC-4626 entry points (deposit/mint/withdraw/redeem), reallocate,
+     *      accrueFees, and the fee setters (setManagementFeeBps, setPerformanceFeeBps,
+     *      setFeeRecipient). `sweep` and `emergencyReallocate` stay callable so stray-token
+     *      rescue and stressed-position wind-down remain available during a freeze. View
+     *      functions remain readable. Records the pause start; `unpauseHub` later excludes this
+     *      window from management-fee accrual. Pause makes no external call, so a bricked
+     *      `totalAssets()` cannot block it. Idempotent — calling while already paused is a silent
+     *      no-op.
+     * @custom:access ACM-gated role "pauseHub()" (Operator, Guardian, or VIP)
+     * @custom:event Emits HubPauseToggled(true) on transition from unpaused to paused
+     */
+    function pauseHub() external override {
+        _checkAccessAllowed("pauseHub()");
+        if (!_hubPaused) {
+            // Record the pause start; unpauseHub excludes this window from fee accrual. No external
+            // call here, so a bricked totalAssets() can't block the pause.
+            _pauseStart = uint64(block.timestamp);
+            _hubPaused = true;
+            emit HubPauseToggled(true);
+        }
+    }
+
+    /**
+     * @notice Unpause the Hub
+     * @dev Advances the fee-accrual cursor by the pause duration so the frozen window does not
+     *      contribute to management-fee proration. Only the time-based management fee is excluded
+     *      from the pause window. The high-water mark is intentionally left unchanged, so real
+     *      per-share gains the underlying protocols earn while the Hub is paused stay subject to the
+     *      performance fee on the first post-resume accrual: the performance fee is a share of
+     *      realized profit, not an availability charge, and the mark is only re-anchored on a true
+     *      cohort reset (refill from empty), never on a pause. Idempotent — calling while
+     *      already unpaused is a silent no-op.
+     * @custom:access ACM-gated role "unpauseHub()" (VIP)
+     * @custom:event Emits HubPauseToggled(false) on transition from paused to unpaused
+     */
+    function unpauseHub() external override {
+        _checkAccessAllowed("unpauseHub()");
+        if (_hubPaused) {
+            _hubPaused = false;
+            // Advance the proration cursor by the pause duration so the frozen window isn't charged.
+            _lastFeeAccrualTimestamp += uint64(block.timestamp) - _pauseStart;
+            emit HubPauseToggled(false);
+        }
+    }
+
+    /**
+     * @notice Pause routing to a specific YieldGroup
+     * @dev Existing YieldGroup balance still counts toward `totalAssets()` (NAV) but is no
+     *      longer reachable by the user withdraw / redeem queue, which skips paused YieldGroups;
+     *      it can only be unwound via {reallocate} / {emergencyReallocate}. New deposit /
+     *      reallocate-push legs targeting this YieldGroup revert with YieldGroupPaused. Idempotent —
+     *      paused-when-paused is a silent no-op.
+     * @param yieldGroup YieldGroup to pause
+     * @custom:access ACM-gated role "pauseYieldGroup(address)" (Operator or VIP)
+     * @custom:event Emits YieldGroupPauseToggled(yieldGroup, true) on transition from unpaused to paused
+     * @custom:error Throws YieldGroupNotRegistered if yieldGroup is not in the registry
+     */
+    function pauseYieldGroup(address yieldGroup) external override {
+        _checkAccessAllowed("pauseYieldGroup(address)");
+        IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+        if (!cfg.registered) revert YieldGroupNotRegistered(yieldGroup);
+        if (!cfg.paused) {
+            cfg.paused = true;
+            emit YieldGroupPauseToggled(yieldGroup, true);
+        }
+    }
+
+    /**
+     * @notice Unpause routing to a specific YieldGroup
+     * @param yieldGroup YieldGroup to unpause
+     * @custom:access ACM-gated role "unpauseYieldGroup(address)" (VIP)
+     * @custom:event Emits YieldGroupPauseToggled(yieldGroup, false) on transition from paused to unpaused
+     * @custom:error Throws YieldGroupNotRegistered if yieldGroup is not in the registry
+     */
+    function unpauseYieldGroup(address yieldGroup) external override {
+        _checkAccessAllowed("unpauseYieldGroup(address)");
+        IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+        if (!cfg.registered) revert YieldGroupNotRegistered(yieldGroup);
+        if (cfg.paused) {
+            cfg.paused = false;
+            emit YieldGroupPauseToggled(yieldGroup, false);
+        }
+    }
+
+    // -- Per-tx withdraw cap --
+
+    /**
+     * @notice Raise the per-transaction withdraw cap
+     * @param newSize New cap in asset units (strictly > current)
+     * @custom:access ACM-gated role "raiseMaxWithdrawalSize(uint256)" (VIP)
+     * @custom:event Emits MaxWithdrawalSizeRaised on successful update
+     * @custom:error Throws NotIncreasing if newSize ≤ current cap (no-op equal value is also rejected
+     *               so the emitted event always reflects a real state change)
+     */
+    function raiseMaxWithdrawalSize(uint256 newSize) external override {
+        _checkAccessAllowed("raiseMaxWithdrawalSize(uint256)");
+        _setMaxWithdrawalSize(newSize, true);
+    }
+
+    /**
+     * @notice Lower the per-transaction withdraw cap
+     * @param newSize New cap in asset units (strictly < current; must be > 0)
+     * @custom:access ACM-gated role "lowerMaxWithdrawalSize(uint256)" (Operator or VIP)
+     * @custom:event Emits MaxWithdrawalSizeLowered on successful update
+     * @custom:error Throws NotDecreasing if newSize ≥ current cap (no-op equal value is also rejected
+     *               so the emitted event always reflects a real state change)
+     * @custom:error Throws ZeroAmount if newSize == 0 (matches the initialize-time guard)
+     */
+    function lowerMaxWithdrawalSize(uint256 newSize) external override {
+        _checkAccessAllowed("lowerMaxWithdrawalSize(uint256)");
+        _setMaxWithdrawalSize(newSize, false);
+    }
+
+    // -- Fees --
+
+    /**
+     * @notice Set the management fee rate
+     * @dev Accrues pending fees at the OLD rate first so the change does not retroactively
+     *      revalue elapsed time. Capped at MAX_FEE_BPS (50%).
+     * @param bps New management fee rate in BPS (≤ MAX_FEE_BPS)
+     * @custom:access ACM-gated role "setManagementFeeBps(uint16)" (VIP)
+     * @custom:event Emits ManagementFeeBpsSet on successful update
+     * @custom:event Emits FeesAccrued / HighWaterMarkUpdated as side effects of pre-set accrual
+     * @custom:error Throws InvalidFeeBps if bps > MAX_FEE_BPS
+     * @custom:error Throws HubPaused if the Hub is paused
+     */
+    function setManagementFeeBps(uint16 bps) external override whenNotHubPaused {
+        _checkAccessAllowed("setManagementFeeBps(uint16)");
+        if (bps > MAX_FEE_BPS) revert InvalidFeeBps(bps);
+        _accrueFees();
+        uint16 old = _managementFeeBps;
+        _managementFeeBps = bps;
+        emit ManagementFeeBpsSet(old, bps);
+    }
+
+    /**
+     * @notice Set the performance fee rate
+     * @param bps New performance fee rate in BPS (≤ MAX_FEE_BPS)
+     * @custom:access ACM-gated role "setPerformanceFeeBps(uint16)" (VIP)
+     * @custom:event Emits PerformanceFeeBpsSet on successful update
+     * @custom:event Emits FeesAccrued / HighWaterMarkUpdated as side effects of pre-set accrual
+     * @custom:error Throws InvalidFeeBps if bps > MAX_FEE_BPS
+     * @custom:error Throws HubPaused if the Hub is paused
+     */
+    function setPerformanceFeeBps(uint16 bps) external override whenNotHubPaused {
+        _checkAccessAllowed("setPerformanceFeeBps(uint16)");
+        if (bps > MAX_FEE_BPS) revert InvalidFeeBps(bps);
+        _accrueFees();
+        uint16 old = _performanceFeeBps;
+        _performanceFeeBps = bps;
+        emit PerformanceFeeBpsSet(old, bps);
+    }
+
+    /**
+     * @notice Set the exit (withdraw/redeem) fee rate, retained in the vault and socialised to
+     *         remaining LPs as a price-per-share uplift. An anti-sandwich governance 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); default 0.
+     * @param bps New exit fee rate in BPS (≤ MAX_REDEEM_FEE_BPS)
+     * @custom:access ACM-gated role "setRedeemFeeBps(uint16)" (VIP)
+     * @custom:event Emits RedeemFeeBpsSet on successful update
+     * @custom:error Throws InvalidFeeBps if bps > MAX_REDEEM_FEE_BPS
+     * @custom:error Throws HubPaused if the Hub is paused
+     */
+    function setRedeemFeeBps(uint16 bps) external override whenNotHubPaused {
+        _checkAccessAllowed("setRedeemFeeBps(uint16)");
+        if (bps > MAX_REDEEM_FEE_BPS) revert InvalidFeeBps(bps);
+        uint16 old = _redeemFeeBps;
+        _redeemFeeBps = bps;
+        emit RedeemFeeBpsSet(old, bps);
+    }
+
+    /**
+     * @notice Set the fee-share recipient
+     * @dev Accrues pending fees to the OLD recipient first. Zero address is permitted and
+     *      disables future fee-share minting (accrueFees still advances HWM and timestamps,
+     *      but the mint step is skipped).
+     * @param recipient New fee-share recipient (may be the zero address)
+     * @custom:access ACM-gated role "setFeeRecipient(address)" (VIP)
+     * @custom:event Emits FeeRecipientSet on successful update
+     * @custom:event Emits FeesAccrued / HighWaterMarkUpdated as side effects of pre-set accrual
+     * @custom:error Throws HubPaused if the Hub is paused
+     */
+    function setFeeRecipient(address recipient) external override whenNotHubPaused {
+        _checkAccessAllowed("setFeeRecipient(address)");
+        _accrueFees();
+        address old = _feeRecipient;
+        _feeRecipient = recipient;
+        emit FeeRecipientSet(old, recipient);
+    }
+
+    /**
+     * @notice Public poke that brings management + performance fee state up to date
+     * @custom:event Emits FeesAccrued and HighWaterMarkUpdated when state advances
+     * @custom:error Throws HubPaused if the Hub is paused
+     */
+    function accrueFees() external override nonReentrant whenNotHubPaused {
+        _accrueFees();
+    }
+
+    // -- Sweep --
+
+    /**
+     * @notice Forward the Hub's full balance of an arbitrary ERC-20 to `to`
+     * @param token ERC-20 to sweep (must not be `asset()`)
+     * @param to Recipient of the balance
+     * @custom:access ACM-gated role "sweep(address,address)" (VIP)
+     * @custom:event Emits Swept when a non-zero balance is transferred
+     * @custom:error Throws SweepProtectedAsset if token == asset()
+     * @custom:error Throws ZeroAddress if to is the zero address
+     */
+    function sweep(address token, address to) external override nonReentrant {
+        _checkAccessAllowed("sweep(address,address)");
+        if (token == asset()) revert SweepProtectedAsset();
+        if (to == address(0)) revert ZeroAddress();
+
+        uint256 bal = IERC20Upgradeable(token).balanceOf(address(this));
+        if (bal > 0) {
+            IERC20Upgradeable(token).safeTransfer(to, bal);
+            emit Swept(token, to, bal);
+        }
+    }
+
+    // ============================== External — view ==========================
+
+    /**
+     * @notice Hub-level pause state
+     * @return True if `pauseHub()` is in effect
+     */
+    function hubPaused() external view override returns (bool) {
+        return _hubPaused;
+    }
+
+    /**
+     * @notice Per-transaction withdraw cap in asset units
+     * @return Current cap value
+     */
+    function maxWithdrawalSize() external view override returns (uint256) {
+        return _maxWithdrawalSize;
+    }
+
+    /**
+     * @notice Recipient of newly-minted fee shares
+     * @dev Zero address means fee-share minting is disabled (HWM and timestamps still advance).
+     * @return Current fee recipient
+     */
+    function feeRecipient() external view override returns (address) {
+        return _feeRecipient;
+    }
+
+    /**
+     * @notice Current fee rates in BPS
+     * @return managementBps Management fee rate
+     * @return performanceBps Performance fee rate
+     */
+    function feeBps() external view override returns (uint16 managementBps, uint16 performanceBps) {
+        return (_managementFeeBps, _performanceFeeBps);
+    }
+
+    /// @inheritdoc IHub
+    function redeemFeeBps() external view override returns (uint16) {
+        return _redeemFeeBps;
+    }
+
+    /**
+     * @notice Performance high-water mark in share-price units (`totalAssets × 1e18 / totalSupply`)
+     * @dev Seeded at `initialize()` to `EXP_SCALE / 10^decimalsOffset` so the performance-fee branch is
+     *      reachable from launch. Non-decreasing while the vault holds shares; moves on three paths:
+     *      ratcheted to PPS on new highs in `_accrueFees`, incremented by the retained exit-fee uplift in
+     *      `_withdraw`, and re-anchored to the entry PPS on a refill from empty in `_deposit`. The refill
+     *      path is the only one that can lower it, so a fresh cohort is measured against its own entry; the
+     *      anchor is bounded above by the virtual-share-inclusive supply and below by the seed, so dust
+     *      cannot manipulate it. During a drawdown the mark can sit above the current PPS.
+     * @return Current HWM value
+     */
+    function highWaterMarkPerShare() external view override returns (uint256) {
+        return _highWaterMarkPerShare;
+    }
+
+    /**
+     * @notice Registered YieldGroups, in insertion order (swap-and-pop on remove)
+     * @return Storage copy of the registry array
+     */
+    function registeredYieldGroups() external view override returns (address[] memory) {
+        return _registeredYieldGroups;
+    }
+
+    /**
+     * @notice Current deposit routing order
+     * @return Storage copy of the deposit queue
+     */
+    function outerDepositQueue() external view override returns (address[] memory) {
+        return _outerDepositQueue;
+    }
+
+    /**
+     * @notice Current withdraw routing order
+     * @return Storage copy of the withdraw queue
+     */
+    function outerWithdrawQueue() external view override returns (address[] memory) {
+        return _outerWithdrawQueue;
+    }
+
+    /**
+     * @notice Full config struct for a YieldGroup
+     * @param yieldGroup Address to look up
+     * @return Stored config
+     */
+    function yieldGroupConfig(address yieldGroup) external view override returns (IHub.YieldGroupConfig memory) {
+        return _yieldGroups[yieldGroup];
+    }
+
+    /**
+     * @notice Live effective cap for a YieldGroup
+     * @dev Returns 0 for unregistered YieldGroups. For registered YieldGroups, returns
+     *      `min(absoluteCap, percentageCapBps × totalAssets() / 10_000)`, with the special case
+     *      `percentageCapBps == 10_000` treated as "percentage cap disabled" (effective cap =
+     *      absoluteCap). Paused YieldGroups still report their cap — the pause flag is checked at
+     *      the routing call site.
+     * @param yieldGroup Address to look up
+     * @return Effective cap in asset units
+     */
+    function yieldGroupEffectiveCap(address yieldGroup) external view override returns (uint256) {
+        IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+        if (!cfg.registered) return 0;
+        return _effectiveCap(cfg, totalAssets());
+    }
+
+    // ============================== Public — mutating (ERC-4626) =============
+    // Each entry wraps super.* with reentrancy guard + pause guard, then accrues fees BEFORE
+    // the share-price math inside super.* so the caller trades against the post-accrual price.
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws HubCapacityExceeded if aggregate spare cap across unpaused YieldGroups is insufficient
+     */
+    function deposit(uint256 assets, address receiver)
+        public
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        nonReentrant
+        whenNotHubPaused
+        returns (uint256)
+    {
+        _accrueFees();
+        return super.deposit(assets, receiver);
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws HubCapacityExceeded if aggregate spare cap is insufficient for the shares requested
+     */
+    function mint(uint256 shares, address receiver)
+        public
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        nonReentrant
+        whenNotHubPaused
+        returns (uint256)
+    {
+        _accrueFees();
+        return super.mint(shares, receiver);
+    }
+
+    /**
+     * @inheritdoc IHub
+     * @dev The consent hash is optional: passing `bytes32(0)` skips the emit and behaves like a plain
+     *      {deposit}, so the frontend can use a single entry point whether or not a disclaimer applies.
+     *      A non-zero hash emits {ConsentRecorded} first, then delegates to {deposit}, so the event is
+     *      rolled back with the transaction if {deposit} reverts; all cap / pause / accrual gating
+     *      lives in {deposit}. Event-only — no new storage, ERC-4626 path untouched.
+     */
+    function depositWithConsent(uint256 assets, address receiver, bytes32 consentHash)
+        external
+        override
+        returns (uint256 shares)
+    {
+        if (consentHash != bytes32(0)) emit ConsentRecorded(_msgSender(), receiver, consentHash);
+        shares = deposit(assets, receiver);
+    }
+
+    /**
+     * @inheritdoc IHub
+     * @dev The consent hash is optional: passing `bytes32(0)` skips the emit and behaves like a plain
+     *      {mint}, so the frontend can use a single entry point whether or not a disclaimer applies. A
+     *      non-zero hash emits {ConsentRecorded} first, then delegates to {mint}, so the event is
+     *      rolled back with the transaction if {mint} reverts; all cap / pause / accrual gating lives
+     *      in {mint}. Event-only — no new storage, ERC-4626 path untouched.
+     */
+    function mintWithConsent(uint256 shares, address receiver, bytes32 consentHash)
+        external
+        override
+        returns (uint256 assets)
+    {
+        if (consentHash != bytes32(0)) emit ConsentRecorded(_msgSender(), receiver, consentHash);
+        assets = mint(shares, receiver);
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws HubWithdrawCapExceeded if assets > maxWithdrawalSize
+     * @custom:error Throws HubInsufficientLiquidity if aggregate liquid funds (withdraw queue plus Hub idle) are insufficient
+     * @custom:error Throws YieldGroupUnderfilled if any YieldGroup returns fewer assets than the leg requested
+     */
+    function withdraw(uint256 assets, address receiver, address owner)
+        public
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        nonReentrant
+        whenNotHubPaused
+        returns (uint256)
+    {
+        _accrueFees();
+        return super.withdraw(assets, receiver, owner);
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws HubWithdrawCapExceeded if the converted assets exceed maxWithdrawalSize
+     * @custom:error Throws HubInsufficientLiquidity if aggregate liquid funds are insufficient
+     * @custom:error Throws YieldGroupUnderfilled if any YieldGroup returns fewer assets than the leg requested
+     */
+    function redeem(uint256 shares, address receiver, address owner)
+        public
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        nonReentrant
+        whenNotHubPaused
+        returns (uint256)
+    {
+        _accrueFees();
+        return super.redeem(shares, receiver, owner);
+    }
+
+    // ============================== Public — view (ERC-4626) =================
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @dev NAV = `Σ YieldGroup.totalAssets()` plus the Hub's idle `asset()` balance.
+     *
+     *      Idle is normally zero — deposits route out atomically, withdrawals pull exact amounts,
+     *      and reallocate is balanced — so the only balance that lingers here is a direct `asset()`
+     *      donation. It is folded into NAV (the underlying cannot be swept) so it accrues to LPs and
+     *      is consumed first on withdraw.
+     *
+     *      Fails closed. A YieldGroup whose `totalAssets()` reverts is NOT isolated here — unlike the
+     *      quantity-gate views (`maxDeposit` / `maxWithdraw`) and the deposit / withdraw routing,
+     *      which deliberately skip a faulting YieldGroup. The difference is the safety class: NAV is the
+     *      share-price denominator that every mint and redeem converts against, so silently counting
+     *      a YieldGroup as 0 would understate the price — under-paying redeemers and over-crediting
+     *      depositors until its value reappeared. Failing to 0 is safe for a quantity gate (it only
+     *      marks that YieldGroup temporarily unavailable); on the price it is a value leak, so halting is
+     *      the correct bias.
+     *
+     *      A reverting `totalAssets()` is fail-closed by design. It can be a YieldGroup-level bug, but it
+     *      can also originate outside the protocol — e.g. a Fluid fToken's valuation reverts when its
+     *      Liquidity-layer exchange price reads zero, on an unexpected exchange-price decrease, or if its
+     *      rewards-rate model reverts. We deliberately do NOT mask this with a fallback or cached /
+     *      governance-overridden NAV. For the resources where a valuation revert is reachable (Fluid today),
+     *      the same exchange-price recompute backs both `totalAssets()` and `withdraw`, so a condition that
+     *      breaks pricing also breaks exit: a substituted NAV could let redeemers exit against a position the
+     *      Hub cannot liquidate (a value leak) while the remaining LPs absorb the loss. Where a resource
+     *      instead has a known-correct fallback value, that is handled in its adapter (e.g. `AdapterFRV`
+     *      values a Closed vault at 0), never here. A genuinely bricked YieldGroup is evicted via the
+     *      emergency path of `removeYieldGroup` and brought back once healthy — see the recovery runbook in
+     *      the README.
+     */
+    function totalAssets() public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256 total) {
+        address[] storage yieldGroups = _registeredYieldGroups;
+        uint256 len = yieldGroups.length;
+        for (uint256 i; i < len; ++i) {
+            total += IYieldGroupBase(yieldGroups[i]).totalAssets();
+        }
+        total += IERC20Upgradeable(asset()).balanceOf(address(this));
+    }
+
+    /// @inheritdoc IERC4626Upgradeable
+    function maxDeposit(address) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
+        if (_hubPaused) return 0;
+        return _aggregateDepositCapacity(totalAssets());
+    }
+
+    /// @inheritdoc IERC4626Upgradeable
+    function maxMint(address receiver) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
+        return convertToShares(maxDeposit(receiver));
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @dev Returns 0 while paused. Otherwise clamped to the minimum of three constraints:
+     *      (1) the owner's share-equivalent assets, (2) aggregate liquid funds across the
+     *      withdraw queue plus Hub idle, and (3) the per-transaction cap `maxWithdrawalSize()`. The
+     *      clamping makes ERC-4626's invariant `withdraw(maxWithdraw(owner), ...)` succeed only when
+     *      the value is read and consumed against the same state. `withdraw`/`redeem` run
+     *      `_accrueFees()` first, which mints fee shares and lowers PPS, and this figure is
+     *      asset-denominated, so a value read before the block's first accrual can exceed the
+     *      post-accrual ceiling and revert by a fee-proportional margin. For a full exit prefer
+     *      `redeem(maxRedeem(owner))`, whose ceiling is share-denominated off the fee-invariant
+     *      `balanceOf(owner)` and does not shrink on accrual.
+     */
+    function maxWithdraw(address owner)
+        public
+        view
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        returns (uint256)
+    {
+        if (_hubPaused) return 0;
+        // Net of the exit fee. At fee 0 this is `convertToAssets(balanceOf)` (unchanged); with a fee
+        // the fee is rounded UP so the net entitlement is conservative — `previewWithdraw` grosses
+        // up the other way (ceil), so this guarantees `withdraw(maxWithdraw(owner))` never tries to
+        // burn more shares than the owner holds.
+        uint256 gross = convertToAssets(balanceOf(owner));
+        uint16 redeemBps = _redeemFeeBps;
+        uint256 fromShares =
+            redeemBps == 0 ? gross : gross - (gross * redeemBps + BPS_DENOMINATOR - 1) / BPS_DENOMINATOR;
+        uint256 liquid = _aggregateLiquid();
+        uint256 perTxCap = _maxWithdrawalSize;
+        uint256 limit = fromShares < liquid ? fromShares : liquid;
+        return limit < perTxCap ? limit : perTxCap;
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @dev Share-denominated off the fee-invariant `balanceOf(owner)`, so unlike {maxWithdraw} it
+     *      does not shrink when `_accrueFees()` mints fee shares. A stale read can still bind on a
+     *      liquidity/cap change or floor-rounding, never on fee accrual, so `redeem(maxRedeem(owner))`
+     *      is the safe full-exit call.
+     */
+    function maxRedeem(address owner) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
+        if (_hubPaused) return 0;
+        uint256 ownerShares = balanceOf(owner);
+        // Net assets `redeem` would pay out for the full balance (exit fee floored, as `redeem` does).
+        uint256 ownerNet = previewRedeem(ownerShares);
+        if (ownerNet == 0) return 0;
+        // Outflow bound, in raw net-asset terms: liquidity and the per-tx cap. The retained fee stays
+        // in the vault, so only the net `assets` routed by `_withdraw` is constrained, and it is
+        // compared like-for-like against `ownerNet` (also a floored net). NOT `maxWithdraw`, which
+        // ceils the fee — clamping to it would under-report by dust and revert a full-balance `redeem`.
+        uint256 netLimit = _aggregateLiquid();
+        uint256 perTxCap = _maxWithdrawalSize;
+        if (perTxCap < netLimit) netLimit = perTxCap;
+        // Full balance fits the bound: redeem everything.
+        // solhint-disable-next-line gas-strict-inequalities
+        if (ownerNet <= netLimit) return ownerShares;
+        // Bound-limited: gross `netLimit` back up to shares. Floor both steps (fee gross-up, then
+        // asset-to-share) so the result's payout nets to <= `netLimit`, matching `redeem`'s floored
+        // fee. At `redeemBps == 0` the gross-up is a no-op, so this single path also covers the fee-off
+        // case. No iterative share-by-share correction: with a large `decimalsOffset` a share is worth
+        // < 1 asset unit, so it could run up to ~10^offset times.
+        uint16 bps = _redeemFeeBps;
+        uint256 maxGrossAssets = bps > 0 ? (netLimit * BPS_DENOMINATOR) / (BPS_DENOMINATOR - bps) : netLimit;
+        uint256 cappedShares = convertToShares(maxGrossAssets);
+        return cappedShares < ownerShares ? cappedShares : ownerShares;
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @dev Net of the exit fee: the redeemer receives `convertToAssets(shares)` minus the retained
+     *      fee. Returns the gross value when the fee is 0.
+     */
+    function previewRedeem(uint256 shares)
+        public
+        view
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        returns (uint256)
+    {
+        uint256 assets = super.previewRedeem(shares);
+        uint16 bps = _redeemFeeBps;
+        if (bps == 0) return assets;
+        // Fee carved out of the gross (floor, favouring the vault); the remainder is delivered.
+        return assets - (assets * bps) / BPS_DENOMINATOR;
+    }
+
+    /**
+     * @inheritdoc IERC4626Upgradeable
+     * @dev To RECEIVE `assets` net of the exit fee, the owner must burn shares covering the grossed-up
+     *      amount `assets + fee`. The retained fee never leaves the vault (only `assets` is routed
+     *      out), socialising it to remaining LPs. Returns the unmodified shares when the fee is 0.
+     */
+    function previewWithdraw(uint256 assets)
+        public
+        view
+        override(ERC4626Upgradeable, IERC4626Upgradeable)
+        returns (uint256)
+    {
+        uint16 bps = _redeemFeeBps;
+        if (bps != 0) {
+            uint256 denom = BPS_DENOMINATOR - bps;
+            // Gross up with a ceil division so the burned shares always cover the net + fee.
+            assets += (assets * bps + denom - 1) / denom;
+        }
+        return super.previewWithdraw(assets);
+    }
+
+    // ============================== Internal — mutating ======================
+
+    /// @inheritdoc ERC4626Upgradeable
+    function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal override {
+        // Snapshot the pre-mint supply so a refill from an empty vault can be detected below.
+        uint256 preTs = totalSupply();
+
+        IERC20Upgradeable(asset()).safeTransferFrom(caller, address(this), assets);
+        _routeDeposit(assets);
+        _mint(receiver, shares);
+
+        // On a refill from empty, re-anchor the mark to this cohort's entry PPS (up or down). While
+        // totalSupply is 0 nothing else maintains it: `_withdraw`'s exit-fee credit needs a non-zero
+        // post-burn supply and `_accrueFees`'s zero-supply branch only advances the clock. Anchoring here
+        // keeps a residual left at supply 0 from reading as a gain on the next depositor, and keeps a prior
+        // cycle's high from shielding the new cohort. Two bounds keep the anchor dust-resistant: pricing it
+        // off the virtual-share-inclusive supply (`ts + 10^offset`) holds it at or below the real entry PPS,
+        // and the launch seed floors it (a dust deposit mints 10^offset shares against ~0 assets, which would
+        // otherwise drag a raw anchor toward 0). A clean first deposit anchors at the seed, so it is a no-op.
+        if (preTs == 0) {
+            uint256 ts = totalSupply();
+            if (ts != 0) {
+                uint256 entryPps = (totalAssets() * EXP_SCALE) / (ts + 10 ** uint256(_decimalsOffset()));
+                uint256 seedPps = EXP_SCALE / (10 ** uint256(_decimalsOffset()));
+                if (entryPps < seedPps) entryPps = seedPps;
+                uint256 hwm = _highWaterMarkPerShare;
+                if (entryPps != hwm) {
+                    _highWaterMarkPerShare = entryPps;
+                    emit HighWaterMarkUpdated(hwm, entryPps);
+                }
+            }
+        }
+
+        emit Deposit(caller, receiver, assets, shares);
+    }
+
+    /// @inheritdoc ERC4626Upgradeable
+    function _withdraw(address caller, address receiver, address owner, uint256 assets, uint256 shares)
+        internal
+        override
+    {
+        if (assets > _maxWithdrawalSize) revert HubWithdrawCapExceeded(assets, _maxWithdrawalSize);
+
+        // A retained exit fee burns more share-value than the assets routed out, lifting PPS. That
+        // uplift is socialised to remaining LPs by design and must be shielded from the performance
+        // fee — otherwise the next `_accrueFees` would read it as a performance gain and mint a
+        // slice of the retained exit fee to the fee recipient, contradicting its "retained for LPs"
+        // purpose. Snapshot the pre-exit PPS so the uplift can be measured as a delta below.
+        uint16 redeemBps = _redeemFeeBps;
+        uint256 prePps;
+        if (redeemBps != 0) {
+            uint256 preTs = totalSupply();
+            if (preTs != 0) {
+                prePps = (totalAssets() * EXP_SCALE) / preTs;
+            }
+        }
+
+        if (caller != owner) {
+            _spendAllowance(owner, caller, shares);
+        }
+        _burn(owner, shares);
+        _routeWithdraw(assets);
+        IERC20Upgradeable(asset()).safeTransfer(receiver, assets);
+
+        // Credit the uplift into the HWM as an increment (`hwm + delta`), NOT an absolute ratchet
+        // to the post-exit PPS: during a drawdown the post-exit PPS is still below the prior mark,
+        // so a `newPps > hwm` ratchet would skip and the uplift would sit below the stale mark,
+        // getting taxed as performance on the next recovery past it. The delta form shields the
+        // retained fee whether PPS sits above or below the mark, and stays monotonic (delta >= 0:
+        // the fee-on burn always destroys at least as much share-value as the assets routed out).
+        // Genuine gains stay taxable: the increment moves the mark by exactly what the fee moved
+        // PPS, preserving the (hwm - pps) gap, so any yield PPS earned on top of the uplift —
+        // including yield landed intra-block after the caller's accrual — is still charged at the
+        // next accrual. No-op when the exit fee is 0 (a proportional burn leaves PPS unchanged).
+        if (redeemBps != 0) {
+            uint256 ts = totalSupply();
+            if (ts != 0) {
+                uint256 newPps = (totalAssets() * EXP_SCALE) / ts;
+                if (newPps > prePps) {
+                    uint256 hwm = _highWaterMarkPerShare;
+                    uint256 newHwm = hwm + (newPps - prePps);
+                    _highWaterMarkPerShare = newHwm;
+                    emit HighWaterMarkUpdated(hwm, newHwm);
+                }
+            }
+        }
+
+        emit Withdraw(caller, receiver, owner, assets, shares);
+    }
+
+    /**
+     * @notice Cascade `assets` through the deposit queue. Reverts if total capacity is insufficient.
+     * @param assets Asset units to place.
+     */
+    function _routeDeposit(uint256 assets) internal {
+        // `totalAssets()` already includes the just-transferred-in `assets` (still idle on the
+        // Hub), so it equals the post-deposit system TVL and stays constant across the loop as
+        // funds move from idle to YieldGroups.
+        uint256 taSnapshot = totalAssets();
+        uint256 remaining = assets;
+        address[] storage queue = _outerDepositQueue;
+        uint256 len = queue.length;
+
+        for (uint256 i; i < len && remaining > 0; ++i) {
+            remaining -= _tryDepositOneYieldGroup(queue[i], remaining, taSnapshot);
+        }
+
+        if (remaining > 0) revert HubCapacityExceeded(assets, assets - remaining);
+    }
+
+    /**
+     * @notice Cascade-pull `assets` through the withdraw queue. Reverts on insufficient liquidity.
+     * @param assets Asset units to pull.
+     */
+    function _routeWithdraw(uint256 assets) internal {
+        uint256 remaining = assets;
+
+        // Consume any idle Hub balance first: it is already in custody, counts toward
+        // liquidity, and is delivered by the caller's final transfer — so it is never pulled
+        // from a YieldGroup. (Idle is normally zero; a direct asset() donation is the only thing
+        // that persists here, since the underlying cannot be swept.)
+        uint256 idle = IERC20Upgradeable(asset()).balanceOf(address(this));
+        if (idle >= remaining) return;
+        unchecked {
+            remaining -= idle;
+        }
+
+        address[] storage queue = _outerWithdrawQueue;
+        uint256 len = queue.length;
+
+        for (uint256 i; i < len && remaining > 0; ++i) {
+            remaining -= _tryWithdrawOneYieldGroup(queue[i], remaining);
+        }
+
+        if (remaining > 0) revert HubInsufficientLiquidity(assets, assets - remaining);
+    }
+
+    /**
+     * @notice Apply pending management + performance fees by minting shares to the recipient.
+     * @dev Idempotent within a block. Fees are skipped when supply is 0, the recipient is
+     *      unset, or the relevant rate is 0 — but the HWM is updated independently of those
+     *      conditions whenever PPS climbs, so a later perf-rate change cannot retroactively
+     *      claim prior gains. HWM tracks the PPS *before* fee dilution, matching the standard
+     *      Yearn / Morpho convention.
+     */
+    function _accrueFees() internal {
+        // Idempotence keys off `block.number`, not the timestamp: resource NAV is block-lazy (a Core
+        // vToken only accrues when `block.number` advances), and consecutive blocks can share a
+        // timestamp on sub-second chains. A timestamp guard would then skip the refresh on a fresh
+        // block and price shares on a stale exchange rate. The block guard refreshes every new block.
+        uint64 nowBlock = uint64(block.number);
+        if (nowBlock == _lastFeeAccrualBlock) return;
+        _lastFeeAccrualBlock = nowBlock;
+
+        uint64 nowTs = uint64(block.timestamp);
+        uint64 last = _lastFeeAccrualTimestamp;
+
+        // Settle resource interest before reading NAV so the fee is charged on interest-current
+        // value, not a one cycle stale one. The block guard above bounds this to once per block.
+        _accrueResources();
+
+        uint256 ts = totalSupply();
+        if (ts == 0) {
+            _lastFeeAccrualTimestamp = nowTs;
+            return;
+        }
+
+        uint256 ta = totalAssets();
+        uint256 currentPps = (ta * EXP_SCALE) / ts;
+        uint256 hwm = _highWaterMarkPerShare;
+        address recipient = _feeRecipient;
+
+        // `chargedUntil` is normally `nowTs`. If the elapsed-window fee would exceed 100% of TA,
+        // the clamp caps it at TA and advances the cursor only over the window producing 100%, so
+        // the excess defers to the next call; that accrual is then skipped by the `totalFee < ta`
+        // guard below. No fees are charged when the recipient is unset.
+        uint256 mgmtAssetFee;
+        uint256 perfAssetFee;
+        uint64 chargedUntil = nowTs;
+        if (recipient != address(0)) {
+            (mgmtAssetFee, chargedUntil) = _pendingManagementFee(ta, last, nowTs);
+            perfAssetFee = _pendingPerformanceFee(ts, currentPps, hwm);
+        }
+
+        uint256 totalFee = mgmtAssetFee + perfAssetFee;
+        if (totalFee > 0 && totalFee < ta) {
+            uint256 totalShares = (totalFee * ts) / (ta - totalFee);
+            if (totalShares > 0) {
+                // mgmt/perf split is floor-rounded: in the dust regime one component can round
+                // to 0 and the other absorbs the remainder. The total mint is exact; only the
+                // off-chain mgmt-vs-perf attribution is approximate.
+                uint256 mgmtShares = (totalShares * mgmtAssetFee) / totalFee;
+                uint256 perfShares = totalShares - mgmtShares;
+                _mint(recipient, totalShares);
+                emit FeesAccrued(mgmtShares, perfShares, totalShares);
+            }
+        }
+
+        if (currentPps > hwm) {
+            _highWaterMarkPerShare = currentPps;
+            emit HighWaterMarkUpdated(hwm, currentPps);
+        }
+
+        _lastFeeAccrualTimestamp = chargedUntil;
+    }
+
+    /**
+     * @notice Poke every registered YieldGroup to settle its resources' accrued interest up to the
+     *         current block, so the subsequent {totalAssets} read is interest-current.
+     * @dev Each YieldGroup's `accrue` is best-effort (it swallows a resource that cannot accrue) and
+     *      is a no-op for families whose NAV is not a block-lazy exchange rate (Flux, FRV), so this
+     *      loop never reverts on a market condition. Calls only governance-registered YieldGroups
+     *      and resources, so it opens no untrusted reentrancy surface.
+     */
+    function _accrueResources() internal {
+        address[] storage yieldGroups = _registeredYieldGroups;
+        uint256 len = yieldGroups.length;
+        for (uint256 i; i < len; ++i) {
+            IYieldGroupBase(yieldGroups[i]).accrue();
+        }
+    }
+
+    // ============================== Internal — view ==========================
+
+    /// @inheritdoc ERC4626Upgradeable
+    function _decimalsOffset() internal view override returns (uint8) {
+        return _decimalsOffsetStored;
+    }
+
+    /**
+     * @notice Compute the effective cap for a YieldGroup given a TVL reference.
+     * @dev When `percentageCapBps == BPS_DENOMINATOR` (100%), the percentage cap is treated
+     *      as disabled and only the absolute cap binds. Without this carve-out, every Hub
+     *      with any percentage-cap value is permanently un-bootstrappable: at TA = 0 the
+     *      percentage component collapses to 0, `maxDeposit()` returns 0, and OZ's
+     *      ERC-4626 wrapper rejects the very first deposit. The carve-out matches the
+     *      MetaMorpho convention and preserves dual-cap semantics for `pctBps < 10_000`.
+     * @dev Cap basis: every cap check (deposit cascade, {maxDeposit}, and {reallocate}) compares this
+     *      ceiling against the YieldGroup's *current marked* `totalAssets()`, not the principal
+     *      deposited into it. Because a group's `totalAssets()` accrues over time, its cap headroom
+     *      shrinks even with no new deposit — most visibly for FRV, whose Hub-facing mark accrues the
+     *      forward coupon over the lock (see `AdapterFRV`) yet is non-withdrawable until the vault is
+     *      terminal. A large FRV position can thus reach or pass its group's cap on accrual alone,
+     *      blocking further deposits / reallocation into that group (even into a different resource
+     *      under it). Fail-closed: accrual only tightens capacity, never over-exposes. Size caps with
+     *      headroom for the coupon expected over the lock.
+     * @param cfg YieldGroup config to evaluate.
+     * @param ta TVL reference used for the percentage-cap component.
+     * @return cap `pctBps == 10_000` ? `absoluteCap` : `min(absoluteCap, pctBps × ta / 10_000)`.
+     */
+    function _effectiveCap(IHub.YieldGroupConfig storage cfg, uint256 ta) internal view returns (uint256 cap) {
+        if (cfg.percentageCapBps == BPS_DENOMINATOR) return cfg.absoluteCap;
+        uint256 pctCap = (ta * cfg.percentageCapBps) / BPS_DENOMINATOR;
+        cap = pctCap < cfg.absoluteCap ? pctCap : cfg.absoluteCap;
+    }
+
+    /**
+     * @notice Sum spare deposit capacity across the unpaused deposit-queue YieldGroups.
+     * @param taSnapshot TVL reference used for percentage-cap math on each YieldGroup.
+     * @return total Aggregate asset units that could be deposited right now.
+     */
+    function _aggregateDepositCapacity(uint256 taSnapshot) internal view returns (uint256 total) {
+        address[] storage queue = _outerDepositQueue;
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            address yieldGroup = queue[i];
+            IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+            if (cfg.registered && !cfg.paused) {
+                // Isolate a misbehaving YieldGroup: a revert in either capacity view contributes 0
+                // spare cap instead of bricking every deposit. Mirrors `totalAssets()`.
+                uint256 currentBal;
+                uint256 yieldGroupMax;
+                bool ok = true;
+                try IYieldGroupBase(yieldGroup).totalAssets() returns (uint256 v) {
+                    currentBal = v;
+                } catch {
+                    ok = false;
+                }
+                if (ok) {
+                    try IYieldGroupBase(yieldGroup).maxDeposit() returns (uint256 v) {
+                        yieldGroupMax = v;
+                    } catch {
+                        ok = false;
+                    }
+                }
+                if (ok) {
+                    uint256 cap = _effectiveCap(cfg, taSnapshot);
+                    uint256 capRoom = cap > currentBal ? cap - currentBal : 0;
+                    total += capRoom < yieldGroupMax ? capRoom : yieldGroupMax;
+                }
+            }
+        }
+    }
+
+    /**
+     * @notice Sum liquid funds across the unpaused withdraw-queue YieldGroups, plus Hub idle.
+     * @dev Hub idle is first-class liquidity: `_routeWithdraw` consumes it before touching any
+     *      YieldGroup, so it must be counted here for `maxWithdraw` to stay consistent with what a
+     *      withdrawal can actually deliver.
+     * @return total Aggregate asset units that could be withdrawn right now.
+     */
+    function _aggregateLiquid() internal view returns (uint256 total) {
+        address[] storage queue = _outerWithdrawQueue;
+        uint256 len = queue.length;
+        for (uint256 i; i < len; ++i) {
+            address yieldGroup = queue[i];
+            IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+            if (cfg.registered && !cfg.paused) {
+                // A revert in a YieldGroup's liquidity view contributes 0 instead of bricking every
+                // withdraw. Mirrors `totalAssets()`.
+                uint256 yieldGroupLiquid;
+                try IYieldGroupBase(yieldGroup).maxWithdraw() returns (uint256 v) {
+                    yieldGroupLiquid = v;
+                } catch {
+                    yieldGroupLiquid = 0;
+                }
+                total += yieldGroupLiquid;
+            }
+        }
+        total += IERC20Upgradeable(asset()).balanceOf(address(this));
+    }
+
+    // ============================== Private — mutating =======================
+
+    /**
+     * @notice Shared net-zero reallocation core for {reallocate} and {emergencyReallocate}.
+     * @dev Accrues fees first so the operation trades against current state — except while
+     *      the Hub is paused, when accrual is skipped so the pause window is excluded from fee
+     *      proration ({unpauseHub} later advances the accrual cursor past the frozen window).
+     *      Enforces `Σ withdraws == Σ deposits`.
+     * @param withdraws Withdraw legs to execute first.
+     * @param deposits Deposit legs to execute against the post-pull TVL snapshot.
+     */
+    function _reallocate(IHub.ReallocateLeg[] calldata withdraws, IHub.ReallocateLeg[] calldata deposits) private {
+        if (!_hubPaused) {
+            _accrueFees();
+        }
+
+        uint256 withdrawSum = _reallocatePullAll(withdraws);
+        // System TVL is conserved across a balanced reallocate, so a single TVL snapshot (taken
+        // after pulls; idle now holds the withdrawn funds) is the correct cap reference for every
+        // push leg. Normal reallocate uses the strict, fail-closed `totalAssets()`. The emergency
+        // path (paused) instead uses a fail-open sum: `totalAssets()` reverts if ANY registered
+        // YieldGroup's view reverts, so a single bricked YieldGroup — the very condition `emergencyReallocate`
+        // exists to unwind — would otherwise block a rebalance even among the healthy YieldGroups.
+        // Skipping a reverting YieldGroup only understates the reference, which makes percentage caps
+        // strictly tighter (more conservative), never looser.
+        uint256 taSnapshot = _hubPaused ? _totalAssetsFailOpen() : totalAssets();
+        uint256 depositSum = _reallocatePushAll(deposits, taSnapshot);
+
+        if (withdrawSum != depositSum) revert ReallocateImbalanced(withdrawSum, depositSum);
+    }
+
+    /**
+     * @notice Execute every withdraw leg of a `reallocate()` plan.
+     * @param withdraws Withdraw legs to execute in order.
+     * @return sum Total asset units pulled into the Hub.
+     */
+    function _reallocatePullAll(IHub.ReallocateLeg[] calldata withdraws) private returns (uint256 sum) {
+        IERC20Upgradeable assetToken = IERC20Upgradeable(asset());
+        uint256 len = withdraws.length;
+        for (uint256 i; i < len; ++i) {
+            IHub.ReallocateLeg calldata withdrawLeg = withdraws[i];
+            if (withdrawLeg.amount == 0) revert ZeroAmount();
+            if (!_yieldGroups[withdrawLeg.yieldGroup].registered) {
+                revert YieldGroupNotRegistered(withdrawLeg.yieldGroup);
+            }
+
+            uint256 preBal = assetToken.balanceOf(address(this));
+            if (withdrawLeg.resource == address(0)) {
+                IYieldGroupBase(withdrawLeg.yieldGroup).withdraw(withdrawLeg.amount, address(this));
+            } else {
+                IYieldGroupBase(withdrawLeg.yieldGroup)
+                    .withdrawResource(withdrawLeg.resource, withdrawLeg.amount, address(this));
+            }
+            uint256 delivered = assetToken.balanceOf(address(this)) - preBal;
+            if (delivered != withdrawLeg.amount) {
+                revert YieldGroupUnderfilled(withdrawLeg.yieldGroup, withdrawLeg.amount, delivered);
+            }
+            sum += withdrawLeg.amount;
+            emit WithdrawRouted(withdrawLeg.yieldGroup, withdrawLeg.amount);
+        }
+    }
+
+    /**
+     * @notice Execute every deposit leg of a `reallocate()` plan.
+     * @param deposits Deposit legs to execute in order.
+     * @param taSnapshot `totalAssets()` snapshot used as the cap reference for every leg.
+     * @return sum Total asset units pushed out of the Hub.
+     */
+    function _reallocatePushAll(IHub.ReallocateLeg[] calldata deposits, uint256 taSnapshot)
+        private
+        returns (uint256 sum)
+    {
+        uint256 len = deposits.length;
+        for (uint256 i; i < len; ++i) {
+            sum += _reallocatePushOne(deposits[i], taSnapshot);
+        }
+    }
+
+    /**
+     * @notice Execute a single `reallocate()` deposit leg with cap and pause checks.
+     * @param depositLeg Deposit leg to execute.
+     * @param taSnapshot `totalAssets()` snapshot used as the cap reference.
+     * @return placed Asset units placed into `depositLeg.yieldGroup` (always `depositLeg.amount`;
+     *         underfills revert).
+     */
+    function _reallocatePushOne(IHub.ReallocateLeg calldata depositLeg, uint256 taSnapshot)
+        private
+        returns (uint256 placed)
+    {
+        if (depositLeg.amount == 0) revert ZeroAmount();
+        IHub.YieldGroupConfig storage cfg = _yieldGroups[depositLeg.yieldGroup];
+        if (!cfg.registered) revert YieldGroupNotRegistered(depositLeg.yieldGroup);
+        if (cfg.paused) revert YieldGroupPaused(depositLeg.yieldGroup);
+
+        uint256 cap = _effectiveCap(cfg, taSnapshot);
+        uint256 currentBal = IYieldGroupBase(depositLeg.yieldGroup).totalAssets();
+        if (currentBal + depositLeg.amount > cap) {
+            revert HubCapacityExceeded(depositLeg.amount, cap > currentBal ? cap - currentBal : 0);
+        }
+
+        IERC20Upgradeable(asset()).forceApprove(depositLeg.yieldGroup, depositLeg.amount);
+        uint256 deposited = depositLeg.resource == address(0)
+            ? IYieldGroupBase(depositLeg.yieldGroup).deposit(depositLeg.amount)
+            : IYieldGroupBase(depositLeg.yieldGroup).depositResource(depositLeg.resource, depositLeg.amount);
+        if (deposited != depositLeg.amount) {
+            revert YieldGroupUnderfilled(depositLeg.yieldGroup, depositLeg.amount, deposited);
+        }
+
+        emit DepositRouted(depositLeg.yieldGroup, depositLeg.amount);
+        return depositLeg.amount;
+    }
+
+    /**
+     * @notice Try to deposit up to `remaining` into one YieldGroup. Skips unregistered / paused.
+     * @dev Accepts a partial fill: the YieldGroup places what its inner queue can absorb and
+     *      refunds the rest, so the returned amount may be less than `remaining`. The outer
+     *      cascade routes the unplaced remainder to the next YieldGroup; the final
+     *      {HubCapacityExceeded} backstop fires if no YieldGroup can absorb the full amount.
+     * @param yieldGroup YieldGroup to deposit into.
+     * @param remaining Asset units still needing placement.
+     * @param taSnapshot TVL reference for percentage-cap math.
+     * @return sent Asset units actually placed into `yieldGroup`.
+     */
+    function _tryDepositOneYieldGroup(address yieldGroup, uint256 remaining, uint256 taSnapshot)
+        private
+        returns (uint256 sent)
+    {
+        IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+        if (!cfg.registered || cfg.paused) return 0;
+
+        uint256 toSend = _capRoomForDeposit(yieldGroup, cfg, taSnapshot, remaining);
+        if (toSend == 0) return 0;
+
+        // Route around a YieldGroup whose mutating `deposit` reverts (e.g. its external protocol paused
+        // it after the views certified capacity) instead of bubbling. The approval lives in the
+        // Hub's own frame and is NOT rolled back by the YieldGroup's revert, so reset it on skip. The
+        // `remaining` total is unchanged by a skip, so the unchanged backstop in `_routeDeposit`
+        // still reverts the whole op atomically if no healthy YieldGroup can absorb the full amount.
+        IERC20Upgradeable(asset()).forceApprove(yieldGroup, toSend);
+        try IYieldGroupBase(yieldGroup).deposit(toSend) returns (uint256 deposited) {
+            // `deposited` is the amount the YieldGroup placed; it refunds any remainder. Return it
+            // so the cascade routes what is left onward to the next YieldGroup.
+            if (deposited > 0) emit DepositRouted(yieldGroup, deposited);
+            return deposited;
+        } catch {
+            IERC20Upgradeable(asset()).forceApprove(yieldGroup, 0);
+            emit YieldGroupSkipped(yieldGroup, true);
+            return 0;
+        }
+    }
+
+    /**
+     * @notice Try to withdraw up to `remaining` from one YieldGroup. Skips unregistered / paused.
+     * @dev Reverts {YieldGroupUnderfilled} if the YieldGroup delivers less than asked.
+     * @param yieldGroup YieldGroup to pull from.
+     * @param remaining Asset units still needing collection.
+     * @return pulled Asset units actually pulled from `yieldGroup`.
+     */
+    function _tryWithdrawOneYieldGroup(address yieldGroup, uint256 remaining) private returns (uint256 pulled) {
+        IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
+        if (!cfg.registered || cfg.paused) return 0;
+
+        // A revert in the liquidity view is treated as "no liquidity" and skipped silently, like
+        // the deposit side's `_capRoomForDeposit`.
+        uint256 yieldGroupLiquid;
+        try IYieldGroupBase(yieldGroup).maxWithdraw() returns (uint256 v) {
+            yieldGroupLiquid = v;
+        } catch {
+            return 0;
+        }
+        uint256 toPull = remaining < yieldGroupLiquid ? remaining : yieldGroupLiquid;
+        if (toPull == 0) return 0;
+
+        // Route around a YieldGroup whose mutating `withdraw` reverts (e.g. paused after the view
+        // certified liquidity) instead of bubbling. `remaining` is unchanged by a skip, so the
+        // unchanged backstop in `_routeWithdraw` still reverts the whole op atomically when no
+        // healthy YieldGroup can deliver the full amount.
+        IERC20Upgradeable assetToken = IERC20Upgradeable(asset());
+        uint256 preBal = assetToken.balanceOf(address(this));
+        try IYieldGroupBase(yieldGroup).withdraw(toPull, address(this)) {
+            uint256 delivered = assetToken.balanceOf(address(this)) - preBal;
+            if (delivered != toPull) revert YieldGroupUnderfilled(yieldGroup, toPull, delivered);
+            emit WithdrawRouted(yieldGroup, toPull);
+            return toPull;
+        } catch {
+            emit YieldGroupSkipped(yieldGroup, false);
+            return 0;
+        }
+    }
+
+    /**
+     * @notice Shared body for the per-transaction withdraw-cap setters; `raising` selects the
+     *         direction guard and the emitted event. Behavior matches the former separate setters.
+     * @param newSize New cap in asset units.
+     * @param raising True for the raise path (NotIncreasing guard); false for lower
+     *        (ZeroAmount + NotDecreasing guards).
+     */
+    function _setMaxWithdrawalSize(uint256 newSize, bool raising) private {
+        uint256 old = _maxWithdrawalSize;
+        if (raising) {
+            if (newSize <= old) revert NotIncreasing();
+        } else {
+            if (newSize == 0) revert ZeroAmount();
+            if (newSize >= old) revert NotDecreasing();
+        }
+        _maxWithdrawalSize = newSize;
+        if (raising) {
+            emit MaxWithdrawalSizeRaised(old, newSize);
+        } else {
+            emit MaxWithdrawalSizeLowered(old, newSize);
+        }
+    }
+
+    // ============================== Private — view ===========================
+
+    /**
+     * @notice Fail-open NAV used ONLY as the emergency-reallocate push-cap reference: a YieldGroup whose
+     *         `totalAssets()` reverts contributes 0 instead of bricking the whole call. Understating
+     *         NAV only tightens percentage caps, so it is conservative for a push gate. Never used for
+     *         share pricing, which must stay fail-closed — see {totalAssets}.
+     * @return total Sum of readable YieldGroup balances plus the Hub's idle `asset()` balance.
+     */
+    function _totalAssetsFailOpen() private view returns (uint256 total) {
+        address[] storage yieldGroups = _registeredYieldGroups;
+        uint256 len = yieldGroups.length;
+        for (uint256 i; i < len; ++i) {
+            // solhint-disable-next-line no-empty-blocks
+            try IYieldGroupBase(yieldGroups[i]).totalAssets() returns (uint256 v) {
+                total += v;
+            } catch {
+                // A bricked YieldGroup contributes 0 to the emergency cap reference instead of reverting.
+            }
+        }
+        total += IERC20Upgradeable(asset()).balanceOf(address(this));
+    }
+
+    /**
+     * @notice Compute how much can be deposited into a YieldGroup this step.
+     * @param yieldGroup YieldGroup under inspection.
+     * @param cfg YieldGroup config (storage ref to avoid a second SLOAD-equivalent).
+     * @param taSnapshot TVL reference for percentage-cap math.
+     * @param remaining Asset units the caller still needs to place.
+     * @return room `min(remaining, capRoom, yieldGroup.maxDeposit())`.
+     */
+    function _capRoomForDeposit(
+        address yieldGroup,
+        IHub.YieldGroupConfig storage cfg,
+        uint256 taSnapshot,
+        uint256 remaining
+    ) private view returns (uint256 room) {
+        // A revert in either capacity view of this single YieldGroup yields 0 room, so the deposit
+        // cascade skips it (consistent with the mutating-leg skip below) instead of bubbling.
+        uint256 currentBal;
+        uint256 yieldGroupMax;
+        try IYieldGroupBase(yieldGroup).totalAssets() returns (uint256 v) {
+            currentBal = v;
+        } catch {
+            return 0;
+        }
+        try IYieldGroupBase(yieldGroup).maxDeposit() returns (uint256 v) {
+            yieldGroupMax = v;
+        } catch {
+            return 0;
+        }
+        uint256 cap = _effectiveCap(cfg, taSnapshot);
+        uint256 capRoom = cap > currentBal ? cap - currentBal : 0;
+        uint256 boundedRoom = capRoom < yieldGroupMax ? capRoom : yieldGroupMax;
+        room = remaining < boundedRoom ? remaining : boundedRoom;
+    }
+
+    /**
+     * @notice Management fee (in asset units) pending since `last`, capped per accrual, and the
+     *         timestamp the accrual cursor should advance to.
+     * @dev The fee is linear in elapsed time and capped at `MAX_MGMT_FEE_PER_ACCRUAL_BPS` of
+     *      `ta` per call. When the cap binds, `chargedUntil` is the time the cap covers
+     *      (`last + dtCharged`), so only that window is consumed and any excess defers to the
+     *      next call.
+     * @param ta `totalAssets()` snapshot.
+     * @param last Timestamp of the previous accrual.
+     * @param nowTs Current block timestamp.
+     * @return mgmtAssetFee Management fee in asset units (capped).
+     * @return chargedUntil Timestamp to store as the new accrual cursor.
+     */
+    function _pendingManagementFee(uint256 ta, uint64 last, uint64 nowTs)
+        private
+        view
+        returns (uint256 mgmtAssetFee, uint64 chargedUntil)
+    {
+        chargedUntil = nowTs;
+        uint16 mgmtBps = _managementFeeBps;
+        if (mgmtBps == 0) return (0, chargedUntil);
+
+        uint256 dt = nowTs - last;
+        mgmtAssetFee = (ta * mgmtBps * dt) / (uint256(BPS_DENOMINATOR) * SECONDS_PER_YEAR);
+        uint256 mgmtCap = (ta * MAX_MGMT_FEE_PER_ACCRUAL_BPS) / BPS_DENOMINATOR;
+        if (mgmtAssetFee > mgmtCap) {
+            mgmtAssetFee = mgmtCap;
+            // dt that exactly produces `mgmtCap`: independent of `ta`. The cap only binds when
+            // `dt > dtCharged`, so `last + dtCharged < nowTs` — never advances past now.
+            uint256 dtCharged = (uint256(MAX_MGMT_FEE_PER_ACCRUAL_BPS) * SECONDS_PER_YEAR) / mgmtBps;
+            // Safe cast: dtCharged <= MAX_MGMT_FEE_PER_ACCRUAL_BPS * SECONDS_PER_YEAR (~3.2e11) << 2^64.
+            // forge-lint: disable-next-line(unsafe-typecast)
+            chargedUntil = last + uint64(dtCharged);
+        }
+    }
+
+    /**
+     * @notice Performance fee (in asset units) on gains above the high-water mark.
+     * @param ts `totalSupply()` snapshot.
+     * @param currentPps Current per-share price (`ta * EXP_SCALE / ts`).
+     * @param hwm Current high-water mark.
+     * @return perfAssetFee Performance fee in asset units (0 when not above the HWM).
+     */
+    function _pendingPerformanceFee(uint256 ts, uint256 currentPps, uint256 hwm)
+        private
+        view
+        returns (uint256 perfAssetFee)
+    {
+        uint16 perfBps = _performanceFeeBps;
+        if (perfBps == 0 || currentPps <= hwm) return 0;
+        uint256 profitAssets = ((currentPps - hwm) * ts) / EXP_SCALE;
+        perfAssetFee = (profitAssets * perfBps) / BPS_DENOMINATOR;
+    }
+}