@bananapus/core-v6 0.0.55 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.55",
+  "version": "0.0.58",
   "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.23",
+    "@bananapus/permission-ids-v6": "^0.0.26",
     "@chainlink/contracts": "1.5.0",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",

package/src/JBController.sol

@@ -67,6 +67,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     error JBController_NoReservedTokens(uint256 projectId);
     error JBController_OnlyDirectory(address sender, IJBDirectory directory);
     error JBController_PendingReservedTokens(uint256 pendingReservedTokenBalance);
+    error JBController_ReservedTokenSplitProjectSameAsOwner(uint256 projectId);
     error JBController_RulesetsAlreadyLaunched(uint256 projectId);
     error JBController_RulesetsArrayEmpty(uint256 projectId, uint256 rulesetConfigurationCount);
     error JBController_RulesetSetTokenNotAllowed(uint256 projectId);
@@ -382,8 +383,10 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     /// @notice Creates a new Juicebox project in one transaction — mints the project NFT, queues initial rulesets,
     /// and
     /// configures terminals. This is the primary entry point for launching a project.
-    /// @dev Anyone can call this on behalf of any owner. Each sub-operation (mint, queue, configure) can also be done
-    /// individually if needed.
+    /// @dev Anyone can call this on behalf of any owner. This is a launch convenience, not owner authorization proof:
+    /// frontends and operators must use the transaction sender, an explicit owner signature, or their own deployment
+    /// flow to decide whether the owner intentionally launched a configuration. Each sub-operation (mint, queue,
+    /// configure) can also be done individually if needed.
     /// @param owner The project's owner. The project ERC-721 will be minted to this address.
     /// @param projectUri The project's metadata URI. This is typically an IPFS hash, optionally with the `ipfs://`
     /// prefix. This can be updated by the project's owner.
@@ -1117,7 +1120,18 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                     // sender.
                     address beneficiary = split.beneficiary != address(0) ? split.beneficiary : messageSender;
 
+                    // Reserved token splits with no project ID mint directly to the beneficiary. A non-zero project ID
+                    // takes the "pay another project" path, which treats the reserved tokens as revenue for the
+                    // destination project and can mint another batch of tokens according to its ruleset.
                     if (split.projectId != 0) {
+                        if (split.projectId == projectId) {
+                            // The source project is not a valid destination for the terminal-payment path.
+                            // `sendReservedTokensToSplitsOf` clears the pending reserve balance before this helper
+                            // runs. Paying those freshly minted reserves into the same project's terminal would book
+                            // them as new revenue, mint another batch of tokens, and start the reserve cycle again.
+                            revert JBController_ReservedTokenSplitProjectSameAsOwner({projectId: projectId});
+                        }
+
                         // Get a reference to the receiving project's primary payment terminal for the token.
                         IJBTerminal terminal = token == IJBToken(address(0))
                             ? IJBTerminal(address(0))

package/src/JBFeelessAddresses.sol

@@ -87,20 +87,26 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Returns whether the specified address is feeless for a specific project, considering the wildcard
-    /// (projectId 0) feeless status, the project-specific feeless status, and the feeless hook (if set).
-    /// @dev The hook is invoked via try/catch — a reverting or out-of-gas hook is treated as `false` so it cannot
-    /// brick the fee path in terminals.
+    /// @notice Returns whether the specified address is feeless for a specific project, providing the outer caller
+    /// of the fee-bearing operation so hooks can scope grants by who initiated the action.
+    /// @dev The static admin-set mappings are caller-agnostic and always apply. The hook (if set) receives `caller`
+    /// (typically the terminal's `_msgSender()`) and may use it to narrow its grant — e.g. grant an ecosystem
+    /// router feeless cash-outs only when the router itself is the caller, not when it appears as a split recipient
+    /// of someone else's payout. Hook is invoked via try/catch — a reverting hook is treated as `false`.
     /// @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, for the project, or per the hook).
-    function isFeelessFor(address addr, uint256 projectId) external view override returns (bool) {
+    /// @param caller The outer caller (typically the terminal's `_msgSender()`). Pass `address(0)` for lookups
+    /// without caller context.
+    /// @return A flag indicating whether the address is feeless.
+    function isFeelessFor(address addr, uint256 projectId, address caller) external view override returns (bool) {
+        // Static grants are administrative and do not depend on who triggered the fee-bearing operation.
         if (_isFeelessFor[0][addr] || _isFeelessFor[projectId][addr]) return true;
 
         IJBFeelessHook hook = feelessHook;
         if (address(hook) == address(0)) return false;
 
-        try hook.isFeeless({projectId: projectId, addr: addr}) returns (bool result) {
+        // Hook grants are optional and caller-aware; a reverting hook is treated as "not feeless".
+        try hook.isFeeless({projectId: projectId, addr: addr, caller: caller}) returns (bool result) {
             return result;
         } catch {
             return false;

package/src/JBFundAccessLimits.sol

@@ -18,6 +18,9 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    error JBFundAccessLimits_DuplicateFundAccessLimitGroup(
+        uint256 projectId, uint256 rulesetId, uint256 groupIndex, address terminal, address token
+    );
     error JBFundAccessLimits_InvalidPayoutLimitCurrencyOrdering(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, uint256 limitIndex
     );
@@ -95,6 +98,28 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
             // Set the limits being iterated on.
             JBFundAccessLimitGroup calldata fundAccessLimitGroup = fundAccessLimitGroups[i];
 
+            // Each terminal/token pair should have exactly one group. The per-group currency ordering checks below
+            // prevent duplicate currencies inside one group; this prevents splitting a duplicate currency across two
+            // groups for the same terminal/token pair.
+            for (uint256 j; j < i;) {
+                JBFundAccessLimitGroup calldata previousGroup = fundAccessLimitGroups[j];
+                if (
+                    previousGroup.terminal == fundAccessLimitGroup.terminal
+                        && previousGroup.token == fundAccessLimitGroup.token
+                ) {
+                    revert JBFundAccessLimits_DuplicateFundAccessLimitGroup({
+                        projectId: projectId,
+                        rulesetId: rulesetId,
+                        groupIndex: i,
+                        terminal: fundAccessLimitGroup.terminal,
+                        token: fundAccessLimitGroup.token
+                    });
+                }
+                unchecked {
+                    ++j;
+                }
+            }
+
             // Keep a reference to the number of payout limits.
             uint256 numberOfPayoutLimits = fundAccessLimitGroup.payoutLimits.length;
 

package/src/JBMultiTerminal.sol

@@ -64,14 +64,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     //*********************************************************************//
 
     error JBMultiTerminal_FeeTerminalNotFound(address token);
-    error JBMultiTerminal_MintNotAllowed(uint256 projectId, uint256 splitProjectId, address terminal);
+    error JBMultiTerminal_MintNotAllowed(uint256 projectId, address terminal);
     error JBMultiTerminal_NoMsgValueAllowed(uint256 value);
     error JBMultiTerminal_OverflowAlert(uint256 value, uint256 limit);
     error JBMultiTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
     error JBMultiTerminal_RecipientProjectTerminalNotFound(uint256 projectId, address token);
+    error JBMultiTerminal_ReentrantTokenTransfer(address token);
     error JBMultiTerminal_SplitHookInvalid(IJBSplitHook hook);
-    error JBMultiTerminal_TerminalTokensIncompatible(uint256 projectId, address token, IJBTerminal terminal);
     error JBMultiTerminal_TemporaryAllowanceNotConsumed(address token, address spender, uint256 allowance);
+    error JBMultiTerminal_TerminalMigrationToSelf(uint256 projectId, address token);
+    error JBMultiTerminal_TerminalTokensIncompatible(uint256 projectId, address token, IJBTerminal terminal);
     error JBMultiTerminal_TokenNotAccepted(address token);
     error JBMultiTerminal_UnderMin(uint256 value, uint256 min);
 
@@ -140,6 +142,18 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @custom:param token The token the fees are held in.
     mapping(uint256 projectId => mapping(address token => uint256)) internal _nextHeldFeeIndexOf;
 
+    //*********************************************************************//
+    // ------------------- transient stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice Whether this terminal is currently measuring an incoming ERC-20 balance delta.
+    bool transient _acceptingToken;
+
+    /// @notice Source project ID for the same-terminal split pay currently being recorded.
+    /// @dev After `_pay` consumes and clears this value, `_fulfillPayHookSpecificationsFor` reuses the slot to return
+    /// the fee basis to `executePayout`.
+    uint256 transient _internalSplitPayProjectId;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -326,6 +340,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             }
 
             if (!_isFeeless({addr: address(split.hook), projectId: projectId})) {
+                // Split hooks pull funds out of this terminal, so non-feeless hooks receive the net amount after
+                // the standard terminal fee.
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -347,6 +363,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         } else if (split.projectId != 0) {
             // Get a reference to the terminal being used.
             IJBTerminal terminal = _primaryTerminalOf({projectId: split.projectId, token: token});
+            bool isThisTerminal = terminal == this;
 
             // The project must have a terminal to send funds to.
             if (terminal == IJBTerminal(address(0))) {
@@ -358,7 +375,9 @@ 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({addr: address(terminal), projectId: projectId})) {
+            if (!isThisTerminal && !_isFeeless({addr: address(terminal), projectId: projectId})) {
+                // Cross-terminal payouts leave this terminal's custody, so charge the standard terminal fee unless
+                // the recipient terminal is feeless.
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -383,17 +402,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             //     through `sendPayoutsOf` is never the right surface.
             // The try-catch in the split group lib catches this revert and restores the balance.
             if (split.projectId == projectId) {
-                revert JBMultiTerminal_MintNotAllowed({
-                    projectId: projectId, splitProjectId: split.projectId, terminal: address(terminal)
-                });
-            }
-
-            // 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. Same-project
-            // splits would inflate this counter against the project's own future zero-tax cashouts
-            // but are already excluded by the self-reference revert above.
-            if (terminal == this) {
-                _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
+                revert JBMultiTerminal_MintNotAllowed({projectId: projectId, terminal: address(terminal)});
             }
 
             // Send the `projectId` in the metadata as a referral.
@@ -408,10 +417,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     amount: netPayoutAmount,
                     metadata: metadata
                 });
+
+                // Same-terminal adds never invoke destination pay hooks, so the full amount remains in the
+                // destination project's balance and must be fee-liable on its later zero-tax cashout.
+                if (isThisTerminal) _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
             } else {
                 // Keep a reference to the beneficiary of the payment.
                 address beneficiary = split.beneficiary != address(0) ? split.beneficiary : originalMessageSender;
 
+                // Mark same-terminal split pays so `_pay` can fee pay-hook forwards inline and track only retained
+                // value as fee-free surplus.
+                if (isThisTerminal) {
+                    _internalSplitPayProjectId = projectId;
+                }
+
                 _efficientPay({
                     terminal: terminal,
                     projectId: split.projectId,
@@ -421,12 +440,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     metadata: metadata
                 });
 
-                // Cap fee-free surplus at remaining balance.
-                // Why: _feeFreeSurplusOf was incremented by the full netPayoutAmount above, but if the
-                // destination project's data hook forwarded part of the payment to pay hooks, the store
-                // only recorded a partial balance increase. Without this cap, _feeFreeSurplusOf can exceed
-                // STORE.balanceOf, causing users to be overcharged fees on zero-tax cashouts.
-                _capFeeFreeSurplus({projectId: split.projectId, token: token});
+                if (isThisTerminal) {
+                    feeEligibleAmount += _internalSplitPayProjectId;
+                    delete _internalSplitPayProjectId;
+                }
             }
         } else {
             // If there's a beneficiary, send the funds directly to the beneficiary.
@@ -437,6 +454,8 @@ 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({addr: recipient, projectId: projectId})) {
+                // Direct payouts leave the terminal, so non-feeless recipients receive the net amount after the
+                // standard terminal fee.
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -521,6 +540,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.MIGRATE_TERMINAL
         });
 
+        // Migrating to the same terminal would zero this terminal's store balance and then try to re-add it through
+        // the external terminal interface. ERC-20 self-transfers produce no balance delta, leaving funds stranded.
+        if (address(to) == address(this)) {
+            revert JBMultiTerminal_TerminalMigrationToSelf({projectId: projectId, token: token});
+        }
+
         // The terminal being migrated to must accept the same token as this terminal.
         if (to.accountingContextForTokenOf({projectId: projectId, token: token}).currency == 0) {
             revert JBMultiTerminal_TerminalTokensIncompatible({projectId: projectId, token: token, terminal: to});
@@ -545,6 +570,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // This also settles any fee-free surplus liability that would otherwise be lost on the new terminal.
             uint256 feeAmount;
             if (!_isFeeless({addr: address(to), projectId: projectId}) && projectId != _FEE_BENEFICIARY_PROJECT_ID) {
+                // Fee processing failures never block migration. If the fee route is broken, `_processFee` credits
+                // the fee amount back to this source terminal and emits `FeeReverted`; the post-fee amount still
+                // migrates so project funds are not trapped behind project #1 routing issues.
                 feeAmount = _takeFeeFrom({
                     projectId: projectId,
                     token: token,
@@ -668,7 +696,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             delete _heldFeesOf[projectId][token][currentIndex];
             _nextHeldFeeIndexOf[projectId][token] = currentIndex + 1;
 
-            // Process the fee.
+            // Process the standard fee on the original gross amount recorded when the held fee was created.
             _processFee({
                 projectId: projectId,
                 token: token,
@@ -1042,11 +1070,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Get a reference to the balance before receiving tokens.
         uint256 balanceBefore = _balanceOf(token);
 
+        // Prevent callback-capable tokens from nesting another incoming ERC-20 transfer inside this balance-delta
+        // measurement.
+        if (_acceptingToken) revert JBMultiTerminal_ReentrantTokenTransfer(token);
+        _acceptingToken = true;
+
         // Transfer tokens to this terminal from the msg sender.
         _transferFrom({from: _msgSender(), to: payable(address(this)), token: token, amount: amount});
 
         // The amount should reflect the change in balance.
-        return _balanceOf(token) - balanceBefore;
+        uint256 acceptedAmount = _balanceOf(token) - balanceBefore;
+
+        _acceptingToken = false;
+
+        return acceptedAmount;
     }
 
     /// @notice Adds funds to a project's balance without minting tokens.
@@ -1360,6 +1397,34 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
+    /// @notice Emits a `Pay` event. Extracted from `_pay` so the 9-field event payload gets its own stack frame —
+    /// inlining the emit into `_pay` overflows the non-IR build's stack budget.
+    function _emitPay(
+        JBRuleset memory ruleset,
+        uint256 projectId,
+        address payer,
+        address beneficiary,
+        uint256 amount,
+        uint256 newlyIssuedTokenCount,
+        string memory memo,
+        bytes memory metadata
+    )
+        internal
+    {
+        emit Pay({
+            rulesetId: ruleset.id,
+            rulesetCycleNumber: ruleset.cycleNumber,
+            projectId: projectId,
+            payer: payer,
+            beneficiary: beneficiary,
+            amount: amount,
+            newlyIssuedTokenCount: newlyIssuedTokenCount,
+            memo: memo,
+            metadata: metadata,
+            caller: _msgSender()
+        });
+    }
+
     /// @notice Fund a project on another terminal by granting a temporary pull allowance for this call only.
     /// @param terminal The recipient terminal.
     /// @param projectId The ID of the project to fund.
@@ -1447,7 +1512,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 continue;
             }
 
-            // Get the fee for the specified amount.
+            // Cash-out hooks receive the net amount after the standard fee unless the hook is feeless.
             uint256 specificationAmountFee = _isFeeless({addr: address(specification.hook), projectId: projectId})
                 ? 0
                 : _feeAmountFrom(specification.amount);
@@ -1503,6 +1568,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param beneficiary The address which will receive any tokens that the payment yields.
     /// @param newlyIssuedTokenCount The number of tokens issued and sent to the beneficiary.
     /// @param metadata Bytes to send along to the emitted event and pay hooks as applicable.
+    /// @param internalSplitPayProjectId The source project when this payment came from a same-terminal split.
     function _fulfillPayHookSpecificationsFor(
         uint256 projectId,
         JBPayHookSpecification[] memory specifications,
@@ -1511,10 +1577,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         JBRuleset memory ruleset,
         address beneficiary,
         uint256 newlyIssuedTokenCount,
-        bytes memory metadata
+        bytes memory metadata,
+        uint256 internalSplitPayProjectId
     )
         internal
     {
+        uint256 amountEligibleForFees;
+
         // Keep a reference to payment context for the pay hooks.
         JBAfterPayRecordedContext memory context = JBAfterPayRecordedContext({
             payer: payer,
@@ -1542,9 +1611,25 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 continue;
             }
 
+            uint256 specificationAmount = specification.amount;
+
+            if (
+                internalSplitPayProjectId != 0
+                    && !_isFeeless({addr: address(specification.hook), projectId: internalSplitPayProjectId})
+            ) {
+                // Same-terminal split pays defer source-side fees until the destination data hook is known. Net
+                // non-feeless hook forwards here so they match ordinary payout semantics before funds leave.
+                // Keep the fee basis local until every hook returns. Writing the transient accumulator before the
+                // hook call would let a reentrant payout overwrite the outer split's pending fee basis.
+                unchecked {
+                    amountEligibleForFees += specificationAmount;
+                    specificationAmount -= _feeAmountFrom(specificationAmount);
+                }
+            }
+
             // Pass the correct token `forwardedAmount` to the hook.
             context.forwardedAmount = JBTokenAmount({
-                value: specification.amount,
+                value: specificationAmount,
                 token: tokenAmount.token,
                 decimals: tokenAmount.decimals,
                 currency: tokenAmount.currency
@@ -1556,7 +1641,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Trigger any inherited pre-transfer logic.
             // Keep a reference to the amount that'll be paid as a `msg.value`.
             uint256 payValue = _beforeTransferTo({
-                to: address(specification.hook), token: tokenAmount.token, amount: specification.amount
+                to: address(specification.hook), token: tokenAmount.token, amount: specificationAmount
             });
 
             // Fulfill the specification.
@@ -1568,13 +1653,17 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             emit HookAfterRecordPay({
                 hook: specification.hook,
                 context: context,
-                specificationAmount: specification.amount,
+                specificationAmount: specificationAmount,
                 caller: _msgSender()
             });
             unchecked {
                 ++i;
             }
         }
+
+        // `_pay` consumed and cleared the source project ID before calling hooks, so the transient slot can now carry
+        // the hook-derived fee basis back to `executePayout`. Publish it only after all untrusted hook calls return.
+        _internalSplitPayProjectId = amountEligibleForFees;
     }
 
     /// @notice Internal implementation of payment logic. Records the payment in the store, mints tokens via the
@@ -1600,6 +1689,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     )
         internal
     {
+        // Same-terminal split pays are the only inbound pays whose source-side fee was intentionally deferred. Cache
+        // and clear the transient source project before untrusted data/pay hooks can reenter ordinary pay flows.
+        uint256 internalSplitPayProjectId = _internalSplitPayProjectId;
+        if (internalSplitPayProjectId != 0) delete _internalSplitPayProjectId;
+
         // Keep a reference to the token amount to forward to the store.
         JBTokenAmount memory tokenAmount = _tokenAmountOf({projectId: projectId, token: token, value: amount});
 
@@ -1611,6 +1705,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             payer: payer, amount: tokenAmount, projectId: projectId, beneficiary: beneficiary, metadata: metadata
         });
 
+        // Only the value retained in the destination balance needs later cashout fee recovery. Non-feeless pay-hook
+        // forwards pay their source-equivalent fee inline before leaving the project.
+        if (internalSplitPayProjectId != 0) {
+            uint256 feeFreeAmount = tokenAmount.value;
+            for (uint256 i; i < hookSpecifications.length;) {
+                // The store already proved the hook-spec total does not exceed the pay amount.
+                unchecked {
+                    feeFreeAmount -= hookSpecifications[i].amount;
+                    ++i;
+                }
+            }
+            _feeFreeSurplusOf[projectId][token] += feeFreeAmount;
+        }
+
         // Keep a reference to the number of tokens issued for the beneficiary.
         uint256 newlyIssuedTokenCount;
 
@@ -1628,17 +1736,19 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         }
 
-        emit Pay({
-            rulesetId: ruleset.id,
-            rulesetCycleNumber: ruleset.cycleNumber,
+        // `_pay` already carries ~10 locals (ruleset, tokenCount, hookSpecifications, balanceDiff, tokenAmount,
+        // newlyIssuedTokenCount, internalSplitPayProjectId, feeFreeAmount, plus loop-local `i` and `hookAmount`).
+        // Inlining the 9-arg `emit Pay` here hits "Stack too deep" under the non-IR build, so the emit is extracted
+        // to `_emitPay` which gets its own stack frame.
+        _emitPay({
+            ruleset: ruleset,
             projectId: projectId,
             payer: payer,
             beneficiary: beneficiary,
             amount: amount,
             newlyIssuedTokenCount: newlyIssuedTokenCount,
             memo: memo,
-            metadata: metadata,
-            caller: _msgSender()
+            metadata: metadata
         });
 
         // If the data hook returned pay hook specifications, fulfill them.
@@ -1651,7 +1761,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 ruleset: ruleset,
                 beneficiary: beneficiary,
                 newlyIssuedTokenCount: newlyIssuedTokenCount,
-                metadata: metadata
+                metadata: metadata,
+                internalSplitPayProjectId: internalSplitPayProjectId
             });
         }
     }
@@ -1663,6 +1774,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param beneficiary The address which will receive any platform tokens minted.
     /// @param feeTerminal The terminal that'll receive the fee.
     /// @param wasHeld A flag indicating if the fee to process was held by this terminal.
+    /// @dev Fee-route failures are forgiven instead of reverted so project funds cannot be trapped by project #1
+    /// misconfiguration. The failed fee amount is credited back to the payer project's balance on this terminal.
     function _processFee(
         uint256 projectId,
         address token,
@@ -1685,10 +1798,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 caller: _msgSender()
             });
         } catch (bytes memory reason) {
-            // Fee processing failed — intentionally forgive the fee and return the amount to the project.
-            // The held-fee entry (if any) was already deleted by `processHeldFeesOf` before this call, so there is no
-            // retry path. This is by design: a broken or misconfigured fee route should not permanently lock project
-            // funds. The `FeeReverted` event makes this observable off-chain.
+            // Fee processing is fail-open for project liveness: a broken project #1 terminal or fee route must not
+            // trap payouts, cash outs, allowances, held-fee processing, or terminal migration. The fee is forgiven,
+            // credited back to the originating project on this terminal, and surfaced through `FeeReverted`.
             emit FeeReverted({
                 projectId: projectId,
                 token: token,
@@ -1741,6 +1853,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Held fees store the original gross amount that paid out before its fee was removed.
             JBFee memory heldFee = _heldFeesOf[projectId][token][i];
 
+            // Recompute the standard fee associated with the held gross amount.
             uint256 feeAmount = _feeAmountFrom(heldFee.amount);
 
             // This is the net amount that originally left the project after the held fee was removed.
@@ -1906,7 +2019,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// accounting context.
     /// @param beneficiary The address to mint the platform's project's tokens for.
     /// @param shouldHoldFees If fees should be tracked and held instead of processing them immediately.
-    /// @return feeAmount The amount of the fee taken.
+    /// @return feeAmount The fee withheld from the current outflow. If immediate fee processing fails, `_processFee`
+    /// credits this amount back to the payer project while the current outflow continues.
     function _takeFeeFrom(
         uint256 projectId,
         address token,
@@ -2112,11 +2226,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Returns a flag indicating if interacting with an address should not incur fees.
+    /// @dev Forwards `_msgSender()` (the outer caller of the terminal, with ERC-2771 forwarders unwrapped) to the
+    /// registry so an installed feeless hook can scope its grant by caller — e.g. recognise an ecosystem router
+    /// that wraps cash-out → pay and grant it fee-free cash-outs only when it itself is the caller.
     /// @param addr The address to check.
     /// @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});
+        return FEELESS_ADDRESSES.isFeelessFor({addr: addr, projectId: projectId, caller: _msgSender()});
     }
 
     /// @notice The calldata. Preferred to use over `msg.data`.

package/src/JBPrices.sol

@@ -27,6 +27,7 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
 
     error JBPrices_PriceFeedAlreadyExists(IJBPriceFeed feed);
     error JBPrices_PriceFeedNotFound(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency);
+    error JBPrices_ZeroPrice(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, IJBPriceFeed feed);
     error JBPrices_ZeroPricingCurrency(uint256 projectId, uint256 pricingCurrency);
     error JBPrices_ZeroUnitCurrency(uint256 projectId, uint256 unitCurrency);
 
@@ -191,8 +192,16 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
         // Get a reference to the price feed.
         IJBPriceFeed feed = priceFeedFor[projectId][pricingCurrency][unitCurrency];
 
-        // If the feed exists, return its price.
-        if (feed != IJBPriceFeed(address(0))) return feed.currentUnitPrice(decimals);
+        // If the feed exists, return its non-zero price.
+        if (feed != IJBPriceFeed(address(0))) {
+            uint256 price = feed.currentUnitPrice(decimals);
+            if (price == 0) {
+                revert JBPrices_ZeroPrice({
+                    projectId: projectId, pricingCurrency: pricingCurrency, unitCurrency: unitCurrency, feed: feed
+                });
+            }
+            return price;
+        }
 
         // Try getting the inverse feed.
         feed = priceFeedFor[projectId][unitCurrency][pricingCurrency];
@@ -202,7 +211,13 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
         // is in the range of ~1e9 to ~1e27 (for 18 decimals). Extreme prices outside this range may lose
         // significant precision due to fixed-point division truncation.
         if (feed != IJBPriceFeed(address(0))) {
-            return mulDiv({x: 10 ** decimals, y: 10 ** decimals, denominator: feed.currentUnitPrice(decimals)});
+            uint256 inversePrice = feed.currentUnitPrice(decimals);
+            if (inversePrice == 0) {
+                revert JBPrices_ZeroPrice({
+                    projectId: projectId, pricingCurrency: unitCurrency, unitCurrency: pricingCurrency, feed: feed
+                });
+            }
+            return mulDiv({x: 10 ** decimals, y: 10 ** decimals, denominator: inversePrice});
         }
 
         // Check for a default feed (project ID 0) if not found.

package/src/JBSplits.sol

@@ -173,14 +173,30 @@ contract JBSplits is JBControlled, IJBSplits {
         uint256 numberOfCurrentSplits = currentSplits.length;
 
         // Check to see if all locked splits are included in the array of splits which is being set.
+        // Duplicate locked splits must be preserved with the same multiplicity. Otherwise a table with two identical
+        // locked splits could be collapsed into one matching split and one unrelated split while each old split sees
+        // the same new match.
         for (uint256 i; i < numberOfCurrentSplits;) {
             // If not locked, continue.
-            if (
-                // forge-lint: disable-next-line(block-timestamp)
-                block.timestamp < currentSplits[i].lockedUntil
-                    && !_includesLockedSplits({splits: splits, lockedSplit: currentSplits[i]})
-            ) {
-                revert JBSplits_PreviousLockedSplitsNotIncluded({projectId: projectId, rulesetId: rulesetId});
+            // forge-lint: disable-next-line(block-timestamp)
+            if (block.timestamp < currentSplits[i].lockedUntil) {
+                uint256 requiredCount;
+                for (uint256 j; j < numberOfCurrentSplits;) {
+                    if (
+                        // forge-lint: disable-next-line(block-timestamp)
+                        block.timestamp < currentSplits[j].lockedUntil
+                            && _isLockedSplitIncluded({split: currentSplits[j], lockedSplit: currentSplits[i]})
+                    ) {
+                        ++requiredCount;
+                    }
+                    unchecked {
+                        ++j;
+                    }
+                }
+
+                if (_includedLockedSplitCount({splits: splits, lockedSplit: currentSplits[i]}) < requiredCount) {
+                    revert JBSplits_PreviousLockedSplitsNotIncluded({projectId: projectId, rulesetId: rulesetId});
+                }
             }
             unchecked {
                 ++i;
@@ -332,31 +348,38 @@ contract JBSplits is JBControlled, IJBSplits {
         return splits;
     }
 
-    /// @notice Determine if the provided splits array includes the locked split.
+    /// @notice Count the splits in the provided array that include the locked split.
     /// @param splits The array of splits to check within.
     /// @param lockedSplit The locked split.
-    /// @return A flag indicating if the `lockedSplit` is contained in the `splits`.
-    function _includesLockedSplits(JBSplit[] memory splits, JBSplit memory lockedSplit) internal pure returns (bool) {
+    /// @return count The number of matching splits.
+    function _includedLockedSplitCount(
+        JBSplit[] memory splits,
+        JBSplit memory lockedSplit
+    )
+        internal
+        pure
+        returns (uint256 count)
+    {
         // Keep a reference to the number of splits.
         uint256 numberOfSplits = splits.length;
 
         for (uint256 i; i < numberOfSplits;) {
-            // Set the split being iterated on.
-            JBSplit memory split = splits[i];
-
-            // Check for sameness.
-            if (
-                // Allow the lock to be extended.
-                split.percent == lockedSplit.percent && split.beneficiary == lockedSplit.beneficiary
-                    && split.hook == lockedSplit.hook && split.projectId == lockedSplit.projectId
-                    && split.preferAddToBalance == lockedSplit.preferAddToBalance
-                    && split.lockedUntil >= lockedSplit.lockedUntil
-            ) return true;
+            if (_isLockedSplitIncluded({split: splits[i], lockedSplit: lockedSplit})) ++count;
             unchecked {
                 ++i;
             }
         }
+    }
 
-        return false;
+    /// @notice Determine if a split satisfies the locked split's immutable fields and lock length.
+    /// @param split The split to check.
+    /// @param lockedSplit The locked split.
+    /// @return A flag indicating whether the split includes the locked split.
+    function _isLockedSplitIncluded(JBSplit memory split, JBSplit memory lockedSplit) internal pure returns (bool) {
+        // Allow the lock to be extended.
+        return split.percent == lockedSplit.percent && split.beneficiary == lockedSplit.beneficiary
+            && split.hook == lockedSplit.hook && split.projectId == lockedSplit.projectId
+            && split.preferAddToBalance == lockedSplit.preferAddToBalance
+            && split.lockedUntil >= lockedSplit.lockedUntil;
     }
 }

package/src/interfaces/IJBFeelessAddresses.sol

@@ -23,12 +23,16 @@ interface IJBFeelessAddresses {
     /// @dev `address(0)` means no hook is set.
     function feelessHook() external view returns (IJBFeelessHook);
 
-    /// @notice Returns whether the specified address is feeless for a specific project, considering the wildcard
-    /// (projectId 0) feeless status, the project-specific feeless status, and the feeless hook (if set).
+    /// @notice Returns whether the specified address is feeless for a specific project, providing the outer caller
+    /// of the fee-bearing operation so hooks can scope grants by who initiated the action.
+    /// @dev Static admin-set mappings are op-agnostic and always apply. The hook (if set) receives `caller` and may
+    /// use it to scope its grant (e.g. an ecosystem router can be feeless only when it itself is the caller).
     /// @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, for the project, or per the hook).
-    function isFeelessFor(address addr, uint256 projectId) external view returns (bool);
+    /// @param caller The outer caller (typically the terminal's `_msgSender()`). Pass `address(0)` for lookups
+    /// without caller context.
+    /// @return A flag indicating whether the address is feeless.
+    function isFeelessFor(address addr, uint256 projectId, address caller) external view returns (bool);
 
     /// @notice Sets whether an address is feeless globally (for all projects).
     /// @param addr The address to set the feeless status of.

package/src/interfaces/IJBFeelessHook.sol

@@ -10,9 +10,16 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 /// so a broken hook cannot brick the fee path in terminals.
 interface IJBFeelessHook is IERC165 {
     /// @notice Returns whether the address should be treated as feeless for the project.
+    /// @dev `caller` is the outer caller that triggered the fee-bearing terminal operation (as resolved by the
+    /// terminal's `_msgSender()`, so ERC-2771 meta-tx forwarders are unwrapped). It is `address(0)` when the registry
+    /// is queried without a caller hint (e.g. a direct off-chain `eth_call` to the registry). Use `caller` together
+    /// with `addr` to scope grants: e.g. an ecosystem router can be feeless ONLY when it is itself the entity calling
+    /// the terminal (so it gets fee-free cash-outs when zapping, but does NOT get feeless status when it merely
+    /// appears as a split recipient of someone else's payout).
     /// @param projectId The ID of the project the fee would be charged on behalf of.
     /// @param addr The address being checked (typically a payout recipient, surplus allowance beneficiary, or
     /// cash-out beneficiary).
+    /// @param caller The outer caller that initiated the terminal operation, or `address(0)` if not provided.
     /// @return A flag indicating whether the address is feeless for the project under the hook's custom logic.
-    function isFeeless(uint256 projectId, address addr) external view returns (bool);
+    function isFeeless(uint256 projectId, address addr, address caller) external view returns (bool);
 }

package/src/libraries/JBMetadataResolver.sol

@@ -30,22 +30,15 @@ library JBMetadataResolver {
     error JBMetadataResolver_MetadataTooLong(uint256 offset, uint256 maxOffset);
     error JBMetadataResolver_MetadataTooShort(uint256 metadataLength, uint256 minMetadataLength);
 
-    // The various sizes used in bytes.
-    uint256 constant ID_SIZE = 4;
+    // Constants alphabetized per STYLE_GUIDE; trailing comments document derivation.
     uint256 constant ID_OFFSET_SIZE = 1;
+    uint256 constant ID_SIZE = 4;
+    uint256 constant MIN_METADATA_LENGTH = 37; // RESERVED_SIZE + ID_SIZE + ID_OFFSET_SIZE
+    uint256 constant NEXT_ID_OFFSET = 9; // TOTAL_ID_SIZE + ID_SIZE
+    uint256 constant RESERVED_SIZE = 32; // 1 * WORD_SIZE — protocol-reserved leading word
+    uint256 constant TOTAL_ID_SIZE = 5; // ID_SIZE + ID_OFFSET_SIZE
     uint256 constant WORD_SIZE = 32;
 
-    // The size that an ID takes in the lookup table (Identifier + Offset).
-    uint256 constant TOTAL_ID_SIZE = 5; // ID_SIZE + ID_OFFSET_SIZE;
-
-    // The amount of bytes to go forward to get to the offset of the next ID (aka. the end of the offset of the current
-    // ID).
-    uint256 constant NEXT_ID_OFFSET = 9; // TOTAL_ID_SIZE + ID_SIZE;
-
-    // 1 word (32B) is reserved for the protocol .
-    uint256 constant RESERVED_SIZE = 32; // 1 * WORD_SIZE;
-    uint256 constant MIN_METADATA_LENGTH = 37; // RESERVED_SIZE + ID_SIZE + ID_OFFSET_SIZE;
-
     /// @notice Add an {id: data} entry to an existing metadata. This is an append-only mechanism.
     /// @param originalMetadata The original metadata
     /// @param idToAdd The id to add

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -8,6 +8,9 @@ import {JBRulesetMetadata} from "./../structs/JBRulesetMetadata.sol";
 /// encodes: reservedPercent, cashOutTaxRate, baseCurrency, 14 boolean flags (pausePay, allowOwnerMinting, etc.),
 /// a data hook address, and 14 bits of custom metadata. Used throughout the protocol to read ruleset configuration
 /// without storing each field separately.
+/// @dev Getter functions are intentionally laid out in bit-position order (low → high), not alphabetical, so that
+/// the source reads as a visual key for the bit layout written by `packRulesetMetadata`. This is the documented
+/// exception to STYLE_GUIDE function ordering for libraries.
 library JBRulesetMetadataResolver {
     function reservedPercent(JBRuleset memory ruleset) internal pure returns (uint16) {
         return uint16(ruleset.metadata >> 4);

package/src/structs/JBFundAccessLimitGroup.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.0;
 import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 
 /// @notice Defines how much a project can withdraw from a specific terminal and token each funding cycle.
+/// @dev A ruleset configuration should include at most one group for each `(terminal, token)` pair.
 /// @dev Example — payout limit of 5 USD in an ETH terminal: the project can distribute up to 5 USD worth of ETH to
 /// its splits per cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD worth of ETH
 /// from the surplus (balance above payout limits).

package/test/helpers/JBTest.sol

@@ -37,6 +37,15 @@ contract JBTest is Test {
         vm.expectCall(_where, _encodedCall);
     }
 
+    /// @notice Calldata for `IJBFeelessAddresses.isFeelessFor(address,uint256,address)`.
+    /// @dev `isFeelessFor` is overloaded on the registry; `abi.encodeCall(IJBFeelessAddresses.isFeelessFor, ...)` is
+    /// ambiguous after the caller-aware overload was added. Terminals call the 3-arg variant forwarding
+    /// `_msgSender()`, so unit tests mocking the registry must encode the 3-arg selector with the expected caller.
+    function feelessCalldata(address addr, uint256 projectId, address caller) public pure returns (bytes memory) {
+        return
+            abi.encodeWithSelector(bytes4(keccak256("isFeelessFor(address,uint256,address)")), addr, projectId, caller);
+    }
+
     // Multiple calls with different return values
     function mockExpectSubsequent(address _where, bytes memory _encodedCall, bytes[] memory _returns) public {
         // Mocks calls with different return values

package/test/mock/MockFeelessHook.sol

@@ -30,7 +30,7 @@ contract MockFeelessHook is ERC165, IJBFeelessHook {
         _allowed[projectId][addr] = flag;
     }
 
-    function isFeeless(uint256 projectId, address addr) external view override returns (bool) {
+    function isFeeless(uint256 projectId, address addr, address) external view override returns (bool) {
         if (mode == 1) revert Nope();
         if (mode == 2) require(false, "nope");
         if (mode == 3) return _allowed[projectId][addr];
@@ -46,14 +46,14 @@ contract MockFeelessHook is ERC165, IJBFeelessHook {
 /// @dev Used to test the `setFeelessHook` validation guard. Has the `isFeeless` selector so the
 /// call shape matches, but its `supportsInterface` advertises only IERC165, not IJBFeelessHook.
 contract MockNonConformingFeelessHook is ERC165 {
-    function isFeeless(uint256, address) external pure returns (bool) {
+    function isFeeless(uint256, address, address) external pure returns (bool) {
         return true;
     }
 }
 
 /// @notice "Hook" with no `supportsInterface` at all — `setFeelessHook` should revert when this is passed.
 contract MockEoaLikeFeelessHook {
-    function isFeeless(uint256, address) external pure returns (bool) {
+    function isFeeless(uint256, address, address) external pure returns (bool) {
         return true;
     }
 }