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

package/contracts/YieldGroup/base/NavGuard.sol

@@ -0,0 +1,412 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { INavGuard } from "../../interfaces/INavGuard.sol";
+
+/**
+ * @title NavGuard
+ * @author Venus
+ * @notice Reusable per-resource band on a position's own value. Extend this when a position's
+ *         value is reported by a counterparty that nothing else validates.
+ * @dev The band vouches for a value: the last counterparty figure we accepted, grown at `driftBps`
+ *      a year, plus whatever we have moved in or out since. {_guardedNav} holds valuation a gap
+ *      either side of that and never reverts. The gaps are a percentage of the counterparty's part
+ *      only, so our own moves never widen them. Take everything out and the band closes; a deposit
+ *      or {setNavGuardSnapshot} reopens it.
+ *
+ *      Two stored numbers carry that, and {_currentBand} is the only place they are combined:
+ *
+ *      - `anchor` is the counterparty's part: the last figure they reported that we accepted, less
+ *        anything we have withdrawn beyond our own deposits. Both gaps are sized off it alone, and
+ *        {_updateNavGuard} moves it once per `interval`.
+ *      - `centre` is where the band sits: the anchor plus our own deposits since. {_recordInflow}
+ *        and {_recordOutflow} move it.
+ *
+ *      Two clocks, because the two things they time are unrelated. `anchoredAt` is the re-anchor
+ *      clock and only a re-anchor moves it, or one dust deposit per interval would hold the band
+ *      frozen. `driftFrom` is the drift baseline and every flow resets it, having first written the
+ *      drift accrued so far into both numbers. That is what lets our deposits earn drift from when
+ *      they arrived without earning any for the period before.
+ *
+ *      Clamping down over-reports a real loss, so the floor rate-limits marking down rather than
+ *      preventing it. Only {_guardedNav} reads `capEnabled` and `floorEnabled`; the re-anchor and
+ *      both flow calls run whether or not a side is armed, so the band keeps tracking while off.
+ *
+ *      Extenders supply {_observedNav} (must not revert; it reports whether it could read) and
+ *      {_requireGuardConfig}, which gates all three governance setters.
+ *
+ *      Storage: one mapping plus a gap, 20 slots total. Extenders are upgradeable proxies — do not
+ *      change this contract's position in the inheritance chain.
+ */
+abstract contract NavGuard is INavGuard {
+    // ============================== Constants =================================
+
+    /// @dev Basis-point denominator for the drift rate and both gaps.
+    uint256 private constant BPS = 10_000;
+
+    /// @dev One year, for annualizing `driftBps`.
+    uint256 private constant SECONDS_PER_YEAR = 365 days;
+
+    // ============================== State =====================================
+
+    /// @notice Optional value band for each resource. Never configured when `interval == 0`.
+    /// @dev The extender's removal paths must clear this with {_clearNavGuard}, or a re-added
+    ///      resource inherits the old band and {setNavGuardRate} holds its new anchor inside it.
+    mapping(address resource => NavBand band) internal _navGuard;
+
+    /// @dev Reserved slots for future fields. Shrink this when adding one.
+    uint256[19] private __gap;
+
+    // ============================== External — mutating ========================
+
+    /// @inheritdoc INavGuard
+    /// @dev The ACM role each of these three setters checks is its own signature, verbatim. So
+    ///      they are also the three strings an onboarding VIP has to grant.
+    function setNavGuardRate(
+        address resource,
+        uint16 driftBps,
+        uint16 upGapBps,
+        uint16 downGapBps,
+        uint32 interval,
+        bool capEnabled,
+        bool floorEnabled
+    ) external virtual override {
+        _requireGuardConfig("setNavGuardRate(address,uint16,uint16,uint16,uint32,bool,bool)", resource);
+        _setNavGuardRate(resource, driftBps, upGapBps, downGapBps, interval, capEnabled, floorEnabled);
+    }
+
+    /// @inheritdoc INavGuard
+    function setNavGuardSnapshot(address resource, uint128 snapshot, uint64 timestamp) external virtual override {
+        _requireGuardConfig("setNavGuardSnapshot(address,uint128,uint64)", resource);
+        _setNavGuardSnapshot(resource, snapshot, timestamp);
+    }
+
+    /// @inheritdoc INavGuard
+    function setNavGuardEnabled(address resource, bool capEnabled, bool floorEnabled) external virtual override {
+        _requireGuardConfig("setNavGuardEnabled(address,bool,bool)", resource);
+        _setNavGuardEnabled(resource, capEnabled, floorEnabled);
+    }
+
+    // ============================== External — view ============================
+
+    /// @inheritdoc INavGuard
+    function navGuard(address resource) external view override returns (NavBand memory) {
+        return _navGuard[resource];
+    }
+
+    /// @inheritdoc INavGuard
+    function navGuardStatus(address resource)
+        external
+        view
+        override
+        returns (
+            uint256 observedValue,
+            uint256 minAllowedValue,
+            uint256 maxAllowedValue,
+            bool isClamped,
+            uint256 clampedValue
+        )
+    {
+        NavBand storage band = _navGuard[resource];
+        if (band.interval == 0) return (0, 0, 0, false, 0);
+
+        (observedValue,) = _observedNav(resource);
+
+        // Both bounds are returned even when their side is switched off, so monitoring can see
+        // where an unarmed side would bind if it were armed.
+        (, minAllowedValue, maxAllowedValue) = _currentBand(band);
+
+        // `_guardedNav` does the clamping, so this only checks whether it clamped or returned `observedValue`.
+        uint256 guarded = _guardedNav(resource, observedValue);
+        if (guarded == observedValue) return (observedValue, minAllowedValue, maxAllowedValue, false, 0);
+        return (observedValue, minAllowedValue, maxAllowedValue, true, guarded);
+    }
+
+    // ============================== Internal — configuration ==================
+
+    /// @dev Validation and storage behind {setNavGuardRate}; auth and registration have already
+    ///      run in {_requireGuardConfig}.
+    function _setNavGuardRate(
+        address resource,
+        uint16 driftBps,
+        uint16 upGapBps,
+        uint16 downGapBps,
+        uint32 interval,
+        bool capEnabled,
+        bool floorEnabled
+    ) internal {
+        // A stored zero interval would read as "no band" in every other path here, and both gaps
+        // stay under 100% so `_currentBand`'s floor subtraction cannot underflow.
+        if (interval == 0 || upGapBps >= BPS || downGapBps >= BPS) revert InvalidNavGuardRate();
+
+        // Arming on a failed read would centre the band at zero and value a live position at nothing.
+        (uint256 anchor, bool readable) = _observedNav(resource);
+        if (!readable) revert NavGuardUnreadable(resource);
+
+        // A retune re-anchors on what the vault reports now, held inside the band already in force,
+        // so a gap change cannot adopt a value the old band was refusing. A zero reading skips that
+        // hold, or `_clamp` would raise it to the old floor and centre the new band on value that is gone.
+        NavBand storage current = _navGuard[resource];
+        if (current.interval != 0 && anchor != 0) {
+            (, uint256 floor, uint256 cap) = _currentBand(current);
+            anchor = _clamp(anchor, floor, cap);
+        }
+        if (anchor > type(uint128).max) revert InvalidNavGuardRate();
+
+        _navGuard[resource] = NavBand({
+            anchor: uint128(anchor),
+            centre: uint128(anchor),
+            anchoredAt: uint64(block.timestamp),
+            driftFrom: uint64(block.timestamp),
+            interval: interval,
+            driftBps: driftBps,
+            upGapBps: upGapBps,
+            downGapBps: downGapBps,
+            capEnabled: capEnabled,
+            floorEnabled: floorEnabled
+        });
+
+        emit NavGuardConfigured(
+            resource, uint128(anchor), driftBps, upGapBps, downGapBps, interval, capEnabled, floorEnabled
+        );
+    }
+
+    /// @dev Validation and storage behind {setNavGuardSnapshot}; auth and registration have
+    ///      already run.
+    function _setNavGuardSnapshot(address resource, uint128 snapshot, uint64 timestamp) internal {
+        NavBand storage band = _navGuard[resource];
+        if (band.interval == 0) revert InvalidNavGuardSnapshot();
+        if (snapshot == 0) revert InvalidNavGuardSnapshot();
+        if (timestamp == 0 || timestamp > block.timestamp) revert InvalidNavGuardSnapshot();
+
+        band.anchor = snapshot;
+        band.centre = snapshot;
+        band.anchoredAt = timestamp;
+        band.driftFrom = timestamp;
+
+        emit NavGuardReanchored(resource, snapshot, timestamp);
+    }
+
+    /// @dev Validation and storage behind {setNavGuardEnabled}; auth and registration have already
+    ///      run.
+    function _setNavGuardEnabled(address resource, bool capEnabled, bool floorEnabled) internal {
+        NavBand storage band = _navGuard[resource];
+        if ((capEnabled || floorEnabled) && band.interval == 0) revert NavGuardNotConfigured(resource);
+        if (band.capEnabled == capEnabled && band.floorEnabled == floorEnabled) return;
+
+        band.capEnabled = capEnabled;
+        band.floorEnabled = floorEnabled;
+        emit NavGuardEnabledSet(resource, capEnabled, floorEnabled);
+    }
+
+    /// @dev Clears the band for `resource`. Used by the extender's write-off / removal paths.
+    function _clearNavGuard(address resource) internal {
+        delete _navGuard[resource];
+    }
+
+    // ============================== Internal — accrual =========================
+
+    /// @dev Must not revert: this runs inside accrual. Every failure to read returns early and
+    ///      leaves the band where it was.
+    ///
+    ///      The clamp log lives here because {_guardedNav} is a view and cannot emit. It comes after
+    ///      the re-anchor, which moves the band, and `Hub._accrueFees` reads NAV later in the same
+    ///      call. Logging any earlier would name a bound valuation no longer uses.
+    function _updateNavGuard(address resource) internal {
+        NavBand storage band = _navGuard[resource];
+        if (band.interval == 0) return;
+
+        // A failed read is no information, and a zero the counterparty publishes must not close the
+        // band: only our own withdrawals do that, through `_recordOutflow`.
+        (uint256 observed, bool readable) = _observedNav(resource);
+        if (!readable || observed == 0) return;
+
+        if (block.timestamp - band.anchoredAt >= band.interval) _reanchor(resource, band, observed);
+
+        uint256 guarded = _guardedNav(resource, observed);
+        if (guarded != observed) emit NavGuardClamped(resource, observed, guarded);
+    }
+
+    /// @dev Once per `interval` the band moves onto what the counterparty reports now, so real
+    ///      growth does not eventually push a healthy position through the cap. `observed` is held
+    ///      inside the band in force before it is stored, which is what stops a single bad reading
+    ///      being adopted whole: 500 against a cap of 102 stores 102, the next band is built around
+    ///      102, and valuation can climb only one gap per interval.
+    function _reanchor(address resource, NavBand storage band, uint256 observed) private {
+        (uint256 centre, uint256 floor, uint256 cap) = _currentBand(band);
+        if (centre == 0) return;
+
+        uint256 anchor = _clamp(observed, floor, cap);
+        if (anchor > type(uint128).max) return;
+
+        band.anchor = uint128(anchor);
+        band.centre = uint128(anchor);
+        band.anchoredAt = uint64(block.timestamp);
+        band.driftFrom = uint64(block.timestamp);
+        emit NavGuardReanchored(resource, uint128(anchor), uint64(block.timestamp));
+    }
+
+    // ============================== Internal — our own moves ===================
+
+    /// @dev Moves the centre up by what we put into `resource`. No part of the deposit reaches the
+    ///      anchor, or it would buy itself a gap on the value it just added, and `anchoredAt` stays
+    ///      where it was, or one dust deposit per interval would hold the band frozen for good. The
+    ///      anchor does take the drift {_settleDrift} writes in first, which is growth it had already
+    ///      earned.
+    ///
+    ///      A position now worth exactly what we sent was empty a moment before, so whatever the band
+    ///      still had stored is value that left without {_recordOutflow} being told, by a sweep or a
+    ///      write-off. The read is what catches that: left in place, a centre of 48 plus a deposit of
+    ///      10 would report 58 over a position holding 10.
+    ///
+    ///      Reverts {NavGuardCentreOverflow} past `uint128`. Reverting unwinds the deposit instead
+    ///      of routing value the band cannot record.
+    function _recordInflow(address resource, uint256 amount) internal {
+        NavBand storage band = _navGuard[resource];
+        if (band.interval == 0 || amount == 0) return;
+
+        uint256 centre = _settleDrift(band) + amount;
+        if (centre > type(uint128).max) revert NavGuardCentreOverflow(resource, centre);
+
+        (uint256 value, bool readable) = _observedNav(resource);
+        if (readable && value == amount && centre != amount) {
+            emit NavGuardClosed(resource, band.centre, 0);
+            band.anchor = 0;
+            centre = amount;
+        }
+
+        band.centre = uint128(centre);
+        emit NavGuardCentreMoved(resource, band.anchor, uint128(centre));
+    }
+
+    /// @dev Moves the centre down by what left `resource`, or closes the band. A withdrawal comes out
+    ///      of our own deposits first, so once the centre falls below the anchor the anchor comes
+    ///      down with it. Left high, the gaps would go on being sized to money that has gone.
+    ///
+    ///      The centre it is measured against is the one {_settleDrift} has just brought up to date,
+    ///      so a payout is compared with what the band vouches for now rather than with a figure
+    ///      that stopped at the last re-anchor.
+    ///
+    ///      The band closes when the withdrawal reaches the centre, or when the position reads empty
+    ///      afterwards. The amount alone cannot show the second while the floor holds the band above
+    ///      a loss: take 50 out of a position worth 50 that the band reports at 98 and the centre
+    ///      would be left at 48 over nothing, for the next deposit to be reported 48 above what went
+    ///      in. An unreadable read does not close the band, since an empty position needs no price.
+    function _recordOutflow(address resource, uint256 amount) internal {
+        NavBand storage band = _navGuard[resource];
+        if (band.interval == 0 || amount == 0 || band.centre == 0) return;
+
+        uint256 centre = _settleDrift(band);
+        (uint256 left, bool readable) = _observedNav(resource);
+        if (amount >= centre || (readable && left == 0)) {
+            band.anchor = 0;
+            band.centre = 0;
+            emit NavGuardClosed(resource, centre, amount);
+            return;
+        }
+
+        centre -= amount;
+        band.centre = uint128(centre);
+        if (band.anchor > centre) band.anchor = uint128(centre);
+        emit NavGuardCentreMoved(resource, band.anchor, uint128(centre));
+    }
+
+    // ============================== Internal — view ============================
+
+    /// @dev Revert unless the caller may call `signature` and `resource` is one the extender manages.
+    ///      Check the caller first, or an unauthorized one learns what this extender has registered.
+    ///
+    ///      One hook for both, so a function added later cannot run the first check and forget the
+    ///      second. It is abstract because the extender already holds an access-control manager.
+    function _requireGuardConfig(string memory signature, address resource) internal view virtual;
+
+    /// @dev What `resource` is worth to the extender right now, in asset units and unclamped.
+    ///      Must not revert: answer `(0, false)` for a read that failed.
+    function _observedNav(address resource) internal view virtual returns (uint256 value, bool readable);
+
+    /// @dev The band applied to `observedNav`, on whichever sides are armed: the floor below it,
+    ///      the cap above it, `observedNav` itself in between. Never reverts.
+    ///
+    ///      A zero `observedNav` passes straight through rather than being clamped up to the
+    ///      floor: that would report value for a resource that demonstrably has none, and a
+    ///      resource can only be removed once it is empty.
+    function _guardedNav(address resource, uint256 observedNav) internal view returns (uint256 value) {
+        if (observedNav == 0) return 0;
+
+        NavBand storage band = _navGuard[resource];
+        if (band.interval == 0) return observedNav;
+
+        bool capOn = band.capEnabled;
+        bool floorOn = band.floorEnabled;
+        if (!capOn && !floorOn) return observedNav;
+
+        (, uint256 floor, uint256 cap) = _currentBand(band);
+        if (floorOn && observedNav < floor) return floor;
+        if (capOn && observedNav > cap) return cap;
+        return observedNav;
+    }
+
+    /// @dev The band right now. Both numbers grow at `driftBps` since `driftFrom`, because
+    ///      Centrifuge prices the whole position with one share price and our own deposits sit in
+    ///      the same fund as the counterparty's part. Crediting drift to the anchor alone left a
+    ///      deposit with no growth allowance until the next re-anchor: 100 armed, 400 deposited and
+    ///      thirty days at exactly the configured 8% put the cap at 502.67 over a position worth
+    ///      503.29, so an honest fund was clamped.
+    ///
+    ///      The gaps are sized to the anchor, not to the centre, and that asymmetry is the point. A
+    ///      deposit raises only the centre, so it buys no headroom on the value it just added. A
+    ///      withdrawal past our own deposits lowers the anchor with the centre, so the gaps resize
+    ///      to what is left: take 99 out of 100 with a 2% gap and the cap is 1.02, where an anchor
+    ///      left at 100 would have allowed 3.
+    ///
+    ///      Nothing here can underflow. The anchor never exceeds the centre and {_grown} is
+    ///      monotonic, so it does not after drifting either; both gaps are held under 100% at
+    ///      configuration; and `driftFrom` is never in the future because every writer uses
+    ///      `block.timestamp` or rejects a later stamp. A closed band returns zeros.
+    function _currentBand(NavBand storage band) internal view returns (uint256 centre, uint256 floor, uint256 cap) {
+        uint256 elapsed = block.timestamp - band.driftFrom;
+        uint256 driftBps = band.driftBps;
+        uint256 anchor = _grown(band.anchor, driftBps, elapsed);
+        centre = _grown(band.centre, driftBps, elapsed);
+
+        floor = centre - (anchor * band.downGapBps) / BPS;
+        cap = centre + (anchor * band.upGapBps) / BPS;
+    }
+
+    /// @dev `value` after `elapsed` seconds at `driftBps` a year, capped where it would stop fitting
+    ///      the slot it is stored in. The cap is unreachable in practice: it needs a position near
+    ///      `uint128` that has also gone a decade without a re-anchor. Capping rather than reverting
+    ///      keeps every caller non-reverting, and it can only lower the band.
+    function _grown(uint256 value, uint256 driftBps, uint256 elapsed) private pure returns (uint256) {
+        uint256 grown = value + (value * driftBps * elapsed) / (BPS * SECONDS_PER_YEAR);
+        return grown > type(uint128).max ? type(uint128).max : grown;
+    }
+
+    /// @dev Writes the drift accrued since `driftFrom` into both stored numbers and restarts that
+    ///      clock, then returns the centre. Every flow calls this before moving anything, so the
+    ///      flow is measured against the band as it stands at that moment and money arriving now
+    ///      earns drift only from now. Without it, growing the centre would hand a deposit the drift
+    ///      of the whole period since the last re-anchor, which is headroom bought with deposit size.
+    ///
+    ///      `anchoredAt` is untouched. The re-anchor clock belongs to the counterparty, and letting
+    ///      a flow move it would let one dust deposit per interval hold the band frozen.
+    function _settleDrift(NavBand storage band) private returns (uint256 centre) {
+        centre = band.centre;
+        uint256 elapsed = block.timestamp - band.driftFrom;
+        uint256 driftBps = band.driftBps;
+
+        if (elapsed != 0 && driftBps != 0 && centre != 0) {
+            centre = _grown(centre, driftBps, elapsed);
+            band.centre = uint128(centre);
+            band.anchor = uint128(_grown(band.anchor, driftBps, elapsed));
+        }
+        band.driftFrom = uint64(block.timestamp);
+    }
+
+    /// @dev `value` held inside `[floor, cap]`.
+    function _clamp(uint256 value, uint256 floor, uint256 cap) private pure returns (uint256) {
+        if (value < floor) return floor;
+        if (value > cap) return cap;
+        return value;
+    }
+}

package/contracts/YieldGroup/base/YieldGroupBase.sol

@@ -164,6 +164,7 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
         // setter is registered-only. Removal restores a clean slate.
         delete _resourceCap[resource];
         delete _resourcesConfig[resource];
+        _onResourceRemoved(resource);
 
         emit ResourceRemoved(resource);
     }
@@ -604,11 +605,26 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
      *      Callers own the registration / pause / capacity checks and must ensure this
      *      YieldGroup already holds `amount` of underlying. Delegatecall credits receipt
      *      tokens to this YieldGroup; `Address.functionDelegateCall` bubbles adapter reverts.
+     *
+     *      `virtual` so a family that has to account for its own value moves can hook here: this
+     *      and {_dispatchWithdraw} are the only two places value enters or leaves a resource.
      * @param adapter Adapter bound to `resource`.
      * @param resource Resource to deposit into.
      * @param amount Underlying units to place (exact).
      */
-    function _dispatchDeposit(address adapter, address resource, uint256 amount) private {
+    /**
+     * @notice Clear whatever per-resource state a family keeps outside this contract, called by
+     *         {removeResource} once the resource is out of the registry and both queues.
+     * @dev Same reason {removeResource} clears `_resourceCap`: `addResource` never writes these,
+     *      and the setters are registered-only, so anything left behind is silently inherited by a
+     *      later re-`addResource` of the same address. A family with no extra state leaves this
+     *      empty. Must not revert, or removal becomes unreachable.
+     * @param resource Resource being removed.
+     */
+    // solhint-disable-next-line no-empty-blocks
+    function _onResourceRemoved(address resource) internal virtual { }
+
+    function _dispatchDeposit(address adapter, address resource, uint256 amount) internal virtual {
         adapter.functionDelegateCall(abi.encodeCall(IResourceAdapter.deposit, (resource, amount)));
         emit DepositRouted(resource, amount);
     }
@@ -623,6 +639,9 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
      *      a shortfall itself — doing so inside the cascade's external self-call frame would blur
      *      our own invariant with an external-protocol revert and force selector-matching to tell
      *      them apart. The delta is cheap defensive verification against a future-adapter regression.
+     *
+     *      `virtual` for the reason on {_dispatchDeposit}. An override should use `received`, not
+     *      `amount`.
      * @param adapter Adapter bound to `resource`.
      * @param resource Resource to pull from.
      * @param amount Underlying units to deliver to `to` (exact).
@@ -630,7 +649,8 @@ abstract contract YieldGroupBase is ReentrancyGuardUpgradeable, YieldGroupBaseSt
      * @return received Underlying units actually delivered to `to`, measured by balance delta.
      */
     function _dispatchWithdraw(address adapter, address resource, uint256 amount, address to)
-        private
+        internal
+        virtual
         returns (uint256 received)
     {
         IERC20 assetToken = IERC20(_assetToken);