@venusprotocol/liquidity-hub 2.1.0-dev.4 → 2.1.0-dev.5

package/contracts/lens/HubLens.sol

@@ -0,0 +1,311 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+import { IHub } from "../interfaces/IHub.sol";
+import { IHubLens } from "../interfaces/IHubLens.sol";
+import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
+import { IYieldGroupBase } from "../interfaces/IYieldGroupBase.sol";
+import { IFRVVault } from "../interfaces/external/IFRVVault.sol";
+import { HubCapacityMath } from "./HubCapacityMath.sol";
+
+/**
+ * @title HubLens
+ * @author Venus
+ * @notice Off-chain read surface for the {Hub}: deposit capacity and blended yield.
+ * @dev Stateless and immutable — no storage, no owner, no initializer, no proxy. The Hub is a call
+ *      parameter rather than a stored address, so a single deployment serves `Hub_U`, `Hub_USDC`,
+ *      `Hub_USDT` and every Hub added later. Nothing on the Hub points at this contract, so a new
+ *      version is deployed rather than upgraded.
+ *
+ *      Quantity views fail open per YieldGroup, mirroring the cascade: a YieldGroup whose
+ *      `maxDeposit()` or `spotAPYBps()` reverts contributes 0 rather than bricking the whole view.
+ *      NAV fails closed, inherited rather than re-implemented — every function here reads
+ *      `Hub.totalAssets()`, which deliberately does NOT isolate a YieldGroup whose `totalAssets()`
+ *      reverts, because a capacity or yield figure computed against a wrong NAV is worse than no
+ *      figure at all.
+ */
+contract HubLens is IHubLens {
+    /// @dev Accrual margin trimmed off each YieldGroup's room: `balance / 10_000`, i.e. 0.01%. Sized
+    ///      on the balance, not on the room, because the interest a deposit settles scales with what
+    ///      the group holds. 0.01% is about nine hours of interest at 10% APY, against a mark that
+    ///      goes stale only between two accruals of the venue behind it.
+    uint256 private constant ACCRUAL_MARGIN_DIVISOR = 10_000;
+
+    /// @dev ABI size of `IFRVVault.config()`: nine static words. Anything else is not an FRV vault.
+    uint256 private constant FRV_CONFIG_SIZE = 9 * 32;
+
+    /// @inheritdoc IHubLens
+    function maxDeposit(address hub) public view override returns (uint256 assets) {
+        if (IHub(hub).hubPaused()) return 0;
+        (address[] memory yieldGroups, HubCapacityMath.GroupInput[] memory groups, uint256 hubTotalAssets) =
+            _readDepositQueue(hub);
+        (HubCapacityMath.ResourceFloor[][] memory floors, bool floored) = _readFloors(yieldGroups);
+        if (floored) {
+            (assets,,) = _routable(hub, groups, floors, hubTotalAssets, false);
+        } else {
+            (assets,) = HubCapacityMath.trimmedCapacity(groups, hubTotalAssets, ACCRUAL_MARGIN_DIVISOR);
+        }
+    }
+
+    /// @inheritdoc IHubLens
+    /// @dev Trimmed a second time: the interest the deposit settles also raises the share price it
+    ///      prices the mint at, so these shares convert to more assets than they do here.
+    function maxMint(address hub) external view override returns (uint256 shares) {
+        if (IHub(hub).hubPaused()) return 0;
+        (address[] memory yieldGroups, HubCapacityMath.GroupInput[] memory groups, uint256 hubTotalAssets) =
+            _readDepositQueue(hub);
+        (HubCapacityMath.ResourceFloor[][] memory floors, bool floored) = _readFloors(yieldGroups);
+        if (floored) {
+            (shares,,) = _routable(hub, groups, floors, hubTotalAssets, true);
+            return shares;
+        }
+
+        uint256 budget = HubCapacityMath.doubleTrimmedCapacity(groups, hubTotalAssets, ACCRUAL_MARGIN_DIVISOR);
+
+        // `mint` charges `previewMint`, which rounds the assets back up, but no give-back is owed:
+        // the floor here already sheds more than that round-up asks for, so `previewMint(shares)`
+        // never passes `budget`. Both directions price off the same supply and assets.
+        shares = IHub(hub).convertToShares(budget);
+    }
+
+    /// @inheritdoc IHubLens
+    function depositCapacityBreakdown(address hub)
+        external
+        view
+        override
+        returns (address[] memory groups, uint256[] memory room)
+    {
+        if (IHub(hub).hubPaused()) return (groups, room);
+        HubCapacityMath.GroupInput[] memory inputs;
+        uint256 hubTotalAssets;
+        (groups, inputs, hubTotalAssets) = _readDepositQueue(hub);
+
+        // Split at the trimmed total, not the untrimmed one: the caps shrink with the deposit, so
+        // rooms solved for the untrimmed figure overstate the percentage-bound groups.
+        (HubCapacityMath.ResourceFloor[][] memory floors, bool floored) = _readFloors(groups);
+        if (floored) {
+            (,, room) = _routable(hub, inputs, floors, hubTotalAssets, false);
+        } else {
+            (, room) = HubCapacityMath.trimmedCapacity(inputs, hubTotalAssets, ACCRUAL_MARGIN_DIVISOR);
+        }
+    }
+
+    /// @inheritdoc IHubLens
+    function spotAPYBps(address hub) external view override returns (uint64 apyBps) {
+        // Read first: this is `Σ YieldGroup.totalAssets()` plus Hub idle, and it reverts if any
+        // registered YieldGroup cannot be valued — the same list this loop walks, so a per-group
+        // guard below would never fire.
+        uint256 hubTotalAssets = IHub(hub).totalAssets();
+        if (hubTotalAssets == 0) return 0;
+
+        address[] memory yieldGroups = IHub(hub).registeredYieldGroups();
+        uint256 weighted;
+
+        for (uint256 i; i < yieldGroups.length; ++i) {
+            address yieldGroup = yieldGroups[i];
+
+            // Weight by the invested part alone. A YieldGroup averages its rate over its
+            // resources, while its `totalAssets()` also counts asset sitting on the YieldGroup
+            // itself, which earns nothing: weighting by the total would pay that idle the rate.
+            uint256 balance = IYieldGroupBase(yieldGroup).totalAssets();
+            uint256 idle = IERC20(IYieldGroupBase(yieldGroup).asset()).balanceOf(yieldGroup);
+            uint256 invested = balance > idle ? balance - idle : 0;
+            if (invested == 0) continue;
+
+            try IYieldGroupBase(yieldGroup).spotAPYBps() returns (uint64 v) {
+                weighted += uint256(v) * invested;
+            } catch {
+                continue;
+            }
+        }
+
+        // Denominator is the Hub's whole TVL, not the sum of the balances weighted above, so Hub
+        // idle and any skipped YieldGroup dilute the figure at 0% instead of vanishing from it.
+        uint256 blended = weighted / hubTotalAssets;
+        return blended > type(uint64).max ? type(uint64).max : uint64(blended);
+    }
+
+    // ============================== Private =================================
+
+    /**
+     * @dev The largest trimmed figure the Hub routes in full when a YieldGroup has floored
+     *      resources. `YieldGroupBase.maxDeposit()` checks each floor against the resource's own
+     *      room, but the Hub cap and the inner queue can shrink the leg afterwards, so the solve's
+     *      figure can land under a floor and revert. Offer the solve each floored YieldGroup's
+     *      room candidates, largest first, and keep the first figure whose dry run routes in full.
+     *      A failed dry run steps down the first YieldGroup that skipped part of its leg.
+     * @return amount Assets, or shares when `forMint`.
+     * @return assets Assets the Hub would route: `amount`, or `previewMint(amount)`.
+     * @return placed Per-YieldGroup amount placed by that routing.
+     */
+    function _routable(
+        address hub,
+        HubCapacityMath.GroupInput[] memory groups,
+        HubCapacityMath.ResourceFloor[][] memory floors,
+        uint256 hubTotalAssets,
+        bool forMint
+    ) private view returns (uint256 amount, uint256 assets, uint256[] memory placed) {
+        uint256 n = groups.length;
+        HubCapacityMath.GroupInput[] memory offered = new HubCapacityMath.GroupInput[](n);
+        uint256[][] memory candidates = new uint256[][](n);
+        uint256[] memory pick = new uint256[](n);
+        uint256 tries = 1;
+
+        for (uint256 i; i < n; ++i) {
+            HubCapacityMath.GroupInput memory g = groups[i];
+            offered[i] = HubCapacityMath.GroupInput({
+                balance: g.balance,
+                venueRoom: g.venueRoom,
+                absoluteCap: g.absoluteCap,
+                percentageCapBps: g.percentageCapBps
+            });
+            if (floors[i].length != 0) {
+                candidates[i] = HubCapacityMath.roomCandidates(floors[i], g.venueRoom);
+                offered[i].venueRoom = candidates[i][0];
+                tries += candidates[i].length;
+            }
+        }
+
+        for (uint256 t; t < tries; ++t) {
+            if (forMint) {
+                uint256 budget = HubCapacityMath.doubleTrimmedCapacity(offered, hubTotalAssets, ACCRUAL_MARGIN_DIVISOR);
+                amount = IHub(hub).convertToShares(budget);
+                assets = IHub(hub).previewMint(amount);
+            } else {
+                (amount,) = HubCapacityMath.trimmedCapacity(offered, hubTotalAssets, ACCRUAL_MARGIN_DIVISOR);
+                assets = amount;
+            }
+
+            uint256 left;
+            bool[] memory short;
+            (left, placed, short) = HubCapacityMath.route(groups, floors, hubTotalAssets, assets);
+            if (left == 0) return (amount, assets, placed);
+
+            uint256 i;
+            while (i < n && !(short[i] && pick[i] + 1 < candidates[i].length)) ++i;
+            if (i == n) break;
+            offered[i].venueRoom = candidates[i][++pick[i]];
+        }
+
+        return (0, 0, new uint256[](n));
+    }
+
+    /// @dev Per YieldGroup, its unpaused inner deposit-queue resources with their room and floor,
+    ///      or empty when none has a floor. `floored` is true when any YieldGroup has one. Room is
+    ///      the adapter's raw `maxDeposit`, which is what `YieldGroupFRV` deposits against.
+    function _readFloors(address[] memory groups)
+        private
+        view
+        returns (HubCapacityMath.ResourceFloor[][] memory floors, bool floored)
+    {
+        floors = new HubCapacityMath.ResourceFloor[][](groups.length);
+        for (uint256 i; i < groups.length; ++i) {
+            floors[i] = _readGroupFloors(groups[i]);
+            if (floors[i].length != 0) floored = true;
+        }
+    }
+
+    function _readGroupFloors(address yieldGroup) private view returns (HubCapacityMath.ResourceFloor[] memory floors) {
+        address[] memory queue;
+        try IYieldGroupBase(yieldGroup).innerDepositQueue() returns (address[] memory q) {
+            queue = q;
+        } catch {
+            return floors;
+        }
+
+        HubCapacityMath.ResourceFloor[] memory buffer = new HubCapacityMath.ResourceFloor[](queue.length);
+        uint256 count;
+        bool anyFloor;
+        for (uint256 k; k < queue.length; ++k) {
+            address resource = queue[k];
+            address adapter;
+            try IYieldGroupBase(yieldGroup).resourceConfig(resource) returns (bool registered, bool paused, address a) {
+                if (!registered || paused) continue;
+                adapter = a;
+            } catch {
+                continue;
+            }
+
+            uint256 room;
+            try IResourceAdapter(adapter).maxDeposit(resource) returns (uint256 v) {
+                room = v;
+            } catch {
+                continue;
+            }
+
+            uint256 minDeposit = _minDepositOf(resource);
+            if (minDeposit != 0) anyFloor = true;
+            buffer[count++] = HubCapacityMath.ResourceFloor({ room: room, minDeposit: minDeposit });
+        }
+        if (!anyFloor) return floors;
+
+        floors = new HubCapacityMath.ResourceFloor[](count);
+        for (uint256 k; k < count; ++k) {
+            floors[k] = buffer[k];
+        }
+    }
+
+    /// @dev `minSupplierDeposit` of an FRV vault, 0 for any resource that is not one. A raw
+    ///      staticcall, so a vToken or fToken without `config()` reads as no floor instead of
+    ///      reverting the view.
+    function _minDepositOf(address resource) private view returns (uint256) {
+        (bool ok, bytes memory data) = resource.staticcall(abi.encodeCall(IFRVVault.config, ()));
+        if (!ok || data.length != FRV_CONFIG_SIZE) return 0;
+        return abi.decode(data, (IFRVVault.FRVVaultConfig)).minSupplierDeposit;
+    }
+
+    /// @dev Read the deposit queue down to what {HubCapacityMath} needs. Sourced from that queue,
+    ///      so a registered but unqueued YieldGroup is out of scope here, unlike {spotAPYBps}.
+    ///      Drops every YieldGroup the cascade would skip — unregistered, paused, or failing either
+    ///      view — so what it leaves out is immovable TVL, which the math derives from
+    ///      `hubTotalAssets`.
+    function _readDepositQueue(address hub)
+        private
+        view
+        returns (address[] memory groups, HubCapacityMath.GroupInput[] memory inputs, uint256 hubTotalAssets)
+    {
+        // Read first, so a YieldGroup that cannot be valued halts here rather than being silently
+        // skipped below and then reverting anyway on this same call.
+        hubTotalAssets = IHub(hub).totalAssets();
+
+        address[] memory queue = IHub(hub).outerDepositQueue();
+        uint256 len = queue.length;
+
+        address[] memory groupBuffer = new address[](len);
+        HubCapacityMath.GroupInput[] memory inputBuffer = new HubCapacityMath.GroupInput[](len);
+        uint256 count;
+
+        for (uint256 i; i < len; ++i) {
+            address yieldGroup = queue[i];
+            IHub.YieldGroupConfig memory cfg = IHub(hub).yieldGroupConfig(yieldGroup);
+            if (!cfg.registered || cfg.paused) continue;
+
+            uint256 balance = IYieldGroupBase(yieldGroup).totalAssets();
+
+            uint256 venueRoom;
+            try IYieldGroupBase(yieldGroup).maxDeposit() returns (uint256 v) {
+                venueRoom = v;
+            } catch {
+                continue;
+            }
+
+            groupBuffer[count] = yieldGroup;
+            inputBuffer[count] = HubCapacityMath.GroupInput({
+                balance: balance,
+                venueRoom: venueRoom,
+                absoluteCap: cfg.absoluteCap,
+                percentageCapBps: cfg.percentageCapBps
+            });
+            ++count;
+        }
+
+        groups = new address[](count);
+        inputs = new HubCapacityMath.GroupInput[](count);
+        for (uint256 i; i < count; ++i) {
+            groups[i] = groupBuffer[i];
+            inputs[i] = inputBuffer[i];
+        }
+    }
+}

package/deployments/bscmainnet/AdapterCentrifuge.json

@@ -1,6 +1,6 @@
 {
-  "address": "0x680cE4422264ecDAd3590cB50FE254D4c153f427",
-  "block": 122006956,
+  "address": "0xaa9D52758890997D91950E595886FF9CDEca81ae",
+  "block": 123325056,
   "chainId": 56,
   "contract": "AdapterCentrifuge",
   "abi": [
@@ -295,6 +295,25 @@
       "outputs": [],
       "stateMutability": "nonpayable"
     },
+    {
+      "type": "function",
+      "name": "resourceName",
+      "inputs": [
+        {
+          "name": "resource",
+          "type": "address",
+          "internalType": "address"
+        }
+      ],
+      "outputs": [
+        {
+          "name": "",
+          "type": "string",
+          "internalType": "string"
+        }
+      ],
+      "stateMutability": "view"
+    },
     {
       "type": "function",
       "name": "spotAPYBps",

package/deployments/bscmainnet/AdapterCoreV1.json

@@ -1,6 +1,6 @@
 {
-  "address": "0x4E514a0C7aB9d140eE204dfA0017574270D92944",
-  "block": 112779813,
+  "address": "0xa061cC2F62BDa2D6bA53Fb98847aD9822DA085dd",
+  "block": 123325056,
   "chainId": 56,
   "contract": "AdapterCoreV1",
   "abi": [
@@ -158,6 +158,25 @@
       ],
       "stateMutability": "view"
     },
+    {
+      "type": "function",
+      "name": "resourceName",
+      "inputs": [
+        {
+          "name": "resource",
+          "type": "address",
+          "internalType": "address"
+        }
+      ],
+      "outputs": [
+        {
+          "name": "",
+          "type": "string",
+          "internalType": "string"
+        }
+      ],
+      "stateMutability": "view"
+    },
     {
       "type": "function",
       "name": "spotAPYBps",

package/deployments/bscmainnet/AdapterFRV.json

@@ -1,6 +1,6 @@
 {
-  "address": "0x1FA0365bDd603452CE96BE3c0e12Db5515a35902",
-  "block": 112780032,
+  "address": "0x1824caA965Ac05ae5C9C2819e045337e2cF5657c",
+  "block": 123325056,
   "chainId": 56,
   "contract": "AdapterFRV",
   "abi": [
@@ -132,6 +132,25 @@
       ],
       "stateMutability": "view"
     },
+    {
+      "type": "function",
+      "name": "resourceName",
+      "inputs": [
+        {
+          "name": "resource",
+          "type": "address",
+          "internalType": "address"
+        }
+      ],
+      "outputs": [
+        {
+          "name": "",
+          "type": "string",
+          "internalType": "string"
+        }
+      ],
+      "stateMutability": "view"
+    },
     {
       "type": "function",
       "name": "spotAPYBps",

package/deployments/bscmainnet/AdapterFlux.json

@@ -1,6 +1,6 @@
 {
-  "address": "0xA81bDf813A428053E764C34Bc679b3E4d0807be3",
-  "block": 112780252,
+  "address": "0x9a1a7F6aebA4a1A3e85Ae1Dba90a7A2A52803404",
+  "block": 123325056,
   "chainId": 56,
   "contract": "AdapterFlux",
   "abi": [
@@ -151,6 +151,25 @@
       ],
       "stateMutability": "view"
     },
+    {
+      "type": "function",
+      "name": "resourceName",
+      "inputs": [
+        {
+          "name": "resource",
+          "type": "address",
+          "internalType": "address"
+        }
+      ],
+      "outputs": [
+        {
+          "name": "",
+          "type": "string",
+          "internalType": "string"
+        }
+      ],
+      "stateMutability": "view"
+    },
     {
       "type": "function",
       "name": "spotAPYBps",