@bananapus/core-v6 0.0.38 → 0.0.40

package/src/interfaces/IJBPayoutTerminal.sol

@@ -17,7 +17,7 @@ interface IJBPayoutTerminal is IJBTerminal {
     /// @notice A direct payout transfer reverted.
     /// @param projectId The ID of the project the payout was for.
     /// @param addr The address the payout was sent to.
-    /// @param token The token being paid out.
+    /// @param token The token to pay out.
     /// @param amount The amount of the payout.
     /// @param fee The fee taken from the payout.
     /// @param reason The revert reason.
@@ -98,7 +98,7 @@ interface IJBPayoutTerminal is IJBTerminal {
 
     /// @notice Sends a project's payouts to its payout split group according to its ruleset's payout limits.
     /// @param projectId The ID of the project to send payouts for.
-    /// @param token The token being paid out.
+    /// @param token The token to pay out.
     /// @param amount The total amount of tokens to pay out.
     /// @param currency The currency the amount is denominated in.
     /// @param minTokensPaidOut The minimum number of terminal tokens expected to be paid out.
@@ -115,7 +115,7 @@ interface IJBPayoutTerminal is IJBTerminal {
 
     /// @notice Uses a project's surplus allowance to send funds to a beneficiary.
     /// @param projectId The ID of the project to use the surplus allowance of.
-    /// @param token The token being paid out.
+    /// @param token The token to pay out.
     /// @param amount The amount of the surplus allowance to use.
     /// @param currency The currency the amount is denominated in.
     /// @param minTokensPaidOut The minimum number of terminal tokens expected to be paid out.

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.
@@ -26,7 +27,7 @@ interface IJBPermissions {
 
     /// @notice Checks if an operator has a specific permission for an account and project.
     /// @param operator The operator to check.
-    /// @param account The account being operated on behalf of.
+    /// @param account The account the operator acts on behalf of.
     /// @param projectId The project ID the permission is scoped to. 0 represents all projects.
     /// @param permissionId The permission ID to check for.
     /// @param includeRoot Whether to return true if the operator has the ROOT permission.
@@ -46,7 +47,7 @@ interface IJBPermissions {
 
     /// @notice Checks if an operator has all of the specified permissions for an account and project.
     /// @param operator The operator to check.
-    /// @param account The account being operated on behalf of.
+    /// @param account The account the operator acts on behalf of.
     /// @param projectId The project ID the permissions are scoped to. 0 represents all projects.
     /// @param permissionIds An array of permission IDs to check for.
     /// @param includeRoot Whether to return true if the operator has the ROOT permission.
@@ -66,13 +67,13 @@ interface IJBPermissions {
 
     /// @notice Returns the packed permissions that an operator has for an account and project.
     /// @param operator The address of the operator.
-    /// @param account The address of the account being operated on behalf of.
+    /// @param account The address of the account operated on behalf of.
     /// @param projectId The project ID the permissions are scoped to. 0 is a wildcard for all projects.
     /// @return The packed permissions as a uint256 bitmap.
     function permissionsOf(address operator, address account, uint256 projectId) external view returns (uint256);
 
     /// @notice Sets permissions for an operator on behalf of an account.
     /// @param account The account setting its operator's permissions.
-    /// @param permissionsData The data specifying the permissions the operator is being given.
+    /// @param permissionsData The data specifying the permissions to grant to the operator.
     function setPermissionsFor(address account, JBPermissionsData calldata permissionsData) external;
 }

package/src/interfaces/IJBPermitTerminal.sol

@@ -13,7 +13,7 @@ interface IJBPermitTerminal is IJBTerminal {
     /// @param reason The failure reason.
     event Permit2AllowanceFailed(address indexed token, address indexed owner, bytes reason);
 
-    /// @notice The Permit2 contract used for token approvals.
+    /// @notice The Permit2 contract used for gasless ERC-20 token approvals during payments.
     // forge-lint: disable-next-line(mixed-case-function)
     function PERMIT2() external returns (IPermit2);
 }

package/src/interfaces/IJBPrices.sol

@@ -4,12 +4,14 @@ 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.
     /// @param pricingCurrency The currency the feed's output price is in terms of.
-    /// @param unitCurrency The currency being priced by the feed.
+    /// @param unitCurrency The currency the feed prices.
     /// @param feed The price feed that was added.
     /// @param caller The address that added the price feed.
     event AddPriceFeed(
@@ -29,7 +31,7 @@ interface IJBPrices {
     /// @notice Returns the price feed for a project's currency pair.
     /// @param projectId The ID of the project to get the price feed of.
     /// @param pricingCurrency The currency the feed's output price is in terms of.
-    /// @param unitCurrency The currency being priced by the feed.
+    /// @param unitCurrency The currency the feed prices.
     /// @return The price feed for the currency pair.
     function priceFeedFor(
         uint256 projectId,
@@ -43,7 +45,7 @@ interface IJBPrices {
     /// @notice Returns the unit price for a currency pair.
     /// @param projectId The ID of the project to get the price for.
     /// @param pricingCurrency The currency the returned price is in terms of.
-    /// @param unitCurrency The currency being priced.
+    /// @param unitCurrency The currency to price.
     /// @param decimals The number of decimals the returned price should use.
     /// @return The unit price.
     function pricePerUnitOf(
@@ -59,7 +61,7 @@ interface IJBPrices {
     /// @notice Adds a price feed for a project's currency pair.
     /// @param projectId The ID of the project to add the price feed for.
     /// @param pricingCurrency The currency the feed's output price is in terms of.
-    /// @param unitCurrency The currency being priced by the feed.
+    /// @param unitCurrency The currency the feed prices.
     /// @param feed The price feed to add.
     function addPriceFeedFor(
         uint256 projectId,

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.
@@ -105,9 +107,9 @@ interface IJBTerminal is IERC165 {
         returns (uint256);
 
     /// @notice Simulates paying a project through this terminal without modifying state.
-    /// @param projectId The ID of the project being paid.
-    /// @param token The token being paid in.
-    /// @param amount The amount of tokens being paid.
+    /// @param projectId The ID of the project to pay.
+    /// @param token The token to pay with.
+    /// @param amount The amount of tokens to pay.
     /// @param beneficiary The address to mint project tokens to.
     /// @param metadata Extra data to pass along to the data hook and pay hooks.
     /// @return ruleset The project's current ruleset.
@@ -137,8 +139,8 @@ interface IJBTerminal is IERC165 {
 
     /// @notice Adds funds to a project's balance.
     /// @param projectId The ID of the project to add funds to.
-    /// @param token The token being added.
-    /// @param amount The amount of tokens being added.
+    /// @param token The token added.
+    /// @param amount The amount of tokens added.
     /// @param shouldReturnHeldFees Whether held fees should be returned based on 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.
@@ -154,16 +156,16 @@ interface IJBTerminal is IERC165 {
         payable;
 
     /// @notice Migrates a project's funds from this terminal to another.
-    /// @param projectId The ID of the project being migrated.
-    /// @param token The address of the token being migrated.
+    /// @param projectId The ID of the project to migrate.
+    /// @param token The address of the token to migrate.
     /// @param to The terminal to migrate to.
     /// @return balance The amount of funds that were migrated.
     function migrateBalanceOf(uint256 projectId, address token, IJBTerminal to) external returns (uint256 balance);
 
     /// @notice Pays a project in a specified token.
-    /// @param projectId The ID of the project being paid.
-    /// @param token The token being paid in.
-    /// @param amount The amount of tokens being paid.
+    /// @param projectId The ID of the project to pay.
+    /// @param token The token to pay with.
+    /// @param amount The amount of tokens to pay.
     /// @param beneficiary The address to mint project tokens to.
     /// @param minReturnedTokens The minimum number of project tokens expected in return.
     /// @param memo A memo to pass along to the emitted event.

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);
@@ -57,7 +59,7 @@ interface IJBTerminalStore {
 
     /// @notice Returns the reclaimable surplus for a project given a cash-out count, total supply, and surplus.
     /// @param projectId The ID of the project.
-    /// @param cashOutCount The number of tokens being cashed out.
+    /// @param cashOutCount The number of tokens to cash out.
     /// @param totalSupply The total token supply.
     /// @param surplus The project's surplus.
     /// @return The reclaimable surplus amount.
@@ -74,7 +76,7 @@ interface IJBTerminalStore {
     /// @notice Returns the reclaimable surplus for a project across multiple terminals, considering only specific
     /// tokens.
     /// @param projectId The ID of the project.
-    /// @param cashOutCount The number of tokens being cashed out.
+    /// @param cashOutCount The number of tokens to cash out.
     /// @param terminals The terminals to include in the surplus calculation. If empty, all project terminals are used.
     /// @param tokens The tokens to include in the surplus calculation.
     /// @param decimals The number of decimals to express the result with.
@@ -112,7 +114,7 @@ interface IJBTerminalStore {
 
     /// @notice Returns the reclaimable surplus for a project across all terminals using all accounting contexts.
     /// @param projectId The ID of the project.
-    /// @param cashOutCount The number of tokens being cashed out.
+    /// @param cashOutCount The number of tokens to cash out.
     /// @param decimals The number of decimals to express the result with.
     /// @param currency The currency to express the result in.
     /// @return The reclaimable surplus amount.
@@ -143,9 +145,9 @@ interface IJBTerminalStore {
     /// @notice Simulates a cash out without modifying state.
     /// @param terminal The terminal to simulate the cash out from.
     /// @param holder The address cashing out.
-    /// @param projectId The ID of the project being cashed out from.
-    /// @param cashOutCount The number of project tokens being cashed out.
-    /// @param tokenToReclaim The token being reclaimed.
+    /// @param projectId The ID of the project to cash out from.
+    /// @param cashOutCount The number of project tokens to cash out.
+    /// @param tokenToReclaim The token to reclaim.
     /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address.
     /// @param metadata Extra data to pass along to the data hook.
     /// @return ruleset The project's current ruleset.
@@ -173,8 +175,8 @@ interface IJBTerminalStore {
     /// @notice Simulates a payment without modifying state.
     /// @param terminal The terminal to simulate the payment from.
     /// @param payer The address of the payer.
-    /// @param amount The amount being paid.
-    /// @param projectId The ID of the project being paid.
+    /// @param amount The amount to pay.
+    /// @param projectId The ID of the project to pay.
     /// @param beneficiary The address to mint project tokens to.
     /// @param metadata Extra data to pass along to the data hook.
     /// @return ruleset The project's current ruleset.
@@ -235,15 +237,15 @@ interface IJBTerminalStore {
 
     /// @notice Records a balance addition for a project.
     /// @param projectId The ID of the project.
-    /// @param token The token being added.
-    /// @param amount The amount being added.
+    /// @param token The token added.
+    /// @param amount The amount added.
     function recordAddedBalanceFor(uint256 projectId, address token, uint256 amount) external;
 
     /// @notice Records a cash out from a project.
     /// @param holder The address cashing out.
-    /// @param projectId The ID of the project being cashed out from.
-    /// @param cashOutCount The number of project tokens being cashed out.
-    /// @param tokenToReclaim The token being reclaimed.
+    /// @param projectId The ID of the project to cash out from.
+    /// @param cashOutCount The number of project tokens to cash out.
+    /// @param tokenToReclaim The token to reclaim.
     /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Passed through to data
     /// hooks so they can skip their own fees when value stays in the protocol (e.g. project-to-project routing).
     /// @param metadata Extra data to pass along to the data hook.
@@ -269,8 +271,8 @@ interface IJBTerminalStore {
 
     /// @notice Records a payment to a project.
     /// @param payer The address of the payer.
-    /// @param amount The amount being paid.
-    /// @param projectId The ID of the project being paid.
+    /// @param amount The amount to pay.
+    /// @param projectId The ID of the project to pay.
     /// @param beneficiary The address to mint project tokens to.
     /// @param metadata Extra data to pass along to the data hook.
     /// @return ruleset The project's current ruleset.
@@ -288,8 +290,8 @@ interface IJBTerminalStore {
 
     /// @notice Records a payout from a project.
     /// @param projectId The ID of the project paying out.
-    /// @param token The token being paid out.
-    /// @param amount The amount being paid out.
+    /// @param token The token to pay out.
+    /// @param amount The amount to pay out.
     /// @param currency The currency the amount is denominated in.
     /// @return ruleset The project's current ruleset.
     /// @return amountPaidOut The amount paid out in the token's native decimals.
@@ -303,14 +305,14 @@ interface IJBTerminalStore {
         returns (JBRuleset memory ruleset, uint256 amountPaidOut);
 
     /// @notice Records a terminal migration for a project.
-    /// @param projectId The ID of the project being migrated.
-    /// @param token The token being migrated.
+    /// @param projectId The ID of the project to migrate.
+    /// @param token The token to migrate.
     /// @return balance The balance that was migrated.
     function recordTerminalMigration(uint256 projectId, address token) external returns (uint256 balance);
 
     /// @notice Records surplus allowance usage for a project.
     /// @param projectId The ID of the project using surplus allowance.
-    /// @param token The token being used.
+    /// @param token The token to use.
     /// @param amount The amount of surplus allowance to use.
     /// @param currency The currency the amount is denominated in.
     /// @return ruleset The project's current ruleset.

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.
@@ -87,7 +88,7 @@ interface IJBTokens {
     /// @return The credit balance.
     function creditBalanceOf(address holder, uint256 projectId) external view returns (uint256);
 
-    /// @notice Returns the project ID associated with a token.
+    /// @notice The project ID that a given ERC-20 token contract is associated with.
     /// @param token The token to get the project ID of.
     /// @return The project ID.
     function projectIdOf(IJBToken token) external view returns (uint256);
@@ -115,13 +116,13 @@ interface IJBTokens {
 
     /// @notice Burns tokens and/or credits from a holder's balance.
     /// @param holder The address to burn tokens from.
-    /// @param projectId The ID of the project whose tokens are being burned.
+    /// @param projectId The ID of the project to burn tokens for.
     /// @param count The number of tokens to burn.
     function burnFrom(address holder, uint256 projectId, uint256 count) external;
 
     /// @notice Claims tokens from a holder's credits into a beneficiary's account.
     /// @param holder The address to claim credits from.
-    /// @param projectId The ID of the project whose tokens are being claimed.
+    /// @param projectId The ID of the project to claim tokens for.
     /// @param count The number of tokens to claim.
     /// @param beneficiary The address to send the claimed tokens to.
     function claimTokensFor(address holder, uint256 projectId, uint256 count, address beneficiary) external;
@@ -143,7 +144,7 @@ interface IJBTokens {
 
     /// @notice Mints tokens or credits for a holder.
     /// @param holder The address to mint tokens for.
-    /// @param projectId The ID of the project whose tokens are being minted.
+    /// @param projectId The ID of the project to mint tokens for.
     /// @param count The number of tokens to mint.
     /// @return token The project's token, if one exists.
     function mintFor(address holder, uint256 projectId, uint256 count) external returns (IJBToken token);
@@ -154,14 +155,14 @@ interface IJBTokens {
     function setTokenFor(uint256 projectId, IJBToken token) external;
 
     /// @notice Sets the name and symbol of a project's token.
-    /// @param projectId The ID of the project whose token is being updated.
+    /// @param projectId The ID of the project to update the token for.
     /// @param name The new name.
     /// @param symbol The new symbol.
     function setTokenMetadataFor(uint256 projectId, string calldata name, string calldata symbol) external;
 
     /// @notice Transfers credits from one holder to another.
     /// @param holder The address to transfer credits from.
-    /// @param projectId The ID of the project whose credits are being transferred.
+    /// @param projectId The ID of the project to transfer credits for.
     /// @param recipient The address to transfer credits to.
     /// @param count The number of credits to transfer.
     function transferCreditsFrom(address holder, uint256 projectId, address recipient, uint256 count) external;

package/src/libraries/JBCashOuts.sol

@@ -5,15 +5,20 @@ 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();
 
     /// @notice Returns the amount of surplus terminal tokens which can be reclaimed based on the total surplus, the
-    /// number of tokens being cashed out, the total token supply, and the ruleset's cash out tax rate.
+    /// number of tokens to cash out, the total token supply, and the ruleset's cash out tax rate.
     /// @param surplus The total amount of surplus terminal tokens.
-    /// @param cashOutCount The number of tokens being cashed out, as a fixed point number with 18 decimals.
+    /// @param cashOutCount The number of tokens to cash out, as a fixed point number with 18 decimals.
     /// @param totalSupply The total token supply, as a fixed point number with 18 decimals.
     /// @param cashOutTaxRate The current ruleset's cash out tax rate.
     /// @return reclaimableSurplus The amount of surplus tokens that can be reclaimed.

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(
@@ -41,9 +44,9 @@ library JBPayoutSplitGroupLib {
     /// @param splits The splits contract to read splits from.
     /// @param store The terminal store used to restore balance when a payout fails.
     /// @param projectId The ID of the project to send the payouts of.
-    /// @param token The address of the token being paid out.
-    /// @param rulesetId The ID of the ruleset of the split group being paid.
-    /// @param amount The total amount being paid out.
+    /// @param token The address of the token to pay out.
+    /// @param rulesetId The ID of the ruleset of the split group to pay.
+    /// @param amount The total amount to pay out.
     /// @param caller The original caller of the terminal payout flow.
     /// @return leftoverAmount The leftover amount after split payouts.
     /// @return amountEligibleForFees The amount of payouts that are eligible for fees.
@@ -118,8 +121,8 @@ library JBPayoutSplitGroupLib {
     /// @param store The terminal store used to restore balance when a payout fails.
     /// @param split The split to pay.
     /// @param projectId The ID of the project the split was specified by.
-    /// @param token The address of the token being paid out.
-    /// @param amount The total amount that the split is being paid.
+    /// @param token The address of the token to pay out.
+    /// @param amount The total amount that the split is paid.
     /// @param caller The original caller of the terminal payout flow.
     /// @return netPayoutAmount The amount sent to the split after subtracting fees.
     function _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,10 +3,12 @@ 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
+    /// @dev This amount changes as the value of the balances changes in relation to the currency used to measure
     /// the project's payout limits.
     /// @param projectId The ID of the project to get the total surplus for.
     /// @param terminals The terminals to look for surplus within.

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/JBAfterCashOutRecordedContext.sol

@@ -3,16 +3,16 @@ pragma solidity ^0.8.0;
 
 import {JBTokenAmount} from "./JBTokenAmount.sol";
 
-/// @custom:member holder The holder of the tokens being cashed out.
-/// @custom:member projectId The ID of the project being cashed out from.
-/// @custom:member rulesetId The ID of the ruleset the cash out is being made during.
-/// @custom:member cashOutCount The number of project tokens being cashed out.
+/// @custom:member holder The holder of the tokens to cash out.
+/// @custom:member projectId The ID of the project to cash out from.
+/// @custom:member rulesetId The ID of the ruleset the cash out is made during.
+/// @custom:member cashOutCount The number of project tokens to cash out.
 /// @custom:member cashOutTaxRate The current ruleset's cash out tax rate.
-/// @custom:member reclaimedAmount The token amount being reclaimed from the project's terminal balance. Includes the
-/// token being
+/// @custom:member reclaimedAmount The token amount reclaimed from the project's terminal balance. Includes the
+/// token
 /// reclaimed, the value, the number of decimals included, and the currency of the amount.
-/// @custom:member forwardedAmount The token amount being forwarded to the cash out hook. Includes the token
-/// being forwarded, the value, the number of decimals included, and the currency of the amount.
+/// @custom:member forwardedAmount The token amount forwarded to the cash out hook. Includes the token
+/// forwarded, the value, the number of decimals included, and the currency of the amount.
 /// @custom:member beneficiary The address the reclaimed amount will be sent to.
 /// @custom:member hookMetadata Extra data specified by the data hook, which is sent to the cash out hook.
 /// @custom:member cashOutMetadata Extra data specified by the account cashing out, which is sent to the cash out hook.