@bananapus/buyback-hook-v6 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/buyback-hook-v6",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,8 +18,8 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-buyback-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.9",
-    "@bananapus/permission-ids-v6": "^0.0.4",
+    "@bananapus/core-v6": "^0.0.10",
+    "@bananapus/permission-ids-v6": "^0.0.5",
     "@openzeppelin/contracts": "^5.2.0",
     "@uniswap/v4-core": "^1.0.2"
   },

package/src/JBBuybackHook.sol

@@ -29,11 +29,11 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
-import {BalanceDelta} from "@uniswap/v4-core/src/types/BalanceDelta.sol";
 import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
 import {IUnlockCallback} from "@uniswap/v4-core/src/interfaces/callback/IUnlockCallback.sol";
 import {StateLibrary} from "@uniswap/v4-core/src/libraries/StateLibrary.sol";
 import {TickMath} from "@uniswap/v4-core/src/libraries/TickMath.sol";
+import {BalanceDelta} from "@uniswap/v4-core/src/types/BalanceDelta.sol";
 import {Currency, CurrencyLibrary} from "@uniswap/v4-core/src/types/Currency.sol";
 import {PoolId, PoolIdLibrary} from "@uniswap/v4-core/src/types/PoolId.sol";
 import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
@@ -181,146 +181,6 @@ contract JBBuybackHook is JBPermissioned, ERC2771Context, IUnlockCallback, IJBBu
         WETH = weth;
     }
 
-    //*********************************************************************//
-    // ------------------------- external views -------------------------- //
-    //*********************************************************************//
-
-    /// @notice To fulfill the `IJBRulesetDataHook` interface.
-    /// @dev Pass cash out context back to the terminal without changes.
-    function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
-        external
-        pure
-        override
-        returns (uint256, uint256, uint256, JBCashOutHookSpecification[] memory hookSpecifications)
-    {
-        return (context.cashOutTaxRate, context.cashOutCount, context.totalSupply, hookSpecifications);
-    }
-
-    /// @notice The `IJBRulesetDataHook` implementation which determines whether tokens should be minted from the
-    /// project or bought from the pool.
-    /// @param context Payment context passed to the data hook by `terminalStore.recordPaymentFrom(...)`.
-    /// `context.metadata` can specify a Uniswap quote and specify how much of the payment should be used to swap.
-    /// If `context.metadata` does not specify a quote, one will be calculated based on the TWAP.
-    /// If `context.metadata` does not specify how much of the payment should be used, the hook uses the full amount
-    /// paid in.
-    /// @return weight The weight to use for minting. 0 if all tokens come from the swap.
-    /// @return hookSpecifications Specifications containing pay hooks, as well as the amount and metadata to send to
-    /// them. Empty if only minting.
-    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
-        external
-        view
-        override
-        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
-    {
-        // Keep a reference to the amount paid in.
-        uint256 totalPaid = context.amount.value;
-
-        // Keep a reference to the weight.
-        weight = context.weight;
-
-        // Keep a reference to the minimum number of tokens expected from the swap.
-        uint256 minimumSwapAmountOut;
-
-        // Keep a reference to the amount to be used to swap (out of `totalPaid`).
-        uint256 amountToSwapWith;
-
-        // Scoped section to prevent stack too deep.
-        {
-            // Unpack the quote specified by the payer/client (typically from the pool).
-            bytes4 metadataId = JBMetadataResolver.getId("quote");
-            (bool quoteExists, bytes memory metadata) = JBMetadataResolver.getDataFor(metadataId, context.metadata);
-            if (quoteExists) (amountToSwapWith, minimumSwapAmountOut) = abi.decode(metadata, (uint256, uint256));
-        }
-
-        // If the amount to swap with is greater than the actual amount paid in, revert.
-        if (amountToSwapWith > totalPaid) revert JBBuybackHook_InsufficientPayAmount(amountToSwapWith, totalPaid);
-
-        // If the payer/client did not specify an amount to use towards the swap, use the `totalPaid`.
-        if (amountToSwapWith == 0) amountToSwapWith = totalPaid;
-
-        // Get a reference to the controller.
-        IJBController controller = IJBController(address(DIRECTORY.controllerOf(context.projectId)));
-
-        // Get a reference to the ruleset.
-        // slither-disable-next-line unused-return
-        (JBRuleset memory ruleset,) = controller.currentRulesetOf(context.projectId);
-
-        // If the hook should base its weight on a currency other than the terminal's currency, determine the factor.
-        uint256 weightRatio = context.amount.currency == ruleset.baseCurrency()
-            ? 10 ** context.amount.decimals
-            : PRICES.pricePerUnitOf({
-                projectId: context.projectId,
-                pricingCurrency: context.amount.currency,
-                unitCurrency: ruleset.baseCurrency(),
-                decimals: context.amount.decimals
-            });
-
-        // Calculate how many tokens would be minted by a direct payment to the project.
-        uint256 tokenCountWithoutHook = mulDiv(amountToSwapWith, weight, weightRatio);
-
-        // Keep a reference to the project's token.
-        address projectToken = projectTokenOf[context.projectId];
-
-        // Keep a reference to the token being used by the terminal. Default to wETH if the terminal uses native.
-        address terminalToken = context.amount.token == JBConstants.NATIVE_TOKEN ? address(WETH) : context.amount.token;
-
-        // Always compute the TWAP-based minimum.
-        uint256 twapMinimum = _getQuote({
-            projectId: context.projectId,
-            projectToken: projectToken,
-            amountIn: amountToSwapWith,
-            terminalToken: terminalToken
-        });
-
-        // Use the higher of the payer's quote and the TWAP quote.
-        // This prevents a stale/malicious payer quote from getting a worse deal than the oracle suggests.
-        if (twapMinimum > minimumSwapAmountOut) minimumSwapAmountOut = twapMinimum;
-
-        // If the minimum amount from the swap exceeds what minting directly would yield, swap.
-        if (tokenCountWithoutHook < minimumSwapAmountOut) {
-            bool projectTokenIs0 = address(projectToken) < terminalToken;
-
-            // Specify this hook as the one to use.
-            hookSpecifications = new JBPayHookSpecification[](1);
-            hookSpecifications[0] = JBPayHookSpecification({
-                hook: IJBPayHook(this),
-                amount: amountToSwapWith,
-                metadata: abi.encode(
-                    projectTokenIs0,
-                    totalPaid == amountToSwapWith ? 0 : totalPaid - amountToSwapWith,
-                    minimumSwapAmountOut,
-                    controller
-                )
-            });
-
-            // All the minting will be done in `afterPayRecordedWith`. Return a weight of 0.
-            return (0, hookSpecifications);
-        }
-    }
-
-    /// @notice Required by the `IJBRulesetDataHook` interfaces. Return false to not leak any permissions.
-    function hasMintPermissionFor(uint256, JBRuleset memory, address) external pure override returns (bool) {
-        return false;
-    }
-
-    //*********************************************************************//
-    // -------------------------- public views --------------------------- //
-    //*********************************************************************//
-
-    /// @notice Returns the PoolKey for a given project and terminal token pair.
-    /// @param projectId The ID of the project.
-    /// @param terminalToken The terminal token address (normalized to WETH for native).
-    /// @return key The V4 PoolKey.
-    function poolKeyOf(uint256 projectId, address terminalToken) public view override returns (PoolKey memory key) {
-        return _poolKeyOf[projectId][terminalToken];
-    }
-
-    function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
-        return interfaceId == type(IJBRulesetDataHook).interfaceId || interfaceId == type(IJBPayHook).interfaceId
-            || interfaceId == type(IJBBuybackHook).interfaceId || interfaceId == type(IJBPermissioned).interfaceId
-            || interfaceId == type(IERC165).interfaceId;
-    }
-
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
@@ -620,94 +480,147 @@ contract JBBuybackHook is JBPermissioned, ERC2771Context, IUnlockCallback, IJBBu
     receive() external payable {}
 
     //*********************************************************************//
-    // -------------------------- internal views ------------------------- //
+    // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @dev `ERC-2771` specifies the context as being a single address (20 bytes).
-    function _contextSuffixLength() internal view override(ERC2771Context, Context) returns (uint256) {
-        return super._contextSuffixLength();
+    /// @notice To fulfill the `IJBRulesetDataHook` interface.
+    /// @dev Pass cash out context back to the terminal without changes.
+    function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
+        external
+        pure
+        override
+        returns (uint256, uint256, uint256, JBCashOutHookSpecification[] memory hookSpecifications)
+    {
+        return (context.cashOutTaxRate, context.cashOutCount, context.totalSupply, hookSpecifications);
     }
 
-    /// @notice Get a quote based on the oracle hook TWAP or spot price.
-    /// @param projectId The ID of the project.
-    /// @param projectToken The project token being swapped for.
-    /// @param amountIn The number of terminal tokens being used to swap.
-    /// @param terminalToken The terminal token being paid in (normalized to WETH for native).
-    /// @return amountOut The minimum number of tokens to receive based on the TWAP and slippage.
-    function _getQuote(
-        uint256 projectId,
-        address projectToken,
-        uint256 amountIn,
-        address terminalToken
-    )
-        internal
+    /// @notice The `IJBRulesetDataHook` implementation which determines whether tokens should be minted from the
+    /// project or bought from the pool.
+    /// @param context Payment context passed to the data hook by `terminalStore.recordPaymentFrom(...)`.
+    /// `context.metadata` can specify a Uniswap quote and specify how much of the payment should be used to swap.
+    /// If `context.metadata` does not specify a quote, one will be calculated based on the TWAP.
+    /// If `context.metadata` does not specify how much of the payment should be used, the hook uses the full amount
+    /// paid in.
+    /// @return weight The weight to use for minting. 0 if all tokens come from the swap.
+    /// @return hookSpecifications Specifications containing pay hooks, as well as the amount and metadata to send to
+    /// them. Empty if only minting.
+    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
+        external
         view
-        returns (uint256 amountOut)
+        override
+        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
     {
-        // Get the pool key for this project/terminal token pair.
-        PoolKey memory key = _poolKeyOf[projectId][terminalToken];
+        // Keep a reference to the amount paid in.
+        uint256 totalPaid = context.amount.value;
 
-        // Make sure a pool has been configured.
-        if (!_poolIsSet[projectId][terminalToken]) return 0;
+        // Keep a reference to the weight.
+        weight = context.weight;
 
-        // Get the TWAP window.
-        uint256 twapWindow = twapWindowOf[projectId];
+        // Keep a reference to the minimum number of tokens expected from the swap.
+        uint256 minimumSwapAmountOut;
 
-        // Query the oracle hook (or spot if twapWindow is 0).
-        int24 arithmeticMeanTick;
-        uint128 meanLiquidity;
-        (amountOut, arithmeticMeanTick, meanLiquidity) = JBSwapLib.getQuoteFromOracle({
-            poolManager: POOL_MANAGER,
-            key: key,
-            twapWindow: uint32(twapWindow),
-            amountIn: uint128(amountIn),
-            baseToken: terminalToken,
-            quoteToken: projectToken
-        });
+        // Keep a reference to the amount to be used to swap (out of `totalPaid`).
+        uint256 amountToSwapWith;
 
-        // If oracle returned 0, no quote available — trigger mint fallback.
-        if (amountOut == 0) return 0;
+        // Scoped section to prevent stack too deep.
+        {
+            // Unpack the quote specified by the payer/client (typically from the pool).
+            bytes4 metadataId = JBMetadataResolver.getId("quote");
+            (bool quoteExists, bytes memory metadata) = JBMetadataResolver.getDataFor(metadataId, context.metadata);
+            if (quoteExists) (amountToSwapWith, minimumSwapAmountOut) = abi.decode(metadata, (uint256, uint256));
+        }
 
-        // If there's no liquidity data, return 0 to trigger mint.
-        if (meanLiquidity == 0) return 0;
+        // If the amount to swap with is greater than the actual amount paid in, revert.
+        if (amountToSwapWith > totalPaid) revert JBBuybackHook_InsufficientPayAmount(amountToSwapWith, totalPaid);
 
-        // Calculate price impact.
-        bool zeroForOne = terminalToken < projectToken;
-        uint160 sqrtP = TickMath.getSqrtPriceAtTick(arithmeticMeanTick);
-        uint256 impact = JBSwapLib.calculateImpact(amountIn, meanLiquidity, sqrtP, zeroForOne);
+        // If the payer/client did not specify an amount to use towards the swap, use the `totalPaid`.
+        if (amountToSwapWith == 0) amountToSwapWith = totalPaid;
 
-        // Get the pool fee in bps (V4 fees are in hundredths of a bip, so divide by 100).
-        uint256 poolFeeBps = uint256(key.fee) / 100;
+        // Get a reference to the controller.
+        IJBController controller = IJBController(address(DIRECTORY.controllerOf(context.projectId)));
 
-        // Calculate continuous sigmoid slippage tolerance.
-        uint256 slippageTolerance = JBSwapLib.getSlippageTolerance(impact, poolFeeBps);
+        // Get a reference to the ruleset.
+        // slither-disable-next-line unused-return
+        (JBRuleset memory ruleset,) = controller.currentRulesetOf(context.projectId);
 
-        // If the slippage tolerance is the maximum, return 0 to trigger mint.
-        if (slippageTolerance >= TWAP_SLIPPAGE_DENOMINATOR) return 0;
+        // If the hook should base its weight on a currency other than the terminal's currency, determine the factor.
+        uint256 weightRatio = context.amount.currency == ruleset.baseCurrency()
+            ? 10 ** context.amount.decimals
+            : PRICES.pricePerUnitOf({
+                projectId: context.projectId,
+                pricingCurrency: context.amount.currency,
+                unitCurrency: ruleset.baseCurrency(),
+                decimals: context.amount.decimals
+            });
 
-        // Apply slippage to the oracle quote.
-        amountOut -= (amountOut * slippageTolerance) / TWAP_SLIPPAGE_DENOMINATOR;
+        // Calculate how many tokens would be minted by a direct payment to the project.
+        uint256 tokenCountWithoutHook = mulDiv(amountToSwapWith, weight, weightRatio);
+
+        // Keep a reference to the project's token.
+        address projectToken = projectTokenOf[context.projectId];
+
+        // Keep a reference to the token being used by the terminal. Default to wETH if the terminal uses native.
+        address terminalToken = context.amount.token == JBConstants.NATIVE_TOKEN ? address(WETH) : context.amount.token;
+
+        // Always compute the TWAP-based minimum.
+        uint256 twapMinimum = _getQuote({
+            projectId: context.projectId,
+            projectToken: projectToken,
+            amountIn: amountToSwapWith,
+            terminalToken: terminalToken
+        });
+
+        // Use the higher of the payer's quote and the TWAP quote.
+        // This prevents a stale/malicious payer quote from getting a worse deal than the oracle suggests.
+        if (twapMinimum > minimumSwapAmountOut) minimumSwapAmountOut = twapMinimum;
+
+        // If the minimum amount from the swap exceeds what minting directly would yield, swap.
+        if (tokenCountWithoutHook < minimumSwapAmountOut) {
+            bool projectTokenIs0 = address(projectToken) < terminalToken;
+
+            // Specify this hook as the one to use.
+            hookSpecifications = new JBPayHookSpecification[](1);
+            hookSpecifications[0] = JBPayHookSpecification({
+                hook: IJBPayHook(this),
+                amount: amountToSwapWith,
+                metadata: abi.encode(
+                    projectTokenIs0,
+                    totalPaid == amountToSwapWith ? 0 : totalPaid - amountToSwapWith,
+                    minimumSwapAmountOut,
+                    controller
+                )
+            });
+
+            // All the minting will be done in `afterPayRecordedWith`. Return a weight of 0.
+            return (0, hookSpecifications);
+        }
     }
 
-    /// @notice The calldata. Preferred to use over `msg.data`.
-    function _msgData() internal view override(ERC2771Context, Context) returns (bytes calldata) {
-        return ERC2771Context._msgData();
+    /// @notice Required by the `IJBRulesetDataHook` interfaces. Return false to not leak any permissions.
+    function hasMintPermissionFor(uint256, JBRuleset memory, address) external pure override returns (bool) {
+        return false;
     }
 
-    /// @notice The message's sender. Preferred to use over `msg.sender`.
-    function _msgSender() internal view override(ERC2771Context, Context) returns (address sender) {
-        return ERC2771Context._msgSender();
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
+    /// @notice Returns the PoolKey for a given project and terminal token pair.
+    /// @param projectId The ID of the project.
+    /// @param terminalToken The terminal token address (normalized to WETH for native).
+    /// @return key The V4 PoolKey.
+    function poolKeyOf(uint256 projectId, address terminalToken) public view override returns (PoolKey memory key) {
+        return _poolKeyOf[projectId][terminalToken];
     }
 
-    /// @notice Returns this contract's balance of the given terminal token.
-    /// @param token The terminal token address (NATIVE_TOKEN for ETH).
-    /// @return balance The current balance held by this contract.
-    function _terminalTokenBalance(address token) internal view returns (uint256 balance) {
-        return token == JBConstants.NATIVE_TOKEN ? address(this).balance : IERC20(token).balanceOf(address(this));
+    function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
+        return interfaceId == type(IJBRulesetDataHook).interfaceId || interfaceId == type(IJBPayHook).interfaceId
+            || interfaceId == type(IJBBuybackHook).interfaceId || interfaceId == type(IJBPermissioned).interfaceId
+            || interfaceId == type(IERC165).interfaceId;
     }
 
     //*********************************************************************//
-    // ---------------------- internal functions ------------------------- //
+    // ---------------------- internal transactions ---------------------- //
     //*********************************************************************//
 
     /// @notice Swap the terminal token to receive project tokens via V4.
@@ -779,4 +692,91 @@ contract JBBuybackHook is JBPermissioned, ERC2771Context, IUnlockCallback, IJBBu
             });
         }
     }
+
+    //*********************************************************************//
+    // -------------------------- internal views ------------------------- //
+    //*********************************************************************//
+
+    /// @dev `ERC-2771` specifies the context as being a single address (20 bytes).
+    function _contextSuffixLength() internal view override(ERC2771Context, Context) returns (uint256) {
+        return super._contextSuffixLength();
+    }
+
+    /// @notice Get a quote based on the oracle hook TWAP or spot price.
+    /// @param projectId The ID of the project.
+    /// @param projectToken The project token being swapped for.
+    /// @param amountIn The number of terminal tokens being used to swap.
+    /// @param terminalToken The terminal token being paid in (normalized to WETH for native).
+    /// @return amountOut The minimum number of tokens to receive based on the TWAP and slippage.
+    function _getQuote(
+        uint256 projectId,
+        address projectToken,
+        uint256 amountIn,
+        address terminalToken
+    )
+        internal
+        view
+        returns (uint256 amountOut)
+    {
+        // Get the pool key for this project/terminal token pair.
+        PoolKey memory key = _poolKeyOf[projectId][terminalToken];
+
+        // Make sure a pool has been configured.
+        if (!_poolIsSet[projectId][terminalToken]) return 0;
+
+        // Get the TWAP window.
+        uint256 twapWindow = twapWindowOf[projectId];
+
+        // Query the oracle hook (or spot if twapWindow is 0).
+        int24 arithmeticMeanTick;
+        uint128 meanLiquidity;
+        (amountOut, arithmeticMeanTick, meanLiquidity) = JBSwapLib.getQuoteFromOracle({
+            poolManager: POOL_MANAGER,
+            key: key,
+            twapWindow: uint32(twapWindow),
+            amountIn: uint128(amountIn),
+            baseToken: terminalToken,
+            quoteToken: projectToken
+        });
+
+        // If oracle returned 0, no quote available — trigger mint fallback.
+        if (amountOut == 0) return 0;
+
+        // If there's no liquidity data, return 0 to trigger mint.
+        if (meanLiquidity == 0) return 0;
+
+        // Calculate price impact.
+        bool zeroForOne = terminalToken < projectToken;
+        uint160 sqrtP = TickMath.getSqrtPriceAtTick(arithmeticMeanTick);
+        uint256 impact = JBSwapLib.calculateImpact(amountIn, meanLiquidity, sqrtP, zeroForOne);
+
+        // Get the pool fee in bps (V4 fees are in hundredths of a bip, so divide by 100).
+        uint256 poolFeeBps = uint256(key.fee) / 100;
+
+        // Calculate continuous sigmoid slippage tolerance.
+        uint256 slippageTolerance = JBSwapLib.getSlippageTolerance(impact, poolFeeBps);
+
+        // If the slippage tolerance is the maximum, return 0 to trigger mint.
+        if (slippageTolerance >= TWAP_SLIPPAGE_DENOMINATOR) return 0;
+
+        // Apply slippage to the oracle quote.
+        amountOut -= (amountOut * slippageTolerance) / TWAP_SLIPPAGE_DENOMINATOR;
+    }
+
+    /// @notice The calldata. Preferred to use over `msg.data`.
+    function _msgData() internal view override(ERC2771Context, Context) returns (bytes calldata) {
+        return ERC2771Context._msgData();
+    }
+
+    /// @notice The message's sender. Preferred to use over `msg.sender`.
+    function _msgSender() internal view override(ERC2771Context, Context) returns (address sender) {
+        return ERC2771Context._msgSender();
+    }
+
+    /// @notice Returns this contract's balance of the given terminal token.
+    /// @param token The terminal token address (NATIVE_TOKEN for ETH).
+    /// @return balance The current balance held by this contract.
+    function _terminalTokenBalance(address token) internal view returns (uint256 balance) {
+        return token == JBConstants.NATIVE_TOKEN ? address(this).balance : IERC20(token).balanceOf(address(this));
+    }
 }

package/src/JBBuybackHookRegistry.sol

@@ -80,77 +80,6 @@ contract JBBuybackHookRegistry is IJBBuybackHookRegistry, ERC2771Context, JBPerm
         PROJECTS = projects;
     }
 
-    //*********************************************************************//
-    // ------------------------- external views -------------------------- //
-    //*********************************************************************//
-
-    /// @notice To fulfill the `IJBRulesetDataHook` interface.
-    /// @dev Pass cash out context back to the terminal without changes.
-    /// @param context The cash out context passed in by the terminal.
-    function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
-        external
-        pure
-        override
-        returns (uint256, uint256, uint256, JBCashOutHookSpecification[] memory hookSpecifications)
-    {
-        return (context.cashOutTaxRate, context.cashOutCount, context.totalSupply, hookSpecifications);
-    }
-
-    /// @notice Forward the call to the hook for the project.
-    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
-        external
-        view
-        override
-        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
-    {
-        // Get the hook for the project (falls back to default).
-        IJBRulesetDataHook hook = _hookOf[context.projectId];
-        if (hook == IJBRulesetDataHook(address(0))) hook = defaultHook;
-
-        // Forward the call to the hook.
-        // slither-disable-next-line unused-return
-        return hook.beforePayRecordedWith(context);
-    }
-
-    /// @notice Make sure the hook has mint permission.
-    /// @param projectId The ID of the project to check the mint permission for.
-    /// @param addr The address to check the mint permission for.
-    /// @return Whether the address has mint permission.
-    function hasMintPermissionFor(
-        uint256 projectId,
-        JBRuleset memory,
-        address addr
-    )
-        external
-        view
-        override
-        returns (bool)
-    {
-        // Get the hook for the project (falls back to default).
-        IJBRulesetDataHook hook = _hookOf[projectId];
-        if (hook == IJBRulesetDataHook(address(0))) hook = defaultHook;
-
-        // Make sure the hook has mint permission.
-        return addr == address(hook);
-    }
-
-    /// @notice The hook for the given project, or the default hook if none is set.
-    /// @param projectId The ID of the project to get the hook for.
-    /// @return hook The hook for the project.
-    function hookOf(uint256 projectId) external view override returns (IJBRulesetDataHook hook) {
-        hook = _hookOf[projectId];
-        if (hook == IJBRulesetDataHook(address(0))) hook = defaultHook;
-    }
-
-    //*********************************************************************//
-    // -------------------------- public views --------------------------- //
-    //*********************************************************************//
-
-    function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
-        return interfaceId == type(IJBBuybackHookRegistry).interfaceId
-            || interfaceId == type(IJBRulesetDataHook).interfaceId || interfaceId == type(IERC165).interfaceId;
-    }
-
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
@@ -248,6 +177,77 @@ contract JBBuybackHookRegistry is IJBBuybackHookRegistry, ERC2771Context, JBPerm
         emit JBBuybackHookRegistry_SetHook(projectId, hook);
     }
 
+    //*********************************************************************//
+    // ------------------------- external views -------------------------- //
+    //*********************************************************************//
+
+    /// @notice To fulfill the `IJBRulesetDataHook` interface.
+    /// @dev Pass cash out context back to the terminal without changes.
+    /// @param context The cash out context passed in by the terminal.
+    function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
+        external
+        pure
+        override
+        returns (uint256, uint256, uint256, JBCashOutHookSpecification[] memory hookSpecifications)
+    {
+        return (context.cashOutTaxRate, context.cashOutCount, context.totalSupply, hookSpecifications);
+    }
+
+    /// @notice Forward the call to the hook for the project.
+    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
+        external
+        view
+        override
+        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
+    {
+        // Get the hook for the project (falls back to default).
+        IJBRulesetDataHook hook = _hookOf[context.projectId];
+        if (hook == IJBRulesetDataHook(address(0))) hook = defaultHook;
+
+        // Forward the call to the hook.
+        // slither-disable-next-line unused-return
+        return hook.beforePayRecordedWith(context);
+    }
+
+    /// @notice Make sure the hook has mint permission.
+    /// @param projectId The ID of the project to check the mint permission for.
+    /// @param addr The address to check the mint permission for.
+    /// @return Whether the address has mint permission.
+    function hasMintPermissionFor(
+        uint256 projectId,
+        JBRuleset memory,
+        address addr
+    )
+        external
+        view
+        override
+        returns (bool)
+    {
+        // Get the hook for the project (falls back to default).
+        IJBRulesetDataHook hook = _hookOf[projectId];
+        if (hook == IJBRulesetDataHook(address(0))) hook = defaultHook;
+
+        // Make sure the hook has mint permission.
+        return addr == address(hook);
+    }
+
+    /// @notice The hook for the given project, or the default hook if none is set.
+    /// @param projectId The ID of the project to get the hook for.
+    /// @return hook The hook for the project.
+    function hookOf(uint256 projectId) external view override returns (IJBRulesetDataHook hook) {
+        hook = _hookOf[projectId];
+        if (hook == IJBRulesetDataHook(address(0))) hook = defaultHook;
+    }
+
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
+    function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
+        return interfaceId == type(IJBBuybackHookRegistry).interfaceId
+            || interfaceId == type(IJBRulesetDataHook).interfaceId || interfaceId == type(IERC165).interfaceId;
+    }
+
     //*********************************************************************//
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//

package/src/interfaces/IJBBuybackHook.sol

@@ -13,28 +13,27 @@ import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
 
 import {IWETH9} from "./external/IWETH9.sol";
 
-/// @notice A hook that facilitates buybacks of project tokens using Uniswap V4 pools.
 interface IJBBuybackHook is IJBPayHook, IJBRulesetDataHook {
-    /// @notice Emitted when tokens are minted instead of swapped.
-    /// @param projectId The ID of the project whose tokens were minted.
-    /// @param leftoverAmount The amount left over after minting.
-    /// @param tokenCount The number of tokens minted.
-    /// @param caller The address that called the function.
+    /// @notice Emitted when leftover terminal tokens are minted as project tokens.
+    /// @param projectId The ID of the project whose tokens are being minted.
+    /// @param leftoverAmount The amount of terminal tokens used for minting.
+    /// @param tokenCount The number of project tokens minted.
+    /// @param caller The address that triggered the mint.
     event Mint(uint256 indexed projectId, uint256 leftoverAmount, uint256 tokenCount, address caller);
 
-    /// @notice Emitted when a pool is added for a project and terminal token.
-    /// @param projectId The ID of the project the pool was added for.
-    /// @param terminalToken The terminal token address.
+    /// @notice Emitted when a pool is added for a project and terminal token pair.
+    /// @param projectId The ID of the project the pool is being added for.
+    /// @param terminalToken The address of the terminal token.
     /// @param poolId The ID of the Uniswap V4 pool.
-    /// @param caller The address that called the function.
+    /// @param caller The address that added the pool.
     event PoolAdded(uint256 indexed projectId, address indexed terminalToken, PoolId poolId, address caller);
 
-    /// @notice Emitted when a swap is performed through the buyback hook.
-    /// @param projectId The ID of the project the swap was performed for.
-    /// @param amountToSwapWith The amount used for the swap.
+    /// @notice Emitted when terminal tokens are swapped for project tokens via the Uniswap V4 pool.
+    /// @param projectId The ID of the project whose tokens are being swapped for.
+    /// @param amountToSwapWith The amount of terminal tokens used for the swap.
     /// @param poolId The ID of the Uniswap V4 pool used.
     /// @param amountReceived The amount of project tokens received from the swap.
-    /// @param caller The address that called the function.
+    /// @param caller The address that triggered the swap.
     event Swap(
         uint256 indexed projectId,
         uint256 amountToSwapWith,
@@ -43,11 +42,11 @@ interface IJBBuybackHook is IJBPayHook, IJBRulesetDataHook {
         address caller
     );
 
-    /// @notice Emitted when the TWAP window is changed for a project.
-    /// @param projectId The ID of the project whose TWAP window was changed.
-    /// @param oldWindow The previous TWAP window value.
-    /// @param newWindow The new TWAP window value.
-    /// @param caller The address that called the function.
+    /// @notice Emitted when the TWAP window for a project is changed.
+    /// @param projectId The ID of the project whose TWAP window is being changed.
+    /// @param oldWindow The previous TWAP window in seconds.
+    /// @param newWindow The new TWAP window in seconds.
+    /// @param caller The address that changed the TWAP window.
     event TwapWindowChanged(uint256 indexed projectId, uint256 oldWindow, uint256 newWindow, address caller);
 
     /// @notice The directory of terminals and controllers.
@@ -62,7 +61,7 @@ interface IJBBuybackHook is IJBPayHook, IJBRulesetDataHook {
     /// @return The minimum TWAP window in seconds.
     function MIN_TWAP_WINDOW() external view returns (uint256);
 
-    /// @notice The Uniswap V4 pool manager.
+    /// @notice The Uniswap V4 PoolManager singleton.
     /// @return The pool manager contract.
     function POOL_MANAGER() external view returns (IPoolManager);
 
@@ -82,22 +81,22 @@ interface IJBBuybackHook is IJBPayHook, IJBRulesetDataHook {
     /// @return The slippage denominator.
     function TWAP_SLIPPAGE_DENOMINATOR() external view returns (uint256);
 
-    /// @notice The WETH contract.
-    /// @return The WETH9 contract.
+    /// @notice The wETH contract.
+    /// @return The WETH contract.
     function WETH() external view returns (IWETH9);
 
-    /// @notice The Uniswap V4 pool key for a given project and terminal token.
+    /// @notice The PoolKey for a given project and terminal token pair.
     /// @param projectId The ID of the project.
     /// @param terminalToken The terminal token address.
-    /// @return key The pool key.
+    /// @return key The V4 PoolKey.
     function poolKeyOf(uint256 projectId, address terminalToken) external view returns (PoolKey memory key);
 
-    /// @notice The project token address for a given project.
+    /// @notice The address of each project's token.
     /// @param projectId The ID of the project.
-    /// @return projectTokenOf The project token address.
+    /// @return projectTokenOf The project's token address.
     function projectTokenOf(uint256 projectId) external view returns (address projectTokenOf);
 
-    /// @notice The TWAP window for a given project.
+    /// @notice The TWAP window for the given project.
     /// @param projectId The ID of the project.
     /// @return window The TWAP window in seconds.
     function twapWindowOf(uint256 projectId) external view returns (uint256 window);
@@ -115,8 +114,8 @@ interface IJBBuybackHook is IJBPayHook, IJBRulesetDataHook {
     )
         external;
 
-    /// @notice Set the TWAP window for a given project.
-    /// @param projectId The ID of the project to set the TWAP window for.
-    /// @param newWindow The new TWAP window in seconds.
+    /// @notice Change the TWAP window for a project.
+    /// @param projectId The ID of the project to set the TWAP window of.
+    /// @param newWindow The new TWAP window.
     function setTwapWindowOf(uint256 projectId, uint256 newWindow) external;
 }

package/src/interfaces/IJBBuybackHookRegistry.sol

@@ -4,9 +4,8 @@ pragma solidity ^0.8.0;
 import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
 import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDataHook.sol";
 
-/// @notice A registry that manages which buyback hooks are used by projects.
 interface IJBBuybackHookRegistry is IJBRulesetDataHook {
-    /// @notice Emitted when a hook is allowed to be used by projects.
+    /// @notice Emitted when a hook is allowed for use by projects.
     /// @param hook The hook that was allowed.
     event JBBuybackHookRegistry_AllowHook(IJBRulesetDataHook hook);
 
@@ -14,7 +13,7 @@ interface IJBBuybackHookRegistry is IJBRulesetDataHook {
     /// @param hook The hook that was disallowed.
     event JBBuybackHookRegistry_DisallowHook(IJBRulesetDataHook hook);
 
-    /// @notice Emitted when the hook for a project is locked.
+    /// @notice Emitted when a project's hook is locked, preventing it from being changed.
     /// @param projectId The ID of the project whose hook was locked.
     event JBBuybackHookRegistry_LockHook(uint256 projectId);
 
@@ -27,6 +26,10 @@ interface IJBBuybackHookRegistry is IJBRulesetDataHook {
     /// @param hook The hook that was set.
     event JBBuybackHookRegistry_SetHook(uint256 indexed projectId, IJBRulesetDataHook hook);
 
+    /// @notice The project registry.
+    /// @return The projects contract.
+    function PROJECTS() external view returns (IJBProjects);
+
     /// @notice The default hook used when a project has not set a specific hook.
     /// @return The default data hook.
     function defaultHook() external view returns (IJBRulesetDataHook);
@@ -46,10 +49,6 @@ interface IJBBuybackHookRegistry is IJBRulesetDataHook {
     /// @return Whether the hook is allowed.
     function isHookAllowed(IJBRulesetDataHook hook) external view returns (bool);
 
-    /// @notice The project registry.
-    /// @return The projects contract.
-    function PROJECTS() external view returns (IJBProjects);
-
     /// @notice Allow a hook to be used by projects.
     /// @param hook The hook to allow.
     function allowHook(IJBRulesetDataHook hook) external;