@bananapus/core-v6 0.0.24 → 0.0.25

package/src/JBERC20.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
@@ -36,7 +36,11 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    constructor() Ownable(address(this)) ERC20("invalid", "invalid") ERC20Permit("JBToken") {}
+    /// @dev Set `_name` on the implementation contract to prevent it from being initialized directly.
+    /// Clones start with empty `_name`, so `initialize(...)` works only on clones.
+    constructor() Ownable(address(this)) ERC20("invalid", "invalid") ERC20Permit("JBToken") {
+        _name = "invalid";
+    }
 
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //

package/src/JBFeelessAddresses.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";

package/src/JBFundAccessLimits.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBControlled} from "./abstract/JBControlled.sol";
 import {IJBDirectory} from "./interfaces/IJBDirectory.sol";

package/src/JBMultiTerminal.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
@@ -123,9 +123,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// `cashOutTaxRate == 0`, fees are applied only up to this amount, then decremented. This prevents a round-trip
     /// fee bypass (intra-terminal payout → zero-tax cashout) while scoping the fee precisely to the fee-free inflow
     /// — legitimate cashouts beyond this amount remain fee-free.
-    /// @dev WARNING: This accumulator persists across rulesets and cannot be cleared. Once a fee-free payout
-    /// increments it, the balance remains until consumed by a zero-tax cashout. There is no admin function to reset
-    /// it. Projects switching from zero-tax to non-zero-tax rulesets will carry forward any unconsumed balance.
+    /// @dev Lifecycle: incremented on fee-free intra-terminal payouts. After any outflow (payouts, useAllowanceOf,
+    /// non-zero-tax or feeless cashouts), capped at remaining balance — non-fee-free funds are considered to leave
+    /// first, preserving the fee-free counter. Consumed during zero-tax cashouts. Cleared on terminal migration.
+    /// @dev Persists across rulesets — projects switching from zero-tax to non-zero-tax carry forward any
+    /// unconsumed balance. There is no admin function to reset it.
     /// @custom:param projectId The ID of the project that received the payout.
     /// @custom:param token The token that was received.
     mapping(uint256 projectId => mapping(address token => uint256)) internal _feeFreeSurplusOf;
@@ -490,6 +492,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             revert JBMultiTerminal_TerminalTokensIncompatible({projectId: projectId, token: token, terminal: to});
         }
 
+        // Clear fee-free surplus tracking before migration. The new terminal has no fee-free history.
+        // This prevents stale fee-free surplus from persisting if the project later migrates back.
+        delete _feeFreeSurplusOf[projectId][token];
+
         // Terminal migration intentionally does not transfer held fees. Held fees belong to the
         // fee beneficiary (project #1), not the migrating project. They unlock after 28 days regardless of terminal.
         // Record the migration in the store.
@@ -578,6 +584,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Process any fees that are being held for the project.
     /// @dev Reentrancy safety: the loop re-reads `_nextHeldFeeIndexOf` from storage each iteration and advances the
     /// index before the external `_processFee` call, so a reentrant call cannot double-process the same fee entry.
+    /// @dev Phantom balance risk: after a terminal migration, held fees remain in this terminal but the backing tokens
+    /// have been transferred to the new terminal via `migrateBalanceOf`. If `_processFee` reverts (e.g. the fee
+    /// terminal rejects the payment), the catch block calls `_recordAddedBalanceFor`, which credits the project's
+    /// recorded balance without any actual tokens arriving — creating a phantom balance. This is an accepted
+    /// trade-off:
+    /// the alternative (losing the fee amount entirely on revert) is worse. Callers should be aware that processing
+    /// held fees post-migration may inflate the project's recorded balance if any fee payments revert.
+    /// @dev The index-increment-before-`_processFee` pattern is intentional: locked (not-yet-unlocked) fees are skipped
+    /// via the `unlockTimestamp` check, and advancing the index before the external call prevents reentrancy from
+    /// reprocessing the same fee entry.
     /// @param projectId The ID of the project to process held fees for.
     /// @param token The token to process held fees for.
     /// @param count The number of fees to process.
@@ -1097,6 +1113,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     // Non-zero tax: fees apply to the full reclaim amount.
                     amountEligibleForFees += reclaimAmount;
                     reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
+                    // Cap fee-free surplus at remaining balance (non-fee-free funds leave first).
+                    _reduceFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
                 } else {
                     // Zero tax: fees apply only up to the fee-free surplus (round-trip prevention).
                     uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][tokenToReclaim];
@@ -1107,6 +1125,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                         reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: feeableAmount, feePercent: FEE});
                     }
                 }
+            } else {
+                // Feeless beneficiary: fee logic skipped, but still cap fee-free surplus at remaining balance.
+                _reduceFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
             }
 
             // Subtract the fee from the reclaim amount.
@@ -1652,6 +1673,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         (ruleset, amountPaidOut) =
             STORE.recordPayoutFor({projectId: projectId, token: token, amount: amount, currency: currency});
 
+        // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
+        _reduceFeeFreeSurplus({projectId: projectId, token: token});
+
         // Get a reference to the project's owner.
         // The owner will receive tokens minted by paying the platform fee and receive any leftover funds not sent to
         // payout splits.
@@ -1850,6 +1874,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         (ruleset, amountPaidOut) =
             STORE.recordUsedAllowanceOf({projectId: projectId, token: token, amount: amount, currency: currency});
 
+        // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
+        _reduceFeeFreeSurplus({projectId: projectId, token: token});
+
         // Take a fee from the `amountPaidOut`, if needed.
         // The net amount is the final amount withdrawn after the fee has been taken.
         // slither-disable-next-line reentrancy-events
@@ -1884,6 +1911,28 @@ 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 _reduceFeeFreeSurplus(uint256 projectId, address token) internal {
+        // Get the current fee-free surplus for this project/token pair.
+        uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][token];
+
+        // Nothing to reduce 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 ------------------------- //
     //*********************************************************************//

package/src/JBPermissions.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
@@ -56,7 +56,11 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     //*********************************************************************//
 
     /// @notice Sets permissions for an operator.
-    /// @dev Only an address can give permissions to or revoke permissions from its operators.
+    /// @dev Only the `account` itself (i.e. `msg.sender == account`) can grant or revoke its operators' permissions
+    /// without restriction — including ROOT on the wildcard project ID (`projectId = 0`).
+    /// @dev A third-party caller who holds ROOT for a specific project may set *non-ROOT* permissions for that project
+    /// on someone else's behalf, but **cannot**: (a) grant ROOT to others, or (b) set any permissions on the wildcard
+    /// project ID. This prevents ROOT operators from escalating their own privileges.
     /// @param account The account setting its operators' permissions.
     /// @param permissionsData The data which specifies the permissions the operator is being given.
     function setPermissionsFor(address account, JBPermissionsData calldata permissionsData) external override {

package/src/JBPrices.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC2771Context, Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";

package/src/JBProjects.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";

package/src/JBRulesets.sol

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

package/src/JBSplits.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBControlled} from "./abstract/JBControlled.sol";
 import {IJBDirectory} from "./interfaces/IJBDirectory.sol";

package/src/JBTerminalStore.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {mulDiv} from "@prb/math/src/Common.sol";
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
@@ -591,57 +591,6 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
-    /// @notice Returns the number of surplus terminal tokens that would be reclaimed from terminals by cashing out a
-    /// given number of tokens, considering only specific tokens.
-    /// @param projectId The ID of the project whose tokens would be cashed out.
-    /// @param cashOutCount The number of tokens that would be cashed out, as a fixed point number with 18 decimals.
-    /// @param terminals The terminals that would be cashed out from. If this is an empty array, surplus within all
-    /// the project's terminals are considered.
-    /// @param tokens The tokens to include in the surplus calculation.
-    /// @param decimals The number of decimals to include in the resulting fixed point number.
-    /// @param currency The currency that the resulting number will be in terms of.
-    /// @return The amount of surplus terminal tokens that would be reclaimed by cashing out `cashOutCount`
-    /// tokens.
-    function currentReclaimableSurplusOf(
-        uint256 projectId,
-        uint256 cashOutCount,
-        IJBTerminal[] calldata terminals,
-        address[] calldata tokens,
-        uint256 decimals,
-        uint256 currency
-    )
-        external
-        view
-        override
-        returns (uint256)
-    {
-        // Aggregate surplus across the terminals, optionally filtered by the specified tokens.
-        uint256 currentSurplus = _currentSurplusOf({
-            projectId: projectId, terminals: terminals, tokens: tokens, decimals: decimals, currency: currency
-        });
-
-        // If there's no surplus, nothing can be reclaimed.
-        if (currentSurplus == 0) return 0;
-
-        // Get the project token's total supply.
-        uint256 totalSupply =
-            IJBController(address(DIRECTORY.controllerOf(projectId))).totalTokenSupplyWithReservedTokensOf(projectId);
-
-        // Can't cash out more tokens than are in the total supply.
-        if (cashOutCount > totalSupply) return 0;
-
-        // Get the cash out tax rate from the current ruleset.
-        uint256 cashOutTaxRate = RULESETS.currentOf(projectId).cashOutTaxRate();
-
-        // Return the amount of surplus terminal tokens that would be reclaimed.
-        return JBCashOuts.cashOutFrom({
-            surplus: currentSurplus,
-            cashOutCount: cashOutCount,
-            totalSupply: totalSupply,
-            cashOutTaxRate: cashOutTaxRate
-        });
-    }
-
     /// @notice Gets the current surplus amount for a project across specified terminals and tokens.
     /// @param projectId The ID of the project to get surplus for.
     /// @param terminals The terminals to include. If empty, all project terminals are used.
@@ -684,7 +633,7 @@ contract JBTerminalStore is IJBTerminalStore {
         override
         returns (uint256)
     {
-        return this.currentReclaimableSurplusOf({
+        return currentReclaimableSurplusOf({
             projectId: projectId,
             cashOutCount: cashOutCount,
             terminals: new IJBTerminal[](0),
@@ -797,6 +746,61 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
+    /// @notice Returns the number of surplus terminal tokens that would be reclaimed from terminals by cashing out a
+    /// given number of tokens, considering only specific tokens.
+    /// @param projectId The ID of the project whose tokens would be cashed out.
+    /// @param cashOutCount The number of tokens that would be cashed out, as a fixed point number with 18 decimals.
+    /// @param terminals The terminals that would be cashed out from. If this is an empty array, surplus within all
+    /// the project's terminals are considered.
+    /// @param tokens The tokens to include in the surplus calculation.
+    /// @param decimals The number of decimals to include in the resulting fixed point number.
+    /// @param currency The currency that the resulting number will be in terms of.
+    /// @return The amount of surplus terminal tokens that would be reclaimed by cashing out `cashOutCount`
+    /// tokens.
+    function currentReclaimableSurplusOf(
+        uint256 projectId,
+        uint256 cashOutCount,
+        IJBTerminal[] memory terminals,
+        address[] memory tokens,
+        uint256 decimals,
+        uint256 currency
+    )
+        public
+        view
+        override
+        returns (uint256)
+    {
+        // Aggregate surplus across the terminals, optionally filtered by the specified tokens.
+        uint256 currentSurplus = _currentSurplusOf({
+            projectId: projectId, terminals: terminals, tokens: tokens, decimals: decimals, currency: currency
+        });
+
+        // If there's no surplus, nothing can be reclaimed.
+        if (currentSurplus == 0) return 0;
+
+        // Get the project token's total supply.
+        uint256 totalSupply =
+            IJBController(address(DIRECTORY.controllerOf(projectId))).totalTokenSupplyWithReservedTokensOf(projectId);
+
+        // Can't cash out more tokens than are in the total supply.
+        if (cashOutCount > totalSupply) return 0;
+
+        // Get the cash out tax rate from the current ruleset.
+        uint256 cashOutTaxRate = RULESETS.currentOf(projectId).cashOutTaxRate();
+
+        // Return the amount of surplus terminal tokens that would be reclaimed.
+        return JBCashOuts.cashOutFrom({
+            surplus: currentSurplus,
+            cashOutCount: cashOutCount,
+            totalSupply: totalSupply,
+            cashOutTaxRate: cashOutTaxRate
+        });
+    }
+
     //*********************************************************************//
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//

package/src/JBTokens.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
 
@@ -398,6 +398,10 @@ contract JBTokens is JBControlled, IJBTokens {
     //*********************************************************************//
 
     /// @notice The total supply for a specific project, including both tokens and token credits.
+    /// @dev WARNING: Projects that use `setTokenFor` with an external ERC-20 inherit that token's supply manipulation
+    /// surface. If the external token has a separate minting authority, `totalSupply()` can be inflated outside of
+    /// this contract, which dilutes cash-out values for all holders. Projects using `deployERC20For` are safe because
+    /// the resulting `JBERC20` is exclusively owned by this `JBTokens` contract.
     /// @param projectId The ID of the project to get the total supply of.
     /// @return totalSupply The total supply of the project's tokens and token credits.
     function totalSupplyOf(uint256 projectId) public view override returns (uint256 totalSupply) {

package/src/interfaces/IJBController.sol

@@ -251,7 +251,13 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     /// @param pricingCurrency The currency the feed's output price is in terms of.
     /// @param unitCurrency The currency being priced by the feed.
     /// @param feed The price feed to add.
-    function addPriceFeed(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, IJBPriceFeed feed) external;
+    function addPriceFeedFor(
+        uint256 projectId,
+        uint256 pricingCurrency,
+        uint256 unitCurrency,
+        IJBPriceFeed feed
+    )
+        external;
 
     /// @notice Burns a holder's project tokens or credits.
     /// @param holder The address whose tokens are being burned.

package/src/libraries/JBPayoutSplitGroupLib.sol

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

package/src/periphery/JBDeadline1Day.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBDeadline3Days.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBDeadline3Hours.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBDeadline7Days.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBMatchingPriceFeed.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {IJBPriceFeed} from "src/interfaces/IJBPriceFeed.sol";
 

package/test/TestAccessToFunds.sol

@@ -1221,14 +1221,14 @@ contract TestAccessToFunds_Local is TestBaseWorkflow {
             MockPriceFeed _priceFeedNativeUsd = new MockPriceFeed(_USD_PRICE_PER_NATIVE, _PRICE_FEED_DECIMALS);
             vm.label(address(_priceFeedNativeUsd), "Mock Price Feed Native-USDC");
 
-            _controller.addPriceFeed({
+            _controller.addPriceFeedFor({
                 projectId: 1,
                 pricingCurrency: uint32(uint160(address(_usdcToken))),
                 unitCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
                 feed: _priceFeedNativeUsd
             });
 
-            _controller.addPriceFeed({
+            _controller.addPriceFeedFor({
                 projectId: 2,
                 pricingCurrency: uint32(uint160(address(_usdcToken))),
                 unitCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
@@ -1898,14 +1898,14 @@ contract TestAccessToFunds_Local is TestBaseWorkflow {
             MockPriceFeed _priceFeedNativeUsd = new MockPriceFeed(_USD_PRICE_PER_NATIVE, _PRICE_FEED_DECIMALS);
             vm.label(address(_priceFeedNativeUsd), "Mock Price Feed Native-USDC");
 
-            _controller.addPriceFeed({
+            _controller.addPriceFeedFor({
                 projectId: 1,
                 pricingCurrency: uint32(uint160(address(_usdcToken))),
                 unitCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
                 feed: _priceFeedNativeUsd
             });
 
-            _controller.addPriceFeed({
+            _controller.addPriceFeedFor({
                 projectId: 2,
                 pricingCurrency: uint32(uint160(address(_usdcToken))),
                 unitCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),