@venusprotocol/liquidity-hub 0.0.0

package/contracts/interfaces/IMigrator.sol

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IMigrator
+ * @author Venus
+ * @notice One-click migration from an existing Venus Core position into a Liquidity Hub. In a
+ *         single atomic transaction the Migrator pulls a user's Core vToken, redeems it to the
+ *         underlying, and deposits that into the matching Hub, minting share tokens to `receiver`.
+ * @dev A single immutable, permissionless deployment serves every registered Hub — the target is
+ *      chosen per call via the `hub` argument and must be present in the HubRegistry, so a migration
+ *      can only ever land in a governance-registered Hub. Two paths exist because Venus splits its
+ *      markets by asset type:
+ *      ERC-20-backed markets (vUSDT, vUSDC, ...) go through {migrateFromCore}; the native market
+ *      (vBNB) redeems raw BNB and so has the dedicated {migrateFromCoreBNB} path that wraps to WBNB
+ *      before depositing into the WBNB Hub.
+ */
+interface IMigrator {
+    /**
+     * @notice Emitted on a completed migration.
+     * @param user The caller whose Core position was migrated.
+     * @param vToken The Core market the position was redeemed from (the WBNB path reports vBNB).
+     * @param hub The Hub the underlying was deposited into.
+     * @param vTokenAmount vToken receipts pulled from `user` and redeemed.
+     * @param underlying Underlying (or wrapped-native) amount deposited into the Hub.
+     * @param shares Hub shares minted to the receiver.
+     */
+    event Migrated(
+        address indexed user,
+        address indexed vToken,
+        address indexed hub,
+        uint256 vTokenAmount,
+        uint256 underlying,
+        uint256 shares
+    );
+
+    /// @notice A required address argument was the zero address.
+    error ZeroAddress();
+    /// @notice A required amount argument was zero.
+    error ZeroAmount();
+    /// @notice The target `hub` is not a governance-registered Hub in the HubRegistry.
+    error HubNotRegistered(address hub);
+    /// @notice The vToken's underlying does not match the Hub's asset.
+    error AssetMismatch(address vTokenUnderlying, address hubAsset);
+    /// @notice The Core market returned a non-zero (failure) error code on redeem.
+    error VTokenRedeemFailed(address vToken, uint256 errorCode);
+    /// @notice The redeem produced no underlying for the Migrator to deposit.
+    error NothingReceived();
+    /// @notice The minted shares were below the caller's `minShares` floor.
+    error InsufficientShares(uint256 shares, uint256 minShares);
+    /// @notice Native value was received from an address other than the configured vBNB market.
+    error OnlyVBNB();
+
+    /**
+     * @notice Migrate an ERC-20-backed Core position into its Hub.
+     * @dev Caller must first `approve` this Migrator to transfer `vTokenAmount` of `vToken`.
+     *      Reverts unless `IVBep20(vToken).underlying() == IHub(hub).asset()` and the resulting
+     *      `shares >= minShares`. Use the WBNB path for vBNB. This is the no-consent path — use
+     *      {migrateFromCoreWithConsent} to record the user's disclaimer consent.
+     * @param vToken The Core market to redeem from (e.g. vUSDT).
+     * @param vTokenAmount vToken receipts to pull and redeem.
+     * @param hub The Hub to deposit the redeemed underlying into.
+     * @param receiver Recipient of the minted Hub shares.
+     * @param minShares Minimum acceptable minted shares (slippage guard).
+     * @return shares Hub shares minted to `receiver`.
+     */
+    function migrateFromCore(address vToken, uint256 vTokenAmount, address hub, address receiver, uint256 minShares)
+        external
+        returns (uint256 shares);
+
+    /**
+     * @notice Migrate an ERC-20-backed Core position into its Hub and optionally record the migrating
+     *         user's disclaimer consent on-chain in the same transaction.
+     * @dev Identical to {migrateFromCore} plus a consent record. The record is attributed to
+     *      `msg.sender` (the migrating user, who calls this Migrator directly), so it is correct even
+     *      though the Hub deposit is intermediated. Emitted before any state change, so it is rolled
+     *      back with the transaction if a later leg reverts. The hash is optional — passing
+     *      `bytes32(0)` skips the emit and migrates without recording.
+     * @param vToken The Core market to redeem from (e.g. vUSDT).
+     * @param vTokenAmount vToken receipts to pull and redeem.
+     * @param hub The Hub to deposit the redeemed underlying into.
+     * @param receiver Recipient of the minted Hub shares.
+     * @param minShares Minimum acceptable minted shares (slippage guard).
+     * @param consentHash keccak256 hash of the disclaimer content the user consented to;
+     *        `bytes32(0)` skips recording (no event emitted).
+     * @return shares Hub shares minted to `receiver`.
+     */
+    function migrateFromCoreWithConsent(
+        address vToken,
+        uint256 vTokenAmount,
+        address hub,
+        address receiver,
+        uint256 minShares,
+        bytes32 consentHash
+    ) external returns (uint256 shares);
+
+    /**
+     * @notice Migrate a native vBNB position into the WBNB Hub.
+     * @dev Caller must first `approve` this Migrator to transfer `vBNBAmount` of the configured
+     *      vBNB market. The redeemed BNB is wrapped to WBNB before deposit. Reverts unless `hub` is a
+     *      registered WBNB Hub (`IHub(hub).asset() == WBNB`) and `shares >= minShares`.
+     *      This is the no-consent path — use {migrateFromCoreBNBWithConsent} to record consent.
+     * @param vBNBAmount vBNB receipts to pull and redeem.
+     * @param hub The WBNB Hub to deposit into.
+     * @param receiver Recipient of the minted Hub shares.
+     * @param minShares Minimum acceptable minted shares (slippage guard).
+     * @return shares Hub shares minted to `receiver`.
+     */
+    function migrateFromCoreBNB(uint256 vBNBAmount, address hub, address receiver, uint256 minShares)
+        external
+        returns (uint256 shares);
+
+    /**
+     * @notice Migrate a native vBNB position into the WBNB Hub and optionally record the migrating
+     *         user's disclaimer consent on-chain in the same transaction.
+     * @dev Identical to {migrateFromCoreBNB} plus a consent record attributed to `msg.sender` (the
+     *      migrating user), emitted before any state change. The hash is optional — passing
+     *      `bytes32(0)` skips the emit and migrates without recording.
+     * @param vBNBAmount vBNB receipts to pull and redeem.
+     * @param hub The WBNB Hub to deposit into.
+     * @param receiver Recipient of the minted Hub shares.
+     * @param minShares Minimum acceptable minted shares (slippage guard).
+     * @param consentHash keccak256 hash of the disclaimer content the user consented to;
+     *        `bytes32(0)` skips recording (no event emitted).
+     * @return shares Hub shares minted to `receiver`.
+     */
+    function migrateFromCoreBNBWithConsent(
+        uint256 vBNBAmount,
+        address hub,
+        address receiver,
+        uint256 minShares,
+        bytes32 consentHash
+    ) external returns (uint256 shares);
+}

package/contracts/interfaces/IResourceAdapter.sol

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IResourceAdapter
+ * @author Venus
+ * @notice Boundary between a `YieldGroup` and a specific yield-protocol ABI (e.g. Compound-
+ *         style vTokens for Core V1, a different shape for Core V2, Fluid for Flux, etc.).
+ *         A single deployment of each implementation is shared across every YieldGroup that
+ *         registers a resource of the matching protocol family.
+ * @dev Dispatch model — load-bearing for security review:
+ *      - **Mutating functions (`deposit`, `withdraw`) MUST be invoked via DELEGATECALL** from
+ *        the YieldGroup. They execute in the YieldGroup's storage context so that
+ *        receipt-token credits and debits land on the YieldGroup, not the adapter. Adapter
+ *        implementations enforce this with an `address(this) != _ADAPTER_SELF` guard.
+ *      - **View functions are invoked via normal CALL / STATICCALL.** They take an explicit
+ *        `holder` parameter (the YieldGroup) where their answer depends on whose position is
+ *        being queried.
+ *      - **`accrue` is invoked via normal CALL** (not delegatecall). It settles the resource's
+ *        own global interest state and credits nothing to the holder, so it needs neither the
+ *        YieldGroup's storage context nor an `onlyDelegateCall` guard.
+ *
+ *      Adapter implementation invariants (required of every adapter; enforced in-code):
+ *      1. The contract declares zero storage variables; only `immutable` values are
+ *         permitted (immutables live in bytecode, not storage slots, so they're safe across
+ *         delegatecall).
+ *      2. No inline assembly performs `sstore`.
+ *      3. External calls go only to (a) the supplied `resource`, (b) addresses the resource
+ *         itself reports — its asset (`underlying()` on a vToken, `asset()` on an ERC-4626
+ *         resource) and, where applicable, its `comptroller()` — and (c) trusted, chain-fixed
+ *         addresses captured as immutables at construction (e.g. AdapterFlux's `LENDING_RESOLVER`,
+ *         read-only). Never an arbitrary user-supplied address. The exact target set is
+ *         per-adapter; see each implementation's NatSpec for its list.
+ *      4. Mutating functions revert when called outside a delegatecall context, preventing
+ *         accidental direct invocation that would orphan receipt tokens on the adapter.
+ */
+interface IResourceAdapter {
+    // -------------------------------- Mutating -------------------------------
+
+    /**
+     * @notice Deposit `amount` of the resource's underlying into `resource`.
+     * @dev MUST be delegatecalled from the YieldGroup. Pre-conditions:
+     *      - The YieldGroup already holds `amount` of `underlying` (transferred in by the
+     *        caller of `YieldGroup.deposit`).
+     *      Post-conditions:
+     *      - Receipt tokens (e.g. vTokens) are credited to the YieldGroup.
+     *      - The full `amount` of `underlying` leaves the YieldGroup into `resource` (under
+     *        delegatecall the code runs in the YieldGroup's context, so the adapter contract
+     *        itself never custodies funds).
+     * @param resource Underlying yield protocol address (e.g. a Venus vToken).
+     * @param amount Underlying units to deposit.
+     * @return deposited Actual amount placed; equals `amount` on success.
+     */
+    function deposit(address resource, uint256 amount) external returns (uint256 deposited);
+
+    /**
+     * @notice Redeem exactly `amount` of underlying from `resource` and deliver it to `to`.
+     * @dev MUST be delegatecalled from the YieldGroup. Pre-conditions:
+     *      - The YieldGroup holds enough receipt tokens to back the redeem.
+     *      Post-conditions:
+     *      - `to` receives exactly `amount` of underlying.
+     *      - Some adapters redeem slightly more than `amount` and leave the excess as idle on
+     *        the YieldGroup (e.g. AdapterCoreV1's treasury-fee gross-up and its sub-one-vToken
+     *        dust bump). Such surplus is counted in `totalAssets` and consumed idle-first on the
+     *        next call. Fee-free adapters (Flux, FRV) leave no surplus.
+     * @param resource Underlying yield protocol address.
+     * @param amount Net underlying units to deliver to `to`.
+     * @param to Recipient of the underlying.
+     */
+    function withdraw(address resource, uint256 amount, address to) external;
+
+    /**
+     * @notice Settle `resource`'s accrued interest up to the current block, so a subsequent
+     *         {totalAssets} read values the position at a fresh exchange rate rather than a
+     *         one-cycle-stale one.
+     * @dev Invoked via normal CALL (not delegatecall): it mutates the resource's own global
+     *      interest state, not the holder's position, so receipt tokens never move. Only
+     *      block-lazy adapters do real work here — Core pokes the vToken's `accrueInterest`;
+     *      Flux and FRV implement it as a no-op (their NAV is not a block-lazy exchange rate).
+     * @param resource Underlying yield protocol address to settle interest on.
+     */
+    function accrue(address resource) external;
+
+    // ---------------------------------- Views --------------------------------
+
+    /**
+     * @notice The ERC-20 underlying accepted by `resource`. YieldGroup uses this to validate
+     *         that a resource's asset matches its own at registration time.
+     * @param resource Underlying yield protocol address.
+     * @return underlying Address of the asset token.
+     */
+    function asset(address resource) external view returns (address underlying);
+
+    /**
+     * @notice Underlying value held by `holder` via `resource`, using stale (non-accruing)
+     *         exchange-rate state. Cheap; safe to call from Hub-level totalAssets aggregation.
+     * @param resource Underlying yield protocol address.
+     * @param holder Address whose position to value (the YieldGroup).
+     * @return value Underlying units `holder` holds via this resource.
+     */
+    function totalAssets(address resource, address holder) external view returns (uint256 value);
+
+    /**
+     * @notice Spare deposit headroom on `resource` right now (capacity remaining before the
+     *         resource rejects mint via its own caps or pause).
+     * @param resource Underlying yield protocol address.
+     * @return capacity Underlying units a holder can still place into this resource.
+     */
+    function maxDeposit(address resource) external view returns (uint256 capacity);
+
+    /**
+     * @notice Underlying that `holder` can withdraw from `resource` right now, NET of any
+     *         protocol fees that will be taken on redeem. Bounded by the lesser of `holder`'s
+     *         position value and the resource's available cash.
+     * @param resource Underlying yield protocol address.
+     * @param holder Address whose position to query (the YieldGroup).
+     * @return liquid Underlying units deliverable to a recipient on a redeem call.
+     */
+    function maxWithdraw(address resource, address holder) external view returns (uint256 liquid);
+
+    /**
+     * @notice Spot supply-side APY for `resource` in BPS.
+     * @dev `blocksPerYear` is consumed only by block-rate adapters (e.g. Core annualises a
+     *      per-block supply rate with it). Adapters whose yieldGroup is already annualised — Flux
+     *      (Fluid APR) and FRV (time-based fixed APY) — ignore the parameter.
+     * @param resource Underlying yield protocol address.
+     * @param blocksPerYear Per-chain block cadence (chain-dependent; ~10_512_000 on BNB Chain);
+     *        used only by block-rate adapters, ignored by the rest.
+     * @return apyBps Spot APY in basis points (capped at `uint64.max`).
+     */
+    function spotAPYBps(address resource, uint256 blocksPerYear) external view returns (uint64 apyBps);
+
+    /**
+     * @notice Raw receipt-token balance `holder` owns via `resource` (vToken / fToken / FRV
+     *         shares), in receipt-token units — NOT underlying value.
+     * @dev Used by `YieldGroup.removeResource` as a share-based emptiness gate. A value-based
+     *      check (`totalAssets`) rounds a small-but-non-zero receipt balance down to 0, which
+     *      would let removal orphan those receipt tokens; reading the raw balance closes that gap.
+     * @param resource Underlying yield protocol address.
+     * @param holder Address whose receipt balance to read (the YieldGroup).
+     * @return shares Receipt-token units `holder` holds in this resource.
+     */
+    function receiptBalance(address resource, address holder) external view returns (uint256 shares);
+
+    /**
+     * @notice Revert if `resource` fails a protocol-specific precondition for registration.
+     * @dev Called by `YieldGroup.addResource`. AdapterCoreV1 rejects a vToken whose 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 must not be
+     *      registered. FRV and Flux have no per-redeem pool fee and implement this as a no-op.
+     * @param resource Underlying yield protocol address being registered.
+     */
+    function validateRegistration(address resource) external view;
+}

package/contracts/interfaces/IYieldGroup.sol

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IYieldGroupBase } from "./IYieldGroupBase.sol";
+
+/**
+ * @title IYieldGroup
+ * @author Venus
+ * @notice External interface for the generic `YieldGroup` — the concrete router shared by the
+ *         synchronous families (Core vTokens, Fluid fTokens). "Core" vs "Flux" is a deployment
+ *         identity (which adapter + resources + cap + `blocksPerYear` are wired into the proxy),
+ *         not a separate contract.
+ * @dev Extends `IYieldGroupBase` (the Hub-facing surface + the shared registry / queue / pause
+ *      machinery) with the per-resource deposit cap and the `blocksPerYear` annualiser. Lifecycle
+ *      families with no cap (FRV) implement `IYieldGroupFRV` instead. Conventions:
+ *      - Mutating admin calls are ACM-gated. The intended split is asymmetric: governance can both
+ *        loosen and tighten; the Operator can only tighten (pause, lower a cap, reorder a queue) —
+ *        never loosen (unpause, raise, register). This asymmetry is enforced purely by which
+ *        addresses governance grants each ACM role to, not by a hard-coded branch in the contract.
+ *      - `deposit` / `withdraw` are `onlyHub`-gated; nothing else can move funds.
+ */
+interface IYieldGroup is IYieldGroupBase {
+    // -------------------------------- Events ----------------------------------
+
+    /**
+     * @notice A resource's optional per-resource deposit cap was raised (loosened).
+     * @param resource Resource whose cap changed.
+     * @param newCap New cap in asset units (`0` = unbounded; protocol cap is the only limit).
+     */
+    event ResourceCapRaised(address indexed resource, uint256 newCap);
+
+    /**
+     * @notice A resource's optional per-resource deposit cap was lowered (tightened).
+     * @param resource Resource whose cap changed.
+     * @param newCap New cap in asset units (`0` = unbounded; protocol cap is the only limit).
+     */
+    event ResourceCapLowered(address indexed resource, uint256 newCap);
+
+    /**
+     * @notice The `blocksPerYear` annualiser was updated by governance.
+     * @param oldBlocksPerYear Previous value.
+     * @param newBlocksPerYear New value.
+     */
+    event BlocksPerYearSet(uint256 oldBlocksPerYear, uint256 newBlocksPerYear);
+
+    // -------------------------------- Errors ----------------------------------
+
+    /// @notice `raiseResourceCap` called with a value not strictly looser than the current cap
+    ///         (recall `0` = unbounded, so raising to `0` removes the cap entirely).
+    error NotIncreasing();
+
+    /// @notice `lowerResourceCap` called with a value not strictly tighter than the current cap.
+    error NotDecreasing();
+
+    // ----------------------- 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 blocksPerYear_ Per-chain block cadence used only to annualise spot APY. Pass the
+     *        chain's value for block-rate families (Core, ~10_512_000 on BNB Chain at 3s/block) and
+     *        `0` for families whose adapter pre-annualises and ignores it (Flux).
+     * @param acm_ AccessControlManagerV8 gating governance calls.
+     */
+    function initialize(address hub_, address asset_, uint256 blocksPerYear_, address acm_) external;
+
+    // ----------------------- Resource caps (asymmetric) ----------------------
+
+    /**
+     * @notice Raise (or remove) the optional per-resource deposit cap. This caps how much
+     *         underlying THIS YieldGroup may hold in `resource`, independent of the resource's
+     *         own protocol-level supply cap. The effective deposit room is always
+     *         `min(protocol headroom, this cap − our balance)`.
+     * @dev ACM role `"raiseResourceCap(address,uint256)"` (Guardian or VIP) — raising a cap is loosening.
+     *      `newCap` must be strictly looser than the current cap, where `0` means unbounded
+     *      (so raising to `0` removes the cap). Emits {ResourceCapRaised}.
+     * @param resource Registered resource whose cap is being raised.
+     * @param newCap New cap in asset units (`0` = unbounded).
+     */
+    function raiseResourceCap(address resource, uint256 newCap) external;
+
+    /**
+     * @notice Lower the optional per-resource deposit cap (tighten). Lowering below the
+     *         current balance simply stops new deposits into `resource`; it never forces a
+     *         withdrawal, mirroring `lowerYieldGroupCap` at the Hub.
+     * @dev ACM role `"lowerResourceCap(address,uint256)"` (Operator or VIP) — lowering is
+     *      tightening. `newCap` must be strictly tighter than the current cap (recall `0` =
+     *      unbounded), and cannot be `0`. Emits {ResourceCapLowered}.
+     * @param resource Registered resource whose cap is being lowered.
+     * @param newCap New cap in asset units (must be non-zero and below the current effective cap).
+     */
+    function lowerResourceCap(address resource, uint256 newCap) external;
+
+    // ----------------------- Blocks per year (governance) --------------------
+
+    /**
+     * @notice Update the per-chain `blocksPerYear` annualiser read by `spotAPYBps`. Purely cosmetic:
+     *         it scales only the reported spot APY and never share pricing, routing, caps, or
+     *         fees. Intended for the rare chain block-time change, applied per YieldGroup.
+     * @dev ACM role `"setBlocksPerYear(uint256)"` (VIP). Accepts any value, including `0` (the Flux
+     *      sentinel, whose adapter pre-annualises and ignores it). Emits {BlocksPerYearSet}.
+     * @param newBlocksPerYear New blocks-per-year value for the deployment chain.
+     */
+    function setBlocksPerYear(uint256 newBlocksPerYear) external;
+
+    // --------------------------------- Views ---------------------------------
+
+    /// @notice The constant used to annualise per-block supply rates.
+    /// @return blocks Number of blocks per year on the deployment chain (`0` if unused).
+    function blocksPerYear() external view returns (uint256 blocks);
+
+    /**
+     * @notice The optional per-resource deposit cap set by governance / Operator.
+     * @param resource Address to look up.
+     * @return cap Cap in asset units; `0` means unbounded (only the protocol cap binds).
+     */
+    function resourceCap(address resource) external view returns (uint256 cap);
+}