@bananapus/ownable-v6 0.0.23 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "license": "MIT",
   "repository": {
     "type": "git",

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,9 +10,12 @@ 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 ------------------------- //
@@ -26,14 +29,14 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     // ---------------- 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;
 
     //*********************************************************************//
@@ -98,12 +101,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 +126,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 +173,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);
@@ -199,10 +204,11 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         _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();
@@ -240,7 +246,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});

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;