@bananapus/721-hook-v6 0.0.36 → 0.0.38

package/RISKS.md

@@ -1,125 +1,118 @@
 # Juicebox 721 Hook Risk Register
 
-This file focuses on the tiered-NFT accounting, reserve-mint, and cash-out risks in the shared 721 hook used across multiple higher-level products.
+This file covers the tiered-NFT accounting, reserve-mint, and cash-out risks in the shared 721 hook used across multiple higher-level products.
 
-## How to use this file
+## How To Use This File
 
-- Read `Priority risks` first; they summarize the shared 721-hook risks with the widest blast radius.
-- Use the detailed sections below for reentrancy, gas, tier accounting, and integration reasoning.
-- Treat `Invariants to Verify` as required regression coverage for any hook or store change.
+- Read `Priority risks` first. They summarize the shared 721-hook risks with the widest blast radius.
+- Use the later sections for reentrancy, gas, tier accounting, and integration reasoning.
+- Treat `Invariants to verify` as required coverage for any hook or store change.
 
-## Priority risks
+## Priority Risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P0 | Shared store corruption or accounting drift | `JB721TiersHookStore` is reused across products; a tier-accounting bug can affect Defifa, Croptop, Banny, revnets, and standalone hooks simultaneously. | Heavy store testing, invariant coverage, and cautious upgrades or deployments. |
-| P1 | Gas and iteration ceilings around tier state | Tier operations can iterate over reserves, pricing state, and cash-out weights; poorly bounded use can become a liveness issue. | Explicit gas tests, tier-count limits, and section 4 DoS analysis. |
-| P1 | Cash-out and reserve math mismatch | Fair redemption depends on tier supply, pending reserves, and pricing state staying aligned. | Detailed invariants, fuzzing, and integration tests with downstream consumers. |
-
+| P0 | Shared store corruption or accounting drift | `JB721TiersHookStore` is reused across products. A tier-accounting bug can affect many repos at once. | Heavy store testing, invariants, and cautious deployment review. |
+| P1 | Gas and iteration ceilings around tier state | Tier operations can iterate over reserves, pricing state, and cash-out weights. | Gas tests, tier-count limits, and DoS review. |
+| P1 | Cash-out and reserve math mismatch | Fair redemption depends on tier supply, pending reserves, and pricing state staying aligned. | Detailed invariants, fuzzing, and integration tests. |
 
 ## 1. Trust Assumptions
 
-- **Store contract (`JB721TiersHookStore`) is fully trusted.** Record functions (`recordMint`, `recordBurn`, `recordAddTiers`, `recordTransferForTier`, `recordFlags`) have no access control -- they key state by `msg.sender`. Any address can call the store to manipulate state for a hook address it controls, but cannot affect other hooks.
-- **Tier configuration is partially immutable.** Once created: `price`, `initialSupply`, `reserveFrequency`, `category`, `votingUnits`, `splitPercent` are permanent. Mutable: `discountPercent` (owner-controlled, subject to `flags.cantIncreaseDiscountPercent`), `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.
-- **`flags.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 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 with a hook-specific error.** The hook explicitly reverts with `JB721TiersHook_ZeroAddress` when called with `address(0)`. This matches standard ERC-721 semantics but is still relevant for integrators that key off the custom error surface.
-- **`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.
+- **The store is trusted.** It keys state by `msg.sender`, so a hook can only affect its own namespace, but that namespace is fully trusted.
+- **Tier configuration is partly immutable.** Price, supply, reserve frequency, category, voting units, and split percent are permanent after creation.
+- **Category ordering matters.** The store's linked-list assumptions depend on correct sorted insertion.
+- **`useReserveBeneficiaryAsDefault` has wide effects.** Setting it on a new tier can change the default reserve beneficiary for older tiers without their own explicit beneficiary.
+- **Clone initialization is one-shot.** Clones are deployed and initialized atomically.
+- **Directory and prices are trusted.** Terminal authentication and cross-currency behavior depend on core.
 
 ## 2. Economic Risks
 
-- **Cash out weight uses full undiscounted price.** `cashOutWeightOf` and `totalCashOutWeight` always use `storedTier.price`, not the discounted price. NFTs bought at a discount have cash-out value proportional to the full tier price. A `discountPercent=200` (100% off, denominator is 200) enables free minting with full cash-out weight. Mitigated by `flags.cantIncreaseDiscountPercent` flag.
-- **Pending reserves inflate the `totalCashOutWeight` denominator.** The total includes `price * pendingReserves` for unminted reserve NFTs. This dilutes per-NFT reclaim value before reserves are actually minted. Effect is proportional to reserve frequency and number of unminted reserves.
-- **Pay credits accumulate without cap.** `payCreditsOf` grows from leftover amounts after minting. Credits are per-beneficiary, not per-payer. When `payer != beneficiary`, overspend accrues to the beneficiary's credits; the payer's existing credits are not applied. No upper bound on accumulation.
-- **Zero-price tiers are valid.** A tier with `price=0` allows free minting. Cash-out weight for price-0 tiers is zero, so no value extraction risk. However, they still consume supply and generate pending reserves if `reserveFrequency > 0`.
-- **Discount denominator is 200, not 10,000.** `DISCOUNT_DENOMINATOR = 200`. A `discountPercent` of 1 = 0.5% off, 100 = 50% off, 200 = 100% off. `mulDiv` rounding makes small-price discounts lossy (e.g., `price=1, discountPercent=1` -> `mulDiv(1,1,200)=0`, no discount applied).
-- **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.
+- **Cash-out weight uses full undiscounted price.**
+- **Pending reserves inflate the cash-out denominator before reserves are minted.**
+- **Pay credits can accumulate without a cap.**
+- **Zero-price tiers are valid.**
+- **Discount math uses a denominator of 200, not 10,000.**
+- **Currency mismatch can silently skip minting when no prices contract is configured.**
+- **`splitPercent` can reduce fungible-token minting weight.**
+- **Reserve minting is permissionless.**
 
 ## 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 the failed amount is accumulated separately, then routed toward the project's balance after the distribution loop via `addToBalanceOf`. Later split recipients receive only their proportional share, not the failed recipient's share. This does not revert the entire payment unless the fallback `addToBalanceOf` path also reverts.
-- **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.
-- **Split fallback can still strand value if the project terminal rejects leftovers.** `_distributeSingleSplit` tries to route failed split payouts into the source project's primary terminal with `addToBalanceOf`. If that fallback also reverts, the whole hook call reverts with `JB721TiersHookLib_SplitFallbackFailed` after the hook has already received the forwarded funds. For native ETH, that leaves the ETH stranded in the hook. For ERC-20s, approval is reset but the tokens remain in the hook. There is no built-in recovery path.
-- **`afterCashOutRecordedWith` execution order.** Burns tokens via `_burn()` -> `_update()` -> `STORE.tierTransferInfoOfTokenId()` 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.
-
-## 4. Gas/DoS Vectors
-
-- **`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.
-- **Reserve minting is unbounded per call.** `mintPendingReservesFor(tierId, count)` mints `count` NFTs in a loop. Large `count` could exceed block gas. Callers should batch.
-- **Max tiers capped at `uint16.max` (65,535).** Store enforces this ceiling. Practical gas limits make 1,000+ tiers problematic for on-chain reads.
-- **200+ tiers tested.** `TestAuditGaps_GasLimits` adds 200 tiers and verifies store correctness and gas within 30M block limit.
+- **Split hook callbacks execute arbitrary code.**
+- **Split beneficiary ETH sends can fail softly and reroute value.**
+- **Terminal `pay` and `addToBalanceOf` calls during split distribution can reenter external systems.**
+- **Split fallback can still strand value if the project terminal rejects leftovers.**
+- **There is no `ReentrancyGuard`.** Safety depends on state ordering, terminal auth, and wrapped external calls.
+
+## 4. Gas And DoS Vectors
+
+- **`totalCashOutWeight` iterates all tier IDs.**
+- **`balanceOf`, `votingUnitsOf`, and `totalSupplyOf` also iterate all tiers.**
+- **Large tier catalogs are technically allowed but not the supported operating shape.**
+- **`tiersOf` still traverses removed tiers until cleanup runs.**
+- **Minting across many tiers in one payment can get expensive fast.**
+- **Reserve minting is loop-based and should be batched when large.**
 
 ## 5. Access Control
 
-- **`adjustTiers` (add/remove):** Requires `ADJUST_721_TIERS` permission from `owner()`. Respects `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting` flags (append-only restrictions). `flags.cantBeRemoved` flag on individual tiers is enforced by the store.
-- **`mintFor` (owner minting):** Requires `MINT_721` permission. Bypasses price checks (`amount: type(uint256).max`). Still requires per-tier `flags.allowOwnerMint` flag. Tiers with `reserveFrequency > 0` cannot have `flags.allowOwnerMint` (enforced at creation).
-- **`setDiscountPercentOf`:** Requires `SET_721_DISCOUNT_PERCENT` permission. Cannot increase discount if `flags.cantIncreaseDiscountPercent` is set on the tier. Can always decrease.
-- **`setMetadata`:** Requires `SET_721_METADATA` permission. Can change name, symbol, baseURI, contractURI, tokenUriResolver, and per-tier IPFS URIs. Sentinel value `IJB721TokenUriResolver(address(this))` means "no change" for resolver.
-- **Transfer pause:** Ruleset-level flag (`transfersPaused` in 721-specific metadata, bit 0). Only applies to tiers with `flags.transfersPausable = true`. Burns (transfer to address(0)) are never paused. Tiers created with `flags.transfersPausable = false` can never be paused.
-- **`mintPendingReservesFor`:** Permissionless. Only gated by `mintPendingReservesPaused` ruleset flag (bit 1 of 721 metadata).
-- **`cleanTiers`:** Permissionless, idempotent. Compacts the sorted tier list by removing gaps from deleted tiers. No economic impact.
-- **Store `recordFlags`:** No access control -- stores against `msg.sender`. Safe because the store keys by caller address, but a compromised hook can freely change its own flags.
+- **`adjustTiers` is permissioned and respects append-only restrictions.**
+- **`mintFor` is permissioned and still depends on per-tier owner-mint flags.**
+- **`setDiscountPercentOf` is permissioned and can be one-way constrained.**
+- **`setMetadata` is permissioned and changes name, symbol, URIs, resolver, and tier URIs.**
+- **Transfer pause is tier-sensitive.**
+- **`mintPendingReservesFor` and `cleanTiers` are permissionless by design.**
 
 ## 6. Integration Risks
 
-- **Data hook weight override.** `beforePayRecordedWith` returns modified `weight` accounting for tier split deductions. Terminal uses this for fungible token minting. If splits consume 100% of payment, `weight = 0` and no fungible tokens are minted.
-- **Metadata encoding is fragile.** Relies on `JBMetadataResolver.getDataFor` with purpose strings `"pay"` / `"cashOut"` keyed by `METADATA_ID_TARGET` (original hook deploy address for clones). Malformed metadata results in no NFTs minted (pay) or no NFTs burned (cashout) without reverting (unless `preventOverspending` is true).
-- **`beforeCashOutRecordedWith` rejects fungible tokens.** Reverts with `JB721Hook_UnexpectedTokenCashedOut` if `context.cashOutCount > 0`. Cannot simultaneously cash out NFTs and fungible tokens in the same terminal call.
-- **Split group ID encoding.** Composite: `uint256(uint160(hookAddress)) | (tierId << 160)`. Tier IDs are capped at uint16, so no overflow. Splits are permanently coupled to a specific hook address -- migrating to a new hook requires re-creating all split groups.
-- **ERC-20 split distribution pulls from terminal.** `distributeAll` calls `SafeERC20.safeTransferFrom(token, msg.sender, address(this), amount)` to pull ERC-20s from the terminal. Requires the terminal to have granted allowance via its `_beforeTransferTo` pattern. If the terminal's allowance mechanism changes, distribution fails.
-- **Forwarded funds depend on non-empty split metadata.** `_processPayment` only calls `distributeAll` when both `context.forwardedAmount.value != 0` and `context.hookMetadata.length != 0`. If an integration ever forwards funds with empty hook metadata, distribution is skipped and the funds remain in the hook contract with no dedicated rescue path.
-- **Split-fallback success depends on the source project's active terminal.** Failed split payouts are not simply burned or refunded. They are re-routed into the source project's current primary terminal for the forwarded token. If that terminal is unset or rejects `addToBalanceOf`, the call reverts and the hook can retain the funds.
-- **Token URI resolver external calls.** `tokenURI()` and `tiersOf(..., includeResolvedUri=true)` call the resolver if set. A reverting resolver blocks all metadata reads (marketplace/frontend impact, no fund risk).
-
-## 7. Invariants to Verify
-
-- **Per-tier supply conservation:** For every tier, `remainingSupply + outstanding + burned == initialSupply`, where `outstanding = initialSupply - remainingSupply - burned`.
-- **Total cash out weight consistency:** `totalCashOutWeight >= sum(tier.price * outstandingNFTs)` for all tiers. Equality holds when no pending reserves exist. Strictly greater when pending reserves are included.
-- **Reserve mints bounded by frequency:** For each tier, `reservesMinted <= ceil(nonReserveMints / reserveFrequency)`. Enforced by `_numberOfPendingReservesFor` calculation.
-- **Remaining supply never exceeds initial:** `remainingSupply + numberOfBurnedFor <= initialSupply` for every tier.
-- **Token ID uniqueness:** Generated as `tierId * 1_000_000_000 + tokenNumber`. Token numbers monotonically assigned from `initialSupply - remainingSupply`. Supply capped at `999,999,999` per tier. No collisions possible.
-- **Credit tracking accuracy:** `payCreditsOf[addr]` equals cumulative leftover from payments where `addr` was beneficiary, minus credits consumed by subsequent mints where `payer == beneficiary`.
-- **Removed tiers excluded from active listing:** `tiersOf()` never returns tiers marked in the removal bitmap.
-- **`maxTierIdOf` monotonically increases:** Tier removal marks a bitmap, does not decrement `maxTierIdOf`.
-- **Balance consistency:** `sum(tierBalanceOf[hook][owner][tierId])` across all tiers equals `ERC721._balances[owner]` for each owner.
-- **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 `flags.cantIncreaseDiscountPercent` 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.
+- **Hook weight can override fungible-token minting.**
+- **Metadata encoding is fragile.**
+- **`beforeCashOutRecordedWith` rejects mixed fungible-token cash outs.**
+- **Split group IDs are tightly coupled to the hook address.**
+- **ERC-20 split distribution depends on terminal allowance behavior.**
+- **Forwarded funds with empty hook metadata can skip distribution and remain in the hook.**
+- **Token URI resolver calls can block metadata reads if the resolver reverts.**
+
+## 7. Invariants To Verify
+
+- per-tier supply conservation holds
+- total cash-out weight stays consistent with outstanding NFTs and pending reserves
+- reserve minting stays bounded by reserve frequency
+- token IDs remain unique
+- credits track leftovers correctly
+- removed tiers stay excluded from active listings
+- store balance views match ERC-721 balances
+- discount monotonicity is enforced when locked
 
 ## 8. Accepted Behaviors
 
-### 8.1 Pending reserves inflate `totalCashOutWeight` denominator (by design)
+### 8.1 Pending reserves dilute cash-out value before minting
 
-`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.
+This is intentional. Including pending reserves in the denominator prevents reserve front-running.
 
-### 8.2 Cash-out weight uses full price regardless of discount (by design)
+### 8.2 Cash-out weight uses full price regardless of discount
 
-`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.
+This is intentional. The cash-out weight represents treasury share, not purchase price.
 
-### 8.3 Currency mismatch silently skips minting (accepted degradation)
+### 8.3 Currency mismatch can skip minting when no prices surface exists
 
-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`.
+If currencies differ and `PRICES == address(0)`, payments can increase project balance without minting NFTs. That is an accepted degradation rather than a revert path.
 
-### 8.4 Tiny split allocations can round down to zero recipient amounts
+### 8.4 Tiny split allocations can round down to zero
 
-Split metadata is expressed in whole token units after conversion and capping. For very small allocations, each rounded per-tier split amount can become zero even though the overall forwarded amount is still reduced by the capped split total. This is an accepted precision tradeoff for dust-sized payments: integrations should not rely on sub-precision split routing and should expect tiny split allocations to be economically lossy.
+Dust-sized split allocations can become economically lossy after rounding.
 
 ### 8.5 Failed split payouts only degrade cleanly if the fallback terminal path works
 
-The hook treats a reverting split hook, beneficiary, or target terminal as a soft failure and attempts to re-route that amount into the source project's balance. That graceful degradation depends on the source project's current primary terminal accepting `addToBalanceOf` for the forwarded token. If that terminal is missing or rejects the call, the transaction reverts after funds have already reached the hook, and the hook can retain those assets without a built-in rescue path.
+If both the primary split path and the fallback `addToBalanceOf` path fail, the hook can retain assets with no built-in rescue path.
+
+### 8.6 Credit-funded tier purchases may underfund split obligations
+
+Pay credits can be used to buy tiers that carry a `splitPercent`. When credits satisfy part of the tier price, the fresh ETH forwarded to splits may be less than the split obligation implied by the full tier price. Project owners who consider this a problem should enable the `preventBuyingTierWithCredits` flag on affected tiers. This is accepted behavior.
+
+### 8.7 Changing the default reserve beneficiary redirects pending reserves
+
+When the default reserve beneficiary is updated, any pending (unminted) reserves across all tiers that rely on the default will be distributed to the new beneficiary once minted. This is by design — the project owner controls reserve distribution targets and may intentionally redirect pending reserves by updating the default.
+
+### 8.8 Discounted credit mints retain full cash-out weight
+
+Tokens minted at a discounted price via credits still carry the full undiscounted tier price as their cash-out weight. This means a holder who purchased at a discount receives the same treasury share as a holder who paid full price. Project owners should factor this into discount percentage decisions, as aggressive discounts can create favorable cash-out economics for discounted buyers.

package/SKILLS.md

@@ -2,47 +2,42 @@
 
 ## Use This File For
 
-- Use this file when the task involves tiered NFT issuance, reserve minting, voting units, tier splits, or token URI resolver integration for Juicebox projects.
-- Start here, then decide whether the bug is in hook runtime logic, store accounting, deployer initialization, or downstream token-URI resolution. This repo spans all four and they are easy to conflate.
+- Use this file when the task involves tiered NFT minting, reserve minting, tier adjustments, deployer wiring, or 721-aware cash-out behavior.
+- Start here, then decide whether the issue is in hook execution, store accounting, deployer setup, or resolver behavior.
 
 ## Read This Next
 
 | If you need... | Open this next |
 |---|---|
-| Repo overview and integration model | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Runtime hook behavior | [`src/JB721TiersHook.sol`](./src/JB721TiersHook.sol), [`src/abstract/JB721Hook.sol`](./src/abstract/JB721Hook.sol) |
-| Tier storage and accounting | [`src/JB721TiersHookStore.sol`](./src/JB721TiersHookStore.sol) |
-| Deployment or project launch helpers | [`src/JB721TiersHookDeployer.sol`](./src/JB721TiersHookDeployer.sol), [`src/JB721TiersHookProjectDeployer.sol`](./src/JB721TiersHookProjectDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
-| Shared libraries, interfaces, and resolver surface | [`src/libraries/`](./src/libraries/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
-| Mint, pricing, voting, and checkpoint behavior | [`test/TestVotingUnitsLifecycle.t.sol`](./test/TestVotingUnitsLifecycle.t.sol), [`test/TestCheckpoints.t.sol`](./test/TestCheckpoints.t.sol) |
-| Reentrancy, forks, and pinned edge cases | [`test/TestSafeTransferReentrancy.t.sol`](./test/TestSafeTransferReentrancy.t.sol), [`test/721HookAttacks.t.sol`](./test/721HookAttacks.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
+| Repo overview and architecture | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Runtime hook behavior | [`src/JB721TiersHook.sol`](./src/JB721TiersHook.sol) |
+| Tier accounting | [`src/JB721TiersHookStore.sol`](./src/JB721TiersHookStore.sol) |
+| Shared math and metadata helpers | [`src/libraries/`](./src/libraries/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
+| Deployer flows | [`src/JB721TiersHookDeployer.sol`](./src/JB721TiersHookDeployer.sol), [`src/JB721TiersHookProjectDeployer.sol`](./src/JB721TiersHookProjectDeployer.sol) |
+| Lifecycle, invariant, and audit coverage | [`test/E2E/Pay_Mint_Redeem_E2E.t.sol`](./test/E2E/Pay_Mint_Redeem_E2E.t.sol), [`test/invariants/TierLifecycleInvariant.t.sol`](./test/invariants/TierLifecycleInvariant.t.sol), [`test/invariants/TieredHookStoreInvariant.t.sol`](./test/invariants/TieredHookStoreInvariant.t.sol), [`test/audit/CodexSplitCreditsMismatch.t.sol`](./test/audit/CodexSplitCreditsMismatch.t.sol) |
 
 ## Repo Map
 
 | Area | Where to look |
 |---|---|
 | Main contracts | [`src/`](./src/) |
-| Abstract bases, interfaces, structs, and libraries | [`src/abstract/`](./src/abstract/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/), [`src/libraries/`](./src/libraries/) |
+| Libraries, interfaces, and structs | [`src/libraries/`](./src/libraries/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
 | Scripts | [`script/`](./script/) |
 | Tests | [`test/`](./test/) |
 
 ## Purpose
 
-Tiered ERC-721 NFT issuance and cash-out hook for Juicebox V6. This repo controls tier pricing, reserve issuance, voting units, split forwarding, and deployer flows for projects that mint NFTs on pay.
+Tiered NFT hook for Juicebox V6. This repo handles priced NFT tiers, reserve logic, tier-aware cash outs, and deployer flows that wire those hooks into projects.
 
 ## Reference Files
 
-- Open [`references/runtime.md`](./references/runtime.md) when you need the contract roles, payment and cash-out path, reserve math, or the main invariants that should hold while editing.
-- Open [`references/operations.md`](./references/operations.md) when you need deployer behavior, metadata and permission surfaces, test breadcrumbs, or the common failure modes to verify before shipping.
+- Open [`references/runtime.md`](./references/runtime.md) when you need hook and store roles, cash-out weight behavior, or main invariants.
+- Open [`references/operations.md`](./references/operations.md) when you need permission paths, tier-adjustment rules, test breadcrumbs, or common stale assumptions.
 
 ## Working Rules
 
-- Start in [`src/JB721TiersHook.sol`](./src/JB721TiersHook.sol) for pay and cash-out behavior, but verify storage-side assumptions in [`src/JB721TiersHookStore.sol`](./src/JB721TiersHookStore.sol) before changing mint, burn, reserve, or supply logic.
-- The store is the source of truth for supply, reserve, removal, and tier-order invariants. Do not “fix” those concepts only in the hook layer.
-- Pending reserves are part of live economics, not deferred bookkeeping. Cash-out denominators and tier availability both depend on them before reserves are minted.
-- Pay credits, overspending protection, and tier split forwarding are economically relevant. Treat them like accounting, not just UX.
-- Treat tier splits, reserve minting, and discounted pricing as treasury-sensitive. Check both runtime code and regression coverage before assuming a change is local.
-- Discounted mint price and cash-out weight are intentionally not the same thing. Free or discounted mints can still carry full tier cash-out weight by design.
-- Changing the default reserve beneficiary is not cosmetic. It can change which tiers have pending reserves and therefore change redemption economics for existing mints.
-- When a task mentions token metadata or rendering, confirm whether the behavior lives in this repo or in an external resolver. Do not over-edit the hook when the real change belongs downstream.
-- When changing deployers or initialization, verify the hook, store, and project-launch path stay aligned. These flows are tightly coupled.
+- Start in [`src/JB721TiersHookStore.sol`](./src/JB721TiersHookStore.sol) for tier accounting questions.
+- Keep hook behavior, store behavior, and resolver behavior separate.
+- Reserve logic, split routing, and cash-out weight calculations are part of the economic surface.
+- Tier adjustments are high-risk because many tier properties are intentionally immutable after creation.
+- If a problem looks like metadata only, verify it is not actually a hook or store issue first.

package/USER_JOURNEYS.md

@@ -2,192 +2,120 @@
 
 ## Repo Purpose
 
-This repo is the standard tiered NFT hook for V6 projects.
-It owns tier issuance, reserve accounting, hook-aware mint and cash-out behavior, and deployer packaging for hook
-clones or hook-shaped project launches. It does not own collection-specific rendering or app-layer policy built on top
-of the hook.
+This repo adds tiered NFT logic to Juicebox payment and cash-out flows. It owns tier pricing, reserves, and NFT lifecycle state. It does not own project-specific artwork or game logic.
 
 ## Primary Actors
 
-- project owners selling or rewarding supporters with tiered NFTs
-- operators managing tier supply, pricing, reserves, and ruleset-aware hook behavior
-- supporters minting or cashing out tier positions through normal Juicebox flows
-- integrators composing custom token URI resolvers or downstream products on top of the hook
+- projects that want priced NFT tiers in their Juicebox flow
+- operators managing tier configuration and hook permissions
+- holders minting, transferring, and cashing out tiered NFTs
+- auditors reviewing tier accounting, reserve behavior, and deployer wiring
 
 ## Key Surfaces
 
-- `JB721TiersHook`: project-facing hook behavior for minting, reserves, metadata, and cash out
-- `JB721TiersHookStore`: tier definitions and accounting backend
-- `JB721TiersHookDeployer`: clone factory for existing projects
-- `JB721TiersHookProjectDeployer`: project-launch packaging for new hook-backed projects
+- `JB721TiersHook`: runtime 721 hook behavior
+- `JB721TiersHookStore`: tier accounting and supply state
+- `JB721TiersHookDeployer` and `JB721TiersHookProjectDeployer`: wiring surfaces
+- token URI resolver contracts in downstream repos: presentation layer
 
-## Journey 1: Add A Tiered 721 Hook To An Existing Project
+## Journey 1: Launch A Project With A Tiered NFT Hook
 
-**Actor:** project owner or deployer.
+**Actor:** project operator or deployer.
 
-**Intent:** attach tiered NFT behavior to an existing project without relaunching it.
+**Intent:** attach tiered NFT issuance to a project from the start.
 
 **Preconditions**
-- the project already exists in Juicebox
-- the owner knows the tier config, reserve behavior, and resolver assumptions it wants
-- the next ruleset metadata can be updated safely
+- the project knows its tier structure and hook expectations
+- the deployer path matches whether the project already exists
 
 **Main Flow**
-1. Use `JB721TiersHookDeployer` to clone a hook for the project.
-2. Define tier config, reserve behavior, resolver choice, and per-ruleset flags.
-3. Queue or install ruleset metadata that points at the hook.
-4. Future payments can now mint tiers under the configured constraints.
+1. Deploy a hook clone or launch a project with the hook already attached.
+2. Configure tier data, hook metadata, and resolver expectations.
+3. Transfer hook ownership into the intended project control surface.
 
 **Failure Modes**
-- the hook is deployed correctly but the ruleset metadata does not actually activate it
-- teams treat the resolver as cosmetic when it is part of the trusted surface
+- wrong hook wiring at launch
+- wrong resolver assumptions
+- teams treat deployer convenience as proof that runtime economics are correct
 
 **Postconditions**
-- the project has an attached hook and future rulesets can mint tiers under the configured constraints
+- the project has a tiered NFT hook wired into its Juicebox flow
 
-## Journey 2: Launch A New Project With A 721 Hook Already Wired In
+## Journey 2: Pay And Mint Tiered NFTs
 
-**Actor:** product team or deployer.
+**Actor:** payer or integration acting for a payer.
 
-**Intent:** launch a project whose treasury and tiered NFT logic are aligned from the first ruleset.
+**Intent:** mint NFTs from configured tiers while preserving the project's terminal flow.
 
 **Preconditions**
-- the team has launch config, terminal config, and initial tier config ready
+- the project has active tiers
+- payment metadata correctly names the intended tiers
 
 **Main Flow**
-1. Use `JB721TiersHookProjectDeployer` with launch and hook config.
-2. Launch the project and deploy the hook in the same packaged flow.
-3. Ensure the first ruleset already points at the created hook.
-4. Start life as a hook-backed project instead of converting later.
+1. A payment reaches the hook through the terminal.
+2. The hook decodes tier selection and records mint state in the store.
+3. NFTs mint, reserve implications update, and any split routing is applied.
 
 **Failure Modes**
-- deployers assume the package is purely convenience and miss the initial ruleset implications
-- launch-time metadata drifts from the actual hook config
+- malformed metadata
+- currency mismatch or missing pricing support
+- splits or discounts behave differently than the integration expected
 
 **Postconditions**
-- the project launches with tiered NFT logic active from the first ruleset
+- the payer or beneficiary receives the intended NFT tiers and tier state updates
 
-## Journey 3: Mint Specific Tiers Through A Payment
+## Journey 3: Mint Or Release Reserve NFTs
 
-**Actor:** payer.
+**Actor:** reserve beneficiary, operator, or any caller using the reserve path.
 
-**Intent:** mint one or more tiers through a normal payment flow.
+**Intent:** realize pending reserves under the configured reserve rules.
 
 **Preconditions**
-- the project has live tiers
-- the payer submits metadata encoding the intended tier selections
+- the relevant tiers have reserve logic enabled
+- the ruleset does not pause pending reserve minting
 
 **Main Flow**
-1. Submit a payment with tier-selection metadata.
-2. `JB721TiersHook` validates availability, quantity rules, discounts, and ruleset flags.
-3. `JB721TiersHookStore` updates supply and reserve accounting.
-4. The hook mints the intended NFTs and the terminal completes treasury accounting.
+1. Eligible reserve amounts accumulate as mint activity happens.
+2. A caller triggers reserve minting for pending tiers.
+3. The store moves reserve state forward and NFTs mint to the configured reserve beneficiary.
 
 **Failure Modes**
-- sold-out tiers, malformed metadata, or cross-currency pricing mistakes
-- pay-hook participation flags do not match the user's assumptions
-- split-routing or hook behavior changes what part of the payment actually mints
+- teams misunderstand that reserve minting timing is not owner-exclusive
+- reserve assumptions drift from actual tier settings
 
 **Postconditions**
-- the intended tiers are minted and store accounting reflects the updated supply and reserve state
+- pending reserves mint according to tier configuration
 
-## Journey 4: Mint Reserves And Operate Tier Inventory Over Time
+## Journey 4: Cash Out Tiered NFTs
 
-**Actor:** owner or authorized operator.
+**Actor:** NFT holder.
 
-**Intent:** manage tier inventory and reserve behavior after launch.
+**Intent:** redeem tiered NFT exposure through the terminal cash-out path.
 
 **Preconditions**
-- the collection is live
-- the operator has the required permission surfaces to mutate tiers or mint reserves
+- the holder owns valid NFTs
+- the hook is active for the cash-out path
 
 **Main Flow**
-1. Use tier-management surfaces to add, remove, or adjust tiers.
-2. Mint reserves through the configured reserve logic.
-3. Let the store preserve historical tier state so old token IDs still resolve correctly.
-4. Keep downstream products assuming stable tier semantics whenever possible.
+1. The holder requests a cash out with NFT-specific metadata.
+2. The hook burns the selected NFTs and records the burn in the store.
+3. The terminal completes reclaim logic using the hook-aware cash-out surface.
 
 **Failure Modes**
-- tier mutations surprise downstream products or resolvers
-- reserve accounting is misread as ordinary minting
+- integrations mix fungible-token and NFT cash-out assumptions
+- pending reserves or discounts are misunderstood in value calculations
+- token IDs are invalid or already burned
 
 **Postconditions**
-- live tier inventory and reserve state match the operator's configured collection policy
-
-## Journey 5: Let Holders Cash Out Tier Positions
-
-**Actor:** holder.
-
-**Intent:** exit a tier position through the project's cash-out path.
-
-**Preconditions**
-- the holder owns one or more NFTs from the hook-enabled project
-- the active ruleset allows a surplus-backed exit
-
-**Main Flow**
-1. Call the project's cash-out path on the terminal.
-2. Let the hook participate in cash-out calculation so tier state is reflected.
-3. Burn or consume the tier exposure as required by the exit path.
-4. Receive the reclaim value through the terminal that holds the asset.
-
-**Failure Modes**
-- the project uses the hook for metadata only and the holder assumes an economic cash-out path exists
-- terminal behavior or reserve drift changes reclaim expectations
-
-**Postconditions**
-- the holder exits the tier position through the hook-aware terminal path or learns that no such economic path is active
-
-## Journey 6: Compose A Custom Product On Top Of The Standard Hook
-
-**Actor:** integrator or downstream product team.
-
-**Intent:** build collection-specific behavior without reimplementing hook economics.
-
-**Preconditions**
-- the team wants custom presentation or app-layer logic
-- the team does not want to fork pricing, reserve, and treasury behavior
-
-**Main Flow**
-1. Plug a custom resolver or wrapper into the hook.
-2. Keep collection-specific behavior outside this repo.
-3. Audit hook-store interactions here first, then audit the downstream wrapper.
-
-**Failure Modes**
-- downstream products reimplement hook behavior and drift from canonical accounting
-- teams blame the hook for bugs that actually live in the resolver or wrapper
-
-**Postconditions**
-- the custom product reuses canonical hook economics while isolating collection-specific behavior downstream
-
-## Journey 7: Mint NFTs To The Correct Beneficiary During Cross-Chain Payments
-
-**Actor:** cross-chain payer or integrator.
-
-**Intent:** preserve the real remote beneficiary when a sucker relays a payment.
-
-**Preconditions**
-- a sucker or relay path pays on behalf of a remote user
-- relay-beneficiary metadata is encoded correctly
-
-**Main Flow**
-1. The sucker calls `terminal.pay()` with relay-beneficiary metadata.
-2. `_mintAndUpdateCredits` resolves the relay beneficiary when `payer == beneficiary`.
-3. NFT minting and credit accounting use the resolved remote user.
-
-**Failure Modes**
-- relay metadata is missing or malformed
-- downstream systems attribute NFTs or credits to the sucker instead of the user
-
-**Postconditions**
-- NFT minting and credit accounting attribute the remote payment to the correct beneficiary
+- NFTs burn and reclaim value follows the intended tier model
 
 ## Trust Boundaries
 
-- `JB721TiersHookStore` is the accounting backend and should be treated as part of the same economic surface as the hook
-- custom token URI resolvers are part of the trusted collection surface
-- core terminals remain the source of treasury accounting truth around the hook
+- this repo trusts core terminals, directory checks, and pricing surfaces from `nana-core-v6`
+- metadata resolvers are outside this repo but still affect user-visible trust
+- the store is the main source of truth for tier lifecycle state
 
 ## Hand-Offs
 
-- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the treasury, ruleset, and permission surfaces the hook plugs into.
-- Use [banny-retail-v6](../banny-retail-v6/USER_JOURNEYS.md), [croptop-core-v6](../croptop-core-v6/USER_JOURNEYS.md), and [revnet-core-v6](../revnet-core-v6/USER_JOURNEYS.md) for product layers built on this hook.
+- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the underlying terminal and accounting behavior.
+- Use the downstream resolver repo when the question is about project-specific metadata or rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JB721CheckpointsDeployer.sol

@@ -37,6 +37,8 @@ contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
     /// @param store The store that holds tier data for the hook's NFTs.
     /// @return module The newly deployed and initialized checkpoint module.
     function deploy(address hook, IJB721TiersHookStore store) external override returns (IJB721Checkpoints module) {
+        if (msg.sender != hook) revert JB721CheckpointsDeployer_Unauthorized();
+
         module = IJB721Checkpoints(
             LibClone.cloneDeterministic({implementation: IMPLEMENTATION, salt: bytes32(uint256(uint160(hook)))})
         );