@bananapus/core-v6 0.0.32 → 0.0.34

package/src/JBRulesets.sol

@@ -208,8 +208,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
             caller: msg.sender
         });
 
-        // Return the struct for the new ruleset's ID.
-        return _getStructFor({projectId: projectId, rulesetId: rulesetId});
+        // Return the struct for the new ruleset's ID, with metadata.
+        return _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
     }
 
     /// @notice Cache the value of the ruleset weight for a specific ruleset.
@@ -221,7 +221,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @param rulesetId The ID of the ruleset to update the cache for.
     function updateRulesetWeightCache(uint256 projectId, uint256 rulesetId) external override {
         // Get the target ruleset.
-        JBRuleset memory targetRuleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+        JBRuleset memory targetRuleset =
+            _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: false});
 
         // Nothing to cache if the target ruleset doesn't have a duration or a weight cut percent.
         // slither-disable-next-line incorrect-equality
@@ -296,8 +297,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // Keep a reference to the number of rulesets being returned.
         uint256 count = 0;
 
-        // Keep a reference to the starting ruleset.
-        JBRuleset memory ruleset = _getStructFor({projectId: projectId, rulesetId: startingId});
+        // Keep a reference to the starting ruleset (metadata not needed — only counting).
+        JBRuleset memory ruleset = _getStructFor({projectId: projectId, rulesetId: startingId, withMetadata: false});
 
         // First, count the number of rulesets to include in the result by iterating backwards from the starting
         // ruleset.
@@ -306,7 +307,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
             count++;
 
             // Iterate to the ruleset it was based on.
-            ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId});
+            ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: false});
         }
 
         // Keep a reference to the array of rulesets that'll be populated.
@@ -317,8 +318,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
             return rulesets;
         }
 
-        // Reset the ruleset being iterated on to the starting ruleset.
-        ruleset = _getStructFor({projectId: projectId, rulesetId: startingId});
+        // Reset the ruleset being iterated on to the starting ruleset, now with metadata for the return array.
+        ruleset = _getStructFor({projectId: projectId, rulesetId: startingId, withMetadata: true});
 
         // Set the counter.
         uint256 i;
@@ -328,8 +329,10 @@ contract JBRulesets is JBControlled, IJBRulesets {
             // Add the ruleset to the array.
             rulesets[i++] = ruleset;
 
-            // Get the ruleset it was based on if needed.
-            if (i != count) ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId});
+            // Get the ruleset it was based on if needed, with metadata for the return array.
+            if (i != count) {
+                ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: true});
+            }
         }
     }
 
@@ -345,8 +348,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // Get a reference to the latest ruleset ID.
         uint256 rulesetId = latestRulesetIdOf[projectId];
 
-        // Resolve the struct for the latest ruleset.
-        JBRuleset memory ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+        // Resolve the struct for the latest ruleset, with metadata (forwarded to the external approval hook).
+        JBRuleset memory ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
 
         return _approvalStatusOf({projectId: projectId, ruleset: ruleset});
     }
@@ -362,15 +365,18 @@ contract JBRulesets is JBControlled, IJBRulesets {
     function currentOf(uint256 projectId) external view override returns (JBRuleset memory ruleset) {
         // If the project does not have a ruleset, return an empty struct.
         // slither-disable-next-line incorrect-equality
-        if (latestRulesetIdOf[projectId] == 0) return _getStructFor({projectId: 0, rulesetId: 0});
+        if (latestRulesetIdOf[projectId] == 0) {
+            return _getStructFor({projectId: 0, rulesetId: 0, withMetadata: false});
+        }
 
         // Get a reference to the currently approvable ruleset's ID.
         uint256 rulesetId = _currentlyApprovableRulesetIdOf(projectId);
 
         // If a currently approvable ruleset exists...
         if (rulesetId != 0) {
-            // Resolve the struct for the currently approvable ruleset.
-            ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+            // Resolve the struct for the currently approvable ruleset, with metadata (forwarded to external hooks
+            // and potentially returned).
+            ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
 
             // Get a reference to the approval status.
             JBApprovalStatus approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
@@ -387,15 +393,16 @@ contract JBRulesets is JBControlled, IJBRulesets {
             // which carries the last approved configuration.
             rulesetId = ruleset.basedOnId;
 
-            // Keep a reference to its ruleset.
-            ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+            // Keep a reference to its ruleset, with metadata (used by `_simulateCycledRulesetBasedOn` and may be
+            // returned).
+            ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
         } else {
             // No upcoming ruleset found that is currently approvable,
             // so use the latest ruleset ID.
             rulesetId = latestRulesetIdOf[projectId];
 
-            // Get the struct for the latest ID.
-            ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+            // Get the struct for the latest ID, with metadata (forwarded to external hooks and may be returned).
+            ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
 
             // Get a reference to the approval status.
             JBApprovalStatus approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
@@ -407,7 +414,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
                     || block.timestamp < ruleset.start
             ) {
                 rulesetId = ruleset.basedOnId;
-                ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+                ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
                 approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
             }
         }
@@ -433,7 +440,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         override
         returns (JBRuleset memory ruleset)
     {
-        return _getStructFor({projectId: projectId, rulesetId: rulesetId});
+        ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
     }
 
     /// @notice The latest ruleset queued for a project. Returns the ruleset's struct and its current approval status.
@@ -451,8 +458,9 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // Get a reference to the latest ruleset's ID.
         uint256 rulesetId = latestRulesetIdOf[projectId];
 
-        // Resolve the struct for the latest ruleset.
-        ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId});
+        // Resolve the struct for the latest ruleset, with metadata (forwarded to the external approval hook and
+        // returned).
+        ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: true});
 
         // Resolve the approval status.
         approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
@@ -465,7 +473,9 @@ contract JBRulesets is JBControlled, IJBRulesets {
     function upcomingOf(uint256 projectId) external view override returns (JBRuleset memory ruleset) {
         // If the project does not have a latest ruleset, return an empty struct.
         // slither-disable-next-line incorrect-equality
-        if (latestRulesetIdOf[projectId] == 0) return _getStructFor({projectId: 0, rulesetId: 0});
+        if (latestRulesetIdOf[projectId] == 0) {
+            return _getStructFor({projectId: 0, rulesetId: 0, withMetadata: false});
+        }
 
         // Get a reference to the upcoming approvable ruleset's ID.
         uint256 upcomingApprovableRulesetId = _upcomingApprovableRulesetIdOf(projectId);
@@ -476,7 +486,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // If an upcoming approvable ruleset has been queued, and it's approval status is Approved or ApprovalExpected,
         // return its ruleset struct
         if (upcomingApprovableRulesetId != 0) {
-            ruleset = _getStructFor({projectId: projectId, rulesetId: upcomingApprovableRulesetId});
+            ruleset = _getStructFor({projectId: projectId, rulesetId: upcomingApprovableRulesetId, withMetadata: true});
 
             // Get a reference to the approval status.
             approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
@@ -488,23 +498,25 @@ contract JBRulesets is JBControlled, IJBRulesets {
                     || approvalStatus == JBApprovalStatus.Empty
             ) return ruleset;
 
-            // Resolve the ruleset for the ruleset the upcoming approvable ruleset was based on.
-            ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId});
+            // Resolve the ruleset for the ruleset the upcoming approvable ruleset was based on, with metadata
+            // (used by `_simulateCycledRulesetBasedOn`).
+            ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: true});
         } else {
-            // Resolve the ruleset for the latest queued ruleset.
-            ruleset = _getStructFor({projectId: projectId, rulesetId: latestRulesetIdOf[projectId]});
+            // Resolve the ruleset for the latest queued ruleset, with metadata (forwarded to external hooks and used
+            // by `_simulateCycledRulesetBasedOn`).
+            ruleset = _getStructFor({projectId: projectId, rulesetId: latestRulesetIdOf[projectId], withMetadata: true});
 
             // If the latest ruleset starts in the future, it must start in the distant future
             // Since its not the upcoming approvable ruleset. In this case, base the upcoming ruleset on the base
             // ruleset.
             while (ruleset.start > block.timestamp) {
-                ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId});
+                ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: true});
             }
         }
 
         // There's no queued if the current has a duration of 0.
         // slither-disable-next-line incorrect-equality
-        if (ruleset.duration == 0) return _getStructFor({projectId: 0, rulesetId: 0});
+        if (ruleset.duration == 0) return _getStructFor({projectId: 0, rulesetId: 0, withMetadata: false});
 
         // Get a reference to the approval status.
         approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
@@ -516,12 +528,13 @@ contract JBRulesets is JBControlled, IJBRulesets {
             return _simulateCycledRulesetBasedOn({projectId: projectId, baseRuleset: ruleset, allowMidRuleset: false});
         }
 
-        // Get the ruleset of its base ruleset, which carries the last approved configuration.
-        ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId});
+        // Get the ruleset of its base ruleset, which carries the last approved configuration. Metadata is needed by
+        // `_simulateCycledRulesetBasedOn`.
+        ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: true});
 
         // There's no queued if the base, which must still be the current, has a duration of 0.
         // slither-disable-next-line incorrect-equality
-        if (ruleset.duration == 0) return _getStructFor({projectId: 0, rulesetId: 0});
+        if (ruleset.duration == 0) return _getStructFor({projectId: 0, rulesetId: 0, withMetadata: false});
 
         // Return a simulated cycled ruleset.
         return _simulateCycledRulesetBasedOn({projectId: projectId, baseRuleset: ruleset, allowMidRuleset: false});
@@ -715,16 +728,16 @@ contract JBRulesets is JBControlled, IJBRulesets {
             // Use an empty ruleset as the base.
             return _initializeRulesetFor({
                 projectId: projectId,
-                baseRuleset: _getStructFor({projectId: 0, rulesetId: 0}),
+                baseRuleset: _getStructFor({projectId: 0, rulesetId: 0, withMetadata: false}),
                 rulesetId: rulesetId,
                 mustStartAtOrAfter: mustStartAtOrAfter,
                 weight: weight
             });
         }
 
-        // Get a reference to the latest ruleset's struct.
-        // Note: full metadata is loaded because `_approvalStatusOf` forwards the struct to external approval hooks.
-        JBRuleset memory baseRuleset = _getStructFor({projectId: projectId, rulesetId: latestId});
+        // Get a reference to the latest ruleset's struct, with metadata because `_approvalStatusOf` forwards the
+        // struct to external approval hooks.
+        JBRuleset memory baseRuleset = _getStructFor({projectId: projectId, rulesetId: latestId, withMetadata: true});
 
         // Get a reference to the approval status.
         JBApprovalStatus approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: baseRuleset});
@@ -748,7 +761,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         ) {
             // Metadata not needed — the fallback ruleset is only used for intrinsic fields (start, basedOnId, etc.)
             // and not forwarded to any external approval hook.
-            baseRuleset = _getStructWithoutMetadataFor({projectId: projectId, rulesetId: baseRuleset.basedOnId});
+            baseRuleset = _getStructFor({projectId: projectId, rulesetId: baseRuleset.basedOnId, withMetadata: false});
         }
 
         // Make sure the ruleset starts after the base ruleset.
@@ -935,7 +948,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         uint256 rulesetId = latestRulesetIdOf[projectId];
 
         // Get the struct for the latest ruleset (metadata not needed — only traversal fields are checked).
-        JBRuleset memory ruleset = _getStructWithoutMetadataFor({projectId: projectId, rulesetId: rulesetId});
+        JBRuleset memory ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: false});
 
         // Loop through all most recently queued rulesets until an approvable one is found, or we've proven one can't
         // exist.
@@ -951,22 +964,23 @@ contract JBRulesets is JBControlled, IJBRulesets {
                 return ruleset.id;
             }
 
-            ruleset = _getStructWithoutMetadataFor({projectId: projectId, rulesetId: ruleset.basedOnId});
+            ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: false});
         } while (ruleset.cycleNumber != 0);
 
         return 0;
     }
 
-    /// @notice Unpack a ruleset's intrinsic and user properties without loading metadata.
-    /// @dev Saves one cold SLOAD (~2,100 gas) compared to `_getStructFor`. Use this for linked-list traversal where
-    /// only `id`, `start`, `duration`, `basedOnId`, `cycleNumber`, `weight`, `weightCutPercent`, and `approvalHook`
-    /// are needed.
+    /// @notice Unpack a ruleset's packed stored values into a struct.
+    /// @dev When `withMetadata` is false, one cold SLOAD (~2,100 gas) is skipped — use this for linked-list traversal
+    /// where only id, start, duration, basedOnId, etc. are needed.
     /// @param projectId The ID of the project the ruleset belongs to.
     /// @param rulesetId The ID of the ruleset to get the struct for.
-    /// @return ruleset A ruleset struct with `metadata` set to 0.
-    function _getStructWithoutMetadataFor(
+    /// @param withMetadata Whether to load the packed metadata from storage.
+    /// @return ruleset The ruleset struct (`metadata` is 0 when `withMetadata` is false).
+    function _getStructFor(
         uint256 projectId,
-        uint256 rulesetId
+        uint256 rulesetId,
+        bool withMetadata
     )
         internal
         view
@@ -1006,49 +1020,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // forge-lint: disable-next-line(unsafe-typecast)
         ruleset.weightCutPercent = uint32(packedUserProperties >> 192);
 
-        // metadata intentionally not loaded — saves one cold SLOAD (~2,100 gas).
-    }
-
-    /// @notice Unpack a ruleset's packed stored values into an easy-to-work-with ruleset struct.
-    /// @param projectId The ID of the project the ruleset belongs to.
-    /// @param rulesetId The ID of the ruleset to get the full struct for.
-    /// @return ruleset A ruleset struct.
-    function _getStructFor(uint256 projectId, uint256 rulesetId) internal view returns (JBRuleset memory ruleset) {
-        // Return an empty ruleset if the specified `rulesetId` is 0.
-        // 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];
+        // Load metadata only when needed — saves one cold SLOAD (~2,100 gas) for traversal-only paths.
+        if (withMetadata) ruleset.metadata = _metadataOf[projectId][rulesetId];
     }
 
     /// @notice A simulated view of the ruleset that would be created if the provided one cycled over (if the project
@@ -1126,7 +1099,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         rulesetId = latestRulesetIdOf[projectId];
 
         // Get the struct for the latest ruleset (metadata not needed — only traversal fields are checked).
-        JBRuleset memory ruleset = _getStructWithoutMetadataFor({projectId: projectId, rulesetId: rulesetId});
+        JBRuleset memory ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: false});
 
         // There is no upcoming ruleset if the latest ruleset has already started.
         // slither-disable-next-line incorrect-equality
@@ -1144,7 +1117,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
         // Find the base ruleset that is not still queued.
         while (true) {
-            baseRuleset = _getStructWithoutMetadataFor({projectId: projectId, rulesetId: basedOnId});
+            baseRuleset = _getStructFor({projectId: projectId, rulesetId: basedOnId, withMetadata: false});
 
             // If the base ruleset starts in the future,
             if (block.timestamp < baseRuleset.start) {
@@ -1159,7 +1132,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         }
 
         // Get the ruleset struct for the ID found (metadata not needed — only `start` and `duration` are checked).
-        ruleset = _getStructWithoutMetadataFor({projectId: projectId, rulesetId: rulesetId});
+        ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: false});
 
         // If the latest ruleset doesn't start until after another base ruleset return 0.
         if (baseRuleset.duration != 0 && block.timestamp < ruleset.start - baseRuleset.duration) {

package/src/JBTerminalStore.sol

@@ -599,6 +599,8 @@ contract JBTerminalStore is IJBTerminalStore {
         JBRuleset memory ruleset = RULESETS.currentOf(projectId);
 
         // Return the amount of surplus terminal tokens that would be reclaimed.
+        // NOTE: This view does not run the data hook, so it cannot reflect a cross-chain totalSupply override.
+        // For accurate omnichain estimates, use the data hook or simulate recordCashOutFor.
         return JBCashOuts.cashOutFrom({
             surplus: surplus,
             cashOutCount: cashOutCount,
@@ -814,6 +816,8 @@ contract JBTerminalStore is IJBTerminalStore {
         if (cashOutCount > totalSupply) return 0;
 
         // Return the amount of surplus terminal tokens that would be reclaimed.
+        // NOTE: This view does not run the data hook, so it cannot reflect a cross-chain totalSupply override.
+        // For accurate omnichain estimates, use the data hook or simulate recordCashOutFor.
         return JBCashOuts.cashOutFrom({
             surplus: currentSurplus,
             cashOutCount: cashOutCount,
@@ -877,6 +881,54 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
+    /// @notice Calls the data hook, validates noop specifications, and computes the bonding curve reclaim amount.
+    /// @dev Extracted from `_computeCashOutFrom` to keep it under the EVM stack depth limit (16 slots).
+    /// @param ruleset The current ruleset (used to resolve the data hook address).
+    /// @param context The fully-populated cash out context to forward to the data hook.
+    /// @param surplus The locally available surplus (used as a cap — can't reclaim more than what's on-chain here).
+    /// @return reclaimAmount The amount of surplus tokens reclaimable after the bonding curve and cap.
+    /// @return cashOutTaxRate The cash out tax rate returned by the data hook.
+    /// @return hookSpecifications The hook specifications returned by the data hook.
+    function _cashOutWithDataHook(
+        JBRuleset memory ruleset,
+        JBBeforeCashOutRecordedContext memory context,
+        uint256 surplus
+    )
+        internal
+        view
+        returns (uint256 reclaimAmount, uint256 cashOutTaxRate, JBCashOutHookSpecification[] memory hookSpecifications)
+    {
+        // Ask the data hook for the effective bonding curve parameters and any hook specifications.
+        uint256 effectiveCashOutCount;
+        uint256 effectiveTotalSupply;
+        uint256 effectiveSurplusValue;
+        (cashOutTaxRate, effectiveCashOutCount, effectiveTotalSupply, effectiveSurplusValue, hookSpecifications) =
+            IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
+
+        // Noop specifications are informational only, so they can't also request forwarded funds.
+        for (uint256 i; i < hookSpecifications.length;) {
+            if (hookSpecifications[i].noop && hookSpecifications[i].amount != 0) {
+                revert JBTerminalStore_NoopHookSpecHasAmount(hookSpecifications[i].amount);
+            }
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Apply the bonding curve to calculate how much of the surplus is reclaimable.
+        if (surplus != 0) {
+            reclaimAmount = JBCashOuts.cashOutFrom({
+                surplus: effectiveSurplusValue,
+                cashOutCount: effectiveCashOutCount,
+                totalSupply: effectiveTotalSupply,
+                cashOutTaxRate: cashOutTaxRate
+            });
+
+            // Cap at local surplus — can't reclaim more than what's locally available.
+            if (reclaimAmount > surplus) reclaimAmount = surplus;
+        }
+    }
+
     /// @notice Computes cash out results without writing state.
     /// @param terminal The terminal recording the cash out.
     /// @param holder The account that is cashing out tokens.
@@ -934,8 +986,6 @@ contract JBTerminalStore is IJBTerminalStore {
         // The terminal still burns the caller-supplied cashOutCount after pricing completes.
         // Project owners MUST audit their data hooks with the same rigor as the terminal.
 
-        uint256 effectiveCashOutCount = cashOutCount;
-
         // If the ruleset has a data hook which is enabled for cash outs, use it to derive a claim amount and memo.
         if (ruleset.useDataHookForCashOut() && ruleset.dataHook() != address(0)) {
             // Build the cash out context field-by-field — the struct has 11 fields, too many for a literal.
@@ -957,30 +1007,21 @@ contract JBTerminalStore is IJBTerminalStore {
             context.beneficiaryIsFeeless = beneficiaryIsFeeless;
             context.metadata = metadata;
 
-            (cashOutTaxRate, effectiveCashOutCount, effectiveTotalSupply, hookSpecifications) =
-                IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
-
-            // Noop specifications are informational only, so they can't also request forwarded funds.
-            for (uint256 i; i < hookSpecifications.length;) {
-                if (hookSpecifications[i].noop && hookSpecifications[i].amount != 0) {
-                    revert JBTerminalStore_NoopHookSpecHasAmount(hookSpecifications[i].amount);
-                }
-                unchecked {
-                    ++i;
-                }
-            }
+            // Hook call + bonding curve in a helper to stay under the stack depth limit.
+            (reclaimAmount, cashOutTaxRate, hookSpecifications) =
+                _cashOutWithDataHook({ruleset: ruleset, context: context, surplus: surplus});
         } else {
             cashOutTaxRate = ruleset.cashOutTaxRate();
-        }
 
-        // Apply the bonding curve to calculate how much of the surplus is reclaimable.
-        if (surplus != 0) {
-            reclaimAmount = JBCashOuts.cashOutFrom({
-                surplus: surplus,
-                cashOutCount: effectiveCashOutCount,
-                totalSupply: effectiveTotalSupply,
-                cashOutTaxRate: cashOutTaxRate
-            });
+            // Apply the bonding curve to calculate how much of the surplus is reclaimable.
+            if (surplus != 0) {
+                reclaimAmount = JBCashOuts.cashOutFrom({
+                    surplus: surplus,
+                    cashOutCount: cashOutCount,
+                    totalSupply: effectiveTotalSupply,
+                    cashOutTaxRate: cashOutTaxRate
+                });
+            }
         }
     }
 

package/src/JBTokens.sol

@@ -228,7 +228,7 @@ contract JBTokens is JBControlled, IJBTokens {
         });
 
         // Initialize the token.
-        token.initialize({name: name, symbol: symbol, owner: address(this)});
+        token.initialize({name: name, symbol: symbol, tokens: address(this)});
     }
 
     /// @notice Mint (create) new tokens or credits.

package/src/abstract/JBPermissioned.sol

@@ -34,6 +34,34 @@ abstract contract JBPermissioned is Context, IJBPermissioned {
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//
 
+    /// @notice Check whether an operator is the account or has the relevant permission.
+    /// @param operator The address to check.
+    /// @param account The account to allow.
+    /// @param projectId The project ID to check the permission under.
+    /// @param permissionId The required permission ID. The operator must have this permission within the specified
+    /// project ID.
+    /// @return Whether the operator is the account or has the permission.
+    function _hasPermissionFrom(
+        address operator,
+        address account,
+        uint256 projectId,
+        uint256 permissionId
+    )
+        internal
+        view
+        returns (bool)
+    {
+        return operator == account
+            || PERMISSIONS.hasPermission({
+                operator: operator,
+                account: account,
+                projectId: projectId,
+                permissionId: permissionId,
+                includeRoot: true,
+                includeWildcardProjectId: true
+            });
+    }
+
     /// @notice Require the message sender to be the account or have the relevant permission.
     /// @param account The account to allow.
     /// @param projectId The project ID to check the permission under.

package/src/interfaces/IJBRulesetDataHook.sol

@@ -19,7 +19,11 @@ interface IJBRulesetDataHook is IERC165 {
     /// @return cashOutTaxRate The rate determining the reclaimable amount for a given surplus and token supply.
     /// @return effectiveCashOutCount The effective token count to use for pricing the cash out. The terminal still
     /// burns the caller-supplied token count.
-    /// @return effectiveTotalSupply The effective total supply to use for pricing the cash out.
+    /// @return effectiveTotalSupply The effective total supply to use for both the proportional reclaim and tax
+    /// calculations. For omnichain projects, this should include tokens on other chains so the tax cannot be bypassed.
+    /// @return effectiveSurplusValue The surplus value to use for the bonding curve calculation, denominated in the
+    /// same token, decimals, and currency as `context.surplus`. The terminal caps the reclaim at locally available
+    /// funds.
     /// @return hookSpecifications The amount and data to send to cash out hooks instead of returning to the
     /// beneficiary.
     function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
@@ -29,6 +33,7 @@ interface IJBRulesetDataHook is IERC165 {
             uint256 cashOutTaxRate,
             uint256 effectiveCashOutCount,
             uint256 effectiveTotalSupply,
+            uint256 effectiveSurplusValue,
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 

package/src/interfaces/IJBToken.sol

@@ -26,11 +26,11 @@ interface IJBToken {
     /// @param amount The amount of tokens to burn.
     function burn(address account, uint256 amount) external;
 
-    /// @notice Initializes the token with a name, symbol, and owner.
+    /// @notice Initializes the token with a name, symbol, and the JBTokens contract.
     /// @param name The token's name.
     /// @param symbol The token's symbol.
-    /// @param owner The token contract's owner.
-    function initialize(string memory name, string memory symbol, address owner) external;
+    /// @param tokens The JBTokens contract that manages this token.
+    function initialize(string memory name, string memory symbol, address tokens) external;
 
     /// @notice Mints tokens to an account.
     /// @param account The address to mint tokens to.

package/test/TestCashOutHooks.sol

@@ -207,7 +207,11 @@ contract TestCashOutHooks_Local is TestBaseWorkflow {
             _DATA_HOOK,
             abi.encodeWithSelector(IJBRulesetDataHook.beforeCashOutRecordedWith.selector),
             abi.encode(
-                _ruleset.cashOutTaxRate(), _beneficiaryTokenBalance / 2, _beneficiaryTokenBalance, _specifications
+                _ruleset.cashOutTaxRate(),
+                _beneficiaryTokenBalance / 2,
+                _beneficiaryTokenBalance,
+                _nativePayAmount,
+                _specifications
             )
         );
 
@@ -322,7 +326,13 @@ contract TestCashOutHooks_Local is TestBaseWorkflow {
         vm.mockCall(
             _DATA_HOOK,
             abi.encodeWithSelector(IJBRulesetDataHook.beforeCashOutRecordedWith.selector),
-            abi.encode(_customCashOutTaxRate, _customCashOutCount, _customTotalSupply, _specifications)
+            abi.encode(
+                _customCashOutTaxRate,
+                _customCashOutCount,
+                _customTotalSupply,
+                _nativeTerminalBalance, // Same as _nativePayAmount (no payouts); avoids stack depth limit.
+                _specifications
+            )
         );
 
         _terminal.cashOutTokensOf({

package/test/TestDataHookFuzzing.sol

@@ -261,12 +261,12 @@ contract TestDataHookFuzzing_Local is TestBaseWorkflow {
         uint256 cashOutCount = tokenBalance / 2;
         _hookTotalSupply = bound(_hookTotalSupply, cashOutCount, tokenBalance * 10);
 
-        // Data hook returns: cashOutTaxRate=0, cashOutCount=half, custom totalSupply, no hook specs.
+        // Data hook returns: cashOutTaxRate=0, cashOutCount=half, custom totalSupply, local surplus, no hook specs.
         JBCashOutHookSpecification[] memory _emptyCashOutSpecs = new JBCashOutHookSpecification[](0);
         vm.mockCall(
             _DATA_HOOK,
             abi.encodeWithSelector(IJBRulesetDataHook.beforeCashOutRecordedWith.selector),
-            abi.encode(uint256(0), cashOutCount, _hookTotalSupply, _emptyCashOutSpecs)
+            abi.encode(uint256(0), cashOutCount, _hookTotalSupply, _payAmount, _emptyCashOutSpecs)
         );
 
         uint256 balanceBefore = address(this).balance;
@@ -336,7 +336,7 @@ contract TestDataHookFuzzing_Local is TestBaseWorkflow {
         vm.mockCall(
             _DATA_HOOK,
             abi.encodeWithSelector(IJBRulesetDataHook.beforeCashOutRecordedWith.selector),
-            abi.encode(uint256(0), cashOutCount, tokenBalance, _specs)
+            abi.encode(uint256(0), cashOutCount, tokenBalance, _payAmount, _specs)
         );
 
         // Mock the cash out hook call.
@@ -500,7 +500,7 @@ contract TestDataHookFuzzing_Local is TestBaseWorkflow {
         vm.mockCall(
             _DATA_HOOK,
             abi.encodeWithSelector(IJBRulesetDataHook.beforeCashOutRecordedWith.selector),
-            abi.encode(uint256(0), tokenBalance, tokenBalance, _specs)
+            abi.encode(uint256(0), tokenBalance, tokenBalance, _payAmount, _specs)
         );
 
         vm.expectRevert(

package/test/TestForwardedTokenConsumption.sol

@@ -145,7 +145,13 @@ contract TestForwardedTokenConsumption_Local is TestBaseWorkflow {
         vm.mockCall(
             _DATA_HOOK,
             abi.encodeWithSelector(IJBRulesetDataHook.beforeCashOutRecordedWith.selector),
-            abi.encode(0, cashOutCount, _controller.totalTokenSupplyWithReservedTokensOf(_projectId), specifications)
+            abi.encode(
+                0,
+                cashOutCount,
+                _controller.totalTokenSupplyWithReservedTokensOf(_projectId),
+                _PAY_AMOUNT,
+                specifications
+            )
         );
 
         vm.prank(multisig());