@bananapus/721-hook-v6 0.0.18 → 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/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.18",
+  "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(""));

package/test/TestAuditGaps.sol

@@ -424,6 +424,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
 
     /// @dev The block gas limit on mainnet is 30M. We use a generous limit for safety.
     uint256 constant BLOCK_GAS_LIMIT = 30_000_000;
+    uint256 constant OPERATING_ENVELOPE_SOFT_LIMIT = 200;
 
     // ---------------------------------------------------------------
     // Test 1: Add 100 tiers in a single adjustTiers call
@@ -446,6 +447,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1), // Ascending categories
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -498,6 +500,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1),
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -552,6 +555,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1),
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -579,6 +583,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
         uint16[] memory tierIdsToMint = new uint16[](10);
         uint256 totalCost;
         for (uint256 i; i < 10; i++) {
+            // forge-lint: disable-next-line(unsafe-typecast)
             // forge-lint: disable-next-line(unsafe-typecast)
             tierIdsToMint[i] = uint16(i + 1);
             totalCost += (i + 1) * 1e15;
@@ -651,6 +656,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1),
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -699,6 +705,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1),
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -759,6 +766,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1),
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -830,6 +838,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
                 reserveBeneficiary: reserveBeneficiary,
                 encodedIPFSUri: tokenUris[i % 10],
                 // forge-lint: disable-next-line(unsafe-typecast)
+                // forge-lint: disable-next-line(unsafe-typecast)
                 category: uint24(i + 1),
                 discountPercent: 0,
                 allowOwnerMint: false,
@@ -856,6 +865,7 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
         uint16[] memory tierIdsToMint = new uint16[](50);
         uint256 totalCost;
         for (uint256 i; i < 50; i++) {
+            // forge-lint: disable-next-line(unsafe-typecast)
             // forge-lint: disable-next-line(unsafe-typecast)
             tierIdsToMint[i] = uint16(i + 1);
             totalCost += (i + 1) * 1e15;
@@ -900,4 +910,141 @@ contract TestAuditGaps_GasLimits is UnitTestSetup {
 
         emit log_named_uint("Gas used to mint from 50 tiers in single payment", gasUsed);
     }
+
+    /// @notice The expensive read paths scale with tier count, not just with the beneficiary's holdings.
+    /// This test exists to prove that a 100-tier catalog is materially more expensive than a 10-tier catalog even
+    /// when the queried user owns zero NFTs.
+    function test_operatingEnvelope_balanceOf_100tiersIsMateriallyMoreExpensiveThan10tiers() public {
+        uint256 gasFor10 = _measureBalanceOfGas({tierCount: 10});
+        uint256 gasFor100 = _measureBalanceOfGas({tierCount: 100});
+
+        assertGt(gasFor100, gasFor10 * 4, "100-tier balanceOf should be materially more expensive than 10 tiers");
+        emit log_named_uint("Gas used for balanceOf (10 tiers)", gasFor10);
+        emit log_named_uint("Gas used for balanceOf (100 tiers)", gasFor100);
+    }
+
+    /// @notice Cash-out accounting also scales with the catalog size because totalCashOutWeight walks the tier set.
+    /// We use a ratio check instead of an absolute snapshot so the test stays stable across compiler changes while
+    /// still proving the production-scale cost increase.
+    function test_operatingEnvelope_totalCashOutWeight_100tiersIsMateriallyMoreExpensiveThan10tiers() public {
+        uint256 gasFor10 = _measureTotalCashOutWeightGas({tierCount: 10, mintedCount: 10});
+        uint256 gasFor100 = _measureTotalCashOutWeightGas({tierCount: 100, mintedCount: 10});
+
+        assertGt(
+            gasFor100, gasFor10 * 4, "100-tier totalCashOutWeight should be materially more expensive than 10 tiers"
+        );
+        emit log_named_uint("Gas used for totalCashOutWeight (10 tiers)", gasFor10);
+        emit log_named_uint("Gas used for totalCashOutWeight (100 tiers)", gasFor100);
+    }
+
+    function _measureBalanceOfGas(uint256 tierCount) internal returns (uint256 gasUsed) {
+        defaultTierConfig.initialSupply = 10;
+        defaultTierConfig.reserveFrequency = 0;
+
+        ForTest_JB721TiersHook targetHook = _initializeForTestHook(0);
+        IJB721TiersHookStore hookStore = targetHook.STORE();
+
+        vm.prank(address(targetHook));
+        hookStore.recordAddTiers(_sequentialTierConfigs(tierCount, 1e15, 10));
+
+        uint256 gasBefore = gasleft();
+        hookStore.balanceOf(address(targetHook), beneficiary);
+        gasUsed = gasBefore - gasleft();
+    }
+
+    function _measureTotalCashOutWeightGas(uint256 tierCount, uint256 mintedCount) internal returns (uint256 gasUsed) {
+        defaultTierConfig.initialSupply = 10;
+        defaultTierConfig.reserveFrequency = 0;
+
+        ForTest_JB721TiersHook targetHook = _initializeForTestHook(0);
+        IJB721TiersHookStore hookStore = targetHook.STORE();
+
+        vm.prank(address(targetHook));
+        hookStore.recordAddTiers(_sequentialTierConfigs(tierCount, 1e15, 10));
+
+        mockAndExpect(
+            address(mockJBDirectory),
+            abi.encodeWithSelector(IJBDirectory.isTerminalOf.selector, projectId, mockTerminalAddress),
+            abi.encode(true)
+        );
+
+        uint16[] memory tierIdsToMint = new uint16[](mintedCount);
+        uint256 totalCost;
+        for (uint256 i; i < mintedCount; i++) {
+            // forge-lint: disable-next-line(unsafe-typecast)
+            tierIdsToMint[i] = uint16(i + 1);
+            totalCost += (i + 1) * 1e15;
+        }
+
+        bytes[] memory data = new bytes[](1);
+        data[0] = abi.encode(false, tierIdsToMint);
+        bytes4[] memory ids = new bytes4[](1);
+        ids[0] = metadataHelper.getId("pay", address(targetHook));
+        bytes memory payerMetadata = metadataHelper.createMetadata(ids, data);
+
+        JBAfterPayRecordedContext memory payContext = JBAfterPayRecordedContext({
+            payer: beneficiary,
+            projectId: projectId,
+            rulesetId: 0,
+            amount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: totalCost,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            forwardedAmount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 0,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            weight: 10e18,
+            newlyIssuedTokenCount: 0,
+            beneficiary: beneficiary,
+            hookMetadata: bytes(""),
+            payerMetadata: payerMetadata
+        });
+
+        vm.prank(mockTerminalAddress);
+        targetHook.afterPayRecordedWith(payContext);
+
+        uint256 gasBefore = gasleft();
+        hookStore.totalCashOutWeight(address(targetHook));
+        gasUsed = gasBefore - gasleft();
+    }
+
+    function _sequentialTierConfigs(
+        uint256 tierCount,
+        uint104 priceStep,
+        uint32 initialSupply
+    )
+        internal
+        view
+        returns (JB721TierConfig[] memory newTiers)
+    {
+        require(tierCount <= OPERATING_ENVELOPE_SOFT_LIMIT, "test helper only sized for envelope coverage");
+
+        newTiers = new JB721TierConfig[](tierCount);
+        for (uint256 i; i < tierCount; i++) {
+            newTiers[i] = JB721TierConfig({
+                price: uint104((i + 1) * priceStep),
+                initialSupply: initialSupply,
+                votingUnits: 0,
+                reserveFrequency: 0,
+                reserveBeneficiary: reserveBeneficiary,
+                encodedIPFSUri: tokenUris[i % 10],
+                // forge-lint: disable-next-line(unsafe-typecast)
+                category: uint24(i + 1),
+                discountPercent: 0,
+                allowOwnerMint: false,
+                useReserveBeneficiaryAsDefault: false,
+                transfersPausable: false,
+                cannotBeRemoved: false,
+                cannotIncreaseDiscountPercent: false,
+                useVotingUnits: false,
+                splitPercent: 0,
+                splits: new JBSplit[](0)
+            });
+        }
+    }
 }