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

package/contracts/interfaces/INavGuard.sol

@@ -0,0 +1,339 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title INavGuard
+ * @author Venus
+ * @notice External interface for `NavGuard` — a per-resource band on a position's own value, for
+ *         positions whose value is reported by a counterparty nothing else validates.
+ * @dev The band vouches for a value: the last counterparty figure we accepted, grown at the
+ *      expected rate, plus whatever we have moved in or out since. Valuation is held a gap either
+ *      side of that, `min(max(observed, floor), cap)`, 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 governance reopens it.
+ *
+ *      It bounds value, not price: a position marked as `quantity x price` can be inflated
+ *      through either factor. Value is the product plus whatever has no price at all, so one band
+ *      covers every way the number can be wrong.
+ *
+ *      Values are in the asset's own units, never a reference currency. The band therefore says
+ *      nothing about what the asset is worth elsewhere: a depeg is invisible to it by design.
+ *
+ *      Two things move the band, and they are deliberately different:
+ *
+ *      - The periodic re-anchor, at most once per `interval`: the anchor adopts
+ *        `clamp(observed, floor, cap)`. Clamped first, so a wrong value moves the band by one gap
+ *        per interval and never becomes the baseline the next reading is judged against.
+ *      - Our own moves: a deposit raises the centre by exactly the amount, and a withdrawal lowers
+ *        it, taking the anchor down with it once our own deposits are used up. Neither reads a
+ *        value that could raise the band, and neither touches the clock, so a deposit or
+ *        withdrawal buys no gap of its own.
+ *
+ *      Everything here is implemented once in `NavGuard`. The extending contract supplies the
+ *      value source, the access-control hook, and the calls that record its own moves.
+ */
+interface INavGuard {
+    // -------------------------------- Structs ---------------------------------
+
+    /**
+     * @notice One resource's value band. All zero until {setNavGuardRate} is called.
+     * @dev A side binds on valuation only while its own flag is true and `interval` is non-zero.
+     *      They answer different questions: `interval == 0` means never configured, while a false
+     *      flag means configured and that side switched off, keeping the band so it can be re-armed
+     *      without re-supplying anything. Both flags false leaves the band tracking but clamping
+     *      nothing.
+     *
+     *      `anchor` and `centre` are stored as of `driftFrom`, and each grows at `driftBps` from
+     *      there when read. A closed band has both at zero: every armed side then values the
+     *      position at nothing, and only a deposit or {setNavGuardSnapshot} reopens it.
+     * @param anchor The counterparty's part of the position: the value accepted at the last
+     *        re-anchor, or forced by governance, less what withdrawals have since taken past our own
+     *        deposits. Never above `centre`. Both gaps are sized to it.
+     * @param centre `anchor` plus our own deposits since. What valuation is held around.
+     * @param anchoredAt When `anchor` was last set. `interval` is measured from here, and only a
+     *        re-anchor moves it, so our own flows can never delay or bring one forward.
+     * @param driftFrom When both stored numbers were last brought up to date. Drift accrues from
+     *        here, and every flow writes what has accrued into them and resets it, so money we add
+     *        drifts from when it arrived rather than from the last re-anchor.
+     * @param interval Minimum seconds between periodic re-anchors. `0` means never configured.
+     * @param driftBps Annual drift of both stored numbers, in basis points. May be zero — a band
+     *        that does not drift is the strictest valid setting.
+     * @param upGapBps Half-width above the centre, in basis points. Below 10_000.
+     * @param downGapBps Half-width below the centre, in basis points. Below 10_000.
+     * @param capEnabled Whether valuation is clamped down to the cap.
+     * @param floorEnabled Whether valuation is clamped up to the floor.
+     */
+    struct NavBand {
+        uint128 anchor;
+        uint128 centre;
+        uint64 anchoredAt;
+        uint64 driftFrom;
+        uint32 interval;
+        uint16 driftBps;
+        uint16 upGapBps;
+        uint16 downGapBps;
+        bool capEnabled;
+        bool floorEnabled;
+    }
+
+    // -------------------------------- Events ----------------------------------
+
+    /**
+     * @notice A resource's band was configured, anchored on the value observed in this transaction
+     *         and held inside the band that was already in force, if any.
+     * @param resource Resource the band applies to.
+     * @param anchor Value the band is now anchored on. Zero means it is closed.
+     * @param driftBps Annual drift of the anchor, in basis points.
+     * @param upGapBps Half-width above the centre, in basis points.
+     * @param downGapBps Half-width below the centre, in basis points.
+     * @param interval Minimum seconds between periodic re-anchors.
+     * @param capEnabled Whether valuation is now clamped down to the cap.
+     * @param floorEnabled Whether valuation is now clamped up to the floor.
+     */
+    event NavGuardConfigured(
+        address indexed resource,
+        uint128 anchor,
+        uint16 driftBps,
+        uint16 upGapBps,
+        uint16 downGapBps,
+        uint32 interval,
+        bool capEnabled,
+        bool floorEnabled
+    );
+
+    /**
+     * @notice A resource's band had one or both sides switched on or off, without changing its
+     *         configuration.
+     * @dev A side that is off reports whatever the counterparty says on that side, but the centre
+     *      keeps tracking — see {setNavGuardEnabled}. Not the only event that carries the flags:
+     *      {setNavGuardRate} takes them too, and reports them on {NavGuardConfigured}.
+     * @param resource Resource whose band was toggled.
+     * @param capEnabled Whether valuation is now clamped down to the cap.
+     * @param floorEnabled Whether valuation is now clamped up to the floor.
+     */
+    event NavGuardEnabledSet(address indexed resource, bool capEnabled, bool floorEnabled);
+
+    /**
+     * @notice A resource's anchor moved: the periodic re-anchor adopted a clamped reading, or
+     *         governance forced one through {setNavGuardSnapshot}. The centre moves onto it too.
+     * @param resource Resource whose anchor moved.
+     * @param anchor New anchor, and new centre.
+     * @param anchoredAt Drift baseline and re-anchor clock from here on.
+     */
+    event NavGuardReanchored(address indexed resource, uint128 anchor, uint64 anchoredAt);
+
+    /**
+     * @notice We moved value into or out of a resource, and its centre moved by exactly that. The
+     *         clock is untouched, and the anchor moves only when a withdrawal reaches into the
+     *         counterparty's part.
+     * @param resource Resource whose centre moved.
+     * @param anchor The counterparty's part after the move. Zero right after a deposit means the
+     *        deposit opened the band, and the band has no width until its first re-anchor.
+     * @param centre New stored centre, before drift.
+     */
+    event NavGuardCentreMoved(address indexed resource, uint128 anchor, uint128 centre);
+
+    /**
+     * @notice The band closed: both bounds are zero, and every armed side values the position at
+     *         nothing until a deposit or {setNavGuardSnapshot} reopens it. A withdrawal took out at
+     *         least what the centre held, or left the position empty, or a deposit found the
+     *         position already empty under a centre nothing had told the band about.
+     * @dev Alert on this and read {navGuardStatus}. A nonzero `observedValue` there means the
+     *      position still holds something that valuation is not counting. A zero `amount` is the
+     *      deposit case, and says value left the position without the band being told, which a
+     *      sweep does; the deposit that found it has reopened the band at exactly its own size.
+     * @param resource Resource whose band closed.
+     * @param centre Centre the band held before.
+     * @param amount Value that left the resource in this transaction; zero when a deposit found
+     *        the position already empty.
+     */
+    event NavGuardClosed(address indexed resource, uint256 centre, uint256 amount);
+
+    /**
+     * @notice A resource's value was held to one of its band's bounds, and valuation reports that
+     *         bound instead.
+     * @dev Fires from the Hub's accrual, so silence means nobody has transacted, not that nothing
+     *      is clamped. {navGuardStatus} answers that on demand.
+     * @param resource Resource whose value was held to a bound.
+     * @param observedValue What the counterparty reports the position is worth.
+     * @param clampedValue What valuation reports instead. Below `observedValue` the cap bound,
+     *        above it the floor.
+     */
+    event NavGuardClamped(address indexed resource, uint256 observedValue, uint256 clampedValue);
+
+    // -------------------------------- Errors ----------------------------------
+
+    /// @notice `setNavGuardRate()` got a zero `interval`, or an `upGapBps` or `downGapBps` of 100%
+    ///         or more. A gap of zero is accepted, and is the tightest band on its side; switching a
+    ///         side off is {setNavGuardEnabled}'s job.
+    error InvalidNavGuardRate();
+
+    /// @notice `setNavGuardRate()` could not read what the resource is worth. Arming on that would
+    ///         centre the band at zero and value a live position at nothing, so the call fails.
+    ///         Whatever stops the read has to be cleared first — for a Centrifuge vault that is
+    ///         usually a share price the publisher has not set.
+    error NavGuardUnreadable(address resource);
+
+    /// @notice `setNavGuardSnapshot()` got a zero `snapshot`, a zero `timestamp`, a `timestamp` in
+    ///         the future, or a resource whose band was never configured.
+    error InvalidNavGuardSnapshot();
+
+    /// @notice `setNavGuardEnabled()` was asked to arm a side of a band that was never configured.
+    ///         There is nothing to clamp to until {setNavGuardRate} has run.
+    error NavGuardNotConfigured(address resource);
+
+    /// @notice A deposit would have pushed a band's centre past `uint128`, so the deposit reverted.
+    ///         Reset the centre with {setNavGuardSnapshot} before depositing into that resource
+    ///         again.
+    /// @param resource Resource whose band could not record the deposit.
+    /// @param centre Centre the deposit would have set.
+    error NavGuardCentreOverflow(address resource, uint256 centre);
+
+    // ----------------------- Governance ---------------------------------------
+
+    /**
+     * @notice Configure the band for one resource and arm the sides asked for: valuation will
+     *         report its value clamped into a corridor that drifts `driftBps` per year, `upGapBps`
+     *         wide above the centre and `downGapBps` below.
+     * @dev ACM role `"setNavGuardRate(address,uint16,uint16,uint16,uint32,bool,bool)"` (VIP).
+     *      Re-callable to retune. Reverts {InvalidNavGuardRate} on a zero `interval` or a gap of
+     *      100% or more, {NavGuardUnreadable} when the position cannot be valued. Emits
+     *      {NavGuardConfigured}.
+     *
+     *      Two things a retune does that are easy to miss. It sets both flags from its arguments
+     *      instead of keeping the current pair, so a cap-only deployment turns the floor back on by
+     *      passing the wrong ones. And it re-anchors on the value observed right now, held inside
+     *      the band already in force, so a retune cannot adopt a value the band was rejecting and a
+     *      closed band stays closed through it. A position that reads empty is not held to the old
+     *      band: there is nothing to vouch for, so it anchors a closed band. Accepting a real
+     *      markdown, or reopening a closed band, is {setNavGuardSnapshot}'s job.
+     *
+     *      A zero observed value is accepted, so a band can be armed before its resource is funded.
+     *      It is then closed until the first deposit opens it, and that deposit is reported at
+     *      exactly what went in until the first re-anchor gives the band an anchor to size its gaps
+     *      from.
+     *
+     *      Sizing. `driftBps` is the position's expected annual return, set above its real trend or
+     *      the cap binds on ordinary growth. The gaps are how far a wrong value moves valuation
+     *      before it is clamped: `upGapBps` covers the jump when the counterparty settles at its
+     *      own mark, `downGapBps` the worst single honest decline. Zero is a side's tightest
+     *      setting, not an off switch.
+     *
+     *      `downGapBps` cannot be picked without `interval`. Each re-anchor lifts the anchor by one
+     *      interval of drift before the gap takes it back down, so the anchor falls only while
+     *      `downGapBps` exceeds `driftBps * interval / 365 days` — at 8% drift, a 2% gap needs an
+     *      interval under about three months. Under that the anchor climbs against a position that
+     *      is genuinely losing, floor armed or not, since the re-anchor clamps against both bounds
+     *      whatever the flags say.
+     *
+     *      The cap bounds the rate a wrong value can inflate valuation, not the total: one that
+     *      stays wrong advances the cap by its full width every `interval`.
+     * @param resource Registered resource the band applies to.
+     * @param driftBps Annual drift of the anchor, in basis points. May be zero.
+     * @param upGapBps Half-width above the centre, in basis points. May be zero, must be under
+     *        100%.
+     * @param downGapBps Half-width below the centre, in basis points. Must be under 100%.
+     * @param interval Minimum seconds between periodic re-anchors. Must be non-zero.
+     * @param capEnabled True to clamp valuation down to the cap.
+     * @param floorEnabled True to clamp valuation up to the floor.
+     */
+    function setNavGuardRate(
+        address resource,
+        uint16 driftBps,
+        uint16 upGapBps,
+        uint16 downGapBps,
+        uint32 interval,
+        bool capEnabled,
+        bool floorEnabled
+    ) external;
+
+    /**
+     * @notice Force the band's anchor and centre onto one value, and its clock onto one time,
+     *         without touching either gap or `interval`.
+     * @dev ACM role `"setNavGuardSnapshot(address,uint128,uint64)"` (VIP). Reads no value — use it
+     *      to accept a markdown the floor is holding up, to reopen a band a withdrawal closed, or
+     *      to hold the previous centre through an investigation. Reverts {InvalidNavGuardSnapshot}
+     *      if the band was never configured, `snapshot` is zero, or `timestamp` is zero or in the
+     *      future. Emits {NavGuardReanchored}.
+     *
+     *      `timestamp` is both the drift baseline and the re-anchor clock. A backdated one has
+     *      already accrued drift, so the centre this puts in force is above `snapshot`, and
+     *      backdating by a full `interval` also leaves a re-anchor due immediately. Nothing here
+     *      compares the centre to the observed value, so parking the band away from it is allowed
+     *      and clamps valuation until the two meet.
+     *
+     *      A zero `snapshot` is refused rather than treated as an off switch: it would close the
+     *      band by hand, and {setNavGuardEnabled} already expresses switching the band off, under
+     *      its own role. To write a resource off entirely, that is `forceRemoveResource`.
+     * @param resource Registered resource whose centre to force.
+     * @param snapshot New anchor and centre, in asset units.
+     * @param timestamp Timestamp to drift from, and what the `interval` clock is measured from.
+     */
+    function setNavGuardSnapshot(address resource, uint128 snapshot, uint64 timestamp) external;
+
+    /**
+     * @notice Arm either side of a resource's band, both, or neither, keeping its configuration
+     *         whichever way.
+     * @dev ACM role `"setNavGuardEnabled(address,bool,bool)"` (VIP). Reads no value, so it still
+     *      works when the value source is broken — which is the point, since a band clamping a
+     *      healthy position is exactly when it has to come off in one transaction. Reverts
+     *      {NavGuardNotConfigured} when arming a side of a band {setNavGuardRate} has never run on.
+     *      Idempotent. Emits {NavGuardEnabledSet}.
+     *
+     *      The two sides do different jobs, which is why they arm separately. The cap protects the
+     *      Hub: an over-reported position is valued down, so nobody withdraws against value that is
+     *      not there. The floor does the opposite — it reports more than the position is worth, in
+     *      exchange for marking a loss down gradually instead of at once. A deployment that wants
+     *      the protection without that trade runs cap-only, and both false switches the band off
+     *      without discarding it.
+     *
+     *      The flags do not gate the centre. Our own moves and the re-anchor apply either way, and
+     *      the re-anchor clamps against both bounds, so a side switched off cannot let a wrong
+     *      value re-anchor the band, and arming it again needs no second transaction. A closed
+     *      band is the exception: it stays closed until a deposit or {setNavGuardSnapshot} reopens
+     *      it.
+     * @param resource Registered resource whose band to arm.
+     * @param capEnabled True to clamp valuation down to the cap.
+     * @param floorEnabled True to clamp valuation up to the floor.
+     */
+    function setNavGuardEnabled(address resource, bool capEnabled, bool floorEnabled) external;
+
+    // ----------------------- Views --------------------------------------------
+
+    /**
+     * @notice The band configured for `resource`, whether or not either side is armed.
+     * @param resource Resource to read.
+     * @return band Stored configuration; all-zero when never configured.
+     */
+    function navGuard(address resource) external view returns (NavBand memory band);
+
+    /**
+     * @notice Where `resource`'s value stands against its band right now.
+     * @dev Never reverts, so monitoring can read it whether or not valuation is working. An
+     *      unreadable source reports `observedValue` as zero, and everything reads zero and false
+     *      when the band was never configured.
+     *
+     *      Both bounds are reported armed or not, so monitoring can see where a side would bind
+     *      before arming it. `isClamped` follows only what valuation actually does, so it is false
+     *      when the breached side is unarmed, and false for a zero `observedValue` — which is
+     *      either an unreadable source or an empty position, and valuation passes both through. A
+     *      closed band under a nonzero `observedValue` is a real clamp to nothing, and says the
+     *      resource holds something valuation is not counting.
+     * @param resource Resource to read.
+     * @return observedValue Value the counterparty reports, in asset units; `0` if unreadable.
+     * @return minAllowedValue Lowest value the band allows right now.
+     * @return maxAllowedValue Highest value the band allows right now.
+     * @return isClamped Whether valuation is currently reporting a bound instead of `observedValue`.
+     * @return clampedValue What valuation reports instead; `0` when `isClamped` is false.
+     */
+    function navGuardStatus(address resource)
+        external
+        view
+        returns (
+            uint256 observedValue,
+            uint256 minAllowedValue,
+            uint256 maxAllowedValue,
+            bool isClamped,
+            uint256 clampedValue
+        );
+}

package/contracts/interfaces/IYieldGroupCentrifuge.sol

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+import { INavGuard } from "./INavGuard.sol";
+import { IYieldGroupBase } from "./IYieldGroupBase.sol";
+
+/**
+ * @title IYieldGroupCentrifuge
+ * @author Venus
+ * @notice External interface for `YieldGroupCentrifuge` — a per-asset YieldGroup holding
+ *         Centrifuge async tokenized-fund vaults (ERC-7540) behind the synchronous Hub boundary.
+ * @dev Extends `IYieldGroupBase` with the async lifecycle the family needs: operator-driven
+ *      redeem requests and cancels, keeper-driven claims. Deposits need no new surface — the
+ *      standard deposit path already opens an escrow request synchronously. Governance also
+ *      gets: the per-resource value band from `INavGuard`, which clamps a Centrifuge position's
+ *      reported value on both sides, with a manual override for when the observed value can't be
+ *      trusted; and a write-off removal for a position Centrifuge has made permanently
+ *      unclaimable.
+ */
+interface IYieldGroupCentrifuge is IYieldGroupBase, INavGuard {
+    // -------------------------------- Events ----------------------------------
+
+    /**
+     * @notice An async redeem request was opened: `shares` moved into Centrifuge escrow.
+     * @param resource Centrifuge vault the request was opened on.
+     * @param shares Share units moved into escrow.
+     */
+    event RedeemRequested(address indexed resource, uint256 shares);
+
+    /**
+     * @notice A cancel was requested for the pending deposit; new deposit requests are blocked
+     *         until Centrifuge fulfils the cancel.
+     * @param resource Centrifuge vault whose pending deposit is being cancelled.
+     */
+    event DepositCancelRequested(address indexed resource);
+
+    /**
+     * @notice A cancel was requested for the pending redeem.
+     * @param resource Centrifuge vault whose pending redeem is being cancelled.
+     */
+    event RedeemCancelRequested(address indexed resource);
+
+    /**
+     * @notice Issued shares were claimed into the group.
+     * @param resource Centrifuge vault the shares were claimed from.
+     * @param shares Share units delivered to the group.
+     */
+    event DepositClaimed(address indexed resource, uint256 shares);
+
+    /**
+     * @notice Settled assets were claimed into the group as idle.
+     * @dev Only {claimRedeem} emits this. A Hub withdrawal that lands on a settled redeem draws
+     *      down the same Centrifuge counter but is logged as {IYieldGroupBase.WithdrawRouted}, so
+     *      this event alone does not add up to every claim.
+     * @param resource Centrifuge vault the assets were claimed from.
+     * @param assets Asset units delivered to the group.
+     */
+    event RedeemClaimed(address indexed resource, uint256 assets);
+
+    /**
+     * @notice A fulfilled deposit cancel was collected as idle assets.
+     * @param resource Centrifuge vault the cancelled deposit returned from.
+     * @param assets Asset units returned to the group.
+     */
+    event DepositCancelClaimed(address indexed resource, uint256 assets);
+
+    /**
+     * @notice A fulfilled redeem cancel was collected as held shares.
+     * @param resource Centrifuge vault the cancelled redeem returned from.
+     * @param shares Share units returned to the group.
+     */
+    event RedeemCancelClaimed(address indexed resource, uint256 shares);
+
+    /**
+     * @notice Governance wrote off a permanently unclaimable position and dropped the resource.
+     * @param resource Force-removed Centrifuge vault.
+     * @param writtenOffValue Underlying value the position was still marked at when removed, raw
+     *        rather than clamped to the NAV band — the point of a write-off is to record what was
+     *        actually there. `0` when valuation itself reverted, which is a dead price feed, and
+     *        plausible in the situation that led here: the value was unknowable at removal time,
+     *        not necessarily zero.
+     * @param orphanedReceipt Receipt sentinel (held shares plus in-flight counters) abandoned.
+     */
+    event ResourceForceRemoved(address indexed resource, uint256 writtenOffValue, uint256 orphanedReceipt);
+
+    /**
+     * @notice Governance published a new spot APY for one Centrifuge vault.
+     * @param resource Centrifuge vault the rate was published for.
+     * @param oldApyBps Rate the resource was advertising before this call.
+     * @param newApyBps Rate it advertises from now on.
+     */
+    event SpotAPYBpsSet(address indexed resource, uint64 oldApyBps, uint64 newApyBps);
+
+    // -------------------------------- Errors ----------------------------------
+
+    /// @notice `requestRedeem()` was called with zero shares.
+    error ZeroShares();
+
+    /// @notice `forceRemoveResource()` was called while the Hub was unpaused. The write-off drops the
+    ///         Hub's share price in one block; the pause keeps that drop untradeable.
+    error HubNotPaused();
+
+    // ----------------------- Initialisation -----------------------------------
+
+    /**
+     * @notice Initialise the YieldGroup. Called once via the proxy.
+     * @param hub_ Hub authorised to call `deposit` / `withdraw`.
+     * @param asset_ Underlying ERC-20 (must match `Hub.asset()`).
+     * @param acm_ AccessControlManagerV8 gating governance calls.
+     */
+    function initialize(address hub_, address asset_, address acm_) external;
+
+    // ----------------------- Async lifecycle (ACM-gated) ----------------------
+
+    /**
+     * @notice Open an async redeem request: move `shares` of the vault's share token from this
+     *         group into Centrifuge escrow. The settled assets become collectable via
+     *         {claimRedeem} once the fund manager fills the request cross-chain.
+     * @dev ACM role `"requestRedeem(address,uint256)"` (Operator or VIP). Allowed on a paused
+     *      resource: pause blocks new deposits, not wind-down. Reverts {ZeroShares} on a zero
+     *      amount, {ResourceNotRegistered} on an unknown resource. Emits {RedeemRequested}.
+     * @param resource Registered Centrifuge vault to open the request on.
+     * @param shares Share units to move into escrow for redemption.
+     */
+    function requestRedeem(address resource, uint256 shares) external;
+
+    /**
+     * @notice Ask Centrifuge to return the group's pending deposit. The returned assets become
+     *         collectable via {claimCancelDeposit} once the manager processes the cancel;
+     *         until then new deposit requests to this vault are blocked.
+     * @dev ACM role `"cancelDepositRequest(address)"` (Operator or VIP). Reverts
+     *      {ResourceNotRegistered} on an unknown resource; Centrifuge itself rejects a cancel
+     *      with nothing pending or with one already in flight. Emits {DepositCancelRequested}.
+     * @param resource Registered Centrifuge vault whose pending deposit to cancel.
+     */
+    function cancelDepositRequest(address resource) external;
+
+    /**
+     * @notice Ask Centrifuge to return the group's pending redeem shares. The returned shares
+     *         become collectable via {claimCancelRedeem} once the manager processes the cancel.
+     * @dev ACM role `"cancelRedeemRequest(address)"` (Operator or VIP). Reverts
+     *      {ResourceNotRegistered} on an unknown resource; Centrifuge itself rejects a cancel
+     *      with nothing pending or with one already in flight. Emits {RedeemCancelRequested}.
+     * @param resource Registered Centrifuge vault whose pending redeem to cancel.
+     */
+    function cancelRedeemRequest(address resource) external;
+
+    /**
+     * @notice Claim every share issued by the group's filled deposit requests into the group.
+     * @dev ACM role `"claimDeposit(address)"` (Keeper or VIP). Idempotent: nothing claimable is a
+     *      silent no-op with no event, so the keeper can poll safely. Reverts
+     *      {ResourceNotRegistered} on an unknown resource. Emits {DepositClaimed} when
+     *      `shares > 0`.
+     * @param resource Registered Centrifuge vault to claim issued shares from.
+     * @return shares Share units claimed (`0` when nothing was claimable).
+     */
+    function claimDeposit(address resource) external returns (uint256 shares);
+
+    /**
+     * @notice Claim every asset reserved by the group's filled redeem requests into the group
+     *         as idle balance.
+     * @dev ACM role `"claimRedeem(address)"` (Keeper or VIP). Idempotent: nothing claimable is a
+     *      silent no-op with no event, so the keeper can poll safely. Reverts
+     *      {ResourceNotRegistered} on an unknown resource. Emits {RedeemClaimed} when
+     *      `assets > 0`.
+     * @param resource Registered Centrifuge vault to claim settled assets from.
+     * @return assets Asset units that reached the group (`0` when nothing was claimable).
+     */
+    function claimRedeem(address resource) external returns (uint256 assets);
+
+    /**
+     * @notice Collect the assets a processed deposit cancel returned, into the group as idle
+     *         balance.
+     * @dev ACM role `"claimCancelDeposit(address)"` (Keeper or VIP). Centrifuge lifts the block on
+     *      new deposit requests when it fulfils the cancel, not when this is called — the claim
+     *      only collects the returned value. Idempotent: nothing claimable is a silent no-op with
+     *      no event. Reverts {ResourceNotRegistered} on an unknown resource. Emits
+     *      {DepositCancelClaimed} when `assets > 0`.
+     * @param resource Registered Centrifuge vault to collect the cancelled deposit from.
+     * @return assets Asset units that reached the group (`0` when nothing was claimable).
+     */
+    function claimCancelDeposit(address resource) external returns (uint256 assets);
+
+    /**
+     * @notice Collect the shares a processed redeem cancel returned, back into the group's held
+     *         share balance.
+     * @dev ACM role `"claimCancelRedeem(address)"` (Keeper or VIP). Centrifuge lifts the block on
+     *      new redeem requests when it fulfils the cancel, not when this is called — the claim
+     *      only collects the returned value. Idempotent: nothing claimable is a silent no-op with
+     *      no event. Reverts {ResourceNotRegistered} on an unknown resource. Emits
+     *      {RedeemCancelClaimed} when `shares > 0`.
+     * @param resource Registered Centrifuge vault to collect the cancelled redeem from.
+     * @return shares Share units collected (`0` when nothing was claimable).
+     */
+    function claimCancelRedeem(address resource) external returns (uint256 shares);
+
+    // ----------------------- Write-off removal (governance) -------------------
+
+    /**
+     * @notice Write off a permanently unclaimable position and drop the resource from the registry.
+     * @dev ACM role `"forceRemoveResource(address)"` (VIP). For the case normal `removeResource`
+     *      cannot reach: once Centrifuge freezes the group's address or unlinks the vault, every
+     *      claim reverts and the position can never be emptied, so leaving it registered would keep
+     *      propping the Hub's share price up with money that is not coming back.
+     *
+     *      Unlike `YieldGroupFRV.forceRemoveResource` there is deliberately no zero-value gate — a
+     *      frozen Centrifuge position still marks above zero, so requiring NAV `== 0` would make
+     *      this unusable in exactly the situation it exists for. CAUTION: with no value check of any
+     *      kind, this removes a healthy, fully recoverable resource just as readily as a stuck one,
+     *      and governance is accepting a real write-off either way — the Hub's share price drops by
+     *      the removed value in this transaction. Establishing that the position is genuinely
+     *      unclaimable is the caller's responsibility; pausing the resource first is the recommended
+     *      practice. The Hub itself must be paused or the call reverts {HubNotPaused}, so the sequence
+     *      is `pauseHub` -> `forceRemoveResource` -> `unpauseHub`. Clears both inner queues and the
+     *      resource's NAV band. Emits {ResourceForceRemoved} carrying the value written off — the
+     *      raw value, not the band-clamped one, since a write-off should record what was actually
+     *      there.
+     * @param resource Registered Centrifuge vault to write off and remove.
+     */
+    function forceRemoveResource(address resource) external;
+
+    // ----------------------- Published spot APY (governance) ------------------
+
+    /**
+     * @notice Publish the annual rate a Centrifuge fund is yielding, in basis points
+     *         (`10_000` = 100%), so `spotAPYBps()` has something to report for it. Centrifuge
+     *         computes its funds' returns off-chain and puts no rate on-chain, so this call is the
+     *         only source that number has. `0` publishes none, which is what a resource reports
+     *         until someone sets it.
+     * @dev ACM role `"setSpotAPYBps(address,uint64)"` (Operator or VIP). The published rate reaches
+     *      `spotAPYBps()` and stops there — not share pricing, not routing, not caps, not fees — so
+     *      a wrong figure misstates the advertised yield and cannot move anyone's balance. Nothing
+     *      on-chain can check it against the fund, and no value is rejected, so what governance
+     *      types is what the group advertises. Reverts {ResourceNotRegistered} on a vault this
+     *      group does not manage. Removing the resource clears the rate. Emits {SpotAPYBpsSet}.
+     * @param resource Registered Centrifuge vault the rate belongs to.
+     * @param apyBps Annual rate in basis points, or `0` to publish none.
+     */
+    function setSpotAPYBps(address resource, uint64 apyBps) external;
+
+    /**
+     * @notice The rate governance has published for one vault, before it is weighted into the
+     *         group's `spotAPYBps()`.
+     * @param resource Centrifuge vault to look up.
+     * @return apyBps Published annual rate in basis points; `0` when none is published.
+     */
+    function resourceSpotAPYBps(address resource) external view returns (uint64 apyBps);
+}

package/contracts/interfaces/external/ICentrifugeAsyncRequestManager.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title ICentrifugeAsyncRequestManager
+ * @author Venus
+ * @notice The one read `AdapterCentrifuge` needs from Centrifuge's `AsyncRequestManager`: the
+ *         per-position `AsyncInvestmentState` behind every bucket of the adapter's valuation and
+ *         every claim amount.
+ * @dev The struct is declared inline rather than imported from the Centrifuge repo, to avoid an
+ *      npm dependency. Field order and types MUST mirror Centrifuge's `AsyncInvestmentState`
+ *      exactly — they are ABI-load-bearing. Two details make that mirror hold: Centrifuge's `D18`
+ *      price fields are `uint128` underneath, and the real member is a public mapping, whose
+ *      getter encodes identically to this struct-returning function.
+ */
+interface ICentrifugeAsyncRequestManager {
+    // ──────────────────────────── Types ─────────────────────────────
+
+    /// @notice Per-(vault, controller) position state, mirroring `AsyncInvestmentState` in the
+    ///         Centrifuge repo field-for-field. The buckets are disjoint: a cancelled slice is
+    ///         already deducted from the pending counters.
+    struct AsyncInvestmentState {
+        // ── Fulfilled: issued/revoked into escrow, only the claim is left ──
+        uint128 maxMint; // shares already issued, claimable via `mint` (share decimals)
+        uint128 maxWithdraw; // assets already revoked, claimable via `withdraw` (asset decimals)
+        uint128 depositPrice; // D18: weighted avg asset-per-share of the fills behind `maxMint`
+        uint128 redeemPrice; // D18: same, for the fills behind `maxWithdraw`
+        // ── Pending: paid in, not yet fulfilled ──
+        uint128 pendingDepositRequest; // assets sent in, nothing issued yet (asset decimals)
+        uint128 pendingRedeemRequest; // shares sent in, nothing revoked yet (share decimals)
+        // ── Cancelled: returned instead of filled ──
+        uint128 claimableCancelDepositRequest; // assets coming back (asset decimals)
+        uint128 claimableCancelRedeemRequest; // shares coming back (share decimals)
+        bool pendingCancelDepositRequest; // cancel in flight — blocks new deposit requests
+        bool pendingCancelRedeemRequest; // cancel in flight — blocks new redeem requests
+    }
+
+    // ──────────────────────────── Views ─────────────────────────────
+
+    /// @notice Full position state for `controller` on `vault` — the source the adapter values the
+    ///         position from, sizes every claim against, and reads the cancel-in-flight gates off.
+    function investments(address vault, address controller) external view returns (AsyncInvestmentState memory state);
+}