@bananapus/core-v6 0.0.38 → 0.0.39

package/src/interfaces/IJBPermissions.sol

@@ -3,7 +3,8 @@ pragma solidity ^0.8.0;
 
 import {JBPermissionsData} from "./../structs/JBPermissionsData.sol";
 
-/// @notice Stores permissions for all addresses and operators.
+/// @notice Interface for the protocol's permission system. Allows any address to authorize operators to perform
+/// specific actions on its behalf, scoped to individual projects or globally (wildcard project ID 0).
 interface IJBPermissions {
     /// @notice Permissions were set for an operator on behalf of an account.
     /// @param operator The operator whose permissions were set.

package/src/interfaces/IJBPrices.sol

@@ -4,7 +4,9 @@ pragma solidity ^0.8.0;
 import {IJBPriceFeed} from "./IJBPriceFeed.sol";
 import {IJBProjects} from "./IJBProjects.sol";
 
-/// @notice Manages price feeds and provides unit prices for currency conversions.
+/// @notice Interface for the price feed registry. Resolves exchange rates between currencies via immutable price feeds
+/// (typically Chainlink). Used when payout limits or surplus allowances are denominated in a different currency than
+/// the token held in the terminal.
 interface IJBPrices {
     /// @notice A price feed was added for a project's currency pair.
     /// @param projectId The ID of the project the price feed was added for.

package/src/interfaces/IJBRulesets.sol

@@ -5,7 +5,8 @@ import {IJBRulesetApprovalHook} from "./IJBRulesetApprovalHook.sol";
 import {JBApprovalStatus} from "./../enums/JBApprovalStatus.sol";
 import {JBRuleset} from "./../structs/JBRuleset.sol";
 
-/// @notice Manages rulesets and queuing for projects.
+/// @notice Interface for the ruleset storage and lifecycle contract. Rulesets define a project's economic parameters
+/// (weight, duration, cash-out rate, etc.) and are queued as a linked list with approval hooks gating transitions.
 interface IJBRulesets {
     /// @notice A ruleset was initialized from a base ruleset.
     /// @param rulesetId The ID of the initialized ruleset.

package/src/interfaces/IJBSplits.sol

@@ -4,7 +4,8 @@ pragma solidity ^0.8.0;
 import {JBSplit} from "./../structs/JBSplit.sol";
 import {JBSplitGroup} from "./../structs/JBSplitGroup.sol";
 
-/// @notice Stores and manages splits for each project.
+/// @notice Interface for the split storage contract. Splits define how payouts and reserved tokens are distributed —
+/// each split specifies a recipient and their percentage share. Splits can be locked until a timestamp.
 interface IJBSplits {
     /// @notice A split was set for a project.
     /// @param projectId The ID of the project the split was set for.

package/src/interfaces/IJBTerminal.sol

@@ -9,7 +9,9 @@ import {JBAfterPayRecordedContext} from "../structs/JBAfterPayRecordedContext.so
 import {JBPayHookSpecification} from "../structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "../structs/JBRuleset.sol";
 
-/// @notice A terminal that accepts payments and can be migrated.
+/// @notice Base interface for all Juicebox terminals. A terminal accepts payments for projects, reports surplus, and
+/// supports balance migration. Projects register their terminals in `JBDirectory`; the primary terminal for a token
+/// receives payments routed by frontends.
 interface IJBTerminal is IERC165 {
     /// @notice Funds were added to a project's balance.
     /// @param projectId The ID of the project that received the funds.

package/src/interfaces/IJBTerminalStore.sol

@@ -11,7 +11,9 @@ import {JBPayHookSpecification} from "../structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "../structs/JBRuleset.sol";
 import {JBTokenAmount} from "../structs/JBTokenAmount.sol";
 
-/// @notice Manages the bookkeeping for payments, cash outs, payouts, and surplus allowance usage for terminals.
+/// @notice Interface for the terminal's accounting engine. Records balances, enforces payout limits and surplus
+/// allowances, calculates token issuance per payment, and determines cash-out reclaim amounts via the bonding curve.
+/// Terminals delegate all state-changing accounting to this contract.
 interface IJBTerminalStore {
     /// @notice The directory of terminals and controllers for projects.
     function DIRECTORY() external view returns (IJBDirectory);

package/src/interfaces/IJBTokens.sol

@@ -3,7 +3,8 @@ pragma solidity ^0.8.0;
 
 import {IJBToken} from "./IJBToken.sol";
 
-/// @notice Manages minting, burning, and balances of projects' tokens and token credits.
+/// @notice Interface for the dual-token system. Manages credits (internal balances) and ERC-20 tokens for every
+/// project. Credits are minted first and can later be claimed as transferable ERC-20 tokens.
 interface IJBTokens {
     /// @notice Tokens or credits were burned from a holder's balance.
     /// @param holder The address whose tokens were burned.

package/src/libraries/JBCashOuts.sol

@@ -5,7 +5,12 @@ import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {JBConstants} from "./JBConstants.sol";
 
-/// @notice Cash out calculations.
+/// @notice Implements the bonding curve math for cash outs. When a token holder cashes out, this library calculates
+/// how much of the project's surplus they can reclaim based on their share of the total supply and the current
+/// cash-out tax rate. A 0% tax rate gives a proportional share; a 100% tax rate returns nothing (all surplus stays).
+/// @dev Formula: `surplus * count * [(MAX - taxRate) + taxRate * (count / supply)] / (supply * MAX)`.
+/// Also provides an inverse function (`cashOutCountFrom`) for determining how many tokens to burn for a desired
+/// reclaim amount.
 library JBCashOuts {
     /// @notice Thrown when the desired output cannot be achieved (e.g., cash out tax rate is 100%).
     error JBCashOuts_DesiredOutputNotAchievable();

package/src/libraries/JBConstants.sol

@@ -1,14 +1,23 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-/// @notice Global constants used across Juicebox contracts.
+/// @notice Protocol-wide constants. These define the boundaries for economic parameters throughout Juicebox.
 library JBConstants {
-    /// @notice Each chain's native token address in Juicebox is represented by
-    /// 0x000000000000000000000000000000000000EEEe.
+    /// @notice The sentinel address used to represent each chain's native token (ETH on mainnet, etc.).
     address public constant NATIVE_TOKEN = address(0x000000000000000000000000000000000000EEEe);
+
+    /// @notice The maximum reserved token percentage (basis points). 10,000 = 100% of minted tokens go to reserves.
     uint16 public constant MAX_RESERVED_PERCENT = 10_000;
+
+    /// @notice The maximum cash-out tax rate (basis points). 10,000 = 100% tax, meaning token holders reclaim nothing.
     uint16 public constant MAX_CASH_OUT_TAX_RATE = 10_000;
+
+    /// @notice The maximum weight cut percent (9-decimal precision). 1,000,000,000 = 100% cut per cycle (no issuance).
     uint32 public constant MAX_WEIGHT_CUT_PERCENT = 1_000_000_000;
+
+    /// @notice The denominator for split percentages (9-decimal precision). A split of 1,000,000,000 = 100%.
     uint32 public constant SPLITS_TOTAL_PERCENT = 1_000_000_000;
+
+    /// @notice The fee denominator. The protocol fee is `FEE / MAX_FEE` (currently 25/1000 = 2.5%).
     uint16 public constant MAX_FEE = 1000;
 }

package/src/libraries/JBCurrencyIds.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+/// @notice Well-known currency IDs used as the `baseCurrency` in ruleset metadata. These are distinct from accounting
+/// context currencies (which use `uint32(uint160(tokenAddress))`). Only used for price feed lookups in `JBPrices`.
 library JBCurrencyIds {
     uint32 public constant ETH = 1;
     uint32 public constant USD = 2;

package/src/libraries/JBFees.sol

@@ -5,7 +5,11 @@ import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {JBConstants} from "./../libraries/JBConstants.sol";
 
-/// @notice Fee calculations.
+/// @notice Utility functions for calculating the protocol fee (2.5%) in both directions: forward (fee from a pre-fee
+/// amount) and backward (the pre-fee amount that would yield a given post-fee amount). Used by `JBMultiTerminal`
+/// during payouts, surplus allowance usage, and cash outs.
+/// @dev Fee dust protection: if a nonzero amount with a nonzero fee would otherwise round to 0, returns 1 wei to
+/// prevent fee bypass via many tiny transfers.
 library JBFees {
     /// @notice Returns the fee that would be taken from `amountBeforeFee`.
     /// @dev Use this to forward-calculate the fee from a known pre-fee amount.

package/src/libraries/JBFixedPointNumber.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+/// @notice Utility for converting between fixed-point numbers with different decimal precisions (e.g. 6-decimal USDC
+/// amounts to 18-decimal internal accounting).
 library JBFixedPointNumber {
     function adjustDecimals(uint256 value, uint256 decimals, uint256 targetDecimals) internal pure returns (uint256) {
         // If decimals need adjusting, multiply or divide the price by the decimal adjuster to get the normalized

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -23,8 +23,11 @@ interface IJBPayoutSplitGroupExecutor {
         returns (uint256 netPayoutAmount);
 }
 
-/// @notice External library for payout split-group distribution extracted to reduce terminal bytecode.
-/// @dev Called via DELEGATECALL from the terminal, so events are emitted from the terminal's address.
+/// @notice Handles distributing payouts to a project's split recipients. Iterates through each split, sends the
+/// proportional amount, and gracefully handles failures — if a split payout reverts (e.g. a hook is broken), the
+/// amount is returned to the project's balance rather than blocking all other splits.
+/// @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 {
     event PayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller);
     event SendPayoutToSplit(

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -4,6 +4,10 @@ pragma solidity 0.8.28;
 import {JBRuleset} from "./../structs/JBRuleset.sol";
 import {JBRulesetMetadata} from "./../structs/JBRulesetMetadata.sol";
 
+/// @notice Unpacks the 256-bit packed `metadata` field from a `JBRuleset` into individual parameters. The metadata
+/// encodes: reservedPercent, cashOutTaxRate, baseCurrency, 14 boolean flags (pausePay, allowOwnerMinting, etc.),
+/// a data hook address, and 14 bits of custom metadata. Used throughout the protocol to read ruleset configuration
+/// without storing each field separately.
 library JBRulesetMetadataResolver {
     function reservedPercent(JBRuleset memory ruleset) internal pure returns (uint16) {
         return uint16(ruleset.metadata >> 4);

package/src/libraries/JBSplitGroupIds.sol

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-/// @notice Group IDs that categorize splits.
+/// @notice Well-known split group IDs. The reserved tokens group (ID 1) defines how a project's reserved tokens are
+/// distributed. Payout split groups use the token address cast to `uint256(uint160(token))` as their group ID.
 library JBSplitGroupIds {
     uint256 public constant RESERVED_TOKENS = 1;
 }

package/src/libraries/JBSurplus.sol

@@ -3,7 +3,9 @@ pragma solidity 0.8.28;
 
 import {IJBTerminal} from "../interfaces/IJBTerminal.sol";
 
-/// @notice Surplus calculations.
+/// @notice Calculates a project's total surplus across all its terminals. Surplus is the amount held beyond what's
+/// needed to cover the project's payout limits — it represents the pool available for cash outs and surplus allowance
+/// usage. Aggregates across multiple terminals and tokens, converting to a common currency via `JBPrices`.
 library JBSurplus {
     /// @notice Gets the total current surplus amount across all of a project's terminals.
     /// @dev This amount changes as the value of the balances changes in relation to the currency being used to measure

package/src/periphery/JBMatchingPriceFeed.sol

@@ -3,6 +3,8 @@ pragma solidity 0.8.28;
 
 import {IJBPriceFeed} from "../interfaces/IJBPriceFeed.sol";
 
+/// @notice A trivial price feed that always returns 1:1 (one unit = one unit). Used when a payout limit is
+/// denominated in the same currency as the terminal's token, so no actual conversion is needed.
 contract JBMatchingPriceFeed is IJBPriceFeed {
     constructor() {}
 

package/src/structs/JBAccountingContext.sol

@@ -1,10 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member token The address of the token that accounting is being done with.
-/// @custom:member decimals The number of decimals expected in that token's fixed point accounting.
-/// @custom:member currency The currency that the token is priced in terms of. By convention, this is
-/// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
+/// @notice Describes how a terminal accounts for a specific token — its address, decimal precision, and which
+/// currency
+/// it's priced in. Used when recording payments, payouts, and cash outs to ensure correct fixed-point arithmetic.
+/// @custom:member token The token address (use `JBConstants.NATIVE_TOKEN` for ETH).
+/// @custom:member decimals The number of decimals for this token's fixed-point amounts (e.g. 18 for ETH, 6 for USDC).
+/// @custom:member currency The currency ID for price feed lookups. Convention: `uint32(uint160(tokenAddress))` for
+/// tokens, or `JBCurrencyIds.ETH`/`JBCurrencyIds.USD` for well-known currencies.
 struct JBAccountingContext {
     address token;
     uint8 decimals;

package/src/structs/JBFundAccessLimitGroup.sol

@@ -3,23 +3,16 @@ pragma solidity ^0.8.0;
 
 import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 
-/// @dev Payout limit example: if the `amount` is 5, the `currency` is 1 (USD), and the terminal's token is ETH, then
-/// the project can pay out 5 USD worth of ETH during a ruleset.
-/// @dev Surplus allowance example: if the `amount` is 5, the `currency` is 1 (USD), and the terminal's token is ETH,
-/// then the project can pay out 5 USD worth of ETH from its surplus during a ruleset. A project's surplus is its
-/// balance minus its current combined payout limit.
-/// @dev If a project has multiple payout limits or surplus allowances, they are all available. They can all be used
-/// during a single ruleset.
-/// @dev The payout limits' and surplus allowances' fixed point amounts have the same number of decimals as the
-/// terminal.
-/// @custom:member terminal The terminal that the payout limits and surplus allowances apply to.
-/// @custom:member token The token that the payout limits and surplus allowances apply to within the `terminal`.
-/// @custom:member payoutLimits An array of payout limits. The payout limits cumulatively dictate the maximum value of
-/// `token`s a project can pay out from its balance in a terminal during a ruleset. Each payout limit can have a unique
-/// currency and amount.
-/// @custom:member surplusAllowances An array of surplus allowances. The surplus allowances cumulatively dictates the
-/// maximum value of `token`s a project can pay out from its surplus (balance less payouts) in a terminal during a
-/// ruleset. Each surplus allowance can have a unique currency and amount.
+/// @notice Defines how much a project can withdraw from a specific terminal and token each funding cycle.
+/// @dev Example — payout limit of 5 USD in an ETH terminal: the project can distribute up to 5 USD worth of ETH to
+/// its splits per cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD worth of ETH
+/// from the surplus (balance above payout limits).
+/// @dev Multiple limits in different currencies are additive — each can be used independently within one cycle.
+/// @dev Amounts use the same decimal precision as the terminal token (e.g. 18 for ETH, 6 for USDC).
+/// @custom:member terminal The terminal address these limits apply to.
+/// @custom:member token The token address within that terminal these limits apply to.
+/// @custom:member payoutLimits Maximum amounts distributable to splits per cycle, each in a specific currency.
+/// @custom:member surplusAllowances Maximum amounts withdrawable from surplus per cycle, each in a specific currency.
 struct JBFundAccessLimitGroup {
     address terminal;
     address token;

package/src/structs/JBRuleset.sol

@@ -3,32 +3,24 @@ pragma solidity ^0.8.0;
 
 import {IJBRulesetApprovalHook} from "./../interfaces/IJBRulesetApprovalHook.sol";
 
-/// @dev `JBRuleset` timestamps are unix timestamps (seconds since 00:00 January 1st, 1970 UTC).
-/// @custom:member cycleNumber The ruleset's cycle number. Each ruleset's `cycleNumber` is the previous ruleset's
-/// `cycleNumber` plus one. Each project's first ruleset has a `cycleNumber` of 1.
-/// @custom:member id The ruleset's ID, which is a timestamp of when this ruleset's rules were initialized. The
-/// `rulesetId` stays the same for rulesets that automatically cycle over from a manually queued ruleset.
-/// @custom:member basedOnId The `rulesetId` of the ruleset which was active when this ruleset was created.
-/// @custom:member start The timestamp from which this ruleset is considered active.
-/// @custom:member duration The number of seconds the ruleset lasts for. After this duration, a new ruleset will start.
-/// The project owner can queue new rulesets at any time, which will take effect once the current ruleset's duration is
-/// over. If the `duration` is 0, newly queued rulesets will take effect immediately. If a ruleset ends and there are no
-/// new rulesets queued, the current ruleset cycles over to another one with the same properties but a new `start`
-/// timestamp and a `weight` reduced by the ruleset's `weightCutPercent`.
-/// @custom:member weight A fixed point number with 18 decimals which is typically used by payment terminals to
-/// determine how many tokens should be minted when a payment is received. This can be used by other contracts for
-/// arbitrary calculations.
-/// @custom:member weightCutPercent The percentage by which to reduce the `weight` each time a new ruleset starts.
-/// `weight`
-/// is
-/// a percentage out of `JBConstants.MAX_WEIGHT_CUT_PERCENT`. If it's 0, the next ruleset will have the same `weight` by
-/// default. If it's 90%, the next ruleset's `weight` will be 10% smaller. If a ruleset explicitly sets a new `weight`,
-/// the `weightCutPercent` doesn't apply.
-/// @custom:member approvalHook An address of a contract that says whether a queued ruleset should be approved or
-/// rejected. If a
-/// ruleset is rejected, it won't go into effect. An approval hook can be used to create rules which dictate how a
-/// project owner can change their ruleset over time.
-/// @custom:member metadata Extra data associated with a ruleset which can be used by other contracts.
+/// @notice A ruleset defines how a project behaves during a period of time — token issuance rate, cash-out terms,
+/// payout rules, and permissions. Rulesets cycle automatically: when one expires, the next queued (and approved) one
+/// takes effect. If nothing is queued, the current ruleset auto-cycles with decayed weight.
+/// @dev Timestamps are unix timestamps (seconds since epoch).
+/// @custom:member cycleNumber Which cycle this is (starts at 1, increments each cycle).
+/// @custom:member id The ruleset's ID — the unix timestamp when it was first stored. Stays the same across
+/// auto-cycles.
+/// @custom:member basedOnId The ID of the ruleset that was active when this one was created (forms a linked list).
+/// @custom:member start When this ruleset became/becomes active.
+/// @custom:member duration How many seconds the ruleset lasts. 0 = no auto-cycling (must be explicitly replaced).
+/// @custom:member weight Tokens minted per unit paid (18 decimals). The terminal divides payment amount by weight to
+/// determine token issuance. Higher weight = more tokens per unit of payment.
+/// @custom:member weightCutPercent How much to reduce weight each cycle (out of 1,000,000,000). 100,000,000 = 10% cut
+/// per cycle. 0 = no decay. Only applies when a cycle auto-rolls without an explicitly queued replacement.
+/// @custom:member approvalHook A contract that gates whether queued rulesets can take effect (e.g. `JBDeadline` for
+/// minimum notice periods). If the hook rejects a queued ruleset, the current one continues.
+/// @custom:member metadata Packed 256-bit field containing reservedPercent, cashOutTaxRate, baseCurrency, boolean
+/// flags, data hook address, and custom metadata. Decoded by `JBRulesetMetadataResolver`.
 struct JBRuleset {
     uint48 cycleNumber;
     uint48 id;

package/src/structs/JBRulesetConfig.sol

@@ -6,31 +6,19 @@ import {JBFundAccessLimitGroup} from "./JBFundAccessLimitGroup.sol";
 import {JBRulesetMetadata} from "./JBRulesetMetadata.sol";
 import {JBSplitGroup} from "./JBSplitGroup.sol";
 
-/// @custom:member mustStartAtOrAfter The earliest time the ruleset can start.
-/// @custom:member duration The number of seconds the ruleset lasts for, after which a new ruleset will start. A
-/// duration of 0 means that the ruleset will stay active until the project owner explicitly issues a reconfiguration,
-/// at which point a new ruleset will immediately start with the updated properties. If the duration is greater than 0,
-/// a project owner cannot make changes to a ruleset's parameters while it is active – any proposed changes will apply
-/// to the subsequent ruleset. If no changes are proposed, a ruleset rolls over to another one with the same properties
-/// but new `start` timestamp and a cut `weight`.
-/// @custom:member weight A fixed point number with 18 decimals that contracts can use to base arbitrary calculations
-/// on. For example, payment terminals can use this to determine how many tokens should be minted when a payment is
-/// received.
-/// @custom:member weightCutPercent A percent by how much the `weight` of the subsequent ruleset should be reduced, if
-/// the
-/// project owner hasn't queued the subsequent ruleset with an explicit `weight`. If it's 0, each ruleset will have
-/// equal weight. If the number is 90%, the next ruleset will have a 10% smaller weight. This weight is out of
-/// `JBConstants.MAX_WEIGHT_CUT_PERCENT`.
-/// @custom:member approvalHook An address of a contract that says whether a proposed ruleset should be accepted or
-/// rejected. It
-/// can be used to create rules around how a project owner can change ruleset parameters over time.
-/// @custom:member metadata Metadata specifying the controller-specific parameters that a ruleset can have. These
-/// properties cannot change until the next ruleset starts.
-/// @custom:member splitGroups An array of splits to use for any number of groups while the ruleset is active.
-/// @custom:member fundAccessLimitGroups An array of structs which dictate the amount of funds a project can access from
-/// its balance in each payment terminal while the ruleset is active. Amounts are fixed point numbers using the same
-/// number of decimals as the corresponding terminal. The `_payoutLimit` and `_surplusAllowance` parameters must fit in
-/// a `uint232`.
+/// @notice The configuration passed to `JBController.launchRulesetsFor` or `queueRulesetsOf` to define a new ruleset.
+/// Includes the economic parameters (weight, duration, decay), the metadata (permissions and hooks), the split
+/// recipients, and the fund access limits.
+/// @custom:member mustStartAtOrAfter The earliest timestamp the ruleset can begin. Pass 0 to start immediately after
+/// the previous ruleset ends.
+/// @custom:member duration How long the ruleset lasts in seconds. 0 = stays active until explicitly replaced.
+/// @custom:member weight Tokens minted per unit of payment (18 decimals). Pass 1 to inherit decayed weight from the
+/// previous ruleset. Pass 0 for no token issuance.
+/// @custom:member weightCutPercent Decay rate per cycle (out of 1,000,000,000). 100,000,000 = 10% cut. 0 = no decay.
+/// @custom:member approvalHook Contract that must approve the *next* queued ruleset for it to take effect.
+/// @custom:member metadata The ruleset's behavioral flags and parameters (see `JBRulesetMetadata`).
+/// @custom:member splitGroups How payouts and reserved tokens are distributed during this ruleset.
+/// @custom:member fundAccessLimitGroups How much the project can withdraw from each terminal per cycle.
 struct JBRulesetConfig {
     uint48 mustStartAtOrAfter;
     uint32 duration;

package/src/structs/JBRulesetMetadata.sol

@@ -1,38 +1,31 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member reservedPercent The reserved percent of the ruleset. This number is a percentage calculated out of
-/// `JBConstants.MAX_RESERVED_PERCENT`.
-/// @custom:member cashOutTaxRate The cash out tax rate of the ruleset. This number is a percentage calculated out of
-/// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
-/// @custom:member baseCurrency The currency on which to base the ruleset's weight. By convention, this is
-/// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
-/// @custom:member pausePay A flag indicating if the pay functionality should be paused during the ruleset.
-/// @custom:member pauseCreditTransfers A flag indicating if the project token transfer functionality should be paused
-/// during the funding cycle.
-/// @custom:member allowOwnerMinting A flag indicating if the project owner or an operator with the `MINT_TOKENS`
-/// permission from the owner should be allowed to mint project tokens on demand during this ruleset.
-/// @custom:member allowTerminalMigration A flag indicating if migrating terminals should be allowed during this
-/// ruleset.
-/// @custom:member allowSetTerminals A flag indicating if a project's terminals can be added or removed.
-/// @custom:member allowSetController A flag indicating if a project's controller can be changed.
-/// @custom:member allowAddAccountingContext A flag indicating if a project can add new accounting contexts for its
-/// terminals to use.
-/// @custom:member allowAddPriceFeed A flag indicating if a project can add new price feeds to calculate exchange rates
-/// between its tokens.
-/// @custom:member ownerMustSendPayouts A flag indicating if privileged payout distribution should be
-/// enforced, otherwise payouts can be distributed by anyone.
-/// @custom:member holdFees A flag indicating if fees should be held during this ruleset.
-/// @custom:member useTotalSurplusForCashOuts A flag indicating if cash outs should use the project's balance held
-/// in all terminals instead of the project's local terminal balance from which the cash out is being fulfilled.
-/// @custom:member useDataHookForPay A flag indicating if the data hook should be used for pay transactions during this
-/// ruleset.
-/// @custom:member useDataHookForCashOut A flag indicating if the data hook should be used for cash out transactions
-/// during
-/// this ruleset.
-/// @custom:member dataHook The data hook to use during this ruleset.
-/// @custom:member metadata Metadata of the metadata, only the 14 least significant bits can be used, the 2 most
-/// significant bits are disregarded.
+/// @notice Human-readable configuration for a ruleset's behavioral flags and parameters. This struct is packed into
+/// 256 bits for on-chain storage (see `JBRulesetMetadataResolver` for the packing layout).
+/// @custom:member reservedPercent Percentage of newly minted tokens set aside for the reserved token split group
+/// (0–10,000 basis points). 5,000 = 50% reserved.
+/// @custom:member cashOutTaxRate Tax applied when holders cash out tokens (0–10,000 basis points). Higher rate = less
+/// reclaim per token. 0 = proportional, 10,000 = no reclaim (100% tax).
+/// @custom:member baseCurrency The currency used to interpret the ruleset's weight for token issuance. Convention:
+/// `uint32(uint160(tokenAddress))` for tokens, or `JBCurrencyIds.ETH`/`JBCurrencyIds.USD` for well-known currencies.
+/// @custom:member pausePay If `true`, the project cannot receive payments during this ruleset.
+/// @custom:member pauseCreditTransfers If `true`, token credit transfers are disabled during this ruleset.
+/// @custom:member allowOwnerMinting If `true`, the project owner (or MINT_TOKENS operator) can mint tokens on demand.
+/// @custom:member allowSetCustomToken If `true`, the project can set a custom ERC-20 token via `setTokenFor`.
+/// @custom:member allowTerminalMigration If `true`, terminals can be migrated to new implementations.
+/// @custom:member allowSetTerminals If `true`, the project's terminal list can be modified.
+/// @custom:member allowSetController If `true`, the project's controller can be changed.
+/// @custom:member allowAddAccountingContext If `true`, new token accounting contexts can be added to terminals.
+/// @custom:member allowAddPriceFeed If `true`, the project can register new price feeds in `JBPrices`.
+/// @custom:member ownerMustSendPayouts If `true`, only the project owner can trigger payout distribution.
+/// @custom:member holdFees If `true`, fees are accumulated but not processed until a future ruleset (or manually).
+/// @custom:member useTotalSurplusForCashOuts If `true`, cash-out calculations use surplus across all terminals (not
+/// just the one being cashed out from).
+/// @custom:member useDataHookForPay If `true`, the data hook is called before recording payments.
+/// @custom:member useDataHookForCashOut If `true`, the data hook is called before recording cash outs.
+/// @custom:member dataHook Contract called before pay/cash-out to potentially override token counts or add hooks.
+/// @custom:member metadata 14 bits of application-specific metadata (upper 2 bits are ignored).
 struct JBRulesetMetadata {
     uint16 reservedPercent;
     uint16 cashOutTaxRate;