@bananapus/core-v6 0.0.32 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "license": "MIT",
   "repository": {
     "type": "git",

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) {