@bananapus/core-v6 0.0.38 → 0.0.39

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
@@ -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 being distributed.
 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,
@@ -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]})
             ) {

package/src/JBTerminalStore.sol

@@ -25,8 +25,12 @@ import {JBPayHookSpecification} from "./structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "./structs/JBRuleset.sol";
 import {JBTokenAmount} from "./structs/JBTokenAmount.sol";
 
-/// @notice Manages all bookkeeping for inflows and outflows of funds from any terminal address.
-/// @dev This contract expects a project's controller to be an `IJBController`.
+/// @notice The accounting engine behind every terminal. Records project balances, enforces payout limits and surplus
+/// allowances, calculates how many tokens to mint per payment (based on the ruleset's weight and currency), and
+/// determines how much a token holder receives when cashing out (via the bonding curve in `JBCashOuts`).
+/// @dev Terminals call `recordPaymentFrom`, `recordPayoutFor`, `recordUsedAllowanceFrom`, and `recordCashOutFor` to
+/// update state. This contract also handles data hook integration — if a ruleset specifies a data hook, it is called
+/// before recording to potentially override token counts or specify pay/cash-out hooks.
 contract JBTerminalStore is IJBTerminalStore {
     // A library that parses the packed ruleset metadata into a friendlier format.
     using JBRulesetMetadataResolver for JBRuleset;
@@ -161,8 +165,9 @@ contract JBTerminalStore is IJBTerminalStore {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Records accounting contexts for a terminal's project tokens.
-    /// @dev Uses msg.sender as the terminal.
+    /// @notice Registers which tokens a terminal can accept for a project, along with their decimal precision and
+    /// currency. Called by the terminal when `addAccountingContextsFor` is invoked.
+    /// @dev Uses `msg.sender` as the terminal address. Reverts if the current ruleset disallows adding contexts.
     /// @param projectId The ID of the project.
     /// @param contexts The accounting contexts to record.
     function recordAccountingContextOf(uint256 projectId, JBAccountingContext[] calldata contexts) external override {
@@ -232,12 +237,11 @@ contract JBTerminalStore is IJBTerminalStore {
         balanceOf[msg.sender][projectId][token] = balanceOf[msg.sender][projectId][token] + amount;
     }
 
-    /// @notice Records a cash out from a project.
-    /// @dev Cashs out the project's tokens according to values provided by the ruleset's data hook. If the ruleset has
-    /// no data hook, cashs out tokens along a cash out bonding curve that is a function of the number of tokens being
-    /// burned.
+    /// @notice Records a cash out — calculates how many terminal tokens a holder receives for burning project tokens.
+    /// @dev Uses the data hook if configured, otherwise applies the bonding curve formula based on cash out tax rate,
+    /// surplus, and supply. The terminal calls this before actually burning tokens and transferring funds.
     /// @param holder The account that is cashing out tokens.
-    /// @param projectId The ID of the project being cashing out from.
+    /// @param projectId The ID of the project being cashed out from.
     /// @param cashOutCount The number of project tokens to cash out, as supplied by the caller and later burned by the
     /// terminal, as a fixed point number with 18 decimals.
     /// @param tokenToReclaim The token being reclaimed by the cash out.
@@ -310,9 +314,9 @@ contract JBTerminalStore is IJBTerminalStore {
         }
     }
 
-    /// @notice Records a payment to a project.
-    /// @dev Mints the project's tokens according to values provided by the ruleset's data hook. If the ruleset has no
-    /// data hook, mints tokens in proportion with the amount paid.
+    /// @notice Records a payment — calculates how many project tokens to mint based on the payment amount and the
+    /// current ruleset's weight. Uses the data hook if configured, otherwise mints proportionally.
+    /// @dev Called by the terminal after accepting funds. Updates the project's recorded balance.
     /// @param payer The address that made the payment to the terminal.
     /// @param amount The amount of tokens being paid. Includes the token being paid, their value, the number of
     /// decimals included, and the currency of the amount.
@@ -353,10 +357,10 @@ contract JBTerminalStore is IJBTerminalStore {
         }
     }
 
-    /// @notice Records a payout from a project.
-    /// @dev The balance is decremented and the used payout limit is incremented before the payout limit validation.
-    /// This is safe because the entire transaction reverts atomically if the validation fails, but callers should
-    /// be aware of this ordering.
+    /// @notice Records a payout — decrements the project's balance and enforces the payout limit. Called by the
+    /// terminal during `sendPayoutsOf`.
+    /// @dev Reverts if the total payouts for this cycle would exceed the ruleset's payout limit. The balance is
+    /// decremented before validation (safe because the entire tx reverts atomically on failure).
     /// @param projectId The ID of the project that is paying out funds.
     /// @param token The token being paid out.
     /// @param amount The amount to pay out (use from the payout limit), as a fixed point number.
@@ -428,7 +432,8 @@ contract JBTerminalStore is IJBTerminalStore {
         usedPayoutLimitOf[msg.sender][projectId][token][ruleset.cycleNumber][currency] = newUsedPayoutLimitOf;
     }
 
-    /// @notice Records the migration of funds from this store.
+    /// @notice Records a terminal migration — zeros out the project's balance and returns the amount being moved to
+    /// the new terminal. The current ruleset must allow terminal migration.
     /// @param projectId The ID of the project being migrated.
     /// @param token The token being migrated.
     /// @return balance The project's current balance (which is being migrated), as a fixed point number with the same
@@ -449,8 +454,10 @@ contract JBTerminalStore is IJBTerminalStore {
         balanceOf[msg.sender][projectId][token] = 0;
     }
 
-    /// @notice Records a use of a project's surplus allowance.
-    /// @dev When surplus allowance is "used", it is taken out of the project's surplus within a terminal.
+    /// @notice Records a surplus allowance withdrawal — takes funds from the project's surplus (the balance above
+    /// payout limits) and enforces the surplus allowance cap.
+    /// @dev Called by the terminal during `useAllowanceOf`. Unlike payouts, surplus withdrawals go directly to a
+    /// beneficiary rather than through splits.
     /// @param projectId The ID of the project to use the surplus allowance of.
     /// @param token The token whose balances should contribute to the surplus allowance being reclaimed from.
     /// @param amount The amount to use from the surplus allowance, as a fixed point number.

package/src/JBTokens.sol

@@ -8,12 +8,12 @@ import {IJBDirectory} from "./interfaces/IJBDirectory.sol";
 import {IJBToken} from "./interfaces/IJBToken.sol";
 import {IJBTokens} from "./interfaces/IJBTokens.sol";
 
-/// @notice Manages minting, burning, and balances of projects' tokens and token credits.
-/// @dev Token balances can either be ERC-20s or token credits. This contract manages these two representations and
-/// allows credit -> ERC-20 claiming.
-/// @dev The total supply of a project's tokens and the balance of each account are calculated in this contract.
-/// @dev An ERC-20 contract must be set by a project's owner for ERC-20 claiming to become available. Projects can bring
-/// their own IJBToken if they prefer.
+/// @notice Manages the dual-token system for every Juicebox project. When someone pays a project, the controller mints
+/// tokens here — initially as internal "credits" tracked by this contract. Once a project deploys or attaches an
+/// ERC-20, holders can claim their credits into transferable ERC-20 tokens. Burns always consume credits first.
+/// @dev The total supply reported by `totalSupplyOf` is credits + ERC-20 supply combined, and is used by the terminal
+/// to calculate cash-out values. Projects can deploy a new ERC-20 via `deployERC20For` or bring their own via
+/// `setTokenFor` (must be 18 decimals).
 contract JBTokens is JBControlled, IJBTokens {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -74,11 +74,11 @@ contract JBTokens is JBControlled, IJBTokens {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Burns (destroys) credits or tokens.
-    /// @dev Credits are burned first, then tokens are burned.
-    /// @dev Only a project's current controller can burn its tokens.
+    /// @notice Destroy a holder's tokens for a project. Credits (internal balance) are burned first; if more tokens
+    /// need burning, the remaining amount is burned from the holder's ERC-20 balance.
+    /// @dev Only a project's current controller can burn its tokens. Called during cash outs and manual burns.
     /// @param holder The address that owns the tokens which are being burned.
-    /// @param projectId The ID of the project to the burned tokens belong to.
+    /// @param projectId The ID of the project the burned tokens belong to.
     /// @param count The number of tokens to burn.
     function burnFrom(address holder, uint256 projectId, uint256 count) external override onlyControllerOf(projectId) {
         // Get a reference to the project's current token.
@@ -131,7 +131,9 @@ contract JBTokens is JBControlled, IJBTokens {
         if (tokensToBurn > 0) token.burn({account: holder, amount: tokensToBurn});
     }
 
-    /// @notice Redeem credits to claim tokens into a holder's wallet.
+    /// @notice Convert internal credits into transferable ERC-20 tokens. The credits are subtracted from the holder's
+    /// balance and the equivalent ERC-20 tokens are minted to the beneficiary. The project must have an ERC-20
+    /// deployed or attached.
     /// @dev Only a project's controller can claim that project's tokens.
     /// @param holder The owner of the credits being redeemed.
     /// @param projectId The ID of the project whose tokens are being claimed.
@@ -180,8 +182,9 @@ contract JBTokens is JBControlled, IJBTokens {
         token.mint({account: beneficiary, amount: count});
     }
 
-    /// @notice Deploys an ERC-20 token for a project. It will be used when claiming tokens.
-    /// @dev Deploys a project's ERC-20 token contract.
+    /// @notice Deploy a new ERC-20 token for a project (cloned from the `TOKEN` implementation). Once deployed, holders
+    /// can claim their credits into this transferable token. A project can only have one token — this reverts if one
+    /// already exists.
     /// @dev Only a project's controller can deploy its token.
     /// @param projectId The ID of the project to deploy an ERC-20 token for.
     /// @param name The ERC-20's name.
@@ -231,8 +234,10 @@ contract JBTokens is JBControlled, IJBTokens {
         token.initialize({name: name, symbol: symbol, tokens: address(this)});
     }
 
-    /// @notice Mint (create) new tokens or credits.
-    /// @dev Only a project's current controller can mint its tokens.
+    /// @notice Create new tokens for a holder. If the project has an ERC-20 deployed, tokens are minted directly to
+    /// the holder's wallet. Otherwise, they're tracked as internal credits that can be claimed later.
+    /// @dev Only a project's current controller can mint its tokens. Called during payments and reserved token
+    /// distribution.
     /// @param holder The address receiving the new tokens.
     /// @param projectId The ID of the project to which the tokens belong.
     /// @param count The number of tokens to mint.
@@ -276,11 +281,12 @@ contract JBTokens is JBControlled, IJBTokens {
         });
     }
 
-    /// @notice Set a project's token if not already set.
+    /// @notice Attach an existing ERC-20 token to a project (instead of deploying a new one). The token must use 18
+    /// decimals and must not already be attached to another project. A project can only have one token.
     /// @dev Only a project's controller can set its token.
-    /// @dev If the provided ERC-20 has a pre-existing supply (minted outside this contract), that supply will be
-    /// included in `totalSupplyOf` and will dilute cash-out calculations for all token holders. Project owners are
-    /// responsible for ensuring the token's supply is appropriate before calling this function.
+    /// @dev WARNING: If the ERC-20 has supply minted outside this contract, that supply will be included in
+    /// `totalSupplyOf` and dilute cash-out values for all holders. Ensure the token's supply is appropriate before
+    /// calling.
     /// @param projectId The ID of the project to set the token of.
     /// @param token The new token's address.
     function setTokenFor(uint256 projectId, IJBToken token) external override onlyControllerOf(projectId) {
@@ -308,7 +314,8 @@ contract JBTokens is JBControlled, IJBTokens {
         emit SetToken({projectId: projectId, token: token, caller: msg.sender});
     }
 
-    /// @notice Sets the name and symbol of a project's token.
+    /// @notice Update the name and symbol of a project's ERC-20 token. The project must already have a token deployed
+    /// or attached.
     /// @dev Only a project's controller can set the token's name and symbol.
     /// @param projectId The ID of the project whose token is being updated.
     /// @param name The new name.
@@ -340,7 +347,8 @@ contract JBTokens is JBControlled, IJBTokens {
         token.setMetadata({name: name, symbol: symbol});
     }
 
-    /// @notice Allows a holder to transfer credits to another account.
+    /// @notice Move internal credits from one account to another. Credits are non-transferable on their own (they're
+    /// just a balance in this contract), so this function enables transfers via the controller.
     /// @dev Only a project's controller can transfer credits for that project.
     /// @param holder The address to transfer credits from.
     /// @param projectId The ID of the project whose credits are being transferred.
@@ -379,7 +387,8 @@ contract JBTokens is JBControlled, IJBTokens {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice The total balance a holder has for a specified project, including both tokens and token credits.
+    /// @notice Get a holder's complete balance for a project — both their internal credits and their ERC-20 token
+    /// balance combined.
     /// @param holder The holder to get a balance for.
     /// @param projectId The project to get the `holder`'s balance for.
     /// @return balance The combined token and token credit balance of the `holder`.
@@ -400,11 +409,12 @@ contract JBTokens is JBControlled, IJBTokens {
     // --------------------------- public views -------------------------- //
     //*********************************************************************//
 
-    /// @notice The total supply for a specific project, including both tokens and token credits.
-    /// @dev WARNING: Projects that use `setTokenFor` with an external ERC-20 inherit that token's supply manipulation
+    /// @notice Get the total token supply for a project — internal credits plus the ERC-20's `totalSupply()`. This is
+    /// the denominator used in cash-out bonding curve calculations.
+    /// @dev WARNING: Projects using `setTokenFor` with an external ERC-20 inherit that token's supply manipulation
     /// surface. If the external token has a separate minting authority, `totalSupply()` can be inflated outside of
-    /// this contract, which dilutes cash-out values for all holders. Projects using `deployERC20For` are safe because
-    /// the resulting `JBERC20` is exclusively owned by this `JBTokens` contract.
+    /// this contract, diluting cash-out values for all holders. Projects using `deployERC20For` are safe because the
+    /// resulting `JBERC20` is exclusively owned by this `JBTokens` contract.
     /// @param projectId The ID of the project to get the total supply of.
     /// @return totalSupply The total supply of the project's tokens and token credits.
     function totalSupplyOf(uint256 projectId) public view override returns (uint256 totalSupply) {

package/src/abstract/JBControlled.sol

@@ -4,7 +4,9 @@ pragma solidity 0.8.28;
 import {IJBControlled} from "./../interfaces/IJBControlled.sol";
 import {IJBDirectory} from "./../interfaces/IJBDirectory.sol";
 
-/// @notice Provides a modifier for contracts with functionality that can only be accessed by a project's controller.
+/// @notice Base contract that restricts certain functions to the project's current controller (as registered in
+/// `JBDirectory`). Used by `JBTokens`, `JBSplits`, `JBFundAccessLimits`, `JBRulesets`, and `JBPrices` to ensure only
+/// the controller can update project state.
 abstract contract JBControlled is IJBControlled {
     //*********************************************************************//
     // --------------------------- custom errors -------------------------- //

package/src/abstract/JBPermissioned.sol

@@ -6,7 +6,9 @@ import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IJBPermissioned} from "./../interfaces/IJBPermissioned.sol";
 import {IJBPermissions} from "./../interfaces/IJBPermissions.sol";
 
-/// @notice Modifiers to allow access to transactions based on which permissions the message's sender has.
+/// @notice Base contract that provides permission-checking helpers. Contracts that inherit this can require that the
+/// caller either *is* the account or has been granted a specific permission by that account (via `JBPermissions`).
+/// @dev Used by `JBController`, `JBMultiTerminal`, `JBDirectory`, and others to enforce operator authorization.
 abstract contract JBPermissioned is Context, IJBPermissioned {
     //*********************************************************************//
     // --------------------------- custom errors -------------------------- //

package/src/enums/JBApprovalStatus.sol

@@ -1,7 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @notice A ruleset's approval status in a ruleset approval hook.
+/// @notice The lifecycle states a queued ruleset can be in relative to its approval hook.
+/// @dev `Empty` — no ruleset exists. `Upcoming` — queued but not yet eligible for approval check. `Active` —
+/// currently
+/// governing the project. `ApprovalExpected` — the deadline hasn't passed yet, expected to be approved.
+/// `Approved` — passed the approval hook and will take effect. `Failed` — rejected by the approval hook; the
+/// previous
+/// ruleset continues.
 enum JBApprovalStatus {
     Empty,
     Upcoming,

package/src/interfaces/IJBController.sol

@@ -23,8 +23,9 @@ import {JBSplit} from "./../structs/JBSplit.sol";
 import {JBSplitGroup} from "./../structs/JBSplitGroup.sol";
 import {JBTerminalConfig} from "./../structs/JBTerminalConfig.sol";
 
-/// @notice Coordinates rulesets and project tokens, and is the entry point for most operations related to rulesets and
-/// project tokens.
+/// @notice The interface for the protocol's project controller — launch projects, queue rulesets, mint/burn tokens,
+/// deploy ERC-20s, distribute reserved tokens, and manage all project configuration. This is the primary contract
+/// project owners and frontends interact with.
 interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessControl {
     /// @notice Tokens were burned from a holder's balance.
     /// @param holder The address whose tokens were burned.

package/src/interfaces/IJBDirectory.sol

@@ -6,7 +6,9 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IJBProjects} from "./IJBProjects.sol";
 import {IJBTerminal} from "./IJBTerminal.sol";
 
-/// @notice Tracks the terminals and the controller used by each project.
+/// @notice Interface for the protocol's routing table. Tracks which terminals accept payments for each project and
+/// which controller manages each project's rulesets and tokens. Used by frontends and contracts to discover where to
+/// send funds.
 interface IJBDirectory {
     /// @notice A terminal was added to a project.
     /// @param projectId The ID of the project the terminal was added to.

package/src/interfaces/IJBMultiTerminal.sol

@@ -12,8 +12,9 @@ import {IJBTerminal} from "./IJBTerminal.sol";
 import {IJBTerminalStore} from "./IJBTerminalStore.sol";
 import {IJBTokens} from "./IJBTokens.sol";
 
-/// @notice A terminal that manages native/ERC-20 payments, cash outs, and surplus allowance usage for any number of
-/// projects.
+/// @notice The interface for the protocol's multi-token payment terminal. Accepts ETH and ERC-20 payments, processes
+/// cash outs (token redemptions), distributes payouts to splits, manages surplus allowance withdrawals, and handles
+/// the 2.5% protocol fee lifecycle. The primary entry point for all fund movement in Juicebox.
 interface IJBMultiTerminal is IJBTerminal, IJBFeeTerminal, IJBCashOutTerminal, IJBPayoutTerminal, IJBPermitTerminal {
     /// @notice The directory of terminals and controllers for projects.
     function DIRECTORY() external view returns (IJBDirectory);