@bananapus/core-v6 0.0.37 → 0.0.39

package/src/JBTerminalStore.sol

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

package/src/JBTokens.sol

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

package/src/abstract/JBControlled.sol

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

package/src/abstract/JBPermissioned.sol

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

package/src/enums/JBApprovalStatus.sol

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

package/src/interfaces/IJBController.sol

@@ -23,8 +23,9 @@ import {JBSplit} from "./../structs/JBSplit.sol";
 import {JBSplitGroup} from "./../structs/JBSplitGroup.sol";
 import {JBTerminalConfig} from "./../structs/JBTerminalConfig.sol";
 
-/// @notice Coordinates rulesets and project tokens, and is the entry point for most operations related to rulesets and
-/// project tokens.
+/// @notice The interface for the protocol's project controller — launch projects, queue rulesets, mint/burn tokens,
+/// deploy ERC-20s, distribute reserved tokens, and manage all project configuration. This is the primary contract
+/// project owners and frontends interact with.
 interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessControl {
     /// @notice Tokens were burned from a holder's balance.
     /// @param holder The address whose tokens were burned.
@@ -57,9 +58,10 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     /// @notice Rulesets were launched for an existing project.
     /// @param rulesetId The ID of the first queued ruleset.
     /// @param projectId The ID of the project.
+    /// @param projectUri The metadata URI of the project.
     /// @param memo A memo associated with the launch.
     /// @param caller The address that called the launch function.
-    event LaunchRulesets(uint256 rulesetId, uint256 projectId, string memo, address caller);
+    event LaunchRulesets(uint256 rulesetId, uint256 projectId, string projectUri, string memo, address caller);
 
     /// @notice Tokens were minted for a beneficiary.
     /// @param beneficiary The address that received the minted tokens.
@@ -313,12 +315,14 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
 
     /// @notice Queues a project's initial rulesets and sets up terminals for it.
     /// @param projectId The ID of the project to launch rulesets for.
+    /// @param projectUri The project's metadata URI. Pass an empty string to leave it unchanged.
     /// @param rulesetConfigurations The rulesets to queue.
     /// @param terminalConfigurations The terminals to set up.
     /// @param memo A memo to pass along to the emitted event.
     /// @return rulesetId The ID of the last successfully queued ruleset.
     function launchRulesetsFor(
         uint256 projectId,
+        string calldata projectUri,
         JBRulesetConfig[] calldata rulesetConfigurations,
         JBTerminalConfig[] calldata terminalConfigurations,
         string calldata memo

package/src/interfaces/IJBDirectory.sol

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

package/src/interfaces/IJBMultiTerminal.sol

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

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,26 +5,68 @@ 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.
+    /// @dev If a nonzero amount and nonzero fee would otherwise produce a zero fee, returns 1 so feeable dust payouts
+    /// cannot bypass protocol fees by splitting across tiny transfers.
+    /// @param amountBeforeFee The amount before the fee is applied, as a fixed point number.
+    /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
+    /// @return The fee amount, as a fixed point number with the same number of decimals as the provided `amount`.
+    function feeAmountFrom(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
+        uint256 feeAmount = feeAmountFromFloor({amountBeforeFee: amountBeforeFee, feePercent: feePercent});
+
+        return feeAmount == 0 && amountBeforeFee != 0 && feePercent != 0 ? 1 : feeAmount;
+    }
+
+    /// @notice Returns the floor-rounded fee that would be taken from `amountBeforeFee`.
+    /// @dev Fee rounding error is bounded by N-1 wei (N = number of splits). Economically insignificant. Rounds down
+    /// (mulDiv floors), so the fee beneficiary may receive up to 1 wei less per split.
+    /// @param amountBeforeFee The amount before the fee is applied, as a fixed point number.
+    /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
+    /// @return The floor-rounded fee amount, as a fixed point number with the same number of decimals as the provided
+    /// `amount`.
+    function feeAmountFromFloor(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
+        return mulDiv(amountBeforeFee, feePercent, JBConstants.MAX_FEE);
+    }
+
     /// @notice Returns the fee amount that, when added to `amountAfterFee`, produces the gross amount needed to yield
     /// `amountAfterFee` after the fee is deducted.
     /// @dev Use this to back-calculate the fee from a desired post-fee payout.
+    /// @dev If a nonzero amount and nonzero fee would otherwise produce a zero fee, returns 1 so feeable dust payouts
+    /// cannot bypass protocol fees by splitting across tiny transfers.
     /// @param amountAfterFee The desired post-fee amount, as a fixed point number.
     /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
     /// @return The fee amount, as a fixed point number with the same number of decimals as the provided `amount`.
     function feeAmountResultingIn(uint256 amountAfterFee, uint256 feePercent) internal pure returns (uint256) {
-        return mulDiv(amountAfterFee, JBConstants.MAX_FEE, JBConstants.MAX_FEE - feePercent) - amountAfterFee;
+        uint256 feeAmount = feeAmountResultingInFloor({amountAfterFee: amountAfterFee, feePercent: feePercent});
+
+        return feeAmount == 0 && amountAfterFee != 0 && feePercent != 0 ? 1 : feeAmount;
     }
 
-    /// @notice Returns the fee that would be taken from `amountBeforeFee`.
-    /// @dev Use this to forward-calculate the fee from a known pre-fee amount.
-    /// @dev Fee rounding error is bounded by N-1 wei (N = number of splits). Economically
-    /// insignificant. Rounds down (mulDiv floors), so the fee beneficiary may receive up to 1 wei less per split.
-    /// @param amountBeforeFee The amount before the fee is applied, as a fixed point number.
+    /// @notice Returns the floor-rounded fee amount that, when added to `amountAfterFee`, produces the gross amount
+    /// needed to yield `amountAfterFee` after the fee is deducted.
+    /// @dev Use this when adjusting an existing held-fee entry, where applying the 1-unit minimum again would double
+    /// charge dust.
+    /// @param amountAfterFee The desired post-fee amount, as a fixed point number.
     /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
-    /// @return The fee amount, as a fixed point number with the same number of decimals as the provided `amount`.
-    function feeAmountFrom(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
-        return mulDiv(amountBeforeFee, feePercent, JBConstants.MAX_FEE);
+    /// @return The floor-rounded fee amount, as a fixed point number with the same number of decimals as the provided
+    /// `amount`.
+    function feeAmountResultingInFloor(uint256 amountAfterFee, uint256 feePercent) internal pure returns (uint256) {
+        return mulDiv(amountAfterFee, JBConstants.MAX_FEE, JBConstants.MAX_FEE - feePercent) - amountAfterFee;
+    }
+
+    /// @notice Returns the floor-rounded fee amount resulting in `amountAfterFee` for a 2.5% fee.
+    /// @dev Equivalent to `feeAmountResultingInFloor(amountAfterFee, 25)`, but avoids the generic `mulDiv` path.
+    /// @param amountAfterFee The desired post-fee amount, as a fixed point number.
+    /// @return The floor-rounded fee amount.
+    function feeAmountResultingInFloorForFee25(uint256 amountAfterFee) internal pure returns (uint256) {
+        // The specialized denominator is `(JBConstants.MAX_FEE - 25) / 25`.
+        return amountAfterFee / 39;
     }
 }

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