@bananapus/core-v6 0.0.81 → 0.0.82

package/README.md

@@ -36,7 +36,7 @@ Use this repo when you need the protocol's canonical accounting and execution lo
 
 If you only read one V6 repo before reading the rest, read this one.
 
-## Mental Model
+## Mental model
 
 It helps to think about core in four layers:
 
@@ -54,7 +54,7 @@ The shortest reading path is:
 3. `JBTerminalStore` for the accounting model
 4. `JBDirectory` and `JBPermissions` for routing and authority
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBController.sol`
 2. `src/JBMultiTerminal.sol`
@@ -63,7 +63,7 @@ The shortest reading path is:
 5. `src/JBRulesets.sol`
 6. `src/JBPermissions.sol`
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -75,14 +75,14 @@ The shortest reading path is:
 | `JBPermissions` | Packed operator-permission registry. |
 | `JBPrices` | Price-feed routing used by terminals and integrations. |
 
-## Integration Traps
+## Integration traps
 
 - `JBMultiTerminal` is multi-token and multi-terminal. Do not assume one token or one balance.
 - Data hooks and cash-out hooks can change economics and side effects. They are part of the protocol surface.
 - Permission checks are not always against the project owner. Some flows are scoped to the token holder instead.
 - Preview and execution are intentionally close, but callers should still treat them as separate surfaces when hooks or routing can change behavior.
 
-## Where State Lives
+## Where state lives
 
 - project identity and ownership: `JBProjects`
 - controller and terminal routing: `JBDirectory`
@@ -92,7 +92,7 @@ The shortest reading path is:
 
 When a flow is unclear, read the contract that owns the state before the contract that forwards into it.
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/TestPayBurnRedeemFlow.sol`
 2. `test/TestTerminalPreviewParity.sol`
@@ -122,11 +122,11 @@ Useful scripts:
 - `npm run deploy:mainnets:periphery`
 - `npm run deploy:testnets:periphery`
 
-## Deployment Notes
+## Deployment notes
 
 This repo contains the main core deployments and periphery deployment helpers. Most other V6 packages assume these contracts exist first and treat them as the stable base layer.
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -139,7 +139,7 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 See [RISKS.md](./RISKS.md) for the full risk register. In short:
 
@@ -150,7 +150,7 @@ See [RISKS.md](./RISKS.md) for the full risk register. In short:
 
 The easiest way to misread V6 is to treat core like a simple crowdfunding terminal. It is closer to a configurable accounting and settlement layer.
 
-## For AI Agents
+## For AI agents
 
 - Start with `JBController`, `JBMultiTerminal`, and `JBTerminalStore`.
 - Keep controller configuration, terminal execution, and store accounting separate in your mental model.

package/package.json

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

package/references/entrypoints.md

@@ -28,7 +28,7 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `JBDeadline` | Approval hook: rejects rulesets queued within `DURATION` seconds of start. Ships as `JBDeadline3Hours`, `JBDeadline1Day`, `JBDeadline3Days`, `JBDeadline7Days`. |
 | `JBMatchingPriceFeed` | Always returns 1:1. For equivalent currencies (e.g. ETH/NATIVE_TOKEN). |
 
-## Key Functions
+## Key functions
 
 ### JBController
 

package/references/types-errors-events.md

@@ -2,7 +2,7 @@
 
 Use this file when you need deeper protocol reference material after the repo-local `SKILLS.md` has already routed you to `nana-core-v6`.
 
-## Key Types
+## Key types
 
 | Struct/Enum | Key Fields | Used In |
 |-------------|------------|---------|
@@ -23,7 +23,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | `JBRulesetWeightCache` | `weight (uint112)`, `weightCutMultiple (uint168)` | Weight caching for long-running rulesets in `JBRulesets` |
 | `JBApprovalStatus` (enum) | `Empty`, `Upcoming`, `Active`, `ApprovalExpected`, `Approved`, `Failed` | Approval hook status for queued rulesets |
 
-### Hook Structs
+### Hook structs
 
 | Struct | Key Fields | Used In |
 |--------|------------|---------|
@@ -53,13 +53,13 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | `1` | ETH |
 | `2` | USD |
 
-### Split Group IDs (`JBSplitGroupIds`)
+### Split group IDs (`JBSplitGroupIds`)
 
 | ID | Group |
 |----|-------|
 | `1` | `RESERVED_TOKENS` -- reserved token distribution |
 
-### Special Values
+### Special values
 
 | Value | Context | Meaning |
 |-------|---------|---------|
@@ -143,7 +143,7 @@ Quick-reference for the most common `JBPermissionIds` values (from `@bananapus/p
 
 IDs 22-33 are used by extension contracts (721 hook, buyback hook, router terminal, suckers).
 
-## Common Errors
+## Common errors
 
 Errors an agent is most likely to encounter. All are custom errors (revert with selector).
 
@@ -187,7 +187,7 @@ Errors an agent is most likely to encounter. All are custom errors (revert with
 | `JBRulesets_InvalidWeightCutPercent` | `JBRulesets` | `weightCutPercent` exceeds `MAX_WEIGHT_CUT_PERCENT`. |
 | `JBFundAccessLimits_InvalidPayoutLimitCurrencyOrdering` | `JBFundAccessLimits` | Payout limit currencies not in strictly increasing order. |
 
-## Key Events
+## Key events
 
 The most important events for indexing and off-chain monitoring. Indexed params marked with `*`.
 
@@ -220,7 +220,7 @@ The most important events for indexing and off-chain monitoring. Indexed params
 | `SetSplit` | `IJBSplits` | (projectId, rulesetId, groupId, split, caller) |
 | `AddPriceFeed` | `IJBPrices` | (projectId, pricingCurrency, unitCurrency, feed, caller) |
 
-## Hook Interface Return Types
+## Hook interface return types
 
 ### `IJBRulesetDataHook.beforePayRecordedWith()`
 
@@ -260,7 +260,7 @@ function hasMintPermissionFor(uint256 projectId, JBRuleset memory ruleset, addre
 
 Returns whether `addr` is allowed to mint tokens for the project. Called by `JBController.mintTokensOf` when the caller is not the owner and `allowOwnerMinting` is false -- the data hook can grant mint permission to specific addresses (e.g. suckers for omnichain bridging).
 
-## Example Integration
+## Example integration
 
 ```solidity
 // SPDX-License-Identifier: MIT

package/src/JBChainlinkV3PriceFeed.sol

@@ -17,8 +17,13 @@ contract JBChainlinkV3PriceFeed is IJBPriceFeed {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the feed round is not finished or was not answered in the current round.
     error JBChainlinkV3PriceFeed_IncompleteRound(uint80 roundId, uint80 answeredInRound, uint256 updatedAt);
+
+    /// @notice Thrown when the feed reports a non-positive price.
     error JBChainlinkV3PriceFeed_NegativePrice(int256 price);
+
+    /// @notice Thrown when the feed's last update is older than the staleness threshold.
     error JBChainlinkV3PriceFeed_StalePrice(uint256 timestamp, uint256 threshold, uint256 updatedAt);
 
     //*********************************************************************//

package/src/JBChainlinkV3SequencerPriceFeed.sol

@@ -14,7 +14,10 @@ contract JBChainlinkV3SequencerPriceFeed is JBChainlinkV3PriceFeed {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the sequencer uptime round is invalid (e.g. the uptime contract is not yet initialized).
     error JBChainlinkV3SequencerPriceFeed_InvalidRound(uint256 startedAt);
+
+    /// @notice Thrown when the L2 sequencer is down or has restarted too recently for the grace period to elapse.
     error JBChainlinkV3SequencerPriceFeed_SequencerDownOrRestarting(
         uint256 timestamp, uint256 gracePeriodTime, uint256 startedAt
     );

package/src/JBController.sol

@@ -58,21 +58,52 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the project's current ruleset does not allow adding price feeds.
     error JBController_AddingPriceFeedNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when transferring credits while the current ruleset pauses credit transfers.
     error JBController_CreditTransfersPaused(uint256 projectId, uint256 rulesetId);
+
+    /// @notice Thrown when the cash out tax rate exceeds the allowed maximum.
     error JBController_InvalidCashOutTaxRate(uint256 rate, uint256 limit);
+
+    /// @notice Thrown when the native value sent does not equal the required creation fee.
     error JBController_InvalidCreationFee(uint256 value, uint256 requiredFee);
+
+    /// @notice Thrown when the reserved percent exceeds the allowed maximum.
     error JBController_InvalidReservedPercent(uint256 percent, uint256 limit);
+
+    /// @notice Thrown when the caller is not allowed to mint and is not a terminal or data hook for the project.
     error JBController_MintNotAllowedAndNotTerminalOrHook(address caller);
+
+    /// @notice Thrown when there are no reserved tokens to send to splits.
     error JBController_NoReservedTokens(uint256 projectId);
+
+    /// @notice Thrown when the caller is not the directory.
     error JBController_OnlyDirectory(address sender, IJBDirectory directory);
+
+    /// @notice Thrown when migrating a project that still has pending reserved tokens.
     error JBController_PendingReservedTokens(uint256 pendingReservedTokenBalance);
+
+    /// @notice Thrown when a reserved token split routes back into the same project via the terminal-payment path.
     error JBController_ReservedTokenSplitProjectSameAsOwner(uint256 projectId);
+
+    /// @notice Thrown when launching rulesets for a project that has already launched.
     error JBController_RulesetsAlreadyLaunched(uint256 projectId);
+
+    /// @notice Thrown when the ruleset configurations array is empty.
     error JBController_RulesetsArrayEmpty(uint256 projectId, uint256 rulesetConfigurationCount);
+
+    /// @notice Thrown when the project's current ruleset does not allow setting a custom token.
     error JBController_RulesetSetTokenNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when the terminal did not pull the full token allowance during a payout.
     error JBController_TerminalTokensNotTransferred(address terminal, address token, uint256 allowance);
+
+    /// @notice Thrown when attempting to burn zero tokens.
     error JBController_ZeroTokensToBurn(uint256 projectId, address holder);
+
+    /// @notice Thrown when attempting to mint zero tokens.
     error JBController_ZeroTokensToMint(uint256 projectId, address beneficiary);
 
     //*********************************************************************//
@@ -707,7 +738,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         // If there's no current ruleset, get a reference to the upcoming one.
         if (ruleset.id == 0) ruleset = _upcomingRulesetOf(projectId);
 
-        // If owner minting is disabled for the ruleset, the owner cannot change the token.
+        // If the ruleset doesn't allow setting a custom token, the owner cannot change the token.
         if (!ruleset.allowSetCustomToken()) revert JBController_RulesetSetTokenNotAllowed(projectId);
 
         TOKENS.setTokenFor({projectId: projectId, token: token});
@@ -783,8 +814,8 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
     /// @notice Returns a paginated history of a project's rulesets (with decoded metadata), 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 the
-    /// `startingId` is 0, passed, the project's latest ruleset will be used.
+    /// @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.
     /// @param size The maximum number of rulesets to return.
     /// @return rulesets The array of rulesets with their metadata.
     function allRulesetsOf(
@@ -1320,7 +1351,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         return RULESETS.currentOf(projectId);
     }
 
-    /// @notice Indicates whether the provided address has mint permission for the project byway of the data hook.
+    /// @notice Indicates whether the provided address has mint permission for the project by way of the data hook.
     /// @param projectId The ID of the project to check.
     /// @param ruleset The ruleset to check.
     /// @param addr The address to check.

package/src/JBDirectory.sol

@@ -23,10 +23,19 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the same terminal appears more than once in the provided terminals list.
     error JBDirectory_DuplicateTerminals(IJBTerminal terminal);
+
+    /// @notice Thrown when the project ID is greater than the number of existing projects.
     error JBDirectory_InvalidProjectIdInDirectory(uint256 projectId, uint256 limit);
+
+    /// @notice Thrown when the project's current controller does not allow setting a new controller.
     error JBDirectory_SetControllerNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when the project's current controller does not allow setting terminals.
     error JBDirectory_SetTerminalsNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when the terminal being set as primary does not accept the given token.
     error JBDirectory_TokenNotAccepted(uint256 projectId, address token, IJBTerminal terminal);
 
     //*********************************************************************//

package/src/JBERC20.sol

@@ -25,7 +25,10 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when initializing a token that already has a name set, or when the provided name is empty.
     error JBERC20_AlreadyInitialized(uint256 currentNameLength, uint256 newNameLength);
+
+    /// @notice Thrown when the caller is not the JBTokens contract that owns this token.
     error JBERC20_Unauthorized(address caller, address tokens);
 
     //*********************************************************************//

package/src/JBFeelessAddresses.sol

@@ -16,6 +16,7 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the provided feeless hook does not support the `IJBFeelessHook` interface.
     error JBFeelessAddresses_InvalidFeelessHook(IJBFeelessHook hook);
 
     //*********************************************************************//
@@ -33,6 +34,8 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
 
     /// @notice Raw feeless status per project per address.
     /// @dev `projectId = 0` stores the global (all-project) feeless status.
+    /// @custom:param projectId The ID of the project. A `projectId` of 0 is the global (all-project) key.
+    /// @custom:param addr The address whose feeless status is being stored.
     mapping(uint256 projectId => mapping(address addr => bool)) internal _isFeelessFor;
 
     //*********************************************************************//

package/src/JBFundAccessLimits.sol

@@ -18,12 +18,17 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when two fund access limit groups share the same terminal and token.
     error JBFundAccessLimits_DuplicateFundAccessLimitGroup(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, address terminal, address token
     );
+
+    /// @notice Thrown when payout limits within a group are not ordered by ascending currency.
     error JBFundAccessLimits_InvalidPayoutLimitCurrencyOrdering(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, uint256 limitIndex
     );
+
+    /// @notice Thrown when surplus allowances within a group are not ordered by ascending currency.
     error JBFundAccessLimits_InvalidSurplusAllowanceCurrencyOrdering(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, uint256 allowanceIndex
     );

package/src/JBMultiTerminal.sol

@@ -66,18 +66,43 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when no terminal can be found to pay a fee in the given token.
     error JBMultiTerminal_FeeTerminalNotFound(address token);
+
+    /// @notice Thrown when a payout split routes back into the project that is paying out.
     error JBMultiTerminal_MintNotAllowed(uint256 projectId, address terminal);
+
+    /// @notice Thrown when native value is sent with an operation that does not accept it.
     error JBMultiTerminal_NoMsgValueAllowed(uint256 value);
+
+    /// @notice Thrown when a value exceeds the allowed maximum.
     error JBMultiTerminal_OverflowAlert(uint256 value, uint256 limit);
+
+    /// @notice Thrown when the Permit2 allowance is less than the amount being paid.
     error JBMultiTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
+
+    /// @notice Thrown when no terminal can be found to pay a recipient project's split in the given token.
     error JBMultiTerminal_RecipientProjectTerminalNotFound(uint256 projectId, address token);
+
+    /// @notice Thrown when a token transfer reenters during a balance-delta measurement.
     error JBMultiTerminal_ReentrantTokenTransfer(address token);
+
+    /// @notice Thrown when a split hook does not support the `IJBSplitHook` interface.
     error JBMultiTerminal_SplitHookInvalid(IJBSplitHook hook);
+
+    /// @notice Thrown when an approved temporary allowance was not fully consumed by the spender.
     error JBMultiTerminal_TemporaryAllowanceNotConsumed(address token, address spender, uint256 allowance);
+
+    /// @notice Thrown when migrating a terminal to itself.
     error JBMultiTerminal_TerminalMigrationToSelf(uint256 projectId, address token);
+
+    /// @notice Thrown when the terminal being migrated to does not accept the same token.
     error JBMultiTerminal_TerminalTokensIncompatible(uint256 projectId, address token, IJBTerminal terminal);
+
+    /// @notice Thrown when the terminal does not accept the given token.
     error JBMultiTerminal_TokenNotAccepted(address token);
+
+    /// @notice Thrown when a value is less than the required minimum.
     error JBMultiTerminal_UnderMin(uint256 value, uint256 min);
 
     //*********************************************************************//
@@ -109,7 +134,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice The contract that stores and manages the terminal's data.
     IJBTerminalStore public immutable override STORE;
 
-    /// @notice The contract storing and managing project rulesets.
+    /// @notice The contract that manages token minting and burning.
     IJBTokens public immutable override TOKENS;
 
     //*********************************************************************//

package/src/JBPermissions.sol

@@ -17,8 +17,13 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when attempting to set the reserved permission ID 0.
     error JBPermissions_NoZeroPermission(address account, address operator, uint256 projectId);
+
+    /// @notice Thrown when a permission ID is greater than the maximum of 255.
     error JBPermissions_PermissionIdOutOfBounds(uint256 permissionId);
+
+    /// @notice Thrown when the caller is not the account and lacks ROOT permission to set permissions on its behalf.
     error JBPermissions_Unauthorized(address account, address operator, uint256 projectId, uint256 permissionId);
 
     //*********************************************************************//

package/src/JBPrices.sol

@@ -23,10 +23,19 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when adding a price feed that is already registered for the same currency pair.
     error JBPrices_PriceFeedAlreadyAdded(IJBPriceFeed feed);
+
+    /// @notice Thrown when no configured price feed can be found for the requested currency pair.
     error JBPrices_PriceFeedNotFound(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency);
+
+    /// @notice Thrown when the provided price feed is the zero address.
     error JBPrices_ZeroPriceFeed();
+
+    /// @notice Thrown when the pricing currency provided is zero.
     error JBPrices_ZeroPricingCurrency(uint256 projectId, uint256 pricingCurrency);
+
+    /// @notice Thrown when the unit currency provided is zero.
     error JBPrices_ZeroUnitCurrency(uint256 projectId, uint256 unitCurrency);
 
     //*********************************************************************//

package/src/JBProjects.sol

@@ -18,8 +18,13 @@ contract JBProjects is ERC721, ERC2771Context, Ownable, IJBProjects {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the configured creation fee exceeds the allowed maximum.
     error JBProjects_CreationFeeExceedsMax(uint256 fee, uint256 max);
+
+    /// @notice Thrown when the native value sent does not equal the required creation fee.
     error JBProjects_InvalidCreationFee(uint256 value, uint256 requiredFee);
+
+    /// @notice Thrown when a non-zero creation fee is configured without a fee receiver.
     error JBProjects_ZeroCreationFeeReceiver();
 
     //*********************************************************************//

package/src/JBRulesets.sol

@@ -25,11 +25,23 @@ contract JBRulesets is JBControlled, IJBRulesets {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the approval hook is not a contract or does not support the `IJBRulesetApprovalHook`
+    /// interface.
     error JBRulesets_InvalidRulesetApprovalHook(IJBRulesetApprovalHook hook);
+
+    /// @notice Thrown when the ruleset duration exceeds the uint32 maximum.
     error JBRulesets_InvalidRulesetDuration(uint256 duration, uint256 limit);
+
+    /// @notice Thrown when the ruleset's start plus duration exceeds the uint48 maximum.
     error JBRulesets_InvalidRulesetEndTime(uint256 timestamp, uint256 limit);
+
+    /// @notice Thrown when the ruleset weight exceeds the uint112 maximum.
     error JBRulesets_InvalidWeight(uint256 weight, uint256 limit);
+
+    /// @notice Thrown when the weight cut percent exceeds 100%.
     error JBRulesets_InvalidWeightCutPercent(uint256 percent);
+
+    /// @notice Thrown when too many weight-cut iterations remain and the weight cache must be populated first.
     error JBRulesets_WeightCacheRequired(uint256 projectId);
 
     //*********************************************************************//
@@ -396,8 +408,8 @@ contract JBRulesets is JBControlled, IJBRulesets {
             // Get a reference to the approval status.
             JBApprovalStatus approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: ruleset});
 
-            // While the ruleset has a approval hook that isn't approved or if it hasn't yet started, get a reference to
-            // the ruleset that the latest is based on, which has the latest approved configuration.
+            // While the ruleset has an approval hook that isn't approved or if it hasn't yet started, get a reference
+            // to 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)
@@ -472,7 +484,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // Keep a reference to its approval status.
         JBApprovalStatus approvalStatus;
 
-        // If an upcoming approvable ruleset has been queued, and it's approval status is Approved or ApprovalExpected,
+        // If an upcoming approvable ruleset has been queued, and its approval status is Approved or ApprovalExpected,
         // return its ruleset struct
         if (upcomingApprovableRulesetId != 0) {
             ruleset = _getStructFor({projectId: projectId, rulesetId: upcomingApprovableRulesetId, withMetadata: true});
@@ -495,7 +507,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
             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
+            // Since it's 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) {
@@ -723,7 +735,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
         // Get a reference to the approval status.
         JBApprovalStatus approvalStatus = _approvalStatusOf({projectId: projectId, ruleset: baseRuleset});
 
-        // If the base ruleset has started but wasn't approved if a approval hook exists
+        // If the base ruleset has started but wasn't approved if an approval hook exists
         // OR it hasn't started but is currently approved
         // 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.

package/src/JBSplits.sol

@@ -19,8 +19,13 @@ contract JBSplits is JBControlled, IJBSplits {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when a new set of splits omits a still-locked split from the previous set.
     error JBSplits_PreviousLockedSplitsNotIncluded(uint256 projectId, uint256 rulesetId);
+
+    /// @notice Thrown when the splits in a group sum to more than 100%.
     error JBSplits_TotalPercentExceeds100(uint256 projectId, uint256 rulesetId, uint256 groupId, uint256 percentTotal);
+
+    /// @notice Thrown when a split is configured with a percent of zero.
     error JBSplits_ZeroSplitPercent(uint256 projectId, uint256 rulesetId, uint256 groupId, uint256 splitIndex);
 
     //*********************************************************************//

package/src/JBTerminalStore.sol

@@ -39,22 +39,48 @@ contract JBTerminalStore is IJBTerminalStore {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when setting an accounting context for a token that already has one.
     error JBTerminalStore_AccountingContextAlreadySet(address token);
+
+    /// @notice Thrown when a token's provided decimals do not match the decimals it reports.
     error JBTerminalStore_AccountingContextDecimalsMismatch(
         address token, uint256 providedDecimals, uint256 expectedDecimals
     );
+
+    /// @notice Thrown when a token's decimals are outside the supported range.
     error JBTerminalStore_AccountingContextDecimalsOutOfRange(address token, uint256 decimals);
+
+    /// @notice Thrown when the project's current ruleset does not allow adding accounting contexts.
     error JBTerminalStore_AddingAccountingContextNotAllowed(uint256 projectId, uint256 rulesetId, address terminal);
+
+    /// @notice Thrown when the used surplus allowance exceeds the amount the controller granted.
     error JBTerminalStore_InadequateControllerAllowance(uint256 amount, uint256 allowance);
 
+    /// @notice Thrown when the amount to use exceeds the terminal's recorded balance or surplus.
     error JBTerminalStore_InadequateTerminalStoreBalance(uint256 amount, uint256 balance);
+
+    /// @notice Thrown when cashing out more tokens than the effective total supply.
     error JBTerminalStore_InsufficientTokens(uint256 count, uint256 totalSupply);
+
+    /// @notice Thrown when a hook specification asks to forward more than the amount paid.
     error JBTerminalStore_InvalidAmountToForwardHook(uint256 amount, uint256 paidAmount);
+
+    /// @notice Thrown when a hook specification is flagged as a no-op but carries a non-zero amount.
     error JBTerminalStore_NoopHookSpecHasAmount(uint256 amount);
+
+    /// @notice Thrown when the project has no current ruleset.
     error JBTerminalStore_RulesetNotFound(uint256 projectId);
+
+    /// @notice Thrown when paying a project whose current ruleset pauses payments.
     error JBTerminalStore_RulesetPaymentPaused(uint256 projectId, uint256 rulesetId);
+
+    /// @notice Thrown when the project's current ruleset does not allow terminal migration.
     error JBTerminalStore_TerminalMigrationNotAllowed(uint256 projectId, uint256 rulesetId);
+
+    /// @notice Thrown when a value to record exceeds the uint224 maximum.
     error JBTerminalStore_Uint224Overflow(uint256 value);
+
+    /// @notice Thrown when an accounting context's currency is zero.
     error JBTerminalStore_ZeroAccountingContextCurrency(address token);
 
     //*********************************************************************//
@@ -465,7 +491,7 @@ contract JBTerminalStore is IJBTerminalStore {
             revert JBTerminalStore_InadequateTerminalStoreBalance({amount: amountPaidOut, balance: currentBalance});
         }
 
-        // Removed the paid out funds from the project's token balance.
+        // Remove the paid out funds from the project's token balance.
         unchecked {
             balanceOf[msg.sender][projectId][token] = currentBalance - amountPaidOut;
         }
@@ -1137,7 +1163,7 @@ contract JBTerminalStore is IJBTerminalStore {
         if (weight == 0) return (ruleset, 0, hookSpecifications, balanceDiff);
 
         // If the terminal should base its weight on a currency other than the terminal's currency, determine the
-        // factor. The weight is always a fixed point mumber with 18 decimals. To ensure this, the ratio should use the
+        // factor. The weight is always a fixed point number with 18 decimals. To ensure this, the ratio should use the
         // same
         // number of decimals as the `amount`.
         uint256 weightRatio = amount.currency == ruleset.baseCurrency()
@@ -1330,7 +1356,7 @@ contract JBTerminalStore is IJBTerminalStore {
             : mulDiv({
                 x: surplus,
                 y: 10 ** _MAX_FIXED_POINT_FIDELITY, // Use `_MAX_FIXED_POINT_FIDELITY` to keep as much of the
-                // `_payoutLimitRemaining`'s fidelity as possible when converting.
+                // surplus's fidelity as possible when converting.
                 denominator: PRICES.pricePerUnitOf({
                     projectId: projectId,
                     pricingCurrency: accountingContext.currency,

package/src/JBTokens.sol

@@ -19,16 +19,37 @@ contract JBTokens is JBControlled, IJBTokens {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when deploying a token with an empty name.
     error JBTokens_EmptyName(uint256 projectId);
+
+    /// @notice Thrown when deploying a token with an empty symbol.
     error JBTokens_EmptySymbol(uint256 projectId);
+
+    /// @notice Thrown when the token to set is the zero address.
     error JBTokens_EmptyToken(uint256 projectId);
+
+    /// @notice Thrown when burning more credits than the holder's credit balance.
     error JBTokens_InsufficientCredits(uint256 count, uint256 creditBalance);
+
+    /// @notice Thrown when burning more tokens than the holder's combined token and credit balance.
     error JBTokens_InsufficientTokensToBurn(uint256 count, uint256 tokenBalance);
+
+    /// @notice Thrown when minting would push the total supply past the uint208 maximum.
     error JBTokens_OverflowAlert(uint256 value, uint256 limit);
+
+    /// @notice Thrown when the project already has a token set.
     error JBTokens_ProjectAlreadyHasToken(IJBToken token);
+
+    /// @notice Thrown when the token is already in use by another project.
     error JBTokens_TokenAlreadyBeingUsed(uint256 projectId);
+
+    /// @notice Thrown when the token reports that it cannot be added to the project.
     error JBTokens_TokenCantBeAdded(uint256 projectId);
+
+    /// @notice Thrown when the project has no token set.
     error JBTokens_TokenNotFound(uint256 projectId);
+
+    /// @notice Thrown when the token does not use 18 decimals.
     error JBTokens_TokensMustHave18Decimals(uint256 decimals);
 
     //*********************************************************************//

package/src/abstract/JBControlled.sol

@@ -12,6 +12,7 @@ abstract contract JBControlled is IJBControlled {
     // --------------------------- custom errors -------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the caller is not the controller of the specified project.
     error JBControlled_ControllerUnauthorized(address controller);
 
     //*********************************************************************//

package/src/abstract/JBPermissioned.sol

@@ -14,6 +14,7 @@ abstract contract JBPermissioned is Context, IJBPermissioned {
     // --------------------------- custom errors -------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the sender lacks the required permission from the account to perform the operation.
     error JBPermissioned_Unauthorized(address account, address sender, uint256 projectId, uint256 permissionId);
 
     //*********************************************************************//

package/src/enums/JBApprovalStatus.sol

@@ -2,12 +2,12 @@
 pragma solidity ^0.8.0;
 
 /// @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.
+/// @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/libraries/JBMetadataResolver.sol

@@ -25,9 +25,16 @@ pragma solidity 0.8.28;
  *            +-----------------------+
  */
 library JBMetadataResolver {
+    /// @notice Thrown when the data to add is not padded to a multiple of 32 bytes.
     error JBMetadataResolver_DataNotPadded(uint256 dataLength);
+
+    /// @notice Thrown when the IDs and datas arrays have mismatched lengths.
     error JBMetadataResolver_LengthMismatch(uint256 idsLength, uint256 datasLength);
+
+    /// @notice Thrown when the metadata offset exceeds the maximum addressable offset of 255.
     error JBMetadataResolver_MetadataTooLong(uint256 offset, uint256 maxOffset);
+
+    /// @notice Thrown when the metadata is shorter than the minimum required length.
     error JBMetadataResolver_MetadataTooShort(uint256 metadataLength, uint256 minMetadataLength);
 
     // Constants alphabetized per STYLE_GUIDE; trailing comments document derivation.
@@ -260,7 +267,7 @@ library JBMetadataResolver {
             if (parsedId == id) {
                 // Are we at the end of the lookup table (either at the start of data's or next offset is 0/in the
                 // padding)
-                // If not, only return until from this offset to the begining of the next offset
+                // If not, only return until from this offset to the beginning of the next offset
                 uint256 end = (i + NEXT_ID_OFFSET >= firstOffset * WORD_SIZE || metadata[i + NEXT_ID_OFFSET] == 0)
                     ? metadata.length
                     : uint256(uint8(metadata[i + NEXT_ID_OFFSET])) * WORD_SIZE;
@@ -295,6 +302,7 @@ library JBMetadataResolver {
     /// @param start The start index to slice at.
     /// @param end The end index to slice at.
     /// @param slicedBytes The sliced array.
+    /// @return slicedBytes The sliced array.
     function _sliceBytes(bytes memory data, uint256 start, uint256 end)
         private
         pure

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -44,8 +44,22 @@ interface IJBPayoutSplitGroupExecutor {
 /// @dev Extracted as an external library to reduce `JBMultiTerminal` bytecode size. Called via DELEGATECALL, so events
 /// are emitted from the terminal's address.
 library JBPayoutSplitGroupLib {
+    /// @notice A payout to a split reverted, so the amount was returned to the project's balance.
+    /// @param projectId The ID of the project whose payout reverted.
+    /// @param split The split that was being paid when the revert occurred.
+    /// @param amount The amount that was being sent to the split.
+    /// @param reason The reason the payout reverted.
+    /// @param caller The address that called the payout function.
     event PayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller);
 
+    /// @notice A payout was sent to a split.
+    /// @param projectId The ID of the project that the payout was made from.
+    /// @param rulesetId The ID of the ruleset the split belongs to.
+    /// @param group The group the split belongs to.
+    /// @param split The split that was paid.
+    /// @param amount The amount that was sent to the split.
+    /// @param netAmount The amount that the split recipient actually received, after fees.
+    /// @param caller The address that called the payout function.
     event SendPayoutToSplit(
         uint256 indexed projectId,
         uint256 indexed rulesetId,

package/src/periphery/JBMatchingPriceFeed.sol

@@ -8,7 +8,9 @@ import {IJBPriceFeed} from "../interfaces/IJBPriceFeed.sol";
 contract JBMatchingPriceFeed is IJBPriceFeed {
     constructor() {}
 
-    /// @inheritdoc IJBPriceFeed
+    /// @notice Gets the current price (per 1 unit) from the feed.
+    /// @param decimals The number of decimals the return value should use.
+    /// @return The current unit price from the feed, as a fixed point number with the specified number of decimals.
     function currentUnitPrice(uint256 decimals) public view virtual override returns (uint256) {
         return 10 ** decimals;
     }