docs(liquidity-hub): add Liquidity Hub documentation - #353
Open
Debugger022 wants to merge 5 commits into
Open
Conversation
Document the Liquidity Hub — the per-asset ERC-4626 allocator vault that routes a single deposited asset across the Core, Flux, and FRV yield families and returns a yield-bearing share token (yield via a rising exchange rate). What's New: - whats-new/liquidity-hub.md: user-facing overview — Sources, deposit/ withdraw routing, Operator rebalancing, safety envelope, fees, APY Technical reference (new reference-liquidity-hub/ section): - README.md: architecture, three yield families, contract index, audits - hub.md: Hub ERC-4626 API, operation flows, dual caps, fees, APY, multi-level pause, reentrancy, invariants - yield-groups.md: YieldGroupCore/Flux/FRV, ISource surface, FRV 11-state lifecycle, per-resource caps - adapters.md: stateless delegatecall adapters (Core/Flux/FRV) - interfaces.md: ISource and IResourceAdapter boundaries Wire all pages into SUMMARY.md. Scope: v1 (Core/Flux/FRV on BNB Chain, USDT first). Contracts not yet deployed — addresses to be published once live.
|
GitBook Preview: https://docs-v4.venus.io/~/revisions/a2G8a7QkLY0yuK3tFY6Z/ |
nayzawlin4920021-sys
approved these changes
Jun 6, 2026
- ISource does not exist in the code. The Hub boundary interface is IYieldGroupBase, and the stale name appeared on all five pages, including a terminology note asserting the code reserves it. - totalAssets() was documented as fault-isolated, stated twice and once as an invariant. It is fail-closed, so a Source with a reverting view halts share pricing instead of contributing 0. - The deposit cascade accepts partial fills and refunds the remainder. It never raises YieldGroupUnderfilled, which is reachable only from reallocate legs and the withdraw path. - accrue() was absent from both boundary interfaces even though the Hub calls it unguarded on every registered Source. - Permissions rebuilt from the onboarding VIP's ACM grants rather than the natspec annotations, which disagree in two places: the Operator holds raiseYieldGroupCap, and governance is not granted reallocate. - Event and error rows described triggers that cannot fire. YieldGroupSkipped and ResourceSkipped emit only when a call reverts, and TreasuryPercentTooHigh is not a real error. - Documented the Migrator and the BSC testnet deployment, both live and previously absent.
- accrue() is overridden by all three families, so the pages described a base no-op that deployed code never reaches. This hid that any Hub operation advances every registered FRV vault's lifecycle, not just the one being routed to. - The architecture diagram labelled YieldGroupCore, YieldGroupFlux and ISource. None is a declared type, and the terminology callout printed beside it already said so. - raiseResourceCap was marked governance-only, and the user-facing page said tightening belonged to the Operator alone. The executing proposal grants raise and lower to the Operator, and pause to the Guardian at every level. - Dropped the specific attribution for the Operator multisig. Nothing in the contracts or the proposal substantiates the name. - FRV was presented as a live family. It is registered on every Hub with no resource wired, so no capital routes to it until a later proposal adds a vault. - Added launch parameters, the registry's transparent-proxy model and the role-holder addresses, so the documented figures are checkable against the deployment. - Documented three preconditions previously visible only in source: the inner withdraw-queue funded guard, the per-resource cap reset on removal, and ZeroAmount on zero-value reallocate legs.
zed-venus
reviewed
Aug 3, 2026
|
|
||
| ### Overview | ||
|
|
||
| The **Venus Liquidity Hub** is a per-asset *allocator vault*. A lender deposits a single asset (USDT, for example) and receives a yield-bearing share token. Under a governance-set policy, the Hub automatically spreads that capital across the yield families it is wired to — **Core** (Venus Core lending), **Flux** (Fluid Lending, a third-party protocol) and **FRV** (Venus Fixed-Rate Vaults) — and returns a blended yield, removing the need for lenders to pick a product, allocate across it, and assess each one's risk on their own. Capital routed to Flux is exposed to Fluid's contracts, not only to Venus's. |
Contributor
There was a problem hiding this comment.
Suggested change
| The **Venus Liquidity Hub** is a per-asset *allocator vault*. A lender deposits a single asset (USDT, for example) and receives a yield-bearing share token. Under a governance-set policy, the Hub automatically spreads that capital across the yield families it is wired to — **Core** (Venus Core lending), **Flux** (Fluid Lending, a third-party protocol) and **FRV** (Venus Fixed-Rate Vaults) — and returns a blended yield, removing the need for lenders to pick a product, allocate across it, and assess each one's risk on their own. Capital routed to Flux is exposed to Fluid's contracts, not only to Venus's. | |
| The **Venus Liquidity Hub** is a per-asset *allocator vault*. A lender deposits a single asset (USDT, for example) and receives a yield-bearing share token. Under a governance-set policy, the Hub automatically spreads that capital across the yield families it is wired to — **Core** (Venus Core lending), **Flux** (Fluid Lending, a third-party protocol), **FRV** (Venus Fixed-Rate Vaults) and new yield sources as they come online — blending the underlying returns into a single yield, removing the need for lenders to pick a product, allocate across it, and assess each one's risk on their own. Capital routed to Flux is exposed to Fluid's contracts, not only to Venus's. |
| | USDC | `0x9D2D9592cF8DFbf59107fAab703d08494BE14617` | | ||
| | U | `0x0e5AA174d4F31b757a237eb1999DE151596788B0` | | ||
|
|
||
| `HubRegistry` is deployed at `0x4196932b0c76A114178236C00A5e140f27866790`. Prefer resolving Hub addresses through it rather than hard-coding them. |
Contributor
There was a problem hiding this comment.
I think this should be "0x6D93Fd479f2d37445CFBe132412e316a0364acc2"
Contributor
Author
There was a problem hiding this comment.
yes correct HubRegistry is redeployed to use default proxy admin
| | `AdapterCoreV1` | `0x4E514a0C7aB9d140eE204dfA0017574270D92944` | Shared singleton | | ||
| | `AdapterFlux` | `0xA81bDf813A428053E764C34Bc679b3E4d0807be3` | Shared singleton | | ||
| | `AdapterFRV` | `0x1FA0365bDd603452CE96BE3c0e12Db5515a35902` | Shared singleton | | ||
| | `HubRegistryProxyAdmin` | `0x3E2fbA605c1d9D470FB2691c4AA59Eb0570caB3E` | `ProxyAdmin` for the registry's `TransparentUpgradeableProxy`; governance-owned | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `HubRegistryProxyAdmin` | `0x3E2fbA605c1d9D470FB2691c4AA59Eb0570caB3E` | `ProxyAdmin` for the registry's `TransparentUpgradeableProxy`; governance-owned | | |
| | `DefaultProxyAdmin` | `0x6beb6D2695B67FEb73ad4f172E8E2975497187e4` | Venus's shared `ProxyAdmin`, administering the registry's `TransparentUpgradeableProxy`; governance-owned | |
|
|
||
| The Hub uses a **beacon-proxy model**: one `UpgradeableBeacon` per family per chain (Hub, Core, FRV, Flux), each owned by governance — upgrading a beacon upgrades every vault of that family atomically; per-asset instances are beacon proxies. Deploy scripts only deploy and initialize the proxies; **ACM wiring, `addYieldGroup` / `addResource`, and queue configuration are separate governance (ACM-gated) actions**. | ||
|
|
||
| `HubRegistry` is the exception: it is a chain-level singleton behind a **`TransparentUpgradeableProxy`** with its own `ProxyAdmin`, not a beacon proxy, so it is upgraded independently of every Hub. |
Contributor
There was a problem hiding this comment.
Suggested change
| `HubRegistry` is the exception: it is a chain-level singleton behind a **`TransparentUpgradeableProxy`** with its own `ProxyAdmin`, not a beacon proxy, so it is upgraded independently of every Hub. | |
| `HubRegistry` is the exception: it is a chain-level singleton behind a **`TransparentUpgradeableProxy`** administered by Venus's shared `DefaultProxyAdmin`, not a beacon proxy, so it is upgraded independently of every Hub. |
- The registry was redeployed so its proxy sits under the chain's shared DefaultProxyAdmin instead of a bespoke one. Both the registry address and the admin address changed. - Verified against the deployment artifacts and the live proxy admin and implementation slots on chain. - Testnet still uses a registry-specific ProxyAdmin, so the shared-admin note is scoped per chain and the difference is listed with the other testnet caveats. - Overview now counts future yield sources in the blend, not only the three families wired today.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Document the Liquidity Hub — the per-asset ERC-4626 allocator vault that routes a single deposited asset across the Core, Flux, and FRV yield families and returns a yield-bearing share token (yield via a rising exchange rate).
What's New:
Technical reference (new reference-liquidity-hub/ section):
Wire all pages into SUMMARY.md.
Scope: v1 (Core/Flux/FRV on BNB Chain, USDT first). Contracts not yet deployed — addresses to be published once live.