@bananapus/ownable-v6 0.0.23 → 0.0.25

package/README.md

@@ -62,7 +62,7 @@ This package is a small ownership adapter:
 
 1. `test/Ownable.t.sol`
 2. `test/OwnableAttacks.t.sol`
-3. `test/CodexUnmintedProjectHijack.t.sol`
+3. `test/RegressionUnmintedProjectHijack.t.sol`
 4. `test/regression/BurnLockProtection.t.sol`
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,8 +19,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bananapus/core-v6": "0.0.38",
-    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/core-v6": "^0.0.54",
+    "@bananapus/permission-ids-v6": "^0.0.25",
     "@openzeppelin/contracts": "5.6.1"
   },
   "scripts": {

package/references/runtime.md

@@ -16,4 +16,4 @@
 - [`test/Ownable.t.sol`](../test/Ownable.t.sol) for baseline behavior.
 - [`test/OwnableEdgeCases.t.sol`](../test/OwnableEdgeCases.t.sol) and [`test/OwnableAttacks.t.sol`](../test/OwnableAttacks.t.sol) for edge and adversarial cases.
 - [`test/OwnableInvariantTests.sol`](../test/OwnableInvariantTests.sol) for broader invariants.
-- [`test/regression/BurnLockProtection.t.sol`](../test/regression/BurnLockProtection.t.sol), [`test/regression/ZeroAddressValidation.t.sol`](../test/regression/ZeroAddressValidation.t.sol), and [`test/CodexUnmintedProjectHijack.t.sol`](../test/CodexUnmintedProjectHijack.t.sol) for the regressions most likely to matter in review.
+- [`test/regression/BurnLockProtection.t.sol`](../test/regression/BurnLockProtection.t.sol), [`test/regression/ZeroAddressValidation.t.sol`](../test/regression/ZeroAddressValidation.t.sol), and [`test/RegressionUnmintedProjectHijack.t.sol`](../test/RegressionUnmintedProjectHijack.t.sol) for the regressions most likely to matter in review.

package/src/JBOwnable.sol

@@ -7,16 +7,11 @@ import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.s
 
 import {JBOwnableOverrides} from "./JBOwnableOverrides.sol";
 
-/// @notice A function restricted by `JBOwnable` can only be called by a Juicebox project's owner, a specified owner
-/// address (if set), or addresses with permission from the owner.
-/// @dev A function with the `onlyOwner` modifier from `JBOwnable` can only be called by addresses with owner access
-/// based on a `JBOwner` struct:
-/// 1. If `JBOwner.projectId` isn't zero, the address holding the `JBProjects` NFT with the `JBOwner.projectId` ID is
-/// the owner.
-/// 2. If `JBOwner.projectId` is set to `0`, the `JBOwner.owner` address is the owner.
-/// 3. The owner can give other addresses access with `JBPermissions.setPermissionsFor(...)`, using the
-/// `JBOwner.permissionId` permission.
-/// @dev To use `onlyOwner`, inherit this contract and apply the modifier to a function.
+/// @notice Juicebox-aware ownership for any contract. Inherit this and apply the `onlyOwner` modifier to restrict
+/// functions to the project owner, a fixed address, or anyone the owner has granted permission to via `JBPermissions`.
+/// @dev Ownership resolves dynamically: if `JBOwner.projectId` is set, the holder of that project's ERC-721 NFT is
+/// the owner. If `projectId` is 0, the stored `JBOwner.owner` address is used instead. The owner can delegate access
+/// to other addresses by setting a `permissionId` and granting that permission through `JBPermissions`.
 contract JBOwnable is JBOwnableOverrides {
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //

package/src/JBOwnableOverrides.sol

@@ -10,30 +10,43 @@ import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IJBOwnable} from "./interfaces/IJBOwnable.sol";
 import {JBOwner} from "./structs/JBOwner.sol";
 
-/// @notice An abstract base for `JBOwnable`, which restricts functions so they can only be called by a Juicebox
-/// project's owner or a specific owner address. The owner can give access permission to other addresses with
-/// `JBPermissions`.
+/// @notice Abstract base implementing Juicebox-aware ownership resolution, transfer, and permission delegation.
+/// Ownership is either address-based (a fixed EOA/contract) or project-based (whoever holds the project's ERC-721
+/// NFT). The owner can delegate access to other addresses by configuring a `permissionId` in `JBPermissions`.
+/// @dev Stale permission detection: when ownership changes (e.g. project NFT transferred), the `permissionId` is
+/// effectively ignored until the new owner explicitly re-sets it — preventing the previous owner's delegates from
+/// retaining access.
 abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error JBOwnableOverrides_InvalidNewOwner();
-    error JBOwnableOverrides_ProjectDoesNotExist();
-    error JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner();
+    /// @notice Thrown when an ownership transfer or constructor input does not identify exactly one valid owner.
+    /// @param newOwner The address owner being set.
+    /// @param projectId The project owner ID being set.
+    error JBOwnableOverrides_InvalidNewOwner(address newOwner, uint256 projectId);
+
+    /// @notice Thrown when project-based ownership points to a project that has not been minted.
+    /// @param projectId The project ID that was requested.
+    /// @param projectCount The current number of minted projects.
+    error JBOwnableOverrides_ProjectDoesNotExist(uint256 projectId, uint256 projectCount);
+
+    /// @notice Thrown when project-based ownership is requested without a `JBProjects` contract.
+    /// @param projectId The project owner ID that requires a non-zero `JBProjects` contract.
+    error JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner(uint256 projectId);
 
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //
     //*********************************************************************//
 
-    /// @notice Mints ERC-721s that represent project ownership and transfers.
+    /// @notice The `JBProjects` ERC-721 contract used to resolve project-based ownership.
     IJBProjects public immutable override PROJECTS;
 
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice This contract's owner information.
+    /// @notice The current ownership state — who owns this contract and how permission delegation is configured.
     JBOwner public override jbOwner;
 
     //*********************************************************************//
@@ -76,7 +89,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         // Deploying with projects=address(0) and a non-zero projectId would permanently disable
         // ownership resolution, as all ownerOf() calls would revert on the zero address.
         if (initialProjectIdOwner != 0 && address(projects) == address(0)) {
-            revert JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner();
+            revert JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner({projectId: initialProjectIdOwner});
         }
 
         // We force the inheriting contract to set an owner, as there is a low chance someone will use `JBOwnable` to
@@ -84,7 +97,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         // It's more likely both were accidentally set to `0`. If you really want an unowned contract, set the owner to
         // an address and call `renounceOwnership()` in the constructor body.
         if (initialProjectIdOwner == 0 && initialOwner == address(0)) {
-            revert JBOwnableOverrides_InvalidNewOwner();
+            revert JBOwnableOverrides_InvalidNewOwner({newOwner: initialOwner, projectId: initialProjectIdOwner});
         }
 
         // No explicit project existence check here — if `initialProjectIdOwner` refers to an unminted project,
@@ -98,12 +111,11 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Returns the owner's address based on this contract's `JBOwner`.
-    /// @dev If `projectId` is non-zero, resolves via `PROJECTS.ownerOf()`. If that call reverts (e.g., because the
-    /// project NFT was burned or invalidated), returns `address(0)` — effectively treating the contract as renounced.
-    /// @dev **Assumption:** `JBProjects` V6 has no burn function, so this scenario cannot occur under normal
-    /// conditions. The try-catch is a defensive measure against hypothetical future changes to `JBProjects` or
-    /// unexpected ERC-721 behavior.
+    /// @notice Returns the current owner's address. If ownership is project-based, this dynamically resolves to
+    /// whoever holds the project's ERC-721 NFT right now.
+    /// @dev If `projectId` is non-zero, resolves via `PROJECTS.ownerOf()`. If that call reverts (e.g., burned NFT),
+    /// returns `address(0)` — effectively treating the contract as renounced. `JBProjects` V6 has no burn function,
+    /// so this is a defensive measure only.
     function owner() public view virtual returns (address) {
         JBOwner memory ownerInfo = jbOwner;
 
@@ -124,9 +136,11 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//
 
-    /// @notice Reverts if the sender is not the owner.
+    /// @notice Reverts if the caller is not the owner (or an authorized delegate when `permissionId` is set).
     /// @dev If `projectId` is non-zero and `PROJECTS.ownerOf()` reverts (e.g., burned NFT), the resolved owner is
     /// `address(0)`, causing all `_checkOwner` calls to revert — equivalent to a renounced contract.
+    /// @dev Stale permission detection: if the resolved owner differs from `_permissionOwner` (set when
+    /// `setPermissionId` was last called), delegation is disabled until the new owner re-configures it.
     function _checkOwner() internal view virtual {
         JBOwner memory ownerInfo = jbOwner;
 
@@ -169,17 +183,18 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     // ---------------------- public transactions ------------------------ //
     //*********************************************************************//
 
-    /// @notice Gives up ownership of this contract, making it impossible to call `onlyOwner` and `_checkOwner`
-    /// functions.
-    /// @dev This can only be called by the current owner.
+    /// @notice Permanently gives up ownership. After this, no address can call `onlyOwner` functions.
+    /// @dev Can only be called by the current owner. This is irreversible.
     function renounceOwnership() public virtual override {
         _checkOwner();
         _transferOwnership({newOwner: address(0), projectId: 0});
     }
 
-    /// @notice Sets the permission ID the owner can use to give other addresses owner access.
-    /// @dev This can only be called by the current owner.
-    /// @param permissionId The permission ID to use for `onlyOwner`.
+    /// @notice Configures which `JBPermissions` permission ID grants delegate access to `onlyOwner` functions.
+    /// Set to 0 to disable delegation entirely (only the direct owner can call).
+    /// @dev Can only be called by the current owner. Records the current owner so stale permissions are detected
+    /// if ownership later changes.
+    /// @param permissionId The permission ID to use for `onlyOwner` delegation.
     function setPermissionId(uint8 permissionId) public virtual override {
         _checkOwner();
         _setPermissionId(permissionId);
@@ -193,26 +208,27 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     function transferOwnership(address newOwner) public virtual override {
         _checkOwner();
         if (newOwner == address(0)) {
-            revert JBOwnableOverrides_InvalidNewOwner();
+            revert JBOwnableOverrides_InvalidNewOwner({newOwner: newOwner, projectId: 0});
         }
 
         _transferOwnership({newOwner: newOwner, projectId: 0});
     }
 
-    /// @notice Transfer ownership of this contract to a new Juicebox project.
-    /// @dev The `permissionId` is reset to 0 on transfer to prevent permission clashes for the new project owner.
-    /// The new owner must explicitly call `setPermissionId()` to configure owner-level permission delegation.
-    /// @dev The `projectId` must fit within a `uint88`.
+    /// @notice Transfers ownership to a Juicebox project — whoever holds that project's ERC-721 NFT becomes the
+    /// owner.
+    /// @dev The `permissionId` is reset to 0 on transfer to prevent the previous owner's delegates from retaining
+    /// access. The new project owner must call `setPermissionId()` to re-enable delegation.
+    /// @dev The `projectId` must fit within a `uint88` and the project must already exist.
     /// @param projectId The ID of the project to transfer ownership to.
     function transferOwnershipToProject(uint256 projectId) public virtual override {
         _checkOwner();
         if (projectId == 0 || projectId > type(uint88).max) {
-            revert JBOwnableOverrides_InvalidNewOwner();
+            revert JBOwnableOverrides_InvalidNewOwner({newOwner: address(0), projectId: projectId});
         }
 
         // Make sure the project exists to prevent permanent loss of contract control.
         if (projectId > PROJECTS.count()) {
-            revert JBOwnableOverrides_ProjectDoesNotExist();
+            revert JBOwnableOverrides_ProjectDoesNotExist({projectId: projectId, projectCount: PROJECTS.count()});
         }
 
         // forge-lint: disable-next-line(unsafe-typecast)
@@ -240,7 +256,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         emit PermissionIdChanged({newId: permissionId, caller: _msgSender()});
     }
 
-    /// @notice Helper to allow for drop-in replacement of OpenZeppelin `Ownable`.
+    /// @notice Drop-in replacement for OpenZeppelin's `Ownable._transferOwnership(address)`.
     /// @param newOwner The address that should receive ownership of this contract.
     function _transferOwnership(address newOwner) internal virtual {
         _transferOwnership({newOwner: newOwner, projectId: 0});
@@ -255,7 +271,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     function _transferOwnership(address newOwner, uint88 projectId) internal virtual {
         // Can't set both a new owner and a new project ID.
         if (projectId != 0 && newOwner != address(0)) {
-            revert JBOwnableOverrides_InvalidNewOwner();
+            revert JBOwnableOverrides_InvalidNewOwner({newOwner: newOwner, projectId: projectId});
         }
         // Load the owner information from storage.
         JBOwner memory ownerInfo = jbOwner;

package/src/interfaces/IJBOwnable.sol

@@ -3,7 +3,9 @@ pragma solidity ^0.8.0;
 
 import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
 
-/// @notice Provides Juicebox-aware ownership with support for project-based and address-based owners.
+/// @notice Interface for Juicebox-aware ownership. Supports two modes: address-based (a fixed EOA/contract owns the
+/// contract) or project-based (whoever holds a specific Juicebox project's ERC-721 NFT is the owner). The owner can
+/// delegate access to other addresses via `JBPermissions`.
 interface IJBOwnable {
     /// @notice Emitted when ownership is transferred to a new owner.
     /// @param previousOwner The address of the previous owner.
@@ -16,14 +18,14 @@ interface IJBOwnable {
     /// @param caller The address that changed the permission ID.
     event PermissionIdChanged(uint8 newId, address caller);
 
-    /// @notice The contract that mints ERC-721s representing project ownership.
+    /// @notice The `JBProjects` ERC-721 contract used to resolve project-based ownership.
     /// @return projects The `IJBProjects` contract.
     function PROJECTS() external view returns (IJBProjects projects);
 
-    /// @notice This contract's owner information.
+    /// @notice The current ownership state — who owns this contract and how permission delegation is configured.
     /// @return owner The owner address (used when `projectId` is 0).
-    /// @return projectId The ID of the Juicebox project whose owner is this contract's owner (0 if not project-owned).
-    /// @return permissionId The permission ID the owner can use to grant other addresses owner access.
+    /// @return projectId The Juicebox project whose NFT holder is the owner (0 if address-based ownership).
+    /// @return permissionId The permission ID that delegates can use to act as owner via `JBPermissions`.
     function jbOwner() external view returns (address owner, uint88 projectId, uint8 permissionId);
 
     /// @notice Returns the current owner's address.

package/src/structs/JBOwner.sol

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @notice Owner information for a given instance of `JBOwnableOverrides`.
-/// @custom:member owner If `projectId` is 0, this address has owner access.
-/// @custom:member projectId The owner of the `JBProjects` ERC-721 with this ID has owner access. If this is 0, the
-/// `owner` address has owner access.
-/// @custom:member permissionId The permission ID which corresponds to owner access. See `JBPermissions` in `nana-core`
-/// and `nana-permission-ids`.
+/// @notice Describes who owns a `JBOwnable` contract and how they can delegate access.
+/// @custom:member owner The owner address — only used when `projectId` is 0 (address-based ownership mode).
+/// @custom:member projectId If non-zero, the holder of this Juicebox project's ERC-721 NFT is the owner. When set,
+/// the `owner` field is ignored and ownership resolves dynamically via `JBProjects.ownerOf(projectId)`.
+/// @custom:member permissionId The permission ID that delegates can hold (via `JBPermissions`) to act as owner. Set
+/// to 0 to disable delegation entirely — only the direct owner can call `onlyOwner` functions.
 struct JBOwner {
     address owner;
     uint88 projectId;