@venusprotocol/liquidity-hub 0.0.0

package/contracts/YieldGroup/base/YieldGroupBaseStorage.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IYieldGroupBase } from "../../interfaces/IYieldGroupBase.sol";
+
+/**
+ * @title YieldGroupBaseStorage
+ * @notice Shared state for every concrete YieldGroup (the generic `YieldGroup` serving Core / Flux
+ *         and the `YieldGroupFRV` subclass), isolated in a base contract so upgrades can extend
+ *         without disturbing the inheritance linearisation. Add new fields after `__gap` is shrunk
+ *         by the same number of slots; never reorder, never prepend.
+ *
+ * @dev This is the UNION layout: every concrete shares this one slot table so a per-family beacon
+ *      can be repointed at a different implementation without a storage migration. `_blocksPerYear`
+ *      and `_resourceCap` are part of the union for layout stability even though a given family may
+ *      not use them — the generic `YieldGroup` writes them; `YieldGroupFRV` leaves them at `0`.
+ *
+ *         Slot layout (this contract's own contribution):
+ *
+ *           Slot  Used (bytes)  Field
+ *           ----  ------------  -----
+ *             0   20            _hub
+ *             1   20            _assetToken
+ *             2   32            _blocksPerYear          (generic only; 0 for FRV / Flux deploys)
+ *             3   20            _accessControlManager
+ *             4   32            _resources
+ *             5   32            _resourceIndex
+ *             6   32            _resourcesConfig
+ *             7   32            _innerDepositQueue
+ *             8   32            _innerWithdrawQueue
+ *             9   32            _resourceCap            (generic only; never written by FRV)
+ *         10..48  32 × 39       __gap
+ */
+abstract contract YieldGroupBaseStorage {
+    /// @notice Hub authorised to call `deposit` / `withdraw`. Set at initialisation.
+    address internal _hub;
+
+    /// @notice Underlying ERC-20 (matches `Hub.asset()`). Set at initialisation.
+    address internal _assetToken;
+
+    /// @notice Blocks-per-year constant used to annualise per-block supply rates. Set at
+    ///         initialisation; per-chain (BNB Chain ≈ 10_512_000). `0` for families whose adapter
+    ///         pre-annualises and ignores it (Flux), and for FRV.
+    uint256 internal _blocksPerYear;
+
+    /// @notice AccessControlManagerV8 gating governance functions. Set at initialisation.
+    address internal _accessControlManager;
+
+    /// @notice Canonical set of registered yield resources.
+    address[] internal _resources;
+
+    /// @notice 1-indexed position in `_resources` (0 = not registered). Enables O(1) removal.
+    mapping(address resource => uint256 indexPlusOne) internal _resourceIndex;
+
+    /// @notice Per-resource config (registration + pause + adapter).
+    mapping(address resource => IYieldGroupBase.ResourceConfig config) internal _resourcesConfig;
+
+    /// @notice Inner deposit cascade order. Set by Operator via ACM.
+    address[] internal _innerDepositQueue;
+
+    /// @notice Inner withdraw cascade order. Independent of the deposit queue.
+    address[] internal _innerWithdrawQueue;
+
+    /// @notice Optional per-resource deposit cap, in asset units. `0` = unset/unbounded
+    ///         (only the resource's protocol-level supply cap binds). When non-zero, the
+    ///         effective deposit room is `min(protocol headroom, cap − our balance)`. Only the
+    ///         generic `YieldGroup` reads / writes this; FRV leaves it `0`.
+    mapping(address resource => uint256 cap) internal _resourceCap;
+
+    /// @dev Reserved slots for future state. Shrink by the number of slots a new field
+    ///      consumes when extending.
+    uint256[39] private __gap;
+}

package/contracts/adapters/AdapterCoreV1.sol

@@ -0,0 +1,309 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
+import { IVToken } from "../interfaces/external/IVToken.sol";
+import { IComptroller } from "../interfaces/external/IComptroller.sol";
+
+/**
+ * @title AdapterCoreV1
+ * @author Venus
+ * @notice Stateless adapter for Venus Core V1 vTokens. ONE deployment serves every
+ *         YieldGroup that registers a Core V1 market — there is no per-(YieldGroup, vToken)
+ *         instance, no proxy, no clone factory.
+ * @dev Dispatch model: mutating functions (`deposit`, `withdraw`) MUST be invoked via
+ *      DELEGATECALL from a YieldGroup. They execute in the YieldGroup's storage context,
+ *      so receipt-token credits and debits land on the YieldGroup, not this adapter.
+ *      View functions are invoked via normal CALL / STATICCALL with an explicit `holder`
+ *      argument.
+ *
+ *      Storage-safety invariants enforced by this contract:
+ *      1. Zero `internal`/`private`/`public` state variables are declared. Only `immutable`
+ *         values are used.
+ *      2. No inline assembly performs `sstore`.
+ *      3. All external calls go to the supplied `resource` (vToken), its `underlying()`, or
+ *         its `comptroller()`. No arbitrary user-supplied call target.
+ *      4. {onlyDelegateCall} reverts when a mutating function is invoked directly on the
+ *         adapter, preventing accidents that would orphan vTokens here.
+ *
+ *      Treasury-fee handling: when the Comptroller's `treasuryPercent != 0`,
+ *      `redeemUnderlying(X)` delivers only `X − fee` to the caller. `withdraw` grosses up
+ *      the request via ceil-division so the YieldGroup receives at least `amount`; any
+ *      surplus remains as idle on the YieldGroup (counted in `totalAssets`).
+ *
+ *      vBNB is unsupported by design: `IVToken(resource).underlying()` reverts on vBNB,
+ *      which trips `asset()` and prevents the YieldGroup from registering it.
+ */
+contract AdapterCoreV1 is IResourceAdapter {
+    using SafeERC20 for IERC20;
+
+    // ============================== State (immutable only) ====================
+
+    /// @notice This adapter's own address, captured at deployment. Used by
+    ///         {onlyDelegateCall} to detect direct invocation. Immutables live in bytecode,
+    ///         not storage, so they're delegatecall-safe.
+    address private immutable _ADAPTER_SELF;
+
+    // ============================== State (constants) =========================
+
+    /// @notice Mantissa one used in treasury-fee math (`1e18`).
+    uint256 public constant MANTISSA_ONE = 1e18;
+
+    /// @notice Fixed-point scale matching Compound's mantissa (`1e18`).
+    uint256 public constant EXP_SCALE = 1e18;
+
+    /// @notice Scaling factor between mantissa-rate (`1e18`) and BPS (`1e4`).
+    uint256 internal constant MANTISSA_TO_BPS = 1e14;
+
+    // ============================== Errors ===================================
+
+    /// @notice A mutating function was invoked directly (not via delegatecall).
+    error NotDelegateCall();
+
+    /// @notice A vToken `mint` call returned a non-zero error code.
+    /// @param resource vToken that rejected the mint.
+    /// @param errorCode Compound-style error code returned by the vToken.
+    error VTokenMintFailed(address resource, uint256 errorCode);
+
+    /// @notice A vToken `redeemUnderlying` call returned a non-zero error code.
+    /// @param resource vToken that rejected the redeem.
+    /// @param errorCode Compound-style error code returned by the vToken.
+    error VTokenRedeemFailed(address resource, uint256 errorCode);
+
+    /// @notice A vToken `accrueInterest` call returned a non-zero error code.
+    /// @param resource vToken that failed to accrue.
+    /// @param errorCode Compound-style error code returned by the vToken.
+    error VTokenAccrueFailed(address resource, uint256 errorCode);
+
+    /**
+     * @notice A redeem succeeded but delivered less than the requested net amount. Indicates
+     *         a fee-on-transfer underlying, an unexpected treasury cut, or a vToken bug.
+     * @param resource Resource that under-delivered.
+     * @param requested Net underlying units expected.
+     * @param actual Underlying units actually received.
+     */
+    error VTokenUnderfilled(address resource, uint256 requested, uint256 actual);
+
+    /**
+     * @notice A vToken's Comptroller charges a non-zero `treasuryPercent`. That exit fee leaves
+     *         the pool on every redeem without burning shares, so it is unmodeled in the Hub's
+     *         gross NAV and would overstate PPS — rejected at registration.
+     * @param resource vToken whose Comptroller charges the fee.
+     * @param treasuryPercent Offending treasury percent (mantissa).
+     */
+    error TreasuryFeeUnsupported(address resource, uint256 treasuryPercent);
+
+    // ============================== Modifiers ================================
+
+    /// @notice Reverts {NotDelegateCall} when the call is not arriving via delegatecall.
+    /// @dev During a delegatecall, `address(this)` is the caller's address; during a direct
+    ///      call, it equals `_ADAPTER_SELF` (the address captured at construction).
+    modifier onlyDelegateCall() {
+        if (address(this) == _ADAPTER_SELF) revert NotDelegateCall();
+        _;
+    }
+
+    // ============================== Constructor ==============================
+
+    /// @notice Captures the adapter's own address into an immutable for {onlyDelegateCall}.
+    constructor() {
+        _ADAPTER_SELF = address(this);
+    }
+
+    // ============================== External — mutating =======================
+
+    /// @inheritdoc IResourceAdapter
+    function deposit(address resource, uint256 amount) external override onlyDelegateCall returns (uint256 deposited) {
+        // `address(this)` here is the YieldGroup (delegatecall context). The YieldGroup
+        // already holds `amount` of `underlying`; we just approve the vToken and mint —
+        // vTokens are credited to `msg.sender` which, from the vToken's perspective, is
+        // the YieldGroup (delegatecall preserves caller context to the next call).
+        IERC20 assetToken = IERC20(IVToken(resource).underlying());
+        SafeERC20.forceApprove(assetToken, resource, amount);
+        uint256 errCode = IVToken(resource).mint(amount);
+        if (errCode != 0) revert VTokenMintFailed(resource, errCode);
+        return amount;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function withdraw(address resource, uint256 amount, address to) external override onlyDelegateCall {
+        // `address(this)` here is the YieldGroup. `vToken.redeemUnderlying` burns its
+        // (YieldGroup's) vTokens and credits the underlying back to the YieldGroup.
+        IComptroller comptrollerContract = IComptroller(IVToken(resource).comptroller());
+        IERC20 assetToken = IERC20(IVToken(resource).underlying());
+
+        uint256 grossRedeem = _floorRedeemToOneVToken(resource, _grossUpForTreasury(comptrollerContract, amount));
+        uint256 preBal = assetToken.balanceOf(address(this));
+        uint256 errCode = IVToken(resource).redeemUnderlying(grossRedeem);
+        if (errCode != 0) revert VTokenRedeemFailed(resource, errCode);
+        uint256 received = assetToken.balanceOf(address(this)) - preBal;
+        if (received < amount) revert VTokenUnderfilled(resource, amount, received);
+
+        // Transfer exactly `amount` to `to`. Any gross-up surplus stays on the YieldGroup
+        // as idle balance — it's counted in `YieldGroup.totalAssets` and consumed on the
+        // next withdrawal's idle-first path, so dust is never socialised across YieldGroups.
+        assetToken.safeTransfer(to, amount);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Plain CALL, no `onlyDelegateCall`: `accrueInterest` mutates the vToken's own global
+    ///      index, not this caller's position, so it is safe (and cheaper) to run in the adapter's
+    ///      context. After it returns, `exchangeRateStored()` is fresh to the current block.
+    function accrue(address resource) external override {
+        uint256 errCode = IVToken(resource).accrueInterest();
+        if (errCode != 0) revert VTokenAccrueFailed(resource, errCode);
+    }
+
+    // ============================== External — view ==========================
+
+    /// @inheritdoc IResourceAdapter
+    function asset(address resource) external view override returns (address) {
+        return IVToken(resource).underlying();
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Values the position at REALIZABLE (net-of-treasury) terms so NAV/PPS equal the value the
+    ///      position can actually deliver. `withdraw` already nets the Venus treasury exit cut, so
+    ///      valuing gross here would overstate NAV and let a first-out LP exit at the pre-fee price
+    ///      while the shortfall socialises onto the last-out LP. When the Comptroller fee is off
+    ///      (every registered market today) this returns the gross value unchanged.
+    function totalAssets(address resource, address holder) external view override returns (uint256) {
+        uint256 vBal = IVToken(resource).balanceOf(holder);
+        if (vBal == 0) return 0;
+        uint256 gross = (vBal * IVToken(resource).exchangeRateStored()) / EXP_SCALE;
+
+        uint256 treasuryPct = IComptroller(IVToken(resource).comptroller()).treasuryPercent();
+        if (treasuryPct == 0) return gross;
+        // The Comptroller setter enforces `treasuryPercent < 1e18`, so the subtraction cannot underflow.
+        return (gross * (MANTISSA_ONE - treasuryPct)) / MANTISSA_ONE;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Honors Comptroller mint pause and supply cap. `supplyCap == 0` rejects mint
+    ///      outright per PolicyFacet, so we surface that as 0 capacity. The headroom math
+    ///      mirrors PolicyFacet's `nextTotalSupply = totalSupply × ER + mintAmount` check.
+    function maxDeposit(address resource) external view override returns (uint256) {
+        IComptroller comptrollerContract = IComptroller(IVToken(resource).comptroller());
+        // Action.MINT == 0 in the Venus Comptroller's enum.
+        if (comptrollerContract.actionPaused(resource, uint8(0))) return 0;
+        uint256 supplyCap = comptrollerContract.supplyCaps(resource);
+        if (supplyCap == 0) return 0;
+
+        uint256 totalSupplied = (IVToken(resource).totalSupply() * IVToken(resource).exchangeRateStored()) / EXP_SCALE;
+        uint256 raw = supplyCap > totalSupplied ? supplyCap - totalSupplied : 0;
+        // `exchangeRateStored` is pre-accrual, but Venus re-checks the supply cap at mint AFTER
+        // `accrueInterest` raises the rate, so the raw headroom is slightly optimistic on an
+        // interest-accruing near-cap market. Trim a small conservative margin so a normal accrual
+        // between this view and execution cannot push `deposit(maxDeposit())` over the cap. The
+        // routing cascade is the backstop for larger staleness (an over-cap leg is skipped, not
+        // bubbled), so this only needs to absorb a typical inter-block accrual.
+        return raw - (raw / 1000);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Three constraints: (a) what `holder` holds in the resource (vToken balance × ER),
+    ///      (b) what the vToken can pay out in cash (`getCash`), and (c) the treasury cut
+    ///      (`treasuryPercent`). The min of (a) and (b) is the gross redeemable; multiplying
+    ///      by `(1 − treasuryPct)` reflects what actually arrives at the recipient.
+    function maxWithdraw(address resource, address holder) external view override returns (uint256) {
+        IComptroller comptrollerContract = IComptroller(IVToken(resource).comptroller());
+        // Action.REDEEM == 1 in the Venus Comptroller's enum.
+        if (comptrollerContract.actionPaused(resource, uint8(1))) return 0;
+
+        uint256 vBal = IVToken(resource).balanceOf(holder);
+        if (vBal == 0) return 0;
+        uint256 exchangeRate = IVToken(resource).exchangeRateStored();
+        uint256 ourValue = (vBal * exchangeRate) / EXP_SCALE;
+        if (ourValue == 0) return 0;
+
+        uint256 cash = IVToken(resource).getCash();
+        // A redeem that would burn 0 vTokens is bumped to one whole vToken unit of underlying by
+        // `_floorRedeemToOneVToken`. If the market's cash is below that unit, every non-zero redeem
+        // the cascade could try exceeds cash and reverts in Venus `redeemFresh`. Report 0 liquidity
+        // rather than certify a withdraw the market cannot settle.
+        uint256 oneVTokenUnit = (exchangeRate + EXP_SCALE - 1) / EXP_SCALE;
+        if (cash < oneVTokenUnit) return 0;
+
+        uint256 redeemableGross = ourValue < cash ? ourValue : cash;
+        if (redeemableGross == 0) return 0;
+
+        uint256 treasuryPct = comptrollerContract.treasuryPercent();
+        if (treasuryPct == 0) return redeemableGross;
+        // The Comptroller setter enforces `treasuryPercent < 1e18`, so the subtraction cannot underflow.
+        return (redeemableGross * (MANTISSA_ONE - treasuryPct)) / MANTISSA_ONE;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function spotAPYBps(address resource, uint256 blocksPerYear) external view override returns (uint64) {
+        uint256 annualised = (IVToken(resource).supplyRatePerBlock() * blocksPerYear) / MANTISSA_TO_BPS;
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return annualised > type(uint64).max ? type(uint64).max : uint64(annualised);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function receiptBalance(address resource, address holder) external view override returns (uint256) {
+        return IVToken(resource).balanceOf(holder);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Rejects a market whose Comptroller charges a non-zero `treasuryPercent`: that exit fee
+    ///      is unmodeled in the Hub's gross NAV (see the treasury-fee note above). The withdraw
+    ///      gross-up still keeps individual redeems whole if Venus governance turns the fee on
+    ///      *after* registration; this guard only blocks registering a market that already has it.
+    function validateRegistration(address resource) external view override {
+        uint256 treasuryPct = IComptroller(IVToken(resource).comptroller()).treasuryPercent();
+        if (treasuryPct != 0) revert TreasuryFeeUnsupported(resource, treasuryPct);
+    }
+
+    // ============================== Private — view ===========================
+
+    /**
+     * @notice Gross-up a desired net delivery amount for the Comptroller's treasury cut.
+     * @dev Ceil-division ensures `received >= netAmount`; any rounding surplus stays as
+     *      idle on the YieldGroup, never on this adapter.
+     * @param comptrollerContract Comptroller to read `treasuryPercent` from.
+     * @param netAmount Underlying units the caller wants delivered.
+     * @return grossAmount Underlying units to request from `redeemUnderlying`.
+     */
+    function _grossUpForTreasury(IComptroller comptrollerContract, uint256 netAmount)
+        private
+        view
+        returns (uint256 grossAmount)
+    {
+        uint256 treasuryPct = comptrollerContract.treasuryPercent();
+        if (treasuryPct == 0) return netAmount;
+        // The Comptroller setter enforces `treasuryPercent < 1e18`, so the denominator is always non-zero.
+        uint256 denominator = MANTISSA_ONE - treasuryPct;
+        return (netAmount * MANTISSA_ONE + denominator - 1) / denominator;
+    }
+
+    /**
+     * @notice Raise a sub-one-vToken redeem up to exactly one vToken unit of underlying.
+     * @dev Compound computes `redeemTokens = floor(redeemAmount * 1e18 / exchangeRate)` and reverts
+     *      `"redeemTokens zero"` when that floors to 0. A withdraw cascade can legitimately hand this
+     *      adapter a dust `amount` — e.g. a 1-wei remainder left after an upstream ERC-4626 yieldGroup
+     *      (Flux/FRV) rounds its own redeem down — which would otherwise revert an entirely valid,
+     *      within-`maxWithdraw` withdrawal. When the requested redeem would burn 0 tokens, redeem one
+     *      whole vToken unit instead; `withdraw` then transfers exactly `amount` and leaves the
+     *      surplus idle on the YieldGroup (counted in `totalAssets`, consumed idle-first on the next
+     *      withdrawal) — identical to how the treasury gross-up surplus is handled. A no-op for
+     *      normal-sized redeems and for unit exchange rates (`amount >= 1` never floors to 0 there).
+     * @param resource vToken being redeemed from.
+     * @param grossRedeem Underlying units the caller intends to redeem.
+     * @return bumped `grossRedeem`, raised to `ceil(exchangeRate / 1e18)` only if it would burn 0 tokens.
+     */
+    function _floorRedeemToOneVToken(address resource, uint256 grossRedeem) private view returns (uint256 bumped) {
+        uint256 exchangeRate = IVToken(resource).exchangeRateStored();
+        // Venus burns `redeemTokens = floor(grossRedeem * 1e18 / exchangeRate)` and reverts when that
+        // is 0 — i.e. when `grossRedeem * 1e18 < exchangeRate`. In that case redeem exactly one vToken
+        // unit of underlying (`ceil(exchangeRate / 1e18)`) so the burn is non-zero; the caller still
+        // transfers only `amount` and leaves the surplus idle on the YieldGroup.
+        if (exchangeRate != 0 && grossRedeem * EXP_SCALE < exchangeRate) {
+            return (exchangeRate + EXP_SCALE - 1) / EXP_SCALE;
+        }
+        return grossRedeem;
+    }
+}

package/contracts/adapters/AdapterFRV.sol

@@ -0,0 +1,276 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
+
+import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
+import { IFRVVault } from "../interfaces/external/IFRVVault.sol";
+
+/**
+ * @title AdapterFRV
+ * @author Venus
+ * @notice Stateless adapter for Venus Fixed Rate Vaults (ERC-4626). ONE deployment serves
+ *         every YieldGroupFRV that registers an FRV vault — there is no per-(YieldGroup, vault)
+ *         instance, no proxy, no clone factory.
+ * @dev Dispatch model: mutating functions (`deposit`, `withdraw`) MUST be invoked via
+ *      DELEGATECALL from a YieldGroupFRV. They execute in the YieldGroup's storage context,
+ *      so ERC-4626 share credits and debits land on the YieldGroup, not this adapter.
+ *      View functions are invoked via normal CALL / STATICCALL with an explicit `holder`
+ *      argument.
+ *
+ *      Storage-safety invariants enforced by this contract:
+ *      1. Zero `internal`/`private`/`public` state variables are declared. Only `immutable`
+ *         values (and `constant`s, which live in bytecode) are used.
+ *      2. No inline assembly performs `sstore`.
+ *      3. All external calls go to the supplied `resource` (FRV vault) or its `asset()`.
+ *      4. {onlyDelegateCall} reverts when a mutating function is invoked directly on the
+ *         adapter, preventing accidents that would orphan shares here.
+ *
+ *      No treasury-fee handling: FRV takes its `reserveFactor` cut once at settlement
+ *      (`_settleProtocolShare`), not per-redeem. No gross-up needed on withdraw.
+ *
+ *      Valuation model (time-based linear accrual): a live FRV position in Lock is valued at its
+ *      principal plus the coupon accrued so far on a straight line over the lock — `principal +
+ *      netInterest * elapsed / lockDuration`, where `netInterest` is the full-term coupon net of the
+ *      vault's `reserveFactor`. The arithmetic mirrors `BaseVault` exactly so that at `elapsed ==
+ *      lockDuration` the value equals the vault's full-repayment `settlementAmount`. The Lock ->
+ *      Matured transition is therefore continuous ONLY on full repayment; on a partial / principal
+ *      shortfall the realized `settlementAmount` is lower, so the mark steps DOWN at settlement (and
+ *      a defaulting position in PendingSettlement / SettlementDeadlineExceeded is marked above its
+ *      realizable value). That over-mark is by design a forward-looking accrual; a principal shortfall
+ *      on a defaulting loan is bounded by governance's per-source cap (the Hub may additionally apply
+ *      an exit fee as anti-sandwich friction). `totalAssets` returns this accrued value directly as
+ *      the position's Hub-facing NAV.
+ *
+ *      Cap interaction: this mark rises over the lock while the coupon stays non-withdrawable
+ *      (`maxWithdraw` is 0 until the vault is terminal), so it eats into the YieldGroup's Hub-side cap
+ *      headroom over time — a group can reach or exceed its cap on accrual alone and block further
+ *      deposits / reallocation into it. Fail-closed: it only tightens capacity. See `Hub._effectiveCap`.
+ *
+ *      Basis invariant: the principal / gross slices use the vault's `+1 / +1` floored ERC-4626
+ *      conversion (`mulDiv(shares, assets + 1, supply + 1, Down)`), which is exact ONLY while the FRV
+ *      vault leaves `_decimalsOffset()` at 0 (it does, and defines no override). If a future FRV
+ *      family overrides it, this adapter must be updated in lockstep.
+ *
+ *      FRV state machine (`updateVaultState()`) is NOT called here — `YieldGroupFRV` calls
+ *      it before invoking the adapter so that state-dependent reads reflect the latest state.
+ *      The valuation is time-based, so it needs no state poke of its own; `accrue` is a no-op.
+ */
+contract AdapterFRV is IResourceAdapter {
+    using SafeERC20 for IERC20;
+
+    // ============================== State (immutable only) ====================
+
+    address private immutable _ADAPTER_SELF;
+
+    // ============================== Constants =================================
+    // Mirror `BaseVault` (BPS = 10_000, MANTISSA_ONE = 1e18, YEAR = 365 days) so the accrued value
+    // is computed on the identical basis as the vault's own interest and settlement math.
+
+    uint256 private constant BPS = 10_000;
+    uint256 private constant MANTISSA_ONE = 1e18;
+    uint256 private constant YEAR = 365 days;
+
+    // ============================== Errors ===================================
+
+    error NotDelegateCall();
+
+    // ============================== Modifiers ================================
+
+    modifier onlyDelegateCall() {
+        if (address(this) == _ADAPTER_SELF) revert NotDelegateCall();
+        _;
+    }
+
+    // ============================== Constructor ==============================
+
+    constructor() {
+        _ADAPTER_SELF = address(this);
+    }
+
+    // ============================== External — mutating =======================
+
+    /// @inheritdoc IResourceAdapter
+    function deposit(address resource, uint256 amount) external override onlyDelegateCall returns (uint256 deposited) {
+        IERC20 assetToken = IERC20(IFRVVault(resource).asset());
+        assetToken.forceApprove(resource, amount);
+        IFRVVault(resource).deposit(amount, address(this));
+        return amount;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function withdraw(address resource, uint256 amount, address to) external override onlyDelegateCall {
+        IFRVVault(resource).withdraw(amount, to, address(this));
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev No-op: the FRV valuation is time-based and computed on-demand in {totalAssets} from the
+    ///      vault's lock window, so there is no block-lazy exchange-rate state to freshen here.
+    // solhint-disable-next-line no-empty-blocks
+    function accrue(address resource) external override { }
+
+    // ============================== External — view ==========================
+
+    /// @inheritdoc IResourceAdapter
+    function asset(address resource) external view override returns (address) {
+        return IFRVVault(resource).asset();
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Position value = principal slice + accrued-coupon slice; this is the Hub-facing NAV for
+    ///      the position. See the contract NatSpec for the valuation model.
+    function totalAssets(address resource, address holder) external view override returns (uint256) {
+        (uint256 principalValue, uint256 couponValueGross) = _breakdown(resource, holder);
+        return principalValue + couponValueGross;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev FRV's `maxDeposit()` returns 0 outside Fundraising state. The receiver param
+    ///      is ignored by the FRV vault (capacity is global, not per-address).
+    ///      Pause-blind, like the vault's own `maxDeposit`; a paused vault is caught and skipped by
+    ///      the YieldGroup deposit cascade, not gated here.
+    function maxDeposit(address resource) external view override returns (uint256) {
+        return IFRVVault(resource).maxDeposit(address(this));
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev FRV's `maxWithdraw()` returns 0 outside terminal states (Matured/Failed/Liquidated).
+    ///      No treasury-fee deduction needed — FRV takes its cut at settlement, not per-redeem.
+    ///      The accrued coupon surfaced by {totalAssets} is NOT withdrawable mid-lock; this returning
+    ///      0 during Lock is what keeps the rising NAV non-deliverable until settlement.
+    ///      Pause-blind, like the vault's own `maxWithdraw` (it ignores `pauseLevel`): a completely
+    ///      paused vault is caught and skipped by the YieldGroup withdraw cascade's `try/catch`, not
+    ///      gated here.
+    function maxWithdraw(address resource, address holder) external view override returns (uint256) {
+        return IFRVVault(resource).maxWithdraw(holder);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Returns the vault's `fixedAPY` (already annualised in BPS) only while the vault is
+    ///      actually earning — `Fundraising` or `Lock`. In any other state the capital earns
+    ///      nothing (matured/idle awaiting redemption, failed, liquidated, or pre-fundraising),
+    ///      so report 0 rather than the contractual rate; otherwise dead capital would inflate
+    ///      the YieldGroup's TVL-weighted spot APY. The `blocksPerYear` parameter is unused since FRV
+    ///      yields are time-based, not block-based.
+    function spotAPYBps(
+        address resource,
+        uint256 /* blocksPerYear */
+    )
+        external
+        view
+        override
+        returns (uint64)
+    {
+        IFRVVault.FRVVaultState state = IFRVVault(resource).state();
+        if (state != IFRVVault.FRVVaultState.Fundraising && state != IFRVVault.FRVVaultState.Lock) {
+            return 0;
+        }
+        IFRVVault.FRVVaultConfig memory cfg = IFRVVault(resource).config();
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return cfg.fixedAPY > type(uint64).max ? type(uint64).max : uint64(cfg.fixedAPY);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    function receiptBalance(address resource, address holder) external view override returns (uint256) {
+        return IFRVVault(resource).balanceOf(holder);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev No-op: FRV takes its `reserveFactor` cut once at settlement, not per-redeem, so there
+    ///      is no unmodeled exit fee to guard against at registration.
+    function validateRegistration(address resource) external pure override {
+        // No FRV-specific registration precondition. `resource` validity is established by the
+        // YieldGroup's `asset()` probe and `code.length` check at registration time.
+        resource;
+    }
+
+    // ============================== Internal — view ==========================
+
+    /// @dev Split the holder's position into (principalValue, couponValueGross), both in underlying.
+    ///      Branches by lifecycle state:
+    ///        - no shares           -> (0, 0)
+    ///        - Closed              -> (0, 0)  (stuck residual; valued at 0 = deliverable value)
+    ///        - terminal (Matured / Failed / Liquidated) -> (previewRedeem(shares), 0)  (realized)
+    ///        - otherwise           -> principal slice + accrued-coupon slice
+    ///      Both slices use the vault's own +1/+1 floored ERC-4626 basis (decimalsOffset 0), so the
+    ///      principal slice equals `previewRedeem(shares)` during non-terminal states and the gross
+    ///      sum equals the post-Matured `previewRedeem` at `elapsed == lockDuration`.
+    function _breakdown(address resource, address holder)
+        internal
+        view
+        returns (uint256 principalValue, uint256 couponValueGross)
+    {
+        IFRVVault vault = IFRVVault(resource);
+        uint256 shares = vault.balanceOf(holder);
+        if (shares == 0) return (0, 0);
+
+        IFRVVault.FRVVaultRuntime memory rt = vault.runtime();
+        IFRVVault.FRVVaultState state = rt.state;
+
+        // Closed is not loss-adjusted by the vault (its `totalAssets()` resurrects `totalRaised`),
+        // yet the position is non-withdrawable — value it at 0 so reported NAV == deliverable value.
+        if (state == IFRVVault.FRVVaultState.Closed) return (0, 0);
+
+        // Terminal states have settled to a realized `settlementAmount`; `previewRedeem` is the
+        // deliverable value (can be below principal on a loss). No unrealized coupon remains.
+        if (
+            state == IFRVVault.FRVVaultState.Matured || state == IFRVVault.FRVVaultState.Failed
+                || state == IFRVVault.FRVVaultState.Liquidated
+        ) {
+            return (vault.previewRedeem(shares), 0);
+        }
+
+        uint256 supply = vault.totalSupply();
+        if (supply == 0) return (0, 0); // defensive; a holder with shares implies supply > 0
+
+        // Principal slice on the vault's own +1/+1 floored basis. During Lock the vault reports
+        // `totalAssets() == totalRaised`, so this equals `previewRedeem(shares)` exactly.
+        principalValue = Math.mulDiv(shares, rt.totalRaised + 1, supply + 1, Math.Rounding.Down);
+
+        uint256 accruedTotalAssets = _accruedTotalAssets(vault, rt);
+        // accruedTotalAssets >= totalRaised, so grossValue >= principalValue (mulDiv is monotonic).
+        uint256 grossValue = Math.mulDiv(shares, accruedTotalAssets + 1, supply + 1, Math.Rounding.Down);
+        couponValueGross = grossValue - principalValue;
+    }
+
+    /// @dev Vault-wide accrued total assets used to price the holder's slice. Returns flat
+    ///      `totalRaised` (no coupon) except while the vault is in Lock / PendingSettlement /
+    ///      SettlementDeadlineExceeded, where the coupon accrues on lock state alone:
+    ///        - Lock: principal + netInterest * clamp(now - lockStartTime, 0, lockDuration) / lockDuration
+    ///        - PendingSettlement / SettlementDeadlineExceeded: principal + full netInterest (term is
+    ///          over; held flat into settlement so there is no Lock-end cliff back to principal)
+    ///      Accrual deliberately does NOT key on `fundsWithdrawn`. The vault stamps `lockStartTime` at
+    ///      fundraising close and owes interest over the whole lock window regardless of when, or
+    ///      whether, the institution draws the principal. Gating the mark on the draw would (a)
+    ///      under-mark a locked position versus the vault's own settlement and (b) make the mark jump
+    ///      in the single transaction that flips `fundsWithdrawn` — a sandwichable NAV discontinuity,
+    ///      since `lockStartTime` (and therefore `elapsed`) is unchanged by the draw. Keying on lock
+    ///      state alone keeps the mark continuous from `lockStartTime`.
+    ///      `netInterest` mirrors `BaseVault`: full-term interest then the reserve fee floored and
+    ///      subtracted (NOT `interest * (1 - reserveFactor)`, which rounds differently).
+    function _accruedTotalAssets(IFRVVault vault, IFRVVault.FRVVaultRuntime memory rt) internal view returns (uint256) {
+        bool isLock = rt.state == IFRVVault.FRVVaultState.Lock;
+        bool isPostTerm = rt.state == IFRVVault.FRVVaultState.PendingSettlement
+            || rt.state == IFRVVault.FRVVaultState.SettlementDeadlineExceeded;
+        if (!isLock && !isPostTerm) return rt.totalRaised;
+
+        IFRVVault.FRVVaultConfig memory cfg = vault.config();
+        uint256 lockDuration = cfg.lockDuration;
+        if (lockDuration == 0) return rt.totalRaised; // defensive; config enforces non-zero
+
+        uint256 totalInterest = (rt.totalRaised * cfg.fixedAPY * lockDuration) / (BPS * YEAR);
+        // `reserveFactor <= MANTISSA_ONE` is enforced by the FRV vault controller at config time, so
+        // the fee never exceeds `totalInterest` and this subtraction cannot underflow.
+        uint256 netInterest = totalInterest - (totalInterest * cfg.reserveFactor) / MANTISSA_ONE;
+
+        uint256 elapsed = lockDuration;
+        if (isLock) {
+            uint256 raw = block.timestamp > rt.lockStartTime ? block.timestamp - rt.lockStartTime : 0;
+            elapsed = raw < lockDuration ? raw : lockDuration;
+        }
+
+        return rt.totalRaised + (netInterest * elapsed) / lockDuration;
+    }
+}