@bananapus/721-hook-v6 0.0.18 → 0.0.20

package/ADMINISTRATION.md

@@ -6,7 +6,7 @@ Admin privileges and their scope in nana-721-hook-v6.
 
 ### Hook Owner (JBOwnable)
 
-- **Assigned by**: `initialize()` transfers ownership to the caller (line 285 of `JB721TiersHook.sol`). When deployed via `JB721TiersHookProjectDeployer.launchProjectFor()`, ownership is transferred to the project NFT (line 101 of `JB721TiersHookProjectDeployer.sol`), meaning the project owner controls the hook.
+- **Assigned by**: `initialize()` transfers ownership to the caller. When deployed via `JB721TiersHookProjectDeployer.launchProjectFor()`, ownership is transferred to the project NFT, meaning the project owner controls the hook.
 - **Scope**: Per-hook instance. Each cloned hook has its own independent owner.
 - **Inheritance**: `JBOwnable` supports both EOA ownership and project-based ownership (owner = holder of the project's ERC-721 NFT). When ownership is transferred to a project via `transferOwnershipToProject()`, whoever owns that project NFT becomes the hook's owner.
 
@@ -20,7 +20,7 @@ Admin privileges and their scope in nana-721-hook-v6.
 
 - **Assigned by**: The project's `JBDirectory` configuration.
 - **Scope**: Only a contract registered as a terminal for the hook's project in `JBDirectory` can call `afterPayRecordedWith()` and `afterCashOutRecordedWith()`.
-- **Verification**: `DIRECTORY.isTerminalOf(projectId, IJBTerminal(msg.sender))` is checked at lines 195-197 and 236-237 of `JB721Hook.sol`.
+- **Verification**: `DIRECTORY.isTerminalOf(projectId, IJBTerminal(msg.sender))` is checked in `JB721Hook.sol`.
 
 ### Store Callers (msg.sender Trust Model)
 
@@ -34,49 +34,49 @@ Admin privileges and their scope in nana-721-hook-v6.
 
 | Function | Permission ID | Checked Against | What It Does |
 |----------|--------------|-----------------|--------------|
-| `adjustTiers()` (line 322) | `ADJUST_721_TIERS` | `owner()` | Adds new tiers and/or soft-removes existing tiers. Sets tier split groups in JBSplits. |
-| `mintFor()` (line 338) | `MINT_721` | `owner()` | Manually mints NFTs from tiers that have `allowOwnerMint` enabled. Bypasses price checks (passes `type(uint256).max` as amount). |
-| `setDiscountPercentOf()` (line 389) | `SET_721_DISCOUNT_PERCENT` | `owner()` | Sets the discount percentage for a single tier. |
-| `setDiscountPercentsOf()` (line 399) | `SET_721_DISCOUNT_PERCENT` | `owner()` | Batch-sets discount percentages for multiple tiers. |
-| `setMetadata()` (line 430) | `SET_721_METADATA` | `owner()` | Updates collection name, symbol, baseURI, contractURI, tokenUriResolver, and/or per-tier encoded IPFS URIs. Empty strings leave values unchanged. |
-| `initialize()` (line 223) | None (one-time) | `PROJECT_ID == 0` check | Initializes a cloned hook. Can only be called once. Transfers ownership to caller on completion. |
+| `adjustTiers()` | `ADJUST_721_TIERS` | `owner()` | Adds new tiers and/or soft-removes existing tiers. Sets tier split groups in JBSplits. |
+| `mintFor()` | `MINT_721` | `owner()` | Manually mints NFTs from tiers that have `allowOwnerMint` enabled. Bypasses price checks (passes `type(uint256).max` as amount). |
+| `setDiscountPercentOf()` | `SET_721_DISCOUNT_PERCENT` | `owner()` | Sets the discount percentage for a single tier. |
+| `setDiscountPercentsOf()` | `SET_721_DISCOUNT_PERCENT` | `owner()` | Batch-sets discount percentages for multiple tiers. |
+| `setMetadata()` | `SET_721_METADATA` | `owner()` | Updates collection name, symbol, baseURI, contractURI, tokenUriResolver, and/or per-tier encoded IPFS URIs. Empty strings leave values unchanged. |
+| `initialize()` | None (one-time) | `PROJECT_ID == 0` check | Initializes a cloned hook. Can only be called once. Transfers ownership to caller on completion. |
 
 ### JB721TiersHookProjectDeployer
 
 | Function | Permission ID | Checked Against | What It Does |
 |----------|--------------|-----------------|--------------|
-| `launchProjectFor()` (line 74) | None | Anyone can call | Creates a new project with a 721 hook. Ownership goes to the specified `owner` address. |
-| `launchRulesetsFor()` (line 115) | `QUEUE_RULESETS` + `SET_TERMINALS` | Project NFT owner | Deploys a hook and launches rulesets for an existing project. |
-| `queueRulesetsOf()` (line 164) | `QUEUE_RULESETS` | Project NFT owner | Deploys a hook and queues rulesets for an existing project. |
+| `launchProjectFor()` | None | Anyone can call | Creates a new project with a 721 hook. Ownership goes to the specified `owner` address. |
+| `launchRulesetsFor()` | `QUEUE_RULESETS` + `SET_TERMINALS` | Project NFT owner | Deploys a hook and launches rulesets for an existing project. |
+| `queueRulesetsOf()` | `QUEUE_RULESETS` | Project NFT owner | Deploys a hook and queues rulesets for an existing project. |
 
 ### JB721TiersHookDeployer
 
 | Function | Permission ID | Checked Against | What It Does |
 |----------|--------------|-----------------|--------------|
-| `deployHookFor()` (line 68) | None | Anyone can call | Clones and initializes a new hook instance. Ownership starts with the deployer contract, then is transferred to `msg.sender`. |
+| `deployHookFor()` | None | Anyone can call | Clones and initializes a new hook instance. Ownership starts with the deployer contract, then is transferred to `msg.sender`. |
 
 ### JB721Hook (Abstract Base)
 
 | Function | Required Caller | What It Does |
 |----------|----------------|--------------|
-| `afterPayRecordedWith()` (line 231) | Project terminal | Processes payment, mints NFTs. Verifies caller via `DIRECTORY.isTerminalOf()`. |
-| `afterCashOutRecordedWith()` (line 183) | Project terminal | Burns NFTs on cash out. Verifies caller via `DIRECTORY.isTerminalOf()` and that `msg.value == 0`. |
+| `afterPayRecordedWith()` | Project terminal | Processes payment, mints NFTs. Verifies caller via `DIRECTORY.isTerminalOf()`. |
+| `afterCashOutRecordedWith()` | Project terminal | Burns NFTs on cash out. Verifies caller via `DIRECTORY.isTerminalOf()` and that `msg.value == 0`. |
 
 ### JB721TiersHookStore (No Access Control -- msg.sender Keyed)
 
 | Function | Caller | What It Does |
 |----------|--------|--------------|
-| `recordAddTiers()` (line 772) | Hook contract | Adds tiers to the caller's namespace. Category sort order enforced. |
-| `recordRemoveTierIds()` (line 1139) | Hook contract | Marks tiers as removed in bitmap. Respects `cannotBeRemoved` flag. |
-| `recordMint()` (line 1020) | Hook contract | Records mints, decrements supply, enforces price and reserve checks. |
-| `recordMintReservesFor()` (line 1103) | Hook contract | Mints reserved NFTs from a tier. |
-| `recordBurn()` (line 995) | Hook contract | Increments burn counter for token IDs. |
-| `recordFlags()` (line 1010) | Hook contract | Sets behavioral flags for the caller's hook. |
-| `recordSetTokenUriResolver()` (line 1193) | Hook contract | Sets the token URI resolver. |
-| `recordSetEncodedIPFSUriOf()` (line 1187) | Hook contract | Sets the encoded IPFS URI for a tier. |
-| `recordSetDiscountPercentOf()` (line 1161) | Hook contract | Updates a tier's discount percent. Enforces bounds and `cannotIncreaseDiscountPercent`. |
-| `recordTransferForTier()` (line 1201) | Hook contract | Updates per-tier balance tracking on transfer. |
-| `cleanTiers()` (line 726) | Anyone | Reorganizes the tier sorting linked list to skip removed tiers. Pure bookkeeping, no value at risk. |
+| `recordAddTiers()` | Hook contract | Adds tiers to the caller's namespace. Category sort order enforced. |
+| `recordRemoveTierIds()` | Hook contract | Marks tiers as removed in bitmap. Respects `cannotBeRemoved` flag. |
+| `recordMint()` | Hook contract | Records mints, decrements supply, enforces price and reserve checks. |
+| `recordMintReservesFor()` | Hook contract | Mints reserved NFTs from a tier. |
+| `recordBurn()` | Hook contract | Increments burn counter for token IDs. |
+| `recordFlags()` | Hook contract | Sets behavioral flags for the caller's hook. |
+| `recordSetTokenUriResolver()` | Hook contract | Sets the token URI resolver. |
+| `recordSetEncodedIPFSUriOf()` | Hook contract | Sets the encoded IPFS URI for a tier. |
+| `recordSetDiscountPercentOf()` | Hook contract | Updates a tier's discount percent. Enforces bounds and `cannotIncreaseDiscountPercent`. |
+| `recordTransferForTier()` | Hook contract | Updates per-tier balance tracking on transfer. |
+| `cleanTiers()` | Anyone | Reorganizes the tier sorting linked list to skip removed tiers. Pure bookkeeping, no value at risk. |
 
 ## Permission System
 
@@ -123,6 +123,16 @@ The following are set at deploy/initialization time and **cannot be changed afte
 | Per-tier `price` | `recordAddTiers()` | The base price (and cash-out weight) of NFTs in the tier |
 | Per-tier `category` | `recordAddTiers()` | The category grouping for sort order |
 
+## Clone Pattern
+
+`JB721TiersHook` is deployed as an implementation contract and then cloned via `LibClone.clone()` in `JB721TiersHookDeployer`. Each clone is a minimal proxy that delegates all calls to the implementation.
+
+**Admin implications:**
+- The implementation contract cannot be self-destructed or modified after deployment. Even if it could be, clones would break since they `delegatecall` to the implementation address.
+- Each clone has its own storage (including `PROJECT_ID`, ownership, and tier data). The implementation's storage is unused.
+- `METADATA_ID_TARGET` is set to the original implementation address, ensuring consistent metadata ID derivation across all clones.
+- The `initialize()` function uses a `PROJECT_ID == 0` guard (not OpenZeppelin `Initializable`) to prevent re-initialization. This is safe because `PROJECT_ID` is set during initialization and cannot return to zero.
+
 ## Ruleset-Level Pauses
 
 Two behaviors are controlled by the project's current ruleset metadata (packed into the 14-bit `metadata` field of `JBRulesetMetadata`), parsed by `JB721TiersRulesetMetadataResolver`:
@@ -142,10 +152,10 @@ What the hook owner **cannot** do:
 - **Cannot change tier prices after creation.** The `price` field in `JBStored721Tier` is set once in `recordAddTiers()` and never modified. Cash-out weight is always based on the original price.
 - **Cannot change reserve frequency after creation.** The `reserveFrequency` is immutable per tier.
 - **Cannot reduce a tier's initial supply.** Supply can only decrease through minting and burning.
-- **Cannot remove a tier marked `cannotBeRemoved`.** The store enforces this in `recordRemoveTierIds()` (line 1151).
-- **Cannot increase a tier's discount if `cannotIncreaseDiscountPercent` is set.** The store enforces this in `recordSetDiscountPercentOf()` (line 1176).
-- **Cannot mint from tiers without `allowOwnerMint`.** The `mintFor()` function passes `isOwnerMint: true` to the store, which checks the flag (line 1060).
-- **Cannot re-initialize a hook.** The `initialize()` function reverts if `PROJECT_ID != 0` (line 237).
+- **Cannot remove a tier marked `cannotBeRemoved`.** The store enforces this in `recordRemoveTierIds()`.
+- **Cannot increase a tier's discount if `cannotIncreaseDiscountPercent` is set.** The store enforces this in `recordSetDiscountPercentOf()`.
+- **Cannot mint from tiers without `allowOwnerMint`.** The `mintFor()` function passes `isOwnerMint: true` to the store, which checks the flag.
+- **Cannot re-initialize a hook.** The `initialize()` function reverts if `PROJECT_ID != 0`.
 - **Cannot change the pricing currency, decimals, or prices contract.** `PRICES` is immutable (set in constructor), and the currency/decimals in `_packedPricingContext` are set once during initialization.
 - **Cannot bypass the flag restrictions.** Once `noNewTiersWithReserves`, `noNewTiersWithVotes`, or `noNewTiersWithOwnerMinting` are set, all future tiers added via `adjustTiers()` must comply.
 - **Cannot mint more reserves than the formula allows.** Reserve mints are bounded by `ceil(nonReserveMints / reserveFrequency)`.

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
 
 ```
@@ -16,7 +20,11 @@ src/
 │   ├── JB721Hook.sol                 — Base ERC-721 + pay/cashout hook integration
 │   └── ERC721.sol                    — Minimal ERC-721 implementation
 ├── libraries/
-│   └── JB721TiersHookLib.sol         — Split calculations, price normalization, weight math, fund distribution
+│   ├── JB721Constants.sol            — Global constants (DISCOUNT_DENOMINATOR)
+│   ├── JB721TiersHookLib.sol         — Split calculations, price normalization, weight math, fund distribution
+│   ├── JB721TiersRulesetMetadataResolver.sol — Bit-packed 721 ruleset metadata (transfer/reserve pause flags)
+│   ├── JBBitmap.sol                  — Bitmap utilities for tier removal tracking
+│   └── JBIpfsDecoder.sol             — IPFS CID encoding/decoding for token URIs
 ├── interfaces/                       — All interfaces (IJB721TiersHook, etc.)
 └── structs/                          — Tier config, mint context, cash-out structs
 ```
@@ -31,23 +39,46 @@ User → JBMultiTerminal.pay(metadata)
     → convertSplitAmounts(): convert to payment token denomination (if currencies differ)
     → calculateWeight(): adjust weight down by split fraction
   → JBTerminalStore records payment
-  → afterPayRecordedWith()
+  → afterPayRecordedWith() → _processPayment()
+    → Normalize payment value to tier pricing currency
     → Decode tier IDs from metadata
     → For each tier:
       → Validate: not removed, not paused, supply available
       → Check price (with optional discount, normalized to tier pricing currency)
       → Mint NFT to beneficiary
+    → Leftover amount stored as pay credits (revert if overspending not allowed)
     → Distribute split funds (priority: split.hook > split.projectId > split.beneficiary)
-    → Leftover amount optionally mints best-available tiers
 ```
 
+#### Split Amount and Price Normalization
+
+Tiers can be priced in a different currency than the payment token (e.g. tiers priced in USD while payments arrive in ETH). The split/weight pipeline in `beforePayRecordedWith` resolves this in two steps:
+
+1. **`calculateSplitAmounts`** — For each tier the payer wants to mint, looks up its `splitPercent` (the fraction of the tier price that should be routed to the tier's split group rather than into the project treasury). Computes `effectivePrice * splitPercent / SPLITS_TOTAL_PERCENT` for each tier, where `effectivePrice` accounts for any active discount. Returns the total and a per-tier breakdown, all denominated in the **tier pricing currency**.
+
+2. **`convertSplitAmounts`** — If the payment currency differs from the tier pricing currency, converts every per-tier split amount (and the total) into the **payment token denomination** using `JBPrices`. This is necessary because the terminal will subtract the split amount from the payment value, so both must be in the same unit.
+
+After conversion, `calculateWeight` scales the terminal's minting weight down by the fraction of the payment that was routed to splits (unless the `issueTokensForSplits` flag is set, in which case the full weight is preserved).
+
+During `afterPayRecordedWith`, the payment value is separately normalized into the tier pricing currency via `normalizePaymentValue` so that tier prices can be compared against what was paid. The forwarded split funds are then distributed to each tier's split group by `distributeAll`.
+
+### Discount Mechanism
+
+Each tier has a `discountPercent` (0-200 scale where 200 = 100% discount / free mint). The project owner can adjust it via `setDiscountPercentOf`, subject to a per-tier `cannotIncreaseDiscountPercent` flag that prevents raising the discount once set. Discounts can only be decreased unless the tier explicitly allows increases.
+
+Key behaviors:
+- **Minting**: The store applies the discount when checking the price during `recordMint`, so payers pay less.
+- **Split calculations**: `calculateSplitAmounts` applies the discount to the tier price before computing the split portion, so splits are proportional to the actual amount paid.
+- **Cash-out weight**: Uses the **original undiscounted price**, not the effective price. This means a discounted NFT carries the same cash-out weight as a full-price one. Project owners should be aware that heavily discounted mints dilute the cash-out pool at full weight while contributing less to the treasury.
+
 ### NFT Cash Out
 ```
 Holder → JBMultiTerminal.cashOutTokensOf()
   → JB721TiersHook.afterCashOutRecordedWith()
     → Burn specified NFT token IDs
-    → Each NFT's cash-out weight contributes to reclaim amount
-    → Weight = tier.initialQuantity * tier.price (or custom)
+    → Each NFT's cash-out weight = tier.price (full price, ignoring discounts)
+    → Total cash-out weight (denominator) = sum of (tier.price * (outstanding + pending)) across all tiers
+    →   where outstanding = minted - burned, pending = pending reserve mints
 ```
 
 ### Tier Management
@@ -65,6 +96,22 @@ Owner → JB721TiersHook.adjustTiers()
 | Pay hook | `IJBPayHook` | Called after payment recorded |
 | Cash out hook | `IJBCashOutHook` | Called during cash out |
 
+## Design Decisions
+
+1. **Clone-based deployment** — `JB721TiersHookDeployer` uses Solady's `LibClone` to deploy minimal proxies of a reference `JB721TiersHook` instance. This keeps deployment cost low and consistent regardless of the hook contract's bytecode size. Each clone is initialized via `initialize()` (not a constructor), which sets the project ID, tiers, and flags. Deterministic deploys are supported via `cloneDeterministic` with a caller-scoped salt.
+
+2. **Separate store contract** — `JB721TiersHookStore` holds all tier data, mint tracking, and pricing logic in a standalone contract shared across hook instances. This serves two purposes: it keeps the hook contract under the EIP-170 size limit (24 KB), and it allows the store to act as the `msg.sender` for state mutations (tier additions use `msg.sender` as the hook key), providing a natural access-control boundary.
+
+3. **Category sorting instead of price sorting** — Tiers are stored in a linked list sorted by `category` (a uint24 grouping field), not by price. This lets projects organize NFTs into logical groups (e.g. membership tiers, collectibles, special editions) and query them by group. The `InvalidCategorySortOrder` error enforces that new tiers are added in non-decreasing category order.
+
+4. **Cash-out weight uses `initialSupply * price`** — The `totalCashOutWeight` denominator sums `price * (outstanding + pendingReserves)` across all tiers, where outstanding = minted minus burned. Each individual NFT's weight is simply its tier's `price`. Using the original undiscounted price (rather than what was actually paid) ensures that cash-out values are stable and predictable: discounts are treated as transient purchase incentives, not permanent reductions in an NFT's share of the treasury.
+
+5. **Library extraction for EIP-170 compliance** — `JB721TiersHookLib` contains split calculations, price normalization, fund distribution, tier adjustment logic, and IPFS URI decoding. These are called via `external` library functions (which deploy as a separate contract) or via `DELEGATECALL`. This pattern keeps the hook contract's deployed bytecode under the 24 KB limit while preserving the ability to emit events from the hook's address.
+
+6. **Discount denominator of 200** — The `discountPercent` field is a uint8 with a denominator of 200 (`JB721Constants.DISCOUNT_DENOMINATOR`). A value of 200 represents 100% discount (free mint), giving 0.5% granularity. The `cannotIncreaseDiscountPercent` flag on each tier lets project owners create promotional discounts that can be reduced but never increased beyond their initial level.
+
+7. **Split fund distribution with try-catch** — All external calls during split distribution (to split hooks, terminals, and beneficiaries) are wrapped in try-catch. A reverting recipient does not brick payments for the entire project.
+
 ## Dependencies
 - `@bananapus/core-v6` — Core protocol interfaces
 - `@bananapus/ownable-v6` — JB-aware ownership

package/AUDIT_INSTRUCTIONS.md

@@ -4,6 +4,66 @@ You are auditing the Juicebox V6 tiered NFT hook system. This hook allows Juiceb
 
 Read [ARCHITECTURE.md](./ARCHITECTURE.md) first for data flow context. Read [RISKS.md](./RISKS.md) for 19 known risks with test coverage mapping. Then come back here.
 
+## Compiler and Version Info
+
+| Setting | Value |
+|---------|-------|
+| Solidity version | ^0.8.26 |
+| EVM target | cancun |
+| Optimizer | enabled, 200 runs |
+| via-IR | not enabled |
+| Fuzz runs | 4,096 |
+| Invariant runs | 1,024 (depth 100) |
+
+Source: [`foundry.toml`](./foundry.toml)
+
+## Previous Audit Findings
+
+A Nemesis automated audit was conducted on 2026-03-17. Results are in [`.audit/findings/nemesis-verified.md`](./.audit/findings/nemesis-verified.md). Summary:
+
+| ID | Severity | Title | Status |
+|----|----------|-------|--------|
+| NM-001 | MEDIUM | Unprotected external calls in tier split distribution cascade to full payment revert | **Remediated** -- hook callbacks, terminal calls, and native-token sends in `_sendPayoutToSplit` are now wrapped in try-catch; ERC-20 beneficiary `safeTransfer` remains unwrapped (reverts only if the token itself reverts) |
+| NM-002 | LOW | `_addToBalance` silently drops funds when no primary terminal | Open |
+| NM-003 | LOW | Missing `splitPercent` bounds validation in `recordAddTiers` | **Remediated** -- `SplitPercentExceedsBounds` check added at `JB721TiersHookStore.sol:866` |
+| NM-004 | LOW | Implementation contract initializable | Open (no fund risk) |
+| NM-005 | LOW | `setMetadata` uses non-standard sentinel for tokenUriResolver | Open (documented behavior) |
+
+No prior formal audit with finding IDs from an external security firm has been conducted. See [RISKS.md](./RISKS.md) for the project's own risk assessment.
+
+## Error Reference
+
+| Error | Contract | Trigger Condition |
+|-------|----------|-------------------|
+| `JB721TiersHookStore_CantMintManually(uint256 tierId)` | JB721TiersHookStore | `recordMint` called with `isManualMint=true` on a tier with `allowOwnerMint=false` |
+| `JB721TiersHookStore_CantRemoveTier(uint256 tierId)` | JB721TiersHookStore | `recordRemoveTierIds` called on a tier with `cannotBeRemoved=true` |
+| `JB721TiersHookStore_DiscountPercentExceedsBounds(uint256 percent, uint256 limit)` | JB721TiersHookStore | `recordSetDiscountPercentOf` or `recordAddTiers` with `discountPercent > DISCOUNT_DENOMINATOR (200)` |
+| `JB721TiersHookStore_DiscountPercentIncreaseNotAllowed(uint256 percent, uint256 storedPercent)` | JB721TiersHookStore | `recordSetDiscountPercentOf` increases discount on a tier with `cannotIncreaseDiscountPercent=true` |
+| `JB721TiersHookStore_InsufficientPendingReserves(uint256 count, uint256 numberOfPendingReserves)` | JB721TiersHookStore | `recordMintReservesFor` called with `count > pendingReserves` |
+| `JB721TiersHookStore_InsufficientSupplyRemaining(uint256 tierId)` | JB721TiersHookStore | `recordMint` when `remainingSupply < pendingReserves` after decrement |
+| `JB721TiersHookStore_InvalidCategorySortOrder(uint256 tierCategory, uint256 previousTierCategory)` | JB721TiersHookStore | `recordAddTiers` with tiers not in ascending category order |
+| `JB721TiersHookStore_InvalidQuantity(uint256 quantity, uint256 limit)` | JB721TiersHookStore | `recordAddTiers` with `initialSupply >= _ONE_BILLION` |
+| `JB721TiersHookStore_ManualMintingNotAllowed(uint256 tierId)` | JB721TiersHookStore | `recordMint` called as manual mint when `noNewTiersWithOwnerMinting` flag is set and tier allows it |
+| `JB721TiersHookStore_MaxTiersExceeded(uint256 numberOfTiers, uint256 limit)` | JB721TiersHookStore | `recordAddTiers` would push `maxTierIdOf` above `type(uint16).max` (65,535) |
+| `JB721TiersHookStore_PriceExceedsAmount(uint256 price, uint256 leftoverAmount)` | JB721TiersHookStore | `recordMint` when tier's (discounted) price exceeds remaining payment amount |
+| `JB721TiersHookStore_ReserveFrequencyNotAllowed(uint256 tierId)` | JB721TiersHookStore | `recordAddTiers` with `reserveFrequency > 0` when `noNewTiersWithReserves` flag is set |
+| `JB721TiersHookStore_SplitPercentExceedsBounds(uint256 percent, uint256 limit)` | JB721TiersHookStore | `recordAddTiers` with `splitPercent` exceeding bounds |
+| `JB721TiersHookStore_TierRemoved(uint256 tierId)` | JB721TiersHookStore | `recordMint` or `recordSetDiscountPercentOf` called on a removed tier |
+| `JB721TiersHookStore_UnrecognizedTier(uint256 tierId)` | JB721TiersHookStore | Any operation referencing a `tierId` that does not exist (> `maxTierIdOf` or never created) |
+| `JB721TiersHookStore_VotingUnitsNotAllowed(uint256 tierId)` | JB721TiersHookStore | `recordAddTiers` with `votingUnits > 0` when `noNewTiersWithVotes` flag is set |
+| `JB721TiersHookStore_ZeroInitialSupply(uint256 tierId)` | JB721TiersHookStore | `recordAddTiers` with `initialSupply == 0` |
+| `JB721TiersHook_AlreadyInitialized(uint256 projectId)` | JB721TiersHook | `initialize()` called on a hook that already has `PROJECT_ID != 0` |
+| `JB721TiersHook_CurrencyMismatch(uint256 paymentCurrency, uint256 tierCurrency)` | JB721TiersHook | Payment currency differs from tier pricing currency and no price feed is configured |
+| `JB721TiersHook_InvalidPricingDecimals(uint256 decimals)` | JB721TiersHook | `initialize()` with `pricingDecimals > 18` |
+| `JB721TiersHook_MintReserveNftsPaused()` | JB721TiersHook | `mintPendingReservesFor` called when `mintPendingReservesPaused` ruleset flag is active |
+| `JB721TiersHook_NoProjectId()` | JB721TiersHook | `initialize()` called with `projectId == 0` |
+| `JB721TiersHook_Overspending(uint256 leftoverAmount)` | JB721TiersHook | Payment has leftover after minting and `allowOverspending` metadata flag is false |
+| `JB721TiersHook_TierTransfersPaused()` | JB721TiersHook | NFT transfer attempted on a tier with `transfersPausable=true` when `transfersPaused` ruleset flag is active |
+| `JB721Hook_InvalidCashOut()` | JB721Hook | `afterCashOutRecordedWith` called by a non-terminal address |
+| `JB721Hook_InvalidPay()` | JB721Hook | `afterPayRecordedWith` called by a non-terminal address |
+| `JB721Hook_UnauthorizedToken(uint256 tokenId, address holder)` | JB721Hook | `afterCashOutRecordedWith` with a token ID not owned by the cash-out holder |
+| `JB721Hook_UnexpectedTokenCashedOut()` | JB721Hook | `beforeCashOutRecordedWith` called with `cashOutCount > 0` (fungible tokens cannot be cashed out through this hook) |
+
 ## Architecture
 
 Four contracts, one library:
@@ -14,7 +74,7 @@ Four contracts, one library:
 | `JB721TiersHookStore` | ~1230 | All tier state. Keyed by `msg.sender` (the hook address). Manages tier CRUD, supply tracking, reserve accounting, bitmap-based removal, sorted linked list, transfer balance tracking, voting units, discount enforcement. |
 | `JB721TiersHookDeployer` | ~115 | Deploys hook clones (Solady `LibClone`). Optional deterministic addressing via salt. Atomic deploy + initialize + ownership transfer. Registers with `JBAddressRegistry`. |
 | `JB721TiersHookProjectDeployer` | ~420 | Convenience: launches a project + hook in one transaction. Converts `JBPayDataHookRulesetConfig` to `JBRulesetConfig` with `useDataHookForPay: true` hardcoded. Also supports `launchRulesetsFor` and `queueRulesetsOf`. |
-| `JB721TiersHookLib` (library) | ~607 | Extracted logic for EIP-170 compliance. Tier adjustments, split amount calculation, price normalization, weight adjustment, split fund distribution, token URI resolution. Called via DELEGATECALL from the hook. |
+| `JB721TiersHookLib` (library) | ~634 | Extracted logic for EIP-170 compliance. Tier adjustments, split amount calculation, price normalization, weight adjustment, split fund distribution, token URI resolution. Called via DELEGATECALL from the hook. |
 
 Supporting:
 - `JB721Hook` (abstract, ~270 lines) -- Base ERC-721 with `beforePayRecordedWith`, `beforeCashOutRecordedWith`, `afterPayRecordedWith`, `afterCashOutRecordedWith`. Terminal authorization checks.
@@ -270,6 +330,19 @@ These must hold. If you can break any, it's a finding:
 9. **Removal idempotency**: Removing an already-removed tier is a no-op (bitmap set is idempotent).
 10. **NFT supply cap**: Minted count per tier never exceeds `initialSupply` (same as invariant 1, but auditors should verify the `_ONE_BILLION - 1` cap prevents token ID overflow into the next tier).
 
+## Anti-Patterns to Hunt
+
+| Pattern | Where to Look | Why It's Dangerous |
+|---------|--------------|-------------------|
+| DELEGATECALL from hook to library | `JB721TiersHook` → `JB721TiersHookLib` | Library executes in the hook's storage context. A subtle mismatch in storage layout assumptions could corrupt state. |
+| `safeTransfer` before callback | `_sendPayoutToSplit` ERC-20 path | Tokens leave the contract before the hook callback. The function returns `true` regardless of callback success to prevent double-spend in leftover accounting. |
+| `forceApprove` + external call | `_sendPayoutToSplit` terminal path | If the external call fails, the approval is reset to zero. But between `forceApprove` and the failure, the approval exists. Can an attacker exploit this window? |
+| `mulDiv` rounding in price normalization | `normalizePaymentValue`, `convertSplitAmounts` | Rounding through the conversion chain (normalize → calculate splits → convert back) can compound. Verify rounding favors the protocol. |
+| Bitmap-based removal with iteration by maxTierIdOf | `totalCashOutWeight`, `cleanTiers` | `totalCashOutWeight` iterates up to `maxTierIdOf`, not by sorted list. If many tiers are added and removed, gas cost grows unboundedly. |
+| Clone initialization guard | `JB721TiersHookDeployer` | `initialize()` is guarded by `PROJECT_ID != 0`, not OpenZeppelin's `Initializable`. Verify the implementation contract cannot be initialized. |
+| `_mint` instead of `_safeMint` | `JB721TiersHook` | No `onERC721Received` callback. Prevents mint-time DoS but contracts won't detect incoming NFTs. |
+| Token ID overflow at tier boundary | `_generateTokenId` | `tokenId = tierId * 1_000_000_000 + tokenNumber`. If `tokenNumber` reaches `_ONE_BILLION`, it overflows into the next tier's namespace. Supply cap enforcement (`_ONE_BILLION - 1`) prevents this -- verify the enforcement is complete. |
+
 ## Testing Setup
 
 ```bash
@@ -295,23 +368,22 @@ forge test --gas-report
 
 | Category | Files | Coverage |
 |----------|------:|---------|
-| Unit tests | 10 | adjustTier, deployer, getters/constructor, mintFor/mintReservesFor, pay, redeem, tierSplitRouting, splitHookDistribution, JBBitmap, JBIpfsDecoder |
+| Unit tests | 13 | adjustTier, deployer, getters/constructor, mintFor/mintReservesFor, pay, redeem, tierSplitRouting, splitHookDistribution, JBBitmap, JBIpfsDecoder, pay_CrossCurrency, JB721TiersRulesetMetadataResolver, TierSupplyReserveCheck |
 | Invariant tests | 2 + 2 handlers | TierLifecycleInvariant (6), TieredHookStoreInvariant (3) |
 | Attack tests | 1 | 10 adversarial scenarios |
-| Regression tests | 3 | L34, L35, L36 |
+| Regression tests | 6 | BrokenTerminalDoesNotDos, CacheTierLookup, ProjectDeployerRulesets, ReserveBeneficiaryOverwrite, SplitDistributionBugs, SplitNoBeneficiary |
 | E2E tests | 1 | Full lifecycle |
-| Fork tests | 1 | Live chain state |
-| Cross-currency | 1 | 9 tests for price feed behavior |
+| Fork tests | 3 | ERC20CashOutFork, ERC20TierSplitFork, IssueTokensForSplitsFork |
 | Supply edge cases | 1 | M6 -- 4 targeted tests |
+| Reentrancy tests | 1 | TestSafeTransferReentrancy -- safeTransfer reentrancy scenarios |
+| Voting units tests | 1 | TestVotingUnitsLifecycle -- voting power through mint/burn/transfer |
 
-### Notable Coverage Gaps
+### Coverage Gaps
 
-1. ~~No reentrancy test for split distribution `.call{value}` or `terminal.pay()` path.~~ Mitigated: all external calls in `_sendPayoutToSplit` are now wrapped in try-catch. `TestAuditGaps_Reentrancy` confirms reentrancy is blocked by terminal check.
-2. No gas limit test for operations with hundreds of tiers.
-3. No test for malicious/reverting token URI resolver.
-4. No test for `initialize()` front-running on deterministic clones.
-5. No fuzz test for discount percent edge cases with very small prices.
-6. ~~No test for cross-terminal reentry through split `terminal.pay()` callback.~~ Mitigated: terminal calls are wrapped in try-catch; hook state is fully settled before distribution begins.
+1. No gas limit test for operations with hundreds of tiers.
+2. No test for malicious/reverting token URI resolver.
+3. No test for `initialize()` front-running on deterministic clones.
+4. No fuzz test for discount percent edge cases with very small prices.
 
 ## How to Report Findings
 
@@ -338,3 +410,4 @@ For each finding:
 - Is `DISCOUNT_DENOMINATOR = 200` surprising but correct? (It is.)
 - Does the store's `msg.sender`-keyed trust model handle the case? (The store trusts the hook.)
 - Is the economic attack profitable after the core protocol's 2.5% fee on cash outs?
+

package/CHANGE_LOG.md

@@ -2,6 +2,14 @@
 
 This document describes all changes between `nana-721-hook` (v5) and `nana-721-hook-v6` (v6).
 
+## Summary
+
+- **Tier splits system**: Each NFT tier can now route a percentage of payments to split recipients instead of the project treasury, with full DOS protection via try-catch on all external calls.
+- **`votingUnits` replaced by `splitPercent`** in packed tier storage — voting units moved to a separate mapping to free the storage slot for the more widely-needed split feature.
+- **New `JB721TiersHookLib` library**: Code extracted from the hook to stay within the EIP-170 contract size limit (24KB).
+- **Mutable collection metadata**: `name` and `symbol` can now be changed post-deployment via `setMetadata()`.
+- **Prices moved to constructor immutable**: `IJBPrices` is now a constructor parameter instead of being packed in tier config.
+
 ---
 
 ## 1. Breaking Changes
@@ -47,6 +55,8 @@ This document describes all changes between `nana-721-hook` (v5) and `nana-721-h
 | `votingUnits` (`uint32`) | Present | Removed | Replaced by `splitPercent` |
 | `splitPercent` (`uint32`) | Not present | Added | Percentage of tier price routed to splits |
 
+> **Why this change**: On-chain voting units were rarely used by projects, while per-tier payment splits were the most requested feature. Reusing the same `uint32` storage slot avoided expanding the packed struct and kept gas costs unchanged. Voting units are still available via the `_tierVotingUnitsOf` mapping.
+
 ### 1.7 Error Signature Changes (Store)
 
 Several store errors gained a `tierId` parameter for better debugging:
@@ -64,7 +74,11 @@ Several store errors gained a `tierId` parameter for better debugging:
 
 ### 1.8 Solidity Version Change
 
-All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.26`.
+All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity ^0.8.26`.
+
+### 1.9 Cross-Repo Impact
+
+> The tier splits system affects `revnet-core-v6`, `croptop-core-v6`, and `nana-omnichain-deployers-v6`, which all deploy 721 hooks and must account for the new `splitPercent`/`splits` fields in `JB721TierConfig`. The `issueTokensForSplits` flag in `JB721TiersHookFlags` is force-set to `false` by `revnet-core-v6` to prevent dilution.
 
 ---