@bananapus/core-v6 0.0.38 → 0.0.40

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 {
@@ -222,9 +227,9 @@ contract JBTerminalStore is IJBTerminalStore {
         }
     }
 
-    /// @notice Records funds being added to a project's balance.
-    /// @param projectId The ID of the project which funds are being added to the balance of.
-    /// @param token The token being added to the balance.
+    /// @notice Records funds added to a project's balance.
+    /// @param projectId The ID of the project which funds are added to the balance of.
+    /// @param token The token to add to the balance.
     /// @param amount The amount of terminal tokens added, as a fixed point number with the same amount of decimals as
     /// its relative terminal.
     function recordAddedBalanceFor(uint256 projectId, address token, uint256 amount) external override {
@@ -232,15 +237,14 @@ 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 to cash 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.
+    /// @param tokenToReclaim The token to reclaim by the cash out.
     /// @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 Bytes to send to the data hook, if the project's current ruleset specifies one.
@@ -310,13 +314,13 @@ 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
+    /// @param amount The amount of tokens to pay. Includes the token paid, their value, the number of
     /// decimals included, and the currency of the amount.
-    /// @param projectId The ID of the project being paid.
+    /// @param projectId The ID of the project to pay.
     /// @param beneficiary The address that should be the beneficiary of anything the payment yields (including project
     /// tokens minted by the payment).
     /// @param metadata Bytes to send to the data hook, if the project's current ruleset specifies one.
@@ -353,12 +357,12 @@ 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 token The token to pay out.
     /// @param amount The amount to pay out (use from the payout limit), as a fixed point number.
     /// @param currency The currency of the `amount`. This must match the project's current ruleset's currency.
     /// @return ruleset The ruleset the payout was made during, as a `JBRuleset` struct.
@@ -428,11 +432,12 @@ contract JBTerminalStore is IJBTerminalStore {
         usedPayoutLimitOf[msg.sender][projectId][token][ruleset.cycleNumber][currency] = newUsedPayoutLimitOf;
     }
 
-    /// @notice Records the migration of funds from this store.
-    /// @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
-    /// amount of decimals as its relative terminal.
+    /// @notice Records a terminal migration — zeros out the project's balance and returns the amount moved to
+    /// the new terminal. The current ruleset must allow terminal migration.
+    /// @param projectId The ID of the project to migrate.
+    /// @param token The token to migrate.
+    /// @return balance The project's current balance (the amount that will migrate), as a fixed point number with the
+    /// same amount of decimals as its relative terminal.
     function recordTerminalMigration(uint256 projectId, address token) external override returns (uint256 balance) {
         // Get a reference to the project's current ruleset.
         JBRuleset memory ruleset = RULESETS.currentOf(projectId);
@@ -449,13 +454,15 @@ 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 token The token whose balances should contribute to the surplus allowance to reclaim from.
     /// @param amount The amount to use from the surplus allowance, as a fixed point number.
     /// @param currency The currency of the `amount`. Must match the currency of the surplus allowance.
-    /// @return ruleset The ruleset during the surplus allowance is being used during, as a `JBRuleset` struct.
+    /// @return ruleset The ruleset the surplus allowance applies to, as a `JBRuleset` struct.
     /// @return usedAmount The amount of terminal tokens used, as a fixed point number with the same amount of decimals
     /// as its relative terminal.
     function recordUsedAllowanceOf(
@@ -690,9 +697,9 @@ contract JBTerminalStore is IJBTerminalStore {
     /// preview and execution).
     /// @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.
@@ -734,8 +741,8 @@ contract JBTerminalStore is IJBTerminalStore {
     /// `recordPaymentFrom` would produce.
     /// @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.
@@ -834,9 +841,9 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @dev When `useTotalSurplusForCashOuts` is enabled, surplus is aggregated from ALL registered terminals without
     /// validation. Projects MUST only register trusted terminals — an untrusted terminal can over-report surplus and
     /// cause the executing terminal to overpay cash-outs.
-    /// @param terminal The terminal the cash out is being recorded from.
-    /// @param projectId The ID of the project being cashed out from.
-    /// @param tokenToReclaim The token being reclaimed.
+    /// @param terminal The terminal recording the cash out.
+    /// @param projectId The ID of the project to cash out from.
+    /// @param tokenToReclaim The token to reclaim.
     /// @param ruleset The ruleset during the cash out.
     /// @return The surplus amount in the token's native decimals and currency.
     function _cashOutSurplusOf(
@@ -932,9 +939,9 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @notice Computes cash out results without writing state.
     /// @param terminal The terminal recording the cash out.
     /// @param holder The account that is cashing out tokens.
-    /// @param projectId The ID of the project being cashed out from.
+    /// @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 being reclaimed.
+    /// @param tokenToReclaim The token to reclaim.
     /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address.
     /// @param metadata Bytes to send to the data hook.
     /// @return ruleset The ruleset during the cash out.
@@ -1028,8 +1035,8 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @notice Computes payment results without writing state.
     /// @param terminal The terminal recording the payment.
     /// @param payer The address that made the payment.
-    /// @param amount The amount of tokens being paid.
-    /// @param projectId The ID of the project being paid.
+    /// @param amount The amount of tokens to pay.
+    /// @param projectId The ID of the project to pay.
     /// @param beneficiary The beneficiary of the payment.
     /// @param metadata Bytes to send to the data hook.
     /// @return ruleset The ruleset the payment would be made during.
@@ -1232,12 +1239,12 @@ contract JBTerminalStore is IJBTerminalStore {
 
     /// @notice Gets a project's surplus amount in a terminal as measured by a given ruleset, across multiple accounting
     /// contexts.
-    /// @dev This amount changes as the value of the balance changes in relation to the currency being used to measure
+    /// @dev This amount changes as the value of the balance changes in relation to the currency used to measure
     /// various payout limits.
-    /// @param terminal The terminal the surplus is being calculated for.
+    /// @param terminal The terminal to calculate surplus for.
     /// @param projectId The ID of the project to get the surplus for.
     /// @param accountingContexts The accounting contexts of tokens whose balances should contribute to the surplus
-    /// being calculated.
+    /// calculated.
     /// @param ruleset The ruleset to base the surplus on.
     /// @param targetDecimals The number of decimals to include in the resulting fixed point number.
     /// @param targetCurrency The currency that the reported surplus is expected to be in terms of.
@@ -1278,12 +1285,12 @@ contract JBTerminalStore is IJBTerminalStore {
 
     /// @notice Get a project's surplus amount of a specific token in a given terminal as measured by a given ruleset
     /// (one specific accounting context).
-    /// @dev This amount changes as the value of the balance changes in relation to the currency being used to measure
+    /// @dev This amount changes as the value of the balance changes in relation to the currency used to measure
     /// the payout limits.
-    /// @param terminal The terminal the surplus is being calculated for.
+    /// @param terminal The terminal to calculate surplus for.
     /// @param projectId The ID of the project to get the surplus of.
     /// @param accountingContext The accounting context of the token whose balance should contribute to the surplus
-    /// being measured.
+    /// measured.
     /// @param ruleset The ID of the ruleset to base the surplus calculation on.
     /// @param targetDecimals The number of decimals to include in the resulting fixed point number.
     /// @param targetCurrency The currency that the reported surplus is expected to be in terms of.

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 ------------------------- //
@@ -47,7 +47,7 @@ contract JBTokens is JBControlled, IJBTokens {
     /// @custom:param projectId The ID of the project to which the credits belong.
     mapping(address holder => mapping(uint256 projectId => uint256)) public override creditBalanceOf;
 
-    /// @notice Each token's project.
+    /// @notice The project ID that a given ERC-20 token is associated with.
     /// @custom:param token The address of the token associated with the project.
     // slither-disable-next-line unused-return
     mapping(IJBToken token => uint256) public override projectIdOf;
@@ -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.
-    /// @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.
+    /// @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 to burn tokens from.
+    /// @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,10 +131,12 @@ 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.
+    /// @param holder The owner of the credits to redeem.
+    /// @param projectId The ID of the project to claim tokens for.
     /// @param count The number of tokens to claim.
     /// @param beneficiary The account into which the claimed tokens will go.
     function claimTokensFor(
@@ -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,9 +314,10 @@ 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 projectId The ID of the project to update the token for.
     /// @param name The new name.
     /// @param symbol The new symbol.
     function setTokenMetadataFor(
@@ -340,10 +347,11 @@ 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.
+    /// @param projectId The ID of the project to transfer credits for.
     /// @param recipient The recipient of the credits.
     /// @param count The number of token credits to transfer.
     function transferCreditsFrom(
@@ -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/IJBCashOutTerminal.sol

@@ -12,7 +12,7 @@ interface IJBCashOutTerminal is IJBTerminal {
     /// @notice A cash out was processed for a project.
     /// @param rulesetId The ID of the ruleset during the cash out.
     /// @param rulesetCycleNumber The cycle number of the ruleset during the cash out.
-    /// @param projectId The ID of the project being cashed out from.
+    /// @param projectId The ID of the project to cash out from.
     /// @param holder The address whose tokens were cashed out.
     /// @param beneficiary The address that received the reclaimed funds.
     /// @param cashOutCount The number of tokens cashed out.
@@ -48,8 +48,8 @@ interface IJBCashOutTerminal is IJBTerminal {
     );
 
     /// @notice Simulates cashing out project tokens from this terminal without modifying state.
-    /// @param holder The address whose tokens are being cashed out.
-    /// @param projectId The ID of the project whose tokens are being cashed out.
+    /// @param holder The address cashing out tokens.
+    /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out.
     /// @param tokenToReclaim The token to reclaim from the project's surplus.
     /// @param beneficiary The address that would receive the reclaimed tokens.
@@ -77,8 +77,8 @@ interface IJBCashOutTerminal is IJBTerminal {
 
     /// @notice Cashes out a holder's tokens for a project, reclaiming the token's proportional share of the project's
     /// surplus.
-    /// @param holder The address whose tokens are being cashed out.
-    /// @param projectId The ID of the project whose tokens are being cashed out.
+    /// @param holder The address cashing out tokens.
+    /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out.
     /// @param tokenToReclaim The token to reclaim from the project's surplus.
     /// @param minTokensReclaimed The minimum number of terminal tokens expected to be reclaimed.

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.
@@ -81,8 +82,8 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     );
 
     /// @notice A project was prepared for migration from another controller.
-    /// @param projectId The ID of the project being prepared for migration.
-    /// @param from The controller the project is being migrated from.
+    /// @param projectId The ID of the project to prepare for migration.
+    /// @param from The controller to migrate from.
     /// @param caller The address that called the prep migration function.
     event PrepMigration(uint256 indexed projectId, address from, address caller);
 
@@ -225,7 +226,7 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     function pendingReservedTokenBalanceOf(uint256 projectId) external view returns (uint256);
 
     /// @notice Previews how many beneficiary and reserved tokens `mintTokensOf(...)` would produce.
-    /// @param projectId The ID of the project whose tokens are being minted.
+    /// @param projectId The ID of the project to mint tokens for.
     /// @param tokenCount The number of tokens to mint, including any reserved tokens.
     /// @param useReservedPercent Whether to apply the ruleset's reserved percent.
     /// @return beneficiaryTokenCount The number of tokens that would be minted for the beneficiary.
@@ -256,7 +257,7 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     /// @notice Adds a price feed for a project.
     /// @param projectId The ID of the project to add the 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,
@@ -267,15 +268,15 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
         external;
 
     /// @notice Burns a holder's project tokens or credits.
-    /// @param holder The address whose tokens are being burned.
-    /// @param projectId The ID of the project whose tokens are being burned.
+    /// @param holder The address to burn tokens for.
+    /// @param projectId The ID of the project to burn tokens for.
     /// @param tokenCount The number of tokens to burn.
     /// @param memo A memo to pass along to the emitted event.
     function burnTokensOf(address holder, uint256 projectId, uint256 tokenCount, string calldata memo) external;
 
     /// @notice Redeems credits to claim tokens into a beneficiary's account.
     /// @param holder The address to redeem 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 tokenCount The number of tokens to claim.
     /// @param beneficiary The account the claimed tokens will go to.
     function claimTokensFor(address holder, uint256 projectId, uint256 tokenCount, address beneficiary) external;
@@ -330,7 +331,7 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
         returns (uint256 rulesetId);
 
     /// @notice Mints new project tokens or credits to a beneficiary, optionally reserving a portion.
-    /// @param projectId The ID of the project whose tokens are being minted.
+    /// @param projectId The ID of the project to mint tokens for.
     /// @param tokenCount The number of tokens to mint, including any reserved tokens.
     /// @param beneficiary The address which will receive the non-reserved tokens.
     /// @param memo A memo to pass along to the emitted event.
@@ -376,14 +377,14 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     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 setTokenMetadataOf(uint256 projectId, string calldata name, string calldata symbol) external;
 
     /// @notice Transfers credits from one address 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 creditCount The number of credits to transfer.
     function transferCreditsFrom(address holder, uint256 projectId, address recipient, uint256 creditCount) external;

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

@@ -12,17 +12,17 @@ interface IJBMigratable is IERC165 {
     event Migrate(uint256 indexed projectId, IERC165 to, address caller);
 
     /// @notice Called after this controller has been set as the project's controller in the directory.
-    /// @param from The controller being migrated from.
+    /// @param from The controller to migrate from.
     /// @param projectId The ID of the project that was migrated.
     function afterReceiveMigrationFrom(IERC165 from, uint256 projectId) external;
 
-    /// @notice Prepares this controller to receive a project being migrated from another controller.
-    /// @param from The controller being migrated from.
-    /// @param projectId The ID of the project being migrated.
+    /// @notice Prepares this controller to receive a project to migrate from another controller.
+    /// @param from The controller to migrate from.
+    /// @param projectId The ID of the project to migrate.
     function beforeReceiveMigrationFrom(IERC165 from, uint256 projectId) external;
 
     /// @notice Migrates a project from this controller to another.
-    /// @param projectId The ID of the project being migrated.
+    /// @param projectId The ID of the project to migrate.
     /// @param to The controller to migrate the project to.
     function migrate(uint256 projectId, IERC165 to) external;
 }

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);