@bananapus/721-hook-v6 0.0.6 → 0.0.8

package/README.md

@@ -1,9 +1,9 @@
-# Bananapus NFT Hook
+# Juicebox 721 Hook
 
 `nana-721-hook` is:
 
 1. A pay hook for Juicebox projects to sell tiered NFTs (ERC-721s) with different prices and artwork.
-2. (Optionally) a redeem hook which allows holders to burn their NFTs to reclaim funds from the project, in proportion to the NFT's price.
+2. (Optionally) a cash out hook which allows holders to burn their NFTs to reclaim funds from the project, in proportion to the NFT's price.
 
 <details>
   <summary>Table of Contents</summary>
@@ -156,15 +156,15 @@ nana-721-hook/
 │   └── helpers/
 │       └── Hook721DeploymentLib.sol - Internal helpers for deployment scripts.
 ├── src/ - Contract source code. Top level contains implementation contracts.
-│   ├── JB721TiersHook.sol - The core tiered NFT pay/redeem hook.
+│   ├── JB721TiersHook.sol - The core tiered NFT pay/cash out hook.
 │   ├── JB721TiersHookDeployer.sol - Deploys an NFT hook for a project.
 │   ├── JB721TiersHookProjectDeployer.sol - Deploys a project with a tiered NFT hook.
 │   ├── JB721TiersHookStore.sol - Stores and manages data for tiered NFT hooks.
 │   ├── abstract/
-│   │   ├── ERC721.sol - Abstract ERC-721 implementation.
-│   │   └── JB721Hook.sol - Abstract NFT hook implementation.
+│   │   ├── JB721Hook.sol - Abstract base hook: handles pay/cash out lifecycle, metadata, and terminal validation.
+│   │   └── ERC721.sol - Clone-compatible abstract ERC-721 implementation.
 │   ├── interfaces/ - Contract interfaces.
-│   ├── libraries/ - Libraries.
+│   ├── libraries/ - Libraries (includes JB721TiersHookLib for tier adjustments, split distribution, price normalization, and token URI resolution).
 │   └── structs/ - Structs.
 └── test/ - Forge tests and testing utilities.
     ├── E2E/
@@ -190,9 +190,9 @@ graph TD;
     D[JB721TiersHookDeployer] -->|Adds NFT hooks to| B
     A -->|Deploys| C[JB721TiersHook]
     D -->|Deploys| C
-    B -->|Calls upon pay/redeem| C
+    B -->|Calls upon pay/cash out| C
     C -->|Stores data in| E[JB721TiersHookStore]
-    B -->|Uses| F[Pay/redeem terminal]
+    B -->|Uses| F[Pay/cash out terminal]
     C -->|Mints NFTs upon payment through| F
     C -->|Burns NFTs to reclaim funds through| F
 ```
@@ -201,7 +201,8 @@ graph TD;
 
 | Contract                                                                                                                          | Description                                                                                             |
 | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| [`JB721TiersHook.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHook.sol)                               | The core tiered NFT pay/redeem hook implementation.                                                     |
+| [`JB721Hook.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/abstract/JB721Hook.sol)                                 | Abstract base for 721 hooks: handles pay/cash out lifecycle, terminal validation, and metadata resolution. |
+| [`JB721TiersHook.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHook.sol)                               | The core tiered NFT pay/cash out hook implementation, extending `JB721Hook`.                              |
 | [`JB721TiersHookDeployer.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHookDeployer.sol)               | Exposes a `deployHookFor(…)` function which allows deploys an NFT hook for a project.                   |
 | [`JB721TiersHookProjectDeployer.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHookProjectDeployer.sol) | Exposes a `launchProjectFor(…)` function which deploys a project with a tiered NFT hook already set up. |
 | [`JB721TiersHookStore.sol`](https://github.com/Bananapus/nana-721-hook/blob/main/src/JB721TiersHookStore.sol)                     | Stores and manages data for tiered NFT hooks.                                                           |
@@ -210,44 +211,47 @@ graph TD;
 
 ### Hooks
 
-This contract is a _data hook_, a _pay hook_, and a _redeem hook_. Data hooks receive information about a payment or a redemption, and put together a payload for the pay/redeem hook to execute.
+This contract is a _data hook_, a _pay hook_, and a _cash out hook_. Data hooks receive information about a payment or a cash out, and put together a payload for the pay/cash out hook to execute.
 
-Juicebox projects can specify a data hook in their `JBRulesetMetadata`. When someone attempts to pay or redeem from the project, the project's terminal records the payment in the terminal store, passing information about the payment/redemption to the data hook in the process. The data hook responds with a list of payloads – each payload specifies the address of a pay/redeem hook, as well as some custom data and an amount of funds to send to that pay/redeem hook.
+Juicebox projects can specify a data hook in their `JBRulesetMetadata`. When someone attempts to pay or cash out from the project, the project's terminal records the payment in the terminal store, passing information about the payment/cash out to the data hook in the process. The data hook responds with a list of payloads – each payload specifies the address of a pay/cash out hook, as well as some custom data and an amount of funds to send to that pay/cash out hook.
 
-Each pay/redeem hook can then execute custom behavior based on the custom data (and funds) they receive.
+Each pay/cash out hook can then execute custom behavior based on the custom data (and funds) they receive.
 
 ### Mechanism
 
-A project using a 721 tiers hook can specify any number of NFT tiers.
+A project using a 721 tiers hook can specify any number of NFT tiers (up to 65,535 total).
 
-- NFT tiers can be removed by the project owner as long as they are not locked.
-- NFT tiers can be added by the project owner as long as they respect the hook's `flags`. The flags specify if newly added tiers can have votes (voting units), if new tiers can have non-zero reserve frequencies, if new tiers can allow on-demand minting by the project's owner, and if the tier can be removed.
+- NFT tiers can be removed by the project owner as long as they are not locked (`cannotBeRemoved`). After removing tiers, call `cleanTiers()` on the store to optimize tier iteration.
+- NFT tiers can be added by the project owner as long as they respect the hook's `flags`. The flags specify if newly added tiers can have votes (voting units), if new tiers can have non-zero reserve frequencies, if new tiers can allow on-demand minting by the project's owner, and if overspending is allowed.
 
-Each tier has the following optional properties:
+Each tier has the following properties:
 
-- A price.
-- A supply (the maximum number of NFTs which can be minted from the tier).
+- A price (up to `uint104`).
+- A supply (the maximum number of NFTs which can be minted from the tier, up to 999,999,999).
 - A token URI (artwork and metadata), which can be overridden by a URI resolver. The URI resolver can return unique values for each NFT in the tier.
 - A category, so tiers can be organized and accessed for different purposes.
-- A reserve frequency (optional). With a reserve frequency of 5, an extra NFT will be minted to a pre-specified beneficiary address for every 5 NFTs purchased and minted from the tier.
-- A number of votes each NFT should represent on-chain (optional).
+- A discount percent (optional). Reduces the effective purchase price. The discount is out of 200, so a `discountPercent` of 100 means 50% off, and 200 means free. The discount can be changed later via `setDiscountPercentOf`, and tiers can be configured with `cannotIncreaseDiscountPercent` to only allow discounts to decrease. Cash out weight is always based on the original tier price, not the discounted price.
+- A reserve frequency (optional). With a reserve frequency of 5, an extra NFT will be minted to a pre-specified beneficiary address for every 5 NFTs purchased and minted from the tier. Tiers with owner minting enabled cannot have reserves.
+- Voting units (optional). By default, each NFT's voting power equals its tier price. If `useVotingUnits` is true, a custom `votingUnits` value is used instead.
 - A flag to specify whether the NFTs in the tier can always be transferred, or if transfers can be paused depending on the project's ruleset.
 - A flag to specify whether the contract's owner can mint NFTs from the tier on-demand.
-- A set of flags which restrict tiers added in the future (the votes/reserved frequency/on-demand minting/can be removed flags noted above).
+- A split percent and a set of splits (optional). Each tier can route a percentage of its mint price to configured split recipients (other projects, addresses, etc.) every time an NFT from the tier is purchased. The remaining funds stay in the project's balance. The `splitPercent` is out of `JBConstants.SPLITS_TOTAL_PERCENT` (1,000,000,000).
+- A set of flags which restrict tiers added in the future (the votes/reserved frequency/on-demand minting/overspending flags noted above).
 
 Additional notes:
 
-- A payer can specify any number of tiers to mint as long as the total price does not exceed the amount being paid. If tiers aren't specified, their payment mints the most expensive tier possible, unless they specify that the hook should not mint any NFTs.
-- If the payment and a tier's price are specified in different currencies, the `JBPrices` contract is used to normalize the values.
-- If some of a payment does not go towards purchasing an NFT, those extra funds will be stored as "NFT credits" which can be used for future purchases. Optionally, the hook can disallow credits and reject payments with leftover funds.
-- If enabled by the project owner, holders can burn their NFTs to reclaim funds from the project. These redemptions are proportional to the NFTs price, relative to the combined price of all the NFTs.
-- NFT redemptions can be enabled by setting `useDataHookForRedeem` to `true` in the project's `JBRulesetMetadata`. If NFT redemptions are enabled, project token redemptions are disabled.
-- The hook's deployer can choose if the NFTs should support on-chain voting (as `ERC721Votes`). This increases the gas fees to interact with the NFTs, and should be disabled if not needed.
+- A payer can specify any number of tiers to mint as long as the total price does not exceed the amount being paid. If tiers aren't specified, the leftover amount is stored as pay credits (if allowed).
+- If the payment and a tier's price are specified in different currencies, the `JBPrices` contract is used to normalize the values. If no `JBPrices` contract is set and the currencies differ, the payment is silently ignored (no mint, no revert).
+- If some of a payment does not go towards purchasing an NFT, those extra funds will be stored as "NFT credits" which can be used for future purchases. Credits are only combined with the payment when `payer == beneficiary`. Optionally, the hook can disallow credits and reject payments with leftover funds (via `preventOverspending`).
+- If enabled by the project owner, holders can burn their NFTs to reclaim funds from the project. These cash outs are proportional to the NFTs price, relative to the combined price of all the NFTs (including pending reserves in the denominator).
+- NFT cash outs can be enabled by setting `useDataHookForCashOut` to `true` in the project's `JBRulesetMetadata`. If NFT cash outs are enabled, project token cash outs are disabled -- attempting to cash out fungible tokens when the data hook is active will revert.
+- Per-tier voting units can be configured: either custom voting units or the tier's price as the default. Voting power is computed per-address across all tiers.
+- The hook declares support for ERC-2981 (royalties) via `supportsInterface`, but does not implement the `royaltyInfo` function. This is intended for future extension.
 
 ### Setup
 
 To use a 721 tiers hook, a Juicebox project should be created by a `JB721TiersHookProjectDeployer` instead of a `JBController`. The deployer will create a `JB721TiersHook` (through an associated `JB721TiersHookDeployer`) and add it to the project's first ruleset. New rulesets can be queued with `JB721TiersHookProjectDeployer.queueRulesetsOf(…)` if the project's owner gives the project deployer the permission [`JBPermissions.QUEUE_RULESETS`](https://github.com/Bananapus/nana-permission-ids/blob/master/src/JBPermissionIds.sol) (ID `2`) in [`JBPermissions`](https://github.com/Bananapus/nana-core/blob/main/src/JBPermissions.sol).
 
-It's also possible to add a 721 tiers hook to an existing project by calling `JB721TiersHookDeployer.deployHookFor(…)` and adding the hook to the project's ruleset – specifically, the project must set their [`JBRulesetMetadata.dataHook`](https://github.com/Bananapus/nana-core/blob/main/src/structs/JBRulesetMetadata.sol) to the newly deployed hook, and enable `JBRulesetMetadata.useDataHookForPay` and/or `JBRulesetMetadata.useDataHookForRedeem` depending on the functionality they'd like to enable.
+It's also possible to add a 721 tiers hook to an existing project by calling `JB721TiersHookDeployer.deployHookFor(…)` and adding the hook to the project's ruleset – specifically, the project must set their [`JBRulesetMetadata.dataHook`](https://github.com/Bananapus/nana-core/blob/main/src/structs/JBRulesetMetadata.sol) to the newly deployed hook, and enable `JBRulesetMetadata.useDataHookForPay` and/or `JBRulesetMetadata.useDataHookForCashOut` depending on the functionality they'd like to enable.
 
 All `JB721TiersHook`s store their data in the `JB721TiersHookStore` contract.

package/SKILLS.md

@@ -1,4 +1,4 @@
-# nana-721-hook-v5
+# Juicebox 721 Hook
 
 ## Purpose
 
@@ -8,76 +8,166 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 
 | Contract | Role |
 |----------|------|
-| `JB721TiersHook` | Core hook: processes payments (mints NFTs), processes cash outs (burns NFTs), manages tiers, reserves, credits, metadata, and discount percents. Deployed as minimal clones. |
+| `JB721Hook` (abstract) | Abstract base hook: owns `DIRECTORY`, `METADATA_ID_TARGET`, `PROJECT_ID`. Implements `afterPayRecordedWith` (terminal validation + delegates to virtual `_processPayment`), `afterCashOutRecordedWith` (terminal validation, burn loop, delegates to virtual `_didBurn`), `beforeCashOutRecordedWith` (metadata decoding, delegates to virtual `cashOutWeightOf`/`totalCashOutWeight`), `beforePayRecordedWith` (default: forward weight), `hasMintPermissionFor` (returns false), `supportsInterface`, and `_initialize`. |
+| `JB721TiersHook` | Core hook: extends `JB721Hook`. Manages tiers, reserves, credits, metadata, and discount percents. Deployed as minimal clones. Inherits `JBOwnable`, `ERC2771Context`, `JB721Hook`, `IJB721TiersHook`. Overrides `cashOutWeightOf`, `totalCashOutWeight`, `_didBurn`, `_processPayment`, and `beforePayRecordedWith` (adds tier split calculation). |
 | `JB721TiersHookStore` | Shared singleton storage for all hook instances. Stores tiers (`JBStored721Tier`), balances, reserves, bitmaps for removed tiers, flags, and token URI resolvers. |
 | `JB721TiersHookDeployer` | Factory: clones `JB721TiersHook` via `LibClone.clone` / `cloneDeterministic`, initializes, registers in address registry. |
-| `JB721TiersHookProjectDeployer` | Convenience deployer: creates a Juicebox project + hook in one transaction. Wires the hook as the data hook with `useDataHookForPay: true`. |
-| `JB721Hook` (abstract) | Base: implements `IJBRulesetDataHook` + `IJBPayHook` + `IJBCashOutHook`. Validates caller is a project terminal. |
+| `JB721TiersHookProjectDeployer` | Convenience deployer: creates a Juicebox project + hook in one transaction. Also supports `launchRulesetsFor` and `queueRulesetsOf`. Wires the hook as the data hook with `useDataHookForPay: true`. |
+| `JB721TiersHookLib` (library) | External library called via DELEGATECALL from the hook. Handles tier adjustments (`adjustTiersFor`), split amount calculation (`calculateSplitAmounts`), split fund distribution (`distributeAll`), price normalization (`normalizePaymentValue`), and token URI resolution (`resolveTokenURI`). Extracted to stay within EIP-170 contract size limit. |
+| `IJB721Hook` (interface) | Interface for `JB721Hook`: extends `IJBRulesetDataHook`, `IJBPayHook`, `IJBCashOutHook`. Declares `DIRECTORY()`, `METADATA_ID_TARGET()`, `PROJECT_ID()`. |
 | `ERC721` (abstract) | Clone-compatible ERC-721 with `_initialize(name, symbol)` instead of constructor args. |
 
 ## Key Functions
 
 | Function | Contract | What it does |
 |----------|----------|--------------|
-| `initialize(projectId, name, symbol, baseUri, tokenUriResolver, contractUri, tiersConfig, flags)` | `JB721TiersHook` | One-time setup for a cloned hook instance. Stores pricing context (currency, decimals, prices contract packed into uint256), records tiers and flags in the store. |
-| `afterPayRecordedWith(context)` | `JB721Hook` | Called by terminal after payment. Validates caller is a project terminal, delegates to `_processPayment`. |
-| `_processPayment(context)` | `JB721TiersHook` | Normalizes payment value via pricing context, decodes payer metadata for tier IDs to mint, calls `_mintAll`, manages pay credits for overspending. |
-| `afterCashOutRecordedWith(context)` | `JB721Hook` | Called by terminal during cash out. Decodes token IDs from metadata, validates ownership, burns NFTs, calls `_didBurn`. |
-| `beforePayRecordedWith(context)` | `JB721Hook` | Data hook: returns original weight and sets this contract as the pay hook (amount=0). |
-| `beforeCashOutRecordedWith(context)` | `JB721Hook` | Data hook: calculates `cashOutCount` (weight of NFTs being cashed out) and `totalSupply` (total weight of all NFTs). Rejects if fungible tokens are also being cashed out. |
-| `adjustTiers(tiersToAdd, tierIdsToRemove)` | `JB721TiersHook` | Owner-only. Adds/removes tiers via the store. Requires `ADJUST_721_TIERS` permission. |
+| `initialize(projectId, name, symbol, baseUri, tokenUriResolver, contractUri, tiersConfig, flags)` | `JB721TiersHook` | One-time setup for a cloned hook instance. Stores pricing context (currency, decimals, prices contract packed into uint256), records tiers and flags in the store. Validates `decimals <= 18`. |
+| `afterPayRecordedWith(context)` | `JB721Hook` | Called by terminal after payment. Validates caller is a project terminal, delegates to virtual `_processPayment`. |
+| `_processPayment(context)` | `JB721TiersHook` | Normalizes payment value via pricing context, decodes payer metadata for tier IDs to mint, calls `_mintAll`, manages pay credits for overspending. Distributes tier split funds via `JB721TiersHookLib.distributeAll` if split amounts were forwarded. |
+| `afterCashOutRecordedWith(context)` | `JB721Hook` | Called by terminal during cash out. Decodes token IDs from metadata, validates ownership, burns NFTs, delegates to virtual `_didBurn`. Reverts if `msg.value != 0`. |
+| `beforePayRecordedWith(context)` | `JB721TiersHook` | Data hook: returns original weight, calculates per-tier split amounts via `JB721TiersHookLib.calculateSplitAmounts`, and sets this contract as the pay hook with the total split amount forwarded. |
+| `beforeCashOutRecordedWith(context)` | `JB721Hook` | Data hook: calculates `cashOutCount` (via virtual `cashOutWeightOf`) and `totalSupply` (via virtual `totalCashOutWeight`). Rejects if fungible tokens are also being cashed out. |
+| `adjustTiers(tiersToAdd, tierIdsToRemove)` | `JB721TiersHook` | Owner-only. Adds/removes tiers via `JB721TiersHookLib.adjustTiersFor` (DELEGATECALL). Requires `ADJUST_721_TIERS` permission. Registers tier splits in `JBSplits` if configured. |
 | `mintFor(tierIds, beneficiary)` | `JB721TiersHook` | Owner-only manual mint. Requires `MINT_721` permission. Passes `amount: type(uint256).max` and `isOwnerMint: true` to force the mint. |
 | `mintPendingReservesFor(tierId, count)` | `JB721TiersHook` | Public. Mints pending reserve NFTs for a tier to the tier's `reserveBeneficiary`. Checks ruleset metadata for `mintPendingReservesPaused`. |
-| `setMetadata(baseUri, contractUri, tokenUriResolver, encodedIPFSTUriTierId, encodedIPFSUri)` | `JB721TiersHook` | Owner-only. Updates base URI, contract URI, token URI resolver, or per-tier encoded IPFS URI. Requires `SET_721_METADATA` permission. |
+| `mintPendingReservesFor(configs[])` | `JB721TiersHook` | Batch variant. Calls `mintPendingReservesFor(tierId, count)` for each config. |
+| `setMetadata(baseUri, contractUri, tokenUriResolver, encodedIPFSUriTierId, encodedIPFSUri)` | `JB721TiersHook` | Owner-only. Updates base URI, contract URI, token URI resolver, or per-tier encoded IPFS URI. Requires `SET_721_METADATA` permission. |
 | `setDiscountPercentOf(tierId, discountPercent)` | `JB721TiersHook` | Owner-only. Sets discount percent for a tier. Requires `SET_721_DISCOUNT_PERCENT` permission. |
+| `setDiscountPercentsOf(configs[])` | `JB721TiersHook` | Batch variant. Sets discount percent for multiple tiers. Requires `SET_721_DISCOUNT_PERCENT` permission. |
+| `tokenURI(tokenId)` | `JB721TiersHook` | Resolves token metadata URI. Delegates to `JB721TiersHookLib.resolveTokenURI`, which checks for a custom `tokenUriResolver` first, then falls back to IPFS decoding via `JBIpfsDecoder`. |
+| `firstOwnerOf(tokenId)` | `JB721TiersHook` | Returns the first owner of an NFT (the address that originally received it). Stored on first transfer out; returns current owner if never transferred. |
+| `pricingContext()` | `JB721TiersHook` | Unpacks and returns the currency, decimals, and prices contract from the packed `_packedPricingContext`. |
+| `balanceOf(owner)` | `JB721TiersHook` | Overrides ERC-721 `balanceOf` to delegate to `STORE.balanceOf`, which sums across all tiers. |
+| `hasMintPermissionFor(...)` | `JB721Hook` | Always returns `false`. Required by `IJBRulesetDataHook`; prevents the hook from granting mint permissions to anyone. |
+| `supportsInterface(interfaceId)` | `JB721TiersHook` | Returns `true` for `IJB721TiersHook`, `IJBRulesetDataHook`, `IJBPayHook`, `IJBCashOutHook`, `IERC2981`, `IERC721`, `IERC721Metadata`, `IERC165`. |
 | `deployHookFor(projectId, config, salt)` | `JB721TiersHookDeployer` | Clones the hook implementation, initializes it, transfers ownership to caller, registers in address registry. |
 | `launchProjectFor(owner, deployConfig, launchConfig, controller, salt)` | `JB721TiersHookProjectDeployer` | Creates project via controller, deploys hook, wires hook as data hook with `useDataHookForPay: true`, transfers hook ownership to project. |
-| `recordMint(amount, tierIds, isOwnerMint)` | `JB721TiersHookStore` | Records minting: validates supply, checks tier prices against amount (unless owner mint), generates token IDs (tierId * 1_000_000_000 + mintCount), tracks reserves. |
-| `recordAddTiers(tiers)` | `JB721TiersHookStore` | Adds new tiers sorted by category. Validates against hook flags (no new reserves/votes/owner-minting if flagged). |
-| `recordRemoveTierIds(tierIds)` | `JB721TiersHookStore` | Marks tiers as removed in the bitmap. Validates tier is not locked (`cannotBeRemoved`). |
+| `launchRulesetsFor(projectId, deployConfig, launchRulesetsConfig, controller, salt)` | `JB721TiersHookProjectDeployer` | Deploys a hook for an existing project and launches rulesets. Requires `QUEUE_RULESETS` and `SET_TERMINALS` permissions. Transfers hook ownership to project. |
+| `queueRulesetsOf(projectId, deployConfig, queueRulesetsConfig, controller, salt)` | `JB721TiersHookProjectDeployer` | Deploys a hook and queues rulesets for an existing project. Requires `QUEUE_RULESETS` permission. Transfers hook ownership to project. |
+| `recordMint(amount, tierIds, isOwnerMint)` | `JB721TiersHookStore` | Records minting: validates supply, checks tier prices against amount (unless owner mint), applies discount if set, generates token IDs (`tierId * 1_000_000_000 + mintCount`), ensures remaining supply covers pending reserves. |
+| `recordAddTiers(tiers)` | `JB721TiersHookStore` | Adds new tiers sorted by category. Validates against hook flags (no new reserves/votes/owner-minting if flagged). Enforces max tier count (`type(uint16).max`), max supply per tier (`999_999_999`), discount percent bounds, non-zero supply, category sort order, and reserve+owner-mint mutual exclusion. |
+| `recordRemoveTierIds(tierIds)` | `JB721TiersHookStore` | Marks tiers as removed in the bitmap. Validates tier is not locked (`cannotBeRemoved`). Does NOT update the sorted linked list -- call `cleanTiers()` afterward. |
+| `recordMintReservesFor(tierId, count)` | `JB721TiersHookStore` | Mints reserve NFTs from remaining supply. Validates count does not exceed pending reserves. |
+| `recordSetDiscountPercentOf(tierId, discountPercent)` | `JB721TiersHookStore` | Sets discount percent for a tier. Validates bounds (`<= DISCOUNT_DENOMINATOR`). If `cannotIncreaseDiscountPercent` is set, rejects increases. |
+| `recordBurn(tokenIds)` | `JB721TiersHookStore` | Increments burn counter per tier. Trusts `msg.sender` (the hook) to have already verified ownership and burned the tokens. |
+| `cleanTiers(hook)` | `JB721TiersHookStore` | Public. Removes stale entries from the sorted tier linked list after tiers have been removed via `recordRemoveTierIds`. Optimizes tier iteration. |
+| `tiersOf(hook, categories, includeResolvedUri, startingId, size)` | `JB721TiersHookStore` | Returns an array of active tiers, optionally filtered by categories. Skips removed tiers. |
+| `tierOf(hook, id, includeResolvedUri)` | `JB721TiersHookStore` | Returns a single tier by ID. |
+| `tierOfTokenId(hook, tokenId, includeResolvedUri)` | `JB721TiersHookStore` | Returns the tier for a given token ID. |
+| `totalSupplyOf(hook)` | `JB721TiersHookStore` | Returns total NFTs minted across all tiers (excluding burns). |
+| `totalCashOutWeight(hook)` | `JB721TiersHookStore` | Returns total cash out weight (sum of `price * (minted + pendingReserves)` for all tiers). Uses original price, not discounted price. |
+| `cashOutWeightOf(hook, tokenIds)` | `JB721TiersHookStore` | Returns combined cash out weight for specific token IDs. Uses original tier price, not discounted. |
+| `votingUnitsOf(hook, account)` | `JB721TiersHookStore` | Returns total voting units for an address across all tiers. Uses custom `votingUnits` if `useVotingUnits` is set, otherwise uses tier price. |
+| `tierVotingUnitsOf(hook, account, tierId)` | `JB721TiersHookStore` | Returns voting units for an address within a specific tier. |
+| `calculateSplitAmounts(store, hook, metadataIdTarget, metadata)` | `JB721TiersHookLib` | Called in `beforePayRecordedWith`. Decodes tier IDs from payer metadata, looks up each tier's `splitPercent`, calculates `mulDiv(price, splitPercent, SPLITS_TOTAL_PERCENT)` per tier, returns `totalSplitAmount` (forwarded to hook as `amount`) and encoded `hookMetadata` (tier IDs + amounts). |
+| `distributeAll(directory, projectId, hookAddress, token, encodedSplitData)` | `JB721TiersHookLib` | Called in `afterPayRecordedWith`. Decodes per-tier amounts, looks up each tier's splits from `JBSplits` by group ID (`hookAddress | (tierId << 160)`), distributes to split recipients. Leftover goes to project balance via `addToBalance`. |
+| `adjustTiersFor(store, directory, projectId, hookAddress, caller, tiersToAdd, tierIdsToRemove)` | `JB721TiersHookLib` | Called via DELEGATECALL from `adjustTiers`. Removes tiers, adds tiers, emits events, and registers any configured splits in `JBSplits` via the project's controller. |
+| `normalizePaymentValue(packedPricingContext, projectId, amountValue, amountCurrency, amountDecimals)` | `JB721TiersHookLib` | Converts a payment value to the hook's pricing currency using `JBPrices`. Returns `(0, false)` if currencies differ and no prices contract is set. |
+| `resolveTokenURI(store, hook, baseUri, tokenId)` | `JB721TiersHookLib` | Resolves token URI: checks for custom `tokenUriResolver` first, otherwise decodes IPFS URI via `JBIpfsDecoder`. |
 
 ## Integration Points
 
 | Dependency | Import | Used For |
 |------------|--------|----------|
-| `@bananapus/core-v6` | `IJBDirectory`, `IJBRulesets`, `IJBPrices`, `IJBController`, `IJBTerminal`, `JBRuleset`, `JBRulesetMetadata`, `JBAfterPayRecordedContext`, `JBBeforeCashOutRecordedContext`, etc. | Terminal validation, ruleset metadata, pricing, payment/cash-out contexts |
+| `@bananapus/core-v6` | `IJBDirectory`, `IJBRulesets`, `IJBPrices`, `IJBController`, `IJBTerminal`, `IJBSplits`, `JBRuleset`, `JBRulesetMetadata`, `JBAfterPayRecordedContext`, `JBBeforeCashOutRecordedContext`, `JBSplit`, `JBSplitGroup`, `JBConstants`, etc. | Terminal validation, ruleset metadata, pricing, payment/cash-out contexts, splits |
 | `@bananapus/ownable-v6` | `JBOwnable` | Project-based ownership for the hook (ownership can be transferred to a project NFT) |
 | `@bananapus/permission-ids-v6` | `JBPermissionIds` | Permission IDs: `ADJUST_721_TIERS`, `MINT_721`, `SET_721_METADATA`, `SET_721_DISCOUNT_PERCENT`, `QUEUE_RULESETS`, `SET_TERMINALS` |
 | `@bananapus/address-registry-v6` | `IJBAddressRegistry` | Registering deployed hook clones |
-| `@openzeppelin/contracts` | `ERC2771Context`, `IERC165`, `IERC2981`, `IERC721` | Meta-transactions (trusted forwarder), interface detection, royalty standard |
-| `@prb/math` | `mulDiv` | Safe fixed-point multiplication/division for price normalization |
+| `@openzeppelin/contracts` | `ERC2771Context`, `IERC165`, `IERC2981`, `IERC721`, `SafeERC20` | Meta-transactions (trusted forwarder), interface detection, royalty standard declaration, safe ERC-20 transfers for split distribution |
+| `@prb/math` | `mulDiv` | Safe fixed-point multiplication/division for price normalization and discount/split calculation |
 | `solady` | `LibClone` | Minimal proxy (clone) deployment for hooks |
 
 ## Key Types
 
 | Struct/Enum | Key Fields | Used In |
 |-------------|------------|---------|
-| `JB721TierConfig` | `uint104 price`, `uint32 initialSupply`, `uint32 votingUnits`, `uint16 reserveFrequency`, `address reserveBeneficiary`, `bytes32 encodedIPFSUri`, `uint24 category`, `uint8 discountPercent`, `bool allowOwnerMint`, `bool transfersPausable`, `bool cannotBeRemoved`, `bool cannotIncreaseDiscountPercent` | `adjustTiers`, `initialize`, `recordAddTiers` |
-| `JB721Tier` | Same as config plus `uint32 id`, `uint32 remainingSupply`, `string resolvedUri` | Return type from `tierOf`, `tiersOf`, `tierOfTokenId` |
-| `JBStored721Tier` | `uint104 price`, `uint32 remainingSupply`, `uint32 initialSupply`, `uint32 votingUnits`, `uint24 category`, `uint8 discountPercent`, `uint16 reserveFrequency`, `uint8 packedBools` | Internal storage in `JB721TiersHookStore` |
-| `JB721InitTiersConfig` | `JB721TierConfig[] tiers`, `uint32 currency`, `uint8 decimals`, `IJBPrices prices` | `initialize` — defines tiers and pricing context |
+| `JB721TierConfig` | `uint104 price`, `uint32 initialSupply`, `uint32 votingUnits`, `uint16 reserveFrequency`, `address reserveBeneficiary`, `bytes32 encodedIPFSUri`, `uint24 category`, `uint8 discountPercent`, `bool allowOwnerMint`, `bool useReserveBeneficiaryAsDefault`, `bool transfersPausable`, `bool useVotingUnits`, `bool cannotBeRemoved`, `bool cannotIncreaseDiscountPercent`, `uint32 splitPercent`, `JBSplit[] splits` | `adjustTiers`, `initialize`, `recordAddTiers` |
+| `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`, `IJBPrices prices` | `initialize` -- defines tiers and pricing context |
 | `JBDeploy721TiersHookConfig` | `string name`, `string symbol`, `string baseUri`, `IJB721TokenUriResolver tokenUriResolver`, `string contractUri`, `JB721InitTiersConfig tiersConfig`, `address reserveBeneficiary`, `JB721TiersHookFlags flags` | `deployHookFor`, `launchProjectFor` |
 | `JB721TiersHookFlags` | `bool noNewTiersWithReserves`, `bool noNewTiersWithVotes`, `bool noNewTiersWithOwnerMinting`, `bool preventOverspending` | `initialize`, `recordFlags` |
-| `JB721TiersRulesetMetadata` | `bool pauseTransfers`, `bool pauseMintPendingReserves` | Packed into `JBRulesetMetadata.metadata` per-ruleset |
-| `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 |
-| `JBPayDataHookRulesetMetadata` | Same as `JBRulesetMetadata` minus `allowSetCustomToken` (hardcoded false) and `useDataHookForPay` (hardcoded true) and `dataHook` (set to deployed hook) | `launchProjectFor`, `launchRulesetsFor`, `queueRulesetsOf` |
+| `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 |
+| `JBPayDataHookRulesetMetadata` | Same as `JBRulesetMetadata` minus `allowSetCustomToken` (hardcoded false) and `useDataHookForPay` (hardcoded true) and `dataHook` (set to deployed hook). Includes `ownerMustSendPayouts`. | `launchProjectFor`, `launchRulesetsFor`, `queueRulesetsOf` |
+| `JBLaunchProjectConfig` | `string projectUri`, `JBPayDataHookRulesetConfig[] rulesetConfigurations`, `JBTerminalConfig[] terminalConfigurations`, `string memo` | `launchProjectFor` |
+| `JBLaunchRulesetsConfig` | `uint56 projectId`, `JBPayDataHookRulesetConfig[] rulesetConfigurations`, `JBTerminalConfig[] terminalConfigurations`, `string memo` | `launchRulesetsFor` |
+| `JBQueueRulesetsConfig` | `uint56 projectId`, `JBPayDataHookRulesetConfig[] rulesetConfigurations`, `string memo` | `queueRulesetsOf` |
 | `JB721TiersMintReservesConfig` | `uint32 tierId`, `uint16 count` | `mintPendingReservesFor` batch variant |
 | `JB721TiersSetDiscountPercentConfig` | `uint32 tierId`, `uint16 discountPercent` | `setDiscountPercentsOf` batch variant |
 | `JBBitmapWord` | `uint256 currentWord`, `uint256 currentDepth` | Internal tier removal tracking in store |
 
+## Constants
+
+| Constant | Value | Location | Meaning |
+|----------|-------|----------|---------|
+| `DISCOUNT_DENOMINATOR` | `200` | `JB721Constants` | Max `discountPercent` value. A `discountPercent` of 200 = 100% discount (free). A `discountPercent` of 100 = 50% off. Formula: `price -= mulDiv(price, discountPercent, 200)`. |
+| `_ONE_BILLION` | `1_000_000_000` | `JB721TiersHookStore` | Used for token ID generation: `tokenId = tierId * 1_000_000_000 + tokenNumber`. Also caps max initial supply per tier at 999,999,999. |
+| Max tier count | `type(uint16).max` (65,535) | `JB721TiersHookStore` | Maximum total number of tiers across all `recordAddTiers` calls for a single hook. |
+
+## Discount Percent
+
+Each tier has a `discountPercent` (uint8) that reduces its effective purchase price:
+
+- The discount is applied during `recordMint`: `price -= mulDiv(price, discountPercent, DISCOUNT_DENOMINATOR)`.
+- `DISCOUNT_DENOMINATOR` is 200, so `discountPercent = 100` means 50% off, `discountPercent = 200` means free.
+- Discount can be changed via `setDiscountPercentOf` / `setDiscountPercentsOf` (requires `SET_721_DISCOUNT_PERCENT` permission).
+- If `cannotIncreaseDiscountPercent` is set on the tier, the discount can only be decreased or kept the same -- increases are rejected by the store.
+- Cash out weight always uses the **original tier price**, not the discounted price. This prevents discount changes from retroactively altering the cash-out value of already-minted NFTs.
+
+## Voting Units
+
+Each tier has configurable voting power:
+
+- If `useVotingUnits` is `true` on the tier config, voting power per NFT is the custom `votingUnits` value (stored in `_tierVotingUnitsOf`).
+- If `useVotingUnits` is `false`, voting power per NFT defaults to the tier's `price`.
+- The `noNewTiersWithVotes` flag blocks adding new tiers with any voting power -- this means blocking tiers where `(useVotingUnits && votingUnits != 0)` OR `(!useVotingUnits && price != 0)`.
+- Total voting units for an address are computed by `votingUnitsOf(hook, account)`, which sums `balance * votingPower` across all tiers.
+
+## Reserve Minting
+
+- Reserves accumulate as NFTs are purchased: for every `reserveFrequency` non-reserve mints, one reserve NFT becomes available.
+- Pending count: `ceil(numberOfNonReserveMints / reserveFrequency) - numberOfReservesMintedFor`.
+- Reserves are minted to the tier's `reserveBeneficiary` (or the hook's `defaultReserveBeneficiaryOf` as fallback).
+- Reserve minting is permissionless (`mintPendingReservesFor`), but can be paused per-ruleset via `pauseMintPendingReserves` in `JB721TiersRulesetMetadata`.
+- Supply is protected: `recordMint` ensures remaining supply covers pending reserves after each purchase.
+- Tiers with `allowOwnerMint: true` cannot have a `reserveFrequency` -- the store rejects this combination.
+
+## Tier Splits
+
+- Each tier can route a percentage of its mint price to configured split recipients. The `splitPercent` field (out of `JBConstants.SPLITS_TOTAL_PERCENT` = 1,000,000,000) determines how much of the price is forwarded.
+- Split recipients are stored in `JBSplits` using group IDs computed as `uint256(uint160(hookAddress)) | (uint256(tierId) << 160)`.
+- Splits are registered via `JB721TiersHookLib._setSplitGroupsFor` when tiers with `splits` are added.
+- In `beforePayRecordedWith`, `calculateSplitAmounts` decodes tier IDs from payer metadata, computes `mulDiv(price, splitPercent, SPLITS_TOTAL_PERCENT)` per tier, and returns the total to be forwarded to the hook.
+- 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`.
+- Split recipients can be projects (via `terminal.pay` or `terminal.addToBalance`) or plain addresses (direct ETH transfer or `SafeERC20.safeTransfer`).
+
 ## Gotchas
 
 - `JB721TiersHook` is deployed as a **minimal clone** (not a full deployment). The constructor sets immutables (`RULESETS`, `STORE`, `DIRECTORY`, `METADATA_ID_TARGET`), and `initialize()` sets per-instance state. Calling `initialize()` twice reverts with `JB721TiersHook_AlreadyInitialized`.
+- **`JB721Hook` abstract base**: `JB721TiersHook` extends `JB721Hook`, which handles generic 721 hook lifecycle (terminal validation, burn loop, metadata decoding). `JB721TiersHook` overrides `cashOutWeightOf`, `totalCashOutWeight`, `_didBurn`, `_processPayment`, and `beforePayRecordedWith`. Errors like `JB721Hook_InvalidPay` and `JB721Hook_InvalidCashOut` are defined on the abstract class, not `JB721TiersHook`.
 - **Pricing context is bit-packed** into a single `uint256`: currency (bits 0-31), decimals (bits 32-39), prices contract address (bits 40-199). Read it via `pricingContext()`.
+- **Pricing decimals must be <= 18**: `initialize` reverts with `JB721TiersHook_InvalidPricingDecimals` otherwise.
 - **Token IDs encode tier ID**: `tokenId = tierId * 1_000_000_000 + mintNumber`. Use `STORE.tierIdOfToken(tokenId)` to extract the tier ID.
 - **Pay credits**: If a payer overpays (amount > total tier prices), the excess is stored as `payCreditsOf[beneficiary]` and can be applied to future mints. This only works when `preventOverspending` flag is `false`. Credits are only combined with payment when `payer == beneficiary`.
-- **Cash outs reject fungible tokens**: `beforeCashOutRecordedWith` reverts with `JB721Hook_UnexpectedTokenCashedOut` if `context.cashOutCount > 0`. NFT cash outs and fungible token cash outs are mutually exclusive.
+- **Cash outs reject fungible tokens**: `beforeCashOutRecordedWith` reverts with `JB721TiersHook_UnexpectedTokenCashedOut` if `context.cashOutCount > 0`. NFT cash outs and fungible token cash outs are mutually exclusive.
+- **Cash out weight uses original price**: `cashOutWeightOf` and `totalCashOutWeight` use the full tier `price`, not the discounted price. This prevents discount changes from altering the cash-out value of already-minted NFTs.
+- **Pending reserves inflate totalCashOutWeight**: `totalCashOutWeight` includes pending reserves in the denominator (`price * (minted + pendingReserves)`). This dilutes cash-out value before reserves are minted, preventing early cashers from extracting more than their fair share.
 - **Reserve minting is permissionless** but governed by ruleset metadata. Anyone can call `mintPendingReservesFor` as long as `mintPendingReservesPaused` is not set in the current ruleset's metadata.
+- **Reserve + owner-mint mutual exclusion**: Tiers with `allowOwnerMint: true` cannot have a `reserveFrequency`. The store rejects this combination during `recordAddTiers`.
 - `setMetadata` uses `address(this)` as the sentinel for "no change" on `tokenUriResolver` (not `address(0)`). Passing `address(0)` will clear the resolver.
 - `JBPayDataHookRulesetConfig` hardcodes `allowSetCustomToken: false` and `useDataHookForPay: true` when wiring rulesets through the project deployer.
 - The `_update` override in `JB721TiersHook` checks `tier.transfersPausable` and consults the current ruleset's metadata for `transfersPaused`. Transfers to `address(0)` (burns) are never blocked.
+- **IERC2981 declared but not implemented**: `supportsInterface` returns `true` for `IERC2981`, but no `royaltyInfo` function is implemented. Callers querying `royaltyInfo` will get a revert. This appears intentional -- the interface is declared for future extension or to signal capability to marketplaces that may override behavior.
+- **Tier splits**: Each tier can route a percentage of its mint price to configured split recipients. `splitPercent` is out of `JBConstants.SPLITS_TOTAL_PERCENT` (1,000,000,000). Split group IDs are `uint256(uint160(hookAddress)) | (uint256(tierId) << 160)`.
+- **Removing tiers does not update the sorted list**: `recordRemoveTierIds` only marks tiers in the bitmap. Call `cleanTiers()` afterward to remove them from the iteration sequence.
 - `JB721TiersHookStore` is a **shared singleton** -- all hook instances on the same chain use the same store, keyed by `address(hook)`.
 - The `ERC721` abstract uses `_initialize(name, symbol)` instead of a constructor, making it clone-compatible. The standard `_owners` mapping is `internal` (not `private`).
+- **`hasMintPermissionFor` always returns `false`**: The hook never grants mint permission to any address. This is part of the `IJBRulesetDataHook` interface.
+- **Max tier count is 65,535** (`type(uint16).max`). Adding tiers beyond this limit reverts.
+- **Max initial supply per tier is 999,999,999** (`_ONE_BILLION - 1`). Exceeding this would cause token ID overflow into the next tier's ID space.
+- **`noNewTiersWithVotes` blocks all voting power**: It rejects tiers where voting units would be non-zero, whether from custom `votingUnits` or from a non-zero `price` (when `useVotingUnits` is false).
+- **`firstOwnerOf` is lazy**: The first owner is only stored when the token is first transferred away from its original holder. Before any transfer, `firstOwnerOf` returns the current owner.
 
 ## Example Integration
 
@@ -107,7 +197,9 @@ tiers[0] = JB721TierConfig({
     transfersPausable: false,
     useVotingUnits: false,
     cannotBeRemoved: false,
-    cannotIncreaseDiscountPercent: false
+    cannotIncreaseDiscountPercent: false,
+    splitPercent: 0,
+    splits: new JBSplit[](0)
 });
 
 // Deploy a project with the 721 hook attached.

package/package.json

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

package/src/JB721TiersHook.sol

@@ -1,31 +1,23 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.26;
 
-import {IJBCashOutHook} from "@bananapus/core-v6/src/interfaces/IJBCashOutHook.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
-import {IJBPayHook} from "@bananapus/core-v6/src/interfaces/IJBPayHook.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
 import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDataHook.sol";
 import {IJBRulesets} from "@bananapus/core-v6/src/interfaces/IJBRulesets.sol";
-import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
-import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
 import {JBRulesetMetadataResolver} from "@bananapus/core-v6/src/libraries/JBRulesetMetadataResolver.sol";
-import {JBAfterCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBAfterCashOutRecordedContext.sol";
 import {JBAfterPayRecordedContext} from "@bananapus/core-v6/src/structs/JBAfterPayRecordedContext.sol";
-import {JBBeforeCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforeCashOutRecordedContext.sol";
 import {JBBeforePayRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforePayRecordedContext.sol";
-import {JBCashOutHookSpecification} from "@bananapus/core-v6/src/structs/JBCashOutHookSpecification.sol";
 import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
 import {JBOwnable} from "@bananapus/ownable-v6/src/JBOwnable.sol";
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
-import {IERC2981} from "@openzeppelin/contracts/interfaces/IERC2981.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
-import {ERC721} from "./abstract/ERC721.sol";
+import {JB721Hook} from "./abstract/JB721Hook.sol";
 import {IJB721TiersHook} from "./interfaces/IJB721TiersHook.sol";
 import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "./interfaces/IJB721TokenUriResolver.sol";
@@ -43,33 +35,23 @@ import {JB721TiersMintReservesConfig} from "./structs/JB721TiersMintReservesConf
 /// the project is paid, the hook may mint NFTs to the payer, depending on the hook's setup, the amount paid, and
 /// information specified by the payer. The project's owner can enable NFT cash outs through this hook, allowing
 /// holders to burn their NFTs to reclaim funds from the project (in proportion to the NFT's price).
-contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
+contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
     error JB721TiersHook_AlreadyInitialized(uint256 projectId);
     error JB721TiersHook_CurrencyMismatch(uint256 paymentCurrency, uint256 tierCurrency);
-    error JB721TiersHook_InvalidCashOut();
-    error JB721TiersHook_InvalidPay();
     error JB721TiersHook_InvalidPricingDecimals(uint256 decimals);
     error JB721TiersHook_MintReserveNftsPaused();
     error JB721TiersHook_NoProjectId();
     error JB721TiersHook_Overspending(uint256 leftoverAmount);
     error JB721TiersHook_TierTransfersPaused();
-    error JB721TiersHook_UnauthorizedToken(uint256 tokenId, address holder);
-    error JB721TiersHook_UnexpectedTokenCashedOut();
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
 
-    /// @notice The directory of terminals and controllers for projects.
-    IJBDirectory public immutable override DIRECTORY;
-
-    /// @notice The ID used when parsing metadata.
-    address public immutable override METADATA_ID_TARGET;
-
     /// @notice The contract storing and managing project rulesets.
     IJBRulesets public immutable override RULESETS;
 
@@ -80,9 +62,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
     // ---------------------- public stored properties ------------------- //
     //*********************************************************************//
 
-    /// @notice The ID of the project that this contract is associated with.
-    uint256 public override PROJECT_ID;
-
     /// @notice The base URI for the NFT `tokenUris`.
     string public override baseURI;
 
@@ -127,10 +106,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         address trustedForwarder
     )
         JBOwnable(permissions, directory.PROJECTS(), msg.sender, uint88(0))
+        JB721Hook(directory)
         ERC2771Context(trustedForwarder)
     {
-        DIRECTORY = directory;
-        METADATA_ID_TARGET = address(this);
         RULESETS = rulesets;
         STORE = store;
     }
@@ -139,61 +117,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice The data calculated before a cash out is recorded in the terminal store. This data is provided to the
-    /// terminal's `cashOutTokensOf(...)` transaction.
-    /// @dev Sets this contract as the cash out hook. Part of `IJBRulesetDataHook`.
-    /// @dev This function is used for NFT cash outs, and will only be called if the project's ruleset has
-    /// `useDataHookForCashOut` set to `true`.
-    /// @param context The cash out context passed to this contract by the `cashOutTokensOf(...)` function.
-    /// @return cashOutTaxRate The cash out tax rate influencing the reclaim amount.
-    /// @return cashOutCount The amount of tokens that should be considered cashed out.
-    /// @return totalSupply The total amount of tokens that are considered to be existing.
-    /// @return hookSpecifications The amount and data to send to cash out hooks (this contract) instead of returning to
-    /// the beneficiary.
-    function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
-        public
-        view
-        virtual
-        override
-        returns (
-            uint256 cashOutTaxRate,
-            uint256 cashOutCount,
-            uint256 totalSupply,
-            JBCashOutHookSpecification[] memory hookSpecifications
-        )
-    {
-        // Make sure (fungible) project tokens aren't also being cashed out.
-        if (context.cashOutCount > 0) revert JB721TiersHook_UnexpectedTokenCashedOut();
-
-        // Fetch the cash out hook metadata using the corresponding metadata ID.
-        (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
-            id: JBMetadataResolver.getId({purpose: "cashOut", target: METADATA_ID_TARGET}), metadata: context.metadata
-        });
-
-        // Use this contract as the only cash out hook.
-        hookSpecifications = new JBCashOutHookSpecification[](1);
-        hookSpecifications[0] = JBCashOutHookSpecification({hook: this, amount: 0, metadata: bytes("")});
-
-        uint256[] memory decodedTokenIds;
-
-        // Decode the metadata.
-        if (metadataExists) decodedTokenIds = abi.decode(metadata, (uint256[]));
-
-        // Use the cash out weight of the provided 721s.
-        cashOutCount = STORE.cashOutWeightOf({hook: address(this), tokenIds: decodedTokenIds});
-
-        // Use the total cash out weight of the 721s.
-        totalSupply = STORE.totalCashOutWeight(address(this));
-
-        // Use the cash out tax rate from the context.
-        cashOutTaxRate = context.cashOutTaxRate;
-    }
-
-    /// @notice Required by the IJBRulesetDataHook interfaces. Return false to not leak any permissions.
-    function hasMintPermissionFor(uint256, JBRuleset memory, address) external pure returns (bool) {
-        return false;
-    }
-
     /// @notice The first owner of an NFT.
     /// @dev This is generally the address which paid for the NFT.
     /// @param tokenId The token ID of the NFT to get the first owner of.
@@ -236,18 +159,16 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         return STORE.balanceOf({hook: address(this), owner: owner});
     }
 
-    /// @notice The data calculated before a payment is recorded in the terminal store. This data is provided to the
-    /// terminal's `pay(...)` transaction.
-    /// @dev Sets this contract as the pay hook. Part of `IJBRulesetDataHook`.
-    /// @param context The payment context passed to this contract by the `pay(...)` function.
-    /// @return weight The new `weight` to use, overriding the ruleset's `weight`.
-    /// @return hookSpecifications The amount and data to send to pay hooks (this contract) instead of adding to the
-    /// terminal's balance.
+    /// @notice The data calculated before a payment is recorded in the terminal store.
+    /// @dev Overrides the base to calculate the split amount to forward based on tier split percentages.
+    /// @param context The payment context.
+    /// @return weight The weight to use for token minting (unchanged from ruleset weight).
+    /// @return hookSpecifications The hook specifications, with the split amount to forward.
     function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
         public
         view
         virtual
-        override
+        override(JB721Hook, IJBRulesetDataHook)
         returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
     {
         weight = context.weight;
@@ -260,13 +181,20 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         hookSpecifications[0] = JBPayHookSpecification({hook: this, amount: totalSplitAmount, metadata: splitMetadata});
     }
 
+    /// @notice The combined cash out weight of the NFTs with the specified token IDs.
+    /// @dev An NFT's cash out weight is its price.
+    /// @dev To get their relative cash out weight, divide the result by the `totalCashOutWeight(...)`.
+    /// @param tokenIds The token IDs of the NFTs to get the cumulative cash out weight of.
+    /// @return weight The cash out weight of the tokenIds.
+    function cashOutWeightOf(uint256[] memory tokenIds) public view virtual override returns (uint256) {
+        return STORE.cashOutWeightOf({hook: address(this), tokenIds: tokenIds});
+    }
+
     /// @notice Indicates if this contract adheres to the specified interface.
     /// @dev See {IERC165-supportsInterface}.
     /// @param interfaceId The ID of the interface to check for adherence to.
-    function supportsInterface(bytes4 interfaceId) public view virtual override(ERC721, IERC165) returns (bool) {
-        return interfaceId == type(IJB721TiersHook).interfaceId || interfaceId == type(IJBRulesetDataHook).interfaceId
-            || interfaceId == type(IJBPayHook).interfaceId || interfaceId == type(IJBCashOutHook).interfaceId
-            || interfaceId == type(IERC2981).interfaceId || super.supportsInterface(interfaceId);
+    function supportsInterface(bytes4 interfaceId) public view override(IERC165, JB721Hook) returns (bool) {
+        return interfaceId == type(IJB721TiersHook).interfaceId || JB721Hook.supportsInterface(interfaceId);
     }
 
     /// @notice Initializes a cloned copy of the original hook contract.
@@ -298,9 +226,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         // Make sure a projectId is provided.
         if (projectId == 0) revert JB721TiersHook_NoProjectId();
 
-        // Initialize ERC721 and set the project ID.
-        ERC721._initialize({name_: name, symbol_: symbol});
-        PROJECT_ID = projectId;
+        // Initialize the superclass.
+        JB721Hook._initialize({projectId: projectId, name: name, symbol: symbol});
 
         // Validate pricing decimals are within a reasonable range.
         if (tiersConfig.decimals > 18) revert JB721TiersHook_InvalidPricingDecimals(tiersConfig.decimals);
@@ -352,76 +279,17 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         return JB721TiersHookLib.resolveTokenURI(STORE, address(this), baseURI, tokenId);
     }
 
+    /// @notice The combined cash out weight of all outstanding NFTs.
+    /// @dev An NFT's cash out weight is its price.
+    /// @return weight The total cash out weight.
+    function totalCashOutWeight() public view virtual override returns (uint256) {
+        return STORE.totalCashOutWeight(address(this));
+    }
+
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Mints one or more NFTs to the `context.beneficiary` upon payment if conditions are met. Part of
-    /// `IJBPayHook`.
-    /// @dev Reverts if the calling contract is not one of the project's terminals.
-    /// @param context The payment context passed in by the terminal.
-    // slither-disable-next-line locked-ether
-    function afterPayRecordedWith(JBAfterPayRecordedContext calldata context) external payable virtual override {
-        uint256 projectId = PROJECT_ID;
-
-        // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
-        // interaction with the correct project.
-        if (!DIRECTORY.isTerminalOf(projectId, IJBTerminal(msg.sender)) || context.projectId != projectId) {
-            revert JB721TiersHook_InvalidPay();
-        }
-
-        // Process the payment.
-        _processPayment(context);
-    }
-
-    /// @notice Burns the specified NFTs upon token holder cash out, reclaiming funds from the project's balance for
-    /// `context.beneficiary`. Part of `IJBCashOutHook`.
-    /// @dev Reverts if the calling contract is not one of the project's terminals.
-    /// @param context The cash out context passed in by the terminal.
-    // slither-disable-next-line locked-ether
-    function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context)
-        external
-        payable
-        virtual
-        override
-    {
-        // Keep a reference to the project ID.
-        uint256 projectId = PROJECT_ID;
-
-        // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
-        // interaction with the correct project.
-        if (
-            msg.value != 0 || !DIRECTORY.isTerminalOf({projectId: projectId, terminal: IJBTerminal(msg.sender)})
-                || context.projectId != projectId
-        ) revert JB721TiersHook_InvalidCashOut();
-
-        // Fetch the cash out hook metadata using the corresponding metadata ID.
-        (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
-            id: JBMetadataResolver.getId({purpose: "cashOut", target: METADATA_ID_TARGET}),
-            metadata: context.cashOutMetadata
-        });
-
-        uint256[] memory decodedTokenIds;
-
-        // Decode the metadata.
-        if (metadataExists) decodedTokenIds = abi.decode(metadata, (uint256[]));
-
-        // Iterate through the NFTs, burning them if the owner is correct.
-        for (uint256 i; i < decodedTokenIds.length; i++) {
-            // Set the current NFT's token ID.
-            uint256 tokenId = decodedTokenIds[i];
-
-            // Make sure the token's owner is correct.
-            if (_ownerOf(tokenId) != context.holder) revert JB721TiersHook_UnauthorizedToken(tokenId, context.holder);
-
-            // Burn the token.
-            _burn(tokenId);
-        }
-
-        // Add to burned counter.
-        STORE.recordBurn(decodedTokenIds);
-    }
-
     /// @notice Add or delete tiers.
     /// @dev Only the contract's owner or an operator with the `ADJUST_TIERS` permission from the owner can adjust the
     /// tiers.
@@ -638,6 +506,13 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
     // ------------------------ internal functions ----------------------- //
     //*********************************************************************//
 
+    /// @notice A function which gets called after NFTs have been cashed out and recorded by the terminal.
+    /// @param tokenIds The token IDs of the NFTs that were burned.
+    function _didBurn(uint256[] memory tokenIds) internal virtual override {
+        // Add to burned counter.
+        STORE.recordBurn(tokenIds);
+    }
+
     /// @notice Mints one NFT from each of the specified tiers for the beneficiary.
     /// @dev The same tier can be specified more than once.
     /// @param amount The amount to base the mints on. The total price of the NFTs being minted cannot be larger than
@@ -687,7 +562,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
     /// the payer's existing credits are NOT applied to the mint. Only the beneficiary's credits are combined with
     /// the incoming payment value. Leftover funds after minting are stored as credits for the beneficiary.
     /// @param context Payment context provided by the terminal after it has recorded the payment in the terminal store.
-    function _processPayment(JBAfterPayRecordedContext calldata context) internal virtual {
+    function _processPayment(JBAfterPayRecordedContext calldata context) internal virtual override {
         // Normalize the payment value based on the pricing context.
         uint256 value;
         {
@@ -711,9 +586,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         // If the payer is the beneficiary, combine their NFT credits with the amount paid.
         uint256 unusedPayCredits;
         if (context.payer == context.beneficiary) {
-            unchecked {
-                leftoverAmount += payCredits;
-            }
+            leftoverAmount += payCredits;
         } else {
             // Otherwise, the payer's NFT credits won't be used, and we keep track of the unused credits.
             unusedPayCredits = payCredits;
@@ -755,28 +628,26 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, ERC721, IJB721TiersHook {
         if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
 
         // Update NFT credits if they changed.
-        unchecked {
-            uint256 newPayCredits = leftoverAmount + unusedPayCredits;
-
-            if (newPayCredits != payCredits) {
-                if (newPayCredits > payCredits) {
-                    emit AddPayCredits({
-                        amount: newPayCredits - payCredits,
-                        newTotalCredits: newPayCredits,
-                        account: context.beneficiary,
-                        caller: _msgSender()
-                    });
-                } else {
-                    emit UsePayCredits({
-                        amount: payCredits - newPayCredits,
-                        newTotalCredits: newPayCredits,
-                        account: context.beneficiary,
-                        caller: _msgSender()
-                    });
-                }
-
-                payCreditsOf[context.beneficiary] = newPayCredits;
+        uint256 newPayCredits = leftoverAmount + unusedPayCredits;
+
+        if (newPayCredits != payCredits) {
+            if (newPayCredits > payCredits) {
+                emit AddPayCredits({
+                    amount: newPayCredits - payCredits,
+                    newTotalCredits: newPayCredits,
+                    account: context.beneficiary,
+                    caller: _msgSender()
+                });
+            } else {
+                emit UsePayCredits({
+                    amount: payCredits - newPayCredits,
+                    newTotalCredits: newPayCredits,
+                    account: context.beneficiary,
+                    caller: _msgSender()
+                });
             }
+
+            payCreditsOf[context.beneficiary] = newPayCredits;
         }
 
         // Distribute any forwarded funds to tier split groups.

package/src/abstract/JB721Hook.sol

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {IJBCashOutHook} from "@bananapus/core-v6/src/interfaces/IJBCashOutHook.sol";
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBPayHook} from "@bananapus/core-v6/src/interfaces/IJBPayHook.sol";
+import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDataHook.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {JBAfterCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBAfterCashOutRecordedContext.sol";
+import {JBAfterPayRecordedContext} from "@bananapus/core-v6/src/structs/JBAfterPayRecordedContext.sol";
+import {JBBeforeCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforeCashOutRecordedContext.sol";
+import {JBBeforePayRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforePayRecordedContext.sol";
+import {JBCashOutHookSpecification} from "@bananapus/core-v6/src/structs/JBCashOutHookSpecification.sol";
+import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+import {IERC2981} from "@openzeppelin/contracts/interfaces/IERC2981.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+import {ERC721} from "./ERC721.sol";
+import {IJB721Hook} from "../interfaces/IJB721Hook.sol";
+
+/// @title JB721Hook
+/// @notice When a project which uses this hook is paid, this hook may mint NFTs to the payer, depending on this hook's
+/// setup, the amount paid, and information specified by the payer. The project's owner can enable NFT cash outs
+/// through this hook, allowing the NFT holders to burn their NFTs to reclaim funds from the project (in proportion to
+/// the NFT's price).
+abstract contract JB721Hook is ERC721, IJB721Hook {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JB721Hook_InvalidCashOut();
+    error JB721Hook_InvalidPay();
+    error JB721Hook_UnauthorizedToken(uint256 tokenId, address holder);
+    error JB721Hook_UnexpectedTokenCashedOut();
+
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice The directory of terminals and controllers for projects.
+    IJBDirectory public immutable override DIRECTORY;
+
+    /// @notice The ID used when parsing metadata.
+    address public immutable override METADATA_ID_TARGET;
+
+    //*********************************************************************//
+    // -------------------- public stored properties --------------------- //
+    //*********************************************************************//
+
+    /// @notice The ID of the project that this contract is associated with.
+    uint256 public override PROJECT_ID;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @param directory A directory of terminals and controllers for projects.
+    constructor(IJBDirectory directory) {
+        DIRECTORY = directory;
+        // Store the address of the original hook deploy. Clones will each use the address of the instance they're based
+        // on.
+        METADATA_ID_TARGET = address(this);
+    }
+
+    //*********************************************************************//
+    // ------------------------- external views -------------------------- //
+    //*********************************************************************//
+
+    /// @notice The data calculated before a payment is recorded in the terminal store. This data is provided to the
+    /// terminal's `pay(...)` transaction.
+    /// @dev Sets this contract as the pay hook. Part of `IJBRulesetDataHook`.
+    /// @param context The payment context passed to this contract by the `pay(...)` function.
+    /// @return weight The new `weight` to use, overriding the ruleset's `weight`.
+    /// @return hookSpecifications The amount and data to send to pay hooks (this contract) instead of adding to the
+    /// terminal's balance.
+    function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
+        public
+        view
+        virtual
+        override
+        returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
+    {
+        // Forward the received weight and use this contract as the only pay hook.
+        weight = context.weight;
+        hookSpecifications = new JBPayHookSpecification[](1);
+        hookSpecifications[0] = JBPayHookSpecification({hook: this, amount: 0, metadata: bytes("")});
+    }
+
+    /// @notice The data calculated before a cash out is recorded in the terminal store. This data is provided to the
+    /// terminal's `cashOutTokensOf(...)` transaction.
+    /// @dev Sets this contract as the cash out hook. Part of `IJBRulesetDataHook`.
+    /// @dev This function is used for NFT cash outs, and will only be called if the project's ruleset has
+    /// `useDataHookForCashOut` set to `true`.
+    /// @param context The cash out context passed to this contract by the `cashOutTokensOf(...)` function.
+    /// @return cashOutTaxRate The cash out tax rate influencing the reclaim amount.
+    /// @return cashOutCount The amount of tokens that should be considered cashed out.
+    /// @return totalSupply The total amount of tokens that are considered to be existing.
+    /// @return hookSpecifications The amount and data to send to cash out hooks (this contract) instead of returning to
+    /// the beneficiary.
+    function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
+        public
+        view
+        virtual
+        override
+        returns (
+            uint256 cashOutTaxRate,
+            uint256 cashOutCount,
+            uint256 totalSupply,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        )
+    {
+        // Make sure (fungible) project tokens aren't also being cashed out.
+        if (context.cashOutCount > 0) revert JB721Hook_UnexpectedTokenCashedOut();
+
+        // Fetch the cash out hook metadata using the corresponding metadata ID.
+        (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
+            id: JBMetadataResolver.getId({purpose: "cashOut", target: METADATA_ID_TARGET}), metadata: context.metadata
+        });
+
+        // Use this contract as the only cash out hook.
+        hookSpecifications = new JBCashOutHookSpecification[](1);
+        hookSpecifications[0] = JBCashOutHookSpecification({hook: this, amount: 0, metadata: bytes("")});
+
+        uint256[] memory decodedTokenIds;
+
+        // Decode the metadata.
+        if (metadataExists) decodedTokenIds = abi.decode(metadata, (uint256[]));
+
+        // Use the cash out weight of the provided 721s.
+        cashOutCount = cashOutWeightOf(decodedTokenIds);
+
+        // Use the total cash out weight of the 721s.
+        totalSupply = totalCashOutWeight();
+
+        // Use the cash out tax rate from the context.
+        cashOutTaxRate = context.cashOutTaxRate;
+    }
+
+    /// @notice Required by the IJBRulesetDataHook interfaces. Return false to not leak any permissions.
+    function hasMintPermissionFor(uint256, JBRuleset memory, address) external pure returns (bool) {
+        return false;
+    }
+
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
+    /// @notice Returns the cumulative cash out weight of the specified token IDs relative to the
+    /// `totalCashOutWeight`.
+    /// @param tokenIds The NFT token IDs to calculate the cumulative cash out weight of.
+    /// @return The cumulative cash out weight of the specified token IDs.
+    function cashOutWeightOf(uint256[] memory tokenIds) public view virtual returns (uint256) {
+        tokenIds; // Prevents unused var compiler and natspec complaints.
+        return 0;
+    }
+
+    /// @notice Indicates if this contract adheres to the specified interface.
+    /// @dev See {IERC165-supportsInterface}.
+    /// @param interfaceId The ID of the interface to check for adherence to.
+    function supportsInterface(bytes4 interfaceId) public view virtual override(ERC721, IERC165) returns (bool) {
+        return interfaceId == type(IJB721Hook).interfaceId || interfaceId == type(IJBRulesetDataHook).interfaceId
+            || interfaceId == type(IJBPayHook).interfaceId || interfaceId == type(IJBCashOutHook).interfaceId
+            || interfaceId == type(IERC2981).interfaceId || super.supportsInterface(interfaceId);
+    }
+
+    /// @notice Calculates the cumulative cash out weight of all NFT token IDs.
+    /// @return The total cumulative cash out weight of all NFT token IDs.
+    function totalCashOutWeight() public view virtual returns (uint256) {
+        return 0;
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Mints one or more NFTs to the `context.beneficiary` upon payment if conditions are met. Part of
+    /// `IJBPayHook`.
+    /// @dev Reverts if the calling contract is not one of the project's terminals.
+    /// @param context The payment context passed in by the terminal.
+    // slither-disable-next-line locked-ether
+    function afterPayRecordedWith(JBAfterPayRecordedContext calldata context) external payable virtual override {
+        uint256 projectId = PROJECT_ID;
+
+        // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
+        // interaction with the correct project.
+        if (!DIRECTORY.isTerminalOf(projectId, IJBTerminal(msg.sender)) || context.projectId != projectId) {
+            revert JB721Hook_InvalidPay();
+        }
+
+        // Process the payment.
+        _processPayment(context);
+    }
+
+    /// @notice Burns the specified NFTs upon token holder cash out, reclaiming funds from the project's balance for
+    /// `context.beneficiary`. Part of `IJBCashOutHook`.
+    /// @dev Reverts if the calling contract is not one of the project's terminals.
+    /// @param context The cash out context passed in by the terminal.
+    // slither-disable-next-line locked-ether
+    function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context)
+        external
+        payable
+        virtual
+        override
+    {
+        // Keep a reference to the project ID.
+        uint256 projectId = PROJECT_ID;
+
+        // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
+        // interaction with the correct project.
+        if (
+            msg.value != 0 || !DIRECTORY.isTerminalOf({projectId: projectId, terminal: IJBTerminal(msg.sender)})
+                || context.projectId != projectId
+        ) revert JB721Hook_InvalidCashOut();
+
+        // Fetch the cash out hook metadata using the corresponding metadata ID.
+        (bool metadataExists, bytes memory metadata) = JBMetadataResolver.getDataFor({
+            id: JBMetadataResolver.getId({purpose: "cashOut", target: METADATA_ID_TARGET}),
+            metadata: context.cashOutMetadata
+        });
+
+        uint256[] memory decodedTokenIds;
+
+        // Decode the metadata.
+        if (metadataExists) decodedTokenIds = abi.decode(metadata, (uint256[]));
+
+        // Iterate through the NFTs, burning them if the owner is correct.
+        for (uint256 i; i < decodedTokenIds.length; i++) {
+            // Set the current NFT's token ID.
+            uint256 tokenId = decodedTokenIds[i];
+
+            // Make sure the token's owner is correct.
+            if (_ownerOf(tokenId) != context.holder) revert JB721Hook_UnauthorizedToken(tokenId, context.holder);
+
+            // Burn the token.
+            _burn(tokenId);
+        }
+
+        // Call the hook.
+        _didBurn(decodedTokenIds);
+    }
+
+    //*********************************************************************//
+    // ---------------------- internal transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Initializes the contract by associating it with a project and adding ERC721 details.
+    /// @param projectId The ID of the project that this contract is associated with.
+    /// @param name The name of the NFT collection.
+    /// @param symbol The symbol representing the NFT collection.
+    function _initialize(uint256 projectId, string memory name, string memory symbol) internal {
+        ERC721._initialize({name_: name, symbol_: symbol});
+        PROJECT_ID = projectId;
+    }
+
+    /// @notice Executes after NFTs have been burned via cash out.
+    /// @param tokenIds The token IDs of the NFTs that were burned.
+    function _didBurn(uint256[] memory tokenIds) internal virtual;
+
+    /// @notice Process a received payment.
+    /// @param context The payment context passed in by the terminal.
+    function _processPayment(JBAfterPayRecordedContext calldata context) internal virtual;
+}

package/src/interfaces/IJB721Hook.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJBCashOutHook} from "@bananapus/core-v6/src/interfaces/IJBCashOutHook.sol";
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBPayHook} from "@bananapus/core-v6/src/interfaces/IJBPayHook.sol";
+import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDataHook.sol";
+
+interface IJB721Hook is IJBRulesetDataHook, IJBPayHook, IJBCashOutHook {
+    /// @notice The directory of terminals and controllers for projects.
+    /// @return The directory contract.
+    function DIRECTORY() external view returns (IJBDirectory);
+
+    /// @notice The ID used when parsing metadata.
+    /// @return The address of the metadata ID target.
+    function METADATA_ID_TARGET() external view returns (address);
+
+    /// @notice The ID of the project that this contract is associated with.
+    /// @return The project ID.
+    function PROJECT_ID() external view returns (uint256);
+}

package/src/interfaces/IJB721TiersHook.sol

@@ -1,13 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import {IJBCashOutHook} from "@bananapus/core-v6/src/interfaces/IJBCashOutHook.sol";
-import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
-import {IJBPayHook} from "@bananapus/core-v6/src/interfaces/IJBPayHook.sol";
 import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
-import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDataHook.sol";
 import {IJBRulesets} from "@bananapus/core-v6/src/interfaces/IJBRulesets.sol";
 
+import {IJB721Hook} from "./IJB721Hook.sol";
 import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "./IJB721TokenUriResolver.sol";
 import {JB721InitTiersConfig} from "../structs/JB721InitTiersConfig.sol";
@@ -16,7 +13,7 @@ import {JB721TiersHookFlags} from "../structs/JB721TiersHookFlags.sol";
 import {JB721TiersMintReservesConfig} from "../structs/JB721TiersMintReservesConfig.sol";
 import {JB721TiersSetDiscountPercentConfig} from "../structs/JB721TiersSetDiscountPercentConfig.sol";
 
-interface IJB721TiersHook is IJBRulesetDataHook, IJBPayHook, IJBCashOutHook {
+interface IJB721TiersHook is IJB721Hook {
     event AddPayCredits(
         uint256 indexed amount, uint256 indexed newTotalCredits, address indexed account, address caller
     );
@@ -39,18 +36,6 @@ interface IJB721TiersHook is IJBRulesetDataHook, IJBPayHook, IJBCashOutHook {
         uint256 indexed amount, uint256 indexed newTotalCredits, address indexed account, address caller
     );
 
-    /// @notice The directory of terminals and controllers for projects.
-    /// @return The directory contract.
-    function DIRECTORY() external view returns (IJBDirectory);
-
-    /// @notice The ID used when parsing metadata.
-    /// @return The address of the metadata ID target.
-    function METADATA_ID_TARGET() external view returns (address);
-
-    /// @notice The ID of the project that this contract is associated with.
-    /// @return The project ID.
-    function PROJECT_ID() external view returns (uint256);
-
     /// @notice The contract storing and managing project rulesets.
     /// @return The rulesets contract.
     function RULESETS() external view returns (IJBRulesets);

package/test/unit/pay_Unit.t.sol

@@ -965,7 +965,7 @@ contract Test_afterPayRecorded_Unit is UnitTestSetup {
         vm.prank(terminal);
 
         // Expect a revert for the caller not being a terminal of the project.
-        vm.expectRevert(abi.encodeWithSelector(JB721TiersHook.JB721TiersHook_InvalidPay.selector));
+        vm.expectRevert(abi.encodeWithSelector(JB721Hook.JB721Hook_InvalidPay.selector));
 
         hook.afterPayRecordedWith(
             JBAfterPayRecordedContext({
@@ -1530,4 +1530,88 @@ contract Test_afterPayRecorded_Unit is UnitTestSetup {
         // Check: has the holder's balance returned to 0?
         assertEq(hook.balanceOf(holder), 0);
     }
+
+    function test_afterPayRecorded_revertOnCreditOverflow_samePayerBeneficiary() public {
+        // Mock the directory call.
+        mockAndExpect(
+            address(mockJBDirectory),
+            abi.encodeWithSelector(IJBDirectory.isTerminalOf.selector, projectId, mockTerminalAddress),
+            abi.encode(true)
+        );
+
+        // Set the beneficiary's pay credits to max uint256.
+        stdstore.target(address(hook)).sig("payCreditsOf(address)").with_key(beneficiary)
+            .checked_write(type(uint256).max);
+
+        // Pay 1 wei where payer == beneficiary. No metadata → no NFT mints.
+        // `leftoverAmount += payCredits` overflows: 1 + type(uint256).max.
+        vm.expectRevert(stdError.arithmeticError);
+        vm.prank(mockTerminalAddress);
+        hook.afterPayRecordedWith(
+            JBAfterPayRecordedContext({
+                payer: beneficiary,
+                projectId: projectId,
+                rulesetId: 0,
+                amount: JBTokenAmount({
+                    token: JBConstants.NATIVE_TOKEN,
+                    value: 1,
+                    decimals: 18,
+                    currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+                }),
+                forwardedAmount: JBTokenAmount({
+                    token: JBConstants.NATIVE_TOKEN,
+                    value: 0,
+                    decimals: 18,
+                    currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+                }),
+                weight: 10 ** 18,
+                newlyIssuedTokenCount: 0,
+                beneficiary: beneficiary,
+                hookMetadata: new bytes(0),
+                payerMetadata: new bytes(0)
+            })
+        );
+    }
+
+    function test_afterPayRecorded_revertOnCreditOverflow_differentPayerBeneficiary() public {
+        // Mock the directory call.
+        mockAndExpect(
+            address(mockJBDirectory),
+            abi.encodeWithSelector(IJBDirectory.isTerminalOf.selector, projectId, mockTerminalAddress),
+            abi.encode(true)
+        );
+
+        // Set the beneficiary's pay credits to max uint256.
+        stdstore.target(address(hook)).sig("payCreditsOf(address)").with_key(beneficiary)
+            .checked_write(type(uint256).max);
+
+        // Pay 1 wei where payer != beneficiary. No metadata → no NFT mints, overspending allowed.
+        // leftoverAmount=1, unusedPayCredits=type(uint256).max → overflow in `leftoverAmount + unusedPayCredits`.
+        vm.expectRevert(stdError.arithmeticError);
+        vm.prank(mockTerminalAddress);
+        hook.afterPayRecordedWith(
+            JBAfterPayRecordedContext({
+                payer: address(0xdead),
+                projectId: projectId,
+                rulesetId: 0,
+                amount: JBTokenAmount({
+                    token: JBConstants.NATIVE_TOKEN,
+                    value: 1,
+                    decimals: 18,
+                    currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+                }),
+                forwardedAmount: JBTokenAmount({
+                    token: JBConstants.NATIVE_TOKEN,
+                    value: 0,
+                    decimals: 18,
+                    currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+                }),
+                weight: 10 ** 18,
+                newlyIssuedTokenCount: 0,
+                beneficiary: beneficiary,
+                hookMetadata: new bytes(0),
+                payerMetadata: new bytes(0)
+            })
+        );
+    }
 }

package/test/unit/redeem_Unit.t.sol

@@ -206,7 +206,7 @@ contract Test_cashOut_Unit is UnitTestSetup {
         vm.assume(tokenCount > 0);
 
         // Expect a revert on account of the token count being non-zero while the total supply is zero.
-        vm.expectRevert(abi.encodeWithSelector(JB721TiersHook.JB721TiersHook_UnexpectedTokenCashedOut.selector));
+        vm.expectRevert(abi.encodeWithSelector(JB721Hook.JB721Hook_UnexpectedTokenCashedOut.selector));
 
         hook.beforeCashOutRecordedWith(
             JBBeforeCashOutRecordedContext({
@@ -347,7 +347,7 @@ contract Test_cashOut_Unit is UnitTestSetup {
         );
 
         // Expect to revert on account of the project ID being incorrect.
-        vm.expectRevert(abi.encodeWithSelector(JB721TiersHook.JB721TiersHook_InvalidCashOut.selector));
+        vm.expectRevert(abi.encodeWithSelector(JB721Hook.JB721Hook_InvalidCashOut.selector));
 
         vm.prank(mockTerminalAddress);
         hook.afterCashOutRecordedWith(
@@ -382,7 +382,7 @@ contract Test_cashOut_Unit is UnitTestSetup {
         );
 
         // Expect to revert on account of the caller not being a terminal of the project.
-        vm.expectRevert(abi.encodeWithSelector(JB721TiersHook.JB721TiersHook_InvalidCashOut.selector));
+        vm.expectRevert(abi.encodeWithSelector(JB721Hook.JB721Hook_InvalidCashOut.selector));
 
         vm.prank(mockTerminalAddress);
         hook.afterCashOutRecordedWith(
@@ -434,9 +434,7 @@ contract Test_cashOut_Unit is UnitTestSetup {
             abi.encode(true)
         );
 
-        vm.expectRevert(
-            abi.encodeWithSelector(JB721TiersHook.JB721TiersHook_UnauthorizedToken.selector, tokenId, wrongHolder)
-        );
+        vm.expectRevert(abi.encodeWithSelector(JB721Hook.JB721Hook_UnauthorizedToken.selector, tokenId, wrongHolder));
 
         vm.prank(mockTerminalAddress);
         hook.afterCashOutRecordedWith(