@bananapus/core-v6 0.0.15 → 0.0.17

package/src/JBFundAccessLimits.sol

@@ -177,6 +177,7 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
 
             // If the currencies match, return the value.
             if (currency == packedPayoutLimitData >> 224) {
+                // forge-lint: disable-next-line(unsafe-typecast)
                 return uint256(uint224(packedPayoutLimitData));
             }
         }
@@ -217,8 +218,12 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
             uint256 packedPayoutLimitData = packedPayoutLimitsData[i];
 
             // The limit amount is in bits 0-223. The currency is in bits 224-255.
+            // forge-lint: disable-next-line(unsafe-typecast)
             payoutLimits[i] = JBCurrencyAmount({
-                currency: uint32(packedPayoutLimitData >> 224), amount: uint224(packedPayoutLimitData)
+                // forge-lint: disable-next-line(unsafe-typecast)
+                currency: uint32(packedPayoutLimitData >> 224),
+                // forge-lint: disable-next-line(unsafe-typecast)
+                amount: uint224(packedPayoutLimitData)
             });
         }
     }
@@ -258,6 +263,7 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
 
             // If the currencies match, return the value.
             if (currency == packedSurplusAllowanceData >> 224) {
+                // forge-lint: disable-next-line(unsafe-typecast)
                 return uint256(uint224(packedSurplusAllowanceData));
             }
         }
@@ -300,8 +306,12 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
             uint256 packedSurplusAllowanceData = packedSurplusAllowancesData[i];
 
             // The limit is in bits 0-223. The currency is in bits 224-255.
+            // forge-lint: disable-next-line(unsafe-typecast)
             surplusAllowances[i] = JBCurrencyAmount({
-                currency: uint32(packedSurplusAllowanceData >> 224), amount: uint224(packedSurplusAllowanceData)
+                // forge-lint: disable-next-line(unsafe-typecast)
+                currency: uint32(packedSurplusAllowanceData >> 224),
+                // forge-lint: disable-next-line(unsafe-typecast)
+                amount: uint224(packedSurplusAllowanceData)
             });
         }
     }

package/src/JBMultiTerminal.sol

@@ -136,6 +136,18 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @custom:param projectId The ID of the project to get a list of accepted tokens for.
     mapping(uint256 projectId => JBAccountingContext[]) internal _accountingContextsOf;
 
+    /// @notice The cumulative amount of fee-free intra-terminal payouts a project has received for a given token.
+    /// @dev Incremented each time a fee-free payout lands (same terminal, no fee charged). During cashout with
+    /// `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.
+    /// @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;
+
     /// @notice Fees that are being held for each project.
     /// @dev Projects can temporarily hold fees and unlock them later by adding funds to the project's balance.
     /// @dev Held fees can be processed at any time by this terminal's owner.
@@ -416,12 +428,21 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 revert JBMultiTerminal_RecipientProjectTerminalNotFound(split.projectId, token);
             }
 
+            // Fees apply to fund egress, not intra-terminal accounting. When both projects share this terminal,
+            // funds stay within the contract (addToBalance or pay) so no fee is charged. This is intentional:
+            // 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 feelss address.
+            // a feeless address.
             if (terminal != this && !_isFeeless(address(terminal))) {
                 netPayoutAmount -= JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
             }
 
+            // Track the fee-free payout amount. During cashout at zero tax rate, fees apply
+            // only up to this accumulated amount, preventing round-trip fee bypass.
+            if (terminal == this) {
+                _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
+            }
+
             // Send the `projectId` in the metadata as a referral.
             bytes memory metadata = bytes(abi.encodePacked(projectId));
 
@@ -541,6 +562,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             revert JBMultiTerminal_TerminalTokensIncompatible({projectId: projectId, token: token, terminal: to});
         }
 
+        // 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.
         // slither-disable-next-line reentrancy-events
         balance = STORE.recordTerminalMigration({projectId: projectId, token: token});
@@ -625,6 +648,8 @@ 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.
     /// @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.
@@ -1049,6 +1074,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 accountingContext: accountingContext,
                 balanceAccountingContexts: balanceAccountingContexts,
                 cashOutCount: cashOutCount,
+                beneficiaryIsFeeless: _isFeeless(beneficiary),
                 metadata: metadata
             });
         }
@@ -1064,12 +1090,22 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         // Send the reclaimed funds to the beneficiary.
         if (reclaimAmount != 0) {
-            // Determine if a fee should be taken. Fees are not taked if the cash out tax rate is zero,
-            // if the beneficiary is feeless, or if the fee beneficiary doesn't accept the given token.
-            if (!_isFeeless(beneficiary) && cashOutTaxRate != 0) {
-                amountEligibleForFees += reclaimAmount;
-                // Subtract the fee for the reclaimed amount.
-                reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
+            // Determine if a fee should be taken. Fees are not taken if the beneficiary is feeless.
+            if (!_isFeeless(beneficiary)) {
+                if (cashOutTaxRate != 0) {
+                    // Non-zero tax: fees apply to the full reclaim amount.
+                    amountEligibleForFees += reclaimAmount;
+                    reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
+                } else {
+                    // Zero tax: fees apply only up to the fee-free surplus (round-trip prevention).
+                    uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][tokenToReclaim];
+                    if (feeFreeSurplus != 0) {
+                        uint256 feeableAmount = reclaimAmount < feeFreeSurplus ? reclaimAmount : feeFreeSurplus;
+                        _feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
+                        amountEligibleForFees += feeableAmount;
+                        reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: feeableAmount, feePercent: FEE});
+                    }
+                }
             }
 
             // Subtract the fee from the reclaim amount.
@@ -1623,7 +1659,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         internal
         returns (uint256)
     {
-        // Attempt to distribute this split.
+        // Failed split payouts consume the payout limit by design. The try-catch prevents a single
+        // split from DoS-ing the entire payout. Failed splits' amounts are returned to the project balance via
+        // `_recordAddedBalanceFor`. Payout limit consumption is correct because the project authorized the
+        // distribution.
         // slither-disable-next-line reentrancy-events
         try this.executePayout({
             split: split, projectId: projectId, token: token, amount: amount, originalMessageSender: _msgSender()
@@ -1697,7 +1736,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 ? 0
                 : JBFees.feeAmountFrom({amountBeforeFee: leftoverPayoutAmount, feePercent: FEE});
 
-            // Transfer the amount to the project owner.
+            // Failed owner transfer consumes the payout limit by design. Same pattern as split payouts:
+            // the try-catch prevents revert, failed amount is returned to project balance, and the owner can retry
+            // via addToBalanceOf or in the next cycle.
             try this.executeTransferTo({addr: projectOwner, token: token, amount: leftoverPayoutAmount - fee}) {
                 if (fee > 0) {
                     amountEligibleForFees += leftoverPayoutAmount;
@@ -1834,6 +1875,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 JBFee({
                     amount: amount,
                     beneficiary: beneficiary,
+                    // forge-lint: disable-next-line(unsafe-typecast)
                     unlockTimestamp: uint48(block.timestamp + _FEE_HOLDING_SECONDS)
                 })
             );
@@ -1877,7 +1919,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
 
         // If there's sufficient approval, transfer normally.
-        if (IERC20(token).allowance(address(from), address(this)) >= amount) {
+        if (IERC20(token).allowance({owner: address(from), spender: address(this)}) >= amount) {
             return IERC20(token).safeTransferFrom({from: from, to: to, value: amount});
         }
 
@@ -1885,6 +1927,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         if (amount > type(uint160).max) revert JBMultiTerminal_OverflowAlert(amount, type(uint160).max);
 
         // Otherwise we attempt to use the PERMIT2 method.
+        // forge-lint: disable-next-line(unsafe-typecast)
         PERMIT2.transferFrom({from: from, to: to, amount: uint160(amount), token: token});
     }
 

package/src/JBPermissions.sol

@@ -154,6 +154,8 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
         uint256 operatorAccountWildcardProjectPermissions =
             includeWildcardProjectId ? permissionsOf[operator][account][WILDCARD_PROJECT_ID] : 0;
 
+        // Returns true for empty permission arrays by design (vacuous truth). An empty set of
+        // required permissions is trivially satisfied. Callers should validate non-empty permission arrays if needed.
         for (uint256 i; i < permissionIds.length; i++) {
             // Set the permission being iterated on.
             uint256 permissionId = permissionIds[i];
@@ -250,6 +252,7 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
             uint256 permissionId = permissionIds[i];
 
             // Turn on the bit at the ID.
+            // forge-lint: disable-next-line(incorrect-shift)
             packed |= 1 << permissionId;
         }
     }

package/src/JBPrices.sol

@@ -15,8 +15,10 @@ import {IJBProjects} from "./interfaces/IJBProjects.sol";
 
 /// @notice Manages and normalizes price feeds. Price feeds are contracts which return the "pricing currency" cost of 1
 /// "unit currency".
-/// @dev Price feeds are immutable once set and cannot be replaced or removed. If a price feed needs to be changed,
-/// a new JBPrices contract must be deployed and projects must migrate to use it.
+/// @dev Price feeds are immutable once set and cannot be replaced or removed. This prevents oracle manipulation via
+/// admin-key attacks, but means a misconfigured or failing feed will cause operations using that currency pair to
+/// revert (DoS, not fund loss). Select feeds carefully — recovery requires deploying a new JBPrices contract and
+/// migrating projects.
 contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBPrices {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -134,6 +136,10 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
                     : priceFeedFor[projectId][unitCurrency][pricingCurrency]);
         }
 
+        // Price feed immutability is by design to prevent admin-key attacks on price oracles.
+        // If a feed fails, operations using that currency pair revert (DoS but not fund loss). Projects can use
+        // alternative currency pairs. A default feed for a currency pair prevents per-project overrides to ensure
+        // price consistency; projects should use unused currency IDs for custom pricing.
         // Store the feed.
         priceFeedFor[projectId][pricingCurrency][unitCurrency] = feed;
 

package/src/JBProjects.sol

@@ -74,7 +74,7 @@ contract JBProjects is ERC721, ERC2771Context, Ownable, IJBProjects {
         emit Create({projectId: projectId, owner: owner, caller: _msgSender()});
 
         // Mint the project.
-        _safeMint(owner, projectId);
+        _safeMint({to: owner, tokenId: projectId});
     }
 
     //*********************************************************************//

package/src/JBRulesets.sol

@@ -247,6 +247,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // Calculate the weight cut multiple.
         uint168 weightCutMultiple;
         unchecked {
+            // forge-lint: disable-next-line(unsafe-typecast)
             weightCutMultiple = uint168(startDistance / targetRuleset.duration);
         }
 
@@ -352,6 +353,9 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
     /// @notice The ruleset that is currently active for the specified project.
     /// @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.
     /// @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) {
@@ -955,26 +959,34 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // slither-disable-next-line incorrect-equality
         if (rulesetId == 0) return ruleset;
 
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.id = uint48(rulesetId);
 
         uint256 packedIntrinsicProperties = _packedIntrinsicPropertiesOf[projectId][rulesetId];
 
         // `weight` in bits 0-111 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.weight = uint112(packedIntrinsicProperties);
         // `basedOnId` in bits 112-159 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.basedOnId = uint48(packedIntrinsicProperties >> 112);
         // `start` in bits 160-207 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.start = uint48(packedIntrinsicProperties >> 160);
         // `cycleNumber` in bits 208-255 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.cycleNumber = uint48(packedIntrinsicProperties >> 208);
 
         uint256 packedUserProperties = _packedUserPropertiesOf[projectId][rulesetId];
 
         // approval hook in bits 0-159 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.approvalHook = IJBRulesetApprovalHook(address(uint160(packedUserProperties)));
         // `duration` in bits 160-191 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.duration = uint32(packedUserProperties >> 160);
         // weight cut percent in bits 192-223 bits.
+        // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.weightCutPercent = uint32(packedUserProperties >> 192);
 
         ruleset.metadata = _metadataOf[projectId][rulesetId];
@@ -1021,9 +1033,11 @@ contract JBRulesets is JBControlled, IJBRulesets {
         });
 
         return JBRuleset({
+            // forge-lint: disable-next-line(unsafe-typecast)
             cycleNumber: uint48(rulesetCycleNumber),
             id: baseRuleset.id,
             basedOnId: baseRuleset.basedOnId,
+            // forge-lint: disable-next-line(unsafe-typecast)
             start: uint48(start),
             duration: baseRuleset.duration,
             weight: uint112(

package/src/JBSplits.sol

@@ -77,8 +77,9 @@ contract JBSplits is JBControlled, IJBSplits {
 
     /// @notice Sets a project's split groups.
     /// @dev Only a project's controller can set its splits, unless the first 160 bits of the group's ID match
-    /// `msg.sender`, in which case the caller can set its own splits. The remaining upper 96 bits are free for the
-    /// caller to use as sub-categorization.
+    /// `msg.sender` AND the upper 96 bits are non-zero, in which case the caller can set its own splits.
+    /// GroupIds with zero upper 96 bits (i.e. bare addresses) are reserved for protocol use (e.g. terminal
+    /// payout groups keyed by token address) and always require controller authorization.
     /// @dev The new split groups must include any currently set splits that are locked.
     /// @param projectId The ID of the project to set the split groups of.
     /// @param rulesetId The ID of the ruleset the split groups should be active in. Send
@@ -101,9 +102,12 @@ contract JBSplits is JBControlled, IJBSplits {
             // Get a reference to the grouped split being iterated on.
             JBSplitGroup memory splitGroup = splitGroups[i];
 
-            // Allow contracts to set splits in their own namespace (first 160 bits of groupId == msg.sender).
-            // Otherwise, require controller (checked once).
-            if (address(uint160(splitGroup.groupId)) != msg.sender && !controllerChecked) {
+            // Self-auth: lower 160 bits must match msg.sender AND upper 96 bits must be non-zero.
+            // GroupIds with zero upper bits are reserved for protocol use (e.g. terminal payout groups)
+            // and always require controller authorization to prevent token contracts from hijacking payouts.
+            bool isSelfManaged = splitGroup.groupId >> 160 != 0 && address(uint160(splitGroup.groupId)) == msg.sender;
+
+            if (!isSelfManaged && !controllerChecked) {
                 _onlyControllerOf(projectId);
                 controllerChecked = true;
             }
@@ -271,10 +275,13 @@ contract JBSplits is JBControlled, IJBSplits {
             JBSplit memory split;
 
             // `percent` in bits 0-31.
+            // forge-lint: disable-next-line(unsafe-typecast)
             split.percent = uint32(packedSplitPart1);
             // `projectId` in bits 32-95.
+            // forge-lint: disable-next-line(unsafe-typecast)
             split.projectId = uint64(packedSplitPart1 >> 32);
             // `beneficiary` in bits 96-255.
+            // forge-lint: disable-next-line(unsafe-typecast)
             split.beneficiary = payable(address(uint160(packedSplitPart1 >> 96)));
 
             // Get a reference to the second part of the split's packed data.
@@ -285,8 +292,10 @@ contract JBSplits is JBControlled, IJBSplits {
                 // `preferAddToBalance` in bit 0.
                 split.preferAddToBalance = packedSplitPart2 & 1 == 1;
                 // `lockedUntil` in bits 1-48.
+                // forge-lint: disable-next-line(unsafe-typecast)
                 split.lockedUntil = uint48(packedSplitPart2 >> 1);
                 // `hook` in bits 49-208.
+                // forge-lint: disable-next-line(unsafe-typecast)
                 split.hook = IJBSplitHook(address(uint160(packedSplitPart2 >> 49)));
             }
 

package/src/JBTerminalStore.sol

@@ -156,6 +156,8 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @param accountingContext The accounting context of the token being reclaimed by the cash out.
     /// @param balanceAccountingContexts The accounting contexts of the tokens whose balances should contribute to the
     /// surplus being reclaimed from.
+    /// @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).
     /// @param metadata Bytes to send to the data hook, if the project's current ruleset specifies one.
     /// @return ruleset The ruleset during the cash out was made during, as a `JBRuleset` struct. This ruleset will
     /// have a cash out tax rate provided by the cash out hook if applicable.
@@ -170,6 +172,7 @@ contract JBTerminalStore is IJBTerminalStore {
         uint256 cashOutCount,
         JBAccountingContext calldata accountingContext,
         JBAccountingContext[] calldata balanceAccountingContexts,
+        bool beneficiaryIsFeeless,
         bytes memory metadata
     )
         external
@@ -184,10 +187,9 @@ contract JBTerminalStore is IJBTerminalStore {
         // Get a reference to the project's current ruleset.
         ruleset = RULESETS.currentOf(projectId);
 
-        // Get the current surplus amount.
-        // Use the local surplus if the ruleset specifies that it should be used. Otherwise, use the project's total
-        // surplus across all of its terminals.
-        uint256 currentSurplus = ruleset.useTotalSurplusForCashOuts()
+        // Store the current surplus in `reclaimAmount` temporarily to avoid allocating a separate local variable
+        // (saves one stack slot, which is needed to fit the 7th parameter without hitting stack-too-deep).
+        reclaimAmount = ruleset.useTotalSurplusForCashOuts()
             ? JBSurplus.currentSurplusOf({
                 projectId: projectId,
                 terminals: DIRECTORY.terminalsOf(projectId),
@@ -204,54 +206,59 @@ contract JBTerminalStore is IJBTerminalStore {
                 targetCurrency: accountingContext.currency
             });
 
-        // Get the total number of outstanding project tokens.
-        uint256 totalSupply =
-            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);
-
-        // SECURITY NOTE: The data hook has absolute control over cash-out economics.
-        // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
-        // completely overriding the terminal's bonding curve math. For example, setting
-        // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
-        // Project owners MUST audit their data hooks with the same rigor as the terminal.
-
-        // 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)) {
-            // Create the cash out context that'll be sent to the data hook.
-            JBBeforeCashOutRecordedContext memory context = JBBeforeCashOutRecordedContext({
-                terminal: msg.sender,
-                holder: holder,
-                projectId: projectId,
-                rulesetId: ruleset.id,
-                cashOutCount: cashOutCount,
-                totalSupply: totalSupply,
-                surplus: JBTokenAmount({
+        // Scoped to keep `totalSupply` and `context` off the outer stack.
+        {
+            // Get the total number of outstanding project tokens.
+            uint256 totalSupply = 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);
+
+            // SECURITY NOTE: The data hook has absolute control over cash-out economics.
+            // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
+            // completely overriding the terminal's bonding curve math. For example, setting
+            // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
+            // Project owners MUST audit their data hooks with the same rigor as the terminal.
+
+            // 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 to avoid stack-too-deep
+                // (the struct has 11 fields — a struct literal would require all values on the stack at once).
+                JBBeforeCashOutRecordedContext memory context;
+                context.terminal = msg.sender;
+                context.holder = holder;
+                context.projectId = projectId;
+                context.rulesetId = ruleset.id;
+                context.cashOutCount = cashOutCount;
+                context.totalSupply = totalSupply;
+                context.surplus = JBTokenAmount({
                     token: accountingContext.token,
-                    value: currentSurplus,
+                    value: reclaimAmount, // reclaimAmount temporarily holds the current surplus.
                     decimals: accountingContext.decimals,
                     currency: accountingContext.currency
-                }),
-                useTotalSurplus: ruleset.useTotalSurplusForCashOuts(),
-                cashOutTaxRate: ruleset.cashOutTaxRate(),
-                metadata: metadata
-            });
+                });
+                context.useTotalSurplus = ruleset.useTotalSurplusForCashOuts();
+                context.cashOutTaxRate = ruleset.cashOutTaxRate();
+                context.beneficiaryIsFeeless = beneficiaryIsFeeless;
+                context.metadata = metadata;
 
-            (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
-                IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
-        } else {
-            cashOutTaxRate = ruleset.cashOutTaxRate();
-        }
+                (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
+                    IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
+            } else {
+                cashOutTaxRate = ruleset.cashOutTaxRate();
+            }
 
-        if (currentSurplus != 0) {
-            // Calculate reclaim amount using the current surplus amount.
-            reclaimAmount = JBCashOuts.cashOutFrom({
-                surplus: currentSurplus,
-                cashOutCount: cashOutCount,
-                totalSupply: totalSupply,
-                cashOutTaxRate: cashOutTaxRate
-            });
+            // Calculate the reclaim amount. `reclaimAmount` currently holds the surplus — overwrite it with the
+            // result.
+            if (reclaimAmount != 0) {
+                reclaimAmount = JBCashOuts.cashOutFrom({
+                    surplus: reclaimAmount,
+                    cashOutCount: cashOutCount,
+                    totalSupply: totalSupply,
+                    cashOutTaxRate: cashOutTaxRate
+                });
+            }
         }
 
         // Keep a reference to the amount that should be added to the project's balance.
@@ -868,6 +875,7 @@ contract JBTerminalStore is IJBTerminalStore {
                         terminal
                     ][projectId][accountingContext.token][ruleset.cycleNumber][payoutLimit.currency];
                 if (remaining > type(uint224).max) revert JBTerminalStore_Uint224Overflow(remaining);
+                // forge-lint: disable-next-line(unsafe-typecast)
                 payoutLimit.amount = uint224(remaining);
             }
 
@@ -877,6 +885,7 @@ contract JBTerminalStore is IJBTerminalStore {
                     value: payoutLimit.amount, decimals: accountingContext.decimals, targetDecimals: targetDecimals
                 });
                 if (adjusted > type(uint224).max) revert JBTerminalStore_Uint224Overflow(adjusted);
+                // forge-lint: disable-next-line(unsafe-typecast)
                 payoutLimit.amount = uint224(adjusted);
             }
 
@@ -894,6 +903,7 @@ contract JBTerminalStore is IJBTerminalStore {
                     })
                 );
                 if (converted > type(uint224).max) revert JBTerminalStore_Uint224Overflow(converted);
+                // forge-lint: disable-next-line(unsafe-typecast)
                 payoutLimit.amount = uint224(converted);
             }
 

package/src/JBTokens.sol

@@ -128,7 +128,7 @@ contract JBTokens is JBControlled, IJBTokens {
         });
 
         // Burn the tokens.
-        if (tokensToBurn > 0) token.burn(holder, tokensToBurn);
+        if (tokensToBurn > 0) token.burn({account: holder, amount: tokensToBurn});
     }
 
     /// @notice Redeem credits to claim tokens into a holder's wallet.
@@ -177,7 +177,7 @@ contract JBTokens is JBControlled, IJBTokens {
         });
 
         // Mint the equivalent amount of the project's token for the holder.
-        token.mint(beneficiary, count);
+        token.mint({account: beneficiary, amount: count});
     }
 
     /// @notice Deploys an ERC-20 token for a project. It will be used when claiming tokens.
@@ -211,7 +211,11 @@ contract JBTokens is JBControlled, IJBTokens {
 
         token = salt == bytes32(0)
             ? IJBToken(Clones.clone(address(TOKEN)))
-            : IJBToken(Clones.cloneDeterministic(address(TOKEN), keccak256(abi.encode(msg.sender, salt))));
+            : IJBToken(
+                Clones.cloneDeterministic({
+                    implementation: address(TOKEN), salt: keccak256(abi.encode(msg.sender, salt))
+                })
+            );
 
         // Store the token contract.
         tokenOf[projectId] = token;
@@ -257,7 +261,7 @@ contract JBTokens is JBControlled, IJBTokens {
         if (tokensWereClaimed) {
             // If tokens should be claimed, mint tokens into the holder's wallet.
             // slither-disable-next-line reentrancy-events
-            token.mint(holder, count);
+            token.mint({account: holder, amount: count});
         } else {
             // Otherwise, add the tokens to their credits and the credit supply.
             creditBalanceOf[holder][projectId] += count;
@@ -271,6 +275,9 @@ contract JBTokens is JBControlled, IJBTokens {
 
     /// @notice Set a project's token if not already set.
     /// @dev Only a project's controller can set its token.
+    /// @dev If the provided ERC-20 has a pre-existing supply (minted outside this contract), that supply will be
+    /// included in `totalSupplyOf` and will dilute cash-out calculations for all token holders. Project owners are
+    /// responsible for ensuring the token's supply is appropriate before calling this function.
     /// @param projectId The ID of the project to set the token of.
     /// @param token The new token's address.
     function setTokenFor(uint256 projectId, IJBToken token) external override onlyControllerOf(projectId) {
@@ -298,6 +305,38 @@ contract JBTokens is JBControlled, IJBTokens {
         emit SetToken({projectId: projectId, token: token, caller: msg.sender});
     }
 
+    /// @notice Sets the name and symbol of a project's token.
+    /// @dev Only a project's controller can set the token's name and symbol.
+    /// @param projectId The ID of the project whose token is being updated.
+    /// @param name The new name.
+    /// @param symbol The new symbol.
+    function setTokenMetadataFor(
+        uint256 projectId,
+        string calldata name,
+        string calldata symbol
+    )
+        external
+        override
+        onlyControllerOf(projectId)
+    {
+        // Get a reference to the project's current token.
+        IJBToken token = tokenOf[projectId];
+
+        // The project must have a token contract attached.
+        if (token == IJBToken(address(0))) revert JBTokens_TokenNotFound();
+
+        // There must be a name.
+        if (bytes(name).length == 0) revert JBTokens_EmptyName();
+
+        // There must be a symbol.
+        if (bytes(symbol).length == 0) revert JBTokens_EmptySymbol();
+
+        emit SetTokenMetadata({projectId: projectId, name: name, symbol: symbol, caller: msg.sender});
+
+        // Set the name and symbol.
+        token.setMetadata({name: name, symbol: symbol});
+    }
+
     /// @notice Allows a holder to transfer credits to another account.
     /// @dev Only a project's controller can transfer credits for that project.
     /// @param holder The address to transfer credits from.

package/src/interfaces/IJBController.sol

@@ -345,6 +345,12 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     /// @param token The new token's address.
     function setTokenFor(uint256 projectId, IJBToken token) external;
 
+    /// @notice Sets the name and symbol of a project's token.
+    /// @param projectId The ID of the project whose token is being updated.
+    /// @param name The new name.
+    /// @param symbol The new symbol.
+    function setTokenMetadataOf(uint256 projectId, string calldata name, string calldata symbol) external;
+
     /// @notice Transfers credits from one address to another.
     /// @param holder The address to transfer credits from.
     /// @param projectId The ID of the project whose credits are being transferred.

package/src/interfaces/IJBPermitTerminal.sol

@@ -14,5 +14,6 @@ interface IJBPermitTerminal is IJBTerminal {
     event Permit2AllowanceFailed(address indexed token, address indexed owner, bytes reason);
 
     /// @notice The Permit2 contract used for token approvals.
+    // forge-lint: disable-next-line(mixed-case-function)
     function PERMIT2() external returns (IPermit2);
 }