@bananapus/core-v6 0.0.46 → 0.0.48

package/package.json

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

package/src/JBController.sol

@@ -238,12 +238,12 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice Burns a holder's project tokens (or credits), permanently removing them from supply. Used by terminals
-    /// during cash outs, or directly by holders who want to burn voluntarily.
+    /// @notice Burns a holder's project tokens (or unclaimed credits), permanently removing them from the project
+    /// token supply. Used by terminals during cash outs, or directly by holders who want to burn voluntarily.
     /// @dev Can only be called by the holder, an operator with `BURN_TOKENS` permission, or a project terminal.
-    /// @param holder The address to burn tokens for.
-    /// @param projectId The ID of the project to burn tokens for.
-    /// @param tokenCount The number of tokens to burn.
+    /// @param holder The address whose project tokens (or credits) are being burned.
+    /// @param projectId The ID of the project whose tokens are being burned.
+    /// @param tokenCount The number of project tokens (or credits) to burn, as a fixed point number with 18 decimals.
     /// @param memo A memo to pass along to the emitted event.
     function burnTokensOf(
         address holder,
@@ -273,13 +273,16 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         TOKENS.burnFrom({holder: holder, projectId: projectId, count: tokenCount});
     }
 
-    /// @notice Converts internal credits into the project's ERC-20 token, transferring them to the beneficiary's
-    /// wallet. Credits and ERC-20 tokens are interchangeable — this just makes them transferable/tradeable.
+    /// @notice Converts a holder's internal project token credits into the project's ERC-20 representation,
+    /// transferring them to the beneficiary's wallet. Credits and the ERC-20 are equivalent project tokens — this
+    /// just
+    /// makes them transferable/tradeable.
     /// @dev Can only be called by the credit holder or an operator with `CLAIM_TOKENS` permission.
-    /// @param holder The address to redeem credits from.
-    /// @param projectId The ID of the project to claim tokens for.
-    /// @param tokenCount The number of tokens to claim.
-    /// @param beneficiary The account the claimed tokens will go to.
+    /// @param holder The address whose project token credits are being redeemed.
+    /// @param projectId The ID of the project whose project tokens are being claimed.
+    /// @param tokenCount The number of project token credits to convert into ERC-20 project tokens, as a fixed point
+    /// number with 18 decimals.
+    /// @param beneficiary The account that receives the resulting ERC-20 project tokens.
     function claimTokensFor(
         address holder,
         uint256 projectId,
@@ -520,12 +523,14 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     /// reserved percent (which accumulates until `sendReservedTokensToSplitsOf` is called).
     /// @dev Can be called by the project owner, an operator with `MINT_TOKENS` permission, a project terminal, or the
     /// data hook. If `allowOwnerMinting` is false in the current ruleset, only terminals and the data hook can mint.
-    /// @param projectId The ID of the project to mint tokens for.
-    /// @param tokenCount The number of tokens to mint, including any reserved tokens.
-    /// @param beneficiary The address which will receive the (non-reserved) tokens.
+    /// @param projectId The ID of the project whose project tokens are being minted.
+    /// @param tokenCount The total number of project tokens to mint (the beneficiary's share plus the reserved share if
+    /// `useReservedPercent` is true), as a fixed point number with 18 decimals.
+    /// @param beneficiary The address that receives the non-reserved portion of the minted project tokens.
     /// @param memo A memo to pass along to the emitted event.
     /// @param useReservedPercent Whether to apply the ruleset's reserved percent.
-    /// @return beneficiaryTokenCount The number of tokens minted for the `beneficiary`.
+    /// @return beneficiaryTokenCount The number of project tokens minted to `beneficiary` (excluding the reserved
+    /// share), as a fixed point number with 18 decimals.
     function mintTokensOf(
         uint256 projectId,
         uint256 tokenCount,

package/src/JBMultiTerminal.sol

@@ -220,14 +220,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Adds funds to a project's balance without minting tokens. Useful for topping up a project or returning
-    /// funds. Can also unlock previously held fees by returning them to the project's balance.
+    /// @notice Adds funds (terminal tokens) to a project's balance without minting project tokens. Useful for topping
+    /// up a project or returning funds. Can also unlock previously held fees by returning them to the project's
+    /// balance.
     /// @dev If `shouldReturnHeldFees` is true, the added amount offsets held fees proportionally.
     /// @param projectId The ID of the project to add funds to the balance of.
-    /// @param amount The amount of tokens to add to the balance, as a fixed point number with the same number of
-    /// decimals as the token's accounting context. If this is a native token terminal, this is ignored and `msg.value`
-    /// is used instead.
-    /// @param token The token to add to the balance.
+    /// @param token The terminal token being added (the ERC-20, or `JBConstants.NATIVE_TOKEN` for native).
+    /// @param amount The amount of the terminal `token` to add, as a fixed point number with the same number of
+    /// decimals as the token's accounting context. If `token` is the native token, this argument is ignored and
+    /// `msg.value` is used instead.
     /// @param shouldReturnHeldFees If true, return held fees proportional to the amount added.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the emitted event.
@@ -254,24 +255,25 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Cash out project tokens. The project's current ruleset determines the reclaimed surplus and any data
-    /// hook or cash out hook behavior.
-    /// @dev Only the token holder or an operator with `CASH_OUT_TOKENS` permission from that holder can call this.
-    /// @param holder The account cashing out tokens.
+    /// @notice Burn project tokens to reclaim a share of the project's surplus (held as a terminal token). The
+    /// project's current ruleset determines the reclaimed amount, plus any data hook or cash out hook behavior.
+    /// @dev Only the project token holder, or an operator with `CASH_OUT_TOKENS` permission from that holder, can call
+    /// this.
+    /// @dev Two distinct tokens are involved: **project tokens** (`cashOutCount`) are burned from `holder`, and
+    /// **terminal tokens** (`tokenToReclaim`) are sent to `beneficiary` in exchange.
+    /// @param holder The account whose project tokens are being burned.
     /// @param projectId The ID of the project the project tokens belong to.
-    /// @param cashOutCount The number of project tokens to cash out and burn, as a fixed point number with 18
-    /// decimals.
-    /// @param tokenToReclaim The token to reclaim.
-    /// @param minTokensReclaimed The minimum number of terminal tokens expected in return, as a fixed point number with
-    /// the same number of decimals as the token's accounting context. If the amount of tokens minted for the
-    /// beneficiary would be less than this amount, the cash out is reverted.
-    /// @param beneficiary The address to send the cashed out terminal tokens to, and to pass along to the ruleset's
+    /// @param cashOutCount The number of project tokens to burn, as a fixed point number with 18 decimals.
+    /// @param tokenToReclaim The terminal token to reclaim from the project's surplus.
+    /// @param minTokensReclaimed The minimum number of terminal tokens that must be returned to `beneficiary` for the
+    /// call to succeed, as a fixed point number with the same number of decimals as the terminal token's accounting
+    /// context. If fewer terminal tokens would be reclaimed, the cash out is reverted.
+    /// @param beneficiary The address to send the reclaimed terminal tokens to, and to pass along to the ruleset's
     /// data hook and cash out hook if applicable.
     /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hook if
     /// applicable.
-    /// @return reclaimAmount The amount of terminal tokens that the project tokens were cashed out for, as a fixed
-    /// point
-    /// number with 18 decimals.
+    /// @return reclaimAmount The amount of **terminal tokens** sent to `beneficiary` in exchange for the burned project
+    /// tokens, as a fixed point number with the same number of decimals as the terminal token's accounting context.
     function cashOutTokensOf(
         address holder,
         uint256 projectId,
@@ -317,7 +319,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         address originalMessageSender
     )
         external
-        returns (uint256 netPayoutAmount)
+        returns (uint256 netPayoutAmount, uint256 feeEligibleAmount)
     {
         // NOTICE: May only be called by this terminal itself.
         require(msg.sender == address(this));
@@ -332,36 +334,24 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 revert JBMultiTerminal_SplitHookInvalid({hook: split.hook});
             }
 
-            // This payout is eligible for a fee since the funds are leaving this contract and the split hook isn't a
-            // feeless address.
             if (!_isFeeless({addr: address(split.hook), projectId: projectId})) {
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
             }
 
-            // Create the context to send to the split hook.
-            JBSplitHookContext memory context = JBSplitHookContext({
-                token: token,
-                amount: netPayoutAmount,
-                decimals: STORE.accountingContextOf({
-                    terminal: address(this), projectId: projectId, token: token
-                }).decimals,
+            // Delegate the partial-pull-aware hook invocation to the library so this branch stays compact.
+            // The library builds the hook context internally and infers fee-eligibility from
+            // `netPayoutAmount < amount` (`true` only when a fee was deducted above).
+            (netPayoutAmount, feeEligibleAmount) = JBPayoutSplitGroupLib.invokeSplitHookWithPartial({
+                split: split,
                 projectId: projectId,
-                groupId: uint256(uint160(token)),
-                split: split
+                token: token,
+                amount: amount,
+                netPayoutAmount: netPayoutAmount,
+                store: STORE
             });
 
-            // Trigger any inherited pre-transfer logic.
-            // Get a reference to the amount being paid in `msg.value`.
-            uint256 payValue = _beforeTransferTo({to: address(split.hook), token: token, amount: netPayoutAmount});
-
-            // If this terminal's token is the native token, send it in `msg.value`.
-            split.hook.processSplitWith{value: payValue}(context);
-
-            // Revoke the temporary pull allowance now that the hook call has finished.
-            _afterTransferTo({to: address(split.hook), token: token});
-
             // Otherwise, if a project is specified, make a payment to it.
         } else if (split.projectId != 0) {
             // Get a reference to the terminal being used.
@@ -381,6 +371,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
+                feeEligibleAmount = amount;
             }
 
             // Track the fee-free payout amount. During cashout at zero tax rate, fees apply
@@ -444,6 +435,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
+                feeEligibleAmount = amount;
             }
 
             // If there's a beneficiary, send the funds directly to the beneficiary. Otherwise send to the
@@ -565,22 +557,25 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project. The project's current ruleset determines how many project tokens the beneficiary receives
-    /// and any data hook or pay hook behavior.
+    /// @notice Pay a project with a payment token. The project's ruleset determines how many project tokens the
+    /// beneficiary receives, plus any data hook or pay hook behavior.
+    /// @dev Two distinct tokens are involved: the **payment token** (`token`, e.g. ETH or an ERC-20) flows from the
+    /// payer into the terminal, and **project tokens** (the project's own ERC-20 / credit balance) are minted to the
+    /// `beneficiary` according to the ruleset's weight.
     /// @param projectId The ID of the project to pay.
-    /// @param amount The amount of tokens to send, as a fixed point number with the same number of
-    /// decimals as the token's accounting context. If this terminal's token is native, this is ignored and `msg.value`
-    /// is used in its place.
-    /// @param token The token to pay with.
-    /// @param beneficiary The address to mint tokens to, and pass along to the ruleset's data hook and pay hook if
-    /// applicable.
-    /// @param minReturnedTokens The minimum number of project tokens expected in return for this payment, as a fixed
-    /// point number with the same number of decimals as the token's accounting context. If the amount of tokens minted
-    /// for the beneficiary would be less than this amount, the payment is reverted.
+    /// @param token The payment token to pay with (the ERC-20, or `JBConstants.NATIVE_TOKEN` for native).
+    /// @param amount The amount of the payment `token` to send, as a fixed point number with the same number of
+    /// decimals as the token's accounting context. If `token` is the native token, this argument is ignored and
+    /// `msg.value` is used in its place.
+    /// @param beneficiary The address to mint project tokens to, and to pass along to the ruleset's data hook and pay
+    /// hook if applicable.
+    /// @param minReturnedTokens The minimum number of project tokens the beneficiary must receive for the payment to
+    /// succeed, as a fixed point number with 18 decimals. If fewer project tokens would be minted, the payment is
+    /// reverted.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to pass along to the emitted event, as well as the data hook and pay hook if applicable.
-    /// @return beneficiaryTokenCount The number of tokens minted to the beneficiary, as a fixed point number with 18
-    /// decimals.
+    /// @return beneficiaryTokenCount The number of **project tokens** minted to `beneficiary`, as a fixed point number
+    /// with 18 decimals.
     function pay(
         uint256 projectId,
         address token,
@@ -728,21 +723,23 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Withdraws funds from a project's surplus (beyond what's needed for payouts) up to the current ruleset's
     /// surplus allowance. Sent directly to a beneficiary address rather than through splits.
     /// @dev Only the project's owner or an operator with `USE_ALLOWANCE` permission can call this.
-    /// @dev Incurs the 2.5% protocol fee unless the caller is a feeless address.
+    /// @dev Incurs the 2.5% protocol fee unless the caller is a feeless address. The fee is charged in the terminal
+    /// token (`token`); the fee project mints **project tokens** in return and sends them to `feeBeneficiary`.
     /// @param projectId The ID of the project to use the surplus allowance of.
-    /// @param token The token to pay out from the surplus.
-    /// @param amount The amount of terminal tokens to use from the project's current surplus allowance, as a fixed
+    /// @param token The terminal token to pay out from the surplus.
+    /// @param amount The amount of terminal `token` to use from the project's current surplus allowance, as a fixed
     /// point number with the same number of decimals as the token's accounting context.
-    /// @param currency The expected currency of the amount to pay out. Must match the currency of one of the
-    /// project's current ruleset's surplus allowances.
-    /// @param minTokensPaidOut The minimum number of terminal tokens that should be returned from the surplus allowance
-    /// (excluding fees), as a fixed point number with 18 decimals. If the amount of surplus used would be less than
-    /// this amount, the transaction is reverted.
-    /// @param beneficiary The address to send the surplus funds to.
-    /// @param feeBeneficiary The address to send the tokens resulting from paying the fee.
+    /// @param currency The expected currency of `amount`. Must match the currency of one of the project's current
+    /// ruleset's surplus allowances.
+    /// @param minTokensPaidOut The minimum number of terminal tokens that must be returned from the surplus allowance
+    /// (excluding fees), as a fixed point number with the same number of decimals as the terminal token's accounting
+    /// context. If less would be paid out, the transaction is reverted.
+    /// @param beneficiary The address to send the reclaimed terminal tokens to.
+    /// @param feeBeneficiary The address that receives the **project tokens** minted by the fee project in exchange
+    /// for the protocol fee paid in terminal tokens.
     /// @param memo A memo to pass along to the emitted event.
-    /// @return netAmountPaidOut The number of tokens that were sent to the beneficiary, as a fixed point number with
-    /// the same number of decimals as the token's accounting context.
+    /// @return netAmountPaidOut The number of **terminal tokens** sent to `beneficiary`, net of the protocol fee, as a
+    /// fixed point number with the same number of decimals as the terminal token's accounting context.
     function useAllowanceOf(
         uint256 projectId,
         address token,

package/src/JBTerminalStore.sol

@@ -427,6 +427,13 @@ contract JBTerminalStore is IJBTerminalStore {
                 })
             });
 
+        // If cross-currency conversion rounded to zero, return without consuming any payout limit. Otherwise a
+        // permissionless caller could repeatedly request sub-unit payouts to drain the cycle's payout limit
+        // without moving any funds.
+        if (amountPaidOut == 0) {
+            return (ruleset, 0);
+        }
+
         // Cache the balance slot to avoid redundant storage reads.
         uint256 currentBalance = balanceOf[msg.sender][projectId][token];
 

package/src/interfaces/IJBCashOutTerminal.sol

@@ -75,16 +75,16 @@ interface IJBCashOutTerminal is IJBTerminal {
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 
-    /// @notice Cashes out a holder's tokens for a project, reclaiming the token's proportional share of the project's
-    /// surplus.
-    /// @param holder The address cashing out tokens.
-    /// @param projectId The ID of the project cashing out tokens.
-    /// @param cashOutCount The number of project tokens to cash out.
-    /// @param tokenToReclaim The token to reclaim from the project's surplus.
-    /// @param minTokensReclaimed The minimum number of terminal tokens expected to be reclaimed.
-    /// @param beneficiary The address to send the reclaimed tokens to.
+    /// @notice Burn a holder's project tokens to reclaim a proportional share of the project's surplus (paid out as a
+    /// terminal token).
+    /// @param holder The address whose project tokens are being burned.
+    /// @param projectId The ID of the project whose project tokens are being burned.
+    /// @param cashOutCount The number of project tokens to burn.
+    /// @param tokenToReclaim The terminal token to reclaim from the project's surplus.
+    /// @param minTokensReclaimed The minimum number of terminal tokens that must be reclaimed.
+    /// @param beneficiary The address to send the reclaimed terminal tokens to.
     /// @param metadata Extra data to send to the data hook and cash out hooks.
-    /// @return reclaimAmount The amount of tokens reclaimed from the project's surplus.
+    /// @return reclaimAmount The number of terminal tokens reclaimed from the project's surplus.
     function cashOutTokensOf(
         address holder,
         uint256 projectId,

package/src/interfaces/IJBController.sol

@@ -261,18 +261,18 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     )
         external;
 
-    /// @notice Burns a holder's project tokens or credits.
-    /// @param holder The address to burn tokens for.
-    /// @param projectId The ID of the project to burn tokens for.
-    /// @param tokenCount The number of tokens to burn.
+    /// @notice Burns a holder's project tokens or unclaimed project token credits, removing them from supply.
+    /// @param holder The address whose project tokens (or credits) are being burned.
+    /// @param projectId The ID of the project whose project tokens are being burned.
+    /// @param tokenCount The number of project tokens (or credits) to burn.
     /// @param memo A memo to pass along to the emitted event.
     function burnTokensOf(address holder, uint256 projectId, uint256 tokenCount, string calldata memo) external;
 
-    /// @notice Redeems credits to claim tokens into a beneficiary's account.
-    /// @param holder The address to redeem credits from.
-    /// @param projectId The ID of the project to claim tokens for.
-    /// @param tokenCount The number of tokens to claim.
-    /// @param beneficiary The account the claimed tokens will go to.
+    /// @notice Converts project token credits into the project's ERC-20 representation, sending them to a beneficiary.
+    /// @param holder The address whose project token credits are being redeemed.
+    /// @param projectId The ID of the project whose project tokens are being claimed.
+    /// @param tokenCount The number of project token credits to convert into ERC-20 project tokens.
+    /// @param beneficiary The account that receives the resulting ERC-20 project tokens.
     function claimTokensFor(address holder, uint256 projectId, uint256 tokenCount, address beneficiary) external;
 
     /// @notice Deploys an ERC-20 token for a project.
@@ -324,13 +324,16 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
         external
         returns (uint256 rulesetId);
 
-    /// @notice Mints new project tokens or credits to a beneficiary, optionally reserving a portion.
-    /// @param projectId The ID of the project to mint tokens for.
-    /// @param tokenCount The number of tokens to mint, including any reserved tokens.
-    /// @param beneficiary The address which will receive the non-reserved tokens.
+    /// @notice Mints new project tokens (or credits) to a beneficiary, optionally reserving a portion for the ruleset's
+    /// reserved splits.
+    /// @param projectId The ID of the project whose project tokens are being minted.
+    /// @param tokenCount The total number of project tokens to mint (the beneficiary's share plus the reserved share if
+    /// `useReservedPercent` is true).
+    /// @param beneficiary The address that receives the non-reserved portion of the minted project tokens.
     /// @param memo A memo to pass along to the emitted event.
     /// @param useReservedPercent Whether to apply the ruleset's reserved percent.
-    /// @return beneficiaryTokenCount The number of tokens minted for the beneficiary.
+    /// @return beneficiaryTokenCount The number of project tokens minted to `beneficiary` (excluding the reserved
+    /// share).
     function mintTokensOf(
         uint256 projectId,
         uint256 tokenCount,

package/src/interfaces/IJBTerminal.sol

@@ -137,10 +137,10 @@ interface IJBTerminal is IERC165 {
     /// @param accountingContexts The accounting contexts to add.
     function addAccountingContextsFor(uint256 projectId, JBAccountingContext[] calldata accountingContexts) external;
 
-    /// @notice Adds funds to a project's balance.
+    /// @notice Adds terminal tokens to a project's balance (no project tokens are minted).
     /// @param projectId The ID of the project to add funds to.
-    /// @param token The token added.
-    /// @param amount The amount of tokens added.
+    /// @param token The terminal token being added.
+    /// @param amount The amount of terminal `token` being added.
     /// @param shouldReturnHeldFees Whether held fees should be returned based on the amount added.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the emitted event.
@@ -162,15 +162,15 @@ interface IJBTerminal is IERC165 {
     /// @return balance The amount of funds that were migrated.
     function migrateBalanceOf(uint256 projectId, address token, IJBTerminal to) external returns (uint256 balance);
 
-    /// @notice Pays a project in a specified token.
+    /// @notice Pay a project with a payment token in exchange for project tokens minted to a beneficiary.
     /// @param projectId The ID of the project to pay.
-    /// @param token The token to pay with.
-    /// @param amount The amount of tokens to pay.
+    /// @param token The payment token to pay with.
+    /// @param amount The amount of the payment `token` to pay.
     /// @param beneficiary The address to mint project tokens to.
-    /// @param minReturnedTokens The minimum number of project tokens expected in return.
+    /// @param minReturnedTokens The minimum number of project tokens the beneficiary must receive.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the pay hooks.
-    /// @return beneficiaryTokenCount The number of tokens minted for the beneficiary.
+    /// @return beneficiaryTokenCount The number of project tokens minted to the beneficiary.
     function pay(
         uint256 projectId,
         address token,

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -1,11 +1,15 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
 
+import {IJBSplitHook} from "../interfaces/IJBSplitHook.sol";
 import {IJBSplits} from "../interfaces/IJBSplits.sol";
 import {IJBTerminalStore} from "../interfaces/IJBTerminalStore.sol";
 import {JBSplit} from "../structs/JBSplit.sol";
+import {JBSplitHookContext} from "../structs/JBSplitHookContext.sol";
 import {JBConstants} from "./JBConstants.sol";
 
 /// @notice Minimal callback surface used only by this library to call back into the terminal's `executePayout(...)`.
@@ -18,7 +22,11 @@ interface IJBPayoutSplitGroupExecutor {
     /// @param token The token being paid out.
     /// @param amount The amount assigned to the split.
     /// @param originalMessageSender The account that started the payout flow.
-    /// @return netPayoutAmount The amount that was actually paid after fees or hook behavior.
+    /// @return netPayoutAmount The amount the split recipient actually received (may be less than the
+    /// post-fee amount if a split hook accepted a partial pull).
+    /// @return feeEligibleAmount The gross-equivalent of `netPayoutAmount` that should accrue held fees.
+    /// Equals `amount` on a fully-consumed non-feeless payout, `0` on feeless or when the hook took nothing,
+    /// and a scaled value `amount * sent / netOffered` for a partial pull.
     function executePayout(
         JBSplit calldata split,
         uint256 projectId,
@@ -27,7 +35,7 @@ interface IJBPayoutSplitGroupExecutor {
         address originalMessageSender
     )
         external
-        returns (uint256 netPayoutAmount);
+        returns (uint256 netPayoutAmount, uint256 feeEligibleAmount);
 }
 
 /// @notice Handles distributing payouts to a project's split recipients. Iterates through each split, sends the
@@ -48,6 +56,92 @@ library JBPayoutSplitGroupLib {
         address caller
     );
 
+    /// @notice Invokes a split hook with partial-pull-aware allowance handling.
+    /// @dev For ERC-20: grants the hook an allowance, calls `processSplitWith`, and revokes any unconsumed
+    /// allowance. For native ETH: pushes via `msg.value`. The hook may take less than offered (revert or
+    /// short-pull); the unsent portion is routed back to the project balance via `store.recordAddedBalanceFor`,
+    /// scaled to include the proportional fee allocation so the held fee is effectively charged only on the
+    /// consumed amount. Fee-eligibility is inferred from `netPayoutAmount < amount`.
+    /// @dev Called via DELEGATECALL from the terminal, so `address(this)` is the terminal and `msg.sender`
+    /// observed by the hook is the terminal — hooks that check `DIRECTORY.isTerminalOf(msg.sender)` continue
+    /// to work unchanged.
+    /// @param split The split (must have a non-zero hook address).
+    /// @param projectId The originating project ID.
+    /// @param token The token being distributed. Use `JBConstants.NATIVE_TOKEN` for ETH.
+    /// @param amount The gross amount allocated to this split (pre-fee).
+    /// @param netPayoutAmount The amount the hook is offered (post-fee for non-feeless splits, == amount otherwise).
+    /// @param store The terminal store used to credit any refund back to the project and to look up decimals.
+    /// @return sent The amount the hook actually received.
+    /// @return feeEligibleAmount The gross-equivalent of `sent` (used for held-fee accounting). Zero for
+    /// feeless splits or when the hook consumed nothing.
+    function invokeSplitHookWithPartial(
+        JBSplit calldata split,
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        uint256 netPayoutAmount,
+        IJBTerminalStore store
+    )
+        external
+        returns (uint256 sent, uint256 feeEligibleAmount)
+    {
+        // Native vs ERC-20 governs the transfer mechanism (push via msg.value vs allowance pull).
+        bool isNative = token == JBConstants.NATIVE_TOKEN;
+
+        // Snapshot the relevant balance before the hook call. The post-call delta tells us how much the hook
+        // actually took, regardless of whether it pulled the full allowance, partially pulled, or reverted.
+        uint256 balanceBefore = isNative ? address(this).balance : IERC20(token).balanceOf(address(this));
+
+        // Build the hook context inline so the terminal call site doesn't have to. `decimals` is looked up from
+        // the terminal store's recorded accounting context for this (projectId, token) pair.
+        JBSplitHookContext memory context = JBSplitHookContext({
+            token: token,
+            amount: netPayoutAmount,
+            decimals: store.accountingContextOf({terminal: address(this), projectId: projectId, token: token}).decimals,
+            projectId: projectId,
+            groupId: uint256(uint160(token)),
+            split: split
+        });
+
+        // Set up the transfer: ETH is pushed via `value:` on the hook call; ERC-20 grants the hook a pull
+        // allowance for the offered net amount.
+        uint256 payValue;
+        if (isNative) {
+            payValue = netPayoutAmount;
+        } else {
+            SafeERC20.forceApprove({token: IERC20(token), spender: address(split.hook), value: netPayoutAmount});
+        }
+
+        // Wrap the hook call in try/catch so a reverting hook does not bubble out. On revert no tokens leave
+        // this contract (transferFrom inside the hook is rolled back; pushed ETH is returned), so `sent` will
+        // resolve to 0 via balance-delta below.
+        try split.hook.processSplitWith{value: payValue}(context) {} catch {}
+
+        // Revoke any unconsumed ERC-20 allowance immediately after the call so the hook can never pull later.
+        // ETH path has no allowance to revoke.
+        if (!isNative) SafeERC20.forceApprove({token: IERC20(token), spender: address(split.hook), value: 0});
+
+        // The hook's actual consumption is the drop in this contract's balance for the token.
+        sent = balanceBefore - (isNative ? address(this).balance : IERC20(token).balanceOf(address(this)));
+
+        // If the hook took less than offered, refund the proportional gross portion to the project's balance.
+        // 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);
+            if (refund != 0) {
+                store.recordAddedBalanceFor({projectId: projectId, token: token, amount: refund});
+            }
+        }
+
+        // `netPayoutAmount < amount` iff the terminal deducted a fee above (non-feeless split). Report the
+        // 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);
+        }
+    }
+
     /// @notice Sends payouts to the payout splits group specified in a project's ruleset.
     /// @param splits The splits contract to read splits from.
     /// @param store The terminal store used to restore balance when a payout fails.
@@ -87,14 +181,25 @@ library JBPayoutSplitGroupLib {
             // The amount to send to the split.
             uint256 payoutAmount = mulDiv(leftoverAmount, split.percent, leftoverPercentage);
 
-            // The final payout amount after taking out any fees.
-            uint256 netPayoutAmount = _sendPayoutToSplit({
-                store: store, split: split, projectId: projectId, token: token, amount: payoutAmount, caller: caller
-            });
-
-            // If the split hook is a feeless address, this payout doesn't incur a fee.
-            if (netPayoutAmount != 0 && netPayoutAmount != payoutAmount) {
-                amountEligibleForFees += payoutAmount;
+            // 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
+            // hook splits, `feeEligible` equals `payoutAmount` (non-feeless) or 0 (feeless). For a partial split-hook
+            // pull, `feeEligible` scales with consumed. Failed payouts consume the payout limit by design — the
+            // try/catch keeps a single bad split from DoS-ing the rest and restores balance.
+            uint256 netPayoutAmount;
+            try IJBPayoutSplitGroupExecutor(address(this))
+                .executePayout({
+                split: split, projectId: projectId, token: token, amount: payoutAmount, originalMessageSender: caller
+            }) returns (
+                uint256 sentAmount, uint256 feeEligible
+            ) {
+                netPayoutAmount = sentAmount;
+                amountEligibleForFees += feeEligible;
+            } catch (bytes memory failureReason) {
+                emit PayoutReverted({
+                    projectId: projectId, split: split, amount: payoutAmount, reason: failureReason, caller: caller
+                });
+                store.recordAddedBalanceFor({projectId: projectId, token: token, amount: payoutAmount});
             }
 
             if (payoutAmount != 0) {
@@ -123,47 +228,4 @@ library JBPayoutSplitGroupLib {
             }
         }
     }
-
-    /// @notice Sends a payout to a split.
-    /// @param store The terminal store used to restore balance when a payout fails.
-    /// @param split The split to pay.
-    /// @param projectId The ID of the project the split was specified by.
-    /// @param token The address of the token to pay out.
-    /// @param amount The total amount that the split is paid.
-    /// @param caller The original caller of the terminal payout flow.
-    /// @return netPayoutAmount The amount sent to the split after subtracting fees.
-    function _sendPayoutToSplit(
-        IJBTerminalStore store,
-        JBSplit memory split,
-        uint256 projectId,
-        address token,
-        uint256 amount,
-        address caller
-    )
-        private
-        returns (uint256 netPayoutAmount)
-    {
-        // Failed split payouts consume the payout limit by design. The try-catch prevents a single
-        // split from DoS-ing the entire payout. Failed splits' amounts are returned to the project balance via
-        // `recordAddedBalanceFor`. Payout limit consumption is correct because the project authorized the
-        // distribution.
-        try IJBPayoutSplitGroupExecutor(address(this))
-            .executePayout({
-            split: split, projectId: projectId, token: token, amount: amount, originalMessageSender: caller
-        }) returns (
-            uint256 payoutAmount
-        ) {
-            return payoutAmount;
-        } catch (bytes memory failureReason) {
-            emit PayoutReverted({
-                projectId: projectId, split: split, amount: amount, reason: failureReason, caller: caller
-            });
-
-            // Add balance back to the project.
-            store.recordAddedBalanceFor({projectId: projectId, token: token, amount: amount});
-
-            // Since the payout failed the netPayoutAmount is zero.
-            return 0;
-        }
-    }
 }

package/test/helpers/JBTest.sol

@@ -11,6 +11,27 @@ import {Test} from "lib/forge-std/src/Test.sol";
 contract JBTest is Test {
     using JBRulesetMetadataResolver for JBRulesetMetadata;
 
+    /// @notice The pinned CREATE2 address of `JBPayoutSplitGroupLib` from `foundry.toml`.
+    /// @dev Must match the `libraries = [...]` entry. Tests etch the runtime code here so
+    /// `JBMultiTerminal`'s delegatecalls into the library resolve.
+    address internal constant _JB_PAYOUT_SPLIT_GROUP_LIB = 0xE5767922e5f8d18c57C4685289Ef92D859eb980b;
+
+    /// @notice Deploy `JBPayoutSplitGroupLib` locally and etch its runtime bytecode at the pinned
+    /// address from `foundry.toml`. Forge auto-deploys linked libraries only when no `libraries`
+    /// entry is configured; once the address is pinned (needed so deploy-all-v6 can read
+    /// `artifacts/JBMultiTerminal.json::bytecode.object` as valid hex), unit tests must plant the
+    /// runtime code themselves or any path through `executePayout` / `sendPayoutsToSplitGroupOf`
+    /// reverts with `delegatecall to non-contract address`.
+    function _etchPayoutSplitGroupLib() internal {
+        bytes memory creationCode = vm.getCode("JBPayoutSplitGroupLib");
+        address libImpl;
+        assembly {
+            libImpl := create(0, add(creationCode, 0x20), mload(creationCode))
+        }
+        require(libImpl != address(0), "JBPayoutSplitGroupLib deploy failed");
+        vm.etch(_JB_PAYOUT_SPLIT_GROUP_LIB, libImpl.code);
+    }
+
     function mockExpect(address _where, bytes memory _encodedCall, bytes memory _returns) public {
         vm.mockCall(_where, _encodedCall, _returns);
         vm.expectCall(_where, _encodedCall);

package/test/helpers/TestBaseWorkflow.sol

@@ -290,6 +290,9 @@ contract TestBaseWorkflow is JBTest, DeployPermit2 {
 
     // Deploys and initializes contracts for testing.
     function setUp() public virtual {
+        // Plant `JBPayoutSplitGroupLib` at its pre-linked address so terminal delegatecalls resolve.
+        _etchPayoutSplitGroupLib();
+
         _jbPermissions = new JBPermissions(_trustedForwarder);
         _jbProjects = new JBProjects(_multisig, address(0), _trustedForwarder);
         _jbDirectory = new JBDirectory(_jbPermissions, _jbProjects, _multisig);