@bananapus/core-v6 0.0.29 → 0.0.31

package/src/JBController.sol

@@ -158,6 +158,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         RULESETS = rulesets;
         SPLITS = splits;
         TOKENS = tokens;
+        // slither-disable-next-line missing-zero-check
         OMNICHAIN_RULESET_OPERATOR = omnichainRulesetOperator;
     }
 
@@ -820,8 +821,8 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         override
         returns (uint256 beneficiaryTokenCount, uint256 reservedTokenCount)
     {
-        // Revert if there are no tokens to split.
-        if (tokenCount == 0) revert JBController_ZeroTokensToMint();
+        // A zero preview amount means there are no tokens to split.
+        if (tokenCount == 0) return (0, 0);
 
         // Keep a reference to the current ruleset.
         JBRuleset memory ruleset = _currentRulesetOf(projectId);
@@ -900,6 +901,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             JBTerminalConfig memory terminalConfig = terminalConfigurations[i];
 
             // Add the accounting contexts for the specified tokens.
+            // slither-disable-next-line calls-loop
             terminalConfig.terminal
                 .addAccountingContextsFor({
                     projectId: projectId, accountingContexts: terminalConfig.accountingContextsToAccept
@@ -945,6 +947,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             }
 
             // Queue its ruleset.
+            // slither-disable-next-line calls-loop
             JBRuleset memory ruleset = RULESETS.queueFor({
                 projectId: projectId,
                 duration: rulesetConfig.duration,
@@ -956,11 +959,13 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             });
 
             // Set its split groups.
+            // slither-disable-next-line calls-loop
             SPLITS.setSplitGroupsOf({
                 projectId: projectId, rulesetId: ruleset.id, splitGroups: rulesetConfig.splitGroups
             });
 
             // Set its fund access limits.
+            // slither-disable-next-line calls-loop
             FUND_ACCESS_LIMITS.setFundAccessLimitsFor({
                 projectId: projectId, rulesetId: ruleset.id, fundAccessLimitGroups: rulesetConfig.fundAccessLimitGroups
             });
@@ -1023,7 +1028,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                         projectId: projectId, tokenCount: splitTokenCount, recipient: address(split.hook), token: token
                     });
 
-                    // slither-disable-next-line reentrancy-events
+                    // slither-disable-next-line calls-loop,reentrancy-events
                     try split.hook
                         .processSplitWith(
                             JBSplitHookContext({
@@ -1047,6 +1052,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
                     if (split.projectId != 0) {
                         // Get a reference to the receiving project's primary payment terminal for the token.
+                        // slither-disable-next-line calls-loop
                         IJBTerminal terminal = token == IJBToken(address(0))
                             ? IJBTerminal(address(0))
                             : DIRECTORY.primaryTerminalOf({projectId: split.projectId, token: address(token)});
@@ -1065,6 +1071,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                             bytes memory metadata = bytes(abi.encodePacked(projectId));
 
                             // Try to fulfill the payment.
+                            // slither-disable-next-line calls-loop
                             try this.executePayReservedTokenToTerminal({
                                 projectId: split.projectId,
                                 terminal: terminal,
@@ -1088,6 +1095,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                         }
                     } else if (beneficiary == address(0xdead)) {
                         // If the split has no project ID, and the beneficiary is 0xdead, burn.
+                        // slither-disable-next-line calls-loop
                         TOKENS.burnFrom({holder: address(this), projectId: projectId, count: splitTokenCount});
                     } else {
                         // If the split has no project Id, send to beneficiary.

package/src/JBDirectory.sol

@@ -139,6 +139,7 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
         // slither-disable-next-line reentrancy-no-eth
         controllerOf[projectId] = controller;
 
+        // slither-disable-next-line reentrancy-events
         emit SetController({projectId: projectId, controller: controller, caller: msg.sender});
 
         // Notify the new controller that migration is complete and it is now the active controller.

package/src/JBMultiTerminal.sol

@@ -66,10 +66,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     error JBMultiTerminal_RecipientProjectTerminalNotFound(uint256 projectId, address token);
     error JBMultiTerminal_SplitHookInvalid(IJBSplitHook hook);
     error JBMultiTerminal_TerminalTokensIncompatible(uint256 projectId, address token, IJBTerminal terminal);
+    error JBMultiTerminal_TemporaryAllowanceNotConsumed(address token, address spender, uint256 allowance);
     error JBMultiTerminal_TokenNotAccepted(address token);
-    error JBMultiTerminal_UnderMinReturnedTokens(uint256 count, uint256 min);
-    error JBMultiTerminal_UnderMinTokensPaidOut(uint256 amount, uint256 min);
-    error JBMultiTerminal_UnderMinTokensReclaimed(uint256 amount, uint256 min);
+    error JBMultiTerminal_UnderMin(uint256 value, uint256 min);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -209,6 +208,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         // Emit an event for each accounting context.
         for (uint256 i; i < accountingContexts.length; i++) {
+            // slither-disable-next-line reentrancy-events
             emit SetAccountingContext({projectId: projectId, context: accountingContexts[i], caller: _msgSender()});
         }
     }
@@ -251,7 +251,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// those tokens.
     /// @param holder The account whose tokens are being cashed out.
     /// @param projectId The ID of the project the project tokens belong to.
-    /// @param cashOutCount The number of project tokens to cash out, as a fixed point number with 18 decimals.
+    /// @param cashOutCount The number of project tokens to cash out and burn, as a fixed point number with 18
+    /// decimals.
     /// @param tokenToReclaim The token being reclaimed.
     /// @param minTokensReclaimed The minimum number of terminal tokens expected in return, as a fixed point number with
     /// the same number of decimals as this terminal. If the amount of tokens minted for the beneficiary would be less
@@ -289,9 +290,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
 
         // The amount being reclaimed must be at least as much as was expected.
-        if (reclaimAmount < minTokensReclaimed) {
-            revert JBMultiTerminal_UnderMinTokensReclaimed(reclaimAmount, minTokensReclaimed);
-        }
+        _checkMin({value: reclaimAmount, min: minTokensReclaimed});
     }
 
     /// @notice Executes a payout to a split.
@@ -349,6 +348,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // 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.
@@ -542,20 +544,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Transfer the balance minus the fee to the new terminal.
             uint256 migrationAmount = balance - feeAmount;
 
-            // Trigger any inherited pre-transfer logic.
-            // If this terminal's token is the native token, send it in `msg.value`.
-            // slither-disable-next-line reentrancy-events
-            uint256 payValue = _beforeTransferTo({to: address(to), token: token, amount: migrationAmount});
-
-            // Withdraw the balance to transfer to the new terminal.
-            // slither-disable-next-line reentrancy-events
-            to.addToBalanceOf{value: payValue}({
-                projectId: projectId,
-                token: token,
-                amount: migrationAmount,
-                shouldReturnHeldFees: false,
-                memo: "",
-                metadata: bytes("")
+            _externalAddToBalance({
+                terminal: to, projectId: projectId, token: token, amount: migrationAmount, metadata: bytes("")
             });
         }
     }
@@ -612,9 +602,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
 
         // The token count for the beneficiary must be greater than or equal to the specified minimum.
-        if (beneficiaryTokenCount < minReturnedTokens) {
-            revert JBMultiTerminal_UnderMinReturnedTokens(beneficiaryTokenCount, minReturnedTokens);
-        }
+        _checkMin({value: beneficiaryTokenCount, min: minReturnedTokens});
     }
 
     /// @notice Process any fees that are being held for the project.
@@ -654,10 +642,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // if the current fee isn't yet unlocked.
             if (heldFee.unlockTimestamp > block.timestamp) break;
 
-            // Delete the entry to reclaim gas before the external call.
+            // Delete the entry and advance the index *before* the external call. This is intentional:
+            // 1. It prevents reentrancy from reprocessing the same fee.
+            // 2. If `_processFee` fails (try-catch), the fee amount is returned to the project's balance via
+            //    `_recordAddedBalanceFor` — the fee is forgiven rather than retried. This is a deliberate design
+            // choice: projects should not have funds permanently stuck because the fee route is misconfigured or
+            // reverting.
+            //    A `FeeReverted` event is emitted so the forgiveness is observable off-chain.
             delete _heldFeesOf[projectId][token][currentIndex];
-
-            // Update the index before the external call to prevent reentrancy from reprocessing the same fee.
             _nextHeldFeeIndexOf[projectId][token] = currentIndex + 1;
 
             // Process the fee.
@@ -715,9 +707,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         amountPaidOut = _sendPayoutsOf({projectId: projectId, token: token, amount: amount, currency: currency});
 
         // The amount being paid out must be at least as much as was expected.
-        if (amountPaidOut < minTokensPaidOut) {
-            revert JBMultiTerminal_UnderMinTokensPaidOut(amountPaidOut, minTokensPaidOut);
-        }
+        _checkMin({value: amountPaidOut, min: minTokensPaidOut});
     }
 
     /// @notice Allows a project to pay out funds from its surplus up to the current surplus allowance.
@@ -770,9 +760,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
 
         // The amount being withdrawn must be at least as much as was expected.
-        if (netAmountPaidOut < minTokensPaidOut) {
-            revert JBMultiTerminal_UnderMinTokensPaidOut(netAmountPaidOut, minTokensPaidOut);
-        }
+        _checkMin({value: netAmountPaidOut, min: minTokensPaidOut});
     }
 
     //*********************************************************************//
@@ -1022,6 +1010,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Set the allowance to `spend` tokens for the user.
             try PERMIT2.permit({owner: _msgSender(), permitSingle: permitSingle, signature: allowance.signature}) {}
             catch (bytes memory reason) {
+                // slither-disable-next-line reentrancy-events
                 emit Permit2AllowanceFailed(token, _msgSender(), reason);
             }
         }
@@ -1087,6 +1076,29 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         return 0;
     }
 
+    /// @notice Cap fee-free surplus at the project's remaining balance after an outflow.
+    /// @dev Non-fee-free funds are considered to leave first. Fee-free surplus only decreases when the remaining
+    /// balance can no longer support it. This prevents attackers from using outflows to drain the fee-free counter
+    /// and then cashing out without incurring fees.
+    /// @param projectId The ID of the project.
+    /// @param token The token whose fee-free surplus to cap.
+    function _capFeeFreeSurplus(uint256 projectId, address token) internal {
+        // Get the current fee-free surplus for this project/token pair.
+        uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][token];
+
+        // Nothing to cap if there's no fee-free surplus tracked.
+        if (feeFreeSurplus == 0) return;
+
+        // Get the project's remaining balance (already decremented by the store's record call).
+        uint256 remainingBalance = STORE.balanceOf({terminal: address(this), projectId: projectId, token: token});
+
+        // Cap fee-free surplus at the remaining balance.
+        if (feeFreeSurplus > remainingBalance) {
+            // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
+            _feeFreeSurplusOf[projectId][token] = remainingBalance;
+        }
+    }
+
     /// @notice Holders can cash out their tokens to reclaim some of a project's surplus, or to trigger rules determined
     /// by
     /// the project's current ruleset's data hook.
@@ -1154,6 +1166,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][tokenToReclaim];
                     if (feeFreeSurplus != 0) {
                         uint256 feeableAmount = reclaimAmount < feeFreeSurplus ? reclaimAmount : feeFreeSurplus;
+                        // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
                         _feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
                         amountEligibleForFees += feeableAmount;
                         reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: feeableAmount, feePercent: FEE});
@@ -1220,6 +1233,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
+    /// @notice Revert if a value is less than the specified minimum.
+    /// @param value The value to compare against the minimum.
+    /// @param min The minimum acceptable value.
+    function _checkMin(uint256 value, uint256 min) internal pure {
+        if (value < min) revert JBMultiTerminal_UnderMin(value, min);
+    }
+
     /// @notice Fund a project either by calling this terminal's internal `addToBalance` function or by calling the
     /// recipient terminal's `addToBalance` function.
     /// @param terminal The terminal on which the project is expecting to receive funds.
@@ -1237,7 +1257,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     )
         internal
     {
-        // Call the internal method if this terminal is being used.
+        // Use the local internal path when staying on this terminal. Otherwise use the efficient external equivalent,
+        // which forwards value directly after granting a temporary pull allowance.
         if (terminal == IJBTerminal(address(this))) {
             _addToBalanceOf({
                 projectId: projectId,
@@ -1248,20 +1269,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 metadata: metadata
             });
         } else {
-            // Trigger any inherited pre-transfer logic.
-            // Keep a reference to the amount that'll be paid as a `msg.value`.
-            // slither-disable-next-line reentrancy-events
-            uint256 payValue = _beforeTransferTo({to: address(terminal), token: token, amount: amount});
-
-            // Add to balance.
-            // If this terminal's token is the native token, send it in `msg.value`.
-            terminal.addToBalanceOf{value: payValue}({
-                projectId: projectId,
-                token: token,
-                amount: amount,
-                shouldReturnHeldFees: false,
-                memo: "",
-                metadata: metadata
+            _externalAddToBalance({
+                terminal: terminal, projectId: projectId, token: token, amount: amount, metadata: metadata
             });
         }
     }
@@ -1313,9 +1322,47 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 memo: "",
                 metadata: metadata
             });
+
+            // Revoke the temporary pull allowance now that the recipient terminal call has finished.
+            _afterTransferTo({to: address(terminal), token: token});
         }
     }
 
+    /// @notice Fund a project on another terminal by granting a temporary pull allowance for this call only.
+    /// @param terminal The recipient terminal.
+    /// @param projectId The ID of the project being funded.
+    /// @param token The token being used.
+    /// @param amount The amount being funded.
+    /// @param metadata Additional metadata to include with the payment.
+    function _externalAddToBalance(
+        IJBTerminal terminal,
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        bytes memory metadata
+    )
+        internal
+    {
+        // Trigger any inherited pre-transfer logic.
+        // Keep a reference to the amount that'll be paid as a `msg.value`.
+        // slither-disable-next-line reentrancy-events
+        uint256 payValue = _beforeTransferTo({to: address(terminal), token: token, amount: amount});
+
+        // Add to balance on the recipient terminal.
+        // If this terminal's token is the native token, send it in `msg.value`.
+        terminal.addToBalanceOf{value: payValue}({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            shouldReturnHeldFees: false,
+            memo: "",
+            metadata: metadata
+        });
+
+        // Revoke the temporary pull allowance now that the recipient terminal call has finished.
+        _afterTransferTo({to: address(terminal), token: token});
+    }
+
     /// @notice Fulfills a list of cash out hook specifications.
     /// @param projectId The ID of the project being cashed out from.
     /// @param beneficiaryReclaimAmount The number of tokens that are being cashed out from the project.
@@ -1356,6 +1403,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             cashOutMetadata: metadata
         });
 
+        // slither-disable-next-line calls-loop
         for (uint256 i; i < specifications.length; i++) {
             // Set the specification being iterated on.
             JBCashOutHookSpecification memory specification = specifications[i];
@@ -1393,9 +1441,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
 
             // Fulfill the specification.
-            // slither-disable-next-line reentrancy-events
+            // slither-disable-next-line reentrancy-events,calls-loop
             specification.hook.afterCashOutRecordedWith{value: payValue}(context);
 
+            // Revoke the temporary pull allowance now that the hook call has finished.
+            _afterTransferTo({to: address(specification.hook), token: beneficiaryReclaimAmount.token});
+
             emit HookAfterRecordCashOut({
                 hook: specification.hook,
                 context: context,
@@ -1442,6 +1493,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
 
         // Fulfill each specification through their pay hooks.
+        // slither-disable-next-line calls-loop
         for (uint256 i; i < specifications.length; i++) {
             // Set the specification being iterated on.
             JBPayHookSpecification memory specification = specifications[i];
@@ -1468,9 +1520,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
 
             // Fulfill the specification.
-            // slither-disable-next-line reentrancy-events
+            // slither-disable-next-line reentrancy-events,calls-loop
             specification.hook.afterPayRecordedWith{value: payValue}(context);
 
+            // Revoke the temporary pull allowance now that the hook call has finished.
+            _afterTransferTo({to: address(specification.hook), token: tokenAmount.token});
+
             emit HookAfterRecordPay({
                 hook: specification.hook,
                 context: context,
@@ -1590,6 +1645,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 caller: _msgSender()
             });
         } catch (bytes memory reason) {
+            // Fee processing failed — intentionally forgive the fee and return the amount to the project.
+            // The held-fee entry (if any) was already deleted by `processHeldFeesOf` before this call, so there is no
+            // retry path. This is by design: a broken or misconfigured fee route should not permanently lock project
+            // funds. The `FeeReverted` event makes this observable off-chain.
             emit FeeReverted({
                 projectId: projectId,
                 token: token,
@@ -1715,6 +1774,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             STORE.recordPayoutFor({projectId: projectId, token: token, amount: amount, currency: currency});
 
         // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
+        // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
         _capFeeFreeSurplus({projectId: projectId, token: token});
 
         // Get a reference to the project's owner.
@@ -1758,6 +1818,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     leftoverPayoutAmount -= fee;
                 }
             } catch (bytes memory reason) {
+                // slither-disable-next-line reentrancy-events
                 emit PayoutTransferReverted({
                     projectId: projectId,
                     addr: projectOwner,
@@ -1916,6 +1977,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             STORE.recordUsedAllowanceOf({projectId: projectId, token: token, amount: amount, currency: currency});
 
         // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
+        // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
         _capFeeFreeSurplus({projectId: projectId, token: token});
 
         // Take a fee from the `amountPaidOut`, if needed.
@@ -1952,32 +2014,24 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Cap fee-free surplus at the project's remaining balance after an outflow.
-    /// @dev Non-fee-free funds are considered to leave first. Fee-free surplus only decreases when the remaining
-    /// balance can no longer support it. This prevents attackers from using outflows to drain the fee-free counter
-    /// and then cashing out without incurring fees.
-    /// @param projectId The ID of the project.
-    /// @param token The token whose fee-free surplus to cap.
-    function _capFeeFreeSurplus(uint256 projectId, address token) internal {
-        // Get the current fee-free surplus for this project/token pair.
-        uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][token];
-
-        // Nothing to cap if there's no fee-free surplus tracked.
-        if (feeFreeSurplus == 0) return;
-
-        // Get the project's remaining balance (already decremented by the store's record call).
-        uint256 remainingBalance = STORE.balanceOf({terminal: address(this), projectId: projectId, token: token});
-
-        // Cap fee-free surplus at the remaining balance.
-        if (feeFreeSurplus > remainingBalance) {
-            _feeFreeSurplusOf[projectId][token] = remainingBalance;
-        }
-    }
-
     //*********************************************************************//
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//
 
+    /// @notice Logic to be triggered after transferring tokens from this terminal.
+    /// @dev Clears any allowance granted by `_beforeTransferTo` so receivers cannot retain pull access after the call.
+    /// @param to The address whose temporary pull allowance should be cleared.
+    /// @param token The token whose temporary allowance should be cleared.
+    function _afterTransferTo(address to, address token) internal view {
+        // Native-token transfers use `msg.value`, so there is no ERC-20 approval to clear.
+        if (token == JBConstants.NATIVE_TOKEN) return;
+
+        // Revert if the callee returned without consuming the full forwarded ERC-20 amount.
+        // slither-disable-next-line calls-loop
+        uint256 allowance = IERC20(token).allowance({owner: address(this), spender: to});
+        if (allowance != 0) revert JBMultiTerminal_TemporaryAllowanceNotConsumed(token, to, allowance);
+    }
+
     /// @notice Returns a project's accounting context for a token, reverting if it is not accepted.
     /// @param projectId The ID of the project to get the accounting context for.
     /// @param token The token to get the accounting context for.

package/src/JBRulesets.sol

@@ -355,7 +355,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @dev If a current ruleset of the project is not found, returns an empty ruleset with all properties set to 0.
     /// @dev The first cycle returns the stored ruleset directly (cycleNumber=1, original weight). Subsequent cycles
     /// simulate cycling with weight decay via `_simulateCycledRulesetBasedOn`. Payout limits reset each cycle because
-    /// the terminal store keys usage by rulesetId, and each cycle produces a new simulated rulesetId.
+    /// they are keyed by `cycleNumber`, but the simulated cycle keeps the same `rulesetId` / config id as the stored
+    /// ruleset it is based on.
     /// @param projectId The ID of the project to get the current ruleset of.
     /// @return ruleset The project's current ruleset.
     function currentOf(uint256 projectId) external view override returns (JBRuleset memory ruleset) {

package/src/JBTerminalStore.sol

@@ -228,12 +228,12 @@ contract JBTerminalStore is IJBTerminalStore {
 
     /// @notice Records a cash out from a project.
     /// @dev Cashs out the project's tokens according to values provided by the ruleset's data hook. If the ruleset has
-    /// no
-    /// data hook, cashs out tokens along a cash out bonding curve that is a function of the number of tokens being
+    /// no data hook, cashs out tokens along a cash out bonding curve that is a function of the number of tokens being
     /// burned.
     /// @param holder The account that is cashing out tokens.
     /// @param projectId The ID of the project being cashing out from.
-    /// @param cashOutCount The number of project tokens to cash out, as a fixed point number with 18 decimals.
+    /// @param cashOutCount The number of project tokens to cash out, as supplied by the caller and later burned by the
+    /// terminal, as a fixed point number with 18 decimals.
     /// @param tokenToReclaim The token being reclaimed by the cash out.
     /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Passed through to data
     /// hooks so they can skip their own fees when value stays in the protocol (e.g. project-to-project routing).
@@ -895,18 +895,23 @@ contract JBTerminalStore is IJBTerminalStore {
         JBAccountingContext memory accountingContext = _accountingContextForTokenOf[terminal][projectId][tokenToReclaim];
 
         // Get the total number of outstanding project tokens.
-        uint256 totalSupply =
+        uint256 effectiveTotalSupply =
             IJBController(address(DIRECTORY.controllerOf(projectId))).totalTokenSupplyWithReservedTokensOf(projectId);
 
         // Can't cash out more tokens than are in the supply.
-        if (cashOutCount > totalSupply) revert JBTerminalStore_InsufficientTokens(cashOutCount, totalSupply);
+        if (cashOutCount > effectiveTotalSupply) {
+            revert JBTerminalStore_InsufficientTokens(cashOutCount, effectiveTotalSupply);
+        }
 
-        // SECURITY NOTE: The data hook has absolute control over cash-out economics.
-        // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
+        // SECURITY NOTE: The data hook has absolute control over cash-out pricing.
+        // It can set effectiveTotalSupply, effectiveCashOutCount, and cashOutTaxRate to arbitrary values,
         // completely overriding the terminal's bonding curve math. For example, setting
-        // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
+        // effectiveTotalSupply = surplus makes reclaimAmount = effectiveCashOutCount, bypassing the curve.
+        // The terminal still burns the caller-supplied cashOutCount after pricing completes.
         // Project owners MUST audit their data hooks with the same rigor as the terminal.
 
+        uint256 effectiveCashOutCount = cashOutCount;
+
         // If the ruleset has a data hook which is enabled for cash outs, use it to derive a claim amount and memo.
         if (ruleset.useDataHookForCashOut() && ruleset.dataHook() != address(0)) {
             // Build the cash out context field-by-field — the struct has 11 fields, too many for a literal.
@@ -916,7 +921,7 @@ contract JBTerminalStore is IJBTerminalStore {
             context.projectId = projectId;
             context.rulesetId = ruleset.id;
             context.cashOutCount = cashOutCount;
-            context.totalSupply = totalSupply;
+            context.totalSupply = effectiveTotalSupply;
             context.surplus = JBTokenAmount({
                 token: accountingContext.token,
                 value: surplus,
@@ -928,7 +933,7 @@ contract JBTerminalStore is IJBTerminalStore {
             context.beneficiaryIsFeeless = beneficiaryIsFeeless;
             context.metadata = metadata;
 
-            (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
+            (cashOutTaxRate, effectiveCashOutCount, effectiveTotalSupply, hookSpecifications) =
                 IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
 
             // Noop specifications are informational only, so they can't also request forwarded funds.
@@ -944,7 +949,10 @@ contract JBTerminalStore is IJBTerminalStore {
         // Apply the bonding curve to calculate how much of the surplus is reclaimable.
         if (surplus != 0) {
             reclaimAmount = JBCashOuts.cashOutFrom({
-                surplus: surplus, cashOutCount: cashOutCount, totalSupply: totalSupply, cashOutTaxRate: cashOutTaxRate
+                surplus: surplus,
+                cashOutCount: effectiveCashOutCount,
+                totalSupply: effectiveTotalSupply,
+                cashOutTaxRate: cashOutTaxRate
             });
         }
     }
@@ -1193,6 +1201,7 @@ contract JBTerminalStore is IJBTerminalStore {
             });
 
         // Add up all the balances.
+        // slither-disable-next-line calls-loop
         surplus = (surplus == 0 || accountingContext.currency == targetCurrency)
             ? surplus
             : mulDiv({
@@ -1208,6 +1217,7 @@ contract JBTerminalStore is IJBTerminalStore {
             });
 
         // Get a reference to the payout limit during the ruleset for the token.
+        // slither-disable-next-line calls-loop
         JBCurrencyAmount[] memory payoutLimits = IJBController(address(DIRECTORY.controllerOf(projectId)))
             .FUND_ACCESS_LIMITS()
             .payoutLimitsOf({
@@ -1247,6 +1257,7 @@ contract JBTerminalStore is IJBTerminalStore {
 
             // Convert the `payoutLimit`'s amount to be in terms of the provided currency.
             if (payoutLimit.amount != 0 && payoutLimit.currency != targetCurrency) {
+                // slither-disable-next-line calls-loop
                 uint256 converted = mulDiv({
                     x: payoutLimit.amount,
                     y: 10 ** _MAX_FIXED_POINT_FIDELITY, // Use `_MAX_FIXED_POINT_FIDELITY` to keep as much of the

package/src/abstract/JBControlled.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
+pragma solidity 0.8.28;
 
 import {IJBControlled} from "./../interfaces/IJBControlled.sol";
 import {IJBDirectory} from "./../interfaces/IJBDirectory.sol";
@@ -39,9 +39,15 @@ abstract contract JBControlled is IJBControlled {
         DIRECTORY = directory;
     }
 
+    //*********************************************************************//
+    // -------------------------- internal views ------------------------- //
+    //*********************************************************************//
+
     /// @notice Only allows the controller of the specified project to proceed.
     function _onlyControllerOf(uint256 projectId) internal view {
+        // slither-disable-next-line calls-loop
         if (address(DIRECTORY.controllerOf(projectId)) != msg.sender) {
+            // slither-disable-next-line calls-loop
             revert JBControlled_ControllerUnauthorized(address(DIRECTORY.controllerOf(projectId)));
         }
     }

package/src/abstract/JBPermissioned.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
+pragma solidity 0.8.28;
 
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 

package/src/interfaces/IJBRulesetDataHook.sol

@@ -17,8 +17,9 @@ interface IJBRulesetDataHook is IERC165 {
     /// @notice Calculates data before a cash out is recorded in the terminal store.
     /// @param context The context passed to this data hook by the `cashOutTokensOf(...)` function.
     /// @return cashOutTaxRate The rate determining the reclaimable amount for a given surplus and token supply.
-    /// @return cashOutCount The number of tokens to consider cashed out.
-    /// @return totalSupply The total number of tokens to consider existing.
+    /// @return effectiveCashOutCount The effective token count to use for pricing the cash out. The terminal still
+    /// burns the caller-supplied token count.
+    /// @return effectiveTotalSupply The effective total supply to use for pricing the cash out.
     /// @return hookSpecifications The amount and data to send to cash out hooks instead of returning to the
     /// beneficiary.
     function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
@@ -26,8 +27,8 @@ interface IJBRulesetDataHook is IERC165 {
         view
         returns (
             uint256 cashOutTaxRate,
-            uint256 cashOutCount,
-            uint256 totalSupply,
+            uint256 effectiveCashOutCount,
+            uint256 effectiveTotalSupply,
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 

package/src/libraries/JBCashOuts.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.17;
+pragma solidity 0.8.28;
 
 import {mulDiv} from "@prb/math/src/Common.sol";