Interest distribution operator

.forge-snapshots/ERC7540Vault_requestDeposit.snap

@@ -1 +1 @@
-574684
+597184

.forge-snapshots/InterestDistributor_distribute_requestRedeem.snap

@@ -0,0 +1 @@
+434922

.forge-snapshots/InterestDistributor_distribute_updateShares.snap

@@ -0,0 +1 @@
+71669

script/Deployer.sol

@@ -13,6 +13,7 @@ import {PoolManager} from "src/PoolManager.sol";
 import {Escrow} from "src/Escrow.sol";
 import {CentrifugeRouter} from "src/CentrifugeRouter.sol";
 import {Guardian} from "src/admin/Guardian.sol";
+import {InterestDistributor} from "src/operators/InterestDistributor.sol";
 import {IAuth} from "src/interfaces/IAuth.sol";
 import "forge-std/Script.sol";
 
@@ -31,6 +32,7 @@ contract Deployer is Script {
     GasService public gasService;
     CentrifugeRouter public router;
     TransferProxyFactory public transferProxyFactory;
+    InterestDistributor public interestDistributor;
     address public vaultFactory;
     address public restrictionManager;
     address public trancheFactory;
@@ -60,6 +62,7 @@ contract Deployer is Script {
         gateway = new Gateway(address(root), address(poolManager), address(investmentManager), address(gasService));
         router = new CentrifugeRouter(address(routerEscrow), address(gateway), address(poolManager));
         guardian = new Guardian(adminSafe, address(root), address(gateway));
+        interestDistributor = new InterestDistributor(address(poolManager));
 
         _endorse();
         _rely();

src/CentrifugeRouter.sol

@@ -15,6 +15,7 @@ import {IGateway} from "src/interfaces/gateway/IGateway.sol";
 import {TransientStorage} from "src/libraries/TransientStorage.sol";
 import {IRecoverable} from "src/interfaces/IRoot.sol";
 import {ITransferProxy} from "src/interfaces/factories/ITransferProxy.sol";
+import {IInterestDistributor} from "src/interfaces/operators/IInterestDistributor.sol";
 
 /// @title  CentrifugeRouter
 /// @notice This is a helper contract, designed to be the entrypoint for EOAs.
@@ -36,6 +37,7 @@ contract CentrifugeRouter is Auth, ICentrifugeRouter {
     IEscrow public immutable escrow;
     IGateway public immutable gateway;
     IPoolManager public immutable poolManager;
+    IInterestDistributor public immutable interestDistributor;
 
     /// @inheritdoc ICentrifugeRouter
     mapping(address controller => mapping(address vault => uint256 amount)) public lockedRequests;
@@ -67,11 +69,11 @@ contract CentrifugeRouter is Auth, ICentrifugeRouter {
     }
 
     // --- Enable interactions with the vault ---
-    function enable(address vault) public protected {
+    function enable(address vault) public payable protected {
         IERC7540Vault(vault).setEndorsedOperator(msg.sender, true);
     }
 
-    function disable(address vault) external protected {
+    function disable(address vault) external payable protected {
         IERC7540Vault(vault).setEndorsedOperator(msg.sender, false);
     }
 
@@ -218,6 +220,12 @@ contract CentrifugeRouter is Auth, ICentrifugeRouter {
         IERC7540Vault(vault).claimCancelRedeemRequest(REQUEST_ID, receiver, controller);
     }
 
+    /// @inheritdoc ICentrifugeRouter
+    function distributeInterest(address vault, address controller, uint256 topUpAmount) external payable protected {
+        if (topUpAmount > 0) _pay(topUpAmount);
+        interestDistributor.distribute(vault, controller);
+    }
+
     // --- Transfer ---
     /// @inheritdoc ICentrifugeRouter
     function transferAssets(address asset, bytes32 recipient, uint128 amount, uint256 topUpAmount)

src/interfaces/ICentrifugeRouter.sol

@@ -21,10 +21,10 @@ interface ICentrifugeRouter is IRecoverable {
     /// @dev    After this is called, anyone can claim tokens to msg.sender.
     ///         Even any requests submitted directly to the vault (not through the CentrifugeRouter) will be
     ///         permissionlessly claimable through the CentrifugeRouter, until `disable()` is called.
-    function enable(address vault) external;
+    function enable(address vault) external payable;
 
     /// @notice Disable permissionless claiming
-    function disable(address vault) external;
+    function disable(address vault) external payable;
 
     // --- Deposit ---
     /// @notice Check `IERC7540Deposit.requestDeposit`.
@@ -154,6 +154,9 @@ interface ICentrifugeRouter is IRecoverable {
     /// @param  controller Check  IERC7540CancelRedeem.claimCancelRedeemRequest.controller
     function claimCancelRedeemRequest(address vault, address receiver, address controller) external payable;
 
+    /// @notice TODO
+    function distributeInterest(address vault, address controller, uint256 topUpAmount) external payable;
+
     // --- Transfer ---
     /// @notice Check `IPoolManager.transferAssets`.
     /// @dev    This adds a mandatory prepayment for all the costs that will incur during the transaction.

src/interfaces/operators/IInterestDistributor.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+pragma solidity >=0.5.0;
+
+struct InterestDetails {
+    /// @dev Time of the last price update after which a distribution happened.
+    ///      Downcast from uint64 so only works until 2106.
+    uint32 lastUpdate;
+    /// @dev Highest recorded price (downcast from uint256)
+    uint96 peak;
+    /// @dev Outstanding shares on which the interest calculation is based.
+    uint128 shares;
+}
+
+interface IInterestDistributor {
+    // --- Events ---
+    event InterestRedeemRequest(
+        address indexed vault, address indexed controller, uint96 previousPrice, uint96 currentPrice, uint128 request
+    );
+    event OutstandingSharesUpdate(address indexed vault, address indexed controller, uint128 previous, uint128 current);
+    event Clear(address indexed vault, address indexed controller);
+
+    /// @notice Trigger redeem request of pending interest for a controller who has set the interest distributor
+    ///         as an operator for the given vault.
+    ///         Should be called after any fulfillment to update the outstanding shares.
+    ///         Interest is only redeemed in the next price update after the first distribute() call post fulfillment.
+    function distribute(address vault, address controller) external;
+
+    /// @notice Called by controllers to disable the use of the interest distributor, after they have called
+    ///         setOperator(address(interestDistributor), false)
+    function clear(address vault, address controller) external;
+
+    /// @notice Returns the pending interest to be redeemed.
+    function pending(address vault, address controller) external view returns (uint128 shares);
+}

src/operators/InterestDistributor.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+pragma solidity 0.8.26;
+
+import {IERC20} from "src/interfaces/IERC20.sol";
+import {IERC7540Vault} from "src/interfaces/IERC7540.sol";
+import {IPoolManager} from "src/interfaces/IPoolManager.sol";
+import {MathLib} from "src/libraries/MathLib.sol";
+import {IInterestDistributor, InterestDetails} from "src/interfaces/operators/IInterestDistributor.sol";
+
+/// @title  InterestDistributor
+/// @notice Contract that can be enabled by calling vault.setOperator(address(interestDistributor), true), which then
+///         allows permissionless triggers of redeem requests for the accrued interest on a vault.
+///
+///         Whenever a user claims new tranche tokens or a principal redeem request is initiated,
+///         distribute() should be called to update the outstanding shares that the interest is computed based on.
+///
+///         Uses peak price to calculate interest. If the price goes down, interest will only be redeemed
+///         again once the price fully recovers above the previous high point (peak).
+///         Peak is stored per user since if the price has globally gone down, and a user invests at that time,
+///         they'd expect to redeem interest based on the price they invested in, not the previous high point.
+/// @dev    Requires that:
+///         - Whenever orders are fulfilled, an UpdateTranchePrice message is also submitted
+///         - Users claim the complete fulfilled amount using the router, rather than partial claims through the vault.
+///         Otherwise the interest amounts may be off.
+contract InterestDistributor is IInterestDistributor {
+    using MathLib for uint256;
+
+    mapping(address vault => mapping(address user => InterestDetails)) internal _users;
+
+    IPoolManager public immutable poolManager;
+
+    constructor(address poolManager_) {
+        poolManager = IPoolManager(poolManager_);
+    }
+
+    /// @inheritdoc IInterestDistributor
+    function distribute(address vault, address controller) external {
+        IERC7540Vault vault_ = IERC7540Vault(vault);
+        require(vault_.isOperator(controller, address(this)), "InterestDistributor/not-an-operator");
+
+        InterestDetails memory user = _users[vault][controller];
+        uint128 prevShares = user.shares;
+
+        (address asset,) = poolManager.getVaultAsset(vault);
+        (uint128 currentPrice, uint64 priceLastUpdated) =
+            poolManager.getTranchePrice(vault_.poolId(), vault_.trancheId(), asset);
+        uint128 currentShares = IERC20(vault_.share()).balanceOf(controller).toUint128();
+
+        // Calculate request before updating user.shares, so it is based on the balance at the last price update.
+        // Assuming price updates coincide with epoch fulfillments, this results in only requesting
+        // interest on the previous outstanding balance before the new fulfillment.
+        uint128 request = priceLastUpdated > user.lastUpdate
+            ? _computeRequest(prevShares, currentShares, user.peak, uint96(currentPrice))
+            : 0;
+
+        user.lastUpdate = uint32(priceLastUpdated);
+        if (currentPrice > user.peak) user.peak = uint96(currentPrice);
+        user.shares = currentShares - request;
+        _users[vault][controller] = user;
+
+        if (request > 0) {
+            vault_.requestRedeem(request, controller, controller);
+            emit InterestRedeemRequest(vault, controller, user.peak, uint96(currentPrice), request);
+        }
+
+        if (user.shares != prevShares) {
+            emit OutstandingSharesUpdate(vault, controller, prevShares, user.shares);
+        }
+    }
+
+    /// @inheritdoc IInterestDistributor
+    function clear(address vault, address controller) external {
+        require(!IERC7540Vault(vault).isOperator(controller, address(this)), "InterestDistributor/still-an-operator");
+        require(_users[vault][controller].lastUpdate > 0, "InterestDistributor/unknown-controller");
+
+        delete _users[vault][controller];
+        emit Clear(vault, controller);
+    }
+
+    /// @inheritdoc IInterestDistributor
+    function pending(address vault, address controller) external view returns (uint128 shares) {
+        InterestDetails memory user = _users[vault][controller];
+        IERC7540Vault vault_ = IERC7540Vault(vault);
+        (uint128 currentPrice, uint64 priceLastUpdated) =
+            poolManager.getTranchePrice(vault_.poolId(), vault_.trancheId(), vault_.asset());
+        if (user.lastUpdate == uint32(priceLastUpdated)) return 0;
+        shares =
+            _computeRequest(user.shares, IERC20(vault_.share()).balanceOf(controller), user.peak, uint96(currentPrice));
+    }
+
+    /// @dev Calculate shares to redeem based on outstandingShares * ((currentPrice - prevPrice) / currentPrice)
+    function _computeRequest(uint128 outstandingShares, uint256 currentShares, uint96 prevPrice, uint96 currentPrice)
+        internal
+        pure
+        returns (uint128)
+    {
+        if (outstandingShares == 0 || currentPrice <= prevPrice) return 0;
+
+        return MathLib.min(
+            uint256(outstandingShares).mulDiv(currentPrice - prevPrice, currentPrice, MathLib.Rounding.Down),
+            currentShares
+        ).toUint128();
+    }
+}

test/integration/InterestDistributor.t.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+pragma solidity 0.8.26;
+
+import "test/BaseTest.sol";
+
+contract InterestDistributorTest is BaseTest {
+    function testDistributeInterest(uint256 amount) public {
+        // If lower than 4 or odd, rounding down can lead to not receiving any tokens
+        amount = uint128(bound(amount, 4, MAX_UINT128));
+        vm.assume(amount % 2 == 0);
+
+        uint128 price = 1 * 10 ** 18;
+        address vault_ = deploySimpleVault();
+        address investor = makeAddr("investor");
+        ERC7540Vault vault = ERC7540Vault(vault_);
+
+        centrifugeChain.updateTranchePrice(
+            vault.poolId(), vault.trancheId(), defaultAssetId, price, uint64(block.timestamp)
+        );
+
+        erc20.mint(investor, amount);
+
+        centrifugeChain.updateMember(vault.poolId(), vault.trancheId(), investor, type(uint64).max);
+        vm.prank(investor);
+        erc20.approve(vault_, amount);
+
+        vm.prank(investor);
+        vault.requestDeposit(amount, investor, investor);
+
+        centrifugeChain.isFulfilledDepositRequest(
+            vault.poolId(),
+            vault.trancheId(),
+            bytes32(bytes20(investor)),
+            defaultAssetId,
+            uint128(amount),
+            uint128(amount)
+        );
+
+        vm.prank(investor);
+        vault.deposit(amount, investor, investor);
+
+        // Initially, pending interest is 0
+        assertApproxEqAbs(vault.pendingRedeemRequest(0, investor), 0, 1);
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), 0, 1);
+
+        vm.expectRevert(bytes("InterestDistributor/not-an-operator"));
+        interestDistributor.distribute(vault_, investor);
+
+        vm.prank(investor);
+        vault.setOperator(address(interestDistributor), true);
+
+        snapStart("InterestDistributor_distribute_updateShares");
+        interestDistributor.distribute(vault_, investor);
+        snapEnd();
+
+        assertApproxEqAbs(vault.pendingRedeemRequest(0, investor), 0, 1);
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), 0, 1);
+
+        // Once price goes to 1.25, 1/5th of the total shares are redeemed
+        vm.warp(block.timestamp + 1 days);
+        centrifugeChain.updateTranchePrice(
+            vault.poolId(), vault.trancheId(), defaultAssetId, 1.25 * 10 ** 18, uint64(block.timestamp)
+        );
+
+        assertApproxEqAbs(vault.pendingRedeemRequest(0, investor), 0, 1);
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), amount / 5, 1);
+
+        snapStart("InterestDistributor_distribute_requestRedeem");
+        interestDistributor.distribute(vault_, investor);
+        snapEnd();
+
+        assertApproxEqAbs(vault.pendingRedeemRequest(0, investor), amount / 5, 1);
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), 0, 1);
+
+        // When price goes down, no new redemption is submitted
+        vm.warp(block.timestamp + 1 days);
+        centrifugeChain.updateTranchePrice(
+            vault.poolId(), vault.trancheId(), defaultAssetId, 1.0 * 10 ** 18, uint64(block.timestamp)
+        );
+
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), 0, 1);
+        interestDistributor.distribute(vault_, investor);
+
+        vm.warp(block.timestamp + 1 days);
+        centrifugeChain.updateTranchePrice(
+            vault.poolId(), vault.trancheId(), defaultAssetId, 1.1 * 10 ** 18, uint64(block.timestamp)
+        );
+
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), 0, 1);
+        interestDistributor.distribute(vault_, investor);
+
+        // Once price goes above 1.25 (to 2.50) again, shares are redeemed
+        vm.warp(block.timestamp + 1 days);
+        centrifugeChain.updateTranchePrice(
+            vault.poolId(), vault.trancheId(), defaultAssetId, 2.5 * 10 ** 18, uint64(block.timestamp)
+        );
+
+        assertApproxEqAbs(interestDistributor.pending(vault_, investor), (amount - amount / 5) / 2, 1);
+    }
+
+    // TODO: testDistributeAfterAnotherDeposit
+    // TODO: testDistributeAfterPrincipalRedemption
+    // TODO: testClear
+}