@bananapus/721-hook-v6 0.0.42 → 0.0.45

package/foundry.lock

@@ -1,11 +1,5 @@
 {
   "lib/forge-std": {
     "rev": "77876f8a5b44b770a935621bb331660c90ac928e"
-  },
-  "lib/sphinx": {
-    "branch": {
-      "name": "v0.23.0",
-      "rev": "5fb24a825f46bd6ae0b5359fe0da1d2346126b09"
-    }
   }
-}
+}

package/foundry.toml

@@ -14,7 +14,7 @@ depth = 100
 fail_on_revert = false
 
 [lint]
-exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
+exclude_lints = ["mixed-case-variable", "pascal-case-struct"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.42",
+  "version": "0.0.45",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-721-hook-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.lock",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/",
+    "sphinx.lock",
+    "src/",
+    "test/utils/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -17,15 +28,15 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-721-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.20",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/ownable-v6": "^0.0.20",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@prb/math": "^4.1.0",
-    "solady": "^0.1.8"
+    "@bananapus/address-registry-v6": "0.0.25",
+    "@bananapus/core-v6": "^0.0.39",
+    "@bananapus/ownable-v6": "^0.0.24",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@openzeppelin/contracts": "5.6.1",
+    "@prb/math": "4.1.1",
+    "solady": "0.1.26"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/script/Deploy.s.sol

@@ -87,12 +87,12 @@ contract DeployScript is Script, Sphinx {
             (address _deployer, bool _deployerIsDeployed) = _isDeployed({
                 salt: CHECKPOINTS_DEPLOYER_SALT,
                 creationCode: type(JB721CheckpointsDeployer).creationCode,
-                arguments: ""
+                arguments: abi.encode(store)
             });
 
             // Deploy it if it has not been deployed yet.
             checkpointsDeployer = !_deployerIsDeployed
-                ? new JB721CheckpointsDeployer{salt: CHECKPOINTS_DEPLOYER_SALT}()
+                ? new JB721CheckpointsDeployer{salt: CHECKPOINTS_DEPLOYER_SALT}(store)
                 : JB721CheckpointsDeployer(_deployer);
         }
 

package/src/JB721Checkpoints.sol

@@ -1,9 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.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";
+
 import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
+import {IJB721TiersHook} from "./interfaces/IJB721TiersHook.sol";
 import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 
 /// @title JB721Checkpoints
@@ -14,6 +17,8 @@ import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 /// (`_cachedThis`) is uninitialized on clones, so `domainSeparatorV4()` always rebuilds using the clone's
 /// `address(this)` — correct behavior, tiny gas overhead.
 contract JB721Checkpoints is Votes, IJB721Checkpoints {
+    using Checkpoints for Checkpoints.Trace160;
+
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
@@ -22,55 +27,67 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     error JB721Checkpoints_Unauthorized();
 
     //*********************************************************************//
-    // --------------------- private stored properties ------------------ //
+    // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
 
-    /// @notice Whether this contract has been initialized.
-    bool private _initialized;
+    /// @notice The store that holds tier and voting data for the hook's NFTs.
+    IJB721TiersHookStore public immutable override STORE;
 
     //*********************************************************************//
-    // ---------------------- public stored properties ------------------- //
+    // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
     /// @notice The hook that this module tracks voting power for.
     address public override HOOK;
 
-    /// @notice The store that holds tier and voting data for the hook's NFTs.
-    IJB721TiersHookStore public override STORE;
+    //*********************************************************************//
+    // -------------------- internal stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice Checkpointed token owners for historical reward eligibility after first transfer.
+    /// @custom:param tokenId The token ID to get historical owner checkpoints for.
+    mapping(uint256 tokenId => Checkpoints.Trace160) internal _ownerCheckpointsOf;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @dev Parameterless. The implementation contract is initialized in the constructor to prevent direct use.
-    /// Clones are initialized via `initialize()`.
-    constructor() EIP712("JB721Checkpoints", "1") {
-        _initialized = true;
+    /// @dev The implementation contract is initialized in the constructor to prevent direct use. Clones are initialized
+    /// via `initialize()`.
+    /// @param store The store that holds tier data for each hook's NFTs.
+    constructor(IJB721TiersHookStore store) EIP712("JB721Checkpoints", "1") {
+        STORE = store;
+        HOOK = address(1);
     }
 
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Initializes a cloned module with its hook and store references.
+    /// @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.
-    /// @param store The store that holds tier data for the hook's NFTs.
-    function initialize(address hook, IJB721TiersHookStore store) external override {
-        if (_initialized) revert JB721Checkpoints_AlreadyInitialized();
-        _initialized = true;
+    function initialize(address hook) external override {
+        if (HOOK != address(0)) revert JB721Checkpoints_AlreadyInitialized();
+        // `hook` cannot be zero when called through the deployer because `msg.sender` must equal `hook`.
+        // slither-disable-next-line missing-zero-check
         HOOK = hook;
-        STORE = store;
     }
 
     /// @notice Called by the hook after every NFT transfer to update checkpointed voting power.
     /// @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 (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)});
+        }
+
         // Look up this token's tier to get its voting units.
         uint256 votingUnits = STORE.tierOfTokenId({hook: HOOK, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
 
@@ -79,7 +96,32 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     }
 
     //*********************************************************************//
-    // ------------------------ internal functions ----------------------- //
+    // ----------------------- external views ---------------------------- //
+    //*********************************************************************//
+
+    /// @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`.
+    /// @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.
+    function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view override returns (address) {
+        // forge-lint: disable-next-line(unsafe-typecast)
+        uint96 blockNumber96 = uint96(blockNumber);
+
+        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);
+        }
+
+        return address(uint160(checkpoints.upperLookupRecent(blockNumber96)));
+    }
+
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
     //*********************************************************************//
 
     /// @notice Returns the total voting units held by an account (across all tiers).

package/src/JB721CheckpointsDeployer.sol

@@ -2,6 +2,7 @@
 pragma solidity 0.8.28;
 
 import {LibClone} from "solady/src/utils/LibClone.sol";
+
 import {JB721Checkpoints} from "./JB721Checkpoints.sol";
 import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
 import {IJB721CheckpointsDeployer} from "./interfaces/IJB721CheckpointsDeployer.sol";
@@ -19,12 +20,17 @@ contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
     /// @notice The checkpoint module implementation that clones delegate to.
     address public immutable override IMPLEMENTATION;
 
+    /// @notice The store that holds tier and voting data for each hook's NFTs.
+    IJB721TiersHookStore public immutable override STORE;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    constructor() {
-        IMPLEMENTATION = address(new JB721Checkpoints());
+    /// @param store The store that holds tier data for each hook's NFTs.
+    constructor(IJB721TiersHookStore store) {
+        STORE = store;
+        IMPLEMENTATION = address(new JB721Checkpoints(store));
     }
 
     //*********************************************************************//
@@ -34,14 +40,13 @@ contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
     /// @notice Deploys a new deterministic checkpoint clone for the given hook.
     /// @dev Uses CREATE2 with the hook address as salt so the clone address is the same across chains.
     /// @param hook The hook address the module will serve.
-    /// @param store The store that holds tier data for the hook's NFTs.
     /// @return module The newly deployed and initialized checkpoint module.
-    function deploy(address hook, IJB721TiersHookStore store) external override returns (IJB721Checkpoints module) {
+    function deploy(address hook) external override returns (IJB721Checkpoints module) {
         if (msg.sender != hook) revert JB721CheckpointsDeployer_Unauthorized();
 
         module = IJB721Checkpoints(
             LibClone.cloneDeterministic({implementation: IMPLEMENTATION, salt: bytes32(uint256(uint160(hook)))})
         );
-        module.initialize({hook: hook, store: store});
+        module.initialize(hook);
     }
 }

package/src/JB721TiersHook.sol

@@ -151,18 +151,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 +186,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 +223,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.
@@ -328,9 +332,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 +343,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 +367,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,
@@ -389,9 +395,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 +412,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 +426,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 +447,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.
@@ -510,8 +518,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 {
@@ -591,11 +599,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,
@@ -656,6 +665,7 @@ 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
             });
@@ -734,17 +744,18 @@ 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({
@@ -753,8 +764,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     }
 
     /// @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
@@ -791,10 +802,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
 
         // Deploy the checkpoint module lazily on the first transfer.
         if (address(CHECKPOINTS) == address(0)) {
-            CHECKPOINTS = CHECKPOINTS_DEPLOYER.deploy({hook: address(this), store: STORE});
+            // 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,