@bananapus/core-v6 0.0.54 → 0.0.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.54",
+  "version": "0.0.55",
   "license": "MIT",
   "repository": {
     "type": "git",

package/script/helpers/CoreDeploymentLib.sol

@@ -43,11 +43,10 @@ library CoreDeploymentLib {
     string constant PROJECT_NAME = "nana-core-v6";
 
     function getDeployment(string memory path) internal returns (CoreDeployment memory deployment) {
-        // get chainId for which we need to get the deployment.
+        // Match the current chain ID to the Sphinx network name used in deployment artifacts.
         uint256 chainId = block.chainid;
 
-        // Deploy to get the constants.
-        // TODO: get constants without deploy.
+        // `SphinxConstants` exposes Sphinx's supported chain ID to network name mapping.
         SphinxConstants sphinxConstants = new SphinxConstants();
         NetworkInfo[] memory networks = sphinxConstants.getNetworkInfoArray();
 

package/src/JBController.sol

@@ -1061,7 +1061,8 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             JBSplit memory split = splits[i];
 
             // Calculate the amount to send to the split.
-            uint256 splitTokenCount = mulDiv(tokenCount, split.percent, JBConstants.SPLITS_TOTAL_PERCENT);
+            uint256 splitTokenCount =
+                mulDiv({x: tokenCount, y: split.percent, denominator: JBConstants.SPLITS_TOTAL_PERCENT});
 
             // Mints tokens for the split if needed.
             if (splitTokenCount > 0) {
@@ -1264,8 +1265,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         returns (uint256 beneficiaryTokenCount, uint256 reservedTokenCount)
     {
         // Compute the beneficiary's portion after removing the reserved share.
-        beneficiaryTokenCount =
-            mulDiv(tokenCount, JBConstants.MAX_RESERVED_PERCENT - reservedPercent, JBConstants.MAX_RESERVED_PERCENT);
+        beneficiaryTokenCount = mulDiv({
+            x: tokenCount,
+            y: JBConstants.MAX_RESERVED_PERCENT - reservedPercent,
+            denominator: JBConstants.MAX_RESERVED_PERCENT
+        });
 
         // The remaining tokens are reserved.
         reservedTokenCount = tokenCount - beneficiaryTokenCount;

package/src/JBERC20.sol

@@ -41,7 +41,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
 
     /// @notice The JBTokens contract that owns this token.
     /// @dev Set via `initialize` because JBERC20 is deployed before JBTokens (circular dependency).
-    IJBTokens public TOKENS;
+    IJBTokens public tokens;
 
     //*********************************************************************//
     // -------------------- private stored properties -------------------- //
@@ -80,7 +80,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @notice Only the JBTokens contract can call this function.
     // forge-lint: disable-next-line(unwrapped-modifier-logic)
     modifier onlyTokens() {
-        if (msg.sender != address(TOKENS)) revert JBERC20_Unauthorized({caller: msg.sender, tokens: address(TOKENS)});
+        if (msg.sender != address(tokens)) revert JBERC20_Unauthorized({caller: msg.sender, tokens: address(tokens)});
         _;
     }
 
@@ -130,11 +130,11 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @return magicValue `0x1626ba7e` if the signature is valid, `0xffffffff` otherwise.
     function isValidSignature(bytes32 hash, bytes memory signature) external view override returns (bytes4 magicValue) {
         // Recover the signer from the signature. Return invalid if recovery fails.
-        (address signer, ECDSA.RecoverError error,) = ECDSA.tryRecover(hash, signature);
+        (address signer, ECDSA.RecoverError error,) = ECDSA.tryRecover({hash: hash, signature: signature});
         if (error != ECDSA.RecoverError.NoError) return 0xffffffff;
 
         // Get the project ID this token belongs to.
-        uint256 projectId = TOKENS.projectIdOf(IJBToken(address(this)));
+        uint256 projectId = tokens.projectIdOf(IJBToken(address(this)));
 
         // Get the project owner (the NFT holder).
         address projectOwner = PROJECTS.ownerOf(projectId);
@@ -195,8 +195,8 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @notice Initialize a new project token with the given name, symbol, and owner.
     /// @param name_ The token's name.
     /// @param symbol_ The token's symbol.
-    /// @param tokens The JBTokens contract that manages this token.
-    function initialize(string memory name_, string memory symbol_, address tokens) public override {
+    /// @param tokensAddress The JBTokens contract that manages this token.
+    function initialize(string memory name_, string memory symbol_, address tokensAddress) public override {
         // Prevent re-initialization by reverting if a name is already set or if the provided name is empty.
         if (bytes(_name).length != 0 || bytes(name_).length == 0) {
             revert JBERC20_AlreadyInitialized({
@@ -206,7 +206,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
 
         _name = name_;
         _symbol = symbol_;
-        TOKENS = IJBTokens(tokens);
+        tokens = IJBTokens(tokensAddress);
     }
 
     //*********************************************************************//

package/src/JBFeelessAddresses.sol

@@ -5,12 +5,28 @@ import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 import {IJBFeelessAddresses} from "./interfaces/IJBFeelessAddresses.sol";
+import {IJBFeelessHook} from "./interfaces/IJBFeelessHook.sol";
 
 /// @notice A registry of addresses exempt from the protocol's 2.5% fee. Feeless addresses don't incur fees on
 /// payouts they receive, surplus allowance they use, or cash outs where they are the beneficiary.
 /// @dev All feeless status is managed by the contract owner (typically the protocol multisig).
 /// @dev `projectId = 0` is the wildcard — an address feeless for project 0 is feeless for ALL projects.
 contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JBFeelessAddresses_InvalidFeelessHook(IJBFeelessHook hook);
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice Optional hook consulted (in addition to the static mappings) when computing feeless status.
+    /// @dev OR'd with the mappings — the hook can only widen the feeless set, never shrink it. `address(0)` disables
+    /// hook consultation.
+    IJBFeelessHook public override feelessHook;
+
     //*********************************************************************//
     // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
@@ -53,19 +69,48 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
         emit SetFeelessAddress({projectId: projectId, addr: addr, isFeeless: flag, caller: _msgSender()});
     }
 
+    /// @notice Sets (or clears) the feeless hook consulted by `isFeelessFor`.
+    /// @dev Can only be called by this contract's owner (typically the protocol multisig).
+    /// @dev If `hook` is non-zero, it must report ERC-165 support for `IJBFeelessHook` or this call reverts.
+    /// @param hook The new hook. Pass `address(0)` to disable hook consultation.
+    function setFeelessHook(IJBFeelessHook hook) external virtual override onlyOwner {
+        if (address(hook) != address(0) && !hook.supportsInterface(type(IJBFeelessHook).interfaceId)) {
+            revert JBFeelessAddresses_InvalidFeelessHook(hook);
+        }
+
+        feelessHook = hook;
+
+        emit SetFeelessHook({hook: hook, caller: _msgSender()});
+    }
+
     //*********************************************************************//
-    // -------------------------- public views --------------------------- //
+    // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Returns whether the specified address is feeless for a specific project, considering both the wildcard
-    /// (projectId 0) and project-specific feeless status.
+    /// @notice Returns whether the specified address is feeless for a specific project, considering the wildcard
+    /// (projectId 0) feeless status, the project-specific feeless status, and the feeless hook (if set).
+    /// @dev The hook is invoked via try/catch — a reverting or out-of-gas hook is treated as `false` so it cannot
+    /// brick the fee path in terminals.
     /// @param addr The address to check.
     /// @param projectId The ID of the project to check.
-    /// @return A flag indicating whether the address is feeless (globally or for the project).
+    /// @return A flag indicating whether the address is feeless (globally, for the project, or per the hook).
     function isFeelessFor(address addr, uint256 projectId) external view override returns (bool) {
-        return _isFeelessFor[0][addr] || _isFeelessFor[projectId][addr];
+        if (_isFeelessFor[0][addr] || _isFeelessFor[projectId][addr]) return true;
+
+        IJBFeelessHook hook = feelessHook;
+        if (address(hook) == address(0)) return false;
+
+        try hook.isFeeless({projectId: projectId, addr: addr}) returns (bool result) {
+            return result;
+        } catch {
+            return false;
+        }
     }
 
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
     /// @notice Indicates whether this contract adheres to the specified interface.
     /// @dev See {IERC165-supportsInterface}.
     /// @param interfaceId The ID of the interface to check for adherence to.

package/src/JBMultiTerminal.sol

@@ -367,6 +367,31 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
             // Track the fee-free payout amount. During cashout at zero tax rate, fees apply
             // only up to this accumulated amount, preventing round-trip fee bypass.
+            // Revert on any self-referencing payout (the source project paying itself via a split),
+            // regardless of which terminal receives the call or which branch (pay vs add-to-balance)
+            // is taken. Both shapes are disguised owner actions that the payout pipeline must not
+            // silently authorize:
+            //   - pay branch: the destination terminal's `pay()` mints new project tokens against
+            //     the project's own surplus, diluting holders out-of-cycle and bypassing the
+            //     ruleset's `allowOwnerMinting=false` guarantee. This holds even when the
+            //     destination terminal is a different instance owned by the same project, because
+            //     every registered terminal can mint via the terminal-as-minter pathway.
+            //   - addToBalance branch: a same-project add-balance split shuffles surplus between
+            //     the project's own terminals through the payout pipeline. The same effect is
+            //     available via `addToBalanceOf` directly without the side effects (locked-split
+            //     consumption, payout-limit drawdown, fee-free-surplus accounting); routing it
+            //     through `sendPayoutsOf` is never the right surface.
+            // The try-catch in the split group lib catches this revert and restores the balance.
+            if (split.projectId == projectId) {
+                revert JBMultiTerminal_MintNotAllowed({
+                    projectId: projectId, splitProjectId: split.projectId, terminal: address(terminal)
+                });
+            }
+
+            // Track the fee-free payout amount. During cashout at zero tax rate, fees apply
+            // only up to this accumulated amount, preventing round-trip fee bypass. Same-project
+            // splits would inflate this counter against the project's own future zero-tax cashouts
+            // but are already excluded by the self-reference revert above.
             if (terminal == this) {
                 _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
             }
@@ -384,17 +409,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     metadata: metadata
                 });
             } else {
-                // Revert if this is a self-referencing payout (project paying itself via a split).
-                // Same-project pay splits would mint tokens against existing balance without new funds entering.
-                // Projects that want to mint should do so explicitly via the controller.
-                // Cross-project pay splits on the same terminal are allowed (different project receives the funds).
-                // The try-catch in the split group lib catches this revert and restores the balance.
-                if (terminal == this && split.projectId == projectId) {
-                    revert JBMultiTerminal_MintNotAllowed({
-                        projectId: projectId, splitProjectId: split.projectId, terminal: address(terminal)
-                    });
-                }
-
                 // Keep a reference to the beneficiary of the payment.
                 address beneficiary = split.beneficiary != address(0) ? split.beneficiary : originalMessageSender;
 

package/src/JBPrices.sol

@@ -202,7 +202,7 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
         // is in the range of ~1e9 to ~1e27 (for 18 decimals). Extreme prices outside this range may lose
         // significant precision due to fixed-point division truncation.
         if (feed != IJBPriceFeed(address(0))) {
-            return mulDiv(10 ** decimals, 10 ** decimals, feed.currentUnitPrice(decimals));
+            return mulDiv({x: 10 ** decimals, y: 10 ** decimals, denominator: feed.currentUnitPrice(decimals)});
         }
 
         // Check for a default feed (project ID 0) if not found.

package/src/JBRulesets.sol

@@ -623,11 +623,11 @@ contract JBRulesets is JBControlled, IJBRulesets {
     {
         // A subsequent ruleset to one with a duration of 0 should have the next possible weight.
         if (baseRulesetDuration == 0) {
-            return mulDiv(
-                baseRulesetWeight,
-                JBConstants.MAX_WEIGHT_CUT_PERCENT - baseRulesetWeightCutPercent,
-                JBConstants.MAX_WEIGHT_CUT_PERCENT
-            );
+            return mulDiv({
+                x: baseRulesetWeight,
+                y: JBConstants.MAX_WEIGHT_CUT_PERCENT - baseRulesetWeightCutPercent,
+                denominator: JBConstants.MAX_WEIGHT_CUT_PERCENT
+            });
         }
 
         // The weight should be based off the base ruleset's weight.
@@ -673,7 +673,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
         for (uint256 i; i < weightCutMultiple;) {
             // Base the new weight on the specified ruleset's weight.
-            weight = mulDiv(weight, cutFactor, maxPercent);
+            weight = mulDiv({x: weight, y: cutFactor, denominator: maxPercent});
 
             // The calculation doesn't need to continue if the weight is 0.
             if (weight == 0) break;

package/src/JBTokens.sol

@@ -230,7 +230,7 @@ contract JBTokens is JBControlled, IJBTokens {
         });
 
         // Initialize the token.
-        token.initialize({name: name, symbol: symbol, tokens: address(this)});
+        token.initialize({name: name, symbol: symbol, tokensAddress: address(this)});
     }
 
     /// @notice Create new tokens for a holder. If the project has an ERC-20 deployed, tokens are minted directly to

package/src/interfaces/IJBFeelessAddresses.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+import {IJBFeelessHook} from "./IJBFeelessHook.sol";
+
 /// @notice Tracks addresses that are exempt from fees, both globally and on a per-project basis.
 /// @dev `projectId = 0` is the wildcard — an address feeless for project 0 is feeless for ALL projects.
 interface IJBFeelessAddresses {
@@ -11,11 +13,21 @@ interface IJBFeelessAddresses {
     /// @param caller The address that set the feeless status.
     event SetFeelessAddress(uint256 indexed projectId, address indexed addr, bool indexed isFeeless, address caller);
 
-    /// @notice Returns whether the specified address is feeless for a specific project, considering both the wildcard
-    /// (projectId 0) and project-specific feeless status.
+    /// @notice The optional hook (set by the owner) that can grant feeless status with arbitrary logic. Set to the
+    /// zero address to disable.
+    /// @param hook The new feeless hook. The zero address disables hook consultation.
+    /// @param caller The address that set the hook.
+    event SetFeelessHook(IJBFeelessHook indexed hook, address caller);
+
+    /// @notice The optional hook consulted (in addition to the static mappings) when computing feeless status.
+    /// @dev `address(0)` means no hook is set.
+    function feelessHook() external view returns (IJBFeelessHook);
+
+    /// @notice Returns whether the specified address is feeless for a specific project, considering the wildcard
+    /// (projectId 0) feeless status, the project-specific feeless status, and the feeless hook (if set).
     /// @param addr The address to check.
     /// @param projectId The ID of the project to check.
-    /// @return A flag indicating whether the address is feeless (globally or for the project).
+    /// @return A flag indicating whether the address is feeless (globally, for the project, or per the hook).
     function isFeelessFor(address addr, uint256 projectId) external view returns (bool);
 
     /// @notice Sets whether an address is feeless globally (for all projects).
@@ -28,4 +40,8 @@ interface IJBFeelessAddresses {
     /// @param addr The address to set the feeless status of.
     /// @param flag A flag indicating whether the address should be feeless for the project.
     function setFeelessAddressFor(uint256 projectId, address addr, bool flag) external;
+
+    /// @notice Sets (or clears) the feeless hook consulted by `isFeelessFor`.
+    /// @param hook The new hook. Pass `address(0)` to disable hook consultation.
+    function setFeelessHook(IJBFeelessHook hook) external;
 }

package/src/interfaces/IJBFeelessHook.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+/// @notice Optional hook that can grant feeless status to addresses based on arbitrary off-chain or on-chain logic.
+/// @dev Plugged into `JBFeelessAddresses` by the contract owner. The hook is OR'd with the static feeless mappings,
+/// so it can only widen the feeless set, never shrink it.
+/// @dev `JBFeelessAddresses` invokes this hook inside a try/catch — a reverting hook is treated as returning `false`,
+/// so a broken hook cannot brick the fee path in terminals.
+interface IJBFeelessHook is IERC165 {
+    /// @notice Returns whether the address should be treated as feeless for the project.
+    /// @param projectId The ID of the project the fee would be charged on behalf of.
+    /// @param addr The address being checked (typically a payout recipient, surplus allowance beneficiary, or
+    /// cash-out beneficiary).
+    /// @return A flag indicating whether the address is feeless for the project under the hook's custom logic.
+    function isFeeless(uint256 projectId, address addr) external view returns (bool);
+}

package/src/interfaces/IJBToken.sol

@@ -29,8 +29,8 @@ interface IJBToken {
     /// @notice Initializes the token with a name, symbol, and the JBTokens contract.
     /// @param name The token's name.
     /// @param symbol The token's symbol.
-    /// @param tokens The JBTokens contract that manages this token.
-    function initialize(string memory name, string memory symbol, address tokens) external;
+    /// @param tokensAddress The JBTokens contract that manages this token.
+    function initialize(string memory name, string memory symbol, address tokensAddress) external;
 
     /// @notice Mints tokens to an account.
     /// @param account The address to mint tokens to.

package/src/libraries/JBCashOuts.sol

@@ -42,7 +42,7 @@ library JBCashOuts {
         if (cashOutCount >= totalSupply) return surplus;
 
         // Get a reference to the linear proportion.
-        uint256 base = mulDiv(surplus, cashOutCount, totalSupply);
+        uint256 base = mulDiv({x: surplus, y: cashOutCount, denominator: totalSupply});
 
         // These conditions are all part of the same curve.
         // Edge conditions are separated to minimize the operations performed in those cases.
@@ -50,11 +50,12 @@ library JBCashOuts {
             return base;
         }
 
-        return mulDiv(
-            base,
-            (JBConstants.MAX_CASH_OUT_TAX_RATE - cashOutTaxRate) + mulDiv(cashOutTaxRate, cashOutCount, totalSupply),
-            JBConstants.MAX_CASH_OUT_TAX_RATE
-        );
+        return mulDiv({
+            x: base,
+            y: (JBConstants.MAX_CASH_OUT_TAX_RATE - cashOutTaxRate)
+                + mulDiv({x: cashOutTaxRate, y: cashOutCount, denominator: totalSupply}),
+            denominator: JBConstants.MAX_CASH_OUT_TAX_RATE
+        });
     }
 
     /// @notice Returns the minimum number of tokens that must be cashed out to receive at least `desiredOutput` of
@@ -93,9 +94,9 @@ library JBCashOuts {
 
         // Linear case (no tax): out = surplus * c / totalSupply, so c = ceil(out * totalSupply / surplus).
         if (cashOutTaxRate == 0) {
-            uint256 count = mulDiv(desiredOutput, totalSupply, surplus);
+            uint256 count = mulDiv({x: desiredOutput, y: totalSupply, denominator: surplus});
             // Round up if the floor division undershoots.
-            if (mulDiv(surplus, count, totalSupply) < desiredOutput) count++;
+            if (mulDiv({x: surplus, y: count, denominator: totalSupply}) < desiredOutput) count++;
             return count;
         }
 

package/src/libraries/JBFees.sol

@@ -15,7 +15,7 @@ library JBFees {
     /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
     /// @return The fee amount, as a fixed point number with the same number of decimals as `amountBeforeFee`.
     function feeAmountFrom(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
-        return mulDiv(amountBeforeFee, feePercent, JBConstants.MAX_FEE);
+        return mulDiv({x: amountBeforeFee, y: feePercent, denominator: JBConstants.MAX_FEE});
     }
 
     /// @notice Returns the fee amount that, when added to `amountAfterFee`, produces the gross amount needed to yield
@@ -25,7 +25,8 @@ library JBFees {
     /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
     /// @return The fee amount, as a fixed point number with the same number of decimals as `amountAfterFee`.
     function feeAmountResultingIn(uint256 amountAfterFee, uint256 feePercent) internal pure returns (uint256) {
-        return mulDiv(amountAfterFee, JBConstants.MAX_FEE, JBConstants.MAX_FEE - feePercent) - amountAfterFee;
+        return mulDiv({x: amountAfterFee, y: JBConstants.MAX_FEE, denominator: JBConstants.MAX_FEE - feePercent})
+            - amountAfterFee;
     }
 
     /// @notice Returns the standard protocol fee taken from `amountBeforeFee`.
@@ -45,6 +46,6 @@ library JBFees {
     /// @return The fee amount that, when added to `amountAfterFee`, yields the gross pre-fee amount.
     function standardFeeAmountResultingIn(uint256 amountAfterFee) internal pure returns (uint256) {
         // Use `mulDiv` instead of `amountAfterFee * 40 / 39` to preserve overflow safety.
-        return mulDiv(amountAfterFee, 40, 39) - amountAfterFee;
+        return mulDiv({x: amountAfterFee, y: 40, denominator: 39}) - amountAfterFee;
     }
 }

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -141,7 +141,7 @@ library JBPayoutSplitGroupLib {
         // refund = amount * (netPayoutAmount - sent) / netPayoutAmount. For full consumption this branch is
         // skipped. For zero consumption this refunds the full `amount` (i.e. the gross, fee allocation included).
         if (sent < netPayoutAmount) {
-            uint256 refund = mulDiv(amount, netPayoutAmount - sent, netPayoutAmount);
+            uint256 refund = mulDiv({x: amount, y: netPayoutAmount - sent, denominator: netPayoutAmount});
             if (refund != 0) {
                 store.recordAddedBalanceFor({projectId: projectId, token: token, amount: refund});
             }
@@ -151,7 +151,7 @@ library JBPayoutSplitGroupLib {
         // gross-equivalent of what the hook actually consumed so the held fee scales with consumption rather
         // than with the project's original payout intent.
         if (netPayoutAmount < amount && sent != 0) {
-            feeEligibleAmount = mulDiv(amount, sent, netPayoutAmount);
+            feeEligibleAmount = mulDiv({x: amount, y: sent, denominator: netPayoutAmount});
         }
     }
 
@@ -192,7 +192,7 @@ library JBPayoutSplitGroupLib {
             JBSplit memory split = payoutSplits[i];
 
             // The amount to send to the split.
-            uint256 payoutAmount = mulDiv(leftoverAmount, split.percent, leftoverPercentage);
+            uint256 payoutAmount = mulDiv({x: leftoverAmount, y: split.percent, denominator: leftoverPercentage});
 
             // Send the payout (inlined to keep stack pressure manageable with the tuple return).
             // Returns (netPayoutAmount sent, feeEligible gross-equivalent). For non-hook splits and fully-consumed

package/test/mock/MockFeelessHook.sol

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IJBFeelessHook} from "../../src/interfaces/IJBFeelessHook.sol";
+
+import {ERC165, IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
+
+/// @notice Configurable `IJBFeelessHook` mock for unit tests.
+/// @dev `mode` controls behavior of `isFeeless`:
+///   - 0: returns `defaultResult` for any (projectId, addr)
+///   - 1: reverts with `Nope()`
+///   - 2: reverts via `require(false, "nope")`
+///   - 3: returns `true` iff `(projectId, addr)` has been allowlisted via `setAllowed`
+contract MockFeelessHook is ERC165, IJBFeelessHook {
+    error Nope();
+
+    uint256 public mode;
+    bool public defaultResult;
+    mapping(uint256 => mapping(address => bool)) internal _allowed;
+
+    function setMode(uint256 newMode) external {
+        mode = newMode;
+    }
+
+    function setDefaultResult(bool result) external {
+        defaultResult = result;
+    }
+
+    function setAllowed(uint256 projectId, address addr, bool flag) external {
+        _allowed[projectId][addr] = flag;
+    }
+
+    function isFeeless(uint256 projectId, address addr) external view override returns (bool) {
+        if (mode == 1) revert Nope();
+        if (mode == 2) require(false, "nope");
+        if (mode == 3) return _allowed[projectId][addr];
+        return defaultResult;
+    }
+
+    function supportsInterface(bytes4 interfaceId) public view override(IERC165, ERC165) returns (bool) {
+        return interfaceId == type(IJBFeelessHook).interfaceId || super.supportsInterface(interfaceId);
+    }
+}
+
+/// @notice Non-conforming "hook" that returns false for the IJBFeelessHook interfaceId in ERC-165.
+/// @dev Used to test the `setFeelessHook` validation guard. Has the `isFeeless` selector so the
+/// call shape matches, but its `supportsInterface` advertises only IERC165, not IJBFeelessHook.
+contract MockNonConformingFeelessHook is ERC165 {
+    function isFeeless(uint256, address) external pure returns (bool) {
+        return true;
+    }
+}
+
+/// @notice "Hook" with no `supportsInterface` at all — `setFeelessHook` should revert when this is passed.
+contract MockEoaLikeFeelessHook {
+    function isFeeless(uint256, address) external pure returns (bool) {
+        return true;
+    }
+}