@venusprotocol/liquidity-hub 0.0.0

package/contracts/interfaces/IYieldGroupBase.sol

@@ -0,0 +1,507 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IYieldGroupBase
+ * @author Venus
+ * @notice Boundary between Hub and the concrete typed routers (the generic `YieldGroup` serving
+ *         Core / Flux, `YieldGroupFRV`, ...). Hub depends only on this interface; it never reaches
+ *         past a YieldGroup into the underlying market (vToken / Fluid / FRV).
+ * @dev This interface also declares the registry / queue / pause surface and the struct, events and
+ *      errors shared by every concrete YieldGroup, so the shared `YieldGroupBase` implementation can
+ *      live in one place. Family-specific surface (the per-resource cap + `blocksPerYear` for the
+ *      generic; `forceRemoveResource` for FRV) lives in the leaf interfaces `IYieldGroup` and
+ *      `IYieldGroupFRV`. Conventions:
+ *      - All amounts are denominated in `asset()` units (no share conversion at this layer).
+ *      - `deposit` / `withdraw` (and their `*Resource` variants) are Hub-only; implementers
+ *        gate them with an `onlyHub` modifier. Hub pulls via safeTransferFrom, so Hub must
+ *        approve this YieldGroup before calling `deposit`.
+ *      - `withdraw` pushes the underlying directly to the supplied `to` address (rather than
+ *        always to `msg.sender`) so future Hub optimisations can route to the end-receiver
+ *        without an interface rev. Today Hub passes `address(this)`.
+ *      - `deposit` returns the actually-placed amount, which may be LESS than the requested
+ *        `amount` (partial fill). Implementers place what their inner queue can absorb, refund
+ *        the unplaced remainder to the caller (the Hub) via `asset` transfer, and return the
+ *        placed amount. The Hub's auto-routing cascade treats the return value as the placed
+ *        amount and routes the refunded remainder to the next YieldGroup. `reallocate`, which
+ *        moves an exact named amount, keeps its own `deposited == amount` exact-fill check and
+ *        reverts {YieldGroupUnderfilled} on a short fill — so partial fills are only ever
+ *        consumed by the auto-route, never by reallocation.
+ *        Fee-on-transfer underlyings are unsupported and fail closed *inside* the deposit:
+ *        the inner queue routes against the requested amount, so a token that skims the
+ *        transfer leaves the YieldGroup short and the downstream mint reverts.
+ *      - `withdraw` has no return value: it MUST deliver exactly `amount` to `to` or revert.
+ *        Hub defensively measures the resulting balance delta rather than trusting a
+ *        self-reported number; tighter than the prior return-value convention.
+ *      - YieldGroups may hold assets across multiple internal vaults and route via their own
+ *        inner queue; that detail is opaque to Hub.
+ */
+interface IYieldGroupBase {
+    // -------------------------------- Types ----------------------------------
+
+    /**
+     * @notice Per-resource configuration.
+     * @dev The optional per-resource deposit cap lives in a separate mapping (see
+     *      {IYieldGroup.resourceCap}), not in this struct, so adding it did not disturb the
+     *      struct's single-slot packing. The `paused` flag enables a per-resource pause scope even
+     *      when only one resource is registered. The `adapter` field is the `IResourceAdapter`
+     *      implementation that translates between this YieldGroup and the resource's
+     *      protocol-specific ABI; adapters are stateless and typically shared across every
+     *      YieldGroup registering the same protocol family.
+     * @param registered True iff present in the resource registry.
+     * @param paused When true, routing skips this resource; existing balance still counts.
+     * @param adapter `IResourceAdapter` implementation handling this resource's ABI.
+     */
+    struct ResourceConfig {
+        bool registered;
+        bool paused;
+        address adapter;
+    }
+
+    // -------------------------------- Events ----------------------------------
+
+    /**
+     * @notice A new yield resource was registered alongside the adapter that handles it.
+     * @param resource Newly-registered resource address (e.g. a Venus vToken).
+     * @param adapter `IResourceAdapter` implementation translating this resource's ABI.
+     */
+    event ResourceAdded(address indexed resource, address indexed adapter);
+
+    /**
+     * @notice A registered resource was removed.
+     * @param resource Removed resource address.
+     */
+    event ResourceRemoved(address indexed resource);
+
+    /**
+     * @notice A registered resource's adapter was repointed without changing the resource itself.
+     * @param resource Resource whose adapter changed; its held balance and registry slot are kept.
+     * @param oldAdapter Previous `IResourceAdapter` implementation.
+     * @param newAdapter New `IResourceAdapter` implementation now handling this resource's ABI.
+     */
+    event ResourceAdapterUpdated(address indexed resource, address indexed oldAdapter, address indexed newAdapter);
+
+    /**
+     * @notice A resource's pause flag flipped.
+     * @param resource Resource whose flag flipped.
+     * @param paused New pause state.
+     */
+    event ResourcePauseToggled(address indexed resource, bool paused);
+
+    /**
+     * @notice Inner deposit-queue order replaced.
+     * @param queue Full replacement queue in deposit-priority order.
+     */
+    event InnerDepositQueueSet(address[] queue);
+
+    /**
+     * @notice Inner withdraw-queue order replaced.
+     * @param queue Full replacement queue in withdraw-priority order.
+     */
+    event InnerWithdrawQueueSet(address[] queue);
+
+    /**
+     * @notice Underlying placed into a resource on a deposit / reallocate-push leg.
+     * @param resource Resource that received the deposit.
+     * @param amount Underlying units placed.
+     */
+    event DepositRouted(address indexed resource, uint256 amount);
+
+    /**
+     * @notice Underlying pulled from a resource on a withdraw / reallocate-pull leg.
+     * @param resource Resource that was pulled from.
+     * @param amount Underlying units pulled.
+     */
+    event WithdrawRouted(address indexed resource, uint256 amount);
+
+    /**
+     * @notice A cascade leg was skipped because its mutating dispatch reverted (e.g. the resource's
+     *         external protocol paused it or rejected the leg). The operation routes around it
+     *         instead of bubbling the revert; a healthy system emits this zero times.
+     * @param resource Resource whose deposit / withdraw leg was skipped.
+     * @param isDeposit True if the skipped leg was a deposit, false for a withdraw.
+     */
+    event ResourceSkipped(address indexed resource, bool isDeposit);
+
+    /**
+     * @notice A resource's accrual poke reverted and was skipped so it does not brick the Hub's fee accrual; a healthy system emits this zero times.
+     * @param resource Resource whose accrual poke reverted.
+     * @param adapter Adapter registered for that resource.
+     */
+    event ResourceAccrualFailed(address indexed resource, address indexed adapter);
+
+    /**
+     * @notice A stray non-asset, non-receipt ERC-20 balance was 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);
+
+    // -------------------------------- Errors ----------------------------------
+
+    /// @notice Caller of an `onlyHub` function was not the registered Hub.
+    /// @param caller The non-Hub address that called the function.
+    error NotHub(address caller);
+
+    /**
+     * @notice Caller lacked the ACM role required for the called function.
+     * @param caller Address whose ACM lookup failed.
+     * @param signature ACM role string that was checked.
+     */
+    error Unauthorized(address caller, string signature);
+
+    /// @notice A `dispatch*External` self-call wrapper was invoked by anyone other than the
+    ///         YieldGroup itself. These wrappers exist only so the inner cascade can `try/catch`
+    ///         the adapter delegatecall; they are not part of the external API.
+    error OnlySelf();
+
+    /// @notice Required non-zero address parameter was zero.
+    error ZeroAddress();
+
+    /**
+     * @notice The asset declared in `initialize` does not match the Hub's `asset()`.
+     * @param declared Asset address passed at initialisation.
+     * @param hubAsset Asset address reported by the Hub.
+     */
+    error HubAssetMismatch(address declared, address hubAsset);
+
+    /**
+     * @notice A registered resource's asset (as reported by its adapter's `asset(resource)`) does
+     *         not match this YieldGroup's asset.
+     * @param resource Resource under inspection.
+     * @param resourceAsset Asset the adapter reported for the resource.
+     * @param expected This YieldGroup's `assetToken`.
+     */
+    error ResourceAssetMismatch(address resource, address resourceAsset, address expected);
+
+    /**
+     * @notice `addResource()` called with an already-registered resource.
+     * @param resource Address that is already registered.
+     */
+    error ResourceAlreadyRegistered(address resource);
+
+    /**
+     * @notice Operation targeted a resource that is not in the registry.
+     * @param resource Address that failed the registry lookup.
+     */
+    error ResourceNotRegistered(address resource);
+
+    /**
+     * @notice `removeResource()` called while the resource still holds a non-zero balance.
+     * @param resource Resource attempted to be removed.
+     * @param balance Current resource balance preventing removal.
+     */
+    error ResourceHasBalance(address resource, uint256 balance);
+
+    /**
+     * @notice A deposit (passive cascade or targeted `depositResource`) was routed to a paused
+     *         resource. Pause / unpause toggles are idempotent no-ops, so this fires only on the
+     *         deposit path — never for a redundant pause-state change.
+     * @param resource The paused resource the deposit targeted.
+     */
+    error ResourceIsPaused(address resource);
+
+    /**
+     * @notice Deposit exceeded aggregate spare capacity across the inner deposit queue.
+     * @param requested Underlying units requested.
+     * @param maxAvailable Aggregate spare capacity at revert time.
+     */
+    error ResourceCapacityExceeded(uint256 requested, uint256 maxAvailable);
+
+    /**
+     * @notice Withdraw exceeded aggregate liquid funds across the inner withdraw queue.
+     * @param requested Underlying units requested.
+     * @param available Aggregate liquid funds at revert time.
+     */
+    error ResourceLiquidityInsufficient(uint256 requested, uint256 available);
+
+    /**
+     * @notice The supplied resource address is not a contract (code length zero). Catches
+     *         registering an EOA as a resource, which would make the adapter's `asset()` probe
+     *         revert opaquely on the empty-returndata decode.
+     * @param resource Offending resource address.
+     */
+    error ResourceNotContract(address resource);
+
+    /**
+     * @notice The supplied adapter address is not a contract (code length zero). Catches
+     *         registering an EOA, which would cause `delegatecall` to silently succeed
+     *         without doing anything and orphan the deposit.
+     * @param adapter Offending adapter address.
+     */
+    error AdapterNotContract(address adapter);
+
+    /**
+     * @notice The adapter completed a delegatecall but its observed effect did not match the
+     *         requested amount (e.g. `withdraw` did not transfer the full amount). Indicates an
+     *         adapter bug; the underlying protocol's own revert is bubbled up directly when it fires.
+     * @param resource Resource the adapter was acting on.
+     * @param requested Amount the YieldGroup asked the adapter to move.
+     * @param actual Amount the YieldGroup observed.
+     */
+    error AdapterUnderfilled(address resource, uint256 requested, uint256 actual);
+
+    /// @notice Queue contains duplicates or references an unregistered resource.
+    error InvalidQueue();
+
+    /**
+     * @notice Withdraw queue omits a resource still holding receipt tokens, which the cascade would
+     *         then not visit.
+     * @param resource The funded resource missing from the queue.
+     */
+    error WithdrawQueueOmitsFundedResource(address resource);
+
+    /**
+     * @notice A targeted deposit fell below a resource's minimum deposit floor without being the
+     *         exact residual tail. Only thrown by subclasses that impose a per-resource minimum
+     *         (e.g. FRV's `minSupplierDeposit`); for families with no floor this never fires.
+     * @param resource Resource the deposit targeted.
+     * @param requested Underlying units requested.
+     * @param minimum The resource's minimum deposit floor.
+     */
+    error ResourceBelowMinimumDeposit(address resource, uint256 requested, uint256 minimum);
+
+    /// @notice `sweep()` was called with `token == asset()`; the asset is counted as idle in
+    ///         `totalAssets` and must never be sweepable.
+    error SweepProtectedAsset();
+
+    /**
+     * @notice `sweep()` targeted a registered resource. In every family the resource address is the
+     *         receipt token backing `totalAssets`, so sweeping it would drain the YieldGroup.
+     * @param resource The registered resource that may not be swept.
+     */
+    error SweepProtectedResource(address resource);
+
+    // -------------------------------- Mutating -------------------------------
+
+    /**
+     * @notice Move `amount` of `asset` from caller into this YieldGroup's vaults via the inner
+     *         deposit queue. Pulls via safeTransferFrom; caller must have approved.
+     * @param amount Requested amount in asset units.
+     * @return deposited Amount actually placed across vaults; may be LESS than `amount` when the
+     *         inner queue cannot absorb it all. The unplaced remainder is refunded to the caller
+     *         and the Hub's auto-route places it elsewhere. `reallocate` instead asserts
+     *         `deposited == amount` at its own call site and reverts on a short fill.
+     */
+    function deposit(uint256 amount) external returns (uint256 deposited);
+
+    /**
+     * @notice Pull `amount` of `asset` from this YieldGroup's vaults via the inner withdraw queue
+     *         and send it to `to`.
+     * @dev Must deliver exactly `amount` to `to` or revert; no partial fill. Hub measures the
+     *      balance delta on `to` to defensively verify delivery.
+     * @param amount Requested amount in asset units.
+     * @param to Recipient of the withdrawn assets.
+     */
+    function withdraw(uint256 amount, address to) external;
+
+    /**
+     * @notice Settle accrued interest across this YieldGroup's resources so a following
+     *         {totalAssets} read values them at a fresh exchange rate.
+     * @dev `onlyHub`. The Hub calls this once per block before reading NAV for fee accrual, so
+     *      the fee is charged on interest-current value rather than a one-cycle-stale one. The
+     *      freshening is best-effort: a resource whose accrual reverts is left at its last-settled
+     *      rate (still valid for `totalAssets`) instead of bricking the whole accrual. Block-lazy
+     *      families (Core) do real work; Flux and FRV implement it as a no-op.
+     */
+    function accrue() external;
+
+    // ------------------- Mutating (Operator reallocation) --------------------
+    // The two functions below address a SPECIFIC resource inside the YieldGroup, bypassing the
+    // inner queue. They exist solely for Hub-orchestrated `reallocate`. The Hub treats
+    // `resource` as an opaque address it does not interpret — the YieldGroup validates it against
+    // its own registry. This is the one place the Hub names something below the YieldGroup
+    // boundary; the rest of IYieldGroupBase stays resource-agnostic.
+
+    /**
+     * @notice Deposit `amount` of `asset` into a SPECIFIC resource within this YieldGroup,
+     *         bypassing the inner deposit queue. Pulls via safeTransferFrom; caller must have
+     *         approved.
+     * @dev `onlyHub`. Unlike {deposit} (which cascades through the inner queue), this routes
+     *      the full amount into the single named `resource` and reverts if that resource
+     *      cannot accept exactly `amount` — capacity, pause, or lifecycle state. Reverting on
+     *      under-placement is required: the Hub's reallocate net-zero invariant relies on each
+     *      leg moving its stated amount in full.
+     * @param resource Target resource (e.g. a specific vToken or FRV vault) to deposit into.
+     * @param amount Requested amount in asset units. Placed in full or the call reverts.
+     * @return deposited Amount placed; equals `amount` on success.
+     */
+    function depositResource(address resource, uint256 amount) external returns (uint256 deposited);
+
+    /**
+     * @notice Withdraw `amount` of `asset` from a SPECIFIC resource within this YieldGroup,
+     *         bypassing the inner withdraw queue, and send it to `to`.
+     * @dev `onlyHub`. Unlike {withdraw}, this does NOT consume idle balance first and does NOT
+     *      cascade — it redeems exactly `amount` from the single named `resource` or reverts
+     *      (insufficient liquidity, or a locked lifecycle state for FRV). Must deliver exactly
+     *      `amount` to `to`; pulling from a paused resource is permitted (wind-down).
+     * @param resource Target resource to pull from.
+     * @param amount Requested amount in asset units. Delivered in full or the call reverts.
+     * @param to Recipient of the withdrawn assets.
+     */
+    function withdrawResource(address resource, uint256 amount, address to) external;
+
+    // ----------------------- Registry (governance) ---------------------------
+
+    /**
+     * @notice Register a new yield resource alongside the stateless adapter that handles its
+     *         ABI. The same adapter address may be reused for any number of resources in the
+     *         same protocol family (one deployment of `AdapterCoreV1` serves every Core V1
+     *         vToken on every YieldGroup, for example).
+     * @dev ACM role `"addResource(address,address)"` (VIP). Validates:
+     *      - `adapter` is a contract (not an EOA) — delegatecall to an EOA returns success
+     *        with empty data and would silently no-op every routing call.
+     *      - `adapter.asset(resource) == asset()` — the resource speaks the YieldGroup's
+     *        underlying currency.
+     *      Does not auto-append to either inner queue. Emits {ResourceAdded}.
+     * @param resource Resource address to register (e.g. a Venus vToken).
+     * @param adapter `IResourceAdapter` implementation handling this resource's ABI.
+     */
+    function addResource(address resource, address adapter) external;
+
+    /**
+     * @notice Remove a registered resource. Requires zero balance held in that resource.
+     * @dev ACM role `"removeResource(address)"` (VIP). Also removes the resource from both
+     *      inner queues via swap-and-pop. Emits {ResourceRemoved}.
+     * @param resource Resource to remove.
+     */
+    function removeResource(address resource) external;
+
+    /**
+     * @notice Repoint a registered resource at a new adapter, keeping its balance and registry
+     *         slot intact. Intended for the case where the underlying yield source is still
+     *         functioning but the adapter needs a fix or must follow an underlying-protocol
+     *         upgrade — `removeResource` is balance-gated and cannot serve that without first
+     *         draining the position.
+     * @dev ACM role `"updateResourceAdapter(address,address)"` (VIP). Re-runs the same checks as
+     *      `addResource` against `newAdapter` (contract-not-EOA, `asset(resource) == asset()`,
+     *      `validateRegistration`); pause flag, cap, and queue position are unchanged. Emits
+     *      {ResourceAdapterUpdated}.
+     * @param resource Registered resource to repoint.
+     * @param newAdapter New `IResourceAdapter` implementation handling this resource's ABI.
+     */
+    function updateResourceAdapter(address resource, address newAdapter) external;
+
+    // ----------------------- Inner queues (Operator) -------------------------
+
+    /**
+     * @notice Replace the inner deposit-routing order.
+     * @dev ACM role `"setInnerDepositQueue(address[])"` (Operator or VIP). Every entry must be
+     *      a registered resource; duplicates revert. Emits {InnerDepositQueueSet}. Operator
+     *      responsibility: keep every queue member in the inner withdraw queue. A member absent from
+     *      the withdraw queue is funded by deposits but not reached by the withdraw cascade 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 setInnerDepositQueue(address[] calldata queue) external;
+
+    /**
+     * @notice Replace the inner withdraw-routing order.
+     * @dev ACM role `"setInnerWithdrawQueue(address[])"` (Operator or VIP). Independent of the
+     *      deposit queue. Emits {InnerWithdrawQueueSet}.
+     * @param queue Full replacement queue in withdraw-priority order.
+     */
+    function setInnerWithdrawQueue(address[] calldata queue) external;
+
+    // ----------------------- Pause (asymmetric) ------------------------------
+
+    /**
+     * @notice Pause routing to a specific resource. Existing balance stays counted.
+     * @dev ACM role `"pauseResource(address)"` (Operator or VIP). Emits {ResourcePauseToggled}.
+     * @param resource Resource to pause.
+     */
+    function pauseResource(address resource) external;
+
+    /**
+     * @notice Unpause routing to a specific resource.
+     * @dev ACM role `"unpauseResource(address)"` (VIP). Emits {ResourcePauseToggled}.
+     * @param resource Resource to unpause.
+     */
+    function unpauseResource(address resource) external;
+
+    // ------------------------------- Sweep (governance) ----------------------
+
+    /**
+     * @notice Forward this YieldGroup's full balance of a stray ERC-20 to `to`, recovering rewards,
+     *         airdrops, or mistransfers that would otherwise be locked. Mirrors the Hub's `sweep`.
+     * @dev ACM role `"sweep(address,address)"` (VIP). Bars `asset()` (counted as idle in `totalAssets`)
+     *      and every registered resource (the receipt token backing NAV in all current families), so
+     *      no value-bearing token is sweepable. Zero balance is a silent no-op; emits {Swept} otherwise.
+     * @param token Stray ERC-20 to sweep; neither `asset()` nor a registered resource.
+     * @param to Recipient of the balance.
+     */
+    function sweep(address token, address to) external;
+
+    // ---------------------------------- Views --------------------------------
+
+    /**
+     * @notice The ERC-20 asset this YieldGroup accepts. Must match `Hub.asset()`.
+     * @return underlying Address of the asset token.
+     */
+    function asset() external view returns (address underlying);
+
+    /**
+     * @notice Sum of `asset` held across all of this YieldGroup's underlying vaults.
+     * @dev Hub sums `totalAssets()` over its registered YieldGroups to compute its own totalAssets().
+     * @return total Asset units currently held by the YieldGroup.
+     */
+    function totalAssets() external view returns (uint256 total);
+
+    /**
+     * @notice Aggregate remaining deposit capacity across this YieldGroup's underlying vaults.
+     * @dev Must satisfy: `deposit(maxDeposit())` does not revert (EIP-4626 honesty contract,
+     *      transitively applied to YieldGroups). Caveat: a YieldGroup whose capacity depends on a
+     *      lifecycle clock (FRV, whose vaults exit `Fundraising` by time) can report stale
+     *      non-zero capacity from this view until a state-advancing call refreshes it; the
+     *      honesty contract holds against current state, not a time-due future one.
+     * @return capacity Spare deposit capacity in asset units.
+     */
+    function maxDeposit() external view returns (uint256 capacity);
+
+    /**
+     * @notice Aggregate currently-withdrawable amount across this YieldGroup's underlying vaults.
+     * @dev Must satisfy: `withdraw(maxWithdraw(), to)` does not revert (subject to upstream
+     *      liquidity).
+     * @return liquid Withdrawable amount in asset units.
+     */
+    function maxWithdraw() external view returns (uint256 liquid);
+
+    /**
+     * @notice TVL-weighted spot (instantaneous) supply-side APY across this YieldGroup's vaults,
+     *         in BPS (`10_000` = 100%). Informational only — not consumed by Hub accounting;
+     *         intended for off-chain APY tracking. The YieldGroup layer has no notion of historical
+     *         realisation.
+     * @return apyBps Spot APY in basis points.
+     */
+    function spotAPYBps() external view returns (uint64 apyBps);
+
+    /// @notice The Hub authorised to call `deposit` / `withdraw`.
+    /// @return hubAddress Address of the registered Hub.
+    function hub() external view returns (address hubAddress);
+
+    /// @notice The Access Control Manager gating governance calls.
+    /// @return acmAddress Address of the ACM.
+    function accessControlManager() external view returns (address acmAddress);
+
+    /// @notice All registered resources, in insertion order.
+    /// @return list Storage copy of the registry array.
+    function resources() external view returns (address[] memory list);
+
+    /**
+     * @notice Per-resource registration / pause state plus the adapter handling it.
+     * @param resource Address to look up.
+     * @return registered True iff present in `resources()`.
+     * @return paused True iff this resource is paused.
+     * @return adapter `IResourceAdapter` implementation bound to this resource.
+     */
+    function resourceConfig(address resource) external view returns (bool registered, bool paused, address adapter);
+
+    /// @notice Current inner deposit-routing order.
+    /// @return queue Storage copy of the inner deposit queue.
+    function innerDepositQueue() external view returns (address[] memory queue);
+
+    /// @notice Current inner withdraw-routing order.
+    /// @return queue Storage copy of the inner withdraw queue.
+    function innerWithdrawQueue() external view returns (address[] memory queue);
+}

package/contracts/interfaces/IYieldGroupFRV.sol

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IYieldGroupBase } from "./IYieldGroupBase.sol";
+
+/**
+ * @title IYieldGroupFRV
+ * @author Venus
+ * @notice External interface for `YieldGroupFRV` — a per-asset YieldGroup that aggregates one or
+ *         more Venus Fixed Rate Vaults behind the standard `IYieldGroupBase` Hub boundary.
+ * @dev Extends `IYieldGroupBase` (the Hub-facing surface + the shared registry / queue / pause
+ *      machinery) with the FRV-only `forceRemoveResource` escape hatch. FRV has no per-resource
+ *      deposit cap and no `blocksPerYear` annualiser, so it does not implement `IYieldGroup`. The
+ *      per-vault lifecycle (Fundraising → Lock → Matured / Closed) is handled inside the
+ *      implementation via `updateVaultState()` pre-advances; it is not part of this interface.
+ */
+interface IYieldGroupFRV is IYieldGroupBase {
+    // -------------------------------- Events ----------------------------------
+
+    /**
+     * @notice An un-drainable resource was force-removed by governance, orphaning its residual
+     *         (non-withdrawable) shares as an accepted write-off.
+     * @param resource Force-removed FRV vault address.
+     * @param orphanedShares Receipt-token (share) balance written off at removal.
+     */
+    event ResourceForceRemoved(address indexed resource, uint256 orphanedShares);
+
+    // -------------------------------- Errors ----------------------------------
+
+    /**
+     * @notice `forceRemoveResource()` was called on a resource that still carries realizable value
+     *         (NAV > 0). Force-removal may only orphan an already-valueless position; while value
+     *         remains it must be exited via the normal `removeResource` path.
+     * @param resource Resource attempted to be force-removed.
+     * @param nav Realizable value still backing the position.
+     */
+    error ResourceHasValue(address resource, uint256 nav);
+
+    // ----------------------- Initialisation ---------------------------------
+
+    /**
+     * @notice Initialise the YieldGroup. Called once via the proxy.
+     * @param hub_ Hub authorised to call `deposit` / `withdraw`.
+     * @param asset_ Underlying ERC-20 (must match `Hub.asset()`).
+     * @param acm_ AccessControlManagerV8 gating governance calls.
+     */
+    function initialize(address hub_, address asset_, address acm_) external;
+
+    // ----------------------- Registry (governance) ---------------------------
+
+    /**
+     * @notice Emergency-remove an un-drainable resource, orphaning its residual non-withdrawable
+     *         shares as an accepted write-off (e.g. an FRV vault moved to `Closed`, whose shares can
+     *         never be redeemed yet whose receipt balance permanently blocks `removeResource`).
+     * @dev ACM role `"forceRemoveResource(address)"` (VIP). Reverts {ResourceHasValue} if the
+     *      resource still carries realizable value (NAV), so it can only ever orphan value that is
+     *      already unrecoverable, never live funds. Also removes the resource from both inner queues.
+     * @param resource Resource to force-remove.
+     */
+    function forceRemoveResource(address resource) external;
+}

package/contracts/interfaces/external/IComptroller.sol

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IComptroller
+ * @author Venus
+ * @notice Minimal subset of the Venus Core Comptroller interface needed by the Core Yield
+ *         Group adapter. Only the accessors used by cap math, pause checks, and treasury-fee
+ *         gross-up are declared.
+ * @dev `actionPaused` uses `uint8` instead of importing Venus's `Action` enum to avoid
+ *      pulling in the full ComptrollerInterface dependency tree. The deployed contract uses
+ *      `enum Action { MINT, REDEEM, BORROW, REPAY, SEIZE, LIQUIDATE, TRANSFER, ENTER_MARKET,
+ *      EXIT_MARKET }`, so `MINT = 0` and `REDEEM = 1`. The ABI is identical to the enum form.
+ */
+interface IComptroller {
+    /**
+     * @notice Per-market supply cap, in underlying units. `0` means mint is rejected outright
+     *         (PolicyFacet:39 `require(supplyCap != 0)`).
+     * @param vToken Market to query.
+     * @return cap Supply cap in underlying units; `0` disables minting.
+     */
+    function supplyCaps(address vToken) external view returns (uint256 cap);
+
+    /**
+     * @notice Whether a specific action is paused on a given market.
+     * @param market vToken market to query.
+     * @param action Action enum value: `0 = MINT`, `1 = REDEEM`, etc.
+     * @return paused True iff the action is paused.
+     */
+    function actionPaused(address market, uint8 action) external view returns (bool paused);
+
+    /**
+     * @notice Fraction of every `redeemUnderlying` that is diverted to the treasury, scaled
+     *         by `1e18`. Non-zero values mean the receiver gets less than the requested
+     *         redeem amount; adapters must gross-up to deliver an exact net amount.
+     * @return percent Treasury cut, scaled by `1e18` (e.g. `5e16` = 5%).
+     */
+    function treasuryPercent() external view returns (uint256 percent);
+
+    /**
+     * @notice Approve or revoke `delegate` as a redeem-on-behalf-of agent for `msg.sender`.
+     *         After approval, `delegate` can call `vToken.redeemBehalf(msg.sender, ...)` and
+     *         `vToken.redeemUnderlyingBehalf(msg.sender, ...)` to burn `msg.sender`'s vTokens
+     *         and receive the underlying themselves (typically to forward).
+     * @param delegate Address to (un)authorise.
+     * @param approved True to grant, false to revoke.
+     */
+    function updateDelegate(address delegate, bool approved) external;
+
+    /**
+     * @notice Whether `delegate` is currently approved as a redeem-on-behalf agent for `owner`.
+     * @param owner The vToken holder whose delegation set is queried.
+     * @param delegate The address to test.
+     * @return approved True iff `delegate` may redeem on `owner`'s behalf.
+     */
+    function approvedDelegates(address owner, address delegate) external view returns (bool approved);
+}