@bananapus/721-hook-v6 0.0.43 → 0.0.46

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.43",
+  "version": "0.0.46",
   "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

@@ -23,8 +23,8 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error JB721Checkpoints_AlreadyInitialized();
-    error JB721Checkpoints_Unauthorized();
+    error JB721Checkpoints_AlreadyInitialized(address hook);
+    error JB721Checkpoints_Unauthorized(address caller, address hook);
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -68,9 +68,8 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @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;
     }
 
@@ -78,13 +77,12 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @dev Only callable by the HOOK. Looks up the token's tier voting units from the store.
     /// @param from The previous owner (address(0) on mint).
     /// @param to The new owner (address(0) on burn).
-    /// @param tokenId The token ID being transferred.
+    /// @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)});
         }
 

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 ---------------- //
@@ -151,18 +149,19 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice The first owner of an NFT.
-    /// @dev This is generally the address which paid for the NFT.
-    /// @param tokenId The token ID of the NFT to get the first owner of.
+    /// @notice The address that originally received an NFT (typically the payer). Tracked separately from the current
+    /// owner so it persists through transfers, useful for provenance and historical voting checkpoints.
+    /// @param tokenId The token ID of the NFT.
     /// @return The address of the NFT's first owner.
     function firstOwnerOf(uint256 tokenId) external view override returns (address) {
         address first = _firstOwnerOf[tokenId];
         return first != address(0) ? first : _ownerOf(tokenId);
     }
 
-    /// @notice Context for the pricing of this hook's tiers.
+    /// @notice The currency and decimal precision used for this hook's tier prices. For example, if tiers are priced
+    /// in ETH with 18 decimals, `currency` would be the ETH currency ID and `decimals` would be 18.
     /// @return currency The currency used for tier prices.
-    /// @return decimals The amount of decimals being used in tier prices.
+    /// @return decimals The number of decimals used in tier prices.
     function pricingContext() external view override returns (uint256 currency, uint256 decimals) {
         // Get a reference to the packed pricing context.
         uint256 packed = _packedPricingContext;
@@ -185,12 +184,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         return STORE.balanceOf({hook: address(this), owner: owner});
     }
 
-    /// @notice The data calculated before a payment is recorded in the terminal store.
-    /// @dev Overrides the base to calculate the split amount to forward based on tier split percentages.
-    /// @param context The payment context.
-    /// @return weight The weight to use for token minting, adjusted down when tier splits route funds away from the
-    /// project (unless `issueTokensForSplits` is set).
-    /// @return hookSpecifications The hook specifications, with the split amount to forward.
+    /// @notice Called by the terminal before recording a payment. Calculates how much of the payment should be routed
+    /// to tier-based splits vs. kept by the project, and adjusts the minting weight accordingly.
+    /// @dev Overrides the base to compute tier split amounts from each tier's `splitPercent`.
+    /// @param context The payment context from the terminal.
+    /// @return weight The adjusted weight for project token minting (reduced when splits route funds away).
+    /// @return hookSpecifications Specifies this hook as the pay hook, with the split amount to forward.
     function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
         public
         view
@@ -222,17 +221,20 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         });
     }
 
-    /// @notice The combined cash out weight of the NFTs with the specified token IDs.
-    /// @dev An NFT's cash out weight is its price.
-    /// @dev To get their relative cash out weight, divide the result by the `totalCashOutWeight(...)`.
-    /// @param tokenIds The token IDs of the NFTs to get the cumulative cash out weight of.
-    /// @return weight The cash out weight of the tokenIds.
+    /// @notice The combined cash-out weight of specific NFTs. Divide by `totalCashOutWeight()` to get the fraction of
+    /// surplus these NFTs can reclaim. Weight is based on the original tier price, not any discount paid.
+    /// @param tokenIds The token IDs of the NFTs to get the combined cash-out weight of.
+    /// @return weight The combined cash-out weight.
     function cashOutWeightOf(uint256[] memory tokenIds) public view virtual override returns (uint256) {
         return STORE.cashOutWeightOf({hook: address(this), tokenIds: tokenIds});
     }
 
-    /// @notice Initializes a cloned copy of the original hook contract.
-    /// @param projectId The ID of the project this this hook is associated with.
+    /// @notice Initialize a cloned copy of the hook. Sets the project association, ERC-721 name/symbol, pricing
+    /// context (currency + decimals), metadata URIs, initial tiers, and behavioral flags. Can only be called once
+    /// per clone — the implementation contract is pre-initialized in its constructor to prevent misuse.
+    /// @dev Called by `JB721TiersHookDeployer` immediately after cloning. Reverts with
+    /// `JB721TiersHook_AlreadyInitialized` if called more than once, or `JB721TiersHook_NoProjectId` if projectId is 0.
+    /// @param projectId The ID of the project this hook is associated with.
     /// @param name The name of the NFT collection.
     /// @param symbol The symbol representing the NFT collection.
     /// @param baseUri The URI to use as a base for full NFT `tokenUri`s.
@@ -260,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});
@@ -275,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.
@@ -328,9 +329,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         return JB721TiersHookLib.resolveTokenURI(STORE, address(this), baseURI, tokenId);
     }
 
-    /// @notice The combined cash out weight of all outstanding NFTs.
-    /// @dev An NFT's cash out weight is its price.
-    /// @return weight The total cash out weight.
+    /// @notice The total cash-out weight across all outstanding NFTs and pending reserves. This is the denominator
+    /// for cash-out calculations — an NFT's share of the surplus is its weight divided by this total.
+    /// @return weight The total cash-out weight.
     function totalCashOutWeight() public view virtual override returns (uint256) {
         return STORE.totalCashOutWeight(address(this));
     }
@@ -339,12 +340,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Add or delete tiers.
-    /// @dev Only the contract's owner or an operator with the `ADJUST_TIERS` permission from the owner can adjust the
-    /// tiers.
-    /// @dev Any added tiers must adhere to this hook's `JB721TiersHookFlags`.
-    /// @param tiersToAdd The tiers to add, as an array of `JB721TierConfig` structs`.
-    /// @param tierIdsToRemove The tiers to remove, as an array of tier IDs.
+    /// @notice Add new NFT tiers or remove existing ones. Added tiers get sequential IDs and must be sorted by
+    /// category. Removed tiers stop accepting new mints but existing NFTs remain valid.
+    /// @dev Only the collection owner or an operator with `ADJUST_721_TIERS` permission can call this.
+    /// @dev Added tiers must respect this hook's flags (e.g. `noNewTiersWithVotes`, `noNewTiersWithReserves`).
+    /// @param tiersToAdd The tiers to add, as an array of `JB721TierConfig` structs.
+    /// @param tierIdsToRemove The IDs of the tiers to remove.
     function adjustTiers(JB721TierConfig[] calldata tiersToAdd, uint256[] calldata tierIdsToRemove) external override {
         // Enforce permissions.
         _requirePermissionFrom({
@@ -363,9 +364,11 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         });
     }
 
-    /// @notice Manually mint NFTs from the provided tiers .
+    /// @notice Manually mint NFTs from specific tiers to a beneficiary, without requiring payment. Only tiers with
+    /// `allowOwnerMint` enabled can be minted this way.
+    /// @dev Only the collection owner or an operator with `MINT_721` permission can call this.
     /// @param tierIds The IDs of the tiers to mint from.
-    /// @param beneficiary The address to mint to.
+    /// @param beneficiary The address to mint the NFTs to.
     /// @return tokenIds The IDs of the newly minted tokens.
     function mintFor(
         uint16[] calldata tierIds,
@@ -379,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,
@@ -389,9 +391,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         _mintTokens({tokenIds: tokenIds, tierIds: tierIds, beneficiary: beneficiary, totalAmountPaid: 0});
     }
 
-    /// @notice Mint pending reserved NFTs based on the provided information.
-    /// @dev "Pending" means that the NFTs have been reserved, but have not been minted yet.
-    /// @param reserveMintConfigs Contains information about how many reserved tokens to mint for each tier.
+    /// @notice Mint pending reserved NFTs across multiple tiers in a single call. Reserves accumulate automatically
+    /// as NFTs are sold (based on each tier's `reserveFrequency`) and anyone can trigger their minting.
+    /// @param reserveMintConfigs The tier IDs and counts specifying how many reserves to mint from each tier.
     function mintPendingReservesFor(JB721TiersMintReservesConfig[] calldata reserveMintConfigs) external override {
         for (uint256 i; i < reserveMintConfigs.length;) {
             // Get a reference to the params being iterated upon.
@@ -406,12 +408,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         }
     }
 
-    /// @notice Allows the collection's owner to set the discount for a tier, if the tier allows it.
-    /// @dev Only the contract's owner or an operator with the `SET_721_DISCOUNT_PERCENT` permission from the owner can
-    /// adjust the
-    /// tiers.
+    /// @notice Set a discount on a tier's price. Discounts reduce the price payers must pay, but don't affect the
+    /// NFT's cash-out weight (which always uses the original price). The tier must have `cannotIncreaseDiscountPercent`
+    /// set appropriately.
+    /// @dev Only the collection owner or an operator with `SET_721_DISCOUNT_PERCENT` permission can call this.
     /// @param tierId The ID of the tier to set the discount of.
-    /// @param discountPercent The discount percent to set.
+    /// @param discountPercent The discount percent to set (0–100).
     function setDiscountPercentOf(uint256 tierId, uint256 discountPercent) external override {
         // Enforce permissions.
         _requirePermissionFrom({
@@ -420,8 +422,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         _setDiscountPercentOf({tierId: tierId, discountPercent: discountPercent});
     }
 
-    /// @notice Allows the collection's owner to set the discount percent for multiple tiers.
-    /// @param configs The configs to set the discount percent for.
+    /// @notice Set discount percentages for multiple tiers in a single call.
+    /// @dev Only the collection owner or an operator with `SET_721_DISCOUNT_PERCENT` permission can call this.
+    /// @param configs An array of tier ID + discount percent pairs to apply.
     function setDiscountPercentsOf(JB721TiersSetDiscountPercentConfig[] calldata configs) external override {
         // Enforce permissions.
         _requirePermissionFrom({
@@ -440,7 +443,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         }
     }
 
-    /// @notice Update this hook's metadata properties.
+    /// @notice Update any combination of this hook's metadata properties in a single call. Pass empty strings or
+    /// sentinel values for fields you don't want to change.
     /// @dev Only this contract's owner or an operator with the `SET_721_METADATA` permission can set the metadata.
     /// @param name The new collection name. Send empty to leave unchanged.
     /// @param symbol The new collection symbol. Send empty to leave unchanged.
@@ -495,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)) {
@@ -510,8 +513,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     // ----------------------- public transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Mint reserved pending reserved NFTs within the provided tier.
-    /// @dev "Pending" means that the NFTs have been reserved, but have not been minted yet.
+    /// @notice Mint pending reserved NFTs from a specific tier. Anyone can call this — reserves are minted to the
+    /// tier's reserve beneficiary (or the hook's default). Reverts if the ruleset has reserve minting paused.
     /// @param tierId The ID of the tier to mint reserved NFTs from.
     /// @param count The number of reserved NFTs to mint.
     function mintPendingReservesFor(uint256 tierId, uint256 count) public override {
@@ -521,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.
@@ -542,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 {
@@ -564,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);
     }
 
@@ -591,11 +590,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         STORE.recordBurn(tokenIds);
     }
 
-    /// @notice Mints NFTs and emits events for each.
-    /// @param tokenIds The token IDs to mint.
-    /// @param tierIds The tier IDs corresponding to each token.
+    /// @notice Mint a batch of NFTs to the beneficiary and emit a `Mint` event for each. Called after the store has
+    /// recorded the mint and generated token IDs.
+    /// @param tokenIds The token IDs to mint (generated by the store based on tier and sequence number).
+    /// @param tierIds The tier IDs corresponding to each token (same length and order as `tokenIds`).
     /// @param beneficiary The address receiving the NFTs.
-    /// @param totalAmountPaid The amount to report in the Mint event.
+    /// @param totalAmountPaid The total payment amount (including credits) to report in the Mint event for indexing.
     function _mintTokens(
         uint256[] memory tokenIds,
         uint16[] memory tierIds,
@@ -616,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 {
@@ -656,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
             });
@@ -680,7 +678,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 });
             }
 
-            // slither-disable-next-line reentrancy-no-eth
             payCreditsOf[beneficiary] = newPayCredits;
         }
     }
@@ -735,30 +732,29 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         }
     }
 
-    /// @notice Record the setting of a new token URI resolver.
-    /// @param tokenUriResolver The new token URI resolver.
+    /// @notice Emit the `SetTokenUriResolver` event and persist the new resolver in the store. Pass `address(0)` to
+    /// clear the resolver and fall back to the default IPFS-based URI.
+    /// @param tokenUriResolver The new token URI resolver (or address(0) to clear).
     function _recordSetTokenUriResolver(IJB721TokenUriResolver tokenUriResolver) internal {
         emit SetTokenUriResolver({resolver: tokenUriResolver, caller: _msgSender()});
 
         STORE.recordSetTokenUriResolver(tokenUriResolver);
     }
 
-    /// @notice Internal function to set the discount percent for a tier.
+    /// @notice Delegate discount percent storage to the library, which validates and records it in the store.
     /// @param tierId The ID of the tier to set the discount percent for.
-    /// @param discountPercent The discount percent to set for the tier.
+    /// @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()
         });
     }
 
     /// @notice Before transferring an NFT, register its first owner (if necessary).
-    /// @param to The address the NFT is being transferred to.
-    /// @param tokenId The token ID of the NFT being transferred.
+    /// @param to The address to transfer the NFT to.
+    /// @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});
 
@@ -778,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

@@ -13,7 +13,9 @@ import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 import {JBDeploy721TiersHookConfig} from "./structs/JBDeploy721TiersHookConfig.sol";
 
 /// @title JB721TiersHookDeployer
-/// @notice Deploys a `JB721TiersHook` for an existing project.
+/// @notice Factory that deploys EIP-1167 clones of `JB721TiersHook` for existing projects. Each clone is initialized
+/// with its own tiers, metadata, and flags, then ownership is transferred to the caller. The deployed hook is
+/// registered in the `IJBAddressRegistry` for cross-chain address verification.
 contract JB721TiersHookDeployer is ERC2771Context, IJB721TiersHookDeployer {
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -22,7 +24,7 @@ contract JB721TiersHookDeployer is ERC2771Context, IJB721TiersHookDeployer {
     /// @notice A registry which stores references to contracts and their deployers.
     IJBAddressRegistry public immutable ADDRESS_REGISTRY;
 
-    /// @notice A 721 tiers hook.
+    /// @notice The reference 721 tiers hook implementation that gets cloned for each new deployment.
     JB721TiersHook public immutable HOOK;
 
     /// @notice The contract that stores and manages data for this contract's NFTs.
@@ -60,10 +62,11 @@ contract JB721TiersHookDeployer is ERC2771Context, IJB721TiersHookDeployer {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Deploys a 721 tiers hook for the specified project.
+    /// @notice Deploy a new 721 tiers hook for a project. Clones the implementation, initializes it with the provided
+    /// tiers and flags, transfers ownership to the caller, and registers the hook in the address registry.
     /// @param projectId The ID of the project to deploy the hook for.
-    /// @param deployTiersHookConfig The config to deploy the hook with, which determines its behavior.
-    /// @param salt A salt to use for the deterministic deployment.
+    /// @param deployTiersHookConfig The tiers, metadata, and flags to initialize the hook with.
+    /// @param salt A salt for deterministic (CREATE2) deployment. Pass `bytes32(0)` for non-deterministic deployment.
     /// @return newHook The address of the newly deployed hook.
     function deployHookFor(
         uint256 projectId,
@@ -100,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.