@bananapus/core-v6 0.0.38 → 0.0.40

package/foundry.toml

@@ -17,7 +17,7 @@ fail_on_revert = false
 ethereum = "${RPC_ETHEREUM_MAINNET}"
 
 [lint]
-exclude_lints = ["block-timestamp", "mixed-case-variable", "pascal-case-struct"]
+exclude_lints = ["mixed-case-variable", "pascal-case-struct"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBChainlinkV3PriceFeed.sol

@@ -6,7 +6,9 @@ import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interf
 import {IJBPriceFeed} from "./interfaces/IJBPriceFeed.sol";
 import {JBFixedPointNumber} from "./libraries/JBFixedPointNumber.sol";
 
-/// @notice An `IJBPriceFeed` implementation that reports prices from a Chainlink `AggregatorV3Interface`.
+/// @notice A price feed adapter that reads from a Chainlink V3 aggregator. Reverts if the price is stale (older than
+/// `THRESHOLD` seconds), negative, or from an incomplete round — protecting against serving outdated oracle data.
+/// Used by `JBPrices` to convert between currencies (e.g. ETH/USD).
 contract JBChainlinkV3PriceFeed is IJBPriceFeed {
     // A library that provides utility for fixed point numbers.
     using JBFixedPointNumber for uint256;
@@ -60,6 +62,7 @@ contract JBChainlinkV3PriceFeed is IJBPriceFeed {
         if (answeredInRound < roundId) revert JBChainlinkV3PriceFeed_IncompleteRound();
 
         // Make sure the price's update threshold is met.
+        // forge-lint: disable-next-line(block-timestamp)
         if (block.timestamp > THRESHOLD + updatedAt) {
             revert JBChainlinkV3PriceFeed_StalePrice(block.timestamp, THRESHOLD, updatedAt);
         }

package/src/JBChainlinkV3SequencerPriceFeed.sol

@@ -6,8 +6,9 @@ import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interf
 
 import {JBChainlinkV3PriceFeed} from "./JBChainlinkV3PriceFeed.sol";
 
-/// @notice An `IJBPriceFeed` implementation that reports prices from a Chainlink `AggregatorV3Interface` from
-/// optimistic sequencers.
+/// @notice Extends `JBChainlinkV3PriceFeed` with L2 sequencer uptime checks (for Optimism, Arbitrum, etc.). Reverts if
+/// the sequencer is down or has not been back online for at least `GRACE_PERIOD_TIME` seconds — preventing stale
+/// prices from to use immediately after an outage.
 contract JBChainlinkV3SequencerPriceFeed is JBChainlinkV3PriceFeed {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -64,6 +65,7 @@ contract JBChainlinkV3SequencerPriceFeed is JBChainlinkV3PriceFeed {
         if (startedAt == 0) revert JBChainlinkV3SequencerPriceFeed_InvalidRound();
 
         // Revert if sequencer has too recently restarted or is currently down.
+        // forge-lint: disable-next-line(block-timestamp)
         if (block.timestamp <= GRACE_PERIOD_TIME + startedAt || answer != 0) {
             revert JBChainlinkV3SequencerPriceFeed_SequencerDownOrRestarting(
                 block.timestamp, GRACE_PERIOD_TIME, startedAt

package/src/JBController.sol

@@ -41,8 +41,13 @@ import {JBSplitGroup} from "./structs/JBSplitGroup.sol";
 import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
 import {JBTerminalConfig} from "./structs/JBTerminalConfig.sol";
 
-/// @notice `JBController` coordinates rulesets and project tokens, and is the entry point for most operations related
-/// to rulesets and project tokens.
+/// @notice The orchestrator for every Juicebox project's lifecycle. Use the controller to launch a project, queue new
+/// rulesets (funding cycles), mint or burn tokens, deploy an ERC-20, distribute reserved tokens, and manage
+/// permissions. The controller coordinates between the terminal (money), rulesets (rules), tokens (issuance), and
+/// splits (distribution).
+/// @dev Supports ERC-2771 meta-transactions. Implements `IJBMigratable` for controller-to-controller migration.
+/// An omnichain deployer address is trusted to launch and queue rulesets on behalf of any project for cross-chain
+/// coordination.
 contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigratable {
     // A library that parses packed ruleset metadata into a friendlier format.
     using JBRulesetMetadataResolver for JBRuleset;
@@ -166,11 +171,12 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Add a price feed for a project.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to `ADD_PRICE_FEED`.
+    /// @notice Registers a price feed so the project can use a new currency for payout limits or surplus allowances.
+    /// @dev Can only be called by the project's owner or an operator with `ADD_PRICE_FEED` permission. The current
+    /// ruleset must have `allowAddPriceFeed` enabled.
     /// @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 address of the price feed to add.
     function addPriceFeedFor(
         uint256 projectId,
@@ -198,7 +204,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
     /// @notice Called after this controller has been set as the project's controller in the directory.
     /// @dev Can only be called by the directory.
-    /// @param from The controller being migrated from.
+    /// @param from The controller to migrate from.
     /// @param projectId The ID of the project that migrated to this controller.
     function afterReceiveMigrationFrom(IERC165 from, uint256 projectId) external view override {
         from; // Suppress unused variable warning.
@@ -208,9 +214,9 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         if (_msgSender() != address(DIRECTORY)) revert JBController_OnlyDirectory(_msgSender(), DIRECTORY);
     }
 
-    /// @notice Prepares this controller to receive a project being migrated from another controller.
+    /// @notice Prepares this controller to receive a project to migrate from another controller.
     /// @dev This controller should not be the project's controller yet.
-    /// @param from The controller being migrated from.
+    /// @param from The controller to migrate from.
     /// @param projectId The ID of the project that will migrate to this controller.
     function beforeReceiveMigrationFrom(IERC165 from, uint256 projectId) external override {
         // Keep a reference to the sender.
@@ -234,11 +240,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice Burns a project's tokens or credits from the specific holder's balance.
-    /// @dev Can only be called by the holder, an address with the holder's permission to `BURN_TOKENS`, or a project's
-    /// terminal.
-    /// @param holder The address whose tokens are being burned.
-    /// @param projectId The ID of the project whose tokens are being burned.
+    /// @notice Burns a holder's project tokens (or credits), permanently removing them from supply. Used by terminals
+    /// during cash outs, or directly by holders who want to burn voluntarily.
+    /// @dev Can only be called by the holder, an operator with `BURN_TOKENS` permission, or a project terminal.
+    /// @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(
@@ -269,10 +275,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         TOKENS.burnFrom({holder: holder, projectId: projectId, count: tokenCount});
     }
 
-    /// @notice Redeem credits to claim tokens into a `beneficiary`'s account.
-    /// @dev Can only be called by the credit holder or an address with the holder's permission to `CLAIM_TOKENS`.
+    /// @notice Converts internal credits into the project's ERC-20 token, transferring them to the beneficiary's
+    /// wallet. Credits and ERC-20 tokens are interchangeable — this just makes them transferable/tradeable.
+    /// @dev Can only be called by the credit holder or an operator with `CLAIM_TOKENS` permission.
     /// @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(
@@ -290,9 +297,10 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         TOKENS.claimTokensFor({holder: holder, projectId: projectId, count: tokenCount, beneficiary: beneficiary});
     }
 
-    /// @notice Deploys an ERC-20 token for a project. It will be used when claiming tokens (with credits).
-    /// @dev Deploys the project's ERC-20 contract.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to `DEPLOY_ERC20`.
+    /// @notice Deploys a new ERC-20 token for a project. Once deployed, holders can claim their credits as this token.
+    /// Includes ERC20Votes (governance) and ERC20Permit (gasless approvals).
+    /// @dev Can only be called by the project's owner or an operator with `DEPLOY_ERC20` permission.
+    /// @dev Each project can only have one ERC-20 deployed — calling this again after deployment will revert.
     /// @param projectId The ID of the project to deploy the ERC-20 for.
     /// @param name The ERC-20's name.
     /// @param symbol The ERC-20's symbol.
@@ -330,9 +338,9 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     /// terminal.
     /// @dev Can only be called by this controller.
     /// @param terminal The terminal to pay.
-    /// @param projectId The ID of the project being paid.
-    /// @param token The token being paid with.
-    /// @param splitTokenCount The number of tokens being paid.
+    /// @param projectId The ID of the project to pay.
+    /// @param token The token to pay with.
+    /// @param splitTokenCount The number of tokens to pay.
     /// @param beneficiary The payment's beneficiary.
     /// @param metadata The pay metadata sent to the terminal.
     function executePayReservedTokenToTerminal(
@@ -368,10 +376,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice Creates a project.
-    /// @dev This will mint the project's ERC-721 to the `owner`'s address, queue the specified rulesets, and set up the
-    /// specified splits and terminals. Each operation within this transaction can be done in sequence separately.
-    /// @dev Anyone can deploy a project to any `owner`'s address.
+    /// @notice Creates a new Juicebox project in one transaction — mints the project NFT, queues initial rulesets,
+    /// and
+    /// configures terminals. This is the primary entry point for launching a project.
+    /// @dev Anyone can call this on behalf of any owner. Each sub-operation (mint, queue, configure) can also be done
+    /// individually if needed.
     /// @param owner The project's owner. The project ERC-721 will be minted to this address.
     /// @param projectUri The project's metadata URI. This is typically an IPFS hash, optionally with the `ipfs://`
     /// prefix. This can be updated by the project's owner.
@@ -414,10 +423,10 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         });
     }
 
-    /// @notice Queue a project's initial rulesets and set up terminals for it. Projects which already have rulesets
-    /// should use `queueRulesetsOf(...)`.
-    /// @dev Each operation within this transaction can be done in sequence separately.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to `LAUNCH_RULESETS`.
+    /// @notice Queues the first rulesets for an existing project and configures its terminals. For projects that
+    /// already have active rulesets, use `queueRulesetsOf(...)` instead.
+    /// @dev Can only be called by the project's owner or an operator with `LAUNCH_RULESETS` permission.
+    /// @dev Each sub-operation can also be done individually if needed.
     /// @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.
@@ -508,13 +517,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         if (pendingReservedTokenBalance != 0) revert JBController_PendingReservedTokens(pendingReservedTokenBalance);
     }
 
-    /// @notice Add new project tokens or credits to the specified beneficiary's balance. Optionally, reserve a portion
-    /// according to the ruleset's reserved percent.
-    /// @dev Can only be called by the project's owner, an address with the owner's permission to `MINT_TOKENS`, one of
-    /// the project's terminals, or the project's data hook.
-    /// @dev If the ruleset's metadata has `allowOwnerMinting` set to `false`, this function can only be called by the
-    /// project's terminals or data hook.
-    /// @param projectId The ID of the project whose tokens are being minted.
+    /// @notice Mints new project tokens to a beneficiary. Optionally reserves a portion according to the ruleset's
+    /// reserved percent (which accumulates until `sendReservedTokensToSplitsOf` is called).
+    /// @dev Can be called by the project owner, an operator with `MINT_TOKENS` permission, a project terminal, or the
+    /// data hook. If `allowOwnerMinting` is false in the current ruleset, only terminals and the data hook can mint.
+    /// @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.
@@ -594,9 +601,9 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice Add one or more rulesets to the end of a project's ruleset queue. Rulesets take effect after the
-    /// previous ruleset in the queue ends, and only if they are approved by the previous ruleset's approval hook.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to `QUEUE_RULESETS`.
+    /// @notice Queues new rulesets to take effect after the current one ends. Each queued ruleset must be approved by
+    /// the previous ruleset's approval hook (if one is set) before it can take effect.
+    /// @dev Can only be called by the project's owner or an operator with `QUEUE_RULESETS` permission.
     /// @param projectId The ID of the project to queue rulesets for.
     /// @param rulesetConfigurations The rulesets to queue.
     /// @param memo A memo to pass along to the emitted event.
@@ -628,17 +635,18 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         emit QueueRulesets({rulesetId: rulesetId, projectId: projectId, memo: memo, caller: _msgSender()});
     }
 
-    /// @notice Sends a project's pending reserved tokens to its reserved token splits.
-    /// @dev If the project has no reserved token splits, or if they don't add up to 100%, leftover tokens are sent to
-    /// the project's owner.
+    /// @notice Mints and distributes all pending reserved tokens to the project's reserved token split recipients.
+    /// Anyone can call this — it's permissionless.
+    /// @dev If splits don't add up to 100%, the remainder goes to the project owner.
     /// @param projectId The ID of the project to send reserved tokens for.
     /// @return The amount of reserved tokens minted and sent.
     function sendReservedTokensToSplitsOf(uint256 projectId) external override returns (uint256) {
         return _sendReservedTokensToSplitsOf(projectId);
     }
 
-    /// @notice Sets a project's split groups. The new split groups must include any current splits which are locked.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to `SET_SPLIT_GROUPS`.
+    /// @notice Configures how a project distributes payouts and reserved tokens. Locked splits from the current
+    /// configuration must be preserved in the new split groups.
+    /// @dev Can only be called by the project's owner or an operator with `SET_SPLIT_GROUPS` permission.
     /// @param projectId The ID of the project to set the split groups of.
     /// @param rulesetId The ID of the ruleset the split groups should be active in. Use a `rulesetId` of 0 to set the
     /// default split groups, which are used when a ruleset has no splits set. If there are no default splits and no
@@ -686,7 +694,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     /// @notice Sets the name and symbol of a project's token.
     /// @dev Can only be called by the project's owner or an address with the owner's permission to
     /// `SET_TOKEN_METADATA`.
-    /// @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 override {
@@ -716,10 +724,12 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         emit SetUri({projectId: projectId, uri: uri, caller: _msgSender()});
     }
 
-    /// @notice Allows a credit holder to transfer credits to another address.
-    /// @dev Can only be called by the credit holder or an address with the holder's permission to `TRANSFER_CREDITS`.
+    /// @notice Transfers internal credits (unclaimed tokens) from one address to another. Credits function like tokens
+    /// but live inside the protocol rather than as an ERC-20.
+    /// @dev Can only be called by the credit holder or an operator with `TRANSFER_CREDITS` permission. The current
+    /// ruleset must not have credit transfers paused.
     /// @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(
@@ -747,8 +757,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Get an array of a project's rulesets (with metadata) up to a maximum array size, sorted from latest to
-    /// earliest.
+    /// @notice Returns a paginated history of a project's rulesets (with decoded metadata), sorted newest-first.
     /// @param projectId The ID of the project to get the rulesets of.
     /// @param startingId The ID of the ruleset to begin with. This will be the latest ruleset in the result. If the
     /// `startingId` is 0, passed, the project's latest ruleset will be used.
@@ -786,7 +795,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice A project's currently active ruleset and its metadata.
+    /// @notice Returns the ruleset currently governing a project, along with its decoded metadata.
     /// @param projectId The ID of the project to get the current ruleset of.
     /// @return ruleset The current ruleset's struct.
     /// @return metadata The current ruleset's metadata.
@@ -835,7 +844,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     }
 
     /// @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.
@@ -862,21 +871,21 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             });
     }
 
-    /// @notice Check whether the project's controller can currently be set.
+    /// @notice Whether the project's current ruleset allows migrating to a different controller.
     /// @param projectId The ID of the project to check.
     /// @return A `bool` which is true if the project allows controllers to be set.
     function setControllerAllowed(uint256 projectId) external view returns (bool) {
         return _currentRulesetOf(projectId).expandMetadata().allowSetController;
     }
 
-    /// @notice Check whether the project's terminals can currently be set.
+    /// @notice Whether the project's current ruleset allows changing its terminals.
     /// @param projectId The ID of the project to check.
     /// @return A `bool` which is true if the project allows terminals to be set.
     function setTerminalsAllowed(uint256 projectId) external view returns (bool) {
         return _currentRulesetOf(projectId).expandMetadata().allowSetTerminals;
     }
 
-    /// @notice Gets the a project token's total supply, including pending reserved tokens.
+    /// @notice Returns the project's total token supply including tokens that have been reserved but not yet minted.
     /// @param projectId The ID of the project to get the total token supply of.
     /// @return The total supply of the project's token, including pending reserved tokens.
     function totalTokenSupplyWithReservedTokensOf(uint256 projectId) external view override returns (uint256) {
@@ -884,7 +893,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         return TOKENS.totalSupplyOf(projectId) + pendingReservedTokenBalanceOf[projectId];
     }
 
-    /// @notice A project's next ruleset along with its metadata.
+    /// @notice Returns the ruleset that will take effect after the current one ends, along with its decoded metadata.
     /// @dev If an upcoming ruleset isn't found, returns an empty ruleset with all properties set to 0.
     /// @param projectId The ID of the project to get the next ruleset of.
     /// @return ruleset The upcoming ruleset's struct.
@@ -951,7 +960,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
     /// @notice Queues one or more rulesets and stores information pertinent to the configuration.
     /// @param projectId The ID of the project to queue rulesets for.
-    /// @param rulesetConfigurations The rulesets being queued.
+    /// @param rulesetConfigurations The rulesets to queue.
     /// @return rulesetId The ID of the last ruleset that was successfully queued.
     function _queueRulesets(
         uint256 projectId,

package/src/JBDeadline.sol

@@ -7,10 +7,9 @@ import {JBApprovalStatus} from "./enums/JBApprovalStatus.sol";
 import {IJBRulesetApprovalHook} from "./interfaces/IJBRulesetApprovalHook.sol";
 import {JBRuleset} from "./structs/JBRuleset.sol";
 
-/// @notice `JBDeadline` is a ruleset approval hook which rejects rulesets if they are not queued at least `duration`
-/// seconds before the current ruleset ends. In other words, rulesets must be queued before the deadline to take effect.
-/// @dev Project rulesets are stored in a queue. Rulesets take effect after the previous ruleset in the queue ends, and
-/// only if they are approved by the previous ruleset's approval hook.
+/// @notice A ruleset approval hook that enforces a queuing deadline. If a new ruleset is not queued at least `DURATION`
+/// seconds before the current ruleset ends, it is rejected and the existing rules continue. This gives token holders
+/// a guaranteed notice period before any project configuration changes take effect.
 /// @dev If `DURATION` is set longer than the ruleset's cycle duration, no queued ruleset can ever satisfy the deadline
 /// and the current ruleset will effectively be locked in perpetuity. Choose a `DURATION` shorter than the shortest
 /// cycle it will govern.
@@ -60,6 +59,7 @@ contract JBDeadline is IJBRulesetApprovalHook {
             // If we've already passed the deadline, the ruleset is `Approved`.
             return (ruleset.start - ruleset.id < DURATION)
                 ? JBApprovalStatus.Failed
+                // forge-lint: disable-next-line(block-timestamp)
                 : (block.timestamp + DURATION < ruleset.start)
                     ? JBApprovalStatus.ApprovalExpected
                     : JBApprovalStatus.Approved;

package/src/JBDirectory.sol

@@ -13,9 +13,11 @@ import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
 import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBTerminal} from "./interfaces/IJBTerminal.sol";
 
-/// @notice `JBDirectory` tracks the terminals and the controller used by each project.
-/// @dev Tracks which `IJBTerminal`s each project is currently accepting funds through, and which `IJBController` is
-/// managing each project's tokens and rulesets.
+/// @notice The routing table for the protocol. Every project registers which terminals accept its payments and which
+/// controller manages its rulesets and tokens. Frontends and other contracts use the directory to discover where to
+/// send funds for a given project and token.
+/// @dev Also manages controller migration — when a project upgrades its controller, the directory orchestrates the
+/// handoff including `beforeReceiveMigrationFrom`, `migrate`, and `afterReceiveMigrationFrom` lifecycle hooks.
 contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -83,13 +85,15 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Set a project's controller. Controllers manage how terminals interact with tokens and rulesets.
+    /// @notice Assign a new controller to a project. The controller dictates how the project's terminals interact with
+    /// its tokens and rulesets. If the project already has a controller, this triggers a full migration lifecycle
+    /// (`beforeReceiveMigrationFrom` → `migrate` → state update → `afterReceiveMigrationFrom`).
     /// @dev Can only be called if:
-    /// - The ruleset's metadata has `allowSetController` enabled, and the message's sender is the project's owner or an
-    /// address with the owner's permission to `SET_CONTROLLER`.
-    /// - OR the message's sender is the project's current controller.
-    /// - OR an address which `isAllowedToSetFirstController` is setting a project's first controller.
-    /// @param projectId The ID of the project whose controller is being set.
+    /// - The ruleset's metadata has `allowSetController` enabled, and the caller is the project's owner or has
+    /// `SET_CONTROLLER` permission.
+    /// - OR the caller is the project's current controller.
+    /// - OR the caller `isAllowedToSetFirstController` and the project has no controller yet.
+    /// @param projectId The ID of the project to set the controller for.
     /// @param controller The address of the controller to set.
     function setControllerOf(uint256 projectId, IERC165 controller) external override {
         // Keep a reference to the current controller.
@@ -149,15 +153,13 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
         }
     }
 
-    /// @notice Add or remove an address/contract from a list of trusted addresses which are allowed to set a first
-    /// controller for projects.
-    /// @dev Only this contract's owner can call this function.
-    /// @dev These addresses are vetted controllers as well as contracts designed to launch new projects.
-    /// @dev A project can set its own controller without being on this list.
-    /// @dev If you would like to add an address/contract to this list, please reach out to this contract's owner.
-    /// @param addr The address to allow or not allow.
-    /// @param flag Whether the address is allowed to set first controllers for projects. Use `true` to allow and
-    /// `false` to not allow.
+    /// @notice Allow or disallow an address to set the first controller for new projects. Typically used to whitelist
+    /// deployer contracts (like `JBController`) that set a controller during `launchProjectFor`.
+    /// @dev Only this contract's owner can call this function. These addresses are vetted controllers and project
+    /// launchers. A project owner can always set their own controller — this list only governs *first* controller
+    /// assignment by third parties.
+    /// @param addr The address to allow or disallow.
+    /// @param flag Whether the address is allowed to set first controllers. `true` to allow, `false` to revoke.
     function setIsAllowedToSetFirstController(address addr, bool flag) external override onlyOwner {
         // Set the flag in the allowlist.
         isAllowedToSetFirstController[addr] = flag;
@@ -165,14 +167,14 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
         emit SetIsAllowedToSetFirstController({addr: addr, isAllowed: flag, caller: msg.sender});
     }
 
-    /// @notice Set a project's primary terminal for a token.
-    /// @dev The primary terminal for a token is where payments in that token are routed to by default.
-    /// @dev This is useful in cases where a project has multiple terminals which accept the same token.
-    /// @dev Can only be called by the project's owner, or an address with the owner's permission to
-    /// `SET_PRIMARY_TERMINAL`.
-    /// @param projectId The ID of the project whose primary terminal is being set.
+    /// @notice Designate which terminal should receive payments by default when someone pays a project in a specific
+    /// token. Useful when a project has multiple terminals that accept the same token.
+    /// @dev Can only be called by the project's owner or an address with `SET_PRIMARY_TERMINAL` permission. The
+    /// terminal must accept the token for this project. If the terminal isn't already in the project's terminal list,
+    /// it will be added automatically (requires `ADD_TERMINALS` permission).
+    /// @param projectId The ID of the project to set the primary terminal for.
     /// @param token The token to set the primary terminal for.
-    /// @param terminal The terminal being set as the primary terminal.
+    /// @param terminal The terminal to set as the primary terminal.
     function setPrimaryTerminalOf(uint256 projectId, address token, IJBTerminal terminal) external override {
         // Enforce permissions.
         _requirePermissionFrom({
@@ -203,11 +205,11 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
         emit SetPrimaryTerminal({projectId: projectId, token: token, terminal: terminal, caller: msg.sender});
     }
 
-    /// @notice Set a project's terminals.
-    /// @dev Can only be called by the project's owner, an address with the owner's permission to `SET_TERMINALS`, or
-    /// the project's controller.
-    /// @dev Unless the caller is the project's controller, the project's ruleset must allow setting terminals.
-    /// @param projectId The ID of the project whose terminals are being set.
+    /// @notice Replace a project's entire terminal list. Terminals are the contracts that accept payments and process
+    /// cash outs for a project. This overwrites the existing list.
+    /// @dev Can only be called by the project's owner, an address with `SET_TERMINALS` permission, or the project's
+    /// controller. Unless the caller is the controller, the ruleset must have `allowSetTerminals` enabled.
+    /// @param projectId The ID of the project to set terminals for.
     /// @param terminals An array of terminal addresses to set for the project.
     function setTerminalsOf(uint256 projectId, IJBTerminal[] calldata terminals) external override {
         // Cache the controller to avoid redundant storage reads.
@@ -254,10 +256,9 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice The primary terminal that a project uses for the specified token.
-    /// @dev Returns the first terminal that accepts the token if the project hasn't explicitly set a primary terminal
-    /// for it.
-    /// @dev Returns the zero address if no terminal accepts the token.
+    /// @notice Look up the terminal where payments in a given token should be sent for a project. Returns the
+    /// explicitly-set primary terminal, or falls back to the first terminal in the project's list that accepts the
+    /// token. Returns the zero address if no terminal accepts the token.
     /// @param projectId The ID of the project to get the primary terminal of.
     /// @param token The token that the terminal accepts.
     /// @return The primary terminal's address.
@@ -298,7 +299,8 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
         return IJBTerminal(address(0));
     }
 
-    /// @notice The specified project's terminals.
+    /// @notice Get all terminals registered for a project. Terminals are the contracts that hold a project's funds and
+    /// process payments and cash outs on its behalf.
     /// @param projectId The ID of the project to get the terminals of.
     /// @return An array of the project's terminal addresses.
     function terminalsOf(uint256 projectId) external view override returns (IJBTerminal[] memory) {
@@ -309,7 +311,7 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Check if a project uses a specific terminal.
+    /// @notice Check whether a specific terminal is in a project's registered terminal list.
     /// @param projectId The ID of the project to check.
     /// @param terminal The terminal to check for.
     /// @return A flag indicating whether the project uses the terminal.

package/src/JBERC20.sol

@@ -15,10 +15,11 @@ import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBToken} from "./interfaces/IJBToken.sol";
 import {IJBTokens} from "./interfaces/IJBTokens.sol";
 
-/// @notice An ERC-20 token that can be used by a project in `JBTokens` and `JBController`.
-/// @dev By default, a project uses "credits" to track balances. Once a project sets their `IJBToken` using
-/// `JBController.deployERC20For(...)` or `JBController.setTokenFor(...)`, credits can be redeemed to claim tokens.
-/// @dev `JBController.deployERC20For(...)` deploys a `JBERC20` contract and sets it as the project's token.
+/// @notice The ERC-20 token implementation used by Juicebox projects. Includes ERC20Votes (governance delegation) and
+/// ERC20Permit (gasless approvals). Deployed as a minimal clone via `JBController.deployERC20For` — once deployed,
+/// holders can claim their internal credits into this transferable token.
+/// @dev Only `JBTokens` can mint and burn. The project owner (via `SET_TOKEN_METADATA` permission) can rename the
+/// token. Supports ERC-1271 signature validation for smart-contract wallets.
 contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -126,7 +127,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @notice Validates a signature on behalf of this token contract (ERC-1271).
     /// @dev Allows the project owner or an operator with `SIGN_FOR_ERC20` permission to sign messages on behalf of
     /// this token. Useful for Etherscan contract verification and other off-chain signature flows.
-    /// @param hash The hash of the data being signed.
+    /// @param hash The hash of the data to sign.
     /// @param signature The signature to validate.
     /// @return magicValue `0x1626ba7e` if the signature is valid, `0xffffffff` otherwise.
     function isValidSignature(bytes32 hash, bytes memory signature) external view override returns (bytes4 magicValue) {
@@ -169,17 +170,17 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
         return super.decimals();
     }
 
-    /// @notice The token's name.
+    /// @notice The token's name, set during initialization.
     function name() public view virtual override returns (string memory) {
         return _name;
     }
 
-    /// @notice Required override.
+    /// @notice The current nonce for a given account, used for permit signatures.
     function nonces(address owner) public view virtual override(ERC20Permit, Nonces) returns (uint256) {
         return super.nonces(owner);
     }
 
-    /// @notice The token's symbol.
+    /// @notice The token's ticker symbol, set during initialization.
     function symbol() public view virtual override returns (string memory) {
         return _symbol;
     }
@@ -194,7 +195,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     // ----------------------- public transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Initializes the token.
+    /// @notice Initialize a new project token with the given name, symbol, and owner.
     /// @param name_ The token's name.
     /// @param symbol_ The token's symbol.
     /// @param tokens The JBTokens contract that manages this token.

package/src/JBFeelessAddresses.sol

@@ -6,7 +6,9 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 import {IJBFeelessAddresses} from "./interfaces/IJBFeelessAddresses.sol";
 
-/// @notice Stores a list of addresses that shouldn't incur fees when sending or receiving payments.
+/// @notice A registry of addresses exempt from the protocol's 2.5% fee. Feeless addresses don't incur fees on
+/// payouts they receive, surplus allowance they use, or cash outs where they are the beneficiary. Managed by the
+/// contract owner (typically the protocol multisig).
 contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
@@ -30,8 +32,9 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets whether an address is feeless.
-    /// @dev Can only be called by this contract's owner.
+    /// @notice Add or remove an address from the fee-exempt list. Feeless addresses don't pay the 2.5% protocol fee
+    /// on payouts received, surplus allowance used, or cash outs where they're the beneficiary.
+    /// @dev Can only be called by this contract's owner (typically the protocol multisig).
     /// @param addr The address to set as feeless or not feeless.
     /// @param flag Whether the address should be feeless (`true`) or not feeless (`false`).
     function setFeelessAddress(address addr, bool flag) external virtual override onlyOwner {