@bananapus/core-v6 0.0.81 → 0.0.83

package/README.md

@@ -15,7 +15,7 @@ In-repo docs (entry points for this repo):
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — what to focus on for a security audit and how to start.
 - [SKILLS.md](./SKILLS.md) — implementation nuances, gotchas, and reading order for working on this codebase.
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity conventions and repo layout used across the V6 ecosystem.
-- [CHANGELOG.md](./CHANGELOG.md) — v5 → v6 ABI and behavior deltas.
+- [CHANGELOG.md](./CHANGELOG.md) - V5 to V6 ABI and behavior deltas.
 - [references/entrypoints.md](./references/entrypoints.md) — callable entrypoints by contract.
 - [references/types-errors-events.md](./references/types-errors-events.md) — packed metadata, errors, events, and hook return shapes.
 
@@ -36,7 +36,7 @@ Use this repo when you need the protocol's canonical accounting and execution lo
 
 If you only read one V6 repo before reading the rest, read this one.
 
-## Mental Model
+## Mental model
 
 It helps to think about core in four layers:
 
@@ -54,7 +54,7 @@ The shortest reading path is:
 3. `JBTerminalStore` for the accounting model
 4. `JBDirectory` and `JBPermissions` for routing and authority
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBController.sol`
 2. `src/JBMultiTerminal.sol`
@@ -63,7 +63,7 @@ The shortest reading path is:
 5. `src/JBRulesets.sol`
 6. `src/JBPermissions.sol`
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -75,14 +75,14 @@ The shortest reading path is:
 | `JBPermissions` | Packed operator-permission registry. |
 | `JBPrices` | Price-feed routing used by terminals and integrations. |
 
-## Integration Traps
+## Integration traps
 
 - `JBMultiTerminal` is multi-token and multi-terminal. Do not assume one token or one balance.
 - Data hooks and cash-out hooks can change economics and side effects. They are part of the protocol surface.
 - Permission checks are not always against the project owner. Some flows are scoped to the token holder instead.
 - Preview and execution are intentionally close, but callers should still treat them as separate surfaces when hooks or routing can change behavior.
 
-## Where State Lives
+## Where state lives
 
 - project identity and ownership: `JBProjects`
 - controller and terminal routing: `JBDirectory`
@@ -92,7 +92,7 @@ The shortest reading path is:
 
 When a flow is unclear, read the contract that owns the state before the contract that forwards into it.
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/TestPayBurnRedeemFlow.sol`
 2. `test/TestTerminalPreviewParity.sol`
@@ -122,11 +122,11 @@ Useful scripts:
 - `npm run deploy:mainnets:periphery`
 - `npm run deploy:testnets:periphery`
 
-## Deployment Notes
+## Deployment notes
 
 This repo contains the main core deployments and periphery deployment helpers. Most other V6 packages assume these contracts exist first and treat them as the stable base layer.
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -139,7 +139,7 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 See [RISKS.md](./RISKS.md) for the full risk register. In short:
 
@@ -150,7 +150,7 @@ See [RISKS.md](./RISKS.md) for the full risk register. In short:
 
 The easiest way to misread V6 is to treat core like a simple crowdfunding terminal. It is closer to a configurable accounting and settlement layer.
 
-## For AI Agents
+## For AI agents
 
 - Start with `JBController`, `JBMultiTerminal`, and `JBTerminalStore`.
 - Keep controller configuration, terminal execution, and store accounting separate in your mental model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.81",
+  "version": "0.0.83",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,10 +35,10 @@
     "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.28",
+    "@bananapus/permission-ids-v6": "^0.0.30",
     "@chainlink/contracts": "1.5.0",
     "@openzeppelin/contracts": "5.6.1",
-    "@prb/math": "4.1.1",
+    "@prb/math": "4.1.2",
     "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219"
   },
   "devDependencies": {

package/references/entrypoints.md

@@ -28,7 +28,7 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `JBDeadline` | Approval hook: rejects rulesets queued within `DURATION` seconds of start. Ships as `JBDeadline3Hours`, `JBDeadline1Day`, `JBDeadline3Days`, `JBDeadline7Days`. |
 | `JBMatchingPriceFeed` | Always returns 1:1. For equivalent currencies (e.g. ETH/NATIVE_TOKEN). |
 
-## Key Functions
+## Key functions
 
 ### JBController
 

package/references/types-errors-events.md

@@ -2,7 +2,7 @@
 
 Use this file when you need deeper protocol reference material after the repo-local `SKILLS.md` has already routed you to `nana-core-v6`.
 
-## Key Types
+## Key types
 
 | Struct/Enum | Key Fields | Used In |
 |-------------|------------|---------|
@@ -23,7 +23,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | `JBRulesetWeightCache` | `weight (uint112)`, `weightCutMultiple (uint168)` | Weight caching for long-running rulesets in `JBRulesets` |
 | `JBApprovalStatus` (enum) | `Empty`, `Upcoming`, `Active`, `ApprovalExpected`, `Approved`, `Failed` | Approval hook status for queued rulesets |
 
-### Hook Structs
+### Hook structs
 
 | Struct | Key Fields | Used In |
 |--------|------------|---------|
@@ -53,13 +53,13 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | `1` | ETH |
 | `2` | USD |
 
-### Split Group IDs (`JBSplitGroupIds`)
+### Split group IDs (`JBSplitGroupIds`)
 
 | ID | Group |
 |----|-------|
 | `1` | `RESERVED_TOKENS` -- reserved token distribution |
 
-### Special Values
+### Special values
 
 | Value | Context | Meaning |
 |-------|---------|---------|
@@ -143,7 +143,7 @@ Quick-reference for the most common `JBPermissionIds` values (from `@bananapus/p
 
 IDs 22-33 are used by extension contracts (721 hook, buyback hook, router terminal, suckers).
 
-## Common Errors
+## Common errors
 
 Errors an agent is most likely to encounter. All are custom errors (revert with selector).
 
@@ -187,7 +187,7 @@ Errors an agent is most likely to encounter. All are custom errors (revert with
 | `JBRulesets_InvalidWeightCutPercent` | `JBRulesets` | `weightCutPercent` exceeds `MAX_WEIGHT_CUT_PERCENT`. |
 | `JBFundAccessLimits_InvalidPayoutLimitCurrencyOrdering` | `JBFundAccessLimits` | Payout limit currencies not in strictly increasing order. |
 
-## Key Events
+## Key events
 
 The most important events for indexing and off-chain monitoring. Indexed params marked with `*`.
 
@@ -220,7 +220,7 @@ The most important events for indexing and off-chain monitoring. Indexed params
 | `SetSplit` | `IJBSplits` | (projectId, rulesetId, groupId, split, caller) |
 | `AddPriceFeed` | `IJBPrices` | (projectId, pricingCurrency, unitCurrency, feed, caller) |
 
-## Hook Interface Return Types
+## Hook interface return types
 
 ### `IJBRulesetDataHook.beforePayRecordedWith()`
 
@@ -260,7 +260,7 @@ function hasMintPermissionFor(uint256 projectId, JBRuleset memory ruleset, addre
 
 Returns whether `addr` is allowed to mint tokens for the project. Called by `JBController.mintTokensOf` when the caller is not the owner and `allowOwnerMinting` is false -- the data hook can grant mint permission to specific addresses (e.g. suckers for omnichain bridging).
 
-## Example Integration
+## Example integration
 
 ```solidity
 // SPDX-License-Identifier: MIT

package/src/JBChainlinkV3PriceFeed.sol

@@ -17,8 +17,13 @@ contract JBChainlinkV3PriceFeed is IJBPriceFeed {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the feed round is not finished or was not answered in the current round.
     error JBChainlinkV3PriceFeed_IncompleteRound(uint80 roundId, uint80 answeredInRound, uint256 updatedAt);
+
+    /// @notice Thrown when the feed reports a non-positive price.
     error JBChainlinkV3PriceFeed_NegativePrice(int256 price);
+
+    /// @notice Thrown when the feed's last update is older than the staleness threshold.
     error JBChainlinkV3PriceFeed_StalePrice(uint256 timestamp, uint256 threshold, uint256 updatedAt);
 
     //*********************************************************************//

package/src/JBChainlinkV3SequencerPriceFeed.sol

@@ -14,7 +14,10 @@ contract JBChainlinkV3SequencerPriceFeed is JBChainlinkV3PriceFeed {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the sequencer uptime round is invalid (e.g. the uptime contract is not yet initialized).
     error JBChainlinkV3SequencerPriceFeed_InvalidRound(uint256 startedAt);
+
+    /// @notice Thrown when the L2 sequencer is down or has restarted too recently for the grace period to elapse.
     error JBChainlinkV3SequencerPriceFeed_SequencerDownOrRestarting(
         uint256 timestamp, uint256 gracePeriodTime, uint256 startedAt
     );

package/src/JBController.sol

@@ -58,21 +58,52 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the project's current ruleset does not allow adding price feeds.
     error JBController_AddingPriceFeedNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when transferring credits while the current ruleset pauses credit transfers.
     error JBController_CreditTransfersPaused(uint256 projectId, uint256 rulesetId);
+
+    /// @notice Thrown when the cash out tax rate exceeds the allowed maximum.
     error JBController_InvalidCashOutTaxRate(uint256 rate, uint256 limit);
+
+    /// @notice Thrown when the native value sent does not equal the required creation fee.
     error JBController_InvalidCreationFee(uint256 value, uint256 requiredFee);
+
+    /// @notice Thrown when the reserved percent exceeds the allowed maximum.
     error JBController_InvalidReservedPercent(uint256 percent, uint256 limit);
+
+    /// @notice Thrown when the caller is not allowed to mint and is not a terminal or data hook for the project.
     error JBController_MintNotAllowedAndNotTerminalOrHook(address caller);
+
+    /// @notice Thrown when there are no reserved tokens to send to splits.
     error JBController_NoReservedTokens(uint256 projectId);
+
+    /// @notice Thrown when the caller is not the directory.
     error JBController_OnlyDirectory(address sender, IJBDirectory directory);
+
+    /// @notice Thrown when migrating a project that still has pending reserved tokens.
     error JBController_PendingReservedTokens(uint256 pendingReservedTokenBalance);
+
+    /// @notice Thrown when a reserved token split routes back into the same project via the terminal-payment path.
     error JBController_ReservedTokenSplitProjectSameAsOwner(uint256 projectId);
+
+    /// @notice Thrown when launching rulesets for a project that has already launched.
     error JBController_RulesetsAlreadyLaunched(uint256 projectId);
+
+    /// @notice Thrown when the ruleset configurations array is empty.
     error JBController_RulesetsArrayEmpty(uint256 projectId, uint256 rulesetConfigurationCount);
+
+    /// @notice Thrown when the project's current ruleset does not allow setting a custom token.
     error JBController_RulesetSetTokenNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when the terminal did not pull the full token allowance during a payout.
     error JBController_TerminalTokensNotTransferred(address terminal, address token, uint256 allowance);
+
+    /// @notice Thrown when attempting to burn zero tokens.
     error JBController_ZeroTokensToBurn(uint256 projectId, address holder);
+
+    /// @notice Thrown when attempting to mint zero tokens.
     error JBController_ZeroTokensToMint(uint256 projectId, address beneficiary);
 
     //*********************************************************************//
@@ -281,8 +312,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     }
 
     /// @notice Converts a holder's internal project token credits into the project's ERC-20 representation,
-    /// transferring them to the beneficiary's wallet. Credits and the ERC-20 are equivalent project tokens — this
-    /// just
+    /// transferring them to the beneficiary's wallet. Credits and the ERC-20 are equivalent project tokens; 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 whose project token credits are being redeemed.
@@ -342,8 +372,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         return TOKENS.deployERC20For({projectId: projectId, name: name, symbol: symbol, salt: saltHash});
     }
 
-    /// @notice When a project receives reserved tokens, if it has a terminal for the token, this is used to pay the
-    /// terminal.
+    /// @notice Pays a project's terminal with reserved tokens when the project has a terminal for that token.
     /// @dev Can only be called by this controller.
     /// @param terminal The terminal to pay.
     /// @param projectId The ID of the project to pay.
@@ -386,9 +415,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @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.
+    /// @notice Creates a Juicebox project in one transaction: mints the NFT, queues rulesets, and configures terminals.
     /// @dev Anyone can call this on behalf of any owner. This is a launch convenience, not owner authorization proof:
     /// frontends and operators must use the transaction sender, an explicit owner signature, or their own deployment
     /// flow to decide whether the owner intentionally launched a configuration. Each sub-operation (mint, queue,
@@ -707,15 +734,14 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         // If there's no current ruleset, get a reference to the upcoming one.
         if (ruleset.id == 0) ruleset = _upcomingRulesetOf(projectId);
 
-        // If owner minting is disabled for the ruleset, the owner cannot change the token.
+        // If the ruleset doesn't allow setting a custom token, the owner cannot change the token.
         if (!ruleset.allowSetCustomToken()) revert JBController_RulesetSetTokenNotAllowed(projectId);
 
         TOKENS.setTokenFor({projectId: projectId, token: token});
     }
 
     /// @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`.
+    /// @dev Can only be called by the project's owner or an address with the owner's `SET_TOKEN_METADATA` permission.
     /// @param projectId The ID of the project to update the token for.
     /// @param name The new name.
     /// @param symbol The new symbol.
@@ -730,8 +756,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
     /// @notice Set a project's metadata URI.
     /// @dev This is typically an IPFS hash, optionally with an `ipfs://` prefix.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to
-    /// `SET_PROJECT_URI`.
+    /// @dev Can only be called by the project's owner or an address with the owner's `SET_PROJECT_URI` permission.
     /// @param projectId The ID of the project to set the metadata URI of.
     /// @param uri The metadata URI to set.
     function setUriOf(uint256 projectId, string calldata uri) external override {
@@ -783,8 +808,8 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
     /// @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.
+    /// @param startingId The ID of the ruleset to begin with. This will be the latest ruleset in the result.
+    /// If 0 is passed, the project's latest ruleset will be used.
     /// @param size The maximum number of rulesets to return.
     /// @return rulesets The array of rulesets with their metadata.
     function allRulesetsOf(
@@ -1215,8 +1240,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     }
 
     /// @notice Sends pending reserved tokens to the project's 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.
+    /// @dev If the project has no reserved token splits, or if they don't add up to 100%, leftovers go to the owner.
     /// @param projectId The ID of the project to send reserved tokens for.
     /// @return tokenCount The amount of reserved tokens minted and sent.
     function _sendReservedTokensToSplitsOf(uint256 projectId) internal returns (uint256 tokenCount) {
@@ -1320,7 +1344,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         return RULESETS.currentOf(projectId);
     }
 
-    /// @notice Indicates whether the provided address has mint permission for the project byway of the data hook.
+    /// @notice Indicates whether the provided address has mint permission for the project by way of the data hook.
     /// @param projectId The ID of the project to check.
     /// @param ruleset The ruleset to check.
     /// @param addr The address to check.

package/src/JBDirectory.sol

@@ -23,10 +23,19 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the same terminal appears more than once in the provided terminals list.
     error JBDirectory_DuplicateTerminals(IJBTerminal terminal);
+
+    /// @notice Thrown when the project ID is greater than the number of existing projects.
     error JBDirectory_InvalidProjectIdInDirectory(uint256 projectId, uint256 limit);
+
+    /// @notice Thrown when the project's current controller does not allow setting a new controller.
     error JBDirectory_SetControllerNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when the project's current controller does not allow setting terminals.
     error JBDirectory_SetTerminalsNotAllowed(uint256 projectId);
+
+    /// @notice Thrown when the terminal being set as primary does not accept the given token.
     error JBDirectory_TokenNotAccepted(uint256 projectId, address token, IJBTerminal terminal);
 
     //*********************************************************************//
@@ -40,8 +49,7 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice The specified project's controller, which dictates how its terminals interact with its tokens and
-    /// rulesets.
+    /// @notice The specified project's controller, which dictates how terminals interact with tokens and rulesets.
     /// @custom:param projectId The ID of the project to get the controller of.
     mapping(uint256 projectId => IERC165) public override controllerOf;
 
@@ -89,8 +97,7 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     /// 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 caller is the project's owner or has
-    /// `SET_CONTROLLER` permission.
+    /// - The ruleset metadata enables `allowSetController`, and the caller owns the project or has `SET_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.

package/src/JBERC20.sol

@@ -25,7 +25,10 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when initializing a token that already has a name set, or when the provided name is empty.
     error JBERC20_AlreadyInitialized(uint256 currentNameLength, uint256 newNameLength);
+
+    /// @notice Thrown when the caller is not the JBTokens contract that owns this token.
     error JBERC20_Unauthorized(address caller, address tokens);
 
     //*********************************************************************//

package/src/JBFeelessAddresses.sol

@@ -16,6 +16,7 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the provided feeless hook does not support the `IJBFeelessHook` interface.
     error JBFeelessAddresses_InvalidFeelessHook(IJBFeelessHook hook);
 
     //*********************************************************************//
@@ -33,6 +34,8 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
 
     /// @notice Raw feeless status per project per address.
     /// @dev `projectId = 0` stores the global (all-project) feeless status.
+    /// @custom:param projectId The ID of the project. A `projectId` of 0 is the global (all-project) key.
+    /// @custom:param addr The address whose feeless status is being stored.
     mapping(uint256 projectId => mapping(address addr => bool)) internal _isFeelessFor;
 
     //*********************************************************************//

package/src/JBFundAccessLimits.sol

@@ -18,12 +18,17 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when two fund access limit groups share the same terminal and token.
     error JBFundAccessLimits_DuplicateFundAccessLimitGroup(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, address terminal, address token
     );
+
+    /// @notice Thrown when payout limits within a group are not ordered by ascending currency.
     error JBFundAccessLimits_InvalidPayoutLimitCurrencyOrdering(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, uint256 limitIndex
     );
+
+    /// @notice Thrown when surplus allowances within a group are not ordered by ascending currency.
     error JBFundAccessLimits_InvalidSurplusAllowanceCurrencyOrdering(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, uint256 allowanceIndex
     );