@bananapus/721-hook-v6 0.0.45 → 0.0.47

package/CHANGELOG.md

@@ -20,7 +20,7 @@ This file describes the verified change from `nana-721-hook-v5` to the current `
 - The repo now carries a dedicated helper library to keep the hook surface manageable and to support the larger v6 feature set.
 - The repo was upgraded from the v5 Solidity baseline to `0.8.28`.
 
-## Local audit remediations
+## Local review remediations
 
 - `JB721TiersHookProjectDeployer.launchRulesetsFor` now checks `LAUNCH_RULESETS` instead of `QUEUE_RULESETS`. The previous check was semantically wrong — launching active rulesets should require the launch permission, not the queue permission.
 
@@ -43,7 +43,7 @@ This file describes the verified change from `nana-721-hook-v5` to the current `
 
 ## Indexer impact
 
-- New events: `AddToBalanceReverted` (declared but no longer emitted -- replaced by `JB721TiersHookLib_SplitFallbackFailed` revert error), `SetName`, `SetSymbol`, `SplitPayoutReverted`.
+- New events: `SetName`, `SetSymbol`, `SplitPayoutReverted`.
 - Tier config decoding changed because `JB721TierConfig` is no longer v5-compatible.
 - Collection metadata can now change after deployment, so one-time indexing of `name` and `symbol` is no longer sufficient.
 
@@ -62,7 +62,6 @@ This file describes the verified change from `nana-721-hook-v5` to the current `
   - `pricingContext()`
   - `setMetadata(...)`
 - Added events
-  - `AddToBalanceReverted` (declared in interface but no longer emitted; the library now reverts with `JB721TiersHookLib_SplitFallbackFailed` instead)
   - `SetName`
   - `SetSymbol`
   - `SplitPayoutReverted`

package/README.md

@@ -73,7 +73,7 @@ That split is why UI bugs, economic bugs, and deployment bugs often land in diff
 1. `test/E2E/Pay_Mint_Redeem_E2E.t.sol`
 2. `test/invariants/TierLifecycleInvariant.t.sol`
 3. `test/invariants/TieredHookStoreInvariant.t.sol`
-4. `test/audit/CodexSplitCreditsMismatch.t.sol`
+4. `test/regression/RegressionSplitCreditsMismatch.t.sol`
 5. `test/regression/ProjectDeployerRulesets.t.sol`
 
 ## Install
@@ -112,7 +112,7 @@ src/
   libraries/
   structs/
 test/
-  unit, E2E, fork, invariant, audit, and regression coverage
+  unit, E2E, fork, invariant, review, and regression coverage
 script/
   Deploy.s.sol
   helpers/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@bananapus/address-registry-v6": "0.0.25",
-    "@bananapus/core-v6": "^0.0.39",
+    "@bananapus/core-v6": "0.0.44",
     "@bananapus/ownable-v6": "^0.0.24",
     "@bananapus/permission-ids-v6": "0.0.22",
     "@openzeppelin/contracts": "5.6.1",

package/references/operations.md

@@ -25,8 +25,8 @@
 ## Useful Proof Points
 
 - [`test/Fork.t.sol`](../test/Fork.t.sol) for live-integration assumptions.
-- [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for known edge cases the repo authors considered worth pinning down.
+- [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) for known edge cases the repo authors considered worth pinning down.
 - [`test/TestCheckpoints.t.sol`](../test/TestCheckpoints.t.sol) when you need a narrow function-level proof before editing a broad runtime path.
 - [`test/invariants/TierLifecycleInvariant.t.sol`](../test/invariants/TierLifecycleInvariant.t.sol) and [`test/invariants/TieredHookStoreInvariant.t.sol`](../test/invariants/TieredHookStoreInvariant.t.sol) when a local patch may have broken store-level relationships.
-- [`test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol`](../test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol) when reserve-beneficiary or pending-reserve behavior changes.
+- [`test/regression/RetroactiveReserveBeneficiaryDilution.t.sol`](../test/regression/RetroactiveReserveBeneficiaryDilution.t.sol) when reserve-beneficiary or pending-reserve behavior changes.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) when a deployment or launch question is really about config assembly rather than contract behavior.

package/references/runtime.md

@@ -30,4 +30,4 @@
 - [`test/TestVotingUnitsLifecycle.t.sol`](../test/TestVotingUnitsLifecycle.t.sol) for voting-unit lifecycle behavior.
 - [`test/TestCheckpoints.t.sol`](../test/TestCheckpoints.t.sol) for checkpoint/module behavior.
 - [`test/invariants/TierLifecycleInvariant.t.sol`](../test/invariants/TierLifecycleInvariant.t.sol) and [`test/invariants/TieredHookStoreInvariant.t.sol`](../test/invariants/TieredHookStoreInvariant.t.sol) for store-level lifecycle invariants.
-- [`test/TestSafeTransferReentrancy.t.sol`](../test/TestSafeTransferReentrancy.t.sol), [`test/721HookAttacks.t.sol`](../test/721HookAttacks.t.sol), [`test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol`](../test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol), and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for reentrancy and attack-surface checks.
+- [`test/TestSafeTransferReentrancy.t.sol`](../test/TestSafeTransferReentrancy.t.sol), [`test/721HookAttacks.t.sol`](../test/721HookAttacks.t.sol), [`test/regression/RetroactiveReserveBeneficiaryDilution.t.sol`](../test/regression/RetroactiveReserveBeneficiaryDilution.t.sol), and [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) for reentrancy and attack-surface checks.

package/script/helpers/Hook721DeploymentLib.sol

@@ -35,7 +35,7 @@ library Hook721DeploymentLib {
 
         for (uint256 _i; _i < networks.length; _i++) {
             if (networks[_i].chainId == chainId) {
-                return getDeployment(path, networks[_i].name);
+                return getDeployment({path: path, network_name: networks[_i].name});
             }
         }
 
@@ -52,15 +52,31 @@ library Hook721DeploymentLib {
         returns (Hook721Deployment memory deployment)
     {
         deployment.hook_deployer = IJB721TiersHookDeployer(
-            _getDeploymentAddress(path, "nana-721-hook-v6", network_name, "JB721TiersHookDeployer")
+            _getDeploymentAddress({
+                path: path,
+                project_name: "nana-721-hook-v6",
+                network_name: network_name,
+                contractName: "JB721TiersHookDeployer"
+            })
         );
 
         deployment.project_deployer = IJB721TiersHookProjectDeployer(
-            _getDeploymentAddress(path, "nana-721-hook-v6", network_name, "JB721TiersHookProjectDeployer")
+            _getDeploymentAddress({
+                path: path,
+                project_name: "nana-721-hook-v6",
+                network_name: network_name,
+                contractName: "JB721TiersHookProjectDeployer"
+            })
         );
 
-        deployment.store =
-            IJB721TiersHookStore(_getDeploymentAddress(path, "nana-721-hook-v6", network_name, "JB721TiersHookStore"));
+        deployment.store = IJB721TiersHookStore(
+            _getDeploymentAddress({
+                path: path,
+                project_name: "nana-721-hook-v6",
+                network_name: network_name,
+                contractName: "JB721TiersHookStore"
+            })
+        );
     }
 
     /// @notice Get the address of a contract that was deployed by the Deploy script.

package/src/JB721Checkpoints.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {Votes} from "@openzeppelin/contracts/governance/utils/Votes.sol";
 import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
 import {Checkpoints} from "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
@@ -23,8 +24,9 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error JB721Checkpoints_AlreadyInitialized();
-    error JB721Checkpoints_Unauthorized();
+    error JB721Checkpoints_AlreadyInitialized(address hook);
+    error JB721Checkpoints_NotOwner(uint256 tokenId, address caller);
+    error JB721Checkpoints_Unauthorized(address caller, address hook);
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -44,7 +46,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
 
-    /// @notice Checkpointed token owners for historical reward eligibility after first transfer.
+    /// @notice Checkpointed token owners for historical reward eligibility. Written on enrollment or transfer.
     /// @custom:param tokenId The token ID to get historical owner checkpoints for.
     mapping(uint256 tokenId => Checkpoints.Trace160) internal _ownerCheckpointsOf;
 
@@ -64,13 +66,43 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
+    /// @notice Delegates voting power and enrolls tokens for distribution eligibility.
+    /// @dev Writes per-token owner checkpoints so `ownerOfAt` can prove ownership at past blocks.
+    /// Only the current token owner can enroll. Tokens without checkpoints are ineligible for snapshot-based
+    /// distribution. The existing `delegate(address)` from OZ Votes still works for pure delegation without enrollment.
+    /// @param delegatee The address to delegate voting power to. Use your own address for self-delegation.
+    /// @param tokenIds The token IDs to enroll for distribution eligibility.
+    function delegate(address delegatee, uint256[] calldata tokenIds) external override {
+        // Delegate voting power (reuses OZ Votes internals).
+        _delegate({account: msg.sender, delegatee: delegatee});
+
+        // Write per-token owner checkpoints for distribution eligibility.
+        for (uint256 i; i < tokenIds.length;) {
+            uint256 tokenId = tokenIds[i];
+
+            // Only the current owner can enroll their tokens.
+            if (IERC721(HOOK).ownerOf(tokenId) != msg.sender) {
+                revert JB721Checkpoints_NotOwner({tokenId: tokenId, caller: msg.sender});
+            }
+
+            // Write an owner checkpoint if the token has none yet.
+            if (_ownerCheckpointsOf[tokenId].length() == 0) {
+                // forge-lint: disable-next-line(unsafe-typecast)
+                _ownerCheckpointsOf[tokenId].push({key: uint96(block.number), value: uint160(msg.sender)});
+            }
+
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
     /// @notice Initializes a cloned module with its hook reference.
     /// @dev Can only be called once. Called by the deployer after cloning.
     /// @param hook The hook this module serves.
     function initialize(address hook) external override {
-        if (HOOK != address(0)) revert JB721Checkpoints_AlreadyInitialized();
+        if (HOOK != address(0)) revert JB721Checkpoints_AlreadyInitialized({hook: HOOK});
         // `hook` cannot be zero when called through the deployer because `msg.sender` must equal `hook`.
-        // slither-disable-next-line missing-zero-check
         HOOK = hook;
     }
 
@@ -80,11 +112,10 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @param to The new owner (address(0) on burn).
     /// @param tokenId The token ID to transfer.
     function onTransfer(address from, address to, uint256 tokenId) external override {
-        if (msg.sender != HOOK) revert JB721Checkpoints_Unauthorized();
+        if (msg.sender != HOOK) revert JB721Checkpoints_Unauthorized({caller: msg.sender, hook: HOOK});
 
         if (from != address(0)) {
             // forge-lint: disable-next-line(unsafe-typecast)
-            // slither-disable-next-line unused-return
             _ownerCheckpointsOf[tokenId].push({key: uint96(block.number), value: uint160(to)});
         }
 
@@ -100,11 +131,11 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     //*********************************************************************//
 
     /// @notice The owner of an NFT at a past block.
-    /// @dev Mints do not write per-token checkpoint storage. Until a token's first non-mint transfer, ownership is
-    /// inferred from the hook's `firstOwnerOf`.
+    /// @dev Returns `address(0)` for tokens that have never been enrolled (via `delegate(address, uint256[])`) or
+    /// transferred. Unenrolled tokens are ineligible for snapshot-based distribution.
     /// @param tokenId The token ID of the NFT to get the historical owner of.
     /// @param blockNumber The block number to look up.
-    /// @return The owner of the token at `blockNumber`, or zero if the token has no known owner.
+    /// @return The owner of the token at `blockNumber`, or zero if the token is unenrolled or has no known owner.
     function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view override returns (address) {
         // forge-lint: disable-next-line(unsafe-typecast)
         uint96 blockNumber96 = uint96(blockNumber);
@@ -112,10 +143,11 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         Checkpoints.Trace160 storage checkpoints = _ownerCheckpointsOf[tokenId];
         uint256 checkpointCount = checkpoints.length();
 
-        // Before the first transfer/burn checkpoint, the mint owner is implicit in the hook's first-owner tracking.
-        if (checkpointCount == 0 || checkpoints.at(0)._key > blockNumber96) {
-            return IJB721TiersHook(HOOK).firstOwnerOf(tokenId);
-        }
+        // No checkpoints = not enrolled and never transferred. Not eligible.
+        if (checkpointCount == 0) return address(0);
+
+        // Query is before the first checkpoint — token not yet enrolled/transferred at this block.
+        if (checkpoints.at(0)._key > blockNumber96) return address(0);
 
         return address(uint160(checkpoints.upperLookupRecent(blockNumber96)));
     }

package/src/JB721CheckpointsDeployer.sol

@@ -13,6 +13,12 @@ import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 /// @dev The implementation is deployed once in the constructor. Each `deploy()` call clones it (~45k gas) and
 /// initializes the clone with the hook and store references.
 contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JB721CheckpointsDeployer_Unauthorized(address caller, address hook);
+
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
@@ -42,7 +48,9 @@ contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
     /// @param hook The hook address the module will serve.
     /// @return module The newly deployed and initialized checkpoint module.
     function deploy(address hook) external override returns (IJB721Checkpoints module) {
-        if (msg.sender != hook) revert JB721CheckpointsDeployer_Unauthorized();
+        if (msg.sender != hook) {
+            revert JB721CheckpointsDeployer_Unauthorized({caller: msg.sender, hook: hook});
+        }
 
         module = IJB721Checkpoints(
             LibClone.cloneDeterministic({implementation: IMPLEMENTATION, salt: bytes32(uint256(uint160(hook)))})

package/src/JB721TiersHook.sol

@@ -42,12 +42,10 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     //*********************************************************************//
 
     error JB721TiersHook_AlreadyInitialized(uint256 projectId);
-    error JB721TiersHook_CantBuyWithCredits();
     error JB721TiersHook_InvalidPricingDecimals(uint256 decimals);
-    error JB721TiersHook_MintReserveNftsPaused();
-    error JB721TiersHook_NoProjectId();
-    error JB721TiersHook_Overspending(uint256 leftoverAmount);
-    error JB721TiersHook_TierTransfersPaused();
+    error JB721TiersHook_MintReserveNftsPaused(uint256 projectId, uint256 tierId);
+    error JB721TiersHook_NoProjectId(uint256 projectId);
+    error JB721TiersHook_TierTransfersPaused(uint256 projectId, uint256 tokenId, address from, address to);
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -264,7 +262,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         _initialized = true;
 
         // Make sure a projectId is provided.
-        if (projectId == 0) revert JB721TiersHook_NoProjectId();
+        if (projectId == 0) revert JB721TiersHook_NoProjectId({projectId: projectId});
 
         // Initialize the superclass.
         JB721Hook._initialize({projectId: projectId, name: name, symbol: symbol});
@@ -279,7 +277,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         // pack the pricing decimals in bits 32-39 (8 bits).
         packed |= uint256(tiersConfig.decimals) << 32;
         // Store the packed value.
-        // slither-disable-next-line events-maths
         _packedPricingContext = packed;
 
         // Store the base URI if provided.
@@ -385,7 +382,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         _requirePermissionFrom({account: owner(), projectId: PROJECT_ID, permissionId: JBPermissionIds.MINT_721});
 
         // Record the mint. The token IDs returned correspond to the tiers passed in.
-        // slither-disable-next-line reentrancy-events,unused-return
         (tokenIds,,) = STORE.recordMint({
             amount: type(uint256).max, // force the mint.
             tierIds: tierIds,
@@ -503,7 +499,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         // `address(this)` is the sentinel value meaning "leave unchanged" (since `address(0)` clears the resolver).
         if (tokenUriResolver != IJB721TokenUriResolver(address(this))) {
             // Store the new URI resolver.
-            // slither-disable-next-line reentrancy-events
             _recordSetTokenUriResolver(tokenUriResolver);
         }
         if (encodedIPFSUriTierId != 0 && encodedIPFSUri != bytes32(0)) {
@@ -529,15 +524,13 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         // Pending reserve mints must not be paused.
         if (JB721TiersRulesetMetadataResolver.mintPendingReservesPaused((JBRulesetMetadataResolver.metadata(ruleset))))
         {
-            revert JB721TiersHook_MintReserveNftsPaused();
+            revert JB721TiersHook_MintReserveNftsPaused({projectId: PROJECT_ID, tierId: tierId});
         }
 
         // Record the reserved mint for the tier.
-        // slither-disable-next-line reentrancy-events,calls-loop
         uint256[] memory tokenIds = STORE.recordMintReservesFor({tierId: tierId, count: count});
 
         // Keep a reference to the beneficiary.
-        // slither-disable-next-line calls-loop
         address reserveBeneficiary = STORE.reserveBeneficiaryOf({hook: address(this), tierId: tierId});
 
         // Cache _msgSender() before the loop to avoid repeated calls.
@@ -550,7 +543,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             emit MintReservedNft({tokenId: tokenId, tierId: tierId, beneficiary: reserveBeneficiary, caller: caller});
 
             // Mint the NFT.
-            // slither-disable-next-line reentrency-events
             _mint({to: reserveBeneficiary, tokenId: tokenId});
 
             unchecked {
@@ -572,7 +564,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param projectId The ID of the project to check.
     /// @return The project's current ruleset.
     function _currentRulesetOf(uint256 projectId) internal view returns (JBRuleset memory) {
-        // slither-disable-next-line calls-loop
         return RULESETS.currentOf(projectId);
     }
 
@@ -625,7 +616,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 caller: caller
             });
 
-            // slither-disable-next-line reentrancy-events
             _mint({to: beneficiary, tokenId: tokenIds[i]});
 
             unchecked {
@@ -665,7 +655,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         if (tokenIds.length != 0) {
             // totalAmountPaid is the full amount available before recordMint deducted tier prices.
             uint256 totalAmountPaid = (payer == beneficiary) ? value + payCredits : value;
-            // slither-disable-next-line reentrancy-events
             _mintTokens({
                 tokenIds: tokenIds, tierIds: tierIdsToMint, beneficiary: beneficiary, totalAmountPaid: totalAmountPaid
             });
@@ -689,7 +678,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 });
             }
 
-            // slither-disable-next-line reentrancy-no-eth
             payCreditsOf[beneficiary] = newPayCredits;
         }
     }
@@ -757,7 +745,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param tierId The ID of the tier to set the discount percent for.
     /// @param discountPercent The discount percent to set (0 = no discount, up to DISCOUNT_DENOMINATOR = free).
     function _setDiscountPercentOf(uint256 tierId, uint256 discountPercent) internal {
-        // slither-disable-next-line calls-loop
         JB721TiersHookLib.setDiscountPercentOf({
             store: STORE, tierId: tierId, discountPercent: discountPercent, caller: _msgSender()
         });
@@ -768,7 +755,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param tokenId The token ID of the NFT to transfer.
     function _update(address to, uint256 tokenId, address auth) internal virtual override returns (address from) {
         // Get only the tier ID and transfersPausable flag (lightweight — avoids full struct construction).
-        // slither-disable-next-line calls-loop
         (uint256 tierId, bool transfersPausable) =
             STORE.tierTransferInfoOfTokenId({hook: address(this), tokenId: tokenId});
 
@@ -788,26 +774,26 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                         && JB721TiersRulesetMetadataResolver.transfersPaused(
                             (JBRulesetMetadataResolver.metadata(ruleset))
                         )
-                ) revert JB721TiersHook_TierTransfersPaused();
+                ) {
+                    revert JB721TiersHook_TierTransfersPaused({
+                        projectId: PROJECT_ID, tokenId: tokenId, from: from, to: to
+                    });
+                }
             }
 
             // If the token isn't already associated with a first owner, store the sender as the first owner.
-            // slither-disable-next-line calls-loop
             if (_firstOwnerOf[tokenId] == address(0)) _firstOwnerOf[tokenId] = from;
         }
 
         // Record the transfer.
-        // slither-disable-next-line reentrency-events,calls-loop
         STORE.recordTransferForTier({tierId: tierId, from: from, to: to});
 
         // Deploy the checkpoint module lazily on the first transfer.
         if (address(CHECKPOINTS) == address(0)) {
-            // slither-disable-next-line calls-loop,reentrancy-events
             CHECKPOINTS = CHECKPOINTS_DEPLOYER.deploy(address(this));
         }
 
         // Notify the checkpoint module to update checkpointed voting power.
-        // slither-disable-next-line calls-loop,reentrancy-events
         CHECKPOINTS.onTransfer({from: from, to: to, tokenId: tokenId});
     }
 }

package/src/JB721TiersHookDeployer.sol

@@ -103,7 +103,6 @@ contract JB721TiersHookDeployer is ERC2771Context, IJB721TiersHookDeployer {
         JBOwnable(address(newHook)).transferOwnership(_msgSender());
 
         // Increment the nonce.
-        // slither-disable-next-line reentrancy-benign
         ++_nonce;
 
         // Add the hook to the address registry. This contract's nonce starts at 1.

package/src/JB721TiersHookProjectDeployer.sol

@@ -276,7 +276,7 @@ contract JB721TiersHookProjectDeployer is
                     allowAddPriceFeed: payDataRulesetConfig.metadata.allowAddPriceFeed,
                     ownerMustSendPayouts: payDataRulesetConfig.metadata.ownerMustSendPayouts,
                     holdFees: payDataRulesetConfig.metadata.holdFees,
-                    useTotalSurplusForCashOuts: payDataRulesetConfig.metadata.useTotalSurplusForCashOuts,
+                    scopeCashOutsToLocalBalances: payDataRulesetConfig.metadata.scopeCashOutsToLocalBalances,
                     useDataHookForPay: true,
                     useDataHookForCashOut: payDataRulesetConfig.metadata.useDataHookForCashOut,
                     dataHook: address(dataHook),
@@ -292,7 +292,6 @@ contract JB721TiersHookProjectDeployer is
         }
 
         // Launch the rulesets for the reserved project.
-        // slither-disable-next-line unused-return
         controller.launchRulesetsFor({
             projectId: projectId,
             projectUri: launchProjectConfig.projectUri,
@@ -351,7 +350,7 @@ contract JB721TiersHookProjectDeployer is
                     allowAddPriceFeed: payDataRulesetConfig.metadata.allowAddPriceFeed,
                     ownerMustSendPayouts: payDataRulesetConfig.metadata.ownerMustSendPayouts,
                     holdFees: payDataRulesetConfig.metadata.holdFees,
-                    useTotalSurplusForCashOuts: payDataRulesetConfig.metadata.useTotalSurplusForCashOuts,
+                    scopeCashOutsToLocalBalances: payDataRulesetConfig.metadata.scopeCashOutsToLocalBalances,
                     useDataHookForPay: true,
                     useDataHookForCashOut: payDataRulesetConfig.metadata.useDataHookForCashOut,
                     dataHook: address(dataHook),
@@ -426,7 +425,7 @@ contract JB721TiersHookProjectDeployer is
                     allowAddPriceFeed: payDataRulesetConfig.metadata.allowAddPriceFeed,
                     ownerMustSendPayouts: payDataRulesetConfig.metadata.ownerMustSendPayouts,
                     holdFees: payDataRulesetConfig.metadata.holdFees,
-                    useTotalSurplusForCashOuts: payDataRulesetConfig.metadata.useTotalSurplusForCashOuts,
+                    scopeCashOutsToLocalBalances: payDataRulesetConfig.metadata.scopeCashOutsToLocalBalances,
                     useDataHookForPay: true,
                     useDataHookForCashOut: payDataRulesetConfig.metadata.useDataHookForCashOut,
                     dataHook: address(dataHook),

package/src/JB721TiersHookStore.sol

@@ -31,7 +31,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
     error JB721TiersHookStore_CantMintManually(uint256 tierId);
     error JB721TiersHookStore_CantRemoveTier(uint256 tierId);
-    error JB721TiersHookStore_DeadlockedReserve();
+    error JB721TiersHookStore_DeadlockedReserve(uint256 tierId, uint256 initialSupply, uint256 reserveFrequency);
     error JB721TiersHookStore_DiscountPercentExceedsBounds(uint256 percent, uint256 limit);
     error JB721TiersHookStore_DiscountPercentIncreaseNotAllowed(uint256 percent, uint256 storedPercent);
     error JB721TiersHookStore_InsufficientPendingReserves(uint256 count, uint256 numberOfPendingReserves);
@@ -618,7 +618,6 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         // Cache packed bools to avoid stack-too-deep from destructuring all 6 bools.
         uint8 packed = storedTier.packedBools;
 
-        // slither-disable-next-line calls-loop
         return JB721Tier({
             // forge-lint: disable-next-line(unsafe-typecast)
             id: uint32(tierId),
@@ -838,11 +837,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         uint256 currentSortedTierId = _firstSortedTierIdOf({hook: hook, category: 0});
 
         // Keep track of the previous non-removed tier ID.
-        // slither-disable-next-line uninitialized-local
         uint256 previousSortedTierId;
 
         // Initialize a `JBBitmapWord` for tracking removed tiers.
-        // slither-disable-next-line uninitialized-local
         JBBitmapWord memory bitmapWord;
 
         // Make the sorted array.
@@ -905,7 +902,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
         // Make sure the max number of tiers won't be exceeded.
         if (currentMaxTierIdOf + tiersToAdd.length > type(uint16).max) {
-            revert JB721TiersHookStore_MaxTiersExceeded(currentMaxTierIdOf + tiersToAdd.length, type(uint16).max);
+            revert JB721TiersHookStore_MaxTiersExceeded({
+                numberOfTiers: currentMaxTierIdOf + tiersToAdd.length, limit: type(uint16).max
+            });
         }
 
         // Keep a reference to the current last sorted tier ID (sorted by category).
@@ -919,7 +918,6 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         uint256 startSortedTierId = currentMaxTierIdOf == 0 ? 0 : _firstSortedTierIdOf({hook: msg.sender, category: 0});
 
         // Keep track of the previous tier's ID while iterating.
-        // slither-disable-next-line uninitialized-local
         uint256 previousTierId;
 
         // Keep a reference to the 721 contract's flags.
@@ -932,7 +930,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
             // Make sure the supply maximum is enforced. If it's greater than one billion, it would overflow into the
             // next tier.
             if (tierToAdd.initialSupply > _ONE_BILLION - 1) {
-                revert JB721TiersHookStore_InvalidQuantity(tierToAdd.initialSupply, _ONE_BILLION - 1);
+                revert JB721TiersHookStore_InvalidQuantity({quantity: tierToAdd.initialSupply, limit: _ONE_BILLION - 1});
             }
 
             // Make sure the tier's category is greater than or equal to the previously added tier's category.
@@ -942,7 +940,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
                 // Revert if the category is not equal or greater than the previously added tier's category.
                 if (tierToAdd.category < previousCategory) {
-                    revert JB721TiersHookStore_InvalidCategorySortOrder(tierToAdd.category, previousCategory);
+                    revert JB721TiersHookStore_InvalidCategorySortOrder({
+                        tierCategory: tierToAdd.category, previousTierCategory: previousCategory
+                    });
                 }
             }
 
@@ -955,32 +955,32 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
                     && ((tierToAdd.flags.useVotingUnits && tierToAdd.votingUnits != 0)
                         || (!tierToAdd.flags.useVotingUnits && tierToAdd.price != 0))
             ) {
-                revert JB721TiersHookStore_VotingUnitsNotAllowed(tierId);
+                revert JB721TiersHookStore_VotingUnitsNotAllowed({tierId: tierId});
             }
 
             // Make sure the new tier doesn't have a reserve frequency if the 721 contract's flags don't allow it to,
             // OR if manual minting is allowed.
             if ((flags.noNewTiersWithReserves || tierToAdd.flags.allowOwnerMint) && tierToAdd.reserveFrequency != 0) {
-                revert JB721TiersHookStore_ReserveFrequencyNotAllowed(tierId);
+                revert JB721TiersHookStore_ReserveFrequencyNotAllowed({tierId: tierId});
             }
 
             // Make sure the new tier doesn't have owner minting enabled if the 721 contract's flags don't allow it to.
             if (flags.noNewTiersWithOwnerMinting && tierToAdd.flags.allowOwnerMint) {
-                revert JB721TiersHookStore_ManualMintingNotAllowed(tierId);
+                revert JB721TiersHookStore_ManualMintingNotAllowed({tierId: tierId});
             }
 
             // Make sure the discount percent is within the bound.
             if (tierToAdd.discountPercent > JB721Constants.DISCOUNT_DENOMINATOR) {
-                revert JB721TiersHookStore_DiscountPercentExceedsBounds(
-                    tierToAdd.discountPercent, JB721Constants.DISCOUNT_DENOMINATOR
-                );
+                revert JB721TiersHookStore_DiscountPercentExceedsBounds({
+                    percent: tierToAdd.discountPercent, limit: JB721Constants.DISCOUNT_DENOMINATOR
+                });
             }
 
             // Make sure the split percent is within the bound.
             if (tierToAdd.splitPercent > JBConstants.SPLITS_TOTAL_PERCENT) {
-                revert JB721TiersHookStore_SplitPercentExceedsBounds(
-                    tierToAdd.splitPercent, JBConstants.SPLITS_TOTAL_PERCENT
-                );
+                revert JB721TiersHookStore_SplitPercentExceedsBounds({
+                    percent: tierToAdd.splitPercent, limit: JBConstants.SPLITS_TOTAL_PERCENT
+                });
             }
 
             // Make sure the tier has a non-zero supply.
@@ -989,7 +989,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
             // A tier with initialSupply == 1 and reserveFrequency > 0 deadlocks: the single mint is reserved,
             // leaving zero available for paid mints, but reserves only mint after a paid mint triggers them.
             if (tierToAdd.initialSupply == 1 && tierToAdd.reserveFrequency > 0) {
-                revert JB721TiersHookStore_DeadlockedReserve();
+                revert JB721TiersHookStore_DeadlockedReserve({
+                    tierId: tierId, initialSupply: tierToAdd.initialSupply, reserveFrequency: tierToAdd.reserveFrequency
+                });
             }
 
             // A tier with reserves must have a beneficiary — either tier-specific or a previously set default.
@@ -998,7 +1000,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
                 tierToAdd.reserveFrequency > 0 && tierToAdd.reserveBeneficiary == address(0)
                     && defaultReserveBeneficiaryOf[msg.sender] == address(0)
             ) {
-                revert JB721TiersHookStore_MissingReserveBeneficiary(tierId);
+                revert JB721TiersHookStore_MissingReserveBeneficiary({tierId: tierId});
             }
 
             // Store the tier with that ID.
@@ -1213,7 +1215,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
             // Make sure the tier hasn't been removed.
             if (_isTierRemovedWithRefresh({hook: msg.sender, tierId: tierId, bitmapWord: bitmapWord})) {
-                revert JB721TiersHookStore_TierRemoved(tierId);
+                revert JB721TiersHookStore_TierRemoved({tierId: tierId});
             }
 
             // Keep a reference to the stored tier being iterated on.
@@ -1265,7 +1267,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
                 storedTier.remainingSupply
                     < _numberOfPendingReservesFor({hook: msg.sender, tierId: tierId, storedTier: storedTier})
             ) {
-                revert JB721TiersHookStore_InsufficientSupplyRemaining(tierId);
+                revert JB721TiersHookStore_InsufficientSupplyRemaining({tierId: tierId});
             }
 
             unchecked {
@@ -1295,7 +1297,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
         // Can't mint more than the number of pending reserves.
         if (count > numberOfPendingReserves) {
-            revert JB721TiersHookStore_InsufficientPendingReserves(count, numberOfPendingReserves);
+            revert JB721TiersHookStore_InsufficientPendingReserves({
+                count: count, numberOfPendingReserves: numberOfPendingReserves
+            });
         }
 
         // Increment the number of reserve NFTs minted.
@@ -1330,7 +1334,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
             // Reject tier IDs that don't exist yet — removing a future tier would cause it
             // to be born already removed when later added.
             if (tierId == 0 || tierId > maxTierIdOf[msg.sender]) {
-                revert JB721TiersHookStore_UnrecognizedTier(tierId);
+                revert JB721TiersHookStore_UnrecognizedTier({tierId: tierId});
             }
 
             // Get a reference to the stored tier.
@@ -1363,9 +1367,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
         // Make sure the discount percent is within the bound.
         if (discountPercent > JB721Constants.DISCOUNT_DENOMINATOR) {
-            revert JB721TiersHookStore_DiscountPercentExceedsBounds(
-                discountPercent, JB721Constants.DISCOUNT_DENOMINATOR
-            );
+            revert JB721TiersHookStore_DiscountPercentExceedsBounds({
+                percent: discountPercent, limit: JB721Constants.DISCOUNT_DENOMINATOR
+            });
         }
 
         // Get a reference to the stored tier.
@@ -1376,7 +1380,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
         // Make sure that increasing the discount is allowed for the tier.
         if (discountPercent > storedTier.discountPercent && cantIncreaseDiscountPercent) {
-            revert JB721TiersHookStore_DiscountPercentIncreaseNotAllowed(discountPercent, storedTier.discountPercent);
+            revert JB721TiersHookStore_DiscountPercentIncreaseNotAllowed({
+                percent: discountPercent, storedPercent: storedTier.discountPercent
+            });
         }
 
         // Set the discount.

package/src/abstract/ERC721.sol

@@ -72,7 +72,7 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      */
     function balanceOf(address owner) public view virtual returns (uint256) {
         if (owner == address(0)) {
-            revert ERC721InvalidOwner(address(0));
+            revert ERC721InvalidOwner({owner: address(0)});
         }
         return _balances[owner];
     }
@@ -153,13 +153,13 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      */
     function transferFrom(address from, address to, uint256 tokenId) public virtual {
         if (to == address(0)) {
-            revert ERC721InvalidReceiver(address(0));
+            revert ERC721InvalidReceiver({receiver: address(0)});
         }
         // Setting an "auth" arguments enables the `_isAuthorized` check which verifies that the token exists
         // (from != 0). Therefore, it is not needed to verify that the return value is not 0 here.
         address previousOwner = _update({to: to, tokenId: tokenId, auth: _msgSender()});
         if (previousOwner != from) {
-            revert ERC721IncorrectOwner(from, tokenId, previousOwner);
+            revert ERC721IncorrectOwner({sender: from, tokenId: tokenId, owner: previousOwner});
         }
     }
 
@@ -206,7 +206,9 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      */
     function _isAuthorized(address owner, address spender, uint256 tokenId) internal view virtual returns (bool) {
         return spender != address(0)
-            && (owner == spender || isApprovedForAll(owner, spender) || _getApproved(tokenId) == spender);
+            && (owner == spender
+                || isApprovedForAll({owner: owner, operator: spender})
+                || _getApproved(tokenId) == spender);
     }
 
     /**
@@ -218,11 +220,11 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      * assumption.
      */
     function _checkAuthorized(address owner, address spender, uint256 tokenId) internal view virtual {
-        if (!_isAuthorized(owner, spender, tokenId)) {
+        if (!_isAuthorized({owner: owner, spender: spender, tokenId: tokenId})) {
             if (owner == address(0)) {
-                revert ERC721NonexistentToken(tokenId);
+                revert ERC721NonexistentToken({tokenId: tokenId});
             } else {
-                revert ERC721InsufficientApproval(spender, tokenId);
+                revert ERC721InsufficientApproval({operator: spender, tokenId: tokenId});
             }
         }
     }
@@ -280,7 +282,7 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
 
         _owners[tokenId] = to;
 
-        emit Transfer(from, to, tokenId);
+        emit Transfer({from: from, to: to, tokenId: tokenId});
 
         return from;
     }
@@ -299,11 +301,11 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      */
     function _mint(address to, uint256 tokenId) internal {
         if (to == address(0)) {
-            revert ERC721InvalidReceiver(address(0));
+            revert ERC721InvalidReceiver({receiver: address(0)});
         }
         address previousOwner = _update({to: to, tokenId: tokenId, auth: address(0)});
         if (previousOwner != address(0)) {
-            revert ERC721InvalidSender(address(0));
+            revert ERC721InvalidSender({sender: address(0)});
         }
     }
 
@@ -345,7 +347,7 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
     function _burn(uint256 tokenId) internal {
         address previousOwner = _update({to: address(0), tokenId: tokenId, auth: address(0)});
         if (previousOwner == address(0)) {
-            revert ERC721NonexistentToken(tokenId);
+            revert ERC721NonexistentToken({tokenId: tokenId});
         }
     }
 
@@ -362,13 +364,13 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      */
     function _transfer(address from, address to, uint256 tokenId) internal {
         if (to == address(0)) {
-            revert ERC721InvalidReceiver(address(0));
+            revert ERC721InvalidReceiver({receiver: address(0)});
         }
         address previousOwner = _update({to: to, tokenId: tokenId, auth: address(0)});
         if (previousOwner == address(0)) {
-            revert ERC721NonexistentToken(tokenId);
+            revert ERC721NonexistentToken({tokenId: tokenId});
         } else if (previousOwner != from) {
-            revert ERC721IncorrectOwner(from, tokenId, previousOwner);
+            revert ERC721IncorrectOwner({sender: from, tokenId: tokenId, owner: previousOwner});
         }
     }
 
@@ -430,12 +432,12 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
             address owner = _requireOwned(tokenId);
 
             // We do not use _isAuthorized because single-token approvals should not be able to call approve
-            if (auth != address(0) && owner != auth && !isApprovedForAll(owner, auth)) {
-                revert ERC721InvalidApprover(auth);
+            if (auth != address(0) && owner != auth && !isApprovedForAll({owner: owner, operator: auth})) {
+                revert ERC721InvalidApprover({approver: auth});
             }
 
             if (emitEvent) {
-                emit Approval(owner, to, tokenId);
+                emit Approval({owner: owner, approved: to, tokenId: tokenId});
             }
         }
 
@@ -452,10 +454,10 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
      */
     function _setApprovalForAll(address owner, address operator, bool approved) internal virtual {
         if (operator == address(0)) {
-            revert ERC721InvalidOperator(operator);
+            revert ERC721InvalidOperator({operator: operator});
         }
         _operatorApprovals[owner][operator] = approved;
-        emit ApprovalForAll(owner, operator, approved);
+        emit ApprovalForAll({owner: owner, operator: operator, approved: approved});
     }
 
     /**
@@ -467,7 +469,7 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
     function _requireOwned(uint256 tokenId) internal view returns (address) {
         address owner = _ownerOf(tokenId);
         if (owner == address(0)) {
-            revert ERC721NonexistentToken(tokenId);
+            revert ERC721NonexistentToken({tokenId: tokenId});
         }
         return owner;
     }
@@ -489,11 +491,11 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
                 bytes4 retval
             ) {
                 if (retval != IERC721Receiver.onERC721Received.selector) {
-                    revert ERC721InvalidReceiver(to);
+                    revert ERC721InvalidReceiver({receiver: to});
                 }
             } catch (bytes memory reason) {
                 if (reason.length == 0) {
-                    revert ERC721InvalidReceiver(to);
+                    revert ERC721InvalidReceiver({receiver: to});
                 } else {
                     /// @solidity memory-safe-assembly
                     assembly {

package/src/abstract/JB721Hook.sol

@@ -30,10 +30,10 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error JB721Hook_InvalidCashOut();
-    error JB721Hook_InvalidPay();
+    error JB721Hook_InvalidCashOut(address caller, uint256 contextProjectId, uint256 projectId, uint256 msgValue);
+    error JB721Hook_InvalidPay(address caller, uint256 contextProjectId, uint256 projectId);
     error JB721Hook_UnauthorizedToken(uint256 tokenId, address holder);
-    error JB721Hook_UnexpectedTokenCashedOut();
+    error JB721Hook_UnexpectedTokenCashedOut(uint256 cashOutCount);
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -94,7 +94,9 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         )
     {
         // Make sure (fungible) project tokens aren't also being cashed out.
-        if (context.cashOutCount > 0) revert JB721Hook_UnexpectedTokenCashedOut();
+        if (context.cashOutCount > 0) {
+            revert JB721Hook_UnexpectedTokenCashedOut({cashOutCount: context.cashOutCount});
+        }
 
         // Fetch the cash out hook metadata using the corresponding metadata ID.
         (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
@@ -185,7 +187,6 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     /// `context.beneficiary`. Part of `IJBCashOutHook`.
     /// @dev Reverts if the calling contract is not one of the project's terminals.
     /// @param context The cash out context passed in by the terminal.
-    // slither-disable-next-line locked-ether
     function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context)
         external
         payable
@@ -200,7 +201,11 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         if (
             msg.value != 0 || !DIRECTORY.isTerminalOf({projectId: projectId, terminal: IJBTerminal(msg.sender)})
                 || context.projectId != projectId
-        ) revert JB721Hook_InvalidCashOut();
+        ) {
+            revert JB721Hook_InvalidCashOut({
+                caller: msg.sender, contextProjectId: context.projectId, projectId: projectId, msgValue: msg.value
+            });
+        }
 
         // Fetch the cash out hook metadata using the corresponding metadata ID.
         (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
@@ -237,7 +242,6 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     /// `IJBPayHook`.
     /// @dev Reverts if the calling contract is not one of the project's terminals.
     /// @param context The payment context passed in by the terminal.
-    // slither-disable-next-line locked-ether
     function afterPayRecordedWith(JBAfterPayRecordedContext calldata context) external payable virtual override {
         uint256 projectId = PROJECT_ID;
 
@@ -247,7 +251,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
             !DIRECTORY.isTerminalOf({projectId: projectId, terminal: IJBTerminal(msg.sender)})
                 || context.projectId != projectId
         ) {
-            revert JB721Hook_InvalidPay();
+            revert JB721Hook_InvalidPay({caller: msg.sender, contextProjectId: context.projectId, projectId: projectId});
         }
 
         // Process the payment.

package/src/interfaces/IJB721Checkpoints.sol

@@ -14,11 +14,11 @@ interface IJB721Checkpoints is IERC5805 {
     function HOOK() external view returns (address);
 
     /// @notice The owner of an NFT at a past block.
-    /// @dev Mints do not write per-token checkpoint storage. Until a token's first non-mint transfer, ownership is
-    /// inferred from the hook's `firstOwnerOf`.
+    /// @dev Returns `address(0)` for tokens that have never been enrolled (via `delegate(address, uint256[])`) or
+    /// transferred. Unenrolled tokens are ineligible for snapshot-based distribution.
     /// @param tokenId The token ID of the NFT to get the historical owner of.
     /// @param blockNumber The block number to look up.
-    /// @return The owner of the token at `blockNumber`, or zero if the token has no known owner.
+    /// @return The owner of the token at `blockNumber`, or zero if the token is unenrolled or has no known owner.
     function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view returns (address);
 
     /// @notice The store that holds tier and voting data for the hook's NFTs.
@@ -26,6 +26,14 @@ interface IJB721Checkpoints is IERC5805 {
     // forge-lint: disable-next-line(mixed-case-function)
     function STORE() external view returns (IJB721TiersHookStore);
 
+    /// @notice Delegates voting power and enrolls tokens for distribution eligibility.
+    /// @dev Writes per-token owner checkpoints so `ownerOfAt` can prove ownership at past blocks.
+    /// Only the current token owner can enroll. Tokens without checkpoints are ineligible for snapshot-based
+    /// distribution.
+    /// @param delegatee The address to delegate voting power to. Use your own address for self-delegation.
+    /// @param tokenIds The token IDs to enroll for distribution eligibility.
+    function delegate(address delegatee, uint256[] calldata tokenIds) external;
+
     /// @notice Initializes a cloned module with its hook reference.
     /// @dev Can only be called once. Called by the deployer after cloning.
     /// @param hook The hook this module serves.
@@ -33,7 +41,6 @@ interface IJB721Checkpoints is IERC5805 {
 
     /// @notice Called by the hook after every NFT transfer to update checkpointed voting power.
     /// @dev Looks up the token's tier voting units from the store internally.
-    /// Auto-self-delegates on first receive so checkpoints work without manual delegation.
     /// @param from The previous owner (address(0) on mint).
     /// @param to The new owner (address(0) on burn).
     /// @param tokenId The token ID to transfer (used to look up tier voting units).

package/src/interfaces/IJB721CheckpointsDeployer.sol

@@ -6,9 +6,6 @@ import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 
 /// @notice Deploys JB721Checkpoints clones for JB721TiersHook instances.
 interface IJB721CheckpointsDeployer {
-    /// @notice Thrown when the caller is not the hook that the checkpoint module is deployed for.
-    error JB721CheckpointsDeployer_Unauthorized();
-
     /// @notice The implementation contract that clones are based on.
     /// @return The implementation address.
     // forge-lint: disable-next-line(mixed-case-function)

package/src/interfaces/IJB721TiersHook.sol

@@ -18,14 +18,6 @@ import {JB721TiersSetDiscountPercentConfig} from "../structs/JB721TiersSetDiscou
 
 /// @notice A 721 tiers hook that mints tiered NFTs for payments and tracks their cash out weight.
 interface IJB721TiersHook is IJB721Hook {
-    /// @notice Emitted when an `addToBalanceOf` call reverts during leftover distribution. The funds remain
-    /// stranded in the hook contract.
-    /// @param projectId The project ID whose terminal reverted.
-    /// @param token The token to send.
-    /// @param amount The amount that failed to send.
-    /// @param reason The revert reason bytes.
-    event AddToBalanceReverted(uint256 indexed projectId, address token, uint256 amount, bytes reason);
-
     /// @notice Emitted when pay credits are added for an account.
     /// @param amount The amount of credits added.
     /// @param newTotalCredits The new total credits balance for the account.

package/src/libraries/JB721Constants.sol

@@ -3,6 +3,7 @@ pragma solidity 0.8.28;
 
 /// @notice Global constants used across 721 hook contracts.
 library JB721Constants {
+    /// @notice The denominator used when applying tier discount percentages.
     uint16 public constant DISCOUNT_DENOMINATOR = 200;
 
     /// @notice The metadata ID used to identify the 721 beneficiary entry in payment metadata.

package/src/libraries/JB721TiersHookLib.sol

@@ -31,7 +31,7 @@ library JB721TiersHookLib {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error JB721TiersHook_CantBuyWithCredits();
+    error JB721TiersHook_CantBuyWithCredits(uint256 restrictedCost, uint256 freshValue);
     error JB721TiersHook_Overspending(uint256 leftoverAmount);
     error JB721TiersHookLib_NoTerminalForLeftover(uint256 projectId, address token, uint256 leftoverAmount);
     error JB721TiersHookLib_SplitFallbackFailed(uint256 projectId, address token, uint256 amount, bytes reason);
@@ -79,7 +79,6 @@ library JB721TiersHookLib {
                     ++i;
                 }
             }
-            // slither-disable-next-line reentrancy-events
             store.recordRemoveTierIds(tierIdsToRemove);
         }
 
@@ -87,7 +86,6 @@ library JB721TiersHookLib {
         if (tiersToAdd.length != 0) {
             uint256[] memory tierIdsAdded = store.recordAddTiers(tiersToAdd);
 
-            // slither-disable-next-line reentrancy-events
             for (uint256 i; i < tiersToAdd.length;) {
                 emit AddTier({tierId: tierIdsAdded[i], tier: tiersToAdd[i], caller: caller});
 
@@ -135,7 +133,9 @@ library JB721TiersHookLib {
             SafeERC20.safeTransferFrom({token: IERC20(token), from: msg.sender, to: address(this), value: amount});
             uint256 receivedAmount = IERC20(token).balanceOf(address(this)) - balanceBefore;
             if (receivedAmount != amount) {
-                revert JB721TiersHookLib_TokenTransferAmountMismatch(amount, receivedAmount);
+                revert JB721TiersHookLib_TokenTransferAmountMismatch({
+                    expectedAmount: amount, receivedAmount: receivedAmount
+                });
             }
         }
 
@@ -223,16 +223,19 @@ library JB721TiersHookLib {
         if (tierIdsToMint.length != 0) {
             uint256 restrictedCost;
 
-            // slither-disable-next-line reentrancy-events,reentrancy-no-eth
             (tokenIds, leftoverAmount, restrictedCost) =
                 store.recordMint({amount: leftoverAmount, tierIds: tierIdsToMint, isOwnerMint: false});
 
             // Credit-restricted tiers must be fully covered by fresh payment (not stored credits).
-            if (restrictedCost > value) revert JB721TiersHook_CantBuyWithCredits();
+            if (restrictedCost > value) {
+                revert JB721TiersHook_CantBuyWithCredits({restrictedCost: restrictedCost, freshValue: value});
+            }
         }
 
         // If overspending isn't allowed, revert.
-        if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
+        if (leftoverAmount != 0 && !allowOverspending) {
+            revert JB721TiersHook_Overspending({leftoverAmount: leftoverAmount});
+        }
 
         // Compute the new pay credits balance: leftover + unused credits (held in newPayCredits).
         newPayCredits = leftoverAmount + newPayCredits;
@@ -259,7 +262,6 @@ library JB721TiersHookLib {
         uint256[] memory tierIdsAdded = store.recordAddTiers(tiersToAdd);
 
         for (uint256 i; i < tiersToAdd.length;) {
-            // slither-disable-next-line reentrancy-events
             emit AddTier({tierId: tierIdsAdded[i], tier: tiersToAdd[i], caller: caller});
 
             unchecked {
@@ -489,7 +491,6 @@ library JB721TiersHookLib {
 
         for (uint256 i; i < tierIdsToMint.length;) {
             // Get only the pricing fields (lightweight — avoids full struct construction).
-            // slither-disable-next-line calls-loop
             (uint104 tierPrice, uint32 tierSplitPercent, uint8 tierDiscountPercent) =
                 store.tierPricingOf({hook: hook, id: tierIdsToMint[i]});
             if (tierSplitPercent != 0) {
@@ -707,7 +708,6 @@ library JB721TiersHookLib {
     )
         private
     {
-        // slither-disable-next-line calls-loop
         JBSplit[] memory tierSplits = splitsContract.splitsOf({projectId: projectId, rulesetId: 0, groupId: groupId});
 
         bool isNativeToken = token == JBConstants.NATIVE_TOKEN;
@@ -725,7 +725,6 @@ library JB721TiersHookLib {
                 // On failure, don't re-add to leftoverAmount — this prevents inflating later recipients.
                 // Failed amounts accumulate as the gap between `amount` and `leftoverAmount + total sent`.
                 // After the loop, we re-add leftoverPercentage-based residual naturally.
-                // slither-disable-next-line calls-loop,reentrancy-no-eth,reentrancy-benign,reentrancy-events
                 if (!_sendPayoutToSplit({
                         directory: directory,
                         split: tierSplits[j],
@@ -752,14 +751,14 @@ library JB721TiersHookLib {
         leftoverAmount += amount;
 
         if (leftoverAmount != 0) {
-            // slither-disable-next-line calls-loop
             IJBTerminal terminal = directory.primaryTerminalOf({projectId: projectId, token: token});
             // Revert if there are leftover funds but no terminal to route them to.
             if (address(terminal) == address(0)) {
-                revert JB721TiersHookLib_NoTerminalForLeftover(projectId, token, leftoverAmount);
+                revert JB721TiersHookLib_NoTerminalForLeftover({
+                    projectId: projectId, token: token, leftoverAmount: leftoverAmount
+                });
             }
             if (isNativeToken) {
-                // slither-disable-next-line arbitrary-send-eth,calls-loop
                 try terminal.addToBalanceOf{value: leftoverAmount}({
                     projectId: projectId,
                     token: token,
@@ -769,11 +768,12 @@ library JB721TiersHookLib {
                     metadata: bytes("")
                 }) {}
                 catch (bytes memory reason) {
-                    revert JB721TiersHookLib_SplitFallbackFailed(projectId, token, leftoverAmount, reason);
+                    revert JB721TiersHookLib_SplitFallbackFailed({
+                        projectId: projectId, token: token, amount: leftoverAmount, reason: reason
+                    });
                 }
             } else {
                 SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: leftoverAmount});
-                // slither-disable-next-line calls-loop
                 try terminal.addToBalanceOf({
                     projectId: projectId,
                     token: token,
@@ -785,7 +785,9 @@ library JB721TiersHookLib {
                 catch (bytes memory reason) {
                     // Reset approval on failure.
                     SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
-                    revert JB721TiersHookLib_SplitFallbackFailed(projectId, token, leftoverAmount, reason);
+                    revert JB721TiersHookLib_SplitFallbackFailed({
+                        projectId: projectId, token: token, amount: leftoverAmount, reason: reason
+                    });
                 }
             }
         }
@@ -817,11 +819,9 @@ library JB721TiersHookLib {
             if (isNativeToken) {
                 // Wrap in try-catch so a reverting hook doesn't brick all project payments.
                 // On revert, ETH stays with the caller and we return false.
-                // slither-disable-next-line calls-loop,reentrancy-no-eth,reentrancy-events
                 try split.hook.processSplitWith{value: amount}(context) {
                     return true;
                 } catch (bytes memory reason) {
-                    // slither-disable-next-line reentrancy-events
                     emit SplitPayoutReverted({
                         projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
                     });
@@ -834,10 +834,8 @@ library JB721TiersHookLib {
                 // cause the caller to skip subtracting this amount from leftoverAmount, leading
                 // to a double-spend when the leftover is later sent to the project's balance.
                 SafeERC20.safeTransfer({token: IERC20(token), to: address(split.hook), value: amount});
-                // slither-disable-next-line calls-loop,reentrancy-no-eth,reentrancy-events
                 try split.hook.processSplitWith(context) {}
                 catch (bytes memory reason) {
-                    // slither-disable-next-line reentrancy-events
                     emit SplitPayoutReverted({
                         projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
                     });
@@ -845,14 +843,12 @@ library JB721TiersHookLib {
                 return true;
             }
         } else if (split.projectId != 0) {
-            // slither-disable-next-line calls-loop
             IJBTerminal terminal = directory.primaryTerminalOf({projectId: split.projectId, token: token});
             if (address(terminal) == address(0)) return false;
 
             // Wrap terminal calls in try-catch to prevent a failing terminal from bricking payments.
             if (split.preferAddToBalance) {
                 if (isNativeToken) {
-                    // slither-disable-next-line arbitrary-send-eth,calls-loop,reentrancy-no-eth,reentrancy-events
                     try terminal.addToBalanceOf{value: amount}({
                         projectId: split.projectId,
                         token: token,
@@ -863,7 +859,6 @@ library JB721TiersHookLib {
                     }) {
                         return true;
                     } catch (bytes memory reason) {
-                        // slither-disable-next-line reentrancy-events
                         emit SplitPayoutReverted({
                             projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
                         });
@@ -871,7 +866,6 @@ library JB721TiersHookLib {
                     }
                 } else {
                     SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
-                    // slither-disable-next-line calls-loop,reentrancy-no-eth,reentrancy-events
                     try terminal.addToBalanceOf({
                         projectId: split.projectId,
                         token: token,
@@ -884,7 +878,6 @@ library JB721TiersHookLib {
                     } catch (bytes memory reason) {
                         // Reset approval on failure so tokens aren't left approved to the terminal.
                         SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
-                        // slither-disable-next-line reentrancy-events
                         emit SplitPayoutReverted({
                             projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
                         });
@@ -893,7 +886,6 @@ library JB721TiersHookLib {
                 }
             } else {
                 if (isNativeToken) {
-                    // slither-disable-next-line arbitrary-send-eth,unused-return,calls-loop,reentrancy-events
                     try terminal.pay{value: amount}({
                         projectId: split.projectId,
                         token: token,
@@ -905,7 +897,6 @@ library JB721TiersHookLib {
                     }) {
                         return true;
                     } catch (bytes memory reason) {
-                        // slither-disable-next-line reentrancy-events
                         emit SplitPayoutReverted({
                             projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
                         });
@@ -913,7 +904,6 @@ library JB721TiersHookLib {
                     }
                 } else {
                     SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
-                    // slither-disable-next-line unused-return,calls-loop,reentrancy-no-eth,reentrancy-events
                     try terminal.pay({
                         projectId: split.projectId,
                         token: token,
@@ -927,7 +917,6 @@ library JB721TiersHookLib {
                     } catch (bytes memory reason) {
                         // Reset approval on failure so tokens aren't left approved to the terminal.
                         SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
-                        // slither-disable-next-line reentrancy-events
                         emit SplitPayoutReverted({
                             projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
                         });
@@ -937,7 +926,6 @@ library JB721TiersHookLib {
             }
         } else if (split.beneficiary != address(0)) {
             if (isNativeToken) {
-                // slither-disable-next-line arbitrary-send-eth,calls-loop
                 (bool success,) = split.beneficiary.call{value: amount}("");
                 if (!success) return false;
             } else {
@@ -945,7 +933,6 @@ library JB721TiersHookLib {
                 // false on failure instead of reverting. This handles non-standard tokens (e.g. USDT)
                 // that return void, while routing failed transfers to the project's balance instead
                 // of bricking all payments.
-                // slither-disable-next-line calls-loop
                 (bool callSuccess, bytes memory returndata) =
                     address(token).call(abi.encodeCall(IERC20.transfer, (split.beneficiary, amount)));
                 if (!callSuccess || (returndata.length != 0 && !abi.decode(returndata, (bool)))) return false;

package/src/libraries/JBBitmap.sol

@@ -32,7 +32,7 @@ library JBBitmap {
     /// @dev The `index` is the index that the bit would have if the bitmap were reshaped to a 1*n matrix.
     function isTierIdRemoved(mapping(uint256 => uint256) storage self, uint256 index) internal view returns (bool) {
         uint256 depth = _retrieveDepth(index);
-        return isTierIdRemoved(JBBitmapWord({currentWord: self[depth], currentDepth: depth}), index);
+        return isTierIdRemoved({self: JBBitmapWord({currentWord: self[depth], currentDepth: depth}), index: index});
     }
 
     /// @notice Set the bit at the given index to true, indicating that the corresponding tier has been removed.

package/src/structs/JBPayDataHookRulesetMetadata.sol

@@ -22,8 +22,8 @@ pragma solidity ^0.8.0;
 /// @custom:member allowAddPriceFeed A flag indicating if a project can add new price feeds to calculate exchange rates
 /// between its tokens.
 /// @custom:member holdFees A flag indicating if fees should be held during this ruleset.
-/// @custom:member useTotalSurplusForCashOut A flag indicating if cash outs should use the project's balance held
-/// in all terminals instead of the project's local terminal balance from which the cash out is fulfilled.
+/// @custom:member scopeCashOutsToLocalBalances A flag indicating if omnichain cash-out calculations should use only
+/// the local chain's terminal balance instead of the project's balance held in all terminals.
 /// @custom:member useDataHookForCashOuts A flag indicating if the data hook should be used for cash out transactions
 /// during
 /// this ruleset.
@@ -43,7 +43,7 @@ struct JBPayDataHookRulesetMetadata {
     bool allowAddPriceFeed;
     bool ownerMustSendPayouts;
     bool holdFees;
-    bool useTotalSurplusForCashOuts;
+    bool scopeCashOutsToLocalBalances;
     bool useDataHookForCashOut;
     uint16 metadata;
 }

package/test/utils/UnitTestSetup.sol

@@ -223,7 +223,7 @@ contract UnitTestSetup is Test {
                             allowAddPriceFeed: false,
                             ownerMustSendPayouts: false,
                             holdFees: false,
-                            useTotalSurplusForCashOuts: false,
+                            scopeCashOutsToLocalBalances: true,
                             useDataHookForPay: true,
                             useDataHookForCashOut: true,
                             dataHook: address(0),
@@ -772,7 +772,7 @@ contract UnitTestSetup is Test {
             allowAddAccountingContext: false,
             allowAddPriceFeed: false,
             holdFees: false,
-            useTotalSurplusForCashOuts: false,
+            scopeCashOutsToLocalBalances: true,
             useDataHookForCashOut: false,
             metadata: 0x00
         });