@bananapus/721-hook-v6 0.0.17 → 0.0.19

package/ARCHITECTURE.md

@@ -4,6 +4,10 @@
 
 NFT tier system for Juicebox V6. Allows projects to attach tiered NFT minting to payments and use NFTs as cash-out hooks. Supports on-chain and off-chain metadata, category-based sorting, and configurable pricing with discounts.
 
+The design permits a high theoretical tier ceiling, but several important reads and cash-out calculations still scale
+with `maxTierId`. In practice, this should be treated as a curated-catalog hook with an explicit operating envelope,
+not as a guarantee that very large catalogs are comfortable to run on-chain.
+
 ## Contract Map
 
 ```

package/CHANGE_LOG.md

@@ -113,15 +113,27 @@ The ERC721 collection `name` and `symbol` can now be changed after initializatio
 | `_setName(string memory)` | Updates the token collection name |
 | `_setSymbol(string memory)` | Updates the token collection symbol |
 
-### 2.3 `beforePayRecordedWith` Override in `JB721TiersHook`
+### 2.3 `split.hook` Support in Tier Distribution
+
+Tier split payouts now support the `split.hook` field (`IJBSplitHook`). The distribution priority follows the same order as `JBMultiTerminal`: hook > projectId > beneficiary. In v5, tier splits did not exist. In v6, this ensures full parity with core split behavior.
+
+### 2.4 DOS Protection on Split Distribution
+
+All external calls during tier split distribution (split hooks, terminal `pay`/`addToBalanceOf`, and leftover distribution) are wrapped in try-catch. A reverting split recipient or terminal cannot brick payments to the project. On failure, funds are returned to the project balance and a `SplitPayoutReverted` or `AddToBalanceReverted` event is emitted with the revert reason. For ERC-20 split hook failures, tokens are transferred first and the hook callback is best-effort; for ERC-20 terminal failures, the approval is reset to zero.
+
+### 2.5 `splitPercent` Bounds Validation
+
+`JB721TiersHookStore.recordAddTiers` now validates that each tier's `splitPercent` does not exceed `JBConstants.SPLITS_TOTAL_PERCENT`. If it does, it reverts with `JB721TiersHookStore_SplitPercentExceedsBounds(uint256 percent, uint256 limit)`.
+
+### 2.6 `beforePayRecordedWith` Override in `JB721TiersHook`
 
 v6 overrides `beforePayRecordedWith` in `JB721TiersHook` (not just the base `JB721Hook`). The override calculates per-tier split amounts and adjusts the minting weight so the terminal only mints project tokens for the portion of the payment that actually enters the project. It also sets the `JBPayHookSpecification.amount` to the total split amount so the terminal forwards those funds to the hook for distribution.
 
-### 2.4 Pricing Decimals Validation
+### 2.7 Pricing Decimals Validation
 
 `initialize(...)` now reverts with `JB721TiersHook_InvalidPricingDecimals` if `tiersConfig.decimals > 18`.
 
-### 2.5 `allowSetCustomToken` Pass-Through
+### 2.8 `allowSetCustomToken` Pass-Through
 
 The `JBPayDataHookRulesetMetadata` struct gained an `allowSetCustomToken` field. In v5, the project deployer hardcoded this to `false`. In v6, it passes through the value from the config.
 
@@ -133,8 +145,10 @@ The `JBPayDataHookRulesetMetadata` struct gained an `allowSetCustomToken` field.
 
 | Event | Signature | Description |
 |-------|-----------|-------------|
+| `AddToBalanceReverted` | `AddToBalanceReverted(uint256 indexed projectId, address token, uint256 amount, bytes reason)` | Emitted when leftover distribution's `addToBalanceOf` call fails. Funds remain in the hook contract. |
 | `SetName` | `SetName(string indexed name, address caller)` | Emitted when the collection name is changed |
 | `SetSymbol` | `SetSymbol(string indexed symbol, address caller)` | Emitted when the collection symbol is changed |
+| `SplitPayoutReverted` | `SplitPayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller)` | Emitted when a split payout reverts during distribution. The failed split's funds route to the project balance. |
 
 ### 3.2 New Event on `IJB721TiersHookStore`
 
@@ -144,7 +158,7 @@ The `JBPayDataHookRulesetMetadata` struct gained an `allowSetCustomToken` field.
 
 ### 3.3 Events Unchanged
 
-All other events (`AddPayCredits`, `AddTier`, `Mint`, `MintReservedNft`, `RemoveTier`, `SetBaseUri`, `SetContractUri`, `SetDiscountPercent`, `SetEncodedIPFSUri`, `SetTokenUriResolver`, `UsePayCredits`, `CleanTiers`, `HookDeployed`) remain identical.
+All other events (`AddPayCredits`, `AddTier`, `Mint`, `MintReservedNft`, `RemoveTier`, `SetBaseUri`, `SetContractUri`, `SetDiscountPercent`, `SetEncodedIPFSUri`, `SetTokenUriResolver`, `UsePayCredits`, `CleanTiers`, `HookDeployed`) remain unchanged.
 
 ---
 
@@ -157,11 +171,17 @@ All other events (`AddPayCredits`, `AddTier`, `Mint`, `MintReservedNft`, `Remove
 | `JB721TiersHook_CurrencyMismatch` | `(uint256 paymentCurrency, uint256 tierCurrency)` | Reserved for currency mismatch detection |
 | `JB721TiersHook_InvalidPricingDecimals` | `(uint256 decimals)` | Reverts when `tiersConfig.decimals > 18` during initialization |
 
-### 4.2 Store Errors with Added `tierId` Parameter
+### 4.2 New Error on `JB721TiersHookStore`
+
+| Error | Signature | Description |
+|-------|-----------|-------------|
+| `JB721TiersHookStore_SplitPercentExceedsBounds` | `(uint256 percent, uint256 limit)` | Reverts when a tier's `splitPercent` exceeds `JBConstants.SPLITS_TOTAL_PERCENT` during `recordAddTiers` |
+
+### 4.3 Store Errors with Added `tierId` Parameter
 
 See Section 1.7 above. Eight store errors gained a `tierId` parameter for improved debuggability.
 
-### 4.3 Errors Unchanged
+### 4.4 Errors Unchanged
 
 All other errors (`JB721Hook_InvalidPay`, `JB721Hook_InvalidCashOut`, `JB721Hook_UnauthorizedToken`, `JB721Hook_UnexpectedTokenCashedOut`, `JB721TiersHook_AlreadyInitialized`, `JB721TiersHook_NoProjectId`, `JB721TiersHook_Overspending`, `JB721TiersHook_MintReserveNftsPaused`, `JB721TiersHook_TierTransfersPaused`) remain unchanged.
 
@@ -240,15 +260,31 @@ In v5, `_packedPricingContext` packed three values: currency (bits 0-31), decima
 
 v5 reverted if `msg.value != 0` in `afterPayRecordedWith`. v6 removes this check because the hook now accepts forwarded native token payments for tier split distribution.
 
-### 6.8 `JB721TiersHookStore.recordAddTiers` — Stores `splitPercent`
+### 6.8 `JB721TiersHookLib._sendPayoutToSplit` — `split.hook` Priority
+
+Split payouts follow the same priority order as `JBMultiTerminal`: if `split.hook` is set, funds are sent to the hook via `processSplitWith`; otherwise if `split.projectId` is set, funds go to the project's primary terminal; otherwise funds go to `split.beneficiary`. For ERC-20 payments to hooks, tokens are transferred first and the hook callback is best-effort (failure does not revert).
+
+### 6.9 `JB721TiersHookLib` — Try-Catch on All External Calls
+
+All external calls during split distribution (split hooks, terminal `pay`, terminal `addToBalanceOf`, and leftover `addToBalanceOf`) are wrapped in try-catch. On failure: native token calls return false (funds stay in the hook), ERC-20 terminal call approvals are reset to zero, and `SplitPayoutReverted` or `AddToBalanceReverted` events are emitted with the revert reason.
+
+### 6.10 `JB721TiersHookLib.calculateSplitAmounts` — Discount Applied Before Splits
+
+Split amounts are calculated on the discount-adjusted (effective) tier price rather than the base price. This ensures the split amount matches the actual price the minter pays when a tier discount is active.
+
+### 6.11 `JB721TiersHookStore.recordAddTiers` — Validates `splitPercent`
+
+`recordAddTiers` now reverts with `JB721TiersHookStore_SplitPercentExceedsBounds` if a tier's `splitPercent` exceeds `JBConstants.SPLITS_TOTAL_PERCENT`.
+
+### 6.12 `JB721TiersHookStore.recordAddTiers` — Stores `splitPercent`
 
 The store now stores `splitPercent` in the `JBStored721Tier` packed struct (replacing the `votingUnits` field in storage). The `votingUnits` value continues to be stored in the `_tierVotingUnitsOf` mapping.
 
-### 6.9 `JB721TiersHookStore.recordAddTiers` — Emits `SetDefaultReserveBeneficiary`
+### 6.13 `JB721TiersHookStore.recordAddTiers` — Emits `SetDefaultReserveBeneficiary`
 
 When a tier config has `useReserveBeneficiaryAsDefault` set and the beneficiary differs from the current default, v6 emits the new `SetDefaultReserveBeneficiary` event.
 
-### 6.10 `JB721TiersHookProjectDeployer` — `allowSetCustomToken` Pass-Through
+### 6.14 `JB721TiersHookProjectDeployer` — `allowSetCustomToken` Pass-Through
 
 In v5, the project deployer hardcoded `allowSetCustomToken: false` when constructing `JBRulesetMetadata`. In v6, it passes through `payDataRulesetConfig.metadata.allowSetCustomToken`.
 
@@ -261,7 +297,7 @@ In v5, the project deployer hardcoded `allowSetCustomToken: false` when construc
 | v5 | v6 | Notes |
 |----|----|-------|
 | `IJB721Hook` | `IJB721Hook` | Unchanged (import path updated) |
-| `IJB721TiersHook` | `IJB721TiersHook` | `pricingContext()` return changed; `setMetadata()` signature changed; added `PRICES()`, `SPLITS()`, `SetName`, `SetSymbol` |
+| `IJB721TiersHook` | `IJB721TiersHook` | `pricingContext()` return changed; `setMetadata()` signature changed; added `PRICES()`, `SPLITS()`, `SetName`, `SetSymbol`, `SplitPayoutReverted`, `AddToBalanceReverted` |
 | `IJB721TiersHookDeployer` | `IJB721TiersHookDeployer` | Unchanged |
 | `IJB721TiersHookProjectDeployer` | `IJB721TiersHookProjectDeployer` | Unchanged |
 | `IJB721TiersHookStore` | `IJB721TiersHookStore` | Added `SetDefaultReserveBeneficiary` event; NatSpec added |
@@ -274,7 +310,7 @@ In v5, the project deployer hardcoded `allowSetCustomToken: false` when construc
 | `JB721TiersHook` | `JB721TiersHook` | Constructor gains `prices` and `splits`; tier splits system; code extracted to library |
 | `JB721TiersHookDeployer` | `JB721TiersHookDeployer` | Unchanged (import paths updated) |
 | `JB721TiersHookProjectDeployer` | `JB721TiersHookProjectDeployer` | `allowSetCustomToken` pass-through |
-| `JB721TiersHookStore` | `JB721TiersHookStore` | `splitPercent` storage; error params added; `SetDefaultReserveBeneficiary` event |
+| `JB721TiersHookStore` | `JB721TiersHookStore` | `splitPercent` storage and validation; error params added; `SplitPercentExceedsBounds` error; `SetDefaultReserveBeneficiary` event |
 | `JB721Hook` (abstract) | `JB721Hook` (abstract) | `cashOutWeightOf`/`totalCashOutWeight` signatures simplified; `msg.value` check removed from `afterPayRecordedWith` |
 | `ERC721` (abstract) | `ERC721` (abstract) | Added `_setName()` and `_setSymbol()` |
 

package/README.md

@@ -55,7 +55,7 @@ For projects using `forge` to manage dependencies (not recommended):
 forge install Bananapus/nana-721-hook
 ```
 
-If you're using `forge` to manage dependencies, add `@bananapus/721-hook/=lib/nana-721-hook/` to `remappings.txt`. You'll also need to install `nana-721-hook`'s dependencies and add similar remappings for them.
+If you're using `forge` to manage dependencies, you'll also need to install `nana-721-hook`'s dependencies. With `libs = ["node_modules", "lib"]` in `foundry.toml`, Foundry auto-resolves import paths — no `remappings.txt` needed.
 
 ### Develop
 
@@ -136,13 +136,7 @@ This example deploys `nana-721-hook` to the Sepolia testnet using the specified
 
 To view test coverage, run `npm run coverage` to generate an LCOV test report. You can use an extension like [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) to view coverage in your editor.
 
-If you're using Nomic Foundation's [Solidity](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity) extension in VSCode, you may run into LSP errors because the extension cannot find dependencies outside of `lib`. You can often fix this by running:
-
-```bash
-forge remappings >> remappings.txt
-```
-
-This makes the extension aware of default remappings.
+If you're using Nomic Foundation's [Solidity](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity) extension in VSCode, you may run into LSP errors because the extension cannot find dependencies outside of `lib`. You can often fix this by running `forge remappings > remappings.txt` to generate a remappings file for the extension. This file is gitignored and only needed for editor support.
 
 ## Repository Layout
 
@@ -219,7 +213,8 @@ Each pay/cash out hook can then execute custom behavior based on the custom data
 
 ### Mechanism
 
-A project using a 721 tiers hook can specify any number of NFT tiers (up to 65,535 total).
+A project using a 721 tiers hook can specify a large number of NFT tiers in theory (up to 65,535 total), but the
+practical operating envelope is much smaller because several important paths still scale with `maxTierId`.
 
 - NFT tiers can be removed by the project owner as long as they are not locked (`cannotBeRemoved`). After removing tiers, call `cleanTiers()` on the store to optimize tier iteration.
 - NFT tiers can be added by the project owner as long as they respect the hook's `flags`. Tiers must be sorted by category in ascending order — the store reverts with `JB721TiersHookStore_InvalidCategorySortOrder` if not. The flags specify if newly added tiers can have votes (voting units), if new tiers can have non-zero reserve frequencies, if new tiers can allow on-demand minting by the project's owner, and if overspending is allowed.
@@ -246,6 +241,21 @@ Additional notes:
 - If enabled by the project owner, holders can burn their NFTs to reclaim funds from the project. These cash outs are proportional to the NFTs price, relative to the combined price of all the NFTs (including pending reserves in the denominator).
 - NFT cash outs can be enabled by setting `useDataHookForCashOut` to `true` in the project's `JBRulesetMetadata`. If NFT cash outs are enabled, project token cash outs are disabled -- attempting to cash out fungible tokens when the data hook is active will revert.
 - Per-tier voting units can be configured: either custom voting units or the tier's price as the default. Voting power is computed per-address across all tiers.
+
+### Supported Operating Envelope
+
+The current implementation is best suited to curated catalogs, not effectively unbounded consumer storefronts.
+
+- Treat roughly `<= 100` active tiers as the comfortable operating envelope for projects that expect frequent
+  `balanceOf`, governance reads, or NFT cash outs.
+- Treat `100-200` tiers as an advanced configuration that should be used only with deliberate gas budgeting and
+  frontend/operator awareness.
+- Above that range, the on-chain reads and cash-out accounting are still functionally correct, but several important
+  paths become increasingly expensive because they iterate the tier set.
+
+The test suite proves survivability at `100` and `200` tiers, and also proves that `balanceOf` and
+`totalCashOutWeight` become materially more expensive at `100` tiers than at `10` tiers. That evidence should be read
+as a scope boundary, not as encouragement to target the `uint16.max` theoretical tier ceiling in production.
 - The hook declares support for ERC-2981 (royalties) via `supportsInterface`, but does not implement the `royaltyInfo` function. This is intended for future extension.
 
 ### Setup

package/RISKS.md

@@ -33,6 +33,10 @@
 
 - **`totalCashOutWeight` iterates ALL tier IDs** (1 to `maxTierIdOf`), including removed tiers with minted NFTs. Called during every `beforeCashOutRecordedWith`. At ~2-3k gas per tier, 500+ tiers approaches block gas limits. Could block all NFT cash-outs if an attacker with `ADJUST_721_TIERS` permission adds thousands of tiers.
 - **`balanceOf`, `votingUnitsOf`, `totalSupplyOf` iterate all tiers.** Same pattern: loop from `maxTierIdOf` down to 1. These are view functions but called by governance contracts.
+- **Theoretical max is not the supported operating envelope.** The store permits up to 65,535 tiers, but the practical
+  comfort zone is far lower. The test suite demonstrates survivability at 100 to 200 tiers and also demonstrates that
+  `balanceOf` and `totalCashOutWeight` become materially more expensive at 100 tiers than at 10 tiers. Treat large
+  catalogs as an explicit gas-budgeting exercise, not as a default deployment shape.
 - **`tiersOf` traverses removed tiers.** Removed tiers are skipped via bitmap but still traversed in the linked list. `cleanTiers()` must be called separately to compact. `cleanTiers()` is permissionless and idempotent.
 - **Minting from many tiers in one payment.** `recordMint` loops per tier ID: storage read (stored tier + bitmap check) per iteration. 50 tiers in one payment ~5-7M gas (tested, fits in 30M block). 100+ tiers in a single mint is feasible but consumes most of the block.
 - **`recordAddTiers` sort-insertion cost.** Adding a low-category tier to a hook with many existing higher-category tiers iterates the entire sorted list to find the insertion point. O(n) per added tier.

package/USER_JOURNEYS.md

@@ -2,6 +2,10 @@
 
 Every user-facing operation in the tiered 721 hook system, with exact entry points, parameters, state changes, events, and edge cases.
 
+These journeys describe functional behavior, not a promise that the theoretical `uint16.max` tier ceiling is a
+production-ready catalog size. Several important reads and cash-out calculations scale with `maxTierId`, so large-tier
+deployments should be evaluated against the repo's documented operating envelope before launch.
+
 ---
 
 ## 1. Pay and Receive NFTs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@bananapus/address-registry-v6": "^0.0.10",
-    "@bananapus/core-v6": "^0.0.17",
+    "@bananapus/core-v6": "^0.0.23",
     "@bananapus/ownable-v6": "^0.0.10",
     "@bananapus/permission-ids-v6": "^0.0.10",
     "@openzeppelin/contracts": "^5.6.1",

package/src/JB721TiersHook.sol

@@ -210,7 +210,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             issueTokensForSplits: STORE.flagsOf(address(this)).issueTokensForSplits
         });
 
-        hookSpecifications[0] = JBPayHookSpecification({hook: this, amount: totalSplitAmount, metadata: splitMetadata});
+        hookSpecifications[0] =
+            JBPayHookSpecification({hook: this, noop: false, amount: totalSplitAmount, metadata: splitMetadata});
     }
 
     /// @notice The combined cash out weight of the NFTs with the specified token IDs.
@@ -620,104 +621,105 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         }
     }
 
-    /// @notice Process a payment, minting NFTs and updating credits as necessary.
-    /// @dev Pay credits are tracked per beneficiary, not per payer. When the payer differs from the beneficiary,
-    /// the payer's existing credits are NOT applied to the mint. Only the beneficiary's credits are combined with
-    /// the incoming payment value. Leftover funds after minting are stored as credits for the beneficiary.
-    /// @param context Payment context provided by the terminal after it has recorded the payment in the terminal store.
-    function _processPayment(JBAfterPayRecordedContext calldata context) internal virtual override {
-        // Normalize the payment value based on the pricing context.
-        uint256 value;
-        {
-            bool valid;
-            (value, valid) = JB721TiersHookLib.normalizePaymentValue({
-                packedPricingContext: _packedPricingContext,
-                prices: PRICES,
-                projectId: PROJECT_ID,
-                amountValue: context.amount.value,
-                amountCurrency: context.amount.currency,
-                amountDecimals: context.amount.decimals
-            });
-            if (!valid) return;
+    /// @notice Mint NFTs from the specified tiers and update the beneficiary's pay credits.
+    /// @param value The normalized payment value.
+    /// @param context Payment context provided by the terminal.
+    function _mintAndUpdateCredits(uint256 value, JBAfterPayRecordedContext calldata context) internal {
+        // Keep a reference to the number of NFT credits the beneficiary already has.
+        uint256 payCredits = payCreditsOf[context.beneficiary];
+
+        // Set the leftover amount as the initial value.
+        uint256 leftoverAmount = value;
+
+        // If the payer is the beneficiary, combine their NFT credits with the amount paid.
+        uint256 unusedPayCredits;
+        if (context.payer == context.beneficiary) {
+            leftoverAmount += payCredits;
+        } else {
+            // Otherwise, the payer's NFT credits won't be used, and we keep track of the unused credits.
+            unusedPayCredits = payCredits;
         }
 
-        // Scope block to free stack slots before the distributeAll call below.
-        {
-            // Keep a reference to the number of NFT credits the beneficiary already has.
-            uint256 payCredits = payCreditsOf[context.beneficiary];
+        // Keep a reference to the boolean indicating whether paying more than the price of the NFTs being minted
+        // is allowed. Defaults to the collection's flag.
+        bool allowOverspending = !STORE.flagsOf(address(this)).preventOverspending;
 
-            // Set the leftover amount as the initial value.
-            uint256 leftoverAmount = value;
+        // Resolve the metadata.
+        (bool found, bytes memory metadata) = JBMetadataResolver.getDataFor({
+            id: JBMetadataResolver.getId({purpose: "pay", target: METADATA_ID_TARGET}), metadata: context.payerMetadata
+        });
 
-            // If the payer is the beneficiary, combine their NFT credits with the amount paid.
-            uint256 unusedPayCredits;
-            if (context.payer == context.beneficiary) {
-                leftoverAmount += payCredits;
-            } else {
-                // Otherwise, the payer's NFT credits won't be used, and we keep track of the unused credits.
-                unusedPayCredits = payCredits;
-            }
+        if (found) {
+            // Keep a reference to the IDs of the tier be to minted.
+            uint16[] memory tierIdsToMint;
 
-            // Keep a reference to the boolean indicating whether paying more than the price of the NFTs being minted
-            // is allowed. Defaults to the collection's flag.
-            bool allowOverspending = !STORE.flagsOf(address(this)).preventOverspending;
+            // Keep a reference to the payer's flag indicating whether overspending is allowed.
+            bool payerAllowsOverspending;
 
-            // Resolve the metadata.
-            (bool found, bytes memory metadata) = JBMetadataResolver.getDataFor({
-                id: JBMetadataResolver.getId({purpose: "pay", target: METADATA_ID_TARGET}),
-                metadata: context.payerMetadata
-            });
+            // Decode the metadata.
+            (payerAllowsOverspending, tierIdsToMint) = abi.decode(metadata, (bool, uint16[]));
 
-            if (found) {
-                // Keep a reference to the IDs of the tier be to minted.
-                uint16[] memory tierIdsToMint;
+            // Make sure overspending is allowed if requested.
+            if (allowOverspending && !payerAllowsOverspending) {
+                allowOverspending = false;
+            }
 
-                // Keep a reference to the payer's flag indicating whether overspending is allowed.
-                bool payerAllowsOverspending;
+            // Mint NFTs from the tiers as specified.
+            if (tierIdsToMint.length != 0) {
+                // slither-disable-next-line reentrancy-events,reentrancy-no-eth
+                leftoverAmount =
+                    _mintAll({amount: leftoverAmount, mintTierIds: tierIdsToMint, beneficiary: context.beneficiary});
+            }
+        }
 
-                // Decode the metadata.
-                (payerAllowsOverspending, tierIdsToMint) = abi.decode(metadata, (bool, uint16[]));
+        // If overspending isn't allowed, revert.
+        if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
 
-                // Make sure overspending is allowed if requested.
-                if (allowOverspending && !payerAllowsOverspending) {
-                    allowOverspending = false;
-                }
+        // Update NFT credits if they changed.
+        uint256 newPayCredits = leftoverAmount + unusedPayCredits;
 
-                // Mint NFTs from the tiers as specified.
-                if (tierIdsToMint.length != 0) {
-                    // slither-disable-next-line reentrancy-events,reentrancy-no-eth
-                    leftoverAmount = _mintAll({
-                        amount: leftoverAmount, mintTierIds: tierIdsToMint, beneficiary: context.beneficiary
-                    });
-                }
+        if (newPayCredits != payCredits) {
+            if (newPayCredits > payCredits) {
+                emit AddPayCredits({
+                    amount: newPayCredits - payCredits,
+                    newTotalCredits: newPayCredits,
+                    account: context.beneficiary,
+                    caller: _msgSender()
+                });
+            } else {
+                emit UsePayCredits({
+                    amount: payCredits - newPayCredits,
+                    newTotalCredits: newPayCredits,
+                    account: context.beneficiary,
+                    caller: _msgSender()
+                });
             }
 
-            // If overspending isn't allowed, revert.
-            if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
-
-            // Update NFT credits if they changed.
-            uint256 newPayCredits = leftoverAmount + unusedPayCredits;
-
-            if (newPayCredits != payCredits) {
-                if (newPayCredits > payCredits) {
-                    emit AddPayCredits({
-                        amount: newPayCredits - payCredits,
-                        newTotalCredits: newPayCredits,
-                        account: context.beneficiary,
-                        caller: _msgSender()
-                    });
-                } else {
-                    emit UsePayCredits({
-                        amount: payCredits - newPayCredits,
-                        newTotalCredits: newPayCredits,
-                        account: context.beneficiary,
-                        caller: _msgSender()
-                    });
-                }
-
-                payCreditsOf[context.beneficiary] = newPayCredits;
-            }
+            payCreditsOf[context.beneficiary] = newPayCredits;
         }
+    }
+
+    /// @notice Process a payment, minting NFTs and updating credits as necessary.
+    /// @dev Pay credits are tracked per beneficiary, not per payer. When the payer differs from the beneficiary,
+    /// the payer's existing credits are NOT applied to the mint. Only the beneficiary's credits are combined with
+    /// the incoming payment value. Leftover funds after minting are stored as credits for the beneficiary.
+    /// @param context Payment context provided by the terminal after it has recorded the payment in the terminal store.
+    function _processPayment(JBAfterPayRecordedContext calldata context) internal virtual override {
+        // Normalize the payment value based on the pricing context.
+        bool valid;
+        uint256 value;
+        (value, valid) = JB721TiersHookLib.normalizePaymentValue({
+            packedPricingContext: _packedPricingContext,
+            prices: PRICES,
+            projectId: PROJECT_ID,
+            amountValue: context.amount.value,
+            amountCurrency: context.amount.currency,
+            amountDecimals: context.amount.decimals
+        });
+        if (!valid) return;
+
+        // Mint NFTs from the specified tiers and update the beneficiary's pay credits.
+        _mintAndUpdateCredits({value: value, context: context});
 
         // Distribute any forwarded funds to tier split groups.
         if (context.hookMetadata.length != 0 && context.forwardedAmount.value != 0) {

package/src/abstract/JB721Hook.sol

@@ -102,7 +102,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
 
         // Use this contract as the only cash out hook.
         hookSpecifications = new JBCashOutHookSpecification[](1);
-        hookSpecifications[0] = JBCashOutHookSpecification({hook: this, amount: 0, metadata: bytes("")});
+        hookSpecifications[0] = JBCashOutHookSpecification({hook: this, noop: false, amount: 0, metadata: bytes("")});
 
         uint256[] memory decodedTokenIds;
 
@@ -136,7 +136,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         // Forward the received weight and use this contract as the only pay hook.
         weight = context.weight;
         hookSpecifications = new JBPayHookSpecification[](1);
-        hookSpecifications[0] = JBPayHookSpecification({hook: this, amount: 0, metadata: bytes("")});
+        hookSpecifications[0] = JBPayHookSpecification({hook: this, noop: false, amount: 0, metadata: bytes("")});
     }
 
     /// @notice Required by the IJBRulesetDataHook interfaces. Return false to not leak any permissions.

package/src/libraries/JB721TiersHookLib.sol

@@ -175,14 +175,10 @@ library JB721TiersHookLib {
         view
         returns (uint256 totalSplitAmount, bytes memory hookMetadata)
     {
-        bytes memory data;
-        {
-            bool found;
-            (found, data) = JBMetadataResolver.getDataFor({
-                id: JBMetadataResolver.getId({purpose: "pay", target: metadataIdTarget}), metadata: metadata
-            });
-            if (!found) return (0, bytes(""));
-        }
+        (bool found, bytes memory data) = JBMetadataResolver.getDataFor({
+            id: JBMetadataResolver.getId({purpose: "pay", target: metadataIdTarget}), metadata: metadata
+        });
+        if (!found) return (0, bytes(""));
 
         (, uint16[] memory tierIdsToMint) = abi.decode(data, (bool, uint16[]));
         if (tierIdsToMint.length == 0) return (0, bytes(""));