@bananapus/core-v6 0.0.43 → 0.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/permission-ids-v6": "^0.0.23",
     "@chainlink/contracts": "1.5.0",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",

package/references/entrypoints.md

@@ -155,6 +155,8 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 
 | Function | What it does |
 |----------|--------------|
-| `setFeelessAddress(address addr, bool flag)` | Adds or removes an address from the fee exemption list. Owner-only. (`JBFeelessAddresses`) |
+| `setFeelessAddress(address addr, bool flag)` | Adds or removes an address from the global (all-project) fee exemption list. Owner-only. (`JBFeelessAddresses`) |
+| `setFeelessAddressFor(uint256 projectId, address addr, bool flag)` | Adds or removes an address from a project's fee exemption list. `projectId = 0` = global wildcard. Owner-only. (`JBFeelessAddresses`) |
+| `isFeelessFor(address addr, uint256 projectId)` | Returns whether an address is feeless for a project (checks both wildcard and project-specific). (`JBFeelessAddresses`) |
 | `setControllerAllowed(uint256 projectId)` | Returns whether a project's controller can currently be set. (`IJBDirectoryAccessControl`) |
 | `setTerminalsAllowed(uint256 projectId)` | Returns whether a project's terminals can currently be set. (`IJBDirectoryAccessControl`) |

package/references/types-errors-events.md

@@ -8,7 +8,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 |-------------|------------|---------|
 | `JBRuleset` | `cycleNumber (uint48)`, `id (uint48)`, `basedOnId (uint48)`, `start (uint48)`, `duration (uint32)`, `weight (uint112)`, `weightCutPercent (uint32)`, `approvalHook`, `metadata (uint256)` | `currentOf()`, `recordPaymentFrom()`, `recordCashOutFor()` return values |
 | `JBRulesetConfig` | `mustStartAtOrAfter (uint48)`, `duration (uint32)`, `weight (uint112)`, `weightCutPercent (uint32)`, `approvalHook`, `metadata (JBRulesetMetadata)`, `splitGroups[]`, `fundAccessLimitGroups[]` | `launchProjectFor()`, `queueRulesetsOf()` input |
-| `JBRulesetMetadata` | `reservedPercent (uint16)`, `cashOutTaxRate (uint16)`, `baseCurrency (uint32)`, `pausePay`, `pauseCreditTransfers`, `allowOwnerMinting`, `allowSetCustomToken`, `allowTerminalMigration`, `allowSetTerminals`, `allowSetController`, `allowAddAccountingContext`, `allowAddPriceFeed`, `ownerMustSendPayouts`, `holdFees`, `useTotalSurplusForCashOuts`, `useDataHookForPay`, `useDataHookForCashOut`, `dataHook (address)`, `metadata (uint16)` | Packed into `JBRuleset.metadata` |
+| `JBRulesetMetadata` | `reservedPercent (uint16)`, `cashOutTaxRate (uint16)`, `baseCurrency (uint32)`, `pausePay`, `pauseCreditTransfers`, `allowOwnerMinting`, `allowSetCustomToken`, `allowTerminalMigration`, `allowSetTerminals`, `allowSetController`, `allowAddAccountingContext`, `allowAddPriceFeed`, `ownerMustSendPayouts`, `holdFees`, `scopeCashOutsToLocalBalances`, `useDataHookForPay`, `useDataHookForCashOut`, `dataHook (address)`, `metadata (uint16)` | Packed into `JBRuleset.metadata` |
 | `JBSplit` | `percent (uint32)`, `projectId (uint64)`, `beneficiary (address payable)`, `preferAddToBalance`, `lockedUntil (uint48)`, `hook (IJBSplitHook)` | `splitsOf()`, `setSplitGroupsOf()` |
 | `JBSplitGroup` | `groupId (uint256)`, `splits (JBSplit[])` | `JBRulesetConfig.splitGroups`, `setSplitGroupsOf()` |
 | `JBAccountingContext` | `token (address)`, `decimals (uint8)`, `currency (uint32)` | Terminal token accounting, surplus/reclaim calculations |
@@ -28,7 +28,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | Struct | Key Fields | Used In |
 |--------|------------|---------|
 | `JBBeforePayRecordedContext` | `terminal`, `payer`, `amount (JBTokenAmount)`, `projectId`, `rulesetId`, `beneficiary`, `weight`, `reservedPercent`, `metadata` | `IJBRulesetDataHook.beforePayRecordedWith()` input |
-| `JBBeforeCashOutRecordedContext` | `terminal`, `holder`, `projectId`, `rulesetId`, `cashOutCount`, `totalSupply`, `surplus (JBTokenAmount)`, `useTotalSurplus`, `cashOutTaxRate`, `beneficiaryIsFeeless`, `metadata` | `IJBRulesetDataHook.beforeCashOutRecordedWith()` input |
+| `JBBeforeCashOutRecordedContext` | `terminal`, `holder`, `projectId`, `rulesetId`, `cashOutCount`, `totalSupply`, `surplus (JBTokenAmount)`, `scopeCashOutsToLocalBalances`, `cashOutTaxRate`, `beneficiaryIsFeeless`, `metadata` | `IJBRulesetDataHook.beforeCashOutRecordedWith()` input |
 | `JBAfterPayRecordedContext` | `payer`, `projectId`, `rulesetId`, `amount (JBTokenAmount)`, `forwardedAmount (JBTokenAmount)`, `weight`, `newlyIssuedTokenCount`, `beneficiary`, `hookMetadata`, `payerMetadata` | `IJBPayHook.afterPayRecordedWith()` input |
 | `JBAfterCashOutRecordedContext` | `holder`, `projectId`, `rulesetId`, `cashOutCount`, `reclaimedAmount (JBTokenAmount)`, `forwardedAmount (JBTokenAmount)`, `cashOutTaxRate`, `beneficiary`, `hookMetadata`, `cashOutMetadata` | `IJBCashOutHook.afterCashOutRecordedWith()` input |
 | `JBPayHookSpecification` | `hook (IJBPayHook)`, `noop (bool)`, `amount`, `metadata` | Returned by data hook; specifies which pay hooks to call and how much to forward. `noop = true` means informational-only (callback skipped, amount must be 0). |

package/src/JBController.sol

@@ -188,7 +188,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.ADD_PRICE_FEED
+            account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.ADD_PRICE_FEED
         });
 
         JBRuleset memory ruleset = _currentRulesetOf(projectId);
@@ -317,7 +317,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.DEPLOY_ERC20
+            account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.DEPLOY_ERC20
         });
 
         // If a salt is provided, use it.
@@ -453,27 +453,25 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         address sender = _msgSender();
 
         // Enforce permissions.
+        bool isOmnichainOperator = sender == OMNICHAIN_RULESET_OPERATOR;
         _requirePermissionAllowingOverrideFrom({
-            account: PROJECTS.ownerOf(projectId),
+            account: _ownerOf(projectId),
             projectId: projectId,
             permissionId: JBPermissionIds.LAUNCH_RULESETS,
-            alsoGrantAccessIf: sender == OMNICHAIN_RULESET_OPERATOR
+            alsoGrantAccessIf: isOmnichainOperator
         });
-
-        // Enforce permissions.
         _requirePermissionAllowingOverrideFrom({
-            account: PROJECTS.ownerOf(projectId),
+            account: _ownerOf(projectId),
             projectId: projectId,
             permissionId: JBPermissionIds.SET_TERMINALS,
-            alsoGrantAccessIf: sender == OMNICHAIN_RULESET_OPERATOR
+            alsoGrantAccessIf: isOmnichainOperator
         });
-
         if (bytes(projectUri).length > 0) {
             _requirePermissionAllowingOverrideFrom({
-                account: PROJECTS.ownerOf(projectId),
+                account: _ownerOf(projectId),
                 projectId: projectId,
                 permissionId: JBPermissionIds.SET_PROJECT_URI,
-                alsoGrantAccessIf: sender == OMNICHAIN_RULESET_OPERATOR
+                alsoGrantAccessIf: isOmnichainOperator
             });
         }
 
@@ -559,7 +557,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         // Minting is restricted to: the project's owner, addresses with permission to `MINT_TOKENS`, the project's
         // terminals, and the project's data hook.
         _requirePermissionAllowingOverrideFrom({
-            account: PROJECTS.ownerOf(projectId),
+            account: _ownerOf(projectId),
             projectId: projectId,
             permissionId: JBPermissionIds.MINT_TOKENS,
             alsoGrantAccessIf: senderIsTerminalOrDataHook || senderHasDataHookMintPermission
@@ -626,7 +624,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
         // Enforce permissions.
         _requirePermissionAllowingOverrideFrom({
-            account: PROJECTS.ownerOf(projectId),
+            account: _ownerOf(projectId),
             projectId: projectId,
             permissionId: JBPermissionIds.QUEUE_RULESETS,
             alsoGrantAccessIf: _msgSender() == OMNICHAIN_RULESET_OPERATOR
@@ -665,7 +663,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_SPLIT_GROUPS
+            account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_SPLIT_GROUPS
         });
 
         // Set the split groups.
@@ -679,7 +677,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     function setTokenFor(uint256 projectId, IJBToken token) external override {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_TOKEN
+            account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_TOKEN
         });
 
         // Get a reference to the current ruleset.
@@ -703,7 +701,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     function setTokenMetadataOf(uint256 projectId, string calldata name, string calldata symbol) external override {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_TOKEN_METADATA
+            account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_TOKEN_METADATA
         });
 
         TOKENS.setTokenMetadataFor({projectId: projectId, name: name, symbol: symbol});
@@ -718,7 +716,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     function setUriOf(uint256 projectId, string calldata uri) external override {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_PROJECT_URI
+            account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.SET_PROJECT_URI
         });
 
         // Set the project's metadata URI.
@@ -1197,7 +1195,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         JBRuleset memory ruleset = _currentRulesetOf(projectId);
 
         // Get a reference to the project's owner.
-        address owner = PROJECTS.ownerOf(projectId);
+        address owner = _ownerOf(projectId);
 
         // Reset the pending reserved token balance.
         pendingReservedTokenBalanceOf[projectId] = 0;
@@ -1324,6 +1322,13 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         return ERC2771Context._msgSender();
     }
 
+    /// @notice The owner of a project.
+    /// @param projectId The ID of the project to get the owner of.
+    /// @return The owner of the project.
+    function _ownerOf(uint256 projectId) internal view returns (address) {
+        return PROJECTS.ownerOf(projectId);
+    }
+
     /// @notice The project's upcoming ruleset.
     /// @param projectId The ID of the project to check.
     /// @return The project's upcoming ruleset.

package/src/JBFeelessAddresses.sol

@@ -7,19 +7,17 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IJBFeelessAddresses} from "./interfaces/IJBFeelessAddresses.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. Managed by the
-/// contract owner (typically the protocol multisig).
+/// 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 {
     //*********************************************************************//
-    // --------------------- public stored properties -------------------- //
+    // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
 
-    /// @notice Check if the specified address is feeless.
-    /// @dev Feeless addresses can receive payouts without incurring a fee.
-    /// @dev Feeless addresses can use the surplus allowance without incurring a fee.
-    /// @dev Feeless addresses can be the beneficiary of cash outs without incurring a fee.
-    /// @custom:param addr The address to check.
-    mapping(address addr => bool) public override isFeeless;
+    /// @notice Raw feeless status per project per address.
+    /// @dev `projectId = 0` stores the global (all-project) feeless status.
+    mapping(uint256 projectId => mapping(address addr => bool)) internal _isFeelessFor;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
@@ -32,21 +30,42 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Add or remove an address from the fee-exempt list. Feeless addresses don't pay the 2.5% protocol fee
-    /// on payouts received, surplus allowance used, or cash outs where they're the beneficiary.
+    /// @notice Add or remove an address from the global (all-project) fee-exempt list.
+    /// @dev Equivalent to `setFeelessAddressFor(0, addr, flag)`.
     /// @dev Can only be called by this contract's owner (typically the protocol multisig).
     /// @param addr The address to set as feeless or not feeless.
     /// @param flag Whether the address should be feeless (`true`) or not feeless (`false`).
     function setFeelessAddress(address addr, bool flag) external virtual override onlyOwner {
-        isFeeless[addr] = flag;
+        _isFeelessFor[0][addr] = flag;
 
-        emit SetFeelessAddress({addr: addr, isFeeless: flag, caller: _msgSender()});
+        emit SetFeelessAddress({projectId: 0, addr: addr, isFeeless: flag, caller: _msgSender()});
+    }
+
+    /// @notice Add or remove an address from a project's fee-exempt list.
+    /// @dev Can only be called by this contract's owner (typically the protocol multisig).
+    /// @dev Use `projectId = 0` to set the global (all-project) feeless status.
+    /// @param projectId The ID of the project. 0 means all projects.
+    /// @param addr The address to set as feeless or not feeless for the project.
+    /// @param flag Whether the address should be feeless for the project (`true`) or not (`false`).
+    function setFeelessAddressFor(uint256 projectId, address addr, bool flag) external virtual override onlyOwner {
+        _isFeelessFor[projectId][addr] = flag;
+
+        emit SetFeelessAddress({projectId: projectId, addr: addr, isFeeless: flag, caller: _msgSender()});
     }
 
     //*********************************************************************//
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
+    /// @notice Returns whether the specified address is feeless for a specific project, considering both the wildcard
+    /// (projectId 0) and project-specific feeless status.
+    /// @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).
+    function isFeelessFor(address addr, uint256 projectId) external view override returns (bool) {
+        return _isFeelessFor[0][addr] || _isFeelessFor[projectId][addr];
+    }
+
     /// @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

@@ -334,7 +334,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
             // 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(address(split.hook))) {
+            if (!_isFeeless({addr: address(split.hook), projectId: projectId})) {
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -377,7 +377,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // the fee model taxes value leaving the protocol ecosystem, not internal rebalancing.
             // This payout is eligible for a fee if the funds are leaving this contract and the receiving terminal isn't
             // a feeless address.
-            if (terminal != this && !_isFeeless(address(terminal))) {
+            if (terminal != this && !_isFeeless({addr: address(terminal), projectId: projectId})) {
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -440,7 +440,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
             // This payout is eligible for a fee since the funds are leaving this contract and the recipient isn't a
             // feeless address.
-            if (!_isFeeless(recipient)) {
+            if (!_isFeeless({addr: recipient, projectId: projectId})) {
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -546,7 +546,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Migration to a non-feeless terminal incurs the standard 2.5% fee, same as any other fund egress.
             // This also settles any fee-free surplus liability that would otherwise be lost on the new terminal.
             uint256 feeAmount;
-            if (!_isFeeless(address(to)) && projectId != _FEE_BENEFICIARY_PROJECT_ID) {
+            if (!_isFeeless({addr: address(to), projectId: projectId}) && projectId != _FEE_BENEFICIARY_PROJECT_ID) {
                 feeAmount = _takeFeeFrom({
                     projectId: projectId,
                     token: token,
@@ -904,16 +904,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             JBCashOutHookSpecification[] memory hookSpecifications
         )
     {
-        (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) =
-            STORE.previewCashOutFrom({
-                terminal: address(this),
-                holder: holder,
-                projectId: projectId,
-                cashOutCount: cashOutCount,
-                tokenToReclaim: tokenToReclaim,
-                beneficiaryIsFeeless: _isFeeless(beneficiary),
-                metadata: metadata
-            });
+        bool feeless = _isFeeless({addr: beneficiary, projectId: projectId});
+        (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) = STORE.previewCashOutFrom({
+            terminal: address(this),
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            tokenToReclaim: tokenToReclaim,
+            beneficiaryIsFeeless: feeless,
+            metadata: metadata
+        });
     }
 
     /// @notice Simulates a payment without modifying state — use this to preview how many project tokens a payer
@@ -1155,7 +1155,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         uint256 cashOutTaxRate;
 
         // Cache whether the beneficiary is feeless.
-        bool beneficiaryIsFeeless = _isFeeless(beneficiary);
+        bool beneficiaryIsFeeless = _isFeeless({addr: beneficiary, projectId: projectId});
 
         {
             // Cache the controller to avoid a redundant external call (also used inside STORE.recordCashOutFor).
@@ -1445,8 +1445,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             }
 
             // Get the fee for the specified amount.
-            uint256 specificationAmountFee =
-                _isFeeless(address(specification.hook)) ? 0 : _feeAmountFrom(specification.amount);
+            uint256 specificationAmountFee = _isFeeless({addr: address(specification.hook), projectId: projectId})
+                ? 0
+                : _feeAmountFrom(specification.amount);
 
             // Add the specification's amount to the amount eligible for fees.
             if (specificationAmountFee != 0) {
@@ -1842,7 +1843,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Send any leftover funds to the project owner and update the fee tracking accordingly.
         if (leftoverPayoutAmount != 0) {
             // Keep a reference to the fee for the leftover payout amount.
-            uint256 fee = _isFeeless(projectOwner) ? 0 : _feeAmountFrom(leftoverPayoutAmount);
+            uint256 fee =
+                _isFeeless({addr: projectOwner, projectId: projectId}) ? 0 : _feeAmountFrom(leftoverPayoutAmount);
 
             uint256 netLeftoverPayoutAmount;
             unchecked {
@@ -2025,7 +2027,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Take a fee from the `amountPaidOut`, if needed.
         // The net amount is the final amount withdrawn after the fee has been taken.
         netAmountPaidOut = amountPaidOut
-            - (_isFeeless(owner) || _isFeeless(beneficiary)
+            - (_isFeeless({addr: owner, projectId: projectId}) || _isFeeless({addr: beneficiary, projectId: projectId})
                     ? 0
                     : _takeFeeFrom({
                         projectId: projectId,
@@ -2113,9 +2115,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Returns a flag indicating if interacting with an address should not incur fees.
     /// @param addr The address to check.
-    /// @return A flag indicating if the address should not incur fees.
-    function _isFeeless(address addr) internal view returns (bool) {
-        return FEELESS_ADDRESSES.isFeeless(addr);
+    /// @param projectId The ID of the project to check the per-project feeless status for.
+    /// @return A flag indicating if the address should not incur fees (globally or for the project).
+    function _isFeeless(address addr, uint256 projectId) internal view returns (bool) {
+        return FEELESS_ADDRESSES.isFeelessFor({addr: addr, projectId: projectId});
     }
 
     /// @notice The calldata. Preferred to use over `msg.data`.

package/src/JBTerminalStore.sol

@@ -847,57 +847,6 @@ contract JBTerminalStore is IJBTerminalStore {
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//
 
-    /// @notice Computes the surplus relevant for a cash out (total or local, depending on ruleset flag).
-    /// @dev When `useTotalSurplusForCashOuts` is enabled, surplus is aggregated from ALL registered terminals without
-    /// validation. Projects MUST only register trusted terminals — an untrusted terminal can over-report surplus and
-    /// cause the executing terminal to overpay cash-outs.
-    /// @param terminal The terminal recording the cash out.
-    /// @param projectId The ID of the project to cash out from.
-    /// @param tokenToReclaim The token to reclaim.
-    /// @param ruleset The ruleset during the cash out.
-    /// @return The surplus amount in the token's native decimals and currency.
-    function _cashOutSurplusOf(
-        address terminal,
-        uint256 projectId,
-        address tokenToReclaim,
-        JBRuleset memory ruleset
-    )
-        internal
-        view
-        returns (uint256)
-    {
-        // Look up the accounting context (decimals, currency) for the token being reclaimed at this terminal.
-        JBAccountingContext memory accountingContext = _accountingContextForTokenOf[terminal][projectId][tokenToReclaim];
-
-        // If the ruleset uses total surplus, aggregate across ALL terminals and ALL tokens.
-        if (ruleset.useTotalSurplusForCashOuts()) {
-            return JBSurplus.currentSurplusOf({
-                projectId: projectId,
-                // Get every terminal the project has registered.
-                terminals: DIRECTORY.terminalsOf(projectId),
-                // Empty tokens array = include all tokens at each terminal.
-                tokens: new address[](0),
-                // Express the result in the reclaimed token's decimals and currency.
-                decimals: accountingContext.decimals,
-                currency: accountingContext.currency
-            });
-        }
-
-        // Otherwise, only account for the specific token's surplus at this terminal.
-        JBAccountingContext[] memory singleContext = new JBAccountingContext[](1);
-        singleContext[0] = accountingContext;
-
-        // Compute surplus from only this terminal using only the reclaimed token's balance.
-        return _surplusFrom({
-            terminal: terminal,
-            projectId: projectId,
-            accountingContexts: singleContext,
-            ruleset: ruleset,
-            targetDecimals: accountingContext.decimals,
-            targetCurrency: accountingContext.currency
-        });
-    }
-
     /// @notice Calls the data hook, validates noop specifications, and computes the bonding curve reclaim amount.
     /// @dev Extracted from `_computeCashOutFrom` to keep it under the EVM stack depth limit (16 slots).
     /// @param ruleset The current ruleset (used to resolve the data hook address).
@@ -979,14 +928,18 @@ contract JBTerminalStore is IJBTerminalStore {
         // Get a reference to the project's current ruleset.
         ruleset = RULESETS.currentOf(projectId);
 
-        // Get the project's current surplus for the token being reclaimed.
-        uint256 surplus = _cashOutSurplusOf({
-            terminal: terminal, projectId: projectId, tokenToReclaim: tokenToReclaim, ruleset: ruleset
-        });
-
         // Get the accounting context for the token being reclaimed.
         JBAccountingContext memory accountingContext = _accountingContextForTokenOf[terminal][projectId][tokenToReclaim];
 
+        // Get the project's current surplus across ALL terminals and ALL tokens.
+        uint256 surplus = JBSurplus.currentSurplusOf({
+            projectId: projectId,
+            terminals: DIRECTORY.terminalsOf(projectId),
+            tokens: new address[](0),
+            decimals: accountingContext.decimals,
+            currency: accountingContext.currency
+        });
+
         // Get the total number of outstanding project tokens.
         uint256 effectiveTotalSupply =
             IJBController(address(DIRECTORY.controllerOf(projectId))).totalTokenSupplyWithReservedTokensOf(projectId);
@@ -1019,7 +972,7 @@ contract JBTerminalStore is IJBTerminalStore {
                 decimals: accountingContext.decimals,
                 currency: accountingContext.currency
             });
-            context.useTotalSurplus = ruleset.useTotalSurplusForCashOuts();
+            context.scopeCashOutsToLocalBalances = ruleset.scopeCashOutsToLocalBalances();
             context.cashOutTaxRate = ruleset.cashOutTaxRate();
             context.beneficiaryIsFeeless = beneficiaryIsFeeless;
             context.metadata = metadata;

package/src/interfaces/IJBFeelessAddresses.sol

@@ -1,21 +1,31 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @notice Tracks addresses that are exempt from fees.
+/// @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 {
-    /// @notice An address's feeless status was set.
+    /// @notice An address's feeless status was set for a project (or globally if projectId is 0).
+    /// @param projectId The project the feeless status applies to. 0 means all projects.
     /// @param addr The address whose feeless status was set.
     /// @param isFeeless Whether the address is feeless.
     /// @param caller The address that set the feeless status.
-    event SetFeelessAddress(address indexed addr, bool indexed isFeeless, address caller);
+    event SetFeelessAddress(uint256 indexed projectId, address indexed addr, bool indexed isFeeless, address caller);
 
-    /// @notice Returns whether the specified address is feeless.
+    /// @notice Returns whether the specified address is feeless for a specific project, considering both the wildcard
+    /// (projectId 0) and project-specific feeless status.
     /// @param addr The address to check.
-    /// @return A flag indicating whether the address is feeless.
-    function isFeeless(address addr) external view returns (bool);
+    /// @param projectId The ID of the project to check.
+    /// @return A flag indicating whether the address is feeless (globally or for the project).
+    function isFeelessFor(address addr, uint256 projectId) external view returns (bool);
 
-    /// @notice Sets whether an address is feeless.
+    /// @notice Sets whether an address is feeless globally (for all projects).
     /// @param addr The address to set the feeless status of.
     /// @param flag A flag indicating whether the address should be feeless.
     function setFeelessAddress(address addr, bool flag) external;
+
+    /// @notice Sets whether an address is feeless for a specific project.
+    /// @param projectId The ID of the project. 0 means all projects (same as `setFeelessAddress`).
+    /// @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;
 }

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -67,7 +67,7 @@ library JBRulesetMetadataResolver {
         return ((ruleset.metadata >> 78) & 1) == 1;
     }
 
-    function useTotalSurplusForCashOuts(JBRuleset memory ruleset) internal pure returns (bool) {
+    function scopeCashOutsToLocalBalances(JBRuleset memory ruleset) internal pure returns (bool) {
         return ((ruleset.metadata >> 79) & 1) == 1;
     }
 
@@ -123,8 +123,8 @@ library JBRulesetMetadataResolver {
         if (rulesetMetadata.ownerMustSendPayouts) packed |= 1 << 77;
         // hold fees in bit 78.
         if (rulesetMetadata.holdFees) packed |= 1 << 78;
-        // useTotalSurplusForCashOuts in bit 79.
-        if (rulesetMetadata.useTotalSurplusForCashOuts) packed |= 1 << 79;
+        // scopeCashOutsToLocalBalances in bit 79.
+        if (rulesetMetadata.scopeCashOutsToLocalBalances) packed |= 1 << 79;
         // use pay data source in bit 80.
         if (rulesetMetadata.useDataHookForPay) packed |= 1 << 80;
         // use cash out data source in bit 81.
@@ -154,7 +154,7 @@ library JBRulesetMetadataResolver {
             allowAddPriceFeed: allowAddPriceFeed(ruleset),
             ownerMustSendPayouts: ownerMustSendPayouts(ruleset),
             holdFees: holdFees(ruleset),
-            useTotalSurplusForCashOuts: useTotalSurplusForCashOuts(ruleset),
+            scopeCashOutsToLocalBalances: scopeCashOutsToLocalBalances(ruleset),
             useDataHookForPay: useDataHookForPay(ruleset),
             useDataHookForCashOut: useDataHookForCashOut(ruleset),
             dataHook: dataHook(ruleset),

package/src/structs/JBBeforeCashOutRecordedContext.sol

@@ -14,7 +14,8 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// @custom:member surplus The surplus amount used for the calculation, as a fixed point number with 18 decimals.
 /// Includes the token of the surplus, the surplus value, the number of decimals
 /// included, and the currency of the surplus.
-/// @custom:member useTotalSurplus If true, use surplus across all of a project's terminals when calculating cash outs.
+/// @custom:member scopeCashOutsToLocalBalances If true, omnichain hooks should use only local chain balances for cash
+/// outs (skip cross-chain aggregation).
 /// @custom:member cashOutTaxRate The cash out tax rate of the ruleset the cash out is made during, out of
 /// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
 /// @custom:member beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Useful for data hooks
@@ -29,7 +30,7 @@ struct JBBeforeCashOutRecordedContext {
     uint256 cashOutCount;
     uint256 totalSupply;
     JBTokenAmount surplus;
-    bool useTotalSurplus;
+    bool scopeCashOutsToLocalBalances;
     uint256 cashOutTaxRate;
     bool beneficiaryIsFeeless;
     bytes metadata;

package/src/structs/JBRulesetMetadata.sol

@@ -21,8 +21,8 @@ pragma solidity ^0.8.0;
 /// @custom:member allowAddPriceFeed If `true`, the project can register new price feeds in `JBPrices`.
 /// @custom:member ownerMustSendPayouts If `true`, only the project owner can trigger payout distribution.
 /// @custom:member holdFees If `true`, fees are accumulated but not processed until a future ruleset (or manually).
-/// @custom:member useTotalSurplusForCashOuts If `true`, cash-out calculations use surplus across all terminals (not
-/// just the one to cash out from).
+/// @custom:member scopeCashOutsToLocalBalances If `true`, omnichain cash-out calculations use only the local chain's
+/// balances (not cross-chain aggregates).
 /// @custom:member useDataHookForPay If `true`, the data hook is called before recording payments.
 /// @custom:member useDataHookForCashOut If `true`, the data hook is called before recording cash outs.
 /// @custom:member dataHook Contract called before pay/cash-out to potentially override token counts or add hooks.
@@ -42,7 +42,7 @@ struct JBRulesetMetadata {
     bool allowAddPriceFeed;
     bool ownerMustSendPayouts;
     bool holdFees;
-    bool useTotalSurplusForCashOuts;
+    bool scopeCashOutsToLocalBalances;
     bool useDataHookForPay;
     bool useDataHookForCashOut;
     address dataHook;

package/test/helpers/JBTest.sol

@@ -43,7 +43,7 @@ contract JBTest is Test {
             allowAddAccountingContext: true,
             allowAddPriceFeed: true,
             holdFees: false,
-            useTotalSurplusForCashOuts: true,
+            scopeCashOutsToLocalBalances: true,
             useDataHookForPay: false,
             useDataHookForCashOut: false,
             dataHook: address(0),
@@ -81,7 +81,7 @@ contract JBTest is Test {
             allowAddAccountingContext: true,
             allowAddPriceFeed: false,
             holdFees: false,
-            useTotalSurplusForCashOuts: false,
+            scopeCashOutsToLocalBalances: false,
             useDataHookForPay: false,
             useDataHookForCashOut: false,
             dataHook: address(0),
@@ -105,7 +105,7 @@ contract JBTest is Test {
             allowAddAccountingContext: false,
             allowAddPriceFeed: false,
             holdFees: true,
-            useTotalSurplusForCashOuts: true,
+            scopeCashOutsToLocalBalances: true,
             useDataHookForPay: false,
             useDataHookForCashOut: false,
             dataHook: address(0),