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

package/README.md

@@ -1,8 +1,8 @@
 # Venus Liquidity Hub
 
-Per-asset ERC-4626 allocator vault. A lender deposits a single asset, the Hub routes it across Venus yield families (Core, Flux, FRV) under a governance-set policy, and returns a yield-bearing share token. Yield accrues through a **rising exchange rate** (one share = X underlying), never by rebasing — one Hub per asset, no cross-asset coupling.
+Per-asset ERC-4626 allocator vault. A lender deposits a single asset, the Hub routes it across Venus yield families (Core, Flux, FRV, Spoke) under a governance-set policy, and returns a yield-bearing share token. Yield accrues through a **rising exchange rate** (one share = X underlying), never by rebasing — one Hub per asset, no cross-asset coupling.
 
-> **Scope.** v1 ships on BNB Chain with three yield families — **Core**, **Flux**, **FRV**. Isolated Pools and RWA (Ondo / BUIDL) are documented future YieldGroups, not v1. The fee machinery is fully implemented but launches at `0/0`.
+> **Scope.** v1 ships on BNB Chain with three yield families — **Core**, **Flux**, **FRV**. **Spoke** (the liquidity side of hub-funded isolated pools) is built and follows once its markets are listed; RWA (Ondo / BUIDL) is a documented future YieldGroup. The fee machinery is fully implemented but launches at `0/0`.
 
 ---
 
@@ -25,53 +25,60 @@ flowchart TB
 
     Hub["Hub_USDT (ERC-4626, beacon proxy)<br/>dual caps · fees · per-tx cap"]:::hub
 
-    Hub --> OuterQ["outer queue (per direction)<br/>[YieldGroup_Core, YieldGroup_Flux, YieldGroup_FRV]"]:::queue
+    Hub --> OuterQ["outer queue (per direction)<br/>[YieldGroup_Core, YieldGroup_Flux, YieldGroup_FRV, YieldGroup_Spoke]"]:::queue
 
     OuterQ --> CoreYG["YieldGroup_Core_USDT"]:::src
     OuterQ --> FluxYG["YieldGroup_Flux_USDT"]:::src
     OuterQ --> FrvYG["YieldGroup_FRV_USDT"]:::src
+    OuterQ --> SpokeYG["YieldGroup_Spoke_USDT"]:::src
 
     CoreYG --> CoreInner["inner queue [vUSDT_v1, ...]"]:::queue
     FluxYG --> FluxInner["inner queue [fUSDT, ...]"]:::queue
     FrvYG  --> FrvInner["inner queue [FRV_A, FRV_B, ...]"]:::queue
+    SpokeYG --> SpokeInner["inner queue [vUSDT_poolA, vUSDT_poolB, ...]"]:::queue
 
     CoreInner -->|"delegatecall"| ACore["AdapterCoreV1<br/>(stateless singleton)"]:::adapter
     FluxInner -->|"delegatecall"| AFlux["AdapterFlux<br/>(stateless singleton)"]:::adapter
     FrvInner  -->|"delegatecall"| AFrv["AdapterFRV<br/>(stateless singleton)"]:::adapter
+    SpokeInner -->|"delegatecall"| ASpoke["AdapterSpokeV1<br/>(stateless singleton)"]:::adapter
 
     ACore --> RCore["vUSDT (Venus Core vToken)"]:::resource
     AFlux --> RFlux["fUSDT (Fluid fToken)"]:::resource
     AFrv  --> RFrv["FRV vault (fixed-rate, lifecycle)"]:::resource
+    ASpoke --> RSpoke["vUSDT (hub-funded spoke pool,<br/>liquidity side)"]:::resource
 ```
 
 ### Key contracts
 
-| Contract                                     | Role                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Hub**                                      | ERC-4626 entry point (beacon proxy). Routes deposits/withdrawals through the outer queue of YieldGroups, manages dual caps, the per-tx withdrawal cap, management + performance fees, and multi-level pause. Registry/queue logic is delegatecall-linked into **HubAdminLib** to stay under the 24 KB bytecode limit.                                                                                                                  |
-| **YieldGroupCore**                           | `IYieldGroupBase` over Venus **Core-pool vTokens** (`mint` / `redeemUnderlying`). Optional per-resource deposit caps. Grosses up redeems for a Comptroller treasury fee if one is ever enabled.                                                                                                                                                                                                                                        |
-| **YieldGroupFlux**                           | `IYieldGroupBase` over **Fluid Lending fTokens** (ERC-4626 shares). No redeem-time fee. Per-resource caps are the primary deposit control (Fluid's protocol `maxDeposit` is effectively unbounded).                                                                                                                                                                                                                                    |
-| **YieldGroupFRV**                            | `IYieldGroupBase` over Venus **Fixed-Rate Vaults** — ERC-4626 with an 11-state lifecycle. Pokes `updateVaultState()` before every routing decision; deposits only while Fundraising, withdrawals only when terminal.                                                                                                                                                                                                                   |
-| **AdapterCoreV1 / AdapterFlux / AdapterFRV** | Stateless singletons — zero storage, only immutables. One deployment per ABI family serves every YieldGroup. Mutating calls run via **delegatecall** so receipt tokens land on the YieldGroup; direct calls revert (`onlyDelegateCall`).                                                                                                                                                                                               |
-| **Migrator**                                 | Immutable, permissionless periphery (no proxy/beacon), one shared deployment per chain. One-click migration of a Venus Core position into a Hub: pulls the caller's vToken, redeems it to the underlying, deposits into the matching Hub, and mints shares to the caller — atomic, with a `minShares` slippage guard. A separate `migrateFromCoreBNB` path wraps a redeemed vBNB position to WBNB before depositing into the WBNB Hub. |
-| **IYieldGroupBase**                          | Hub↔YieldGroup boundary. `deposit` / `withdraw` (queue) + `depositResource` / `withdrawResource` (targeted, reallocate-only) + `totalAssets` / `maxDeposit` / `maxWithdraw` / `spotAPYBps`.                                                                                                                                                                                                                                            |
-| **IResourceAdapter**                         | YieldGroup↔adapter boundary. Mutating fns delegatecalled; view fns take an explicit `holder`. `validateRegistration` rejects resources with an unmodeled per-redeem fee.                                                                                                                                                                                                                                                               |
+| Contract                                     | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Hub**                                      | ERC-4626 entry point (beacon proxy). Routes deposits/withdrawals through the outer queue of YieldGroups, manages dual caps, the per-tx withdrawal cap, management + performance fees, and multi-level pause. Registry/queue logic is delegatecall-linked into **HubAdminLib** to stay under the 24 KB bytecode limit. Its `maxDeposit` / `maxMint` return `type(uint256).max`; caps are enforced by the routing cascade and the real capacity figure lives on **HubLens**. |
+| **YieldGroupCore**                           | `IYieldGroupBase` over Venus **Core-pool vTokens** (`mint` / `redeemUnderlying`). Optional per-resource deposit caps. Grosses up redeems for a Comptroller treasury fee if one is ever enabled.                                                                                                                                                                                                                                                                            |
+| **YieldGroupFlux**                           | `IYieldGroupBase` over **Fluid Lending fTokens** (ERC-4626 shares). No redeem-time fee. Per-resource caps are the primary deposit control (Fluid's protocol `maxDeposit` is effectively unbounded).                                                                                                                                                                                                                                                                        |
+| **YieldGroupFRV**                            | `IYieldGroupBase` over Venus **Fixed-Rate Vaults** — ERC-4626 with an 11-state lifecycle. Pokes `updateVaultState()` before every routing decision; deposits only while Fundraising, withdrawals only when terminal.                                                                                                                                                                                                                                                       |
+| **HubLens**                                  | Stateless, immutable, unowned read surface — no storage, no proxy, no registration. Takes the Hub as a call parameter, so one deployment serves every Hub. Exposes the deposit-capacity solve the Hub no longer runs (`maxDeposit`, `maxMint`, `depositCapacityBreakdown`) plus the Hub-level blended APY (`spotAPYBps`). Frontends and integrators size deposits from here.                                                                                               |
+| **AdapterCoreV1 / AdapterFlux / AdapterFRV** | Stateless singletons — zero storage, only immutables. One deployment per ABI family serves every YieldGroup. Mutating calls run via **delegatecall** so receipt tokens land on the YieldGroup; direct calls revert (`onlyDelegateCall`).                                                                                                                                                                                                                                   |
+| **Migrator**                                 | Immutable, permissionless periphery (no proxy/beacon), one shared deployment per chain. One-click migration of a Venus Core position into a Hub: pulls the caller's vToken, redeems it to the underlying, deposits into the matching Hub, and mints shares to the caller — atomic, with a `minShares` slippage guard. A separate `migrateFromCoreBNB` path wraps a redeemed vBNB position to WBNB before depositing into the WBNB Hub.                                     |
+| **IYieldGroupBase**                          | Hub↔YieldGroup boundary. `deposit` / `withdraw` (queue) + `depositResource` / `withdrawResource` (targeted, reallocate-only) + `totalAssets` / `maxDeposit` / `maxWithdraw` / `spotAPYBps`.                                                                                                                                                                                                                                                                                |
+| **IResourceAdapter**                         | YieldGroup↔adapter boundary. Mutating fns delegatecalled; view fns take an explicit `holder`. `validateRegistration` rejects resources with an unmodeled per-redeem fee.                                                                                                                                                                                                                                                                                                   |
 
 ---
 
 > **Terminology.** A _YieldGroup_ is the grouping layer: the Hub depends only on the `IYieldGroupBase` interface and never reaches past a YieldGroup into the underlying market. A _Resource_ is one underlying market or vault held inside a YieldGroup.
 
-## The three yield families
+## The four yield families
 
-|                          | **Core**                                                                                                 | **Flux**                                     | **FRV**                                          |
-| ------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------ |
-| Underlying protocol      | Venus Core lending                                                                                       | Fluid Lending                                | Venus Fixed-Rate Vaults                          |
-| Resource / receipt token | vToken (Compound-style)                                                                                  | fToken (ERC-4626 share)                      | FRV vault share (ERC-4626)                       |
-| Deposit / withdraw call  | `mint` / `redeemUnderlying`                                                                              | `deposit` / `withdraw(assets)`               | `deposit` / `withdraw(assets)`                   |
-| Redeem-time pool fee     | only if Comptroller `treasuryPercent` is later enabled (grossed-up); registration blocked while non-zero | none (Fluid's cut is in the supply rate)     | none (reserve factor taken once at settlement)   |
-| Spot APY source          | `supplyRatePerBlock` × `blocksPerYear`                                                                   | Fluid `LendingResolver` (pre-annualised APR) | vault `fixedAPY` (only while Fundraising / Lock) |
-| Per-resource deposit cap | optional                                                                                                 | optional (primary control)                   | not applicable (capacity comes from the vault)   |
-| Lifecycle constraint     | none                                                                                                     | none                                         | 11-state machine (see below)                     |
+|                          | **Core**                                                                                                 | **Flux**                                     | **FRV**                                          | **Spoke**                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
+| Underlying protocol      | Venus Core lending                                                                                       | Fluid Lending                                | Venus Fixed-Rate Vaults                          | Venus isolated pools (hub-funded spoke)                              |
+| Resource / receipt token | vToken (Compound-style)                                                                                  | fToken (ERC-4626 share)                      | FRV vault share (ERC-4626)                       | vToken (isolated-pools)                                              |
+| Deposit / withdraw call  | `mint` / `redeemUnderlying`                                                                              | `deposit` / `withdraw(assets)`               | `deposit` / `withdraw(assets)`                   | `mint` / `redeemUnderlying`                                          |
+| Redeem-time pool fee     | only if Comptroller `treasuryPercent` is later enabled (grossed-up); registration blocked while non-zero | none (Fluid's cut is in the supply rate)     | none (reserve factor taken once at settlement)   | none (the cut is the reserve factor, already inside the rate)        |
+| Spot APY source          | `supplyRatePerBlock` × `blocksPerYear`                                                                   | Fluid `LendingResolver` (pre-annualised APR) | vault `fixedAPY` (only while Fundraising / Lock) | `supplyRatePerBlock` × the **market's own** `blocksOrSecondsPerYear` |
+| Per-resource deposit cap | optional                                                                                                 | optional (primary control)                   | not applicable (capacity comes from the vault)   | optional (per spoke pool, alongside the pool's own supply cap)       |
+| Who may supply           | anyone                                                                                                   | anyone                                       | anyone                                           | **allowlisted only** — the pool grants the YieldGroup address        |
+| Valuation basis          | balance × exchange rate                                                                                  | `previewRedeem`                              | lifecycle-aware linear accrual                   | balance × exchange rate (includes `badDebt`)                         |
+| Lifecycle constraint     | none                                                                                                     | none                                         | 11-state machine (see below)                     | none                                                                 |
 
 ## Deposit flow
 
@@ -191,10 +198,11 @@ Hub.totalAssets()
              = Σ adapter.totalAssets(resource, yieldGroup)  +  YieldGroup idle balance
 ```
 
-- **Fails closed.** `totalAssets()` is the share-price denominator, so a YieldGroup whose `totalAssets()` view reverts is **not** isolated here — it halts share math rather than silently dropping that YieldGroup's funds from NAV (which would understate the price, under-pay redeemers and over-credit depositors until the value reappeared). The _quantity gates_ (`maxDeposit` / `maxWithdraw`) and the deposit/withdraw routing **do** isolate a faulting YieldGroup (contribute 0 / skip) because failing conservatively there is safe — only on the price would it corrupt the conversion. A view-level revert is a YieldGroup-level bug (resource-level reverts are isolated inside the YieldGroup, so external pauses surface in `withdraw`/`deposit`, not here); recover via the runbook below.
+- **Fails closed.** `totalAssets()` is the share-price denominator, so a YieldGroup whose `totalAssets()` view reverts is **not** isolated here — it halts share math rather than silently dropping that YieldGroup's funds from NAV (which would understate the price, under-pay redeemers and over-credit depositors until the value reappeared). The _quantity views_ (`maxWithdraw`, and `HubLens`'s capacity figure) and the deposit/withdraw routing **do** isolate a faulting YieldGroup (contribute 0 / skip) because failing conservatively there is safe — only on the price would it corrupt the conversion. A view-level revert is a YieldGroup-level bug (resource-level reverts are isolated inside the YieldGroup, so external pauses surface in `withdraw`/`deposit`, not here); recover via the runbook below.
 - Hub idle is normally zero (deposits route out atomically, withdrawals pull exact amounts, reallocate is balanced). A direct token donation persists and is intentionally counted into NAV (it accrues to LPs and is consumed first on withdraw) — the underlying cannot be swept.
 - YieldGroup idle accumulates from treasury-fee gross-up surplus and dust handling on past withdrawals; it is counted and consumed idle-first.
 - View paths use the **stored** exchange rate (`exchangeRateStored`, stale up to one accrual cycle, no state mutation). Mutating paths trigger interest accrual on the resource during mint/redeem, so the rate is current by the time the operation completes.
+- **Spoke marks at the market's own exchange rate, and that rate includes written-off debt.** An isolated-pools `VToken` keeps written-off debt inside its rate: `healAccount` moves the shortfall from `totalBorrows` into `badDebt`, leaving the numerator unchanged, so the rate does not fall when a loss is booked. `AdapterSpokeV1` values a position at that same rate, as `AdapterCoreV1` does. The written-off amount is therefore cash the market does not have, not a lower share price, and while it is outstanding LPs who exit first are paid in full out of the cash that is left. The market's `shortfall` pays the debt down through `badDebtRecovered`, which lowers `badDebt` and raises cash by the same amount: more can be withdrawn and the share price does not move.
 
 ### Recovering a bricked YieldGroup (governance)
 
@@ -253,7 +261,60 @@ effectiveCap = (percentageCapBps == 10_000)
              : min(absoluteCap, percentageCapBps × hubTVL / 10_000)
 ```
 
-`percentageCapBps == 10_000` (100%) is a sentinel that **disables** the percentage component — required so a fresh Hub at TVL = 0 can take its first deposit (otherwise `pct × 0` collapses the cap to zero). `absoluteCap == type(uint256).max` is rejected; use the sentinel to disable the percentage dimension instead.
+`percentageCapBps == 10_000` (100%) is a sentinel that **disables** the percentage component, leaving only the absolute cap at every TVL. `absoluteCap == type(uint256).max` is rejected; use the sentinel to disable the percentage dimension instead.
+
+**Enforcement is the routing cascade, not a quantity gate.** The Hub does not override `maxDeposit` / `maxMint`, so both inherit OpenZeppelin's bodies and return `type(uint256).max`. Solving the caps means solving every YieldGroup's dual cap against the TVL the deposit itself produces, and ERC-4626 calls those views on every `deposit` and every `mint` — that solve does not belong on the hot path. Instead `_routeDeposit` reverts with `HubCapacityExceeded(assets, placed)` on anything the cascade cannot place, which also names how much would have fit.
+
+**The percentage cap is priced at the post-deposit TVL.** Incoming assets sit idle on the Hub for the whole cascade, so they are already inside `totalAssets()` when each `effectiveCap` is computed — a deposit lifts the very caps it is measured against. Capacity therefore cannot be priced at today's TVL. `HubLens.maxDeposit` solves for the largest TVL that every cap simultaneously admits and reports the distance to it: a book of Core `20,000 / 90%` and FRV `8,000 / 30%` tops out at `28,000`, and an empty Hub reports exactly that, not the `0` that pricing both caps at TVL = 0 produces. A frontend or integrator reads that figure before sizing a deposit; nothing on-chain requires it.
+
+**Solving for the reachable TVL.** Let `X` be the post-deposit TVL. For each unpaused deposit-queue YieldGroup `i`, write `bal_i` for what it currently holds and
+
+```
+absBound_i = min( absoluteCap_i , bal_i + yieldGroup_i.maxDeposit() )
+```
+
+for the most it could ever hold — its absolute cap, further bounded by what its venue will accept on top of that balance. At TVL `X` it holds
+
+```
+hold_i(X) = max( bal_i , min( absBound_i , pct_i × X / 10_000 ) )
+```
+
+The inner `min` is the dual cap. The outer `max` floors it at what the YieldGroup already holds, since a deposit cannot make it give money back. Writing `C` for the assets that are not free to move — Hub idle, paused YieldGroups, YieldGroups outside the deposit queue, and any whose capacity views revert — the reachable TVL is the largest `X` satisfying
+
+```
+X  ≤  C + Σ hold_i(X)
+```
+
+and `HubLens.maxDeposit` returns `X − totalAssets()`.
+
+Each `hold_i` is flat, then sloped, then flat, with a breakpoint at each turn:
+
+```
+hold_i
+  ^
+  |                        +-----------  absBound_i   absolute bound binds
+  |                       /
+  |                      /               percentage cap binds, slope pct_i
+  |        +------------+                bal_i        balance floor binds
+  +--------+------------+-------------->  TVL (X)
+        breakLow_i   breakHigh_i
+```
+
+`breakLow_i` is the TVL at which the percentage cap catches up with the balance, `breakHigh_i` the TVL at which it reaches `absBound_i`.
+
+Summing over the queue gives at most `2n` breakpoints. Between two consecutive ones no YieldGroup changes which bound it sits on, so the sum is `base + slope × X / 10_000` there and the segment crosses in closed form:
+
+```
+X = base × 10_000 / (10_000 − slope)
+```
+
+`HubCapacityMath` collects the breakpoints, sorts them, and keeps the largest crossing that lands inside its own segment. A segment whose `slope ≥ 10_000` has no crossing at all: its right-hand side grows at least as fast as `X`, so every TVL in it satisfies the inequality and the answer there is the segment's top edge, not a fixed point. That edge is snapped down to a multiple of `10_000`, where every percentage cap divides exactly and the cascade's per-YieldGroup flooring sheds nothing. Only a segment with no finite top edge, the last one, is passed over.
+
+Membership is decided on the segment's own crossing, before any adjustment. Charging an adjustment first would push a crossing that lands exactly on a segment boundary just below it and discard the segment that holds the answer.
+
+The crossing is then checked against the room the cascade would really leave at that TVL, and returned unchanged when it fits, which is the usual path. Only when it does not fit is the flooring pre-paid: the closed form floors once where the cascade floors each cap separately, so one wei is taken off `base` for each of the `k` YieldGroups the percentage cap binds on that segment. That pre-payment lowers the reported figure by `k × 10_000 / (10_000 − slope)` wei.
+
+The figure promises only that depositing it succeeds, not that every smaller amount does. In a book with no absolute-only YieldGroup a dust deposit still reverts, because every `pctBps × TVL / 10_000` floors to zero while TVL is tiny.
 
 **Resource level (YieldGroup) — optional, Core & Flux only.** Each resource may carry an optional absolute deposit cap limiting how much underlying _this YieldGroup_ holds in that one market, independent of the market's own protocol supply cap:
 
@@ -263,7 +324,7 @@ room = min( protocolHeadroom,  resourceCap − ourBalanceInResource )
 
 - `resourceCap == 0` means **unset/unbounded** — only the protocol cap binds. When unset, the balance lookup is skipped, so the feature is zero-cost when unused. (`raiseResourceCap` to 0 removes a cap; `lowerResourceCap` to 0 is rejected.)
 - The protocol cap is **global/shared** across all depositors; the resource cap is purely about _this YieldGroup's_ position, so actual room can be below `resourceCap` if others have filled the market.
-- Enforced everywhere deposits land: the inner deposit cascade, `maxDeposit()`, and resource-targeted reallocate pushes.
+- Enforced everywhere deposits land: the inner deposit cascade, `YieldGroup.maxDeposit()`, and resource-targeted reallocate pushes.
 - **YieldGroupFRV has no per-resource cap** — FRV capacity comes entirely from the vault's own `maxBorrowCap` and its Fundraising-only rule.
 
 **Per-transaction withdrawal cap (Hub).** `maxWithdrawalSize` (asset units) bounds every single withdraw/redeem; exceeding it reverts `HubWithdrawCapExceeded`.
@@ -305,11 +366,12 @@ contracts/
     core/                    YieldGroupCore + Storage, Adapters/AdapterCoreV1
     flux/                    YieldGroupFlux + Storage, Adapters/AdapterFlux
     FRV/                     YieldGroupFRV + Storage, Adapters/AdapterFRV
+  lens/                      HubLens.sol + HubCapacityMath.sol (off-chain read surface, no storage)
   migrator/                  Migrator.sol (immutable Core→Hub one-click migration)
   registry/                  HubRegistry.sol (chain-level Hub directory, discovery root)
-  interfaces/                IYieldGroupBase, IResourceAdapter, IHub, IHubRegistry, IYieldGroup*, IMigrator, IVToken, IVBep20, IWBNB, IFToken, IFRVVault, ...
-deploy/                      Foundry deploy scripts 01–07 + DeployBase + config/<network>.json
-tests/foundry/               unit (Hub/, YieldGroup/{core,flux,frv}/, Registry/), Integration/, fork/
+  interfaces/                IYieldGroupBase, IResourceAdapter, IHub, IHubLens, IHubRegistry, IYieldGroup*, IMigrator, IVToken, IVBep20, IWBNB, IFToken, IFRVVault, ...
+deploy/                      Foundry deploy scripts 01–14 + DeployBase + config/<network>.json
+tests/foundry/               unit (Hub/, YieldGroup/{core,flux,frv}/, Registry/, lens/), Integration/, fork/
 deployments/<network>/       committed registry of deployed addresses (source of truth)
 lib/                         git-submodule dependencies
 ```
@@ -348,6 +410,16 @@ npm i @venusprotocol/liquidity-hub@develop    # prerelease, cut from develop
 import { IHub } from "@venusprotocol/liquidity-hub/contracts/interfaces/IHub.sol";
 ```
 
+**Sizing a deposit.** `Hub.maxDeposit` / `Hub.maxMint` return `type(uint256).max` — the Hub does not compute a ceiling, because doing so would run the cap solve on every deposit. That holds while the Hub is paused too, so anything that sizes off them reverts on deposit. Read the real figure from `HubLens` instead:
+
+```solidity
+import { IHubLens } from "@venusprotocol/liquidity-hub/contracts/interfaces/IHubLens.sol";
+
+uint256 room = IHubLens(lens).maxDeposit(hub);   // 0 while the Hub is paused
+```
+
+`HubLens` is stateless and takes the Hub as a parameter, so one deployment serves every Hub on the chain; its address is in `deployments/<network>_addresses.json`. It also exposes `maxMint`, `depositCapacityBreakdown` (the same ceiling split by receiving YieldGroup) and `spotAPYBps` (the Hub's blended yield, weighted by balance, with idle counted at 0%). Depositing more than `maxDeposit` reverts `HubCapacityExceeded(assets, placed)`, which names how much would have fit.
+
 **Addresses and ABIs.** `deployments/<network>_addresses.json` is a name → address map; each `deployments/<network>/<Name>.json` carries `address`, `block`, `chainId`, `contract` and the deployed `abi`.
 
 ```ts
@@ -357,13 +429,18 @@ import hub from "@venusprotocol/liquidity-hub/deployments/bscmainnet/Hub_USDT.js
 
 ## Deployment
 
-Beacon-proxy model: one `UpgradeableBeacon` **per family per chain** (Hub, Core, FRV, Flux), each owned by governance — `beacon.upgradeTo` upgrades every vault of that family atomically. Per-asset instances are `BeaconProxy`s.
+Beacon-proxy model: one `UpgradeableBeacon` **per family per chain** (Hub, Core, FRV, Flux, Spoke), each owned by governance — `beacon.upgradeTo` upgrades every vault of that family atomically. Per-asset instances are `BeaconProxy`s.
 
 ```
 01_DeployHubBeacon   02_DeployCore   03_DeployFRV   04_DeployFlux   # once per chain (impl + adapter + beacon)
 05_DeployHubRegistry                                                # once per chain (upgradeable singleton, discovery root)
 06_DeployAssetVault                                                 # per asset, idempotent
 07_DeployMigrator                                                   # once per chain (immutable, permissionless periphery)
+10_DeployHubLens                                                    # once per chain, before 12 (stateless read surface; re-run to ship a new version)
+11_DeployAdapters                                                   # upgrade only: new Core / Flux / FRV / Centrifuge / Spoke adapters
+12_DeployHubImpl                                                    # upgrade only: new Hub impl behind the existing HubBeacon
+13_DeploySpoke                                                      # once per chain (Spoke adapter + impl + beacon)
+14_DeploySpokeSource                                                # per asset, backfills existing Hubs
 ```
 
 Scripts run in numeric order: beacons first, then the registry, then per-asset instances against both. Scripts only deploy + initialize — **ACM wiring, `addYieldGroup` / `addResource`, and queue configuration are governance (ACM-gated) actions done separately.**
@@ -374,6 +451,10 @@ Script 06 deploys a Hub proxy per asset (YieldGroups read `IHub.asset()` and rev
 
 Script 07 deploys the immutable **Migrator** (no beacon, no proxy); it is permissionless and needs **no** ACM wiring — a user calls it directly after approving their vToken.
 
+Scripts 13 and 14 add the **Spoke** family. They are split from 02–04/06 because script 06 skips any asset whose Hub already exists, so a Hub deployed before this family could never receive a Spoke source through it; 14 is keyed on the source instead and therefore backfills existing Hubs and covers new ones alike. The listing VIP must list the market and call `setAllowedSupplier(vToken, <SpokeSource>, true)` on each spoke pool **before** `addResource` — `AdapterSpokeV1.validateRegistration` rejects the registration otherwise, which is deliberate: a market that will not accept this source would otherwise occupy a queue slot it can never fill.
+
+Scripts 11 and 12 ship new code to a chain whose families are already deployed, and are not part of onboarding. The family scripts do not fit that case: 01, 02 and 03 also deploy a new beacon and overwrite its record, 04 and 13 skip an adapter that is already recorded, and 08_DeployCentrifuge also deploys a YieldGroup implementation. Script 11 deploys only the five adapters; the YieldGroups keep the old adapter until governance calls `updateResourceAdapter(resource, adapter)` for each resource. Script 12 deploys only a Hub implementation and requires the `HubBeacon` record; the Hubs move to it when governance calls `HubBeacon.upgradeTo(impl)`. Both overwrite their registry records, so a dry run (no `--broadcast`) leaves `deployments/` modified; restore it with `git checkout deployments/`.
+
 ### Hub onboarding flow (deploy + one-tx registration VIP)
 
 Onboarding an asset: the deployer EOA runs the scripts in numeric order (no ACM roles needed), then **one** governance proposal — a single hop — registers and wires the Hub atomically.

package/contracts/Hub/Hub.sol

@@ -26,6 +26,10 @@ import { HubAdminLib } from "./lib/HubAdminLib.sol";
  *      Inheritance order is load-bearing for upgrade safety — do not reorder.
  *      Function ordering follows the Solidity style guide: external → public → internal →
  *      private, mutating before view within each group.
+ *      Capacity: `maxDeposit` / `maxMint` return `type(uint256).max`, paused or not, and do not
+ *      reflect the caps. Size deposits and mints from `HubLens.maxDeposit` / `HubLens.maxMint`,
+ *      which return the real figure and 0 while paused. The caps themselves are enforced by the
+ *      deposit routing, which reverts `HubCapacityExceeded` on anything it cannot place.
  *      {HubAdminLib} is linked for EIP-170 headroom; a library declares no state, so it cannot shift this layout.
  * @custom:oz-upgrades-unsafe-allow external-library-linking
  */
@@ -819,9 +823,9 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
      *      donation. It is folded into NAV (the underlying cannot be swept) so it accrues to LPs and
      *      is consumed first on withdraw.
      *
-     *      Fails closed. A YieldGroup whose `totalAssets()` reverts is NOT isolated here — unlike the
-     *      quantity-gate views (`maxDeposit` / `maxWithdraw`) and the deposit / withdraw routing,
-     *      which deliberately skip a faulting YieldGroup. The difference is the safety class: NAV is the
+     *      Fails closed. A YieldGroup whose `totalAssets()` reverts is NOT isolated here — unlike
+     *      `maxWithdraw` and the deposit / withdraw routing, which deliberately skip a faulting
+     *      YieldGroup. The difference is the safety class: NAV is the
      *      share-price denominator that every mint and redeem converts against, so silently counting
      *      a YieldGroup as 0 would understate the price — under-paying redeemers and over-crediting
      *      depositors until its value reappeared. Failing to 0 is safe for a quantity gate (it only
@@ -850,16 +854,29 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
         total += IERC20Upgradeable(asset()).balanceOf(address(this));
     }
 
-    /// @inheritdoc IERC4626Upgradeable
-    function maxDeposit(address) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
-        if (_hubPaused) return 0;
-        return _aggregateDepositCapacity(totalAssets());
-    }
-
-    /// @inheritdoc IERC4626Upgradeable
-    function maxMint(address receiver) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
-        return convertToShares(maxDeposit(receiver));
-    }
+    // `maxDeposit` and `maxMint` are deliberately NOT overridden, so both inherit OpenZeppelin's
+    // bodies and return `type(uint256).max`, including while the Hub is paused (the override this
+    // replaced returned 0 then; deposits still revert, via `whenNotHubPaused`). Computing the real
+    // ceiling means solving every YieldGroup's dual cap against the TVL the deposit itself
+    // produces, and `deposit` / `mint` call these views on every single call — that solve does not
+    // belong on the hot path.
+    //
+    // Caps are still enforced, by `_routeDeposit`: whatever the cascade cannot place reverts with
+    // `HubCapacityExceeded(assets, placed)`, which also names how much would have fit. Restoring an
+    // override here would put the solve back on the hot path without tightening anything.
+    //
+    // The real figures live on `HubLens` (`maxDeposit`, `maxMint`, `depositCapacityBreakdown`),
+    // which is what a frontend or an integrator reads to size a deposit.
+    //
+    // What is inherited, kept here so the removal reads as deliberate rather than an oversight:
+    //
+    // function maxDeposit(address) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
+    //     return type(uint256).max;
+    // }
+    //
+    // function maxMint(address) public view override(ERC4626Upgradeable, IERC4626Upgradeable) returns (uint256) {
+    //     return type(uint256).max;
+    // }
 
     /**
      * @inheritdoc IERC4626Upgradeable
@@ -1038,10 +1055,11 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
         // getting taxed as performance on the next recovery past it. The delta form shields the
         // retained fee whether PPS sits above or below the mark, and stays monotonic (delta >= 0:
         // the fee-on burn always destroys at least as much share-value as the assets routed out).
-        // Genuine gains stay taxable: the increment moves the mark by exactly what the fee moved
-        // PPS, preserving the (hwm - pps) gap, so any yield PPS earned on top of the uplift —
-        // including yield landed intra-block after the caller's accrual — is still charged at the
-        // next accrual. No-op when the exit fee is 0 (a proportional burn leaves PPS unchanged).
+        // Genuine gains stay taxable: the increment preserves the (hwm - pps) gap, so any yield
+        // PPS earned on top of the uplift, including yield landed intra-block after the caller's
+        // accrual, is still charged at the next accrual. `prePps` is taken before `_routeWithdraw`,
+        // so a resource that redeems above its reported value has that surplus shielded too.
+        // No-op when the exit fee is 0 (a proportional burn leaves PPS unchanged).
         if (redeemBps != 0) {
             uint256 ts = totalSupply();
             if (ts != 0) {
@@ -1202,10 +1220,10 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
      * @dev When `percentageCapBps == BPS_DENOMINATOR` (100%), the percentage cap is treated
      *      as disabled and only the absolute cap binds. Without this carve-out, every Hub
      *      with any percentage-cap value is permanently un-bootstrappable: at TA = 0 the
-     *      percentage component collapses to 0, `maxDeposit()` returns 0, and OZ's
-     *      ERC-4626 wrapper rejects the very first deposit. The carve-out matches the
+     *      percentage component collapses to 0, so the cascade can place nothing and
+     *      `_routeDeposit` reverts on the very first deposit. The carve-out matches the
      *      MetaMorpho convention and preserves dual-cap semantics for `pctBps < 10_000`.
-     * @dev Cap basis: every cap check (deposit cascade, {maxDeposit}, and {reallocate}) compares this
+     * @dev Cap basis: every cap check (deposit cascade and {reallocate}, plus `HubLens`) compares this
      *      ceiling against the YieldGroup's *current marked* `totalAssets()`, not the principal
      *      deposited into it. Because a group's `totalAssets()` accrues over time, its cap headroom
      *      shrinks even with no new deposit — most visibly for FRV, whose Hub-facing mark accrues the
@@ -1216,52 +1234,16 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
      *      headroom for the coupon expected over the lock.
      * @param cfg YieldGroup config to evaluate.
      * @param ta TVL reference used for the percentage-cap component.
-     * @return cap `pctBps == 10_000` ? `absoluteCap` : `min(absoluteCap, pctBps × ta / 10_000)`.
+     * @return cap `pctBps == 10_000` ? `absoluteCap` : `min(absoluteCap, ⌈pctBps × ta / 10_000⌉)`.
      */
     function _effectiveCap(IHub.YieldGroupConfig storage cfg, uint256 ta) internal view returns (uint256 cap) {
         if (cfg.percentageCapBps == BPS_DENOMINATOR) return cfg.absoluteCap;
-        uint256 pctCap = (ta * cfg.percentageCapBps) / BPS_DENOMINATOR;
+        // Rounded up: percentage caps summing to 100% leave no slack, so a floored cap would leave
+        // the room a wei short of the deposit that set it.
+        uint256 pctCap = (ta * cfg.percentageCapBps + BPS_DENOMINATOR - 1) / BPS_DENOMINATOR;
         cap = pctCap < cfg.absoluteCap ? pctCap : cfg.absoluteCap;
     }
 
-    /**
-     * @notice Sum spare deposit capacity across the unpaused deposit-queue YieldGroups.
-     * @param taSnapshot TVL reference used for percentage-cap math on each YieldGroup.
-     * @return total Aggregate asset units that could be deposited right now.
-     */
-    function _aggregateDepositCapacity(uint256 taSnapshot) internal view returns (uint256 total) {
-        address[] storage queue = _outerDepositQueue;
-        uint256 len = queue.length;
-        for (uint256 i; i < len; ++i) {
-            address yieldGroup = queue[i];
-            IHub.YieldGroupConfig storage cfg = _yieldGroups[yieldGroup];
-            if (cfg.registered && !cfg.paused) {
-                // Isolate a misbehaving YieldGroup: a revert in either capacity view contributes 0
-                // spare cap instead of bricking every deposit. Mirrors `totalAssets()`.
-                uint256 currentBal;
-                uint256 yieldGroupMax;
-                bool ok = true;
-                try IYieldGroupBase(yieldGroup).totalAssets() returns (uint256 v) {
-                    currentBal = v;
-                } catch {
-                    ok = false;
-                }
-                if (ok) {
-                    try IYieldGroupBase(yieldGroup).maxDeposit() returns (uint256 v) {
-                        yieldGroupMax = v;
-                    } catch {
-                        ok = false;
-                    }
-                }
-                if (ok) {
-                    uint256 cap = _effectiveCap(cfg, taSnapshot);
-                    uint256 capRoom = cap > currentBal ? cap - currentBal : 0;
-                    total += capRoom < yieldGroupMax ? capRoom : yieldGroupMax;
-                }
-            }
-        }
-    }
-
     /**
      * @notice Sum liquid funds across the unpaused withdraw-queue YieldGroups, plus Hub idle.
      * @dev Hub idle is first-class liquidity: `_routeWithdraw` consumes it before touching any
@@ -1292,11 +1274,35 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
 
     // ============================== Private — mutating =======================
 
+    /**
+     * @notice Fail-open resource settlement used ONLY by the paused emergency path: a YieldGroup whose
+     *         `accrue()` reverts is skipped instead of bricking the whole call.
+     * @dev Pairs with {_totalAssetsFailOpen}, the cap reference the same paused branch reads: a YieldGroup
+     *      that has stopped answering the Hub is what {emergencyReallocate} exists to unwind, so it must
+     *      not block the wind-down of the YieldGroups that still work. A skipped YieldGroup only leaves its
+     *      resources unsettled, and {_reallocatePullAll} still requires the delivered amount to equal the
+     *      leg, so an under-settled market reverts that leg. Share pricing keeps the strict
+     *      {_accrueResources} via {_accrueFees}.
+     */
+    function _accrueResourcesFailOpen() private {
+        address[] storage yieldGroups = _registeredYieldGroups;
+        uint256 len = yieldGroups.length;
+        for (uint256 i; i < len; ++i) {
+            // solhint-disable-next-line no-empty-blocks
+            try IYieldGroupBase(yieldGroups[i]).accrue() { }
+            catch {
+                emit YieldGroupAccrualFailed(yieldGroups[i]);
+            }
+        }
+    }
+
     /**
      * @notice Shared net-zero reallocation core for {reallocate} and {emergencyReallocate}.
-     * @dev Accrues fees first so the operation trades against current state — except while
-     *      the Hub is paused, when accrual is skipped so the pause window is excluded from fee
-     *      proration ({unpauseHub} later advances the accrual cursor past the frozen window).
+     * @dev Accrues fees first so the operation trades against current state. A pause skips only the
+     *      FEE half, so the frozen window stays out of fee proration ({unpauseHub} later advances
+     *      the cursor past it). Resource settlement still runs — adapters size withdrawals off
+     *      stored resource state — and charges nothing, moving neither the HWM nor the cursor. Under
+     *      the freeze that settlement is fail-open, matching the NAV read it feeds.
      *      Enforces `Σ withdraws == Σ deposits`.
      * @param withdraws Withdraw legs to execute first.
      * @param deposits Deposit legs to execute against the post-pull TVL snapshot.
@@ -1304,6 +1310,8 @@ contract Hub is ERC4626Upgradeable, AccessControlledV8, ReentrancyGuardUpgradeab
     function _reallocate(IHub.ReallocateLeg[] calldata withdraws, IHub.ReallocateLeg[] calldata deposits) private {
         if (!_hubPaused) {
             _accrueFees();
+        } else {
+            _accrueResourcesFailOpen();
         }
 
         uint256 withdrawSum = _reallocatePullAll(withdraws);

package/contracts/adapters/AdapterCentrifuge.sol

@@ -290,6 +290,11 @@ contract AdapterCentrifuge is IAdapterCentrifuge {
             + inv.claimableCancelRedeemRequest;
     }
 
+    /// @inheritdoc IResourceAdapter
+    function resourceName(address resource) external view override returns (string memory) {
+        return IERC20Metadata(ICentrifugeAsyncVault(resource).share()).name();
+    }
+
     /// @inheritdoc IResourceAdapter
     /// @dev Verifies the vault exposes the share token, request manager, investment state, and price
     ///      reads required by this adapter.

package/contracts/adapters/AdapterCoreV1.sol

@@ -2,6 +2,7 @@
 pragma solidity 0.8.25;
 
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { IERC20Metadata } from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 
 import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
@@ -248,6 +249,11 @@ contract AdapterCoreV1 is IResourceAdapter {
         return IVToken(resource).balanceOf(holder);
     }
 
+    /// @inheritdoc IResourceAdapter
+    function resourceName(address resource) external view override returns (string memory) {
+        return IERC20Metadata(resource).name();
+    }
+
     /// @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

package/contracts/adapters/AdapterFRV.sol

@@ -2,6 +2,7 @@
 pragma solidity 0.8.25;
 
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { IERC20Metadata } from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
 
@@ -148,12 +149,17 @@ contract AdapterFRV is IResourceAdapter {
     }
 
     /// @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.
+    /// @dev Returns the vault's `fixedAPY` (already annualised in BPS) net of `reserveFactor`, 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.
+    ///
+    ///      `fixedAPY` is the rate the institution pays; the vault keeps `reserveFactor` of the
+    ///      interest for the protocol at settlement, so a supplier earns the remainder. This view is
+    ///      defined as the supply-side rate, so it reports that remainder, netted the same way
+    ///      {_accruedTotalAssets} nets the value it marks: floor the cut, then subtract it.
     function spotAPYBps(
         address resource,
         uint256 /* blocksPerYear */
@@ -168,8 +174,17 @@ contract AdapterFRV is IResourceAdapter {
             return 0;
         }
         IFRVVault.FRVVaultConfig memory cfg = IFRVVault(resource).config();
+
+        // Saturate before netting, not after: a misreporting vault can carry a `fixedAPY` large
+        // enough that `fixedAPY * reserveFactor` overflows, and this view must not revert. The
+        // YieldGroup sums it across every resource, so one bad vault would take the whole reading
+        // down. Below `uint64.max` the clamp is a no-op and the arithmetic is exact.
+        uint256 grossApy = cfg.fixedAPY > type(uint64).max ? type(uint64).max : cfg.fixedAPY;
+
+        // `reserveFactor <= MANTISSA_ONE` is enforced by the FRV vault controller at config time, so
+        // the cut never exceeds `grossApy` and this subtraction cannot underflow.
         // forge-lint: disable-next-line(unsafe-typecast)
-        return cfg.fixedAPY > type(uint64).max ? type(uint64).max : uint64(cfg.fixedAPY);
+        return uint64(grossApy - (grossApy * cfg.reserveFactor) / MANTISSA_ONE);
     }
 
     /// @inheritdoc IResourceAdapter
@@ -177,6 +192,11 @@ contract AdapterFRV is IResourceAdapter {
         return IFRVVault(resource).balanceOf(holder);
     }
 
+    /// @inheritdoc IResourceAdapter
+    function resourceName(address resource) external view override returns (string memory) {
+        return IERC20Metadata(resource).name();
+    }
+
     /// @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.

package/contracts/adapters/AdapterFlux.sol

@@ -2,6 +2,7 @@
 pragma solidity 0.8.25;
 
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { IERC20Metadata } from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 
 import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
@@ -162,6 +163,11 @@ contract AdapterFlux is IResourceAdapter {
         return IFToken(resource).balanceOf(holder);
     }
 
+    /// @inheritdoc IResourceAdapter
+    function resourceName(address resource) external view override returns (string memory) {
+        return IERC20Metadata(resource).name();
+    }
+
     /// @inheritdoc IResourceAdapter
     /// @dev No-op: a Fluid fToken takes its revenue cut in the supply rate, not per-redeem, so
     ///      there is no unmodeled exit fee to guard against at registration.