@bananapus/core-v6 0.0.81 → 0.0.83

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;
 
     //*********************************************************************//
@@ -162,8 +187,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @param feelessAddresses A contract that stores addresses that shouldn't incur fees when paid towards or
-    /// from.
+    /// @param feelessAddresses A contract that stores addresses that shouldn't incur fees on payments to or from them.
     /// @param permissions A contract storing permissions.
     /// @param projects A contract which mints ERC-721s that represent project ownership and transfers.
     /// @param splits A contract that stores splits for each project.
@@ -235,9 +259,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @dev If `shouldReturnHeldFees` is true, the added amount offsets held fees proportionally.
     /// @param projectId The ID of the project to add funds to the balance of.
     /// @param token The terminal token being added (the ERC-20, or `JBConstants.NATIVE_TOKEN` for native).
-    /// @param amount The amount of the terminal `token` to add, as a fixed point number with the same number of
-    /// decimals as the token's accounting context. If `token` is the native token, this argument is ignored and
-    /// `msg.value` is used instead.
+    /// @param amount The amount of terminal `token` to add, as a fixed point number using the token accounting
+    /// context's decimals. If `token` is the native token, this argument is ignored and `msg.value` is used instead.
     /// @param shouldReturnHeldFees If true, return held fees proportional to the amount added.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the emitted event.
@@ -279,8 +302,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// context. If fewer terminal tokens would be reclaimed, the cash out is reverted.
     /// @param beneficiary The address to send the reclaimed terminal tokens to, and to pass along to the ruleset's
     /// data hook and cash out hooks if applicable.
-    /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hooks if
-    /// applicable.
+    /// @param metadata Bytes to send to the emitted event, data hook, and cash out hooks, if applicable.
     /// @return reclaimAmount The amount of **terminal tokens** sent to `beneficiary` in exchange for the burned project
     /// tokens, as a fixed point number with the same number of decimals as the terminal token's accounting context.
     function cashOutTokensOf(
@@ -627,9 +649,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// `msg.value` is used in its place.
     /// @param beneficiary The address to mint project tokens to, and to pass along to the ruleset's data hook and pay
     /// hook if applicable.
-    /// @param minReturnedTokens The minimum number of project tokens the beneficiary must receive for the payment to
-    /// succeed, as a fixed point number with 18 decimals. If fewer project tokens would be minted, the payment is
-    /// reverted.
+    /// @param minReturnedTokens The minimum project tokens the beneficiary must receive for the payment to succeed, as
+    /// a fixed point number with 18 decimals. If fewer project tokens would be minted, the payment is reverted.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to pass along to the emitted event, as well as the data hook and pay hook if applicable.
     /// @return beneficiaryTokenCount The number of **project tokens** minted to `beneficiary`, as a fixed point number
@@ -755,18 +776,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// payout limit. Anyone can call this on behalf of any project.
     /// @dev If splits don't add up to 100%, the remainder goes to the project owner. A wildcard split (no hook,
     /// projectId, or beneficiary) sends its share to `msg.sender` — useful for incentivizing the call.
-    /// @dev Payouts to non-feeless addresses incur the 2.5% protocol fee. Projects whose terminal is feeless are
-    /// exempt.
+    /// @dev Payouts to non-feeless addresses incur the 2.5% protocol fee; feeless project terminals are exempt.
     /// @param projectId The ID of the project having its payouts sent.
     /// @param token The token to send.
     /// @param amount The total number of terminal tokens to send, as a fixed point number with the same number of
     /// decimals as the token's accounting context.
     /// @param currency The expected currency of the payouts. Must match the currency of one of the
     /// project's current ruleset's payout limits.
-    /// @param minTokensPaidOut The minimum number of terminal tokens that the `amount` should be worth (if expressed
-    /// in terms of the token's accounting context currency), as a fixed point number with the same number of decimals
-    /// as the token's accounting context. If the amount of tokens paid out would be less than this amount, the send is
-    /// reverted.
+    /// @param minTokensPaidOut The minimum terminal-token value of `amount`, if expressed in the token accounting
+    /// context currency. If the payout would be less than this amount, the send is reverted.
     /// @return amountPaidOut The total amount paid out.
     function sendPayoutsOf(
         uint256 projectId,
@@ -921,8 +939,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Simulates a cash out without modifying state — use this to preview how many tokens a holder would
-    /// reclaim.
+    /// @notice Simulates a cash out without modifying state to preview how many tokens a holder would reclaim.
     /// @param holder The address cashing out tokens.
     /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out.
@@ -963,9 +980,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Simulates a payment without modifying state — use this to preview how many project tokens a payer
-    /// would
-    /// receive.
+    /// @notice Simulates a payment without modifying state to preview the project tokens a payer would receive.
     /// @param projectId The ID of the project to pay.
     /// @param token The token to pay with.
     /// @param amount The amount of tokens to pay.
@@ -1175,19 +1190,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Holders can cash out their tokens to reclaim some of a project's surplus, or to trigger rules determined
-    /// by
-    /// the project's current ruleset's data hook.
+    /// @notice Holders can cash out their tokens to reclaim some of a project's surplus, or to trigger rules
+    /// determined by the project's current ruleset's data hook.
     /// @dev Only a token holder or an operator with the `CASH_OUT_TOKENS` permission from that holder can cash out
-    /// those
-    /// tokens.
+    /// those tokens.
     /// @param holder The account cashing out tokens.
     /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out, as a fixed point number with 18 decimals.
     /// @param tokenToReclaim The address of the token to reclaim.
     /// @param beneficiary The address to send the reclaimed terminal tokens to.
-    /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hook if
-    /// applicable.
+    /// @param metadata Bytes to send to the emitted event, data hook, and cash out hook, if applicable.
     /// @return reclaimAmount The number of terminal tokens reclaimed for the `beneficiary`, as a fixed point number
     /// with 18 decimals.
     function _cashOutTokensOf(
@@ -1475,8 +1487,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param metadata Bytes to send along to the emitted event and cash out hooks as applicable.
     /// @param ruleset The ruleset active during this cash out as a `JBRuleset` struct.
     /// @param cashOutTaxRate The cash out tax rate influencing the reclaim amount, out of
-    /// `JBConstants.MAX_CASH_OUT_TAX_RATE`. @param beneficiary The address which will receive any terminal tokens that
-    /// are cashed out.
+    /// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
+    /// @param beneficiary The address which will receive any cashed out terminal tokens.
     /// @param specifications The hook specifications to fulfill.
     /// @return amountEligibleForFees The amount of funds which were allocated to cash out hooks and are eligible for
     /// fees.
@@ -1682,8 +1694,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// decimals as the token's accounting context. If this terminal's token is the native token, `amount` is ignored
     /// and `msg.value` is used in its place.
     /// @param payer The address making the payment.
-    /// @param beneficiary The address to mint tokens to, and pass along to the ruleset's data hook and pay hook if
-    /// applicable.
+    /// @param beneficiary The token recipient passed to the ruleset's data hook and pay hook, if applicable.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to send along to the emitted event, as well as the data hook and pay hook if applicable.
     function _pay(
@@ -2061,8 +2072,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Allows a project to send out funds from its surplus up to the current surplus allowance.
-    /// @dev Only a project's owner or an operator with the `USE_ALLOWANCE` permission from that owner can use the
-    /// surplus allowance.
+    /// @dev Only a project's owner or an operator with the owner's `USE_ALLOWANCE` permission can use the allowance.
     /// @dev Incurs the protocol fee unless the caller is a feeless address.
     /// @param projectId The ID of the project to use the surplus allowance of.
     /// @param owner The project's owner.

package/src/JBPermissions.sol

@@ -17,17 +17,21 @@ 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);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
     //*********************************************************************//
 
-    /// @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.
+    /// @notice Project ID 0 acts as a wildcard for permissions across all projects owned by the account.
+    /// @dev Setting permissions for project ID 0 is powerful and should be done carefully.
     uint256 public constant override WILDCARD_PROJECT_ID = 0;
 
     //*********************************************************************//
@@ -35,8 +39,7 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     //*********************************************************************//
 
     /// @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
+    /// @dev Each bit in the returned `uint256` corresponds to a permission ID (0–255). A `1` bit means the 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 operated on behalf of.

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);
 
     //*********************************************************************//
@@ -46,8 +58,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
     /// @notice The ID of the ruleset with the latest start time for a specific project, whether the ruleset has been
     /// approved or not.
-    /// @dev If a project has multiple rulesets queued, the `latestRulesetIdOf` will be the last one. This is the
-    /// "changeable" cycle.
+    /// @dev If a project has multiple rulesets queued, `latestRulesetIdOf` is the last "changeable" cycle.
     /// @custom:param projectId The ID of the project to get the latest ruleset ID of.
     /// @return latestRulesetIdOf The `rulesetId` of the project's latest ruleset.
     mapping(uint256 projectId => uint256) public override latestRulesetIdOf;
@@ -206,9 +217,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
     /// @notice Cache the value of the ruleset weight for a specific ruleset.
     /// @dev The caller should pass the ruleset ID that `currentOf()` actually uses. When a queued ruleset is rejected
-    /// by an approval hook, `currentOf()` falls back to the base ruleset — callers should pass that base ruleset's
-    /// ID,
-    /// not the rejected latest.
+    /// by an approval hook, `currentOf()` falls back to the base ruleset, not the rejected latest.
     /// @param projectId The ID of the project having its ruleset weight cached.
     /// @param rulesetId The ID of the ruleset to update the cache for.
     function updateRulesetWeightCache(uint256 projectId, uint256 rulesetId) external override {
@@ -396,8 +405,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 +481,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 +504,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) {
@@ -562,8 +571,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @notice The date that is the nearest multiple of the base ruleset's duration from the start of the next cycle.
     /// @param baseRulesetStart The start time of the base ruleset.
     /// @param baseRulesetDuration The duration of the base ruleset.
-    /// @param mustStartAtOrAfter The earliest time the next ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param mustStartAtOrAfter The earliest timestamp the next ruleset can start at.
     /// @return start The next start time.
     function deriveStartFrom(
         uint256 baseRulesetStart,
@@ -691,8 +699,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @param projectId The ID of the project to update the latest ruleset for.
     /// @param rulesetId The timestamp of when the ruleset was queued.
     /// @param weight The weight to store in the queued ruleset.
-    /// @param mustStartAtOrAfter The earliest time the ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param mustStartAtOrAfter The earliest timestamp the ruleset can start at.
     function _configureIntrinsicPropertiesFor(
         uint256 projectId,
         uint256 rulesetId,
@@ -723,7 +730,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.
@@ -779,8 +786,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @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 to initialize.
-    /// @param mustStartAtOrAfter The earliest time the ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param mustStartAtOrAfter The earliest timestamp the ruleset can start at.
     /// @param weight The weight to give the newly initialized ruleset.
     function _initializeRulesetFor(
         uint256 projectId,

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);
 
     //*********************************************************************//
@@ -95,8 +121,7 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @notice The currency-denominated amount of funds that a project has already paid out from its payout limit
     /// during the current ruleset for each terminal, in terms of the payout limit's currency.
     /// @dev Increases as projects pay out funds.
-    /// @dev The used payout limit is represented as a fixed point number with the same amount of decimals as the
-    /// terminal it applies to.
+    /// @dev The used payout limit is a fixed point number with the same decimals as the terminal it applies to.
     /// @custom:param terminal The terminal the payout limit applies to.
     /// @custom:param projectId The ID of the project to get the used payout limit of.
     /// @custom:param token The token the payout limit applies to in the terminal.
@@ -115,8 +140,7 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @notice The currency-denominated amounts of funds that a project has used from its surplus allowance during the
     /// current ruleset for each terminal, in terms of the surplus allowance's currency.
     /// @dev Increases as projects use their allowance.
-    /// @dev The used surplus allowance is represented as a fixed point number with the same amount of decimals as the
-    /// terminal it applies to.
+    /// @dev The used surplus allowance is a fixed point number with the same decimals as the terminal it applies to.
     /// @dev Surplus allowance usage is keyed by `ruleset.id`, not cycle number. Implicit cycle progression
     /// (duration-based auto-cycling) does not reset allowance — this is by design. Projects must queue a new ruleset
     /// to get a fresh allowance.
@@ -388,8 +412,7 @@ contract JBTerminalStore is IJBTerminalStore {
         }
     }
 
-    /// @notice Records a payout — decrements the project's balance and enforces the payout limit. Called by the
-    /// terminal during `sendPayoutsOf`.
+    /// @notice Records a payout during `sendPayoutsOf`, decrementing balance and enforcing the payout limit.
     /// @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.
@@ -465,7 +488,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;
         }
@@ -786,8 +809,7 @@ contract JBTerminalStore is IJBTerminalStore {
     }
 
     /// @notice Simulates a payment without modifying state.
-    /// @dev Invokes data hooks if configured. Returns the same token count and hook specifications that
-    /// `recordPaymentFrom` would produce.
+    /// @dev Invokes data hooks if configured. Returns what `recordPaymentFrom` would produce.
     /// @param terminal The terminal to simulate the payment from.
     /// @param payer The address of the payer.
     /// @param amount The amount to pay.
@@ -1137,7 +1159,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()
@@ -1182,8 +1204,7 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
-    /// @notice Gets the current surplus amount for a project across specified terminals and tokens, using a
-    /// pre-fetched ruleset.
+    /// @notice Gets a project's current surplus across specified terminals and tokens using a pre-fetched ruleset.
     /// @dev Use this overload when the caller already has the current ruleset to avoid a redundant
     /// `RULESETS.currentOf()` call.
     /// @param projectId The ID of the project to get surplus for.
@@ -1330,7 +1351,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);
 
     //*********************************************************************//
@@ -84,9 +85,7 @@ abstract contract JBPermissioned is Context, IJBPermissioned {
         ) revert JBPermissioned_Unauthorized(account, sender, projectId, permissionId);
     }
 
-    /// @notice If the 'alsoGrantAccessIf' condition is truthy, proceed. Otherwise, require the message sender to be the
-    /// account or
-    /// have the relevant permission.
+    /// @notice If `alsoGrantAccessIf` is false, require the message sender to be the account or have permission.
     /// @param account The account to allow.
     /// @param projectId The project ID to check the permission under.
     /// @param permissionId The required permission ID. The operator must have this permission within the specified

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/interfaces/IJBCashOutTerminal.sol

@@ -75,8 +75,7 @@ interface IJBCashOutTerminal is IJBTerminal {
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 
-    /// @notice Burn a holder's project tokens to reclaim a proportional share of the project's surplus (paid out as a
-    /// terminal token).
+    /// @notice Burn a holder's project tokens to reclaim a proportional share of surplus in a terminal token.
     /// @param holder The address whose project tokens are being burned.
     /// @param projectId The ID of the project whose project tokens are being burned.
     /// @param cashOutCount The number of project tokens to burn.