@bananapus/721-hook-v6 0.0.43 → 0.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JB721Checkpoints.sol

@@ -78,7 +78,7 @@ 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();
 

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,
@@ -735,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({
@@ -754,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

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,

package/src/JB721TiersHookProjectDeployer.sol

@@ -24,8 +24,9 @@ import {JBPayDataHookRulesetConfig} from "./structs/JBPayDataHookRulesetConfig.s
 import {JBQueueRulesetsConfig} from "./structs/JBQueueRulesetsConfig.sol";
 
 /// @title JB721TiersHookProjectDeployer
-/// @notice Deploys a project and a 721 tiers hook for it. Can be used to queue rulesets for the project if given
-/// `JBPermissionIds.QUEUE_RULESETS` or `JBPermissionIds.LAUNCH_RULESETS`.
+/// @notice All-in-one deployer that creates a Juicebox project, deploys a 721 tiers hook, and configures its
+/// rulesets in a single transaction. Can also attach a hook to an existing project by launching or queuing rulesets
+/// with `LAUNCH_RULESETS` or `QUEUE_RULESETS` permission.
 contract JB721TiersHookProjectDeployer is
     ERC2771Context,
     JBPermissioned,
@@ -39,7 +40,7 @@ contract JB721TiersHookProjectDeployer is
     /// @notice The directory of terminals and controllers for projects.
     IJBDirectory public immutable override DIRECTORY;
 
-    /// @notice The 721 tiers hook deployer.
+    /// @notice The deployer contract used to create new 721 tiers hook instances via clone.
     IJB721TiersHookDeployer public immutable override HOOK_DEPLOYER;
 
     //*********************************************************************//
@@ -70,9 +71,8 @@ contract JB721TiersHookProjectDeployer is
     /// @notice Launches a new project with a 721 tiers hook attached.
     /// @param owner The address to set as the owner of the project. The ERC-721 which confers this project's ownership
     /// will be sent to this address.
-    /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook which is being
-    /// deployed.
-    /// @param launchProjectConfig Configuration which dictates the behavior of the project which is being launched.
+    /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook to deploy.
+    /// @param launchProjectConfig Configuration which dictates the behavior of the project to launch.
     /// @param controller The controller that the project's rulesets will be queued with.
     /// @param salt A salt to use for the deterministic deployment.
     /// @return projectId The ID of the newly launched project.
@@ -114,9 +114,8 @@ contract JB721TiersHookProjectDeployer is
     /// @notice Launches rulesets for a project with an attached 721 tiers hook.
     /// @dev Only a project's owner or an operator with the `LAUNCH_RULESETS & SET_TERMINALS` permission can launch its
     /// rulesets.
-    /// @param projectId The ID of the project that rulesets are being launched for.
-    /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook which is being
-    /// deployed.
+    /// @param projectId The ID of the project to launch rulesets for.
+    /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook to deploy.
     /// @param launchRulesetsConfig Configuration which dictates the project's new rulesets.
     /// @param projectUri Metadata URI to associate with the project. Pass an empty string to leave it unchanged.
     /// @param controller The controller that the project's rulesets will be queued with.
@@ -176,9 +175,8 @@ contract JB721TiersHookProjectDeployer is
 
     /// @notice Queues rulesets for a project with an attached 721 tiers hook.
     /// @dev Only a project's owner or an operator with the `QUEUE_RULESETS` permission can queue its rulesets.
-    /// @param projectId The ID of the project that rulesets are being queued for.
-    /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook which is being
-    /// deployed.
+    /// @param projectId The ID of the project to queue rulesets for.
+    /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook to deploy.
     /// @param queueRulesetsConfig Configuration which dictates the project's newly queued rulesets.
     /// @param controller The controller that the project's rulesets will be queued with.
     /// @param salt A salt to use for the deterministic deployment.
@@ -232,9 +230,11 @@ contract JB721TiersHookProjectDeployer is
     // ----------------------- internal helpers -------------------------- //
     //*********************************************************************//
 
-    /// @notice Launches a project.
+    /// @notice Configure and launch rulesets for a newly created project. Converts `JBPayDataHookRulesetConfig` entries
+    /// into standard `JBRulesetConfig` entries with `useDataHookForPay` forced to `true` and the deployed hook set as
+    /// the data hook.
     /// @param projectId The ID of the reserved project.
-    /// @param launchProjectConfig Configuration which dictates the behavior of the project which is being launched.
+    /// @param launchProjectConfig Configuration which dictates the behavior of the project to launch.
     /// @param dataHook The data hook to use for the project.
     /// @param controller The controller that the project's rulesets will be queued with.
     function _launchProjectFor(
@@ -302,7 +302,8 @@ contract JB721TiersHookProjectDeployer is
         });
     }
 
-    /// @notice Launches rulesets for a project.
+    /// @notice Launch rulesets for an existing project. Same conversion logic as `_launchProjectFor` — each
+    /// `JBPayDataHookRulesetConfig` is transformed into a `JBRulesetConfig` with the hook wired as the data hook.
     /// @param projectId The ID of the project to launch rulesets for.
     /// @param launchRulesetsConfig Configuration which dictates the behavior of the project's rulesets.
     /// @param projectUri Metadata URI to associate with the project. Pass an empty string to leave it unchanged.
@@ -377,7 +378,9 @@ contract JB721TiersHookProjectDeployer is
         return rulesetId;
     }
 
-    /// @notice Queues rulesets for a project.
+    /// @notice Queue future rulesets for an existing project. Same conversion logic as the launch functions — each
+    /// `JBPayDataHookRulesetConfig` is transformed into a `JBRulesetConfig` with the hook wired as the data hook.
+    /// Queued rulesets take effect after the current ruleset expires.
     /// @param projectId The ID of the project to queue rulesets for.
     /// @param queueRulesetsConfig Configuration which dictates the behavior of the project's rulesets.
     /// @param dataHook The data hook to use for the project.

package/src/JB721TiersHookStore.sol

@@ -16,7 +16,11 @@ import {JBBitmapWord} from "./structs/JBBitmapWord.sol";
 import {JBStored721Tier} from "./structs/JBStored721Tier.sol";
 
 /// @title JB721TiersHookStore
-/// @notice This contract stores and manages data for many `IJB721TiersHook`s and their NFTs.
+/// @notice The shared data store for all `JB721TiersHook` instances. Stores tier definitions, mint counts, reserve
+/// tracking, voting units, and removal bitmaps. Each hook registers its own tiers here; the store handles
+/// tier validation, minting logic (including reserve accounting), and cash-out weight calculations.
+/// @dev One store is shared across all hooks. Functions are keyed by hook address so each hook reads/writes
+/// only its own data. Tier IDs are sequential per hook and 1-indexed.
 contract JB721TiersHookStore is IJB721TiersHookStore {
     using JBBitmap for mapping(uint256 => uint256);
     using JBBitmap for JBBitmapWord;
@@ -155,48 +159,50 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Resolves the encoded IPFS URI for the tier of the 721 with the provided token ID from the provided 721
-    /// contract.
-    /// @param hook The 721 contract that the encoded IPFS URI belongs to.
-    /// @param tokenId The token ID of the 721 to get the encoded tier IPFS URI of.
-    /// @return The encoded IPFS URI.
+    /// @notice Get the encoded IPFS URI for the tier that a specific NFT belongs to. Used to resolve the NFT's
+    /// metadata when no custom `tokenUriResolver` is set.
+    /// @param hook The 721 hook contract the NFT belongs to.
+    /// @param tokenId The token ID of the NFT.
+    /// @return The encoded IPFS URI for the NFT's tier.
     // forge-lint: disable-next-line(mixed-case-function)
     function encodedTierIPFSUriOf(address hook, uint256 tokenId) external view override returns (bytes32) {
         return encodedIPFSUriOf[hook][tierIdOfToken(tokenId)];
     }
 
-    /// @notice Get the flags that dictate the behavior of the provided 721 contract.
-    /// @param hook The 721 contract to get the flags of.
-    /// @return The flags.
+    /// @notice Get the behavioral flags for a hook — such as whether transfers are pausable, whether NFT holders can
+    /// cash out, and whether token issuance occurs for split-routed payments.
+    /// @param hook The 721 hook contract to get the flags of.
+    /// @return The hook's flags.
     function flagsOf(address hook) external view override returns (JB721TiersHookFlags memory) {
         return _flagsOf[hook];
     }
 
-    /// @notice Check if the provided tier has been removed from the provided 721 contract.
-    /// @param hook The 721 contract the tier belongs to.
-    /// @param tierId The ID of the tier to check the removal status of.
-    /// @return A bool which is `true` if the tier has been removed, and `false` otherwise.
+    /// @notice Check whether a tier has been removed. Removed tiers can no longer be minted from, but existing NFTs
+    /// from that tier remain valid and can still be cashed out.
+    /// @param hook The 721 hook contract the tier belongs to.
+    /// @param tierId The ID of the tier to check.
+    /// @return `true` if the tier has been removed, `false` otherwise.
     function isTierRemoved(address hook, uint256 tierId) external view override returns (bool) {
         JBBitmapWord memory bitmapWord = _removedTiersBitmapWordOf[hook].readId(tierId);
 
         return bitmapWord.isTierIdRemoved(tierId);
     }
 
-    /// @notice Get the number of pending reserve NFTs for the provided tier ID of the provided 721 contract.
-    /// @dev "Pending" means that the NFTs have been reserved, but have not been minted yet.
-    /// @param hook The 721 contract to check for pending reserved NFTs.
-    /// @param tierId The ID of the tier to get the number of pending reserves for.
-    /// @return The number of pending reserved NFTs.
+    /// @notice How many reserved NFTs are waiting to be minted for a tier. Reserves accumulate automatically as
+    /// non-reserve NFTs are minted (based on the tier's `reserveFrequency`). Anyone can mint them via
+    /// `mintPendingReservesFor`.
+    /// @param hook The 721 hook contract to check.
+    /// @param tierId The ID of the tier to check.
+    /// @return The number of pending reserved NFTs that can be minted.
     function numberOfPendingReservesFor(address hook, uint256 tierId) external view override returns (uint256) {
         return _numberOfPendingReservesFor({hook: hook, tierId: tierId, storedTier: _storedTierOf[hook][tierId]});
     }
 
-    /// @notice Get the tier of the 721 with the provided token ID in the provided 721 contract.
-    /// @param hook The 721 contract that the tier belongs to.
-    /// @param tokenId The token ID of the 721 to get the tier of.
-    /// @param includeResolvedUri If set to `true`, if the contract has a token URI resolver, its content will be
-    /// resolved and included.
-    /// @return The tier.
+    /// @notice Look up which tier an NFT belongs to and return the full tier details (price, supply, metadata, etc.).
+    /// @param hook The 721 hook contract the NFT belongs to.
+    /// @param tokenId The token ID of the NFT.
+    /// @param includeResolvedUri If `true` and the hook has a `tokenUriResolver`, resolves the URI and includes it.
+    /// @return The tier that the NFT belongs to.
     function tierOfTokenId(
         address hook,
         uint256 tokenId,
@@ -255,14 +261,14 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         transfersPausable = (storedTier.packedBools & 0x2) != 0;
     }
 
-    /// @notice Gets an array of currently active 721 tiers for the provided 721 contract.
-    /// @param hook The 721 contract to get the tiers of.
-    /// @param categories An array tier categories to get tiers from. Send an empty array to get all categories.
-    /// @param includeResolvedUri If set to `true`, if the contract has a token URI resolver, its content will be
-    /// resolved and included.
-    /// @param startingId The ID of the first tier to get (sorted by category). Send 0 to get all active tiers.
-    /// @param size The number of tiers to include.
-    /// @return tiers An array of active 721 tiers.
+    /// @notice Get all active (non-removed) tiers for a hook, with optional filtering by category and pagination.
+    /// Tiers are returned sorted by category.
+    /// @param hook The 721 hook contract to get tiers from.
+    /// @param categories Filter to specific categories. Pass an empty array to include all categories.
+    /// @param includeResolvedUri If `true` and the hook has a `tokenUriResolver`, resolves URIs and includes them.
+    /// @param startingId Start from this tier ID (for pagination). Pass 0 to start from the beginning.
+    /// @param size The maximum number of tiers to return.
+    /// @return tiers An array of active tiers.
     function tiersOf(
         address hook,
         uint256[] calldata categories,
@@ -345,14 +351,12 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Returns the number of voting units an addresses has within the specified tier of the specified 721
-    /// contract.
-    /// @dev NFTs have a tier-specific number of voting units. If the tier does not have a custom number of voting
-    /// units, the price is used.
-    /// @param hook The 721 contract that the tier belongs to.
-    /// @param account The address to get the voting units of within the tier.
-    /// @param tierId The ID of the tier to get voting units within.
-    /// @return The address' voting units within the tier.
+    /// @notice Get an address's voting power from a specific tier. Each NFT in the tier contributes either the tier's
+    /// custom `votingUnits` (if configured) or the tier's price. Multiply by the holder's balance in the tier.
+    /// @param hook The 721 hook contract that the tier belongs to.
+    /// @param account The address to get voting units for.
+    /// @param tierId The ID of the tier.
+    /// @return The address's total voting units within the tier.
     function tierVotingUnitsOf(
         address hook,
         address account,
@@ -379,9 +383,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         return balance * (useVotingUnits ? _tierVotingUnitsOf[hook][tierId] : storedTier.price);
     }
 
-    /// @notice Get the number of NFTs which have been minted from the provided 721 contract (across all tiers).
-    /// @param hook The 721 contract to get a total supply of.
-    /// @return supply The total number of NFTs minted from all tiers on the contract.
+    /// @notice The total number of NFTs currently in circulation for a hook (minted minus burned, across all tiers).
+    /// @param hook The 721 hook contract to get the total supply of.
+    /// @return supply The total number of outstanding NFTs.
     function totalSupplyOf(address hook) external view override returns (uint256 supply) {
         // Keep a reference to the greatest tier ID.
         uint256 maxTierId = maxTierIdOf[hook];
@@ -402,13 +406,12 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Get the number of voting units the provided address has for the provided 721 contract (across all
-    /// tiers).
-    /// @dev NFTs have a tier-specific number of voting units. If the tier does not have a custom number of voting
-    /// units, the price is used.
-    /// @param hook The 721 contract to get the voting units within.
+    /// @notice Get an address's total voting power across all tiers of a hook. Sums up the voting units from every
+    /// tier where the address holds NFTs.
+    /// @dev Each tier contributes: `balance * (customVotingUnits || tierPrice)`.
+    /// @param hook The 721 hook contract to get voting units within.
     /// @param account The address to get the voting unit total of.
-    /// @return units The total voting units the address has within the 721 contract.
+    /// @return units The total voting units the address holds across all tiers.
     function votingUnitsOf(address hook, address account) external view virtual override returns (uint256 units) {
         // Keep a reference to the greatest tier ID.
         uint256 maxTierId = maxTierIdOf[hook];
@@ -446,11 +449,10 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Get the number of NFTs that the specified address has from the specified 721 contract (across all
-    /// tiers).
-    /// @param hook The 721 contract to get the balance within.
+    /// @notice How many NFTs an address owns from a hook, totaled across all tiers.
+    /// @param hook The 721 hook contract to check.
     /// @param owner The address to check the balance of.
-    /// @return balance The number of NFTs the owner has from the 721 contract.
+    /// @return balance The total number of NFTs the owner holds.
     function balanceOf(address hook, address owner) public view override returns (uint256 balance) {
         // Keep a reference to the greatest tier ID.
         uint256 maxTierId = maxTierIdOf[hook];
@@ -466,13 +468,13 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice The combined cash out weight of the NFTs with the provided token IDs.
-    /// @dev Cash out weight is based on 721 price.
-    /// @dev Divide this result by the `totalCashOutWeight` to get the portion of funds that can be reclaimed by
-    /// cashing out these NFTs.
-    /// @param hook The 721 contract that the NFTs belong to.
-    /// @param tokenIds The token IDs of the NFTs to get the cash out weight of.
-    /// @return weight The cash out weight.
+    /// @notice The combined cash-out weight of specific NFTs. Divide by `totalCashOutWeight` to get the fraction of
+    /// the project's surplus that cashing out these NFTs would reclaim.
+    /// @dev Weight is based on each NFT's original tier price (not the discounted price paid). Discounts are
+    /// transient purchase incentives and don't affect an NFT's share of the cash-out pool.
+    /// @param hook The 721 hook contract the NFTs belong to.
+    /// @param tokenIds The token IDs to get the combined cash-out weight of.
+    /// @return weight The combined cash-out weight.
     function cashOutWeightOf(address hook, uint256[] calldata tokenIds) public view override returns (uint256 weight) {
         // Add each 721's original price (from its tier) to the weight.
         // Uses the full tier price, not the discounted price — by design. Discounts are transient incentives
@@ -488,10 +490,11 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice The reserve beneficiary for the provided tier ID on the provided 721 contract.
-    /// @param hook The 721 contract that the tier belongs to.
-    /// @param tierId The ID of the tier to get the reserve beneficiary of.
-    /// @return The reserve beneficiary for the tier.
+    /// @notice The address that receives reserved NFTs for a tier. Falls back to the hook's default reserve
+    /// beneficiary if no tier-specific beneficiary is set.
+    /// @param hook The 721 hook contract.
+    /// @param tierId The ID of the tier.
+    /// @return The reserve beneficiary address for the tier.
     function reserveBeneficiaryOf(address hook, uint256 tierId) public view override returns (address) {
         // Get the stored reserve beneficiary.
         address storedReserveBeneficiaryOfTier = _reserveBeneficiaryOf[hook][tierId];
@@ -505,19 +508,18 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         return defaultReserveBeneficiaryOf[hook];
     }
 
-    /// @notice The tier ID for the 721 with the provided token ID.
-    /// @dev Tiers are 1-indexed from the `tiers` array, meaning the 0th element of the array is tier 1.
-    /// @param tokenId The token ID of the 721 to get the tier ID of.
-    /// @return The ID of the 721's tier.
+    /// @notice Derive which tier an NFT belongs to from its token ID. Token IDs encode the tier: `tokenId / 1e9`
+    /// gives the tier ID.
+    /// @param tokenId The token ID of the NFT.
+    /// @return The tier ID.
     function tierIdOfToken(uint256 tokenId) public pure override returns (uint256) {
         return tokenId / _ONE_BILLION;
     }
 
-    /// @notice Get the tier with the provided ID from the provided 721 contract.
-    /// @param hook The 721 contract to get the tier from.
+    /// @notice Get the full details of a specific tier by its ID — price, supply, reserve info, metadata, etc.
+    /// @param hook The 721 hook contract to get the tier from.
     /// @param id The ID of the tier to get.
-    /// @param includeResolvedUri If set to `true`, if the contract has a token URI resolver, its content will be
-    /// resolved and included.
+    /// @param includeResolvedUri If `true` and the hook has a `tokenUriResolver`, resolves the URI and includes it.
     /// @return The tier.
     function tierOf(address hook, uint256 id, bool includeResolvedUri) public view override returns (JB721Tier memory) {
         return _getTierFrom({
@@ -525,9 +527,10 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         });
     }
 
-    /// @notice The combined cash out weight for all NFTs from the provided 721 contract.
-    /// @param hook The 721 contract to get the total cash out weight of.
-    /// @return weight The total cash out weight.
+    /// @notice The total cash-out weight across all outstanding NFTs (including pending reserves). This is the
+    /// denominator used to determine what fraction of a project's surplus each NFT can reclaim on cash out.
+    /// @param hook The 721 hook contract to get the total cash-out weight of.
+    /// @return weight The total cash-out weight.
     // Changing defaultReserveBeneficiary retroactively affects totalCashOutWeight. By design —
     // cashOutWeight is calculated dynamically, not snapshotted. The defaultReserveBeneficiary determines which
     // tiers have pending reserves (via _numberOfPendingReservesFor), affecting the denominator. Changing it is
@@ -752,13 +755,15 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Pack five bools into a single uint8.
-    /// @param allowOwnerMint Whether or not owner minting is allowed in new tiers.
-    /// @param transfersPausable Whether or not 721 transfers can be paused.
-    /// @param useVotingUnits Whether or not custom voting unit amounts are allowed in new tiers.
-    /// @param cantBeRemoved Whether or not attempts to remove the tier will revert.
-    /// @param cantIncreaseDiscountPercent Whether or not attempts to increase the discount percent will revert.
-    /// @param cantBuyWithCredits Whether or not the tier cannot be purchased using accumulated pay credits.
+    /// @notice Pack six tier-level boolean flags into a single uint8 for compact storage in `JBStored721Tier`.
+    /// @dev Bit layout: 0=allowOwnerMint, 1=transfersPausable, 2=useVotingUnits, 3=cantBeRemoved,
+    /// 4=cantIncreaseDiscountPercent, 5=cantBuyWithCredits.
+    /// @param allowOwnerMint Whether the project owner can mint from this tier directly (without paying).
+    /// @param transfersPausable Whether transfers of NFTs from this tier can be paused by the ruleset.
+    /// @param useVotingUnits Whether this tier uses a custom voting power value instead of defaulting to its price.
+    /// @param cantBeRemoved Whether this tier is permanently locked and cannot be removed once added.
+    /// @param cantIncreaseDiscountPercent Whether the discount percent can only stay the same or decrease.
+    /// @param cantBuyWithCredits Whether this tier cannot be purchased using accumulated pay credits.
     /// @return packed The packed bools.
     function _packBools(
         bool allowOwnerMint,
@@ -782,14 +787,16 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Unpack six bools from a single uint8.
+    /// @notice Unpack six tier-level boolean flags from a single uint8 stored in `JBStored721Tier.packedBools`.
+    /// @dev Inverse of `_packBools`. Same bit layout: 0=allowOwnerMint, 1=transfersPausable, 2=useVotingUnits,
+    /// 3=cantBeRemoved, 4=cantIncreaseDiscountPercent, 5=cantBuyWithCredits.
     /// @param packed The packed bools.
-    /// @param allowOwnerMint Whether or not owner minting is allowed in new tiers.
-    /// @param transfersPausable Whether or not 721 transfers can be paused.
-    /// @param useVotingUnits Whether or not custom voting unit amounts are allowed in new tiers.
-    /// @param cantBeRemoved Whether or not the tier can be removed once added.
-    /// @param cantIncreaseDiscountPercent Whether or not the discount percent cannot be increased.
-    /// @param cantBuyWithCredits Whether or not the tier cannot be purchased using accumulated pay credits.
+    /// @param allowOwnerMint Whether the project owner can mint from this tier directly (without paying).
+    /// @param transfersPausable Whether transfers of NFTs from this tier can be paused by the ruleset.
+    /// @param useVotingUnits Whether this tier uses a custom voting power value instead of defaulting to its price.
+    /// @param cantBeRemoved Whether this tier is permanently locked and cannot be removed once added.
+    /// @param cantIncreaseDiscountPercent Whether the discount percent can only stay the same or decrease.
+    /// @param cantBuyWithCredits Whether this tier cannot be purchased using accumulated pay credits.
     function _unpackBools(uint8 packed)
         internal
         pure
@@ -816,7 +823,12 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Cleans an 721 contract's removed tiers from the tier sorting sequence.
+    /// @notice Walk through the tier sorting sequence and skip over any tiers that have been removed. This compacts
+    /// the linked list so that `tiersOf` iteration no longer visits removed tiers. Anyone can call this — it's a
+    /// maintenance operation with no access control.
+    /// @dev Call this after `recordRemoveTierIds` to keep tier iteration efficient. Without cleaning, removed tiers
+    /// remain in the linked list (they just can't be minted from). The function also updates
+    /// `_startingTierIdOfCategory` if the previous starting tier for a category was removed.
     /// @param hook The 721 contract to clean tiers for.
     function cleanTiers(address hook) external override {
         // Keep a reference to the last tier ID.
@@ -873,13 +885,16 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         emit CleanTiers({hook: hook, caller: msg.sender});
     }
 
-    /// @notice Record newly added tiers.
-    /// @dev WARNING: If any tier in `tiersToAdd` has `useReserveBeneficiaryAsDefault` set to `true`, its
+    /// @notice Validate and store new tiers for the calling hook. Each tier is assigned a sequential ID, inserted
+    /// into the category-sorted linked list, and has its reserve beneficiary, voting units, IPFS URI, and flags
+    /// persisted. Tiers must be provided sorted by category (ascending).
+    /// @dev Only callable by hook contracts (msg.sender is treated as the hook address).
+    /// WARNING: If any tier in `tiersToAdd` has `useReserveBeneficiaryAsDefault` set to `true`, its
     /// `reserveBeneficiary` will overwrite the hook's global `defaultReserveBeneficiaryOf`. This affects ALL existing
     /// tiers that do not have a tier-specific reserve beneficiary set via `_reserveBeneficiaryOf`. Callers should be
     /// aware of this side effect when using `adjustTiers` to add new tiers.
     /// @param tiersToAdd The tiers to add.
-    /// @return tierIds The IDs of the tiers being added.
+    /// @return tierIds The IDs of the tiers added.
     function recordAddTiers(JB721TierConfig[] calldata tiersToAdd)
         external
         override
@@ -1125,7 +1140,8 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         maxTierIdOf[msg.sender] = currentMaxTierIdOf + tiersToAdd.length;
     }
 
-    /// @notice Records 721 burns.
+    /// @notice Increment the burn counter for each token's tier. Does NOT affect `remainingSupply` — burned NFTs
+    /// cannot be re-minted. The burn count is used by `totalSupplyOf` to compute the circulating supply.
     /// @dev This function trusts `msg.sender` (the hook contract) to only call it after actually burning the
     /// tokens. It does not verify ownership or existence of the token IDs — the hook is responsible for
     /// performing those checks before calling this function.
@@ -1147,16 +1163,22 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Record newly set flags.
+    /// @notice Store the behavioral flags for the calling hook. These flags govern whether new tiers can have voting
+    /// units, reserves, or owner minting enabled.
+    /// @dev Only callable by hook contracts. Overwrites any previously stored flags for the caller.
     /// @param flags The flags to set.
     function recordFlags(JB721TiersHookFlags calldata flags) external override {
         _flagsOf[msg.sender] = flags;
     }
 
-    /// @notice Record 721 mints from the provided tiers.
-    /// @param amount The amount being spent on NFTs. The total price must not exceed this amount.
+    /// @notice Record paid mints: deduct each tier's (discounted) price from `amount`, decrement supply, generate
+    /// token IDs, and enforce that enough supply remains to satisfy pending reserves. Returns the leftover amount
+    /// and the total cost of credit-restricted tiers so the hook can enforce pay-credit rules.
+    /// @dev Reverts if the tier is removed, unrecognized, sold out, or its price exceeds the remaining amount.
+    /// For owner mints, the tier must have `allowOwnerMint` set.
+    /// @param amount The amount to spend on NFTs. The total price must not exceed this amount.
     /// @param tierIds The IDs of the tiers to mint from.
-    /// @param isOwnerMint A flag indicating whether this function is being directly called by the 721 contract's owner.
+    /// @param isOwnerMint A flag indicating whether the 721 contract's owner is directly calling this function.
     /// @return tokenIds The token IDs of the NFTs which were minted.
     /// @return leftoverAmount The `amount` remaining after minting.
     /// @return restrictedCost Total cost of tiers with `cantBuyWithCredits` set. The caller can use this to enforce
@@ -1252,7 +1274,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Record reserve 721 minting for the provided tier ID on the provided 721 contract.
+    /// @notice Generate token IDs for reserve NFT mints and decrement the tier's remaining supply. Reserves
+    /// accumulate as non-reserve NFTs are minted (one reserve per `reserveFrequency` mints). Reverts if `count`
+    /// exceeds the number of pending reserves.
     /// @param tierId The ID of the tier to mint reserves from.
     /// @param count The number of reserve NFTs to mint.
     /// @return tokenIds The token IDs of the reserve NFTs which were minted.
@@ -1292,10 +1316,12 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Record tiers being removed.
+    /// @notice Mark one or more tiers as removed. Removed tiers cannot be minted from, but existing NFTs from those
+    /// tiers remain valid (can still be cashed out and transferred). Pending reserves can still be minted.
     /// @dev Removing a tier only marks it in a bitmap — it does not update the sorted tier linked list.
     /// Call `cleanTiers()` after removing tiers to update the sorting sequence and prevent stale tier iteration.
-    /// @param tierIds The IDs of the tiers being removed.
+    /// Reverts if the tier has `cantBeRemoved` set, or if the tier ID is 0 or exceeds `maxTierIdOf`.
+    /// @param tierIds The IDs of the tiers to remove.
     function recordRemoveTierIds(uint256[] calldata tierIds) external override {
         for (uint256 i; i < tierIds.length;) {
             // Set the tier being iterated upon (0-indexed).
@@ -1325,9 +1351,11 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
-    /// @notice Records the setting of a discount for a tier.
+    /// @notice Update the discount percentage for a tier. Discounts reduce the price payers pay without affecting the
+    /// NFT's cash-out weight (which always uses the original price). Reverts if the tier is removed, if the percent
+    /// exceeds the denominator, or if the tier has `cantIncreaseDiscountPercent` set and the new value is higher.
     /// @param tierId The ID of the tier to record a discount for.
-    /// @param discountPercent The new discount percent being applied.
+    /// @param discountPercent The new discount percent to apply.
     function recordSetDiscountPercentOf(uint256 tierId, uint256 discountPercent) external override {
         // Make sure the tier hasn't been removed.
         JBBitmapWord memory bitmapWord = _removedTiersBitmapWordOf[msg.sender].readId(tierId);
@@ -1370,10 +1398,12 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         tokenUriResolverOf[msg.sender] = resolver;
     }
 
-    /// @notice Record an 721 transfer.
-    /// @param tierId The ID of the tier that the 721 being transferred belongs to.
-    /// @param from The address that the 721 is being transferred from.
-    /// @param to The address that the 721 is being transferred to.
+    /// @notice Update tier balance accounting when an NFT is transferred. Decrements the sender's balance and
+    /// increments the receiver's balance for the given tier. Handles mints (from == address(0)) and burns
+    /// (to == address(0)) as one-sided updates.
+    /// @param tierId The ID of the tier that the 721 to transfer belongs to.
+    /// @param from The address to transfer the 721 from.
+    /// @param to The address to transfer the 721 to.
     function recordTransferForTier(uint256 tierId, address from, address to) external override {
         // If this is not a mint,
         if (from != address(0)) {

package/src/abstract/JB721Hook.sol

@@ -20,10 +20,11 @@ import {IJB721Hook} from "../interfaces/IJB721Hook.sol";
 import {ERC721} from "./ERC721.sol";
 
 /// @title JB721Hook
-/// @notice When a project which uses this hook is paid, this hook may mint NFTs to the payer, depending on this hook's
-/// setup, the amount paid, and information specified by the payer. The project's owner can enable NFT cash outs
-/// through this hook, allowing the NFT holders to burn their NFTs to reclaim funds from the project (in proportion to
-/// the NFT's price).
+/// @notice Abstract base for Juicebox 721 hooks. Implements the pay hook and cash-out hook interfaces: when a project
+/// is paid through its terminal, this hook mints NFTs to the payer; when NFT holders cash out, this hook burns their
+/// NFTs and lets the terminal send them their share of the project's surplus (proportional to the NFT's price).
+/// @dev Subclasses (like `JB721TiersHook`) implement the actual minting logic via `_processPayment` and burn
+/// tracking via `_didBurn`.
 abstract contract JB721Hook is ERC721, IJB721Hook {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -270,7 +271,8 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         PROJECT_ID = projectId;
     }
 
-    /// @notice Process a received payment.
-    /// @param context The payment context passed in by the terminal.
+    /// @notice Process a received payment by minting NFTs and/or updating credits. Subclasses implement the
+    /// specific minting logic (e.g., tier selection, credit tracking, split distribution).
+    /// @param context The payment context passed in by the terminal (includes amount, payer, beneficiary, metadata).
     function _processPayment(JBAfterPayRecordedContext calldata context) internal virtual;
 }

package/src/interfaces/IJB721Checkpoints.sol

@@ -36,6 +36,6 @@ interface IJB721Checkpoints is IERC5805 {
     /// 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 being transferred (used to look up tier voting units).
+    /// @param tokenId The token ID to transfer (used to look up tier voting units).
     function onTransfer(address from, address to, uint256 tokenId) external;
 }

package/src/interfaces/IJB721CheckpointsDeployer.sol

@@ -6,7 +6,7 @@ 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 being deployed for.
+    /// @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.

package/src/interfaces/IJB721TiersHook.sol

@@ -21,7 +21,7 @@ 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 being sent.
+    /// @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);
@@ -108,7 +108,7 @@ interface IJB721TiersHook is IJB721Hook {
     /// project's balance.
     /// @param projectId The project ID the split belongs to.
     /// @param split The split that reverted.
-    /// @param amount The amount that was being paid out.
+    /// @param amount The amount that was paid out.
     /// @param reason The revert reason bytes.
     /// @param caller The address that called the function.
     event SplitPayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller);
@@ -142,7 +142,7 @@ interface IJB721TiersHook is IJB721Hook {
 
     /// @notice Context for the pricing of this hook's tiers.
     /// @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 returns (uint256 currency, uint256 decimals);
 
     /// @notice The checkpoint module that manages IVotes-compatible checkpointed voting power for this hook's NFTs.

package/src/interfaces/IJB721TiersHookProjectDeployer.sol

@@ -40,7 +40,7 @@ interface IJB721TiersHookProjectDeployer {
         returns (uint256 projectId, IJB721TiersHook hook);
 
     /// @notice Launches rulesets for a project with an attached 721 tiers hook.
-    /// @param projectId The ID of the project that rulesets are being launched for.
+    /// @param projectId The ID of the project to launch rulesets for.
     /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook.
     /// @param launchRulesetsConfig Configuration which dictates the project's new rulesets.
     /// @param projectUri Metadata URI to associate with the project. Pass an empty string to leave it unchanged.
@@ -60,7 +60,7 @@ interface IJB721TiersHookProjectDeployer {
         returns (uint256 rulesetId, IJB721TiersHook hook);
 
     /// @notice Queues rulesets for a project with an attached 721 tiers hook.
-    /// @param projectId The ID of the project that rulesets are being queued for.
+    /// @param projectId The ID of the project to queue rulesets for.
     /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook.
     /// @param queueRulesetsConfig Configuration which dictates the project's newly queued rulesets.
     /// @param controller The controller that the project's rulesets will be queued with.

package/src/interfaces/IJB721TiersHookStore.sol

@@ -203,19 +203,19 @@ interface IJB721TiersHookStore {
 
     /// @notice Record newly added tiers.
     /// @param tiersToAdd The tiers to add.
-    /// @return tierIds The IDs of the tiers being added.
+    /// @return tierIds The IDs of the tiers added.
     function recordAddTiers(JB721TierConfig[] calldata tiersToAdd) external returns (uint256[] memory tierIds);
 
-    /// @notice Record 721 burns.
+    /// @notice Records the burning of tiered 721 tokens, updating supply tracking for the affected tiers.
     /// @param tokenIds The token IDs of the NFTs to burn.
     function recordBurn(uint256[] calldata tokenIds) external;
 
-    /// @notice Record newly set flags.
+    /// @notice Stores updated ruleset metadata flags that control minting, transferring, and tier behavior.
     /// @param flags The flags to set.
     function recordFlags(JB721TiersHookFlags calldata flags) external;
 
     /// @notice Record 721 mints from the provided tiers.
-    /// @param amount The amount being spent on NFTs.
+    /// @param amount The amount to spend on NFTs.
     /// @param tierIds The IDs of the tiers to mint from.
     /// @param isOwnerMint Whether this is a direct owner mint.
     /// @return tokenIds The token IDs of the NFTs which were minted.
@@ -235,13 +235,13 @@ interface IJB721TiersHookStore {
     /// @return tokenIds The token IDs of the reserve NFTs which were minted.
     function recordMintReservesFor(uint256 tierId, uint256 count) external returns (uint256[] memory tokenIds);
 
-    /// @notice Record tiers being removed.
-    /// @param tierIds The IDs of the tiers being removed.
+    /// @notice Record tiers to remove.
+    /// @param tierIds The IDs of the tiers to remove.
     function recordRemoveTierIds(uint256[] calldata tierIds) external;
 
     /// @notice Record the setting of a discount for a tier.
     /// @param tierId The ID of the tier to set the discount of.
-    /// @param discountPercent The new discount percent being applied.
+    /// @param discountPercent The new discount percent to apply.
     function recordSetDiscountPercentOf(uint256 tierId, uint256 discountPercent) external;
 
     /// @notice Record a new encoded IPFS URI for a tier.
@@ -254,9 +254,9 @@ interface IJB721TiersHookStore {
     /// @param resolver The resolver to set.
     function recordSetTokenUriResolver(IJB721TokenUriResolver resolver) external;
 
-    /// @notice Record an 721 transfer.
-    /// @param tierId The ID of the tier that the 721 being transferred belongs to.
-    /// @param from The address that the 721 is being transferred from.
-    /// @param to The address that the 721 is being transferred to.
+    /// @notice Records a 721 token transfer, updating the first-owner tracking for the receiving address.
+    /// @param tierId The ID of the tier that the 721 to transfer belongs to.
+    /// @param from The address to transfer the 721 from.
+    /// @param to The address to transfer the 721 to.
     function recordTransferForTier(uint256 tierId, address from, address to) external;
 }

package/src/libraries/JB721TiersHookLib.sol

@@ -113,7 +113,7 @@ library JB721TiersHookLib {
     /// @param splits The splits contract to read tier split groups from.
     /// @param projectId The project ID of the hook.
     /// @param hookAddress The hook address (for computing split group IDs).
-    /// @param token The token being distributed.
+    /// @param token The token to distribute.
     /// @param amount The total amount to distribute.
     /// @param decimals The token decimals.
     /// @param encodedSplitData The encoded per-tier breakdown from hookMetadata.

package/src/structs/JB721TiersHookFlags.sol

@@ -8,7 +8,7 @@ pragma solidity ^0.8.0;
 /// @custom:member noNewTiersWithOwnerMinting A boolean indicating whether attempts to add new tiers with
 /// `allowOwnerMint` set to true will revert.
 /// @custom:member preventOverspending A boolean indicating whether payments attempting to spend more than the price of
-/// the NFTs being minted will revert.
+/// the NFTs to mint will revert.
 /// @custom:member issueTokensForSplits A boolean indicating whether payers receive token credit for the portion of
 /// their payment that is routed to tier splits. When false (default), weight is reduced proportionally.
 struct JB721TiersHookFlags {

package/src/structs/JBPayDataHookRulesetMetadata.sol

@@ -23,7 +23,7 @@ pragma solidity ^0.8.0;
 /// 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 being fulfilled.
+/// in all terminals instead of the project's local terminal balance from which the cash out is fulfilled.
 /// @custom:member useDataHookForCashOuts A flag indicating if the data hook should be used for cash out transactions
 /// during
 /// this ruleset.