@venusprotocol/liquidity-hub 2.0.0 → 2.1.0-dev.2

package/contracts/adapters/AdapterCentrifuge.sol

@@ -0,0 +1,358 @@
+// SPDX-License-Identifier: BUSL-1.1
+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 { IAdapterCentrifuge } from "../interfaces/IAdapterCentrifuge.sol";
+import { IResourceAdapter } from "../interfaces/IResourceAdapter.sol";
+import { IYieldGroupBase } from "../interfaces/IYieldGroupBase.sol";
+import { IYieldGroupCentrifuge } from "../interfaces/IYieldGroupCentrifuge.sol";
+import { ICentrifugeAsyncRequestManager } from "../interfaces/external/ICentrifugeAsyncRequestManager.sol";
+import { ICentrifugeAsyncVault } from "../interfaces/external/ICentrifugeAsyncVault.sol";
+
+/**
+ * @title AdapterCentrifuge
+ * @author Venus
+ * @notice Stateless adapter for Centrifuge ERC-7540 vaults such as JTRSY and JAAA.
+ *         A single deployment can serve any YieldGroup that registers a compatible vault.
+ * @dev Mutating functions execute by delegatecall from the YieldGroup. Under delegatecall, the
+ *      YieldGroup is used as the controller, owner, and claim receiver.
+ *
+ *      A position includes the held share balance and six asynchronous request counters. Asset
+ *      amounts are valued at face value, while share amounts are converted at the vault's NAV:
+ *        - face value: `pendingDepositRequest`, `claimableCancelDepositRequest`, `maxWithdraw`;
+ *        - NAV value: held shares, `maxMint`, `pendingRedeemRequest`,
+ *          `claimableCancelRedeemRequest`.
+ *      Idle assets are excluded because the YieldGroup adds them separately.
+ *
+ *      Claims use the same denomination as the claimable counter: `mint(maxMint)` for shares and
+ *      `withdraw(maxWithdraw)` for assets. Using `deposit` or `redeem` would convert from the
+ *      opposite denomination and could leave one smallest unit unclaimed because of rounding.
+ *
+ *      {totalAssets} values the position from Centrifuge's own counters and price. It rejects a
+ *      zero share price whenever the position contains shares. The group clamps what comes back to
+ *      that resource's NAV band, and it is the group's `totalAssets()` that the Hub sums. That band
+ *      is configured there, since this adapter is stateless.
+ *
+ *      Asset moves read the underlying from the calling YieldGroup, never from `resource.asset()`;
+ *      see {_groupAsset}.
+ */
+contract AdapterCentrifuge is IAdapterCentrifuge {
+    using SafeERC20 for IERC20;
+
+    // ============================== Constants =================================
+
+    /// @dev Centrifuge assigns request id 0 to every request. Requests for the same vault and
+    ///      controller accumulate in one `AsyncInvestmentState` instead of receiving individual
+    ///      ids, so cancellation and cancel-claim calls always target id 0.
+    uint256 private constant REQUEST_ID = 0;
+
+    // ============================== State (immutable only) ====================
+
+    /// @dev Adapter deployment address used to distinguish direct calls from delegatecalls.
+    address private immutable _ADAPTER_SELF;
+
+    // ============================== Errors ====================================
+
+    /// @notice Thrown when a delegatecall-only function is called directly on the adapter.
+    error NotDelegateCall();
+
+    /**
+     * @notice Thrown when a resource does not expose a share token.
+     * @param resource Resource that failed validation.
+     */
+    error NoShareToken(address resource);
+
+    /**
+     * @notice Thrown when a resource does not expose a request manager.
+     * @param resource Resource that failed validation.
+     */
+    error NoManager(address resource);
+
+    /**
+     * @notice Thrown when a position contains shares but the vault reports a zero share price.
+     * @dev `requestRedeem` does not clear this: it still works, but a pending redeem is counted as
+     *      shares. This clears when Centrifuge settles that redeem and the value lands in
+     *      `maxWithdraw`, which is in asset units. If Centrifuge never settles,
+     *      `forceRemoveResource` writes the position off.
+     * @param resource Resource whose share price is zero.
+     */
+    error ZeroSharePrice(address resource);
+
+    // ============================== Modifiers =================================
+
+    /// @dev Restricts mutating adapter functions to delegatecall execution.
+    modifier onlyDelegateCall() {
+        if (address(this) == _ADAPTER_SELF) revert NotDelegateCall();
+        _;
+    }
+
+    // ============================== Constructor ===============================
+
+    /// @dev Stores the adapter address used by {onlyDelegateCall}.
+    constructor() {
+        _ADAPTER_SELF = address(this);
+    }
+
+    // ============================== IResourceAdapter — mutating ===============
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Sends assets to Centrifuge as an asynchronous deposit request. Shares can be collected
+    ///      through {claimDeposit} after settlement. The temporary allowance supports vaults that
+    ///      pull assets with `transferFrom`.
+    function deposit(address resource, uint256 amount) external override onlyDelegateCall returns (uint256) {
+        IERC20 assetToken = _groupAsset();
+        assetToken.forceApprove(resource, amount);
+        ICentrifugeAsyncVault(resource).requestDeposit(amount, address(this), address(this));
+        assetToken.forceApprove(resource, 0);
+        return amount;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Withdraws assets already reserved in `maxWithdraw`. Invested or pending shares are not
+    ///      liquid until a redeem request settles. The YieldGroup sizes normal calls against
+    ///      `maxWithdraw`; the vault call remains the final enforcement point.
+    ///
+    ///      The withdrawal uses two steps because the vault permission-checks the claim receiver.
+    ///      Claiming directly to an arbitrary `to` may revert if that address is not on the share-class
+    ///      memberlist. The adapter therefore claims to the group as receiver and controller, then
+    ///      forwards the underlying with a regular ERC-20 transfer.
+    ///
+    ///      This consumes the same `maxWithdraw` counter as {claimRedeem}, but the YieldGroup logs
+    ///      it as `WithdrawRouted`, not `RedeemClaimed`.
+    function withdraw(address resource, uint256 amount, address to) external override onlyDelegateCall {
+        ICentrifugeAsyncVault vault = ICentrifugeAsyncVault(resource);
+        IERC20 assetToken = _groupAsset();
+
+        // Forward only what the vault delivered. Forwarding `amount` could use sufficient idle
+        // balance to hide a short delivery from the caller's recipient-balance check. Preserving the
+        // shortfall makes the caller revert instead.
+        uint256 preBal = assetToken.balanceOf(address(this));
+        vault.withdraw(amount, address(this), address(this));
+        uint256 received = assetToken.balanceOf(address(this)) - preBal;
+
+        if (to != address(this)) assetToken.safeTransfer(to, received);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev No-op because Centrifuge state is valued live. Claims occur through the YieldGroup's
+    ///      explicit claim functions or when a withdrawal reaches a settled resource.
+    // solhint-disable-next-line no-empty-blocks
+    function accrue(address resource) external override { }
+
+    // ============================== Centrifuge-only — mutating ================
+
+    /// @inheritdoc IAdapterCentrifuge
+    /// @dev Sends shares to Centrifuge as an asynchronous redeem request. Assets can be collected
+    ///      through {claimRedeem} after settlement. No share approval is needed: Centrifuge's
+    ///      BalanceSheet moves the shares with `authTransferFrom`, a ward call that never reads
+    ///      `allowance`. Deposits are different — there the vault runs a real `transferFrom` on the
+    ///      asset, so that approval stays.
+    function requestRedeem(address resource, uint256 shares) external override onlyDelegateCall {
+        ICentrifugeAsyncVault(resource).requestRedeem(shares, address(this), address(this));
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    function cancelDepositRequest(address resource) external override onlyDelegateCall {
+        ICentrifugeAsyncVault(resource).cancelDepositRequest(REQUEST_ID, address(this));
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    function cancelRedeemRequest(address resource) external override onlyDelegateCall {
+        ICentrifugeAsyncVault(resource).cancelRedeemRequest(REQUEST_ID, address(this));
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    /// @dev Requests the full `maxMint` amount to clear the claimable share balance.
+    function claimDeposit(address resource) external override onlyDelegateCall returns (uint256 shares) {
+        shares = _investments(resource, address(this)).maxMint;
+        if (shares > 0) {
+            ICentrifugeAsyncVault(resource).mint(shares, address(this), address(this));
+        }
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    /// @dev Requests the full `maxWithdraw` amount to clear the claimable asset balance.
+    function claimRedeem(address resource) external override onlyDelegateCall returns (uint256 assets) {
+        assets = _investments(resource, address(this)).maxWithdraw;
+        if (assets > 0) {
+            ICentrifugeAsyncVault(resource).withdraw(assets, address(this), address(this));
+        }
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    function claimCancelDeposit(address resource) external override onlyDelegateCall returns (uint256 assets) {
+        assets = _investments(resource, address(this)).claimableCancelDepositRequest;
+        if (assets > 0) {
+            ICentrifugeAsyncVault(resource).claimCancelDepositRequest(REQUEST_ID, address(this), address(this));
+        }
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    function claimCancelRedeem(address resource) external override onlyDelegateCall returns (uint256 shares) {
+        shares = _investments(resource, address(this)).claimableCancelRedeemRequest;
+        if (shares > 0) {
+            ICentrifugeAsyncVault(resource).claimCancelRedeemRequest(REQUEST_ID, address(this), address(this));
+        }
+    }
+
+    // ============================== Views ======================================
+
+    /// @inheritdoc IResourceAdapter
+    function asset(address resource) external view override returns (address) {
+        return ICentrifugeAsyncVault(resource).asset();
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev What Centrifuge's counters and price say the position is worth. `YieldGroupCentrifuge`
+    ///      clamps this to the resource's NAV band on the way to the Hub, so read the group's
+    ///      `totalAssets()` for the figure the Hub sums, and this one for what the band is clamping.
+    ///
+    ///      Only the share-denominated buckets need a price, so a position holding none is valued
+    ///      without the feed at all.
+    function totalAssets(address resource, address holder) external view override returns (uint256 value) {
+        (uint256 face, uint256 shares, address shareToken) = _assetAndShareTotals(resource, holder);
+        value = face;
+        if (shares > 0) {
+            uint256 price = _pricePerShareOrZero(resource);
+            // Reject an unset or unreadable price before it silently values a live position at zero.
+            if (price == 0) revert ZeroSharePrice(resource);
+            value += (shares * price) / (10 ** IERC20Metadata(shareToken).decimals());
+        }
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev The uint128 limit Centrifuge's counters impose. Nothing calls this for Centrifuge:
+    ///      `YieldGroupCentrifuge` sizes deposits through {depositRoom}, which also sees the holder.
+    ///      Kept to satisfy `IResourceAdapter`.
+    function maxDeposit(address resource) external pure override returns (uint256) {
+        resource;
+        return type(uint128).max;
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    function depositRoom(address resource, address holder) external view override returns (uint256) {
+        ICentrifugeAsyncRequestManager.AsyncInvestmentState memory inv = _investments(resource, holder);
+        if (inv.pendingCancelDepositRequest) return 0;
+        return type(uint128).max - inv.pendingDepositRequest;
+    }
+
+    /// @inheritdoc IAdapterCentrifuge
+    function pricePerShare(address resource) external view override returns (uint256 price) {
+        return ICentrifugeAsyncVault(resource).pricePerShare();
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Returns the vault's `maxWithdraw(holder)`, so the vault's permission checks are reflected
+    ///      in reported liquidity. Valuation deliberately reads the raw investment state instead,
+    ///      allowing permission changes to affect liquidity without changing NAV.
+    function maxWithdraw(address resource, address holder) external view override returns (uint256) {
+        return ICentrifugeAsyncVault(resource).maxWithdraw(holder);
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Centrifuge publishes no rate on-chain — a fund's return arrives as a new NAV — so the
+    ///      number comes from the YieldGroup holding the position, where governance publishes it
+    ///      with {IYieldGroupCentrifuge.setSpotAPYBps}. `YieldGroupBase.spotAPYBps` reaches this by
+    ///      direct call rather than delegatecall, so `msg.sender` is that group.
+    ///
+    ///      Any other caller gets `0`. A published rate belongs to one group's position and this
+    ///      adapter is shared between groups, so there is no rate to hand someone holding nothing.
+    ///      Answering rather than reverting keeps the read open to observers, like every other view
+    ///      here, and that needs both guards below: Solidity checks the callee has code before it
+    ///      makes the call, and that revert lands outside `try`, so an address with no code has to
+    ///      be turned away first. The `catch` covers the rest — a contract that is not one of these
+    ///      groups, which answers nothing this can decode.
+    function spotAPYBps(address resource, uint256) external view override returns (uint64) {
+        if (msg.sender.code.length == 0) return 0;
+        try IYieldGroupCentrifuge(msg.sender).resourceSpotAPYBps(resource) returns (uint64 apyBps) {
+            return apyBps;
+        } catch {
+            return 0;
+        }
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Reports whether this group still has value tied to the vault by adding its held, pending,
+    ///      and claimable balances. Asset and share units are mixed intentionally because callers use
+    ///      the result only as a zero/nonzero check; forced removal logs it as a diagnostic value.
+    ///
+    ///      Idle assets are excluded because they are no longer tied to a vault. After redeem or
+    ///      deposit-cancel proceeds are claimed, this can return zero while those assets remain in the
+    ///      group. A complete wind-down must also move that idle balance back to the Hub.
+    function receiptBalance(address resource, address holder) external view override returns (uint256) {
+        ICentrifugeAsyncVault vault = ICentrifugeAsyncVault(resource);
+        ICentrifugeAsyncRequestManager.AsyncInvestmentState memory inv = _investments(resource, holder);
+        return IERC20(vault.share()).balanceOf(holder) + uint256(inv.maxMint) + inv.maxWithdraw
+            + inv.pendingDepositRequest + inv.pendingRedeemRequest + inv.claimableCancelDepositRequest
+            + inv.claimableCancelRedeemRequest;
+    }
+
+    /// @inheritdoc IResourceAdapter
+    /// @dev Verifies the vault exposes the share token, request manager, investment state, and price
+    ///      reads required by this adapter.
+    function validateRegistration(address resource) external view override {
+        ICentrifugeAsyncVault vault = ICentrifugeAsyncVault(resource);
+        if (vault.share() == address(0)) revert NoShareToken(resource);
+        address mgr = vault.baseManager();
+        if (mgr == address(0)) revert NoManager(resource);
+        ICentrifugeAsyncRequestManager(mgr).investments(resource, address(this));
+        vault.pricePerShare();
+    }
+
+    // ============================== Internal — view ===========================
+
+    /// @dev The vault's share price, or `0` when the read reverts. Swallowing it here is what
+    ///      turns a broken or unlinked feed into the named {ZeroSharePrice} on a share-holding
+    ///      position, instead of an opaque revert from inside the vault.
+    function _pricePerShareOrZero(address resource) private view returns (uint256) {
+        try ICentrifugeAsyncVault(resource).pricePerShare() returns (uint256 price) {
+            return price;
+        } catch {
+            return 0;
+        }
+    }
+
+    /// @dev The asset the calling YieldGroup was initialised with and can never change
+    ///      (`address(this)` is the group under delegatecall). Deliberately not `resource.asset()`:
+    ///      the vault is upgradeable and outside Venus control, so if it named another token —
+    ///      another resource's share token, say — approving or transferring it would hand the vault
+    ///      the group's balance of that token.
+    function _groupAsset() private view returns (IERC20) {
+        return IERC20(IYieldGroupBase(address(this)).asset());
+    }
+
+    /// @dev Reads the position once and hands it back as two subtotals, because its parts are
+    ///      denominated differently and so price differently:
+    ///        - `face` is the part already in asset units. It is final; no share price can move it.
+    ///        - `shares` is the part still measured in shares. A caller must price it before adding.
+    ///      `shareToken` comes back too, so a caller needing its decimals does not re-read it. The
+    ///      contract header lists which counter lands in which subtotal.
+    function _assetAndShareTotals(address resource, address holder)
+        private
+        view
+        returns (uint256 face, uint256 shares, address shareToken)
+    {
+        ICentrifugeAsyncRequestManager.AsyncInvestmentState memory inv = _investments(resource, holder);
+
+        // These counters are denominated in the underlying asset.
+        face = uint256(inv.pendingDepositRequest) + inv.claimableCancelDepositRequest + inv.maxWithdraw;
+
+        // These balances are denominated in shares and must be converted at the vault's NAV.
+        shareToken = ICentrifugeAsyncVault(resource).share();
+        shares = IERC20(shareToken).balanceOf(holder) + uint256(inv.pendingRedeemRequest) + inv.maxMint
+            + inv.claimableCancelRedeemRequest;
+    }
+
+    /// @dev Reads all pending and claimable balances for a holder from the vault's request manager.
+    function _investments(address resource, address holder)
+        internal
+        view
+        returns (ICentrifugeAsyncRequestManager.AsyncInvestmentState memory)
+    {
+        address manager = ICentrifugeAsyncVault(resource).baseManager();
+        return ICentrifugeAsyncRequestManager(manager).investments(resource, holder);
+    }
+}

package/contracts/interfaces/IAdapterCentrifuge.sol

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { IResourceAdapter } from "./IResourceAdapter.sol";
+
+/**
+ * @title IAdapterCentrifuge
+ * @author Venus
+ * @notice `IResourceAdapter` plus the Centrifuge-only surface: the async request / cancel / claim
+ *         primitives, which are delegatecall-only and run in the YieldGroup's context, and the
+ *         holder-aware `depositRoom` view behind `YieldGroupCentrifuge._resourceDepositRoom`.
+ */
+interface IAdapterCentrifuge is IResourceAdapter {
+    // ------------------------- Mutating (delegatecall-only) -------------------
+
+    /// @notice Open an async redeem request: `shares` move from the group into Centrifuge escrow.
+    function requestRedeem(address resource, uint256 shares) external;
+
+    /// @notice Ask Centrifuge to return the group's pending deposit; blocks new deposit requests
+    ///         until fulfilled.
+    function cancelDepositRequest(address resource) external;
+
+    /// @notice Ask Centrifuge to return the group's pending redeem shares; blocks new redeem
+    ///         requests until fulfilled.
+    function cancelRedeemRequest(address resource) external;
+
+    /// @notice Claim all issued shares (`investments().maxMint`) via exact-amount `mint`. Returns
+    ///         0 and does nothing when there is nothing to claim.
+    function claimDeposit(address resource) external returns (uint256 shares);
+
+    /// @notice Claim all reserved assets (`investments().maxWithdraw`) via exact-amount
+    ///         `withdraw`. Returns 0 and does nothing when there is nothing to claim.
+    function claimRedeem(address resource) external returns (uint256 assets);
+
+    /// @notice Collect a fulfilled deposit cancel (`claimableCancelDepositRequest`) as idle assets.
+    function claimCancelDeposit(address resource) external returns (uint256 assets);
+
+    /// @notice Collect a fulfilled redeem cancel (`claimableCancelRedeemRequest`) as held shares.
+    function claimCancelRedeem(address resource) external returns (uint256 shares);
+
+    // --------------------------------- Views ----------------------------------
+
+    /// @notice Holder-aware deposit headroom: 0 while `holder` has a deposit cancel in flight,
+    ///         since Centrifuge rejects new requests then; otherwise the uint128 counter headroom.
+    ///         `IResourceAdapter.maxDeposit` has no holder parameter and cannot express this, so
+    ///         `YieldGroupCentrifuge._resourceDepositRoom` routes through here instead.
+    function depositRoom(address resource, address holder) external view returns (uint256 room);
+
+    /**
+     * @notice The vault's current NAV price for one whole share, in asset units.
+     * @dev Plain CALL, not delegatecall — it reads no group state. A thin passthrough to
+     *      `ICentrifugeAsyncVault.pricePerShare`, exposed so callers can read the mark without
+     *      importing the vault interface itself. Returns the raw reading, `0` included: an unset
+     *      price only matters when the position actually holds shares, which is
+     *      {IResourceAdapter.totalAssets}'s call to make, not this one's.
+     *
+     *      A diagnostic rather than part of valuation: `YieldGroupCentrifuge` bounds what the
+     *      position is worth, so this is the number to read alongside a clamped valuation to see
+     *      whether the price moved or the share count did.
+     * @param resource Centrifuge vault to price.
+     * @return price Asset units one whole share converts to at the vault's current NAV.
+     */
+    function pricePerShare(address resource) external view returns (uint256 price);
+}