@venusprotocol/liquidity-hub 0.0.0

package/contracts/interfaces/external/IFRVVault.sol

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+/**
+ * @title IFRVVault
+ * @author Venus
+ * @notice Minimal interface exposing only what `YieldGroupFRV` needs from a Venus Fixed Rate
+ *         Vault. The FRV vault is a standard ERC-4626 with a lifecycle state machine on top.
+ * @dev The `FRVVaultState` enum, `FRVVaultConfig` and `FRVVaultRuntime` structs are defined inline
+ *      (not imported from the FRV repo) to avoid an npm dependency. Field order, types and enum
+ *      numbering MUST match the deployed `VaultState` / `VaultConfig` / `VaultRuntime` ABI exactly —
+ *      if the FRV repo changes these types, this interface must be updated in lockstep.
+ */
+interface IFRVVault {
+    // ──────────────────────────── Types ─────────────────────────────
+
+    /// @notice Vault lifecycle states. Mirrors `VaultState` in the FRV repo.
+    enum FRVVaultState {
+        WaitingForMargin, // 0
+        MarginDeposited, // 1
+        Fundraising, // 2
+        InstitutionConfirmation, // 3
+        Lock, // 4
+        PendingSettlement, // 5
+        SettlementDeadlineExceeded, // 6
+        Matured, // 7
+        Failed, // 8
+        Liquidated, // 9
+        Closed // 10
+    }
+
+    /// @notice Immutable vault configuration. Mirrors `VaultConfig` in the FRV repo.
+    struct FRVVaultConfig {
+        IERC20 supplyAsset;
+        uint256 fixedAPY; // basis points (800 = 8%)
+        uint256 reserveFactor; // mantissa (0.1e18 = 10%)
+        uint256 minBorrowCap;
+        uint256 maxBorrowCap;
+        uint256 minSupplierDeposit;
+        uint40 openDuration;
+        uint40 lockDuration;
+        uint40 settlementWindow;
+    }
+
+    /// @notice Runtime state that changes as the vault progresses through its lifecycle. Mirrors
+    ///         `VaultRuntime` in the FRV repo. Field order and types MUST match the deployed ABI
+    ///         exactly (the timestamps are `uint40`; a struct getter ABI-encodes each field in its
+    ///         own word, so order/types — not storage packing — are what must line up).
+    struct FRVVaultRuntime {
+        // ── Lifecycle ──
+        FRVVaultState state;
+        // ── Timing ──
+        uint40 openStartTime;
+        uint40 openEndTime;
+        uint40 lockStartTime;
+        uint40 lockEndTime;
+        uint40 settlementDeadline;
+        // ── Accounting ──
+        uint256 totalRaised;
+        uint256 totalDebt;
+        uint256 settlementAmount;
+        // ── Flags ──
+        bool fundsWithdrawn;
+        bool protocolShareSettled;
+    }
+
+    // ──────────────────────── ERC-4626 subset ──────────────────────
+
+    function deposit(uint256 assets, address receiver) external returns (uint256 shares);
+
+    function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);
+
+    /// @notice Vault-wide assets (NOT per-holder). `AdapterFRV` values its own position with
+    ///         `previewRedeem(balanceOf(holder))` instead, so this is part of the ERC-4626
+    ///         surface for completeness but is not on the adapter's call path.
+    function totalAssets() external view returns (uint256);
+
+    function maxDeposit(address receiver) external view returns (uint256);
+
+    function maxWithdraw(address owner) external view returns (uint256);
+
+    function balanceOf(address account) external view returns (uint256);
+
+    /// @notice Total vault shares outstanding. Used by `AdapterFRV` to value the holder's slice
+    ///         pro-rata (`shares / totalSupply`) when accruing the time-based coupon.
+    function totalSupply() external view returns (uint256);
+
+    function previewRedeem(uint256 shares) external view returns (uint256);
+
+    function asset() external view returns (address);
+
+    // ─────────────────────── FRV-specific ──────────────────────────
+
+    /// @notice Current lifecycle state of the vault.
+    function state() external view returns (FRVVaultState);
+
+    /// @notice Immutable vault configuration (APY, caps, timing).
+    function config() external view returns (FRVVaultConfig memory);
+
+    /// @notice Mutable runtime state (lifecycle state, lock window timestamps, accounting, flags).
+    ///         `AdapterFRV` reads `state` (Lock / PendingSettlement / SettlementDeadlineExceeded gate
+    ///         the coupon accrual), `lockStartTime` / `lockEndTime` (elapsed-time accrual) and
+    ///         `totalRaised` (principal base) from this. It does NOT read `fundsWithdrawn`: the mark
+    ///         accrues on lock state alone, since the vault owes interest over the whole lock window
+    ///         regardless of when the institution draws.
+    function runtime() external view returns (FRVVaultRuntime memory);
+
+    /// @notice Permissionless state-machine advance. Triggers time-based transitions
+    ///         (e.g. Fundraising → Lock, PendingSettlement → Matured).
+    function updateVaultState() external;
+}

package/contracts/interfaces/external/IFToken.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IFToken
+ * @author Venus
+ * @notice Minimal interface exposing only what `AdapterFlux` needs from a Fluid lending fToken.
+ *         A Fluid fToken is a standard ERC-4626 share token that forwards every deposit to the
+ *         Fluid Liquidity layer and only mints / burns shares — it never custodies the underlying.
+ * @dev Declared locally (not imported from the Fluid repo) to avoid an external dependency, the
+ *      same approach `IFRVVault` takes. The selectors below are the canonical ERC-4626 ones, so
+ *      they bind to any compliant fToken regardless of the Fluid repo's compiler version.
+ *
+ *      Behaviour notes that matter to the adapter:
+ *      - `deposit` pulls `assets` from `msg.sender` via the fToken's `liquidityCallback`, so the
+ *        caller (the YieldGroup, under delegatecall) must have approved the fToken first.
+ *      - `withdraw` delivers exactly `assets` to `receiver` and burns shares from `owner`; no
+ *        redeem-time fee (unlike a Compound-style treasury cut).
+ *      - `maxDeposit` returns headroom up to `int128.max` (effectively unbounded); the real
+ *        deposit control for Flux is the YieldGroup's per-resource cap.
+ *      - `maxWithdraw` is `min(Fluid withdrawal-limit, owner balance)`.
+ */
+interface IFToken {
+    // ──────────────────────── ERC-4626 subset ──────────────────────
+
+    /// @notice Deposit `assets` of the underlying, minting fToken shares to `receiver`.
+    function deposit(uint256 assets, address receiver) external returns (uint256 shares);
+
+    /// @notice Withdraw exactly `assets` of the underlying to `receiver`, burning `owner`'s shares.
+    function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);
+
+    /// @notice The ERC-20 underlying this fToken accepts.
+    function asset() external view returns (address);
+
+    /// @notice fToken share balance of `account`.
+    function balanceOf(address account) external view returns (uint256);
+
+    /// @notice Underlying value of `shares` at the current exchange price (incl. rewards).
+    function previewRedeem(uint256 shares) external view returns (uint256);
+
+    /// @notice Spare deposit headroom (≈ `int128.max − totalSupply`; effectively unbounded).
+    function maxDeposit(address receiver) external view returns (uint256);
+
+    /// @notice Currently-withdrawable underlying for `owner`: `min(Fluid limit, owner balance)`.
+    function maxWithdraw(address owner) external view returns (uint256);
+}

package/contracts/interfaces/external/IFluidLendingResolver.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IFluidLendingResolver
+ * @author Venus
+ * @notice Minimal interface for the Fluid periphery `LendingResolver` — a read-only contract
+ *         Fluid deploys and maintains (e.g. `0x48D32f49aFeAEC7AE66ad7B9264f446fc11a1569` on BSC).
+ *         `AdapterFlux` calls `getFTokenDetails` to read an fToken's spot supply APR and reward
+ *         rate; the fToken itself exposes only cumulative exchange prices, not a spot rate, so the
+ *         resolver (which runs Fluid's `LiquidityCalcs` math for us) is the clean yieldGroup.
+ * @dev The `FTokenDetails` and nested `UserSupplyData` structs are mirrored VERBATIM from Fluid's
+ *      `periphery/resolvers/lending/structs.sol` and `periphery/resolvers/liquidity/structs.sol`.
+ *      Field order and types MUST match the deployed resolver's return ABI exactly — a mismatch
+ *      silently corrupts the decode. If Fluid revs the resolver struct, update this in lockstep
+ *      (same "must match ABI" contract as `IFRVVault`). The function is declared with an `address`
+ *      parameter so its selector is `getFTokenDetails(address)`, identical to the deployed one.
+ *
+ *      Only `supplyRate` (1e2 precision, i.e. already basis points) and `rewardsRate`
+ *      (1e12 precision, `/1e10` to convert to bps) are consumed by the adapter; the remaining
+ *      fields exist purely so the tuple decodes correctly.
+ */
+interface IFluidLendingResolver {
+    /// @notice Mirror of Fluid liquidity resolver `UserSupplyData`. All fields are value types.
+    struct UserSupplyData {
+        bool modeWithInterest;
+        uint256 supply;
+        uint256 withdrawalLimit;
+        uint256 lastUpdateTimestamp;
+        uint256 expandPercent;
+        uint256 expandDuration;
+        uint256 baseWithdrawalLimit;
+        uint256 withdrawableUntilLimit;
+        uint256 withdrawable;
+        uint256 decayEndTimestamp;
+        uint256 decayAmount;
+    }
+
+    /// @notice Mirror of Fluid lending resolver `FTokenDetails`. `rewardsRate` precedes
+    ///         `supplyRate`; both are the only fields the adapter reads.
+    struct FTokenDetails {
+        address tokenAddress;
+        bool eip2612Deposits;
+        bool isNativeUnderlying;
+        string name;
+        string symbol;
+        uint256 decimals;
+        address asset;
+        uint256 totalAssets;
+        uint256 totalSupply;
+        uint256 convertToShares;
+        uint256 convertToAssets;
+        uint256 rewardsRate; // additional yield from rewards, in 1e12 precision (1e12 = 1%)
+        uint256 supplyRate; // base Liquidity yield, in 1e2 precision (100 = 1% = 100 bps)
+        int256 rebalanceDifference;
+        UserSupplyData liquidityUserSupplyData;
+    }
+
+    /// @notice All public details for `fToken`, including spot `supplyRate` and `rewardsRate`.
+    /// @param fToken The fToken to read.
+    /// @return fTokenDetails Populated {FTokenDetails}.
+    function getFTokenDetails(address fToken) external view returns (FTokenDetails memory fTokenDetails);
+}

package/contracts/interfaces/external/IVBep20.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+/**
+ * @title IVBep20
+ * @author Venus
+ * @notice Narrow view of a Venus Core market (`VBep20`) as the Migrator consumes it: the
+ *         transferable ERC-20 receipt plus the two accessors the Migrator needs to redeem a
+ *         position back to its underlying.
+ * @dev Conventions mirror the live Core contracts:
+ *      - The receipt is a full ERC-20, so a position is pulled in with `safeTransferFrom`. Note
+ *        the Core `transferFrom` returns `false` (it does not revert) on failure, so callers must
+ *        route it through `SafeERC20`.
+ *      - `redeem` follows Compound semantics: it returns an error code (`0` on success) AND can
+ *        revert (the Comptroller `redeemAllowed` hook, insufficient cash, and block-freshness
+ *        checks all revert). Callers must both check the returned code and verify a balance delta;
+ *        `redeem` never reports the redeemed amount through its return value.
+ *      - `underlying()` exists only on ERC-20-backed markets; the native market (vBNB) has no such
+ *        accessor, so a call to it reverts — which the Migrator relies on to reject vBNB from the
+ *        ERC-20 path and force the dedicated native path.
+ */
+interface IVBep20 is IERC20 {
+    /**
+     * @notice Burn `redeemTokens` vToken receipts from `msg.sender` and send the corresponding
+     *         underlying (net of any Comptroller treasury fee) to `msg.sender`.
+     * @param redeemTokens vToken units to burn.
+     * @return errorCode Compound-style error code; `0` on success.
+     */
+    function redeem(uint256 redeemTokens) external returns (uint256 errorCode);
+
+    /**
+     * @notice The ERC-20 underlying this market is backed by.
+     * @dev Reverts for the native (vBNB) market, which has no underlying accessor.
+     * @return token Address of the underlying ERC-20.
+     */
+    function underlying() external view returns (address token);
+}

package/contracts/interfaces/external/IVToken.sol

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title IVToken
+ * @author Venus
+ * @notice Minimal subset of the Venus Core `VBep20` interface needed by the Core Yield Group
+ *         adapter. Kept narrow on purpose: importing Venus's full `VBep20Interface` drags in
+ *         Comptroller diamond storage and a dozen transitive imports.
+ * @dev Conventions:
+ *      - Mutating calls follow Compound semantics: return value is an error code (0 = success,
+ *        non-zero = failure). Cap and pause violations REVERT inside the Comptroller hook
+ *        (PolicyFacet) rather than returning a non-zero code — the adapter must handle both
+ *        revert and non-zero-return failure modes.
+ *      - `mint(amount)` pulls `amount` underlying from `msg.sender` via `transferFrom` and
+ *        credits `msg.sender` with vTokens. For fee-on-transfer underlyings the actual minted
+ *        amount equals what was received (less than requested) — not supported by the
+ *        Core Yield Group v1.
+ *      - `redeemUnderlying(amount)` burns vTokens from `msg.sender` and sends underlying to
+ *        `msg.sender`. When the Comptroller's `treasuryPercent() != 0`, the receiver gets
+ *        `amount − (amount × treasuryPercent / 1e18)` and the difference is sent to the
+ *        treasury. Adapters must gross-up to deliver an exact net amount.
+ *      - `mintBehalf` / `redeemUnderlyingBehalf` are the "on behalf of another address"
+ *        variants. NOTE: `AdapterCoreV1` does NOT use them — it dispatches via DELEGATECALL and
+ *        calls plain `mint` / `redeemUnderlying`, so `msg.sender` already is the YieldGroup and
+ *        vTokens land on it directly (no delegate approval needed). These Behalf selectors, and
+ *        the `Comptroller.updateDelegate` / `approvedDelegates` pair, are retained only for
+ *        reference and the integration mocks; they are on no production call path.
+ *      - `balanceOfUnderlying` and `exchangeRateCurrent` are intentionally OMITTED here: they
+ *        mutate state (accrue interest) and have no place in a view-only adapter accessor.
+ */
+interface IVToken {
+    // -------------------------------- Mutating -------------------------------
+
+    /**
+     * @notice Supply `mintAmount` of underlying and receive vTokens.
+     * @param mintAmount Underlying units to deposit.
+     * @return errorCode Compound-style error code; `0` on success.
+     */
+    function mint(uint256 mintAmount) external returns (uint256 errorCode);
+
+    /**
+     * @notice Burn vTokens and receive `redeemAmount` of underlying (less any treasury fee).
+     * @param redeemAmount Underlying units to withdraw (gross of any treasury fee).
+     * @return errorCode Compound-style error code; `0` on success.
+     */
+    function redeemUnderlying(uint256 redeemAmount) external returns (uint256 errorCode);
+
+    /**
+     * @notice Supply `mintAmount` of underlying on behalf of `receiver`. Pulls underlying
+     *         from `msg.sender` (the caller) and credits vTokens to `receiver`. No delegate
+     *         approval required — anyone can mint to anyone; the payer just provides funds.
+     * @param receiver Address that will be credited with vTokens.
+     * @param mintAmount Underlying units to deposit.
+     * @return errorCode Compound-style error code; `0` on success.
+     */
+    function mintBehalf(address receiver, uint256 mintAmount) external returns (uint256 errorCode);
+
+    /**
+     * @notice Redeem `redeemAmount` of underlying on behalf of `redeemer`. Burns vTokens
+     *         from `redeemer` and sends underlying to `msg.sender` (less any treasury fee).
+     *         Requires `redeemer` to have approved `msg.sender` as a delegate via
+     *         `Comptroller.updateDelegate(msg.sender, true)`.
+     * @param redeemer vToken holder whose receipts will be burned.
+     * @param redeemAmount Underlying units to withdraw (gross of any treasury fee).
+     * @return errorCode Compound-style error code; `0` on success.
+     */
+    function redeemUnderlyingBehalf(address redeemer, uint256 redeemAmount) external returns (uint256 errorCode);
+
+    /**
+     * @notice Settle accrued interest into the stored exchange rate up to the current block.
+     * @return errorCode Compound-style error code; `0` on success.
+     */
+    function accrueInterest() external returns (uint256 errorCode);
+
+    // ---------------------------------- Views --------------------------------
+
+    /**
+     * @notice vToken balance of `account` (NOT underlying units; multiply by
+     *         `exchangeRateStored()` and divide by `1e18` for underlying value).
+     * @param account Holder to query.
+     * @return balance vToken units held by `account`.
+     */
+    function balanceOf(address account) external view returns (uint256 balance);
+
+    /**
+     * @notice Last-cached underlying-per-vToken exchange rate, scaled by `1e18`.
+     * @dev Stale by up to one accrual cycle. Cheap; suitable for view-only adapter accessors.
+     *      The mutating variant `exchangeRateCurrent` accrues interest as a side effect and
+     *      should not be called from view paths.
+     * @return rate Exchange rate scaled by `1e18`.
+     */
+    function exchangeRateStored() external view returns (uint256 rate);
+
+    /// @notice Total vToken supply (in vToken units, not underlying).
+    /// @return supply Total outstanding vTokens.
+    function totalSupply() external view returns (uint256 supply);
+
+    /**
+     * @notice Underlying cash currently held by the vToken contract.
+     * @dev This is the realistic upper bound on a single `redeemUnderlying` call: the vToken
+     *      cannot pay out more underlying than it holds in cash.
+     * @return cash Underlying units held by the vToken.
+     */
+    function getCash() external view returns (uint256 cash);
+
+    /**
+     * @notice The ERC-20 underlying token. Reverts for vBNB (which has no `underlying`
+     *         accessor); the Core Yield Group v1 uses this revert as a guard against vBNB
+     *         being registered as a resource.
+     * @return token Address of the underlying ERC-20.
+     */
+    function underlying() external view returns (address token);
+
+    /// @notice Comptroller controlling this vToken.
+    /// @return comptrollerAddress Address of the Comptroller.
+    function comptroller() external view returns (address comptrollerAddress);
+
+    /**
+     * @notice Current per-block supply interest rate, scaled by `1e18`.
+     * @dev Annualise by multiplying by the deployed `InterestRateModel`'s `blocksPerYear`.
+     * @return rate Per-block supply rate, scaled by `1e18`.
+     */
+    function supplyRatePerBlock() external view returns (uint256 rate);
+}

package/contracts/interfaces/external/IWBNB.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+/**
+ * @title IWBNB
+ * @author Venus
+ * @notice Minimal view of the canonical wrapped-native token (WBNB). The Migrator only needs to
+ *         wrap native BNB it receives from a vBNB redeem, then hand the WBNB to a Hub, so this
+ *         exposes `deposit()` plus the ERC-20 surface (for the `forceApprove` to the Hub).
+ */
+interface IWBNB is IERC20 {
+    /// @notice Wrap the attached native value 1:1 into WBNB credited to `msg.sender`.
+    function deposit() external payable;
+}

package/contracts/migrator/Migrator.sol

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { ReentrancyGuard } from "@openzeppelin/contracts/security/ReentrancyGuard.sol";
+
+import { IHub } from "../interfaces/IHub.sol";
+import { IHubRegistry } from "../interfaces/IHubRegistry.sol";
+import { IMigrator } from "../interfaces/IMigrator.sol";
+import { IVBep20 } from "../interfaces/external/IVBep20.sol";
+import { IWBNB } from "../interfaces/external/IWBNB.sol";
+
+/**
+ * @title Migrator
+ * @author Venus
+ * @notice One-click migration from a Venus Core position into a Liquidity Hub. A single immutable,
+ *         permissionless deployment serves every registered Hub; the target Hub is supplied per call
+ *         and must be present in the HubRegistry.
+ * @dev Stateless by design — no proxy, no admin, no funds held between calls. Each migration is
+ *      atomic: pull the user's vToken, redeem it to the underlying, deposit that into the Hub, and
+ *      mint shares straight to the receiver. If any leg fails the whole call reverts and the user
+ *      keeps their vToken.
+ *
+ *      The target `hub` is checked against the immutable {HUB_REGISTRY} before any funds move, so a
+ *      migration can only land in a Hub governance has registered.
+ *
+ *      Accounting is done by balance delta, never by a self-reported amount: Core `redeem` returns
+ *      a Compound error code (not the redeemed amount) and silently nets out any Comptroller
+ *      treasury fee, so the Migrator measures what actually arrived and deposits exactly that. The
+ *      caller's `minShares` is the slippage guard.
+ *
+ *      Two paths mirror how Venus splits its markets. ERC-20-backed markets (vUSDT, vUSDC, ...) use
+ *      {migrateFromCore}, which validates `vToken.underlying() == hub.asset()`. The native market
+ *      (vBNB) has no `underlying()` accessor and redeems raw BNB, so {migrateFromCoreBNB} wraps the
+ *      BNB to WBNB before depositing into the WBNB Hub. vBNB pays out via `transfer` (a 2300-gas
+ *      stipend), so {receive} stays minimal and the wrapping happens in the function body.
+ */
+contract Migrator is IMigrator, ReentrancyGuard {
+    using SafeERC20 for IERC20;
+
+    /// @notice Governance-curated directory of valid Hubs.
+    IHubRegistry public immutable HUB_REGISTRY;
+    /// @notice Canonical wrapped-native token (WBNB).
+    IWBNB public immutable WBNB;
+    /// @notice Canonical Venus native market (vBNB).
+    IVBep20 public immutable VBNB;
+
+    /**
+     * @param wbnb_ Wrapped-native token (WBNB). Mandatory; the constructor reverts on the zero address.
+     * @param vbnb_ Venus native market (vBNB). Mandatory; the constructor reverts on the zero address.
+     * @param hubRegistry_ The HubRegistry every migration target is validated against. Mandatory;
+     *        the constructor reverts on the zero address, since without it no Hub would be accepted.
+     */
+    constructor(IWBNB wbnb_, IVBep20 vbnb_, IHubRegistry hubRegistry_) {
+        if (address(wbnb_) == address(0) || address(vbnb_) == address(0) || address(hubRegistry_) == address(0)) {
+            revert ZeroAddress();
+        }
+        HUB_REGISTRY = hubRegistry_;
+        WBNB = wbnb_;
+        VBNB = vbnb_;
+    }
+
+    /// @notice Accept native BNB only from the configured vBNB market (the redeem payout).
+    receive() external payable {
+        if (msg.sender != address(VBNB)) revert OnlyVBNB();
+    }
+
+    /// @inheritdoc IMigrator
+    function migrateFromCore(address vToken, uint256 vTokenAmount, address hub, address receiver, uint256 minShares)
+        external
+        nonReentrant
+        returns (uint256 shares)
+    {
+        shares = _migrateFromCore(vToken, vTokenAmount, hub, receiver, minShares);
+    }
+
+    /// @inheritdoc IMigrator
+    function migrateFromCoreWithConsent(
+        address vToken,
+        uint256 vTokenAmount,
+        address hub,
+        address receiver,
+        uint256 minShares,
+        bytes32 consentHash
+    ) external nonReentrant returns (uint256 shares) {
+        // Record the migrating user's consent before any state change, so it rolls back with the tx if
+        // a later leg reverts. Attributed to msg.sender: the user calls this Migrator directly, so it
+        // is the authenticated consenting party even though the Hub deposit is intermediated. The hash
+        // is optional — bytes32(0) skips the emit and migrates without recording.
+        if (consentHash != bytes32(0)) emit IHub.ConsentRecorded(msg.sender, receiver, consentHash);
+        shares = _migrateFromCore(vToken, vTokenAmount, hub, receiver, minShares);
+    }
+
+    /// @inheritdoc IMigrator
+    function migrateFromCoreBNB(uint256 vBNBAmount, address hub, address receiver, uint256 minShares)
+        external
+        nonReentrant
+        returns (uint256 shares)
+    {
+        shares = _migrateFromCoreBNB(vBNBAmount, hub, receiver, minShares);
+    }
+
+    /// @inheritdoc IMigrator
+    function migrateFromCoreBNBWithConsent(
+        uint256 vBNBAmount,
+        address hub,
+        address receiver,
+        uint256 minShares,
+        bytes32 consentHash
+    ) external nonReentrant returns (uint256 shares) {
+        // Record the migrating user's consent before any state change (attributed to msg.sender);
+        // rolled back with the tx if a later leg reverts. bytes32(0) skips the emit.
+        if (consentHash != bytes32(0)) emit IHub.ConsentRecorded(msg.sender, receiver, consentHash);
+        shares = _migrateFromCoreBNB(vBNBAmount, hub, receiver, minShares);
+    }
+
+    /// @dev Shared body for {migrateFromCore} / {migrateFromCoreWithConsent}: pull, redeem, deposit.
+    function _migrateFromCore(address vToken, uint256 vTokenAmount, address hub, address receiver, uint256 minShares)
+        private
+        returns (uint256 shares)
+    {
+        if (vToken == address(0) || hub == address(0) || receiver == address(0)) {
+            revert ZeroAddress();
+        }
+        if (vTokenAmount == 0) revert ZeroAmount();
+        if (!HUB_REGISTRY.isHub(hub)) revert HubNotRegistered(hub);
+
+        address asset = IHub(hub).asset();
+        address vTokenUnderlying = IVBep20(vToken).underlying();
+        if (vTokenUnderlying != asset) revert AssetMismatch(vTokenUnderlying, asset);
+
+        // Pull the receipt, then redeem it for ourselves (we now own the vTokens).
+        IERC20(vToken).safeTransferFrom(msg.sender, address(this), vTokenAmount);
+
+        uint256 balanceBefore = IERC20(asset).balanceOf(address(this));
+        uint256 errorCode = IVBep20(vToken).redeem(vTokenAmount);
+        if (errorCode != 0) revert VTokenRedeemFailed(vToken, errorCode);
+        uint256 underlyingAmount = IERC20(asset).balanceOf(address(this)) - balanceBefore;
+        if (underlyingAmount == 0) revert NothingReceived();
+
+        shares = _depositToHub(IERC20(asset), hub, underlyingAmount, receiver, minShares);
+        emit Migrated(msg.sender, vToken, hub, vTokenAmount, underlyingAmount, shares);
+    }
+
+    /// @dev Shared body for {migrateFromCoreBNB} / {migrateFromCoreBNBWithConsent}: pull, redeem,
+    ///      wrap to WBNB, deposit.
+    function _migrateFromCoreBNB(uint256 vBNBAmount, address hub, address receiver, uint256 minShares)
+        private
+        returns (uint256 shares)
+    {
+        if (hub == address(0) || receiver == address(0)) revert ZeroAddress();
+        if (vBNBAmount == 0) revert ZeroAmount();
+        if (!HUB_REGISTRY.isHub(hub)) revert HubNotRegistered(hub);
+
+        address asset = IHub(hub).asset();
+        if (asset != address(WBNB)) revert AssetMismatch(address(WBNB), asset);
+
+        IERC20(address(VBNB)).safeTransferFrom(msg.sender, address(this), vBNBAmount);
+
+        uint256 balanceBefore = address(this).balance;
+        uint256 errorCode = VBNB.redeem(vBNBAmount);
+        if (errorCode != 0) revert VTokenRedeemFailed(address(VBNB), errorCode);
+        uint256 nativeAmount = address(this).balance - balanceBefore;
+        if (nativeAmount == 0) revert NothingReceived();
+
+        WBNB.deposit{ value: nativeAmount }();
+        shares = _depositToHub(IERC20(address(WBNB)), hub, nativeAmount, receiver, minShares);
+        emit Migrated(msg.sender, address(VBNB), hub, vBNBAmount, nativeAmount, shares);
+    }
+
+    /// @dev Approve `hub` for exactly `amount`, deposit to `receiver`, and enforce the slippage
+    ///      floor. `deposit` pulls the full `amount`, so no allowance or balance is left behind.
+    function _depositToHub(IERC20 asset, address hub, uint256 amount, address receiver, uint256 minShares)
+        private
+        returns (uint256 shares)
+    {
+        asset.forceApprove(hub, amount);
+        shares = IHub(hub).deposit(amount, receiver);
+        if (shares < minShares) revert InsufficientShares(shares, minShares);
+    }
+}