@bananapus/ownable-v6 0.0.34 → 0.0.37

package/README.md

@@ -13,6 +13,8 @@
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — code style conventions
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — guidance for auditors
 - [CHANGELOG.md](./CHANGELOG.md) — release notes
+- [references/runtime.md](./references/runtime.md) — owner-resolution, transfer, and delegation behavior by surface
+- [references/operations.md](./references/operations.md) — change checklist and common failure modes
 
 ## Overview
 
@@ -29,7 +31,7 @@ Use this repo when ownership should follow a Juicebox project. Do not use it if
 
 If the issue is in project ownership itself, start in `nana-core-v6` and `JBProjects`. This repo matters when another contract wants its admin surface to follow that project ownership.
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -37,7 +39,7 @@ If the issue is in project ownership itself, start in `nana-core-v6` and `JBProj
 | `JBOwnableOverrides` | Abstract base that holds owner resolution and delegated-permission logic. |
 | `IJBOwnable` | Interface for queries, transfers, permission ID changes, and events. |
 
-## Mental Model
+## Mental model
 
 This package is a small ownership adapter:
 
@@ -45,13 +47,13 @@ This package is a small ownership adapter:
 2. optionally allow a delegated permission to satisfy `onlyOwner` when the contract is project-owned
 3. preserve an `Ownable`-like interface for downstream contracts
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBOwnable.sol`
 2. `src/JBOwnableOverrides.sol`
 3. `src/interfaces/IJBOwnable.sol`
 
-## Integration Traps
+## Integration traps
 
 - ownership may resolve to a project NFT holder instead of a fixed address, so caching `owner()` off-chain can go stale
 - `owner()` can resolve to `address(0)` if the referenced project NFT is invalid or unreadable, which effectively renounces the contract
@@ -60,13 +62,13 @@ This package is a small ownership adapter:
 - a project NFT round trip back to the owner who last set `permissionId` can reactivate that owner's still-granted delegates
 - ownership transfer and permission-ID updates are part of the security model, not just convenience helpers
 
-## Where State Lives
+## Where state lives
 
 - effective ownership configuration: `JBOwnableOverrides`
 - downstream contract state: the inheriting contract
 - project ownership truth: `nana-core-v6` when the owner target is a Juicebox project
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/Ownable.t.sol`
 2. `test/OwnableAttacks.t.sol`
@@ -90,7 +92,7 @@ forge build
 forge test
 ```
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -102,7 +104,7 @@ test/
   core, attack, invariant, mock, and regression coverage
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - if ownership is tied to a project NFT and that NFT becomes unreachable, the contract is effectively locked
 - project-owned delegated access depends on a chosen permission ID, so bad permission selection is an operational risk
@@ -111,7 +113,9 @@ test/
   resolved owner still matches the owner who set it
 - transferring ownership to a project validates that the project exists at transfer time, but later project invalidation can still collapse effective ownership to `address(0)`
 
-## For AI Agents
+## For AI agents
 
 - Do not collapse project-based ownership into ordinary wallet-based ownership in your summary.
 - Read the attack and regression tests before making claims about burn-lock or unminted-project edge cases.
+
+If ownership should track a project NFT, reach for this; if a fixed wallet is enough, plain `Ownable` is simpler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.34",
+  "version": "0.0.37",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,8 +17,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.72",
-    "@bananapus/permission-ids-v6": "^0.0.27",
+    "@bananapus/core-v6": "^0.0.78",
+    "@bananapus/permission-ids-v6": "^0.0.28",
     "@openzeppelin/contracts": "5.6.1"
   },
   "scripts": {

package/references/operations.md

@@ -1,6 +1,6 @@
 # Ownable Operations
 
-## Change Checklist
+## Change checklist
 
 - If you edit owner resolution, verify both direct ownership and project-owned cases.
 - If you edit permission handling, verify explicit transfer resets, project NFT transfer staleness, and NFT round-trip
@@ -9,7 +9,7 @@
   transfers merely make it stale.
 - If the change touches project ownership, check unminted-project and burn-lock regressions before assuming the happy-path tests are enough.
 
-## Common Failure Modes
+## Common failure modes
 
 - Integrations assume delegated operators survive ownership transfer.
 - Bugs are blamed on this repo when the underlying project NFT ownership changed upstream.

package/references/runtime.md

@@ -1,20 +1,20 @@
 # Ownable Runtime
 
-## Core Roles
+## Core roles
 
 - [`src/JBOwnable.sol`](../src/JBOwnable.sol) is the concrete downstream inheritance surface.
 - [`src/JBOwnableOverrides.sol`](../src/JBOwnableOverrides.sol) owns owner resolution and delegated permission checks.
 
-## High-Risk Areas
+## High-risk areas
 
 - Effective-owner resolution: ownership may follow a project NFT rather than a fixed address.
 - Delegated `onlyOwner` permissions: the chosen permission ID changes who can administer a contract.
 - Transfer semantics: explicit ownable transfers reset permission IDs, while project NFT transfers preserve the stored
   ID and rely on `_permissionOwner` to decide whether it is effective.
 
-## Tests To Trust First
+## Tests to trust first
 
 - [`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/RegressionUnmintedProjectHijack.t.sol`](../test/RegressionUnmintedProjectHijack.t.sol), [`test/regression/PermissionIdNFTTransfer.t.sol`](../test/regression/PermissionIdNFTTransfer.t.sol), and [`test/audit/CodexNemesisPermissionReactivation.t.sol`](../test/audit/CodexNemesisPermissionReactivation.t.sol) for the regressions most likely to matter in review.
+- [`test/regression/BurnLockProtection.t.sol`](../test/regression/BurnLockProtection.t.sol), [`test/RegressionUnmintedProjectHijack.t.sol`](../test/RegressionUnmintedProjectHijack.t.sol), [`test/regression/PermissionIdNFTTransfer.t.sol`](../test/regression/PermissionIdNFTTransfer.t.sol), and [`test/regression/StaleDelegateReactivationOnProjectReturn.t.sol`](../test/regression/StaleDelegateReactivationOnProjectReturn.t.sol) for the regressions most likely to matter in review.

package/src/JBOwnable.sol

@@ -67,12 +67,8 @@ contract JBOwnable is JBOwnableOverrides {
     {
         address resolvedNewOwner = newOwner;
         if (newProjectId != 0) {
-            try PROJECTS.ownerOf(newProjectId) returns (address projectOwner) {
-                resolvedNewOwner = projectOwner;
-            } catch {
-                // Pre-bound future projects have no visible owner yet, so the event reports address(0).
-                resolvedNewOwner = address(0);
-            }
+            // Pre-bound future projects have no visible owner yet, so the event reports address(0).
+            resolvedNewOwner = _projectOwnerOf(newProjectId);
         }
 
         emit OwnershipTransferred({previousOwner: previousOwner, newOwner: resolvedNewOwner, caller: _msgSender()});

package/src/JBOwnableOverrides.sol

@@ -115,12 +115,8 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
             return ownerInfo.owner;
         }
 
-        // If the project owner cannot be read, expose the owner as zero instead of bubbling the upstream revert.
-        try PROJECTS.ownerOf(ownerInfo.projectId) returns (address projectOwner) {
-            return projectOwner;
-        } catch {
-            return address(0);
-        }
+        // Expose the project owner, or zero if the project's NFT cannot be read, instead of bubbling the revert.
+        return _projectOwnerOf(ownerInfo.projectId);
     }
 
     //*********************************************************************//
@@ -150,11 +146,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
             return;
         } else {
             // Resolve the project owner dynamically; unreadable projects fail closed to address(0).
-            try PROJECTS.ownerOf(ownerInfo.projectId) returns (address projectOwner) {
-                resolvedOwner = projectOwner;
-            } catch {
-                resolvedOwner = address(0);
-            }
+            resolvedOwner = _projectOwnerOf(ownerInfo.projectId);
         }
 
         // Ignore the stored permission ID while the project NFT is held by a different owner than the one who set it.
@@ -179,6 +171,22 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         });
     }
 
+    /// @notice Resolves the current holder of a project's ownership NFT, or `address(0)` if the project's NFT cannot
+    /// be read.
+    /// @dev Wraps `PROJECTS.ownerOf` in a try-catch so an unreadable project (for example an NFT that has not been
+    /// minted yet) resolves to `address(0)` and owner-gated logic fails closed instead of bubbling the revert. The
+    /// resolution lives in one place so the try-catch lives in a single function rather than at every call site and in
+    /// every contract that inherits this.
+    /// @param projectId The ID of the project whose owner to resolve.
+    /// @return projectOwner The project's current owner, or `address(0)` if `PROJECTS.ownerOf` reverts.
+    function _projectOwnerOf(uint256 projectId) internal view virtual returns (address projectOwner) {
+        try PROJECTS.ownerOf(projectId) returns (address resolved) {
+            projectOwner = resolved;
+        } catch {
+            projectOwner = address(0);
+        }
+    }
+
     //*********************************************************************//
     // ---------------------- public transactions ------------------------ //
     //*********************************************************************//
@@ -288,11 +296,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         if (ownerInfo.projectId == 0) {
             oldOwner = ownerInfo.owner;
         } else {
-            try PROJECTS.ownerOf(ownerInfo.projectId) returns (address projectOwner) {
-                oldOwner = projectOwner;
-            } catch {
-                oldOwner = address(0);
-            }
+            oldOwner = _projectOwnerOf(ownerInfo.projectId);
         }
         // Explicit ownership transfers clear delegated access and the owner who authorized it.
         jbOwner = JBOwner({owner: newOwner, projectId: projectId, permissionId: 0});