@venusprotocol/liquidity-hub 0.0.0

package/contracts/interfaces/IHub.sol

@@ -0,0 +1,551 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC4626Upgradeable } from "@openzeppelin/contracts-upgradeable/interfaces/IERC4626Upgradeable.sol";
+
+/**
+ * @title IHub
+ * @author Venus
+ * @notice External interface for the per-asset Hub vault. Extends ERC-4626 with a YieldGroup
+ *         registry, dual caps, asymmetric pause, Operator reallocation, and fee accrual.
+ * @dev Conventions:
+ *      - Asset amounts are raw underlying units; BPS are out of `10_000`.
+ *      - All mutating user-facing calls are atomic-or-revert. The Hub routes the full amount
+ *        to / from YieldGroups (deposits route out, withdrawals pull exact, reallocate is balanced),
+ *        so idle is normally zero; the only balance that persists is a direct `asset()` donation
+ *        — which, since the underlying cannot be swept, is counted in `totalAssets()` (so it
+ *        accrues to LPs) and consumed first by `withdraw`.
+ *      - Permissions are gated by `AccessControlManagerV8`: each governance-gated function
+ *        calls `_checkAccessAllowed` with its literal function-signature string (e.g.
+ *        `"addYieldGroup(address,uint256,uint16)"`), which is the ACM role for that function.
+ *        Each governance-gated function below names the role string that gates it; the
+ *        Operator-vs-governance split is set by which addresses hold each role, not by a
+ *        hard-coded branch. `deposit` / `mint` / `withdraw` / `redeem` and `accrueFees`
+ *        are permissionless.
+ */
+interface IHub is IERC4626Upgradeable {
+    /**
+     * @notice Per-YieldGroup configuration.
+     * @param absoluteCap Hard cap on the YieldGroup's holdings, in asset units.
+     * @param percentageCapBps Cap as fraction of `totalAssets()` in BPS. The sentinel value
+     *        `10_000` (100%) disables the percentage component — only `absoluteCap` binds.
+     *        For any value `< 10_000`, effective cap = `min(absoluteCap,
+     *        percentageCapBps × totalAssets() / 10_000)`. The `10_000` carve-out exists so
+     *        a freshly-deployed Hub can take its first deposit (otherwise `pct × 0 / 10_000`
+     *        collapses the cap to 0 at TA = 0 and the vault is un-bootstrappable).
+     * @param paused When true, routing skips this YieldGroup; existing balance still counts.
+     * @param registered True iff present in `registeredYieldGroups()`.
+     */
+    struct YieldGroupConfig {
+        uint256 absoluteCap;
+        uint16 percentageCapBps;
+        bool paused;
+        bool registered;
+    }
+
+    /**
+     * @notice One leg of a `reallocate()` plan. The same shape is reused for both the
+     *         withdraw (pull) and the deposit (push) arrays — direction-specific semantics
+     *         are documented on `reallocate()`.
+     * @param yieldGroup YieldGroup to act on. Must be registered. Deposit (push) legs additionally
+     *        require the YieldGroup to be unpaused and to have spare cap.
+     * @param resource Specific resource (market / vault) inside `yieldGroup`. The sentinel
+     *        `address(0)` means "no target": the YieldGroup cascades through its inner queue —
+     *        idle-first on a pull leg, capacity-order on a push leg. A non-zero value moves
+     *        the full `amount` against that one resource and bypasses the queue.
+     * @param amount Asset units to move on this leg.
+     */
+    struct ReallocateLeg {
+        address yieldGroup;
+        address resource;
+        uint256 amount;
+    }
+
+    // --------------------------------- Events --------------------------------
+
+    /// @notice Emitted when a YieldGroup is added to the registry
+    /// @param yieldGroup Newly-registered YieldGroup
+    /// @param absoluteCap Initial absolute cap in asset units
+    /// @param percentageCapBps Initial percentage cap in BPS
+    event YieldGroupAdded(address indexed yieldGroup, uint256 absoluteCap, uint16 percentageCapBps);
+
+    /// @notice Emitted when a YieldGroup is removed from the registry
+    /// @param yieldGroup Removed YieldGroup
+    event YieldGroupRemoved(address indexed yieldGroup);
+
+    /// @notice Emitted when a YieldGroup's caps are raised
+    /// @param yieldGroup YieldGroup whose caps were updated
+    /// @param absoluteCap New absolute cap in asset units
+    /// @param percentageCapBps New percentage cap in BPS
+    event YieldGroupCapRaised(address indexed yieldGroup, uint256 absoluteCap, uint16 percentageCapBps);
+
+    /// @notice Emitted when a YieldGroup's caps are lowered
+    /// @param yieldGroup YieldGroup whose caps were updated
+    /// @param absoluteCap New absolute cap in asset units
+    /// @param percentageCapBps New percentage cap in BPS
+    event YieldGroupCapLowered(address indexed yieldGroup, uint256 absoluteCap, uint16 percentageCapBps);
+
+    /// @notice Emitted when a YieldGroup's pause flag is flipped
+    /// @param yieldGroup YieldGroup whose flag flipped
+    /// @param paused New pause state
+    event YieldGroupPauseToggled(address indexed yieldGroup, bool paused);
+
+    /// @notice Emitted when the deposit routing order is replaced
+    /// @param queue Full replacement queue in deposit-priority order
+    event OuterDepositQueueSet(address[] queue);
+
+    /// @notice Emitted when the withdraw routing order is replaced
+    /// @param queue Full replacement queue in withdraw-priority order
+    event OuterWithdrawQueueSet(address[] queue);
+
+    /// @notice Emitted when the Hub pause flag is flipped
+    /// @param paused New Hub pause state
+    event HubPauseToggled(bool paused);
+
+    /// @notice Emitted when the per-request withdraw cap is raised
+    /// @param oldSize Previous cap in asset units
+    /// @param newSize New cap in asset units
+    event MaxWithdrawalSizeRaised(uint256 oldSize, uint256 newSize);
+
+    /// @notice Emitted when the per-request withdraw cap is lowered
+    /// @param oldSize Previous cap in asset units
+    /// @param newSize New cap in asset units
+    event MaxWithdrawalSizeLowered(uint256 oldSize, uint256 newSize);
+
+    /// @notice Emitted when assets are deposited into a YieldGroup on a deposit / mint / reallocate-push leg
+    /// @param yieldGroup YieldGroup that received the deposit
+    /// @param amount Asset units deposited
+    event DepositRouted(address indexed yieldGroup, uint256 amount);
+
+    /// @notice Emitted when assets are withdrawn from a YieldGroup on a withdraw / redeem / reallocate-pull leg
+    /// @param yieldGroup YieldGroup that was pulled from
+    /// @param amount Asset units withdrawn
+    event WithdrawRouted(address indexed yieldGroup, uint256 amount);
+
+    /// @notice Emitted when a deposit / withdraw cascade leg was skipped because the YieldGroup's mutating
+    ///         call reverted (e.g. its external protocol paused it). The operation routes around the
+    ///         YieldGroup instead of bubbling the revert; a healthy system emits this zero times.
+    /// @param yieldGroup YieldGroup whose leg was skipped
+    /// @param isDeposit True if the skipped leg was a deposit, false for a withdraw
+    event YieldGroupSkipped(address indexed yieldGroup, bool isDeposit);
+
+    /// @notice Emitted when the management fee rate is changed; pending fees accrued at OLD rate first
+    /// @param oldBps Previous rate in BPS
+    /// @param newBps New rate in BPS
+    event ManagementFeeBpsSet(uint16 oldBps, uint16 newBps);
+
+    /// @notice Emitted when the performance fee rate is changed; pending fees accrued at OLD rate first
+    /// @param oldBps Previous rate in BPS
+    /// @param newBps New rate in BPS
+    event PerformanceFeeBpsSet(uint16 oldBps, uint16 newBps);
+
+    /// @notice Emitted when the exit (withdraw/redeem) fee rate is changed
+    /// @param oldBps Previous rate in BPS
+    /// @param newBps New rate in BPS
+    event RedeemFeeBpsSet(uint16 oldBps, uint16 newBps);
+
+    /// @notice Emitted when the fee recipient is changed; pending fees minted to OLD recipient first
+    /// @param oldRecipient Previous recipient
+    /// @param newRecipient New recipient
+    event FeeRecipientSet(address oldRecipient, address newRecipient);
+
+    /// @notice Emitted when fee shares are minted in an accrual
+    /// @param managementShares Shares minted for the management fee
+    /// @param performanceShares Shares minted for the performance fee
+    /// @param totalShares Sum of the two
+    event FeesAccrued(uint256 managementShares, uint256 performanceShares, uint256 totalShares);
+
+    /// @notice Emitted when the performance HWM moves up. Units: `totalAssets × 1e18 / totalSupply`
+    /// @param oldHwm Previous HWM
+    /// @param newHwm New HWM
+    event HighWaterMarkUpdated(uint256 oldHwm, uint256 newHwm);
+
+    /// @notice Emitted when a stray-token balance is rescued via `sweep()`
+    /// @param token ERC-20 that was swept
+    /// @param to Recipient of the balance
+    /// @param amount Amount transferred
+    event Swept(address indexed token, address indexed to, uint256 amount);
+
+    /// @notice Emitted when a supplier records disclaimer consent alongside a deposit / mint
+    /// @param supplier Caller who consented (the depositor / minter)
+    /// @param receiver Address that received the minted shares
+    /// @param consentHash keccak256 hash of the disclaimer content the supplier consented to
+    event ConsentRecorded(address indexed supplier, address indexed receiver, bytes32 indexed consentHash);
+
+    // --------------------------------- Errors --------------------------------
+
+    /// @notice Error thrown when deposit / mint exceeds aggregate spare cap across unpaused YieldGroups
+    /// @param requested Asset units requested
+    /// @param maxAvailable Aggregate spare cap at revert time
+    error HubCapacityExceeded(uint256 requested, uint256 maxAvailable);
+
+    /// @notice Error thrown when withdraw / redeem exceeds aggregate liquid funds (withdraw queue plus Hub idle)
+    /// @param requested Asset units requested
+    /// @param available Aggregate liquid funds at revert time
+    error HubInsufficientLiquidity(uint256 requested, uint256 available);
+
+    /// @notice Error thrown when a YieldGroup returns fewer assets than requested on a deposit or withdraw leg
+    /// @param yieldGroup YieldGroup that under-filled
+    /// @param requested Asset units requested
+    /// @param actual Asset units delivered
+    error YieldGroupUnderfilled(address yieldGroup, uint256 requested, uint256 actual);
+
+    /// @notice Error thrown when withdraw / redeem exceeds the per-transaction cap
+    /// @param requested Asset units requested
+    /// @param perRequestCap Current value of `maxWithdrawalSize()`
+    error HubWithdrawCapExceeded(uint256 requested, uint256 perRequestCap);
+
+    /// @notice Error thrown when a user-facing mutating call is attempted while the Hub is paused
+    error HubPaused();
+
+    /// @notice Error thrown when a deposit or reallocate-deposit leg targets a paused YieldGroup
+    /// @param yieldGroup YieldGroup whose pause flag blocked the routing
+    error YieldGroupPaused(address yieldGroup);
+
+    /// @notice Error thrown when an operation targets a YieldGroup that is not in the registry
+    /// @param yieldGroup Address that failed the registry lookup
+    error YieldGroupNotRegistered(address yieldGroup);
+
+    /// @notice Error thrown when `addYieldGroup()` is called with an already-registered YieldGroup
+    /// @param yieldGroup Address that is already registered
+    error YieldGroupAlreadyRegistered(address yieldGroup);
+
+    /// @notice Error thrown when `removeYieldGroup()` is called while the YieldGroup still holds a non-zero balance
+    /// @param yieldGroup YieldGroup attempted to be removed
+    /// @param balance Current `yieldGroup.totalAssets()` preventing removal
+    error YieldGroupHasBalance(address yieldGroup, uint256 balance);
+
+    /// @notice Error thrown when a YieldGroup's `asset()` does not match the Hub's underlying
+    /// @param yieldGroup YieldGroup under inspection
+    /// @param yieldGroupAsset `asset()` reported by the YieldGroup
+    /// @param hubAsset Hub's own `asset()`
+    error YieldGroupAssetMismatch(address yieldGroup, address yieldGroupAsset, address hubAsset);
+
+    /// @notice Error thrown when a cap pair is invalid (e.g. percentage > 100%)
+    /// @param absoluteCap Offending absolute cap
+    /// @param percentageCapBps Offending percentage cap in BPS
+    error InvalidCap(uint256 absoluteCap, uint16 percentageCapBps);
+
+    /// @notice Error thrown when a queue contains duplicates or references an unregistered YieldGroup
+    error InvalidQueue();
+
+    /// @notice Error thrown when `reallocate()` withdraw and deposit sums do not match
+    /// @param withdrawSum Sum of withdraw-leg `amount` entries
+    /// @param depositSum Sum of deposit-leg `amount` entries
+    error ReallocateImbalanced(uint256 withdrawSum, uint256 depositSum);
+
+    /// @notice Error thrown when a `setOuterWithdrawQueue` replacement would drop a registered
+    ///         YieldGroup that still custodies a balance, stranding its redeemable value. Drain the
+    ///         YieldGroup via reallocate before removing it from the withdraw queue.
+    /// @param yieldGroup Funded YieldGroup missing from the candidate withdraw queue
+    error WithdrawQueueOmitsFundedYieldGroup(address yieldGroup);
+
+    /// @notice Error thrown when `sweep()` is called with `token == asset()`
+    error SweepProtectedAsset();
+
+    /// @notice Error thrown when a required non-zero address parameter was zero
+    error ZeroAddress();
+
+    /// @notice Error thrown when a required non-zero amount parameter was zero
+    error ZeroAmount();
+
+    /// @notice Error thrown when `decimalsOffset_` at `initialize()` exceeded `MAX_DECIMALS_OFFSET`
+    error InvalidDecimalsOffset();
+
+    /// @notice Error thrown when a fee rate exceeded `MAX_FEE_BPS`
+    /// @param bps Offending BPS rate
+    error InvalidFeeBps(uint16 bps);
+
+    /// @notice Error thrown when `raise*` is called with a value not strictly greater than the current one
+    error NotIncreasing();
+
+    /// @notice Error thrown when `lower*` is called with a value not strictly less than the current one
+    error NotDecreasing();
+
+    // ----------------------- YieldGroup registry (governance) --------------------
+
+    /**
+     * @notice Add a YieldGroup to the registry with initial caps
+     * @dev ACM role `"addYieldGroup(address,uint256,uint16)"` (VIP).
+     * @param yieldGroup YieldGroup contract address
+     * @param absoluteCap Initial absolute cap in asset units
+     * @param percentageCapBps Initial percentage cap in BPS
+     */
+    function addYieldGroup(address yieldGroup, uint256 absoluteCap, uint16 percentageCapBps) external;
+
+    /**
+     * @notice Remove a YieldGroup from the registry
+     * @dev ACM role `"removeYieldGroup(address)"` (VIP).
+     * @param yieldGroup YieldGroup to remove
+     */
+    function removeYieldGroup(address yieldGroup) external;
+
+    /**
+     * @notice Raise a YieldGroup's caps
+     * @dev ACM role `"raiseYieldGroupCap(address,uint256,uint16)"` (Guardian or VIP) — raising is loosening.
+     * @param yieldGroup YieldGroup whose caps are being raised
+     * @param absoluteCap New absolute cap in asset units
+     * @param percentageCapBps New percentage cap in BPS
+     */
+    function raiseYieldGroupCap(address yieldGroup, uint256 absoluteCap, uint16 percentageCapBps) external;
+
+    /**
+     * @notice Lower a YieldGroup's caps
+     * @dev ACM role `"lowerYieldGroupCap(address,uint256,uint16)"` (Operator or VIP) — tightening.
+     * @param yieldGroup YieldGroup whose caps are being lowered
+     * @param absoluteCap New absolute cap in asset units
+     * @param percentageCapBps New percentage cap in BPS
+     */
+    function lowerYieldGroupCap(address yieldGroup, uint256 absoluteCap, uint16 percentageCapBps) external;
+
+    // ----------------------- Outer queues (Operator) -------------------------
+
+    /**
+     * @notice Replace the deposit routing order
+     * @dev ACM role `"setOuterDepositQueue(address[])"` (Operator). Operator responsibility: keep
+     *      every queue member in the outer withdraw queue. A member absent from the withdraw queue is
+     *      funded by deposits but not reachable by the normal redeem path until it is (re)added there;
+     *      recovery is one tx and lossless. Not enforced on-chain.
+     * @param queue Full replacement queue in deposit-priority order
+     */
+    function setOuterDepositQueue(address[] calldata queue) external;
+
+    /**
+     * @notice Replace the withdraw routing order
+     * @dev ACM role `"setOuterWithdrawQueue(address[])"` (Operator). Reverts
+     *      {WithdrawQueueOmitsFundedYieldGroup} if a candidate queue drops a YieldGroup still holding a
+     *      balance.
+     * @param queue Full replacement queue in withdraw-priority order
+     */
+    function setOuterWithdrawQueue(address[] calldata queue) external;
+
+    // ----------------------- Reallocate (Operator) ---------------------------
+
+    /**
+     * @notice Atomically rebalance assets across YieldGroups — and, optionally, across specific
+     *         resources within a YieldGroup. Withdraw legs execute first, deposit legs second.
+     *         `Σ withdraws == Σ deposits` is enforced.
+     * @dev ACM role `"reallocate((address,address,uint256)[],(address,address,uint256)[])"`
+     *      (Operator). Each leg may name a specific `resource` to target one market/vault directly, or
+     *      pass `address(0)` to route through the YieldGroup's inner queue (the original
+     *      behavior). Setting both legs to the same `yieldGroup` performs an intra-YieldGroup move
+     *      (e.g. vUSDT_v1 → vUSDT_v2). Honors per-YieldGroup caps and pause on the deposit side.
+     *      Emits {WithdrawRouted} per pull and {DepositRouted} per push at the YieldGroup level;
+     *      the targeted YieldGroup additionally emits its own resource-level routing event.
+     * @param withdraws Ordered list of (YieldGroup, resource, amount) legs to pull from.
+     * @param deposits Ordered list of (YieldGroup, resource, amount) legs to push into.
+     */
+    function reallocate(ReallocateLeg[] calldata withdraws, ReallocateLeg[] calldata deposits) external;
+
+    /**
+     * @notice Emergency variant of {reallocate} that stays callable while the Hub is paused, so
+     *         governance can wind down / rebalance a stressed position during a freeze.
+     * @dev ACM role `"emergencyReallocate((address,address,uint256)[],(address,address,uint256)[])"`
+     *      (Guardian or VIP/governance — NOT the Operator: this is the one fund-moving lever that bypasses the
+     *      Hub pause, so it carries a separate role the Operator does not hold). Same net-zero
+     *      (`Σ withdraws == Σ deposits`) semantics as {reallocate}; fee accrual is skipped while the
+     *      Hub is paused so the frozen window is not charged.
+     * @param withdraws Ordered list of (yieldGroup, resource, amount) legs to pull from.
+     * @param deposits Ordered list of (yieldGroup, resource, amount) legs to push into.
+     */
+    function emergencyReallocate(ReallocateLeg[] calldata withdraws, ReallocateLeg[] calldata deposits) external;
+
+    // ----------------------- Pause (asymmetric) ------------------------------
+
+    /// @notice Pause the Hub
+    /// @dev ACM role `"pauseHub()"` (Operator, Guardian, or VIP).
+    function pauseHub() external;
+
+    /// @notice Unpause the Hub
+    /// @dev ACM role `"unpauseHub()"` (VIP).
+    function unpauseHub() external;
+
+    /**
+     * @notice Pause routing to a specific YieldGroup
+     * @dev ACM role `"pauseYieldGroup(address)"` (Operator or VIP).
+     * @param yieldGroup YieldGroup to pause
+     */
+    function pauseYieldGroup(address yieldGroup) external;
+
+    /**
+     * @notice Unpause routing to a specific YieldGroup
+     * @dev ACM role `"unpauseYieldGroup(address)"` (VIP).
+     * @param yieldGroup YieldGroup to unpause
+     */
+    function unpauseYieldGroup(address yieldGroup) external;
+
+    // ----------------------- Per-request withdraw cap ------------------------
+
+    /**
+     * @notice Raise the per-transaction withdraw cap
+     * @dev ACM role `"raiseMaxWithdrawalSize(uint256)"` (VIP) — raising is loosening.
+     * @param newSize New cap in asset units
+     */
+    function raiseMaxWithdrawalSize(uint256 newSize) external;
+
+    /**
+     * @notice Lower the per-transaction withdraw cap
+     * @dev ACM role `"lowerMaxWithdrawalSize(uint256)"` (Operator or VIP) — tightening.
+     * @param newSize New cap in asset units
+     */
+    function lowerMaxWithdrawalSize(uint256 newSize) external;
+
+    // --------------------------------- Fees ----------------------------------
+
+    /**
+     * @notice Set the management fee rate
+     * @dev ACM role `"setManagementFeeBps(uint16)"` (VIP). Pending fees accrue at the OLD rate
+     *      first. Capped at `MAX_FEE_BPS`.
+     * @param bps New management fee rate in BPS
+     */
+    function setManagementFeeBps(uint16 bps) external;
+
+    /**
+     * @notice Set the performance fee rate
+     * @dev ACM role `"setPerformanceFeeBps(uint16)"` (VIP). Pending fees accrue at the OLD rate
+     *      first. Capped at `MAX_FEE_BPS`.
+     * @param bps New performance fee rate in BPS
+     */
+    function setPerformanceFeeBps(uint16 bps) external;
+
+    /**
+     * @notice Set the exit (withdraw/redeem) fee rate, retained in the vault and socialised to
+     *         remaining LPs. Anti-sandwich governance lever; default 0.
+     * @param bps New exit fee rate in BPS (≤ 5%)
+     */
+    function setRedeemFeeBps(uint16 bps) external;
+
+    /**
+     * @notice Current exit (withdraw/redeem) fee rate in BPS.
+     * @return bps Exit fee rate in BPS (0 by default).
+     */
+    function redeemFeeBps() external view returns (uint16 bps);
+
+    /**
+     * @notice Set the fee-share recipient
+     * @dev ACM role `"setFeeRecipient(address)"` (VIP). Pending fees mint to the OLD recipient
+     *      first; `address(0)` disables fee minting.
+     * @param recipient New fee-share recipient
+     */
+    function setFeeRecipient(address recipient) external;
+
+    /// @notice Public poke that brings fee state up to date
+    /// @dev Permissionless.
+    function accrueFees() external;
+
+    // --------------------------------- Sweep ----------------------------------
+
+    /**
+     * @notice Forward the Hub's full balance of an arbitrary ERC-20 to a recipient
+     * @dev ACM role `"sweep(address,address)"` (VIP). Reverts {SweepProtectedAsset} if
+     *      `token == asset()` — the underlying can never be swept. Callable while paused.
+     * @param token ERC-20 to sweep
+     * @param to Recipient of the balance
+     */
+    function sweep(address token, address to) external;
+
+    // ----------------------------- Supplier functions ------------------------
+
+    /**
+     * @notice Deposit assets and optionally record the supplier's disclaimer consent on-chain in the
+     *         same transaction. Thin wrapper over {deposit}.
+     * @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} before delegating, so it is rolled back with the
+     *      transaction if the delegated {deposit} reverts. All cap / pause / accrual gating is enforced
+     *      by {deposit}; this wrapper adds no other behaviour.
+     * @param assets Amount of underlying to deposit
+     * @param receiver Address to receive the minted shares
+     * @param consentHash keccak256 hash of the disclaimer content the supplier consented to;
+     *        `bytes32(0)` skips recording (no event emitted)
+     * @return shares Shares minted to `receiver`
+     * @custom:event ConsentRecorded Emitted with the supplier, receiver, and hash when consentHash is non-zero
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws HubCapacityExceeded if aggregate spare cap across unpaused YieldGroups is insufficient
+     */
+    function depositWithConsent(uint256 assets, address receiver, bytes32 consentHash) external returns (uint256 shares);
+
+    /**
+     * @notice Mint shares and optionally record the supplier's disclaimer consent on-chain in the
+     *         same transaction. Thin wrapper over {mint}.
+     * @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} before delegating, so it is rolled back with the
+     *      transaction if the delegated {mint} reverts. All cap / pause / accrual gating is enforced by
+     *      {mint}; this wrapper adds no other behaviour.
+     * @param shares Amount of shares to mint
+     * @param receiver Address to receive the minted shares
+     * @param consentHash keccak256 hash of the disclaimer content the supplier consented to;
+     *        `bytes32(0)` skips recording (no event emitted)
+     * @return assets Underlying pulled from the caller
+     * @custom:event ConsentRecorded Emitted with the supplier, receiver, and hash when consentHash is non-zero
+     * @custom:error Throws HubPaused if the Hub is paused
+     * @custom:error Throws HubCapacityExceeded if aggregate spare cap is insufficient for the shares requested
+     */
+    function mintWithConsent(uint256 shares, address receiver, bytes32 consentHash) external returns (uint256 assets);
+
+    // --------------------------------- Views ---------------------------------
+
+    /**
+     * @notice Full config struct for a YieldGroup
+     * @param yieldGroup Address to look up
+     * @return config Stored config
+     */
+    function yieldGroupConfig(address yieldGroup) external view returns (YieldGroupConfig memory config);
+
+    /**
+     * @notice Live effective cap for a YieldGroup
+     * @param yieldGroup Address to look up
+     * @return cap Effective cap in asset units
+     */
+    function yieldGroupEffectiveCap(address yieldGroup) external view returns (uint256 cap);
+
+    /**
+     * @notice Registered YieldGroups
+     * @return yieldGroups Storage copy of the registry array
+     */
+    function registeredYieldGroups() external view returns (address[] memory yieldGroups);
+
+    /**
+     * @notice Current deposit routing order
+     * @return queue Storage copy of the deposit queue
+     */
+    function outerDepositQueue() external view returns (address[] memory queue);
+
+    /**
+     * @notice Current withdraw routing order
+     * @return queue Storage copy of the withdraw queue
+     */
+    function outerWithdrawQueue() external view returns (address[] memory queue);
+
+    /**
+     * @notice Per-transaction withdraw cap in asset units
+     * @return size Cap value
+     */
+    function maxWithdrawalSize() external view returns (uint256 size);
+
+    /**
+     * @notice Hub-level pause state
+     * @return paused True if `pauseHub()` is in effect
+     */
+    function hubPaused() external view returns (bool paused);
+
+    /**
+     * @notice Recipient of newly-minted fee shares
+     * @return recipient Fee recipient
+     */
+    function feeRecipient() external view returns (address recipient);
+
+    /**
+     * @notice Current fee rates in BPS
+     * @return managementBps Management fee rate
+     * @return performanceBps Performance fee rate
+     */
+    function feeBps() external view returns (uint16 managementBps, uint16 performanceBps);
+
+    /**
+     * @notice Performance HWM in share-price units
+     * @return hwm HWM value
+     */
+    function highWaterMarkPerShare() external view returns (uint256 hwm);
+}

package/contracts/interfaces/IHubRegistry.sol

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IHubRegistry
+ * @author Venus
+ * @notice External interface for the chain-level Hub directory. The registry is the single
+ *         on-chain discovery root for the Liquidity Hub topology: off-chain indexers watch
+ *         {HubAdded} / {HubRemoved} here, then follow each Hub's own `YieldGroupAdded` /
+ *         `YieldGroupRemoved` events to reconstruct the full hub → YieldGroup graph. One
+ *         registry per chain; exactly one active Hub per asset.
+ * @dev Conventions:
+ *      - Hubs are deployed outside the registry (the `deploy/06_DeployAssetVault` bootstrap
+ *        script) and registered via `addHub`, which derives the asset key from
+ *        `IHub(hub).asset()`.
+ *      - Indexer correctness contract (NORMATIVE): on every {HubAdded}, an indexer MUST seed
+ *        that Hub's YieldGroup set from state (`registeredYieldGroups()` + per-group config
+ *        views). Event ordering — the onboarding VIP places `addHub` before the Hub's
+ *        `addYieldGroup` calls in one atomic transaction, so {HubAdded} lands at a lower log
+ *        index — is a latency optimization only, NOT a correctness requirement: it is a VIP
+ *        convention that nothing on-chain enforces, and Hubs configured before registration
+ *        (e.g. pre-registry deployments) emit `YieldGroupAdded` before {HubAdded} regardless.
+ *      - The registry holds no funds and never routes assets.
+ *      - Permissions are gated by `AccessControlManagerV8`: each governance-gated function
+ *        calls `_checkAccessAllowed` with its literal function-signature string (e.g.
+ *        `"addHub(address)"`), which is the ACM role for that function.
+ *      - Replacing an asset's hub is an explicit `removeHub` followed by `addHub` — two
+ *        events, so indexers never observe an implicit swap.
+ */
+interface IHubRegistry {
+    // --------------------------------- Events --------------------------------
+
+    /// @notice Emitted when a Hub is registered for its underlying asset
+    /// @param asset Underlying asset of the Hub (`IHub(hub).asset()`)
+    /// @param hub Newly-registered Hub
+    event HubAdded(address indexed asset, address indexed hub);
+
+    /// @notice Emitted when a Hub is removed from the registry
+    /// @param asset Underlying asset the Hub was registered under
+    /// @param hub Removed Hub
+    event HubRemoved(address indexed asset, address indexed hub);
+
+    // --------------------------------- Errors --------------------------------
+
+    /// @notice Error thrown when a required non-zero address parameter was zero
+    error ZeroAddress();
+
+    /// @notice Error thrown when `addHub()` is called with an already-registered Hub
+    /// @param hub Address that is already registered
+    error HubAlreadyRegistered(address hub);
+
+    /// @notice Error thrown when `addHub()` would register a second Hub for an asset that
+    ///         already has one. Replace explicitly: `removeHub(existingHub)` then `addHub(hub)`.
+    /// @param asset Asset that is already served
+    /// @param existingHub Hub currently registered for `asset`
+    error AssetAlreadyHasHub(address asset, address existingHub);
+
+    /// @notice Error thrown when `removeHub()` is called with a Hub that is not in the registry
+    /// @param hub Address that failed the registry lookup
+    error HubNotRegistered(address hub);
+
+    // ----------------------------- Mutating (governance) ---------------------
+
+    /**
+     * @notice Register an externally-deployed Hub under its underlying asset
+     * @dev ACM role `"addHub(address)"` (VIP). Reads `IHub(hub).asset()` to derive the key.
+     *      In an onboarding VIP, order this call BEFORE the Hub's `addYieldGroup` calls so
+     *      {HubAdded} precedes every `YieldGroupAdded` in the same transaction (a latency
+     *      optimization — indexers MUST state-seed on {HubAdded} regardless; see the
+     *      interface-level indexer contract).
+     * @param hub Hub contract address
+     */
+    function addHub(address hub) external;
+
+    /**
+     * @notice Remove a Hub from the registry
+     * @dev ACM role `"removeHub(address)"` (VIP).
+     * @param hub Hub to remove
+     */
+    function removeHub(address hub) external;
+
+    // --------------------------------- Views ---------------------------------
+
+    /**
+     * @notice Active Hub for an asset
+     * @param asset Underlying asset to look up
+     * @return hub Registered Hub, or `address(0)` if the asset has none
+     */
+    function hubForAsset(address asset) external view returns (address hub);
+
+    /**
+     * @notice The asset a Hub is registered under (reverse of {hubForAsset})
+     * @dev Returns the registry's asset-of-record, `address(0)` if `hub` is not registered — so it
+     *      doubles as a registration check without a STATICCALL into a possibly-bricked Hub, and is
+     *      authoritative even after a Hub is removed (unlike `IHub(hub).asset()`, which still reports
+     *      the underlying).
+     * @param hub Hub to look up
+     * @return asset Underlying asset the hub is registered under, or `address(0)` if not registered
+     */
+    function assetForHub(address hub) external view returns (address asset);
+
+    /**
+     * @notice All registered Hubs
+     * @return hubs Storage copy of the registry array
+     */
+    function getHubs() external view returns (address[] memory hubs);
+
+    /**
+     * @notice Number of registered Hubs
+     * @return count Length of the registry array
+     */
+    function getHubsCount() external view returns (uint256 count);
+
+    /**
+     * @notice Whether an address is a registered Hub
+     * @param hub Address to check
+     * @return registered True iff `hub` is present in `getHubs()`
+     */
+    function isHub(address hub) external view returns (bool registered);
+}