@bananapus/core-v6 0.0.38 → 0.0.40

package/src/JBPermissions.sol

@@ -7,8 +7,11 @@ import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol"
 import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
 import {JBPermissionsData} from "./structs/JBPermissionsData.sol";
 
-/// @notice Stores permissions for all addresses and operators. Addresses can give permissions to any other address
-/// (i.e. an *operator*) to execute specific operations on their behalf.
+/// @notice The permission system for Juicebox. Any address can authorize another address (an "operator") to perform
+/// specific actions on its behalf — like queuing rulesets, distributing payouts, or managing terminals.
+/// @dev Permissions are stored as a packed `uint256` bitmap: each of the 256 bits represents one permission's
+/// on/off state. Project ID 0 is a wildcard that grants an operator access across all projects — use with caution.
+/// @dev The ROOT permission (ID 1) implicitly grants every other permission for the scoped project.
 contract JBPermissions is ERC2771Context, IJBPermissions {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -23,21 +26,21 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ------------------------- public constants ------------------------ //
     //*********************************************************************//
 
-    /// @notice The project ID considered a wildcard, meaning it will grant permissions to all projects.
+    /// @notice The project ID that acts as a wildcard — granting the operator permissions across all projects owned
+    /// by
+    /// the account. Setting permissions for project ID 0 is powerful and should be done carefully.
     uint256 public constant override WILDCARD_PROJECT_ID = 0;
 
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice The permissions that an operator has been given by an account for a specific project.
-    /// @dev An account can give an operator permissions that only pertain to a specific project ID.
-    /// @dev There is no project with a ID of 0 – this ID is a wildcard which gives an operator permissions pertaining
-    /// to *all* project IDs on an account's behalf. Use this with caution.
-    /// @dev Permissions are stored in a packed `uint256`. Each of the 256 bits represents the on/off state of a
-    /// permission. Applications can specify the significance of each permission ID.
+    /// @notice The packed permission bitmap that an account has granted to an operator for a specific project.
+    /// @dev Each bit in the returned `uint256` corresponds to a permission ID (0–255). A `1` bit means that
+    /// permission
+    /// is granted. See `JBPermissionIds` for the meaning of each ID.
     /// @custom:param operator The address of the operator.
-    /// @custom:param account The address of the account being operated on behalf of.
+    /// @custom:param account The address of the account operated on behalf of.
     /// @custom:param projectId The project ID the permissions are scoped to. An ID of 0 grants permissions across all
     /// projects.
     mapping(address operator => mapping(address account => mapping(uint256 projectId => uint256)))
@@ -55,14 +58,12 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets permissions for an operator.
-    /// @dev Only the `account` itself (i.e. `msg.sender == account`) can grant or revoke its operators' permissions
-    /// without restriction — including ROOT on the wildcard project ID (`projectId = 0`).
-    /// @dev A third-party caller who holds ROOT for a specific project may set *non-ROOT* permissions for that project
-    /// on someone else's behalf, but **cannot**: (a) grant ROOT to others, or (b) set any permissions on the wildcard
-    /// project ID. This prevents ROOT operators from escalating their own privileges.
-    /// @param account The account setting its operators' permissions.
-    /// @param permissionsData The data which specifies the permissions the operator is being given.
+    /// @notice Grant or revoke permissions for an operator on a specific project.
+    /// @dev Only the account itself can set permissions without restriction. A ROOT operator on a specific project can
+    /// set non-ROOT permissions for that same project on the account's behalf, but cannot grant ROOT or set wildcard
+    /// (project ID 0) permissions — preventing privilege escalation.
+    /// @param account The account to configure operator permissions for.
+    /// @param permissionsData The operator address, project scope, and permission IDs to set.
     function setPermissionsFor(address account, JBPermissionsData calldata permissionsData) external override {
         // Pack the permission IDs into a uint256.
         uint256 packed = _packedPermissions(permissionsData.permissionIds);
@@ -113,16 +114,14 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Check if an operator has all of the specified permissions for a specific address and project ID.
-    /// @param operator The operator to check.
-    /// @param account The account being operated on behalf of.
-    /// @param projectId The project ID that the operator has permission to operate under. 0 represents all projects.
-    /// @param permissionIds An array of permission IDs to check for.
-    /// @param includeRoot A flag indicating if the return value should default to true if the operator has the ROOT
-    /// permission.
-    /// @param includeWildcardProjectId A flag indicating if the return value should return true if the operator has the
-    /// specified permission on the wildcard project ID.
-    /// @return A flag indicating whether the operator has all specified permissions.
+    /// @notice Check whether an operator has *all* of the specified permissions for an account and project.
+    /// @param operator The address to check permissions for.
+    /// @param account The account that granted (or didn't grant) the permissions.
+    /// @param projectId The project ID to check within. Pass 0 to check the wildcard scope directly.
+    /// @param permissionIds The permission IDs that must all be present.
+    /// @param includeRoot If `true`, returns `true` immediately when the operator has the ROOT permission.
+    /// @param includeWildcardProjectId If `true`, also checks wildcard (project 0) permissions as a fallback.
+    /// @return Whether the operator holds every requested permission.
     function hasPermissions(
         address operator,
         address account,
@@ -187,16 +186,14 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Check if an operator has a specific permission for a specific address and project ID.
-    /// @param operator The operator to check.
-    /// @param account The account being operated on behalf of.
-    /// @param projectId The project ID that the operator has permission to operate under. 0 represents all projects.
-    /// @param permissionId The permission ID to check for.
-    /// @param includeRoot A flag indicating if the return value should default to true if the operator has the ROOT
-    /// permission.
-    /// @param includeWildcardProjectId A flag indicating if the return value should return true if the operator has the
-    /// specified permission on the wildcard project ID.
-    /// @return A flag indicating whether the operator has the specified permission.
+    /// @notice Check whether an operator has a single permission for an account and project.
+    /// @param operator The address to check.
+    /// @param account The account that granted (or didn't grant) the permission.
+    /// @param projectId The project ID to check within. Pass 0 to check the wildcard scope directly.
+    /// @param permissionId The specific permission ID to look for (0–255).
+    /// @param includeRoot If `true`, returns `true` immediately when the operator has the ROOT permission.
+    /// @param includeWildcardProjectId If `true`, also checks wildcard (project 0) permissions as a fallback.
+    /// @return Whether the operator holds the requested permission.
     function hasPermission(
         address operator,
         address account,

package/src/JBPrices.sol

@@ -13,12 +13,13 @@ import {IJBPriceFeed} from "./interfaces/IJBPriceFeed.sol";
 import {IJBPrices} from "./interfaces/IJBPrices.sol";
 import {IJBProjects} from "./interfaces/IJBProjects.sol";
 
-/// @notice Manages and normalizes price feeds. Price feeds are contracts which return the "pricing currency" cost of 1
-/// "unit currency".
-/// @dev Price feeds are immutable once set and cannot be replaced or removed. This prevents oracle manipulation via
-/// admin-key attacks, but means a misconfigured or failing feed will cause operations using that currency pair to
-/// revert (DoS, not fund loss). Select feeds carefully — recovery requires deploying a new JBPrices contract and
-/// migrating projects.
+/// @notice Provides currency conversion for the protocol. When a project's payout limits or surplus allowances are
+/// denominated in a currency different from the token held in its terminal (e.g. USD limits with ETH held), this
+/// contract resolves the exchange rate via registered price feeds (typically Chainlink oracles).
+/// @dev Price feeds are immutable once set — they cannot be replaced or removed. This protects against oracle
+/// manipulation via admin-key attacks. If a feed is misconfigured, operations using that pair will revert (DoS, not
+/// fund loss). The inverse of any registered feed is auto-calculated. Projects can have their own feeds; project ID 0
+/// holds protocol-wide defaults.
 contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBPrices {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -52,7 +53,7 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
     /// @custom:param projectId The ID of the project the feed applies to. Feeds stored in ID 0 are used by default for
     /// all projects.
     /// @custom:param pricingCurrency The currency the feed's resulting price is in terms of.
-    /// @custom:param unitCurrency The currency being priced by the feed.
+    /// @custom:param unitCurrency The currency the feed prices.
     mapping(uint256 projectId => mapping(uint256 pricingCurrency => mapping(uint256 unitCurrency => IJBPriceFeed)))
         public
         override priceFeedFor;
@@ -85,15 +86,16 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Add a price feed for the `unitCurrency`, priced in terms of the `pricingCurrency`.
-    /// @dev Price feeds can only be added, not modified or removed. Once a feed is set for a currency pair (in either
-    /// direction), it is permanent for that project ID. Recovery from a misconfigured feed requires deploying a new
-    /// JBPrices contract.
-    /// @dev This contract's owner can add protocol-wide default price feed by passing a `projectId` of 0.
-    /// @param projectId The ID of the project to add a feed for. If `projectId` is 0, add a protocol-wide default price
-    /// feed.
+    /// @notice Register a price feed that provides the exchange rate between two currencies. For example, registering
+    /// an ETH/USD feed allows payout limits denominated in USD to be enforced against ETH balances.
+    /// @dev Price feeds are immutable — once set for a currency pair, they cannot be replaced or removed. This
+    /// prevents
+    /// admin-key oracle manipulation. The inverse rate is auto-calculated, so registering A→B also provides B→A.
+    /// @dev Pass `projectId` = 0 to set a protocol-wide default (owner only). Non-zero project IDs require controller
+    /// authorization. A default feed for a pair blocks per-project overrides for that same pair.
+    /// @param projectId The ID of the project to add a feed for. Pass 0 for a protocol-wide default.
     /// @param pricingCurrency The currency the feed's output price is in terms of.
-    /// @param unitCurrency The currency being priced by the feed.
+    /// @param unitCurrency The currency the feed prices.
     /// @param feed The address of the price feed to add.
     function addPriceFeedFor(
         uint256 projectId,
@@ -156,11 +158,14 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Gets the `pricingCurrency` cost for one unit of the `unitCurrency`.
-    /// @param projectId The ID of the project to check the feed for. Feeds stored in ID 0 are used by default for all
-    /// projects.
-    /// @param pricingCurrency The currency the feed's resulting price is in terms of.
-    /// @param unitCurrency The currency being priced by the feed.
+    /// @notice Convert between currencies — returns how much of `pricingCurrency` one unit of `unitCurrency` is
+    /// worth.
+    /// For example, `pricePerUnitOf(id, USD, ETH, 18)` returns the USD price of 1 ETH with 18 decimals.
+    /// @dev Lookup order: project-specific feed → inverse of project feed → default feed (project 0) → inverse of
+    /// default. Reverts with `JBPrices_PriceFeedNotFound` if no feed exists in any direction.
+    /// @param projectId The ID of the project to check the feed for. Falls back to project 0 (protocol defaults).
+    /// @param pricingCurrency The currency the result is denominated in.
+    /// @param unitCurrency The currency to price.
     /// @param decimals The number of decimals the returned fixed point price should include.
     /// @return The `pricingCurrency` price of 1 `unitCurrency`, as a fixed point number with the specified number of
     /// decimals.

package/src/JBProjects.sol

@@ -9,8 +9,9 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBTokenUriResolver} from "./interfaces/IJBTokenUriResolver.sol";
 
-/// @notice Stores project ownership and metadata.
-/// @dev Projects are represented as ERC-721s.
+/// @notice Each Juicebox project is an ERC-721 NFT. Whoever holds the NFT owns the project and can configure its
+/// rulesets, terminals, and permissions. Projects are created with `createFor` and the resulting token ID is used as
+/// the project's ID across the entire protocol.
 contract JBProjects is ERC721, ERC2771Context, Ownable, IJBProjects {
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
@@ -50,7 +51,9 @@ contract JBProjects is ERC721, ERC2771Context, Ownable, IJBProjects {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets the address of the resolver used to retrieve the tokenURI of projects.
+    /// @notice Set the contract that resolves project NFT metadata (the `tokenURI`). This controls what artwork and
+    /// JSON metadata is returned for each project's ERC-721 token.
+    /// @dev Only this contract's owner can change the resolver.
     /// @param resolver The address of the new resolver.
     function setTokenUriResolver(IJBTokenUriResolver resolver) external override onlyOwner {
         // Store the new resolver.

package/src/JBRulesets.sol

@@ -12,12 +12,14 @@ import {JBConstants} from "./libraries/JBConstants.sol";
 import {JBRuleset} from "./structs/JBRuleset.sol";
 import {JBRulesetWeightCache} from "./structs/JBRulesetWeightCache.sol";
 
-/// @notice Manages rulesets and queuing.
-/// @dev Rulesets dictate how a project behaves for a period of time. To learn more about their functionality, see the
-/// `JBRuleset` data structure.
-/// @dev Throughout this contract, `rulesetId` is an identifier for each ruleset. The `rulesetId` is the unix timestamp
-/// when the ruleset was initialized.
-/// @dev `approvable` means a ruleset which may or may not be approved.
+/// @notice Stores and manages the economic rules for every Juicebox project. A "ruleset" defines how a project behaves
+/// for a period of time: its token issuance weight, cash-out tax rate, payout limits, reserved rate, and more.
+/// Projects queue future rulesets to schedule changes; once a ruleset's duration expires, the next approved ruleset
+/// takes effect automatically.
+/// @dev Rulesets form a linked list via `basedOnId`. Each ruleset ID is the unix timestamp when it was first stored.
+/// Weight decays across cycles using `weightCutPercent` — if many cycles elapse, the decay is computed iteratively
+/// (capped at 20,000 iterations; use `updateRulesetWeightCache` for longer gaps). Approval hooks can gate whether a
+/// queued ruleset actually takes effect.
 contract JBRulesets is JBControlled, IJBRulesets {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -86,32 +88,20 @@ contract JBRulesets is JBControlled, IJBRulesets {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Queues the upcoming approvable ruleset for the specified project.
-    /// @dev Only a project's current controller can queue its rulesets.
+    /// @notice Queues a new ruleset for a project. The ruleset takes effect after the current one ends (or immediately
+    /// if the current ruleset has `duration = 0`). Must be approved by the previous ruleset's approval hook.
+    /// @dev Only the project's current controller can call this.
     /// @param projectId The ID of the project to queue the ruleset for.
-    /// @param duration The number of seconds the ruleset lasts for, after which a new ruleset starts.
-    /// - A `duration` of 0 means this ruleset will remain active until the project owner queues a new ruleset. That new
-    /// ruleset will start immediately.
-    /// - A ruleset with a non-zero `duration` applies until the duration ends – any newly queued rulesets will be
-    /// *queued* to take effect afterwards.
-    /// - If a duration ends and no new rulesets are queued, the ruleset rolls over to a new ruleset with the same rules
-    /// (except for a new `start` timestamp and a cut `weight`).
-    /// @param weight A fixed point number with 18 decimals that contracts can use to base arbitrary calculations on.
-    /// Payment terminals generally use this to determine how many tokens should be minted when the project is paid.
-    /// @param weightCutPercent A fraction (out of `JBConstants.MAX_WEIGHT_CUT_PERCENT`) to reduce the next ruleset's
-    /// `weight`
-    /// by.
-    /// - If a ruleset specifies a non-zero `weight`, the `weightCutPercent` does not apply.
-    /// - If the `weightCutPercent` is 0, the `weight` stays the same.
-    /// - If the `weightCutPercent` is 10% of `JBConstants.MAX_WEIGHT_CUT_PERCENT`, next ruleset's `weight` will be 90%
-    /// of the
-    /// current
-    /// one.
-    /// @param approvalHook A contract which dictates whether a proposed ruleset should be accepted or rejected. It can
-    /// be used to constrain a project owner's ability to change ruleset parameters over time.
-    /// @param metadata Arbitrary extra data to associate with this ruleset. This metadata is not used by `JBRulesets`.
-    /// @param mustStartAtOrAfter The earliest time the ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param duration How long the ruleset lasts (seconds). 0 = no auto-cycling (stays active until explicitly
+    /// replaced). When a duration ends without a queued replacement, the ruleset rolls over with decayed weight.
+    /// @param weight Tokens minted per unit paid (18 decimals). Terminals divide payment amount by weight to determine
+    /// issuance. A value of 1 means "inherit decayed weight from previous ruleset".
+    /// @param weightCutPercent How much to reduce weight each auto-cycle (out of 1,000,000,000). Only applies when no
+    /// explicit replacement is queued. 0 = no decay. 100,000,000 = 10% cut per cycle.
+    /// @param approvalHook A contract that gates whether the *next* queued ruleset can take effect (e.g. `JBDeadline`
+    /// for minimum notice periods). Set to address(0) for no approval gate.
+    /// @param metadata Packed 256-bit field decoded by `JBRulesetMetadataResolver`. Not used by `JBRulesets` itself.
+    /// @param mustStartAtOrAfter The earliest unix timestamp the ruleset can start.
     /// @return The struct of the new ruleset.
     function queueFor(
         uint256 projectId,
@@ -169,6 +159,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         uint256 latestId = latestRulesetIdOf[projectId];
 
         // The new rulesetId timestamp is now, or an increment from now if the current timestamp is taken.
+        // forge-lint: disable-next-line(block-timestamp)
         uint256 rulesetId = latestId >= block.timestamp ? latestId + 1 : block.timestamp;
 
         // Set up the ruleset by configuring intrinsic properties.
@@ -239,6 +230,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
             * targetRuleset.duration;
 
         // Determine the start timestamp to derive a weight from for the cache.
+        // forge-lint: disable-next-line(block-timestamp)
         uint256 start = block.timestamp < maxStart ? block.timestamp : maxStart;
 
         // The difference between the start of the latest queued ruleset and the start of the ruleset we're caching the
@@ -275,7 +267,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Get an array of a project's rulesets up to a maximum array size, sorted from latest to earliest.
+    /// @notice Returns a paginated history of a project's rulesets, sorted newest-first.
     /// @param projectId The ID of the project to get the rulesets of.
     /// @param startingId The ID of the ruleset to begin with. This will be the latest ruleset in the result. If 0 is
     /// passed, the project's latest ruleset will be used.
@@ -336,7 +328,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         }
     }
 
-    /// @notice The current approval status of a given project's latest ruleset.
+    /// @notice Whether the project's most recently queued ruleset has been approved, rejected, or is still pending.
     /// @param projectId The ID of the project to check the approval status of.
     /// @return The project's current approval status.
     function currentApprovalStatusForLatestRulesetOf(uint256 projectId)
@@ -354,12 +346,11 @@ contract JBRulesets is JBControlled, IJBRulesets {
         return _approvalStatusOf({projectId: projectId, ruleset: ruleset});
     }
 
-    /// @notice The ruleset that is currently active for the specified project.
-    /// @dev If a current ruleset of the project is not found, returns an empty ruleset with all properties set to 0.
-    /// @dev The first cycle returns the stored ruleset directly (cycleNumber=1, original weight). Subsequent cycles
-    /// simulate cycling with weight decay via `_simulateCycledRulesetBasedOn`. Payout limits reset each cycle because
-    /// they are keyed by `cycleNumber`, but the simulated cycle keeps the same `rulesetId` / config id as the stored
-    /// ruleset it is based on.
+    /// @notice Returns the ruleset currently governing a project. If the stored ruleset has auto-cycled, simulates
+    /// cycling with weight decay and returns the simulated current cycle.
+    /// @dev Returns an empty ruleset (all zeros) if the project has never had a ruleset queued.
+    /// @dev Payout limits reset each cycle (keyed by `cycleNumber`), but the `rulesetId` stays the same across
+    /// auto-cycles of the same stored ruleset.
     /// @param projectId The ID of the project to get the current ruleset of.
     /// @return ruleset The project's current ruleset.
     function currentOf(uint256 projectId) external view override returns (JBRuleset memory ruleset) {
@@ -411,6 +402,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
             // the ruleset that the latest is based on, which has the latest approved configuration.
             while (
                 (approvalStatus != JBApprovalStatus.Approved && approvalStatus != JBApprovalStatus.Empty)
+                    // forge-lint: disable-next-line(block-timestamp)
                     || block.timestamp < ruleset.start
             ) {
                 rulesetId = ruleset.basedOnId;
@@ -466,8 +458,9 @@ contract JBRulesets is JBControlled, IJBRulesets {
         approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
     }
 
-    /// @notice The ruleset that's up next for a project.
-    /// @dev If an upcoming ruleset is not found for the project, returns an empty ruleset with all properties set to 0.
+    /// @notice Returns the ruleset that will take effect after the current one ends. This could be an explicitly queued
+    /// ruleset or a simulated auto-cycle of the current one (with decayed weight).
+    /// @dev Returns an empty ruleset (all zeros) if there is no upcoming ruleset.
     /// @param projectId The ID of the project to get the upcoming ruleset of.
     /// @return ruleset The struct for the project's upcoming ruleset.
     function upcomingOf(uint256 projectId) external view override returns (JBRuleset memory ruleset) {
@@ -509,6 +502,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
             // 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.
+            // forge-lint: disable-next-line(block-timestamp)
             while (ruleset.start > block.timestamp) {
                 ruleset = _getStructFor({projectId: projectId, rulesetId: ruleset.basedOnId, withMetadata: true});
             }
@@ -747,12 +741,15 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // OR it hasn't started but it is likely to be approved and takes place before the proposed one,
         // set the struct to be the ruleset it's based on, which carries the latest approved ruleset.
         if (
+            // forge-lint: disable-next-line(block-timestamp)
             (block.timestamp >= baseRuleset.start
                     && approvalStatus != JBApprovalStatus.Approved
                     && approvalStatus != JBApprovalStatus.Empty)
+                // forge-lint: disable-next-line(block-timestamp)
                 || (block.timestamp < baseRuleset.start
                     && mustStartAtOrAfter < baseRuleset.start + baseRuleset.duration
                     && approvalStatus != JBApprovalStatus.Approved)
+                // forge-lint: disable-next-line(block-timestamp)
                 || (block.timestamp < baseRuleset.start
                     && mustStartAtOrAfter >= baseRuleset.start + baseRuleset.duration
                     && approvalStatus != JBApprovalStatus.Approved
@@ -794,7 +791,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @notice Initializes a ruleset with the specified properties.
     /// @param projectId The ID of the project to initialize the ruleset for.
     /// @param baseRuleset The ruleset struct to base the newly initialized one on.
-    /// @param rulesetId The `rulesetId` for the ruleset being initialized.
+    /// @param rulesetId The `rulesetId` for the ruleset to initialize.
     /// @param mustStartAtOrAfter The earliest time the ruleset can start. The ruleset cannot start before this
     /// timestamp.
     /// @param weight The weight to give the newly initialized ruleset.
@@ -955,11 +952,13 @@ contract JBRulesets is JBControlled, IJBRulesets {
         do {
             // If the latest ruleset is expired, return an empty ruleset.
             // A ruleset with a duration of 0 cannot expire.
+            // forge-lint: disable-next-line(block-timestamp)
             if (ruleset.duration != 0 && block.timestamp >= ruleset.start + ruleset.duration) {
                 return 0;
             }
 
             // Return the ruleset's `rulesetId` if it has started.
+            // forge-lint: disable-next-line(block-timestamp)
             if (block.timestamp >= ruleset.start) {
                 return ruleset.id;
             }
@@ -1047,6 +1046,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // future.
         uint256 mustStartAtOrAfter = !allowMidRuleset
             ? block.timestamp + 1
+            // forge-lint: disable-next-line(block-timestamp)
             : baseRuleset.duration >= block.timestamp ? 1 : block.timestamp - baseRuleset.duration + 1;
 
         // Calculate what the start time should be.
@@ -1103,6 +1103,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
         // There is no upcoming ruleset if the latest ruleset has already started.
         // slither-disable-next-line incorrect-equality
+        // forge-lint: disable-next-line(block-timestamp)
         if (block.timestamp >= ruleset.start) return 0;
 
         // If this is the first ruleset, it is queued.
@@ -1120,6 +1121,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
             baseRuleset = _getStructFor({projectId: projectId, rulesetId: basedOnId, withMetadata: false});
 
             // If the base ruleset starts in the future,
+            // forge-lint: disable-next-line(block-timestamp)
             if (block.timestamp < baseRuleset.start) {
                 // Set the `rulesetId` to the one found.
                 rulesetId = baseRuleset.id;
@@ -1135,6 +1137,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         ruleset = _getStructFor({projectId: projectId, rulesetId: rulesetId, withMetadata: false});
 
         // If the latest ruleset doesn't start until after another base ruleset return 0.
+        // forge-lint: disable-next-line(block-timestamp)
         if (baseRuleset.duration != 0 && block.timestamp < ruleset.start - baseRuleset.duration) {
             return 0;
         }

package/src/JBSplits.sol

@@ -9,7 +9,11 @@ import {JBConstants} from "./libraries/JBConstants.sol";
 import {JBSplit} from "./structs/JBSplit.sol";
 import {JBSplitGroup} from "./structs/JBSplitGroup.sol";
 
-/// @notice Stores and manages splits for each project.
+/// @notice Manages how a project distributes its payouts and reserved tokens. Each "split" specifies a recipient and
+/// their share (as a fraction of 1,000,000,000). Splits can be locked until a timestamp — locked splits cannot be
+/// removed or reduced until the lock expires, providing recipients with guaranteed revenue streams.
+/// @dev Splits are organized by project, ruleset, and group. Ruleset 0 is the fallback used when no splits are set for
+/// the active ruleset. The payout group ID is derived from the token address to distribute.
 contract JBSplits is JBControlled, IJBSplits {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -75,16 +79,15 @@ contract JBSplits is JBControlled, IJBSplits {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets a project's split groups.
-    /// @dev Only a project's controller can set its splits, unless the first 160 bits of the group's ID match
-    /// `msg.sender` AND the upper 96 bits are non-zero, in which case the caller can set its own splits.
-    /// GroupIds with zero upper 96 bits (i.e. bare addresses) are reserved for protocol use (e.g. terminal
-    /// payout groups keyed by token address) and always require controller authorization.
-    /// @dev The new split groups must include any currently set splits that are locked.
+    /// @notice Configure how a project distributes funds to its split recipients. Each split group defines a list of
+    /// recipients (with percentage shares) for a specific purpose (e.g. payouts in ETH, reserved token distribution).
+    /// @dev Only the project's controller can set splits — unless the group ID encodes `msg.sender` in its lower 160
+    /// bits with non-zero upper 96 bits, which enables self-managed splits (e.g. hooks managing their own groups).
+    /// @dev Locked splits cannot be removed or reduced until their lock expires. The new groups must include all
+    /// currently-locked splits.
     /// @param projectId The ID of the project to set the split groups of.
-    /// @param rulesetId The ID of the ruleset the split groups should be active in. Send
-    /// 0 to set the default split that'll be active if no ruleset has specific splits set. The default's default is the
-    /// project's owner.
+    /// @param rulesetId The ID of the ruleset the split groups should be active in. Pass 0 to set the default splits
+    /// (used when no ruleset-specific splits are configured). The default's default is the project's owner.
     /// @param splitGroups An array of split groups to set.
     function setSplitGroupsOf(
         uint256 projectId,
@@ -127,13 +130,11 @@ contract JBSplits is JBControlled, IJBSplits {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Get the split structs for the specified project ID, within the specified ruleset, for the specified
-    /// group. The splits stored at ruleset 0 are used by default during a ruleset if the splits for the specific
-    /// ruleset aren't set.
-    /// @dev If splits aren't found at the given `rulesetId`, they'll be sought in the FALLBACK_RULESET_ID of 0.
+    /// @notice Get the list of split recipients for a project's group within a given ruleset. Falls back to the
+    /// default splits (ruleset 0) if none are set for the specific ruleset.
     /// @param projectId The ID of the project to get splits for.
-    /// @param rulesetId An identifier within which the returned splits should be considered active.
-    /// @param groupId The identifying group of the splits.
+    /// @param rulesetId The ruleset to look up splits in. Falls back to ruleset 0 if none are found.
+    /// @param groupId The split group ID (e.g. token address for payout groups, or a custom ID for reserved tokens).
     /// @return splits An array of all splits for the project.
     function splitsOf(
         uint256 projectId,
@@ -160,7 +161,7 @@ contract JBSplits is JBControlled, IJBSplits {
     /// @notice Sets the splits for a group given a project, ruleset, and group ID.
     /// @dev The new splits must include any currently set splits that are locked.
     /// @dev The sum of the split `percent`s within one group must be less than 100%.
-    /// @param projectId The ID of the project splits are being set for.
+    /// @param projectId The ID of the project to set splits for.
     /// @param rulesetId The ID of the ruleset the splits should be considered active within.
     /// @param groupId The ID of the group to set the splits within.
     /// @param splits An array of splits to set.
@@ -175,6 +176,7 @@ contract JBSplits is JBControlled, IJBSplits {
         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]})
             ) {