@bananapus/core-v6 0.0.37 → 0.0.39

package/foundry.lock

@@ -1,11 +1,5 @@
 {
   "lib/forge-std": {
     "rev": "726a6ee5fc8427a0013d6f624e486c9130c0e336"
-  },
-  "lib/sphinx": {
-    "branch": {
-      "name": "v0.23.0",
-      "rev": "5fb24a825f46bd6ae0b5359fe0da1d2346126b09"
-    }
   }
-}
+}

package/foundry.toml

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

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-core-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.lock",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/helpers/",
+    "sphinx.lock",
+    "src/",
+    "test/helpers/",
+    "test/mock/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -26,13 +38,13 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@chainlink/contracts": "^1.5.0",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@prb/math": "^4.1.1",
-    "@uniswap/permit2": "github:Uniswap/permit2"
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@chainlink/contracts": "1.5.0",
+    "@openzeppelin/contracts": "5.6.1",
+    "@prb/math": "4.1.1",
+    "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.3"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

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 being used 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,8 +171,9 @@ 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.
@@ -234,9 +240,9 @@ 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.
+    /// @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 whose tokens are being burned.
     /// @param projectId The ID of the project whose tokens are being burned.
     /// @param tokenCount The number of tokens to burn.
@@ -269,8 +275,9 @@ 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 tokenCount The number of tokens to claim.
@@ -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.
@@ -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,17 +423,19 @@ 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.
     /// @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
@@ -455,11 +466,25 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             alsoGrantAccessIf: sender == OMNICHAIN_RULESET_OPERATOR
         });
 
+        if (bytes(projectUri).length > 0) {
+            _requirePermissionAllowingOverrideFrom({
+                account: PROJECTS.ownerOf(projectId),
+                projectId: projectId,
+                permissionId: JBPermissionIds.SET_PROJECT_URI,
+                alsoGrantAccessIf: sender == OMNICHAIN_RULESET_OPERATOR
+            });
+        }
+
         // If the project has already had rulesets, use `queueRulesetsOf(...)` instead.
         if (RULESETS.latestRulesetIdOf(projectId) > 0) {
             revert JBController_RulesetsAlreadyLaunched(projectId);
         }
 
+        // If provided, set the project's metadata URI.
+        if (bytes(projectUri).length > 0) {
+            uriOf[projectId] = projectUri;
+        }
+
         // Set this contract as the project's controller in the directory.
         DIRECTORY.setControllerOf({projectId: projectId, controller: IERC165(this)});
 
@@ -470,7 +495,9 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         // slither-disable-next-line reentrancy-events
         rulesetId = _queueRulesets({projectId: projectId, rulesetConfigurations: rulesetConfigurations});
 
-        emit LaunchRulesets({rulesetId: rulesetId, projectId: projectId, memo: memo, caller: _msgSender()});
+        emit LaunchRulesets({
+            rulesetId: rulesetId, projectId: projectId, projectUri: projectUri, memo: memo, caller: _msgSender()
+        });
     }
 
     /// @notice Migrate a project from this controller to another one.
@@ -490,12 +517,10 @@ 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.
+    /// @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 whose tokens are being minted.
     /// @param tokenCount The number of tokens to mint, including any reserved tokens.
     /// @param beneficiary The address which will receive the (non-reserved) tokens.
@@ -576,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.
@@ -610,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
@@ -698,8 +724,10 @@ 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 recipient The address to transfer credits to.
@@ -729,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.
@@ -768,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.
@@ -844,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) {
@@ -866,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.

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,12 +85,14 @@ 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.
+    /// - 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 whose controller is being set.
     /// @param controller The address of the controller to set.
     function setControllerOf(uint256 projectId, IERC165 controller) external override {
@@ -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,11 +167,11 @@ 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`.
+    /// @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 whose primary terminal is being set.
     /// @param token The token to set the primary terminal for.
     /// @param terminal The terminal being set as the primary terminal.
@@ -203,10 +205,10 @@ 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.
+    /// @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 whose terminals are being set.
     /// @param terminals An array of terminal addresses to set for the project.
     function setTerminalsOf(uint256 projectId, IJBTerminal[] calldata terminals) external override {
@@ -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 ------------------------- //

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 {