@bananapus/721-hook-v6 0.0.21 → 0.0.23

package/ADMINISTRATION.md

@@ -39,7 +39,7 @@ Admin privileges and their scope in nana-721-hook-v6.
 | `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. |
+| `initialize()` | None (one-time) | `_initialized` flag check | Initializes a cloned hook. Can only be called once. Transfers ownership to caller on completion. |
 
 ### JB721TiersHookProjectDeployer
 
@@ -131,7 +131,7 @@ The following are set at deploy/initialization time and **cannot be changed afte
 - 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.
+- The `initialize()` function uses an `_initialized` bool flag to prevent re-initialization. The implementation contract's constructor sets `_initialized = true`, blocking direct initialization. Clones start with `_initialized = false` and set it to `true` during `initialize()`.
 
 ## Ruleset-Level Pauses
 
@@ -155,7 +155,7 @@ What the hook owner **cannot** do:
 - **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 re-initialize a hook.** The `initialize()` function reverts if `_initialized` is already true.
 - **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

@@ -36,7 +36,7 @@ src/
 User → JBMultiTerminal.pay(metadata)
   → beforePayRecordedWith()
     → calculateSplitAmounts(): per-tier split amounts (in tier pricing denomination)
-    → convertSplitAmounts(): convert to payment token denomination (if currencies differ)
+    → convertAndCapSplitAmounts(): convert to payment token denomination (if currencies differ)
     → calculateWeight(): adjust weight down by split fraction
   → JBTerminalStore records payment
   → afterPayRecordedWith() → _processPayment()
@@ -56,7 +56,7 @@ Tiers can be priced in a different currency than the payment token (e.g. tiers p
 
 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.
+2. **`convertAndCapSplitAmounts`** — 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`, and caps the total at the actual payment value. 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).
 
@@ -110,7 +110,7 @@ Owner → JB721TiersHook.adjustTiers()
 
 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.
+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. Failed amounts are accumulated separately during the loop and routed to the project balance afterward, ensuring proportional redistribution -- later recipients receive only their configured share, not an inflated share from earlier failures.
 
 ## Dependencies
 - `@bananapus/core-v6` — Core protocol interfaces

package/AUDIT_INSTRUCTIONS.md

@@ -19,17 +19,17 @@ 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:
+An automated audit was conducted on 2026-03-17. 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) |
+| Severity | Title | Status |
+|----------|-------|--------|
+| 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) |
+| LOW | `_addToBalance` silently drops funds when no primary terminal | **Remediated** -- reverts when `primaryTerminalOf` returns `address(0)` and there are leftover funds |
+| LOW | Missing `splitPercent` bounds validation in `recordAddTiers` | **Remediated** -- `SplitPercentExceedsBounds` check added at `JB721TiersHookStore.sol:866` |
+| LOW | Implementation contract initializable | **Remediated** -- constructor now sets `_initialized = true` on the implementation |
+| 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.
+See [RISKS.md](./RISKS.md) for the project's own risk assessment.
 
 ## Error Reference
 
@@ -52,7 +52,7 @@ No prior formal audit with finding IDs from an external security firm has been c
 | `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_AlreadyInitialized(uint256 projectId)` | JB721TiersHook | `initialize()` called on a hook where `_initialized` is already true |
 | `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 |
@@ -295,11 +295,11 @@ Verify that:
 ### 5. Initialization and Clone Security
 
 `JB721TiersHookDeployer` creates minimal proxy clones:
-- `initialize()` is guarded by `PROJECT_ID != 0` (not `Initializable`)
+- `initialize()` is guarded by an `_initialized` bool flag
 - Ownership is transferred to `_msgSender()` inside `initialize`, then to the deployer caller in `deployHookFor`
 
 Verify that:
-- The implementation contract (HOOK) cannot be initialized (its `PROJECT_ID` is 0 by default -- can someone call initialize on it?)
+- The implementation contract's constructor sets `_initialized = true`, preventing initialization.
 - Deterministic salt derivation (`keccak256(abi.encode(_msgSender(), salt))`) prevents cross-deployer address collision
 - Front-running `deployHookFor` cannot hijack ownership
 
@@ -339,7 +339,7 @@ These must hold. If you can break any, it's a finding:
 | `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. |
+| Clone initialization guard | `JB721TiersHookDeployer` | `initialize()` is guarded by an `_initialized` bool flag. The implementation contract's constructor sets `_initialized = true`. Verify clones cannot be re-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. |
 

package/CHANGE_LOG.md

@@ -105,7 +105,7 @@ Contains functions extracted from `JB721TiersHook` to stay within the EIP-170 co
 | `recordAddTiersFor(...)` | Records new tiers and sets their split groups (used during initialization) |
 | `normalizePaymentValue(...)` | Normalizes payment value based on pricing context |
 | `calculateSplitAmounts(...)` | Calculates per-tier split amounts for a pay event |
-| `convertSplitAmounts(...)` | Converts split amounts between currencies |
+| `convertAndCapSplitAmounts(...)` | Converts split amounts between currencies, capped at payment value |
 | `calculateWeight(...)` | Adjusts minting weight to account for split amounts |
 | `distributeAll(...)` | Pulls tokens and distributes forwarded funds to tier split recipients |
 | `resolveTokenURI(...)` | Resolves the token URI (moved IPFS decoding out of hook) |
@@ -133,7 +133,7 @@ Tier split payouts now support the `split.hook` field (`IJBSplitHook`). The dist
 
 ### 2.4 DOS Protection on Split Distribution
 
-All external calls during tier split distribution (split hooks, terminal `pay`/`addToBalanceOf`, and leftover distribution) are wrapped in try-catch. A reverting split recipient or terminal cannot brick payments to the project. On failure, funds are returned to the project balance and a `SplitPayoutReverted` or `AddToBalanceReverted` event is emitted with the revert reason. For ERC-20 split hook failures, tokens are transferred first and the hook callback is best-effort; for ERC-20 terminal failures, the approval is reset to zero.
+All external calls during tier split distribution (split hooks, terminal `pay`/`addToBalanceOf`, and leftover distribution) are wrapped in try-catch. A reverting split recipient or terminal cannot brick payments to the project. On failure, the failed amount is accumulated separately and routed to the project balance after the distribution loop completes. This proportional redistribution ensures that later split recipients receive only their configured share, not an inflated share from the failed recipient's funds. A `SplitPayoutReverted` or `AddToBalanceReverted` event is emitted with the revert reason. For ERC-20 split hook failures, tokens are transferred first and the hook callback is best-effort; for ERC-20 terminal failures, the approval is reset to zero.
 
 ### 2.5 `splitPercent` Bounds Validation
 
@@ -280,7 +280,7 @@ Split payouts follow the same priority order as `JBMultiTerminal`: if `split.hoo
 
 ### 6.9 `JB721TiersHookLib` — Try-Catch on All External Calls
 
-All external calls during split distribution (split hooks, terminal `pay`, terminal `addToBalanceOf`, and leftover `addToBalanceOf`) are wrapped in try-catch. On failure: native token calls return false (funds stay in the hook), ERC-20 terminal call approvals are reset to zero, and `SplitPayoutReverted` or `AddToBalanceReverted` events are emitted with the revert reason.
+All external calls during split distribution (split hooks, terminal `pay`, terminal `addToBalanceOf`, and leftover `addToBalanceOf`) are wrapped in try-catch. On failure: the failed amount is accumulated separately and routed to the project balance after the distribution loop, ensuring proportional (not equal) redistribution among remaining recipients. Native token calls return false (funds stay in the hook), ERC-20 terminal call approvals are reset to zero, and `SplitPayoutReverted` or `AddToBalanceReverted` events are emitted with the revert reason.
 
 ### 6.10 `JB721TiersHookLib.calculateSplitAmounts` — Discount Applied Before Splits
 

package/RISKS.md

@@ -6,7 +6,7 @@
 - **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`. 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`.
+- **Clone initialization is one-shot, atomic.** `initialize()` guards via an `_initialized` bool flag. The implementation contract's constructor sets `_initialized = true`, blocking direct initialization. Clones start with `_initialized = false` and set it to `true` during `initialize()`. 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.
@@ -27,7 +27,7 @@
 ## 3. Reentrancy Surface
 
 - **Split hook callbacks (`processSplitWith`).** During `afterPayRecordedWith` -> `_processPayment` -> `distributeAll`, the library calls `split.hook.processSplitWith{value}()` for each split with a hook. This executes arbitrary code. At callback time: NFTs already minted, `payCreditsOf` updated, `remainingSupply` decremented in the store. Reentering `afterPayRecordedWith` requires terminal authentication and processes as an independent payment. All split hook and terminal calls are wrapped in try-catch to prevent a single reverting recipient from bricking all payments to the project. For native token hooks, a revert returns false (ETH stays in the contract and routes to project balance). For ERC20 hooks, tokens are transferred before the callback; a revert still returns true because the tokens have already left the contract. Tested: `TestAuditGaps_Reentrancy` confirms reentrancy is blocked by terminal check.
-- **Split beneficiary ETH sends.** `_sendPayoutToSplit` uses `beneficiary.call{value: amount}("")`. If the beneficiary reverts, the function returns `false` and funds route to the project's balance via `_addToBalance`. Does not revert the entire payment.
+- **Split beneficiary ETH sends.** `_sendPayoutToSplit` uses `beneficiary.call{value: amount}("")`. If the beneficiary reverts, the function returns `false` and the failed amount is accumulated separately, then routed to the project's balance after the distribution loop via `addToBalanceOf`. Later split recipients receive only their proportional share, not the failed recipient's share. Does not revert the entire payment.
 - **Terminal `.pay()` / `.addToBalanceOf()` during split distribution.** For project-targeted splits, the library calls the target project's primary terminal via try-catch. A reverting terminal returns false, routing the funds to the project's balance instead. For ERC20 terminal calls, approval is reset to zero on failure to prevent dangling approvals. The target terminal could call back into the hook, but the hook's state is fully settled (supply, credits, mint state). Reentrancy through this path cannot double-mint or corrupt state.
 - **`afterCashOutRecordedWith` execution order.** Burns tokens via `_burn()` -> `_update()` -> `STORE.recordTransferForTier()` in a loop, then calls `STORE.recordBurn()`. ERC721 `_update` triggers the store's tier balance decrement. Burns go to `address(0)`, so no `onERC721Received` callback.
 - **No `ReentrancyGuard`.** Protection relies on state ordering (all `STORE.record*` calls before external calls), terminal authentication checks, and try-catch wrapping of all external calls in `_sendPayoutToSplit`. `_mint()` uses the non-safe variant, avoiding `onERC721Received` callbacks during minting.

package/SKILLS.md

@@ -60,7 +60,7 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 | `votingUnitsOf(hook, account)` | `JB721TiersHookStore` | Returns total voting units for an address across all tiers. |
 | `tierVotingUnitsOf(hook, account, tierId)` | `JB721TiersHookStore` | Returns voting units for an address within a specific tier. |
 | `calculateSplitAmounts(store, hook, metadataIdTarget, metadata)` | `JB721TiersHookLib` | Decodes tier IDs from metadata, computes per-tier split amounts from effective price and `splitPercent`. |
-| `convertSplitAmounts(totalSplitAmount, splitMetadata, packedPricingContext, prices, projectId, amountCurrency, amountDecimals)` | `JB721TiersHookLib` | Converts split amounts from tier pricing denomination to payment token denomination via `JBPrices`. |
+| `convertAndCapSplitAmounts(totalSplitAmount, splitMetadata, packedPricingContext, prices, projectId, amountCurrency, amountDecimals)` | `JB721TiersHookLib` | Converts split amounts from tier pricing denomination to payment token denomination via `JBPrices`, capped at the actual payment value. |
 | `distributeAll(directory, splits, projectId, hookAddress, token, amount, decimals, encodedSplitData)` | `JB721TiersHookLib` | Distributes forwarded split funds to tier split recipients. Leftover goes to project balance via `addToBalance`. |
 | `adjustTiersFor(store, splits, projectId, hookAddress, caller, tiersToAdd, tierIdsToRemove)` | `JB721TiersHookLib` | Called via DELEGATECALL from `adjustTiers`. Removes tiers, adds tiers, emits events, registers splits. |
 | `normalizePaymentValue(packedPricingContext, prices, projectId, amountValue, amountCurrency, amountDecimals)` | `JB721TiersHookLib` | Converts a payment value to the hook's pricing currency using `JBPrices`. |
@@ -86,7 +86,7 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 | `JB721Tier` | `uint32 id`, `uint104 price`, `uint32 remainingSupply`, `uint32 initialSupply`, `uint104 votingUnits`, `uint16 reserveFrequency`, `address reserveBeneficiary`, `bytes32 encodedIPFSUri`, `uint24 category`, `uint8 discountPercent`, `bool allowOwnerMint`, `bool transfersPausable`, `bool cannotBeRemoved`, `bool cannotIncreaseDiscountPercent`, `uint32 splitPercent`, `string resolvedUri` | Return type from `tierOf`, `tiersOf`, `tierOfTokenId` |
 | `JBStored721Tier` | `uint104 price`, `uint32 remainingSupply`, `uint32 initialSupply`, `uint32 splitPercent`, `uint24 category`, `uint8 discountPercent`, `uint16 reserveFrequency`, `uint8 packedBools` (allowOwnerMint, transfersPausable, useVotingUnits, cannotBeRemoved, cannotIncreaseDiscountPercent) | Internal storage in `JB721TiersHookStore`. Voting units stored separately in `_tierVotingUnitsOf` when `useVotingUnits` is true. |
 | `JB721InitTiersConfig` | `JB721TierConfig[] tiers`, `uint32 currency`, `uint8 decimals` | `initialize` -- defines tiers and pricing context. The prices contract is an immutable on the hook, not passed per-config. |
-| `JBDeploy721TiersHookConfig` | `string name`, `string symbol`, `string baseUri`, `IJB721TokenUriResolver tokenUriResolver`, `string contractUri`, `JB721InitTiersConfig tiersConfig`, `address reserveBeneficiary`, `JB721TiersHookFlags flags` | `deployHookFor`, `launchProjectFor` |
+| `JBDeploy721TiersHookConfig` | `string name`, `string symbol`, `string baseUri`, `IJB721TokenUriResolver tokenUriResolver`, `string contractUri`, `JB721InitTiersConfig tiersConfig`, `JB721TiersHookFlags flags` | `deployHookFor`, `launchProjectFor` |
 | `JB721TiersHookFlags` | `bool noNewTiersWithReserves`, `bool noNewTiersWithVotes`, `bool noNewTiersWithOwnerMinting`, `bool preventOverspending`, `bool issueTokensForSplits` | `initialize`, `recordFlags` |
 | `JB721TiersRulesetMetadata` | `bool pauseTransfers`, `bool pauseMintPendingReserves` | Packed into `JBRulesetMetadata.metadata` per-ruleset (bit 0 = pauseTransfers, bit 1 = pauseMintPendingReserves) |
 | `JBPayDataHookRulesetConfig` | `uint48 mustStartAtOrAfter`, `uint32 duration`, `uint112 weight`, `uint32 weightCutPercent`, `IJBRulesetApprovalHook approvalHook`, `JBPayDataHookRulesetMetadata metadata`, `JBSplitGroup[] splitGroups`, `JBFundAccessLimitGroup[] fundAccessLimitGroups` | `JB721TiersHookProjectDeployer` -- wraps core ruleset config with `useDataHookForPay: true` hardcoded |
@@ -144,9 +144,11 @@ Each tier has configurable voting power:
   - Applies the tier's `discountPercent` to derive the effective price.
   - Computes `mulDiv(effectivePrice, splitPercent, SPLITS_TOTAL_PERCENT)` per tier.
   - Returns the total to be forwarded to the hook.
-  - If the payment currency differs from the tier pricing currency, `convertSplitAmounts` converts amounts to the payment token denomination via `JBPrices`.
+  - If the payment currency differs from the tier pricing currency, `convertAndCapSplitAmounts` converts amounts to the payment token denomination via `JBPrices` and caps the total at the actual payment value.
+  - **Pay credits cap**: `totalSplitAmount` is capped at `context.amount.value` before weight calculation and before being returned in the hook specification. Pay credits fund NFT minting (virtual -- they reduce the price threshold in `recordMint`), but splits require real tokens to distribute. Without this cap, a payer with sufficient pay credits but insufficient actual payment value would cause the terminal to attempt forwarding more tokens than were actually received, reverting the transaction. This means the project receiving the NFT payment must have received the full amount including what would have gone to splits -- split recipients are paid from the project's balance, not directly from the payer's contribution.
   - Weight is adjusted down proportionally (`weight = mulDiv(weight, amount - totalSplitAmount, amount)`) unless the `issueTokensForSplits` flag is set, in which case the full `context.weight` is returned.
 - In `afterPayRecordedWith`, `distributeAll` distributes forwarded funds to each tier's split group recipients. Leftover after all splits goes back to the project's balance via `addToBalance`.
+- **Leftover accounting in `_distributeSingleSplit`**: `leftoverAmount` is always decremented **before** the send attempt. If `_sendPayoutToSplit` returns `false` (i.e., the send reverted or had no valid recipient), the failed amount is accumulated in a separate variable (not added back to `leftoverAmount`). After the loop completes, accumulated failed amounts are added to `leftoverAmount` and routed to the project's balance. This "decrement-first, accumulate-failures-separately" pattern uses proportional redistribution: a failed split does not inflate subsequent split recipients' shares because the failed amount is withheld from `leftoverAmount` during the loop, and `leftoverPercentage` still decreases regardless of success.
 - Split recipients follow the same priority chain as `JBMultiTerminal`: `split.hook` > `split.projectId` > `split.beneficiary`:
   - **Split hooks**: receive a `JBSplitHookContext` struct (`token`, `amount`, `decimals`, `projectId`, `groupId`, full `split`). Native tokens forwarded via `{value: amount}`; ERC-20s transferred via `SafeERC20.safeTransfer` before calling `processSplitWith`.
   - **Project splits**: route via `terminal.pay` or `terminal.addToBalance`.
@@ -154,7 +156,7 @@ Each tier has configurable voting power:
   - **Empty splits** (no hook, no project ID, no beneficiary): skipped -- their share stays in the leftover and routes to the project's balance via `addToBalanceOf`, preventing a misconfigured split from bricking the payout distribution.
 - All external calls in `_sendPayoutToSplit` are wrapped in try-catch to prevent a single reverting recipient from bricking all payments to the project:
   - **Native token hooks**: a revert returns `false` (ETH stays in the contract and routes to the project balance).
-  - **ERC-20 hooks**: tokens are transferred via `safeTransfer` before the callback; the function always returns `true` regardless of callback outcome because the tokens have already left -- returning `false` would cause double-spend accounting in the leftover calculation.
+  - **ERC-20 hooks**: tokens are transferred via `safeTransfer` before the callback; the function always returns `true` regardless of callback outcome because the tokens have already left this contract. Since leftoverAmount was already decremented before the send, returning `true` is required to prevent the caller from adding the amount back -- which would create a double-spend (tokens sent to the hook AND counted toward leftover routed to the project).
   - **ERC-20 terminal calls** (`pay`/`addToBalanceOf`): approval is reset to zero on failure to prevent dangling approvals.
 
 ## Gotchas
@@ -197,7 +199,7 @@ Each tier has configurable voting power:
 | `JB721Hook_InvalidPay()` | `JB721Hook` | `afterPayRecordedWith` caller is not a project terminal. |
 | `JB721Hook_UnauthorizedToken(tokenId, holder)` | `JB721Hook` | Cash out attempts to burn a token not owned by `context.holder`. |
 | `JB721Hook_UnexpectedTokenCashedOut()` | `JB721Hook` | `beforeCashOutRecordedWith` called with `cashOutCount > 0` (fungible tokens mixed with NFT cash out). |
-| `JB721TiersHook_AlreadyInitialized(projectId)` | `JB721TiersHook` | `initialize` called on a hook that already has a `PROJECT_ID`. |
+| `JB721TiersHook_AlreadyInitialized(projectId)` | `JB721TiersHook` | `initialize` called on a hook where `_initialized` is already true. |
 | `JB721TiersHook_CurrencyMismatch(paymentCurrency, tierCurrency)` | `JB721TiersHook` | Payment currency differs from tier pricing currency and no `PRICES` contract is configured for conversion. |
 | `JB721TiersHook_InvalidPricingDecimals(decimals)` | `JB721TiersHook` | `initialize` called with `decimals > 18`. |
 | `JB721TiersHook_MintReserveNftsPaused()` | `JB721TiersHook` | `mintPendingReservesFor` called while `pauseMintPendingReserves` is set in the current ruleset metadata. |
@@ -292,7 +294,6 @@ tiers[0] = JB721TierConfig({
             currency: 1,        // ETH
             decimals: 18
         }),
-        reserveBeneficiary: address(0),
         flags: JB721TiersHookFlags({
             noNewTiersWithReserves: false,
             noNewTiersWithVotes: false,

package/USER_JOURNEYS.md

@@ -47,7 +47,7 @@ A user pays a Juicebox project and receives tiered NFTs based on the amount paid
 - **Last slot is reserved**: If minting would leave `remainingSupply < pendingReserves`, reverts with `JB721TiersHookStore_InsufficientSupplyRemaining`.
 - **Cross-currency payment with no price feed**: `normalizePaymentValue` returns `(0, false)`. The hook returns without minting or reverting. The payment is still processed by the terminal.
 - **Discounted tier**: Effective price is `price - mulDiv(price, discountPercent, 200)`. A `discountPercent` of 200 makes it free.
-- **Split distribution**: If a split recipient's `.call{value}` fails, the funds stay in `leftoverAmount` and are added to the project's balance.
+- **Split distribution**: If a split recipient's payout reverts, the failed amount is accumulated separately and added to the project's balance after the loop. Later split recipients receive only their proportional share, not the failed recipient's share.
 
 ---
 
@@ -315,7 +315,6 @@ Deploy a 721 tiers hook for an existing project.
     - `JB721TierConfig[] tiers` -- initial tiers (sorted by category).
     - `uint32 currency` -- pricing currency (`uint32(uint160(tokenAddress))` for concrete, or abstract like 1=ETH, 2=USD).
     - `uint8 decimals` -- pricing decimals (must be <= 18).
-  - `address reserveBeneficiary` -- (unused in current initialize; set via tier configs).
   - `JB721TiersHookFlags flags` -- collection-level behavior flags.
 - `bytes32 salt` -- for deterministic deployment (bytes32(0) for non-deterministic).
 
@@ -331,11 +330,11 @@ Deploy a 721 tiers hook for an existing project.
 - `SetDefaultReserveBeneficiary(hook, newBeneficiary, caller)` -- if any initial tier has `useReserveBeneficiaryAsDefault = true`.
 
 **Edge cases**:
-- **Re-initialization**: Reverts with `JB721TiersHook_AlreadyInitialized` if `PROJECT_ID` is already set.
+- **Re-initialization**: Reverts with `JB721TiersHook_AlreadyInitialized` if `_initialized` is already true.
 - **`projectId == 0`**: Reverts with `JB721TiersHook_NoProjectId`.
 - **`decimals > 18`**: Reverts with `JB721TiersHook_InvalidPricingDecimals`.
 - **Deterministic salt collision**: Reverts at the EVM level (CREATE2 collision).
-- **Implementation contract**: The original `HOOK` has `PROJECT_ID == 0`, so anyone could call `initialize` on it. However, since it is the implementation (not a clone), this would just set state on the implementation which has no operational significance -- clones do not read the implementation's storage.
+- **Implementation contract**: The implementation contract's constructor sets `_initialized = true`, so no one can call `initialize` on it.
 
 ---
 

package/assets/findings/nana-721-hook-v6-pashov-ai-audit-report-20260330-091257.md

@@ -0,0 +1,83 @@
+# 🔐 Security Review — nana-721-hook-v6
+
+---
+
+## Scope
+
+|                                  |                                                        |
+| -------------------------------- | ------------------------------------------------------ |
+| **Mode**                         | ALL / default                                          |
+| **Files reviewed**               | `script/Deploy.s.sol` · `script/helpers/Hook721DeploymentLib.sol` · `src/JB721TiersHook.sol`<br>`src/JB721TiersHookDeployer.sol` · `src/JB721TiersHookProjectDeployer.sol` · `src/JB721TiersHookStore.sol`<br>`src/abstract/ERC721.sol` · `src/abstract/JB721Hook.sol` · `src/libraries/JB721Constants.sol`<br>`src/libraries/JB721TiersHookLib.sol` · `src/libraries/JB721TiersRulesetMetadataResolver.sol` · `src/libraries/JBBitmap.sol`<br>`src/libraries/JBIpfsDecoder.sol` · `src/structs/JB721InitTiersConfig.sol` · `src/structs/JB721Tier.sol`<br>`src/structs/JB721TierConfig.sol` · `src/structs/JB721TiersHookFlags.sol` · `src/structs/JB721TiersMintReservesConfig.sol`<br>`src/structs/JB721TiersRulesetMetadata.sol` · `src/structs/JB721TiersSetDiscountPercentConfig.sol` · `src/structs/JBBitmapWord.sol`<br>`src/structs/JBDeploy721TiersHookConfig.sol` · `src/structs/JBLaunchProjectConfig.sol` · `src/structs/JBLaunchRulesetsConfig.sol`<br>`src/structs/JBPayDataHookRulesetConfig.sol` · `src/structs/JBPayDataHookRulesetMetadata.sol` · `src/structs/JBQueueRulesetsConfig.sol`<br>`src/structs/JBStored721Tier.sol` | 
+| **Confidence threshold (1-100)** | 75                                                     |
+
+---
+
+## Findings
+
+[90] **1. Pay Credits Let Buyers Bypass Tier Split Payments**
+
+`JB721TiersHook._mintAndUpdateCredits` · Confidence: 90
+
+**Description**
+`payCreditsOf` is merged into NFT purchasing power, but tier split payouts are still capped to `context.forwardedAmount.value`, so a buyer can mint a split-bearing tier mostly with credits while paying only a dust-sized fresh split.
+
+**Fix**
+
+```diff
+- leftoverAmount += payCredits;
+- if (context.hookMetadata.length != 0 && context.forwardedAmount.value != 0) {
+-     JB721TiersHookLib.distributeAll(... amount: context.forwardedAmount.value, ...);
+- }
++ uint256 creditBackedAmount = context.payer == context.beneficiary ? payCredits : 0;
++ uint256 splitFundingAmount = context.forwardedAmount.value + creditBackedAmountUsedForMint;
++ if (context.hookMetadata.length != 0 && splitFundingAmount != 0) {
++     JB721TiersHookLib.distributeAll(... amount: splitFundingAmount, ...);
++ }
+```
+---
+
+[90] **2. Failed Early Splits Are Redistributed to Later Recipients**
+
+`JB721TiersHookLib._distributeSingleSplit` · Confidence: 90
+
+**Description**
+When an early split payout fails, its amount is added back into `leftoverAmount` before later splits are calculated, so later recipients can receive the failed recipient’s share instead of that value falling back to project balance.
+
+**Fix**
+
+```diff
+- if (!_sendPayoutToSplit(...)) {
+-     leftoverAmount += payoutAmount;
+- }
++ if (!_sendPayoutToSplit(...)) {
++     failedAmount += payoutAmount;
++ }
+...
+- if (leftoverAmount != 0) {
+-     terminal.addToBalanceOf(... leftoverAmount ...);
++ uint256 amountToProject = leftoverAmount + failedAmount;
++ if (amountToProject != 0) {
++     terminal.addToBalanceOf(... amountToProject ...);
+```
+
+---
+
+Findings List
+
+| # | Confidence | Title |
+|---|---|---|
+| 1 | [90] | Pay Credits Let Buyers Bypass Tier Split Payments |
+| 2 | [90] | Failed Early Splits Are Redistributed to Later Recipients |
+
+---
+
+## Leads
+
+_Vulnerability trails with concrete code smells where the full exploit path could not be completed in one analysis pass. These are not false positives — they are high-signal leads for manual review. Not scored._
+
+- **Public Address Registry Can Grief Hook Deployments** — `JB721TiersHookDeployer.deployHookFor` — Code smells: deployment success depends on `JBAddressRegistry.registerAddress`, and the registry is permissionless plus duplicate-registration-reverting — A third party can likely pre-register a predicted hook address and make `deployHookFor` revert at the registry step, but the practical griefing envelope depends on deployment mode and the caller’s ability to retry with a different salt.
+- **Shared `_nonce` Can Desync Registry Provenance After Mixed CREATE/CREATE2 Deployments** — `JB721TiersHookDeployer.deployHookFor` — Code smells: `_nonce` is incremented for both deterministic and non-deterministic deployments, while only the CREATE path consumes the deployer nonce the registry models — Mixed deployment modes may cause later saltless registrations to point at the wrong CREATE address, but I did not complete an end-to-end exploit showing downstream trust assumptions being violated.
+
+---
+
+> ⚠️ This review was performed by an AI assistant. AI analysis can never verify the complete absence of vulnerabilities and no guarantee of security is given. Team security reviews, bug bounty programs, and on-chain monitoring are strongly recommended. For a consultation regarding your projects' security, visit [https://www.pashov.com](https://www.pashov.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,9 +17,9 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-721-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.15",
-    "@bananapus/core-v6": "^0.0.27",
-    "@bananapus/ownable-v6": "^0.0.14",
+    "@bananapus/address-registry-v6": "^0.0.16",
+    "@bananapus/core-v6": "^0.0.28",
+    "@bananapus/ownable-v6": "^0.0.15",
     "@bananapus/permission-ids-v6": "^0.0.14",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.0",

package/src/JB721TiersHook.sol

@@ -65,6 +65,15 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @notice The contract that stores and manages splits.
     IJBSplits public immutable override SPLITS;
 
+    //*********************************************************************//
+    // --------------------- private stored properties ------------------ //
+    //*********************************************************************//
+
+    /// @notice Whether this contract has been initialized. Used to prevent re-initialization of both the
+    /// implementation contract itself and its clones.
+    /// @dev Internal (not private) so test harnesses that extend this contract can reset it in their constructors.
+    bool internal _initialized;
+
     //*********************************************************************//
     // ---------------------- public stored properties ------------------- //
     //*********************************************************************//
@@ -123,6 +132,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         RULESETS = rulesets;
         STORE = store;
         SPLITS = splits;
+
+        // Prevent the implementation contract from being initialized.
+        _initialized = true;
     }
 
     //*********************************************************************//
@@ -189,16 +201,18 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             store: STORE, hook: address(this), metadataIdTarget: METADATA_ID_TARGET, metadata: context.metadata
         });
 
-        // Convert split amounts from tier pricing to payment token denomination if currencies differ.
+        // Convert split amounts from tier pricing to payment token denomination (if currencies differ)
+        // and cap at the actual payment value so the terminal never forwards more than was paid.
         if (totalSplitAmount != 0) {
-            (totalSplitAmount, splitMetadata) = JB721TiersHookLib.convertSplitAmounts({
+            (totalSplitAmount, splitMetadata) = JB721TiersHookLib.convertAndCapSplitAmounts({
                 totalSplitAmount: totalSplitAmount,
                 splitMetadata: splitMetadata,
                 packedPricingContext: _packedPricingContext,
                 prices: PRICES,
                 projectId: context.projectId,
                 amountCurrency: context.amount.currency,
-                amountDecimals: context.amount.decimals
+                amountDecimals: context.amount.decimals,
+                amountValue: context.amount.value
             });
         }
 
@@ -207,7 +221,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             contextWeight: context.weight,
             amountValue: context.amount.value,
             totalSplitAmount: totalSplitAmount,
-            issueTokensForSplits: STORE.flagsOf(address(this)).issueTokensForSplits
+            store: STORE,
+            hook: address(this)
         });
 
         hookSpecifications[0] =
@@ -246,8 +261,10 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         public
         override
     {
-        // Stop re-initialization by ensuring a projectId is provided and doesn't already exist.
-        if (PROJECT_ID != 0) revert JB721TiersHook_AlreadyInitialized(PROJECT_ID);
+        // Stop re-initialization. This protects both the implementation contract (initialized in constructor)
+        // and clones (initialized via this function).
+        if (_initialized) revert JB721TiersHook_AlreadyInitialized(PROJECT_ID);
+        _initialized = true;
 
         // Make sure a projectId is provided.
         if (projectId == 0) revert JB721TiersHook_NoProjectId();

package/src/JB721TiersHookStore.sol

@@ -749,7 +749,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
         // Make the sorted array.
         while (currentSortedTierId != 0) {
-            // If the current tier ID being iterated on isn't an increment of the previous one,
+            // Check if the current tier has been removed.
             if (!_isTierRemovedWithRefresh({hook: hook, tierId: currentSortedTierId, bitmapWord: bitmapWord})) {
                 // Update its `_tierIdAfter` if needed.
                 if (currentSortedTierId != previousSortedTierId + 1) {
@@ -763,8 +763,22 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
                     _tierIdAfter[hook][previousSortedTierId] = 0;
                 }
 
+                // If this tier's category has a stale `_startingTierIdOfCategory` (reset to 0 because the
+                // previous starting tier was removed), set this tier as the new starting tier for its category.
+                uint256 tierCategory = _storedTierOf[hook][currentSortedTierId].category;
+                if (tierCategory != 0 && _startingTierIdOfCategory[hook][tierCategory] == 0) {
+                    _startingTierIdOfCategory[hook][tierCategory] = currentSortedTierId;
+                }
+
                 // Iterate by setting the previous tier ID for the next loop to the current tier ID.
                 previousSortedTierId = currentSortedTierId;
+            } else {
+                // The tier was removed. If it was the `_startingTierIdOfCategory` for its category, reset the
+                // pointer so the next non-removed tier in the same category can claim it.
+                uint256 removedCategory = _storedTierOf[hook][currentSortedTierId].category;
+                if (removedCategory != 0 && _startingTierIdOfCategory[hook][removedCategory] == currentSortedTierId) {
+                    _startingTierIdOfCategory[hook][removedCategory] = 0;
+                }
             }
             // Iterate by updating the current sorted tier ID to the next sorted tier ID.
             currentSortedTierId = _nextSortedTierIdOf({hook: hook, id: currentSortedTierId, max: lastSortedTierId});