@bananapus/721-hook-v6 0.0.18 → 0.0.20

package/README.md

@@ -1,257 +1,268 @@
 # Juicebox 721 Hook
 
-`nana-721-hook` is:
-
-1. A pay hook for Juicebox projects to sell tiered NFTs (ERC-721s) with different prices and artwork.
-2. (Optionally) a cash out hook which allows holders to burn their NFTs to reclaim funds from the project, in proportion to the NFT's price.
-
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li><a href="#usage">Usage</a></li>
-  <ul>
-    <li><a href="#install">Install</a></li>
-    <li><a href="#develop">Develop</a></li>
-    <li><a href="#scripts">Scripts</a></li>
-    <li><a href="#deployments">Deployments</a></li>
-    <ul>
-      <li><a href="#with-sphinx">With Sphinx</a></li>
-      <li><a href="#without-sphinx">Without Sphinx</a></li>
-      </ul>
-    <li><a href="#tips">Tips</a></li>
-    </ul>
-    <li><a href="#repository-layout">Repository Layout</a></li>
-    <li><a href="#architecture">Architecture</a></li>
-  <ul>
-    <li><a href="#contracts">Contracts</a></li>
-    </ul>
-    <li><a href="#description">Description</a></li>
-  <ul>
-    <li><a href="#hooks">Hooks</a></li>
-    <li><a href="#mechanism">Mechanism</a></li>
-    <li><a href="#setup">Setup</a></li>
-    </ul>
-  </ul>
-  </ol>
-</details>
-
-_If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
-
-## Usage
-
-### Install
-
-How to install `nana-721-hook` in another project.
+Juicebox projects accept payments through terminals, but by default those payments only mint fungible project tokens. `nana-721-hook-v6` extends that flow with a tiered NFT system: project owners define tiers -- each with a price, supply cap, artwork, and optional per-tier features like reserve minting, voting power, discount schedules, and split-based fund routing -- and when someone pays the project, the hook mints the corresponding NFTs. Optionally, holders can burn their NFTs to reclaim funds from the project in proportion to each NFT's price relative to all outstanding NFTs.
 
-For projects using `npm` to manage dependencies (recommended):
+_If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core-v6) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
 
-```bash
-npm install @bananapus/721-hook
-```
+## Conceptual Overview
 
-For projects using `forge` to manage dependencies (not recommended):
-
-```bash
-forge install Bananapus/nana-721-hook
-```
+### How it works
 
-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.
+A `JB721TiersHook` is simultaneously a **data hook**, a **pay hook**, and a **cash out hook**. When a project using this hook is paid through a Juicebox terminal, the terminal asks the data hook what should happen. The data hook inspects the payment amount and any tier IDs the payer specified in the payment metadata, then returns instructions for the pay hook to mint the appropriate NFTs.
 
-### Develop
+1. **Payment arrives** at the terminal. The terminal calls the data hook with details about the payment.
+2. **Tier selection.** The payer can specify which tier IDs to mint in the payment metadata. If no tiers are specified and the hook allows credits, the payment amount is stored as NFT credits for future purchases.
+3. **Price check.** Each requested tier's price (after any discount) is checked against the payment amount. If the tier and payment use different currencies, the hook's immutable `PRICES` contract converts between them. If `PRICES` is the zero address and currencies differ, the payment is silently ignored (no mint, no revert).
+4. **Minting.** The pay hook mints one NFT per requested tier to the payment beneficiary, decrementing each tier's remaining supply.
+5. **Reserve minting.** If a tier has a `reserveFrequency` of N, one extra NFT is minted to the tier's `reserveBeneficiary` for every N NFTs purchased. Reserve NFTs are minted lazily via `mintPendingReservesFor`.
+6. **Credits.** Any leftover payment amount (the portion not spent on tier prices) is stored as NFT credits on the payer's address, redeemable toward future NFT purchases. Credits are only combined with the payment when `payer == beneficiary`. The hook can reject leftover funds entirely via the `preventOverspending` flag.
+7. **Cash outs.** If the project owner enables `useDataHookForCashOut` in the ruleset metadata, NFT holders can burn their NFTs to reclaim funds. The reclaim amount is proportional to the NFT's original tier price (not the discounted price) relative to the total price of all outstanding NFTs (including pending reserves in the denominator). When NFT cash outs are enabled, fungible token cash outs are disabled -- attempting to cash out fungible tokens when the data hook is active will revert.
 
-`nana-721-hook` uses [npm](https://www.npmjs.com/) (version >=20.0.0) for package management and the [Foundry](https://github.com/foundry-rs/foundry) development toolchain for builds, tests, and deployments. To get set up, [install Node.js](https://nodejs.org/en/download) and install [Foundry](https://github.com/foundry-rs/foundry):
+### Tier properties
 
-```bash
-curl -L https://foundry.paradigm.xyz | sh
-```
+Each tier is configured with a `JB721TierConfig` and stored compactly as a `JBStored721Tier`. Key properties:
 
-You can download and install dependencies with:
+- **Price** (`uint104`). The cost to mint one NFT from this tier, denominated in the currency specified in the hook's `JB721InitTiersConfig`.
+- **Initial supply** (`uint32`). The maximum number of NFTs that can ever be minted from this tier (up to 999,999,999).
+- **Category** (`uint24`). Groups tiers for organizational and access purposes. Tiers must be sorted by category in ascending order when added -- the store reverts with `JB721TiersHookStore_InvalidCategorySortOrder` otherwise.
+- **Discount percent** (`uint8`). Reduces the effective purchase price. The denominator is 200, so a `discountPercent` of 100 means 50% off and 200 means free. Can be changed later via `setDiscountPercentOf`. Tiers configured with `cannotIncreaseDiscountPercent` only allow discounts to decrease. Cash out weight always uses the original tier price, not the discounted price.
+- **Reserve frequency** (`uint16`). With a value of N, one extra NFT is minted to the `reserveBeneficiary` for every N NFTs purchased. Tiers with `allowOwnerMint` enabled cannot have reserves.
+- **Voting units** (`uint104`). By default, each NFT's voting power equals its tier price. When `useVotingUnits` is true, a custom `votingUnits` value is used instead. Voting power is computed per-address across all tiers.
+- **Split percent** (`uint32`). Routes a percentage of the tier's mint price to configured split recipients each time an NFT from the tier is purchased, out of `JBConstants.SPLITS_TOTAL_PERCENT` (1,000,000,000). The remaining funds stay in the project's balance. Split recipients follow the same priority as `JBMultiTerminal`: `split.hook` (receives funds via `IJBSplitHook.processSplitWith`) > `split.projectId` (routed via the project's primary terminal) > `split.beneficiary` (direct transfer).
+- **Weight adjustment.** When splits are active, the hook adjusts the returned weight so the terminal only mints fungible project tokens proportional to the amount that actually enters the project treasury. For example, a 50% `splitPercent` on a 1 ETH payment results in half the normal token issuance. This weight adjustment can be disabled with the `issueTokensForSplits` flag, which gives payers full token credit regardless of where the funds go.
+- **Flags.** `allowOwnerMint` (project owner can mint on-demand), `transfersPausable` (transfers can be paused per-ruleset), `cannotBeRemoved` (tier is permanent once added), `cannotIncreaseDiscountPercent` (discount can only decrease).
+- **Token URI.** Each tier has an `encodedIPFSUri` for artwork/metadata, which can be overridden by an `IJB721TokenUriResolver`. The resolver can return unique values for each NFT within a tier.
 
-```bash
-npm ci && forge install
-```
+### Per-ruleset options
 
-If you run into trouble with `forge install`, try using `git submodule update --init --recursive` to ensure that nested submodules have been properly initialized.
+The hook packs two boolean flags into the ruleset's `metadata` field via `JB721TiersRulesetMetadata`:
 
-Some useful commands:
+- `pauseTransfers` -- prevents all NFT transfers during this ruleset (only affects tiers with `transfersPausable` set).
+- `pauseMintPendingReserves` -- prevents minting pending reserve NFTs during this ruleset.
 
-| Command               | Description                                         |
-| --------------------- | --------------------------------------------------- |
-| `forge build`         | Compile the contracts and write artifacts to `out`. |
-| `forge fmt`           | Lint.                                               |
-| `forge test`          | Run the tests.                                      |
-| `forge build --sizes` | Get contract sizes.                                 |
-| `forge coverage`      | Generate a test coverage report.                    |
-| `foundryup`           | Update foundry. Run this periodically.              |
-| `forge clean`         | Remove the build artifacts and cache directories.   |
+### Operating envelope
 
-To learn more, visit the [Foundry Book](https://book.getfoundry.sh/) docs.
+The contract supports up to 65,535 tiers (`uint16.max`), but the practical operating envelope is much smaller because several important read paths iterate the tier set:
 
-### Scripts
+- **Up to ~100 active tiers**: comfortable for projects that expect frequent `balanceOf` reads, governance queries, or NFT cash outs.
+- **100--200 tiers**: an advanced configuration requiring deliberate gas budgeting and frontend/operator awareness.
+- **Above 200 tiers**: on-chain reads and cash-out accounting remain functionally correct, but gas costs scale linearly with `maxTierId`.
 
-For convenience, several utility commands are available in `package.json`.
+The test suite proves survivability at 100 and 200 tiers, and demonstrates that `balanceOf` and `totalCashOutWeight` become materially more expensive at 100 tiers than at 10. Treat this evidence as a scope boundary, not encouragement to target the theoretical ceiling.
 
-| Command             | Description                                             |
-| ------------------- | ------------------------------------------------------- |
-| `npm test`          | Run local tests.                                        |
-| `npm run coverage`  | Generate an LCOV test coverage report.                  |
-| `npm run artifacts` | Fetch Sphinx artifacts and write them to `deployments/` |
+## Architecture
 
-### Deployments
+```mermaid
+graph TD;
+    A[JB721TiersHookProjectDeployer] -->|launches project + queues rulesets| B[Juicebox Project]
+    D[JB721TiersHookDeployer] -->|deploys hook for existing project| C[JB721TiersHook]
+    A -->|deploys via| D
+    B -->|calls on pay / cash out| C
+    C -->|reads and writes tier data| E[JB721TiersHookStore]
+    B -->|uses| F[JBMultiTerminal]
+    C -->|mints NFTs on payment through| F
+    C -->|burns NFTs to reclaim funds through| F
+```
 
-#### With Sphinx
+| Contract | Lines | Description |
+| --- | --- | --- |
+| `JB721TiersHook` | 794 | The core tiered NFT hook. Implements pay hook (mint NFTs), cash out hook (burn NFTs for reclaim), and data hook (compute weight adjustments and split routing). Manages credits, tier adjustments, reserve minting, discount changes, and metadata. Inherits `JB721Hook` and `JBOwnable`. |
+| `JB721TiersHookStore` | 1,240 | Shared data store for all `JB721TiersHook` instances. Manages tier storage (packed `JBStored721Tier`), supply tracking, bitmap-based tier removal, token ID encoding/decoding, and enforces tier sort order, supply limits, and flag constraints. |
+| `JB721TiersHookProjectDeployer` | 418 | Convenience deployer that creates a new Juicebox project with a 721 tiers hook already configured. Exposes `launchProjectFor` and `queueRulesetsOf` for ongoing ruleset management. |
+| `JB721TiersHookDeployer` | 115 | Deploys a `JB721TiersHook` clone for an existing project via `deployHookFor`. Uses Solady `LibClone` for minimal proxy deployment and registers the clone in `IJBAddressRegistry`. |
+| `JB721Hook` (abstract) | 268 | Abstract base for 721 hooks. Handles pay/cash out lifecycle dispatch, terminal validation, metadata ID resolution, and ERC-2981/ERC-165 interface declaration. |
+| `ERC721` (abstract) | 506 | Clone-compatible ERC-721 implementation with mutable `name` and `symbol` (set during `initialize` rather than constructor, since hooks are deployed as clones). |
+| `JB721TiersHookLib` | 634 | Library for tier adjustment logic, split distribution, price normalization across currencies, and token URI resolution. |
+| `JB721TiersRulesetMetadataResolver` | 47 | Packs and unpacks `JB721TiersRulesetMetadata` (transfer pause + reserve mint pause) into the 14-bit metadata field of `JBRulesetMetadata`. |
+| `JBBitmap` | 58 | Word-based bitmap for tracking removed tiers. Each word covers 256 tier IDs. |
+| `JBIpfsDecoder` | 98 | Decodes `bytes32`-encoded IPFS CIDv0 hashes into `Qm...` URI strings. |
+| `JB721Constants` | 7 | Defines `DISCOUNT_DENOMINATOR = 200`. |
+
+### Supporting Types
+
+Key structs used to configure and interact with the hook:
+
+| Struct | Purpose |
+| --- | --- |
+| `JB721TierConfig` | Full configuration for a single tier: price, supply, voting units, reserve frequency, discount, category, splits, and boolean flags. |
+| `JB721Tier` | Read-only view of a tier's current state, including remaining supply and resolved URI. |
+| `JBStored721Tier` | Packed on-chain storage layout for a tier (price, supply, category, discount, reserve frequency, split percent, and packed boolean flags). |
+| `JB721InitTiersConfig` | Wraps an array of `JB721TierConfig` with the currency and decimal precision for tier prices. |
+| `JBDeploy721TiersHookConfig` | Full deployment config: collection name/symbol, base URI, token URI resolver, contract URI, tiers config, default reserve beneficiary, and flags. |
+| `JB721TiersHookFlags` | Hook-wide boolean flags: `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting`, `preventOverspending`, `issueTokensForSplits`. |
+| `JB721TiersRulesetMetadata` | Per-ruleset options packed into `JBRulesetMetadata.metadata`: `pauseTransfers`, `pauseMintPendingReserves`. |
+| `JB721TiersMintReservesConfig` | Specifies which tier to mint reserves for and how many to mint. |
+| `JB721TiersSetDiscountPercentConfig` | Specifies a tier ID and the new discount percent to set. |
+
+## Install
 
-`nana-721-hook` manages deployments with [Sphinx](https://www.sphinx.dev). To run the deployment scripts, install the npm `devDependencies` with:
+For projects using `npm` to manage dependencies (recommended):
 
 ```bash
-`npm ci --also=dev`
+npm install @bananapus/721-hook-v6
 ```
 
-You'll also need to set up a `.env` file based on `.example.env`. Then run one of the following commands:
+For projects using `forge` to manage dependencies (not recommended):
 
-| Command                   | Description                  |
-| ------------------------- | ---------------------------- |
-| `npm run deploy:mainnets` | Propose mainnet deployments. |
-| `npm run deploy:testnets` | Propose testnet deployments. |
+```bash
+forge install Bananapus/nana-721-hook-v6
+```
 
-Your teammates can review and approve the proposed deployments in the Sphinx UI. Once approved, the deployments will be executed.
+If you're using `forge` to manage dependencies, add `libs = ["node_modules", "lib"]` to `foundry.toml` so Foundry resolves imports from both locations. No `remappings.txt` needed.
 
-#### Without Sphinx
+## Develop
 
-You can use the Sphinx CLI to run the deployment scripts without paying for Sphinx. First, install the npm `devDependencies` with:
+`nana-721-hook-v6` uses [npm](https://www.npmjs.com/) (version >=20.0.0) for package management and the [Foundry](https://github.com/foundry-rs/foundry) development toolchain for builds, tests, and deployments. To get set up, [install Node.js](https://nodejs.org/en/download) and install [Foundry](https://github.com/foundry-rs/foundry):
 
 ```bash
-`npm ci --also=dev`
+curl -L https://foundry.paradigm.xyz | sh
 ```
 
-You can deploy the contracts like so:
+You can download and install dependencies with:
 
 ```bash
-PRIVATE_KEY="0x123..." RPC_ETHEREUM_SEPOLIA="https://rpc.ankr.com/eth_sepolia" npx sphinx deploy script/Deploy.s.sol --network ethereum_sepolia
+npm ci && forge install
 ```
 
-This example deploys `nana-721-hook` to the Sepolia testnet using the specified private key. You can configure new networks in `foundry.toml`.
+If you run into trouble with `forge install`, try using `git submodule update --init --recursive` to ensure that nested submodules have been properly initialized.
 
-### Tips
+Some useful commands:
 
-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.
+| Command | Description |
+| --- | --- |
+| `forge build` | Compile the contracts and write artifacts to `out`. |
+| `forge fmt` | Lint. |
+| `forge test` | Run the tests. |
+| `forge build --sizes` | Get contract sizes. |
+| `forge coverage` | Generate a test coverage report. |
+| `foundryup` | Update Foundry. Run this periodically. |
+| `forge clean` | Remove the build artifacts and cache directories. |
 
-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:
+To learn more, visit the [Foundry Book](https://book.getfoundry.sh/) docs.
 
-```bash
-forge remappings >> remappings.txt
-```
+### Configuration
 
-This makes the extension aware of default remappings.
+Key settings from `foundry.toml`:
 
-## Repository Layout
+| Setting | Value |
+| --- | --- |
+| Solidity compiler | ^0.8.26 |
+| EVM target | cancun |
+| Optimizer runs | 200 |
+| Fuzz runs | 4,096 |
+| Invariant runs | 1,024 |
+| Invariant depth | 100 |
 
-The root directory contains this README, an MIT license, and config files. The important source directories are:
+## Repository Layout
 
 ```
-nana-721-hook/
+nana-721-hook-v6/
 ├── script/
-│   ├── Deploy.s.sol - Deploys core contracts - the hook store, deployer, and project deployer.
-│   ├── LaunchProjectFor.s.sol - (DEPRECATED) Deploys a project with a 721 tiers hook.
+│   ├── Deploy.s.sol - Deploys the hook store, hook deployer, and project deployer.
 │   └── helpers/
 │       └── Hook721DeploymentLib.sol - Internal helpers for deployment scripts.
-├── src/ - Contract source code. Top level contains implementation contracts.
-│   ├── JB721TiersHook.sol - The core tiered NFT pay/cash out hook.
-│   ├── JB721TiersHookDeployer.sol - Deploys an NFT hook for a project.
-│   ├── JB721TiersHookProjectDeployer.sol - Deploys a project with a tiered NFT hook.
-│   ├── JB721TiersHookStore.sol - Stores and manages data for tiered NFT hooks.
+├── src/
+│   ├── JB721TiersHook.sol - The core tiered NFT pay/cash out hook (794 lines).
+│   ├── JB721TiersHookDeployer.sol - Deploys a hook clone for an existing project (115 lines).
+│   ├── JB721TiersHookProjectDeployer.sol - Deploys a project with a hook (418 lines).
+│   ├── JB721TiersHookStore.sol - Shared data store for all hooks (1,240 lines).
 │   ├── abstract/
-│   │   ├── JB721Hook.sol - Abstract base hook: handles pay/cash out lifecycle, metadata, and terminal validation.
-│   │   └── ERC721.sol - Clone-compatible abstract ERC-721 implementation with mutable name/symbol.
-│   ├── interfaces/ - Contract interfaces.
-│   ├── libraries/ - Libraries (includes JB721TiersHookLib for tier adjustments, split distribution, price normalization, and token URI resolution).
-│   └── structs/ - Structs.
-└── test/ - Forge tests and testing utilities.
+│   │   ├── JB721Hook.sol - Abstract base: pay/cash out lifecycle, metadata, terminal validation.
+│   │   └── ERC721.sol - Clone-compatible ERC-721 with mutable name/symbol.
+│   ├── interfaces/
+│   │   ├── IJB721Hook.sol
+│   │   ├── IJB721TiersHook.sol
+│   │   ├── IJB721TiersHookDeployer.sol
+│   │   ├── IJB721TiersHookProjectDeployer.sol
+│   │   ├── IJB721TiersHookStore.sol
+│   │   └── IJB721TokenUriResolver.sol
+│   ├── libraries/
+│   │   ├── JB721TiersHookLib.sol - Tier adjustments, split distribution, price normalization, URI resolution.
+│   │   ├── JB721TiersRulesetMetadataResolver.sol - Pack/unpack per-ruleset metadata.
+│   │   ├── JB721Constants.sol - DISCOUNT_DENOMINATOR = 200.
+│   │   ├── JBBitmap.sol - Word-based bitmap for removed tier tracking.
+│   │   └── JBIpfsDecoder.sol - Decodes bytes32-encoded IPFS CIDv0 hashes.
+│   └── structs/
+│       ├── JB721Tier.sol - Read-only tier view.
+│       ├── JB721TierConfig.sol - Tier configuration input.
+│       ├── JBStored721Tier.sol - Packed on-chain tier storage.
+│       ├── JB721InitTiersConfig.sol - Tiers + currency + decimals.
+│       ├── JBDeploy721TiersHookConfig.sol - Full hook deployment config.
+│       ├── JB721TiersHookFlags.sol - Hook-wide boolean flags.
+│       ├── JB721TiersRulesetMetadata.sol - Per-ruleset options.
+│       ├── JB721TiersMintReservesConfig.sol - Reserve minting input.
+│       ├── JB721TiersSetDiscountPercentConfig.sol - Discount change input.
+│       ├── JBBitmapWord.sol - Single bitmap word.
+│       ├── JBLaunchProjectConfig.sol - Project launch config.
+│       ├── JBLaunchRulesetsConfig.sol - Ruleset launch config.
+│       ├── JBPayDataHookRulesetConfig.sol - Ruleset config with data hook.
+│       ├── JBPayDataHookRulesetMetadata.sol - Ruleset metadata with data hook fields.
+│       └── JBQueueRulesetsConfig.sol - Queue rulesets config.
+└── test/
     ├── E2E/
-    │   └── Pay_Mint_Redeem_E2E.t.sol - End-to-end test for minting and redeeming NFTs.
-    ├── unit/ - Unit tests for various components..
-    └── utils/ - Miscellaneous testing utilities.
-```
-
-Other directories:
-
-```
-nana-721-hook/
-├── .github/
-│   └── workflows/ - CI/CD workflows.
-└── deployments/ - Sphinx deployment logs.
-```
-
-## Architecture
-
-```mermaid
-graph TD;
-    A[JB721TiersHookProjectDeployer] -->|Launches & queues rulesets for| B[Juicebox projects]
-    D[JB721TiersHookDeployer] -->|Adds NFT hooks to| B
-    A -->|Deploys| C[JB721TiersHook]
-    D -->|Deploys| C
-    B -->|Calls upon pay/cash out| C
-    C -->|Stores data in| E[JB721TiersHookStore]
-    B -->|Uses| F[Pay/cash out terminal]
-    C -->|Mints NFTs upon payment through| F
-    C -->|Burns NFTs to reclaim funds through| F
+    │   └── Pay_Mint_Redeem_E2E.t.sol - End-to-end payment, minting, and cash out test.
+    ├── unit/
+    │   ├── pay_Unit.t.sol - Payment and minting logic.
+    │   ├── pay_CrossCurrency_Unit.t.sol - Cross-currency price normalization.
+    │   ├── redeem_Unit.t.sol - Cash out (burn-to-reclaim) logic.
+    │   ├── adjustTier_Unit.t.sol - Tier addition and removal.
+    │   ├── deployer_Unit.t.sol - Deployer contract tests.
+    │   ├── getters_constructor_Unit.t.sol - View functions and initialization.
+    │   ├── mintFor_mintReservesFor_Unit.t.sol - Owner minting and reserve minting.
+    │   ├── splitHookDistribution_Unit.t.sol - Split hook fund routing.
+    │   ├── tierSplitRouting_Unit.t.sol - Per-tier split recipient routing.
+    │   ├── JB721TiersRulesetMetadataResolver.t.sol - Metadata pack/unpack.
+    │   ├── JBBitmap.t.sol - Bitmap operations.
+    │   ├── JBIpfsDecoder.t.sol - IPFS URI decoding.
+    │   └── TierSupplyReserveCheck.t.sol - Supply and reserve boundary checks.
+    ├── fork/
+    │   ├── ERC20CashOutFork.t.sol - ERC-20 token cash out on fork.
+    │   ├── ERC20TierSplitFork.t.sol - ERC-20 tier split distribution on fork.
+    │   └── IssueTokensForSplitsFork.t.sol - Token issuance with split flag on fork.
+    ├── invariants/
+    │   ├── TierLifecycleInvariant.t.sol - Tier add/remove/mint lifecycle invariants.
+    │   ├── TieredHookStoreInvariant.t.sol - Store-level data consistency invariants.
+    │   └── handlers/ - Invariant test handler contracts.
+    ├── regression/
+    │   ├── BrokenTerminalDoesNotDos.t.sol - Broken terminal does not cause DoS.
+    │   ├── CacheTierLookup.t.sol - Tier cache regression.
+    │   ├── ProjectDeployerRulesets.t.sol - Project deployer ruleset handling.
+    │   ├── ReserveBeneficiaryOverwrite.t.sol - Reserve beneficiary overwrite edge case.
+    │   ├── SplitDistributionBugs.t.sol - Split distribution edge cases.
+    │   └── SplitNoBeneficiary.t.sol - Split with no beneficiary.
+    ├── 721HookAttacks.t.sol - Attack vector tests (reentrancy, manipulation).
+    ├── Fork.t.sol - General fork tests.
+    ├── TestAuditGaps.sol - Audit gap coverage.
+    ├── TestSafeTransferReentrancy.t.sol - safeTransferFrom reentrancy tests.
+    ├── TestVotingUnitsLifecycle.t.sol - Voting unit lifecycle tests.
+    └── utils/ - Shared test helpers and base workflows.
 ```
 
-### Contracts
-
-| Contract                                                                                                                          | Description                                                                                             |
-| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| [`JB721Hook.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/abstract/JB721Hook.sol)                                 | Abstract base for 721 hooks: handles pay/cash out lifecycle, terminal validation, and metadata resolution. |
-| [`JB721TiersHook.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHook.sol)                               | The core tiered NFT pay/cash out hook implementation, extending `JB721Hook`.                              |
-| [`JB721TiersHookDeployer.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHookDeployer.sol)               | Exposes a `deployHookFor(…)` function which allows deploys an NFT hook for a project.                   |
-| [`JB721TiersHookProjectDeployer.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHookProjectDeployer.sol) | Exposes a `launchProjectFor(…)` function which deploys a project with a tiered NFT hook already set up. |
-| [`JB721TiersHookStore.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHookStore.sol)                     | Stores and manages data for tiered NFT hooks.                                                           |
-
-## Description
-
-### Hooks
-
-This contract is a _data hook_, a _pay hook_, and a _cash out hook_. Data hooks receive information about a payment or a cash out, and put together a payload for the pay/cash out hook to execute.
-
-Juicebox projects can specify a data hook in their `JBRulesetMetadata`. When someone attempts to pay or cash out from the project, the project's terminal records the payment in the terminal store, passing information about the payment/cash out to the data hook in the process. The data hook responds with a list of payloads – each payload specifies the address of a pay/cash out hook, as well as some custom data and an amount of funds to send to that pay/cash out hook.
-
-Each pay/cash out hook can then execute custom behavior based on the custom data (and funds) they receive.
-
-### Mechanism
-
-A project using a 721 tiers hook can specify any number of NFT tiers (up to 65,535 total).
-
-- 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.
-
-Each tier has the following properties:
-
-- A price (up to `uint104`).
-- A supply (the maximum number of NFTs which can be minted from the tier, up to 999,999,999).
-- A token URI (artwork and metadata), which can be overridden by a URI resolver. The URI resolver can return unique values for each NFT in the tier.
-- A category, so tiers can be organized and accessed for different purposes.
-- A discount percent (optional). Reduces the effective purchase price. The discount is out of 200, so a `discountPercent` of 100 means 50% off, and 200 means free. The discount can be changed later via `setDiscountPercentOf`, and tiers can be configured with `cannotIncreaseDiscountPercent` to only allow discounts to decrease. Cash out weight is always based on the original tier price, not the discounted price.
-- A reserve frequency (optional). With a reserve frequency of 5, an extra NFT will be minted to a pre-specified beneficiary address for every 5 NFTs purchased and minted from the tier. Tiers with owner minting enabled cannot have reserves.
-- Voting units (optional). By default, each NFT's voting power equals its tier price. If `useVotingUnits` is true, a custom `votingUnits` value is used instead.
-- A flag to specify whether the NFTs in the tier can always be transferred, or if transfers can be paused depending on the project's ruleset.
-- A flag to specify whether the contract's owner can mint NFTs from the tier on-demand.
-- A split percent and a set of splits (optional). Each tier can route a percentage of its mint price to configured split recipients every time an NFT from the tier is purchased. The remaining funds stay in the project's balance. The `splitPercent` is out of `JBConstants.SPLITS_TOTAL_PERCENT` (1,000,000,000). Split recipients follow the same priority as JBMultiTerminal: `split.hook` (receives funds via `IJBSplitHook.processSplitWith` with full context including token, amount, decimals, project ID, and group ID) > `split.projectId` (routed via the project's primary terminal) > `split.beneficiary` (direct transfer). When splits are active, the hook adjusts the returned weight so the terminal only mints tokens proportional to the amount that actually enters the project treasury (e.g., a 50% split on a 1 ETH payment results in half the normal token issuance). This weight adjustment can be disabled with the `issueTokensForSplits` flag, which gives payers full token credit regardless of where the funds go.
-- A set of flags which restrict tiers added in the future (the votes/reserved frequency/on-demand minting/overspending/issueTokensForSplits flags noted above).
+36 test files. 5,167 lines of source code across `src/`.
 
-Additional notes:
+## Permissions
 
-- A payer can specify any number of tiers to mint as long as the total price does not exceed the amount being paid. If tiers aren't specified, the leftover amount is stored as pay credits (if allowed).
-- If the payment and a tier's price are specified in different currencies, the hook's immutable `PRICES` contract is used to normalize the values. If `PRICES` is the zero address and the currencies differ, the payment is silently ignored (no mint, no revert).
-- If some of a payment does not go towards purchasing an NFT, those extra funds will be stored as "NFT credits" which can be used for future purchases. Credits are only combined with the payment when `payer == beneficiary`. Optionally, the hook can disallow credits and reject payments with leftover funds (via `preventOverspending`).
-- 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.
-- The hook declares support for ERC-2981 (royalties) via `supportsInterface`, but does not implement the `royaltyInfo` function. This is intended for future extension.
+The following `JBPermissionIds` are checked by this hook:
 
-### Setup
+| Permission ID | Used by | Purpose |
+| --- | --- | --- |
+| `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Add or remove NFT tiers. |
+| `MINT_721` | `JB721TiersHook.mintFor` | Mint NFTs on-demand (only for tiers with `allowOwnerMint`). |
+| `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Change a tier's discount percent. |
+| `SET_721_METADATA` | `JB721TiersHook.setMetadataOf` | Update the hook's base URI, contract URI, token URI resolver, or encoded IPFS URIs. |
+| `QUEUE_RULESETS` | `JB721TiersHookProjectDeployer.queueRulesetsOf` | Queue new rulesets for the project through the project deployer. |
+| `SET_TERMINALS` | `JB721TiersHookProjectDeployer.launchRulesetsFor` | Set terminals when launching rulesets. |
 
-To use a 721 tiers hook, a Juicebox project should be created by a `JB721TiersHookProjectDeployer` instead of a `JBController`. The deployer will create a `JB721TiersHook` (through an associated `JB721TiersHookDeployer`) and add it to the project's first ruleset. New rulesets can be queued with `JB721TiersHookProjectDeployer.queueRulesetsOf(…)` if the project's owner gives the project deployer the permission [`JBPermissions.QUEUE_RULESETS`](https://github.com/Bananapus/nana-permission-ids/blob/master/src/JBPermissionIds.sol) (ID `2`) in [`JBPermissions`](https://github.com/Bananapus/nana-core/blob/main/src/JBPermissions.sol).
+All permissions are checked against the project owner via `_requirePermissionFrom`.
 
-It's also possible to add a 721 tiers hook to an existing project by calling `JB721TiersHookDeployer.deployHookFor(…)` and adding the hook to the project's ruleset – specifically, the project must set their [`JBRulesetMetadata.dataHook`](https://github.com/Bananapus/nana-core/blob/main/src/structs/JBRulesetMetadata.sol) to the newly deployed hook, and enable `JBRulesetMetadata.useDataHookForPay` and/or `JBRulesetMetadata.useDataHookForCashOut` depending on the functionality they'd like to enable.
+## Risks
 
-All `JB721TiersHook`s store their data in the `JB721TiersHookStore` contract.
+- **Gas scaling with tier count.** Several read paths (`balanceOf`, `totalCashOutWeight`, `tierOfTokenId`) iterate over all tier IDs up to `maxTierId`, including removed tiers. Projects with more than ~100 active tiers should budget gas carefully for governance reads and cash outs. The `cleanTiers` function on the store can help by compacting the tier linked list after removals.
+- **Cash out value dilution from pending reserves.** Pending reserve NFTs are included in the `totalCashOutWeight` denominator even before they are minted. In extreme cases (high reserve frequency, many unminted reserves), this can reduce cash out value for existing holders. This is by design -- it prevents a race condition where holders cash out before reserves are minted to capture a larger share.
+- **ERC-2981 not supported.** ERC-2981 royalty support was removed. `supportsInterface` returns `false` for `IERC2981`, and no `royaltyInfo` function exists.
+- **No reentrancy guard.** The hook does not use OpenZeppelin's `ReentrancyGuard`. Safety relies on state ordering: tokens are minted and balances are updated before any external calls. The `safeTransferFrom` callback in ERC-721 is a potential reentrancy surface, but state is already settled by the time it fires.
+- **Immutable price feeds.** The `PRICES` contract is set at deployment and cannot be changed. If a price feed reverts (e.g., stale Chainlink data), all cross-currency minting operations for that pair will also revert until the feed recovers. Same-currency operations are unaffected.
+- **Clone architecture.** Each `JB721TiersHook` is deployed as a minimal proxy (clone) of a reference implementation. The reference implementation's immutable storage slots (DIRECTORY, PRICES, RULESETS, STORE, SPLITS) are shared across all clones. If the reference implementation has a bug, all clones are affected.
+- **Silent skip on currency mismatch without PRICES.** If the hook's `PRICES` is the zero address and a payment arrives in a different currency than the tier prices, the payment is silently ignored -- no NFTs are minted and no revert occurs. The payment funds still enter the project treasury.
+- **Discount percent denominator.** The discount denominator is 200, not 100 or 10,000. A `discountPercent` of 100 means 50% off, not 100% off. Setting it to 200 makes the tier free.
+- **Removed tiers still occupy ID space.** Removing a tier marks it in a bitmap but does not reclaim the tier ID. Iteration still traverses removed IDs (skipping them), so removing tiers does not reduce gas costs for reads until `cleanTiers` is called.

package/RISKS.md

@@ -6,7 +6,9 @@
 - **Tier configuration is partially immutable.** Once created: `price`, `initialSupply`, `reserveFrequency`, `category`, `votingUnits`, `splitPercent` are permanent. Mutable: `discountPercent` (owner-controlled, subject to `cannotIncreaseDiscountPercent`), `encodedIPFSUri` (owner-controlled).
 - **Category sort order is enforced only at insertion.** `recordAddTiers` reverts `InvalidCategorySortOrder` if tiers are not ascending by category. The sorted linked list (`_tierIdAfter`) depends on this invariant across all `adjustTiers` calls. Direct store callers could corrupt the list.
 - **`useReserveBeneficiaryAsDefault` has global side effects.** Setting this on ANY new tier overwrites `defaultReserveBeneficiaryOf` for ALL existing tiers that lack a tier-specific `_reserveBeneficiaryOf` entry. Documented but dangerous when calling `adjustTiers` on hooks with existing tiers.
-- **Clone initialization is one-shot, atomic.** `initialize()` guards via `PROJECT_ID != 0`. Deployer contracts call deploy+initialize in a single transaction, preventing front-running. Ownership transfers to `_msgSender()` at the end of `initialize`.
+- **Clone initialization is one-shot, atomic.** `initialize()` guards via `PROJECT_ID != 0`. Since `PROJECT_ID` is a storage variable (not immutable), both the implementation and fresh clones start at zero. After `initialize()` sets it, any subsequent call reverts. Deployer contracts call deploy+initialize in a single transaction, preventing front-running. Ownership transfers to `_msgSender()` at the end of `initialize`.
+- **`balanceOf(address(0))` reverts.** Unlike the standard ERC-721 `balanceOf` which may return zero, the hook overrides `balanceOf` to revert with `JB721TiersHook_ZeroAddress` when called with `address(0)`. This guards against misleading zero-balance results for the zero address.
+- **`tokenURI` reverts for nonexistent tokens.** Calling `tokenURI` with a token ID that has never been minted reverts with `ERC721NonexistentToken(tokenId)`. The check is `_ownerOf(tokenId) == address(0)`.
 - **JBDirectory is trusted for terminal authentication.** `afterPayRecordedWith` and `afterCashOutRecordedWith` check `DIRECTORY.isTerminalOf()`. If the directory is compromised, arbitrary addresses can invoke pay/cashout hooks.
 - **JBPrices is trusted for cross-currency conversion.** A reverting price feed blocks all payments in non-matching currencies (DoS, not fund loss). If `address(prices) == address(0)`, cross-currency payments silently skip minting.
 
@@ -20,6 +22,7 @@
 - **Currency mismatch silently skips minting.** If payment currency differs from tier pricing currency and `PRICES == address(0)`, `_processPayment` returns without minting or reverting. Funds enter the project balance, no NFTs issued, no credits created (the normalized value is 0).
 - **`splitPercent` reduces minting weight.** `beforePayRecordedWith` scales down the weight returned to the terminal by `(amountValue - totalSplitAmount) / amountValue`. Payers receive fewer fungible tokens for the split portion. `issueTokensForSplits` flag overrides this to give full weight.
 - **Reserved NFT minting is permissionless.** Anyone can call `mintPendingReservesFor` to mint pending reserves to the tier's beneficiary. Only gated by the `mintPendingReservesPaused` ruleset flag. Timing of reserve minting is not owner-controlled.
+- **Cross-reference: `PRICES == address(0)` behavior.** When `address(prices) == address(0)`, cross-currency payments skip minting silently (see Trust Assumptions section 1 and Accepted Behaviors section 8.3). This is the same address stored during `initialize()` — clones that omit the prices parameter get `address(0)` permanently.
 
 ## 3. Reentrancy Surface
 
@@ -33,6 +36,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.
@@ -75,3 +82,17 @@
 - **Cash out weight uses full price regardless of discount:** `cashOutWeightOf` for any token returns the tier's stored `price`, not the discounted purchase price.
 - **Discount monotonicity when locked:** If `cannotIncreaseDiscountPercent` is set, `discountPercent` can only decrease or stay the same.
 - **Flags are append-only restrictions:** `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting` prevent future tiers from using those features but do not retroactively affect existing tiers.
+
+## 8. Accepted Behaviors
+
+### 8.1 Pending reserves inflate `totalCashOutWeight` denominator (by design)
+
+`totalCashOutWeight` includes `price * pendingReserves` for unminted reserve NFTs. This dilutes per-NFT reclaim value before reserves are actually minted. This is intentional: if pending reserves were excluded, a holder could front-run `mintPendingReservesFor` to cash out at an inflated per-NFT value, then the reserve mint would reduce the remaining holders' share. Including pending reserves in the denominator ensures that the reserve allocation is priced in at all times, preventing front-running. The trade-off is that minting reserves (via the permissionless `mintPendingReservesFor`) does not change individual cash-out values — the reserves are already accounted for.
+
+### 8.2 Cash-out weight uses full price regardless of discount (by design)
+
+`cashOutWeightOf` returns the tier's stored `price`, not the discounted purchase price. An NFT bought at 50% discount has the same cash-out weight as one bought at full price. This is intentional: the cash-out weight represents the NFT's share of the project's treasury, not the purchase price paid. Changing cash-out weight based on discount would require per-token storage of purchase price, adding significant gas cost. The discount mechanism is designed for promotional pricing, not for creating tiered cash-out classes.
+
+### 8.3 Currency mismatch silently skips minting (accepted degradation)
+
+If the payment currency differs from the tier pricing currency and `PRICES == address(0)`, `_processPayment` returns without minting NFTs or creating credits. Funds enter the project balance but no NFTs are issued. This is accepted because: (1) reverting would block all payments in the mismatched currency, (2) the project owner chose not to configure price feeds (by not setting `PRICES`), and (3) the funds are not lost — they increase the project's surplus and are reclaimable via cash-out. Projects that need cross-currency NFT minting must configure `JBPrices`.