@bananapus/721-hook-v6 0.0.29 → 0.0.31

package/ADMINISTRATION.md

@@ -2,6 +2,33 @@
 
 Admin privileges and their scope in nana-721-hook-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Per-project NFT administration for tier configuration, metadata, discounts, owner mints, and hook deployment. |
+| Operators | The resolved hook owner via `JBOwnable`, project-scoped delegates through `JBPermissions`, terminals, and the deployer/store contracts. |
+| Highest-risk actions | Adjusting tiers after launch, changing metadata or discounts that affect sale behavior, and deploying or initializing the wrong hook clone. |
+| Recovery posture | Clone-level mistakes are usually fixed by deploying a new hook and moving future rulesets to it; immutable constructor references cannot be changed in place. |
+
+## Routine Operations
+
+- Grant only the specific 721 permission IDs a project operator needs instead of handing out broad owner-equivalent access.
+- Use tier adjustments, metadata updates, owner mints, and discount changes with awareness of the project's current sale state and ruleset flags.
+- Treat deployer and clone initialization steps as setup-only actions; verify ownership, pricing, and store references before publishing a hook address to users.
+- When cash-out behavior or pay-hook composition changes, coordinate that with the project's ruleset configuration rather than assuming the hook can pause itself.
+
+## One-Way Or High-Risk Actions
+
+- Clone initialization is one-time, and immutable constructor references on the implementation cannot be changed afterward.
+- Hook ownership transfers change who can exercise every `onlyOwner` surface; accidental ownership moves are high-impact.
+- Tier and pricing changes can have user-facing economic effects immediately even when they are technically reversible for future sales.
+
+## Recovery Notes
+
+- If a hook is initialized with the wrong immutable dependencies or ownership model, deploy a new hook and migrate future project rulesets to it.
+- If a project-specific configuration goes bad, prefer moving the project to a replacement hook over trying to retrofit behavior the hook was not designed to support.
+
 ## Roles
 
 ### Hook Owner (JBOwnable)
@@ -35,7 +62,7 @@ Admin privileges and their scope in nana-721-hook-v6.
 | Function | Permission ID | Checked Against | What It Does |
 |----------|--------------|-----------------|--------------|
 | `adjustTiers()` | `ADJUST_721_TIERS` | `owner()` | Adds new tiers and/or soft-removes existing tiers. Sets tier split groups in JBSplits. |
-| `mintFor()` | `MINT_721` | `owner()` | Manually mints NFTs from tiers that have `allowOwnerMint` enabled. Bypasses price checks (passes `type(uint256).max` as amount). |
+| `mintFor()` | `MINT_721` | `owner()` | Manually mints NFTs from tiers that have `flags.allowOwnerMint` enabled. Bypasses price checks (passes `type(uint256).max` as amount). |
 | `setDiscountPercentOf()` | `SET_721_DISCOUNT_PERCENT` | `owner()` | Sets the discount percentage for a single tier. |
 | `setDiscountPercentsOf()` | `SET_721_DISCOUNT_PERCENT` | `owner()` | Batch-sets discount percentages for multiple tiers. |
 | `setMetadata()` | `SET_721_METADATA` | `owner()` | Updates collection name, symbol, baseURI, contractURI, tokenUriResolver, and/or per-tier encoded IPFS URIs. Empty strings leave values unchanged. |
@@ -46,8 +73,8 @@ Admin privileges and their scope in nana-721-hook-v6.
 | Function | Permission ID | Checked Against | What It Does |
 |----------|--------------|-----------------|--------------|
 | `launchProjectFor()` | None | Anyone can call | Creates a new project with a 721 hook. Ownership goes to the specified `owner` address. |
-| `launchRulesetsFor()` | `QUEUE_RULESETS` + `SET_TERMINALS` | Project NFT owner | Deploys a hook and launches rulesets for an existing project. |
-| `queueRulesetsOf()` | `QUEUE_RULESETS` | Project NFT owner | Deploys a hook and queues rulesets for an existing project. |
+| `launchRulesetsFor()` | `QUEUE_RULESETS` + `SET_TERMINALS` | Project NFT owner or delegate | Deploys a hook and launches rulesets for an existing project. |
+| `queueRulesetsOf()` | `QUEUE_RULESETS` | Project NFT owner or delegate | Deploys a hook and queues rulesets for an existing project. |
 
 ### JB721TiersHookDeployer
 
@@ -67,14 +94,14 @@ Admin privileges and their scope in nana-721-hook-v6.
 | Function | Caller | What It Does |
 |----------|--------|--------------|
 | `recordAddTiers()` | Hook contract | Adds tiers to the caller's namespace. Category sort order enforced. |
-| `recordRemoveTierIds()` | Hook contract | Marks tiers as removed in bitmap. Respects `cannotBeRemoved` flag. |
+| `recordRemoveTierIds()` | Hook contract | Marks tiers as removed in bitmap. Respects `flags.cantBeRemoved` flag. |
 | `recordMint()` | Hook contract | Records mints, decrements supply, enforces price and reserve checks. |
 | `recordMintReservesFor()` | Hook contract | Mints reserved NFTs from a tier. |
 | `recordBurn()` | Hook contract | Increments burn counter for token IDs. |
 | `recordFlags()` | Hook contract | Sets behavioral flags for the caller's hook. |
 | `recordSetTokenUriResolver()` | Hook contract | Sets the token URI resolver. |
 | `recordSetEncodedIPFSUriOf()` | Hook contract | Sets the encoded IPFS URI for a tier. |
-| `recordSetDiscountPercentOf()` | Hook contract | Updates a tier's discount percent. Enforces bounds and `cannotIncreaseDiscountPercent`. |
+| `recordSetDiscountPercentOf()` | Hook contract | Updates a tier's discount percent. Enforces bounds and `flags.cantIncreaseDiscountPercent`. |
 | `recordTransferForTier()` | Hook contract | Updates per-tier balance tracking on transfer. |
 | `cleanTiers()` | Anyone | Reorganizes the tier sorting linked list to skip removed tiers. Pure bookkeeping, no value at risk. |
 
@@ -116,8 +143,8 @@ The following are set at deploy/initialization time and **cannot be changed afte
 | `PROJECT_ID` | `initialize()` | Which project this hook belongs to |
 | Pricing context (currency, decimals) | `initialize()` | Packed into `_packedPricingContext` -- the token denomination for tier prices |
 | `JB721TiersHookFlags` | `initialize()` | `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting`, `preventOverspending`, `issueTokensForSplits` |
-| Per-tier `cannotBeRemoved` | `recordAddTiers()` | Whether a tier can be soft-removed |
-| Per-tier `cannotIncreaseDiscountPercent` | `recordAddTiers()` | Whether a tier's discount can be increased |
+| Per-tier `flags.cantBeRemoved` | `recordAddTiers()` | Whether a tier can be soft-removed |
+| Per-tier `flags.cantIncreaseDiscountPercent` | `recordAddTiers()` | Whether a tier's discount can be increased |
 | Per-tier `reserveFrequency` | `recordAddTiers()` | How often reserve NFTs accrue |
 | Per-tier `initialSupply` | `recordAddTiers()` | Maximum number of NFTs mintable from the tier |
 | Per-tier `price` | `recordAddTiers()` | The base price (and cash-out weight) of NFTs in the tier |
@@ -139,7 +166,7 @@ Two behaviors are controlled by the project's current ruleset metadata (packed i
 
 | Bit | Flag | Effect |
 |-----|------|--------|
-| 0 | `transfersPaused` | When set, NFT transfers are blocked for tiers that have `transfersPausable` enabled |
+| 0 | `transfersPaused` | When set, NFT transfers are blocked for tiers that have `flags.transfersPausable` enabled |
 | 1 | `mintPendingReservesPaused` | When set, `mintPendingReservesFor()` reverts |
 
 These can change each ruleset cycle, giving the project owner temporary control over these behaviors without modifying the hook itself.
@@ -152,9 +179,9 @@ What the hook owner **cannot** do:
 - **Cannot change tier prices after creation.** The `price` field in `JBStored721Tier` is set once in `recordAddTiers()` and never modified. Cash-out weight is always based on the original price.
 - **Cannot change reserve frequency after creation.** The `reserveFrequency` is immutable per tier.
 - **Cannot reduce a tier's initial supply.** Supply can only decrease through minting and burning.
-- **Cannot remove a tier marked `cannotBeRemoved`.** The store enforces this in `recordRemoveTierIds()`.
-- **Cannot increase a tier's discount if `cannotIncreaseDiscountPercent` is set.** The store enforces this in `recordSetDiscountPercentOf()`.
-- **Cannot mint from tiers without `allowOwnerMint`.** The `mintFor()` function passes `isOwnerMint: true` to the store, which checks the flag.
+- **Cannot remove a tier marked `flags.cantBeRemoved`.** The store enforces this in `recordRemoveTierIds()`.
+- **Cannot increase a tier's discount if `flags.cantIncreaseDiscountPercent` is set.** The store enforces this in `recordSetDiscountPercentOf()`.
+- **Cannot mint from tiers without `flags.allowOwnerMint`.** The `mintFor()` function passes `isOwnerMint: true` to the store, which checks the flag.
 - **Cannot re-initialize a hook.** The `initialize()` function reverts if `_initialized` is already true.
 - **Cannot change the pricing currency, decimals, or prices contract.** `PRICES` is immutable (set in constructor), and the currency/decimals in `_packedPricingContext` are set once during initialization.
 - **Cannot bypass the flag restrictions.** Once `noNewTiersWithReserves`, `noNewTiersWithVotes`, or `noNewTiersWithOwnerMinting` are set, all future tiers added via `adjustTiers()` must comply.

package/ARCHITECTURE.md

@@ -1,122 +1,76 @@
-# nana-721-hook-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-NFT tier system for Juicebox V6. Allows projects to attach tiered NFT minting to payments and use NFTs as cash-out hooks. Supports on-chain and off-chain metadata, category-based sorting, and configurable pricing with discounts.
+`nana-721-hook-v6` adds tiered NFT behavior to Juicebox projects. It lets a project accept payments, mint NFTs from configured tiers, optionally accumulate NFT credits, lazily mint reserves, and, when enabled, let holders burn NFTs to cash out project surplus according to tier-defined economics.
 
-The design permits a high theoretical tier ceiling, but several important reads and cash-out calculations still scale
-with `maxTierId`. In practice, this should be treated as a curated-catalog hook with an explicit operating envelope,
-not as a guarantee that very large catalogs are comfortable to run on-chain.
+## Boundaries
 
-## Contract Map
+- `JB721TiersHook` owns tier-aware behavior.
+- `JB721TiersHookStore` owns compact tier storage and many validation rules.
+- `JB721TiersHookDeployer` and `JB721TiersHookProjectDeployer` own deployment and project-launch convenience.
+- The repo does not replace the core terminal, controller, or surplus logic; it plugs into them.
 
-```
-src/
-├── JB721TiersHook.sol                — Pay + cash-out hook that mints/burns tiered NFTs
-├── JB721TiersHookStore.sol           — Tier configuration storage and pricing logic
-├── JB721TiersHookDeployer.sol        — Deploys hook+store pairs (clone-based)
-├── JB721TiersHookProjectDeployer.sol — Launches project + hook in one transaction
-├── abstract/
-│   ├── JB721Hook.sol                 — Base ERC-721 + pay/cashout hook integration
-│   └── ERC721.sol                    — Minimal ERC-721 implementation
-├── libraries/
-│   ├── JB721Constants.sol            — Global constants (DISCOUNT_DENOMINATOR)
-│   ├── JB721TiersHookLib.sol         — Split calculations, price normalization, weight math, fund distribution
-│   ├── JB721TiersRulesetMetadataResolver.sol — Bit-packed 721 ruleset metadata (transfer/reserve pause flags)
-│   ├── JBBitmap.sol                  — Bitmap utilities for tier removal tracking
-│   └── JBIpfsDecoder.sol             — IPFS CID encoding/decoding for token URIs
-├── interfaces/                       — All interfaces (IJB721TiersHook, etc.)
-└── structs/                          — Tier config, mint context, cash-out structs
-```
-
-## Key Data Flows
-
-### NFT Minting (via Payment)
-```
-User → JBMultiTerminal.pay(metadata)
-  → beforePayRecordedWith()
-    → calculateSplitAmounts(): per-tier split amounts (in tier pricing denomination)
-    → convertAndCapSplitAmounts(): convert to payment token denomination (if currencies differ)
-    → calculateWeight(): adjust weight down by split fraction
-  → JBTerminalStore records payment
-  → afterPayRecordedWith() → _processPayment()
-    → Normalize payment value to tier pricing currency
-    → Decode tier IDs from metadata
-    → For each tier:
-      → Validate: not removed, not paused, supply available
-      → Check price (with optional discount, normalized to tier pricing currency)
-      → Mint NFT to beneficiary
-    → Leftover amount stored as pay credits (revert if overspending not allowed)
-    → Distribute split funds (priority: split.hook > split.projectId > split.beneficiary)
-```
-
-#### Split Amount and Price Normalization
-
-Tiers can be priced in a different currency than the payment token (e.g. tiers priced in USD while payments arrive in ETH). The split/weight pipeline in `beforePayRecordedWith` resolves this in two steps:
-
-1. **`calculateSplitAmounts`** — For each tier the payer wants to mint, looks up its `splitPercent` (the fraction of the tier price that should be routed to the tier's split group rather than into the project treasury). Computes `effectivePrice * splitPercent / SPLITS_TOTAL_PERCENT` for each tier, where `effectivePrice` accounts for any active discount. Returns the total and a per-tier breakdown, all denominated in the **tier pricing currency**.
-
-2. **`convertAndCapSplitAmounts`** — If the payment currency differs from the tier pricing currency, converts every per-tier split amount (and the total) into the **payment token denomination** using `JBPrices`, and caps the total at the actual payment value. This is necessary because the terminal will subtract the split amount from the payment value, so both must be in the same unit.
+## Main Components
 
-After conversion, `calculateWeight` scales the terminal's minting weight down by the fraction of the payment that was routed to splits (unless the `issueTokensForSplits` flag is set, in which case the full weight is preserved).
+| Component | Responsibility |
+| --- | --- |
+| `JB721TiersHook` | Data hook, pay hook, and cash-out hook for tiered NFTs |
+| `JB721TiersHookStore` | Packed tier storage, mint accounting, reserves, and validation |
+| `JB721Hook`, `ERC721` | Shared NFT machinery and token metadata plumbing |
+| deployers | Clone and launch helpers for hook instances and projects |
+| libraries and structs | Tier math, metadata decoding, flags, and config surfaces |
 
-During `afterPayRecordedWith`, the payment value is separately normalized into the tier pricing currency via `normalizePaymentValue` so that tier prices can be compared against what was paid. The forwarded split funds are then distributed to each tier's split group by `distributeAll`.
+## Runtime Model
 
-### Discount Mechanism
+### Payment Path
 
-Each tier has a `discountPercent` (0-200 scale where 200 = 100% discount / free mint). The project owner can adjust it via `setDiscountPercentOf`, subject to a per-tier `cannotIncreaseDiscountPercent` flag that prevents raising the discount once set. Discounts can only be decreased unless the tier explicitly allows increases.
-
-Key behaviors:
-- **Minting**: The store applies the discount when checking the price during `recordMint`, so payers pay less.
-- **Split calculations**: `calculateSplitAmounts` applies the discount to the tier price before computing the split portion, so splits are proportional to the actual amount paid.
-- **Cash-out weight**: Uses the **original undiscounted price**, not the effective price. This means a discounted NFT carries the same cash-out weight as a full-price one. Project owners should be aware that heavily discounted mints dilute the cash-out pool at full weight while contributing less to the treasury.
-
-### NFT Cash Out
-```
-Holder → JBMultiTerminal.cashOutTokensOf()
-  → JB721TiersHook.afterCashOutRecordedWith()
-    → Burn specified NFT token IDs
-    → Each NFT's cash-out weight = tier.price (full price, ignoring discounts)
-    → Total cash-out weight (denominator) = sum of (tier.price * (outstanding + pending)) across all tiers
-    →   where outstanding = minted - burned, pending = pending reserve mints
+```text
+terminal payment
+  -> data hook inspects metadata and requested tier IDs
+  -> hook computes which tiers can be minted and how much value is left over
+  -> terminal settles the payment into the project
+  -> pay hook mints NFTs and stores any remaining value as credits when allowed
 ```
 
-### Tier Management
-```
-Owner → JB721TiersHook.adjustTiers()
-  → Add new tiers (must be sorted by category)
-  → Remove existing tiers (flags, doesn't delete)
-```
+### Reserve Path
 
-## Extension Points
+```text
+tier purchases accumulate reserve entitlement
+  -> reserves are minted lazily via explicit reserve-mint calls
+```
 
-| Point | Interface | Purpose |
-|-------|-----------|---------|
-| Token URI resolver | `IJB721TokenUriResolver` | Custom metadata rendering |
-| Pay hook | `IJBPayHook` | Called after payment recorded |
-| Cash out hook | `IJBCashOutHook` | Called during cash out |
+### Cash-Out Path
 
-## Design Decisions
+```text
+holder burns NFT
+  -> data hook can override cash-out count, supply, and tax behavior
+  -> reclaim value is based on the tier's original configured price, not any discount used at mint time
+```
 
-1. **Clone-based deployment** — `JB721TiersHookDeployer` uses Solady's `LibClone` to deploy minimal proxies of a reference `JB721TiersHook` instance. This keeps deployment cost low and consistent regardless of the hook contract's bytecode size. Each clone is initialized via `initialize()` (not a constructor), which sets the project ID, tiers, and flags. Deterministic deploys are supported via `cloneDeterministic` with a caller-scoped salt.
+## Critical Invariants
 
-2. **Separate store contract** — `JB721TiersHookStore` holds all tier data, mint tracking, and pricing logic in a standalone contract shared across hook instances. This serves two purposes: it keeps the hook contract under the EIP-170 size limit (24 KB), and it allows the store to act as the `msg.sender` for state mutations (tier additions use `msg.sender` as the hook key), providing a natural access-control boundary.
+- Tiers are an ordered, compact data structure. Category ordering and tier IDs are part of storage semantics, not just metadata.
+- Original tier price drives cash-out weight. Discounts change purchase price, not reclaim weight.
+- Reserve frequency and owner-mint settings interact; configurations that would double-count mint authority must stay invalid.
+- Pending reserves belong in supply-sensitive calculations even before they are lazily minted.
+- If `useDataHookForCashOut` is enabled, fungible-token cash outs are intentionally displaced by NFT cash-out semantics.
 
-3. **Category sorting instead of price sorting** — Tiers are stored in a linked list sorted by `category` (a uint24 grouping field), not by price. This lets projects organize NFTs into logical groups (e.g. membership tiers, collectibles, special editions) and query them by group. The `InvalidCategorySortOrder` error enforces that new tiers are added in non-decreasing category order.
+## Where Complexity Lives
 
-4. **Cash-out weight uses `initialSupply * price`** — The `totalCashOutWeight` denominator sums `price * (outstanding + pendingReserves)` across all tiers, where outstanding = minted minus burned. Each individual NFT's weight is simply its tier's `price`. Using the original undiscounted price (rather than what was actually paid) ensures that cash-out values are stable and predictable: discounts are treated as transient purchase incentives, not permanent reductions in an NFT's share of the treasury.
+- The store is compact and efficient, which means seemingly small layout changes have wide effects.
+- Preview behavior, pay behavior, reserve minting, and cash-out behavior all depend on the same tier semantics.
+- Metadata decoding and credit handling create edge cases around partial spends and exact-tier selection.
 
-5. **Library extraction for EIP-170 compliance** — `JB721TiersHookLib` contains split calculations, price normalization, fund distribution, tier adjustment logic, and IPFS URI decoding. These are called via `external` library functions (which deploy as a separate contract) or via `DELEGATECALL`. This pattern keeps the hook contract's deployed bytecode under the 24 KB limit while preserving the ability to emit events from the hook's address.
+## Dependencies
 
-6. **Discount denominator of 200** — The `discountPercent` field is a uint8 with a denominator of 200 (`JB721Constants.DISCOUNT_DENOMINATOR`). A value of 200 represents 100% discount (free mint), giving 0.5% granularity. The `cannotIncreaseDiscountPercent` flag on each tier lets project owners create promotional discounts that can be reduced but never increased beyond their initial level.
+- `nana-core-v6` hooks, permissions, controller, and terminal surfaces
+- Optional token URI resolvers such as `banny-retail-v6` and `defifa`
 
-7. **Split fund distribution with try-catch** — All external calls during split distribution (to split hooks, terminals, and beneficiaries) are wrapped in try-catch. A reverting recipient does not brick payments for the entire project. Failed amounts are accumulated separately during the loop and routed to the project balance afterward, ensuring proportional redistribution -- later recipients receive only their configured share, not an inflated share from earlier failures.
+## Safe Change Guide
 
-## Dependencies
-- `@bananapus/core-v6` — Core protocol interfaces
-- `@bananapus/ownable-v6` — JB-aware ownership
-- `@bananapus/address-registry-v6` — Deterministic deploy addresses
-- `@bananapus/permission-ids-v6` — Permission constants
-- `@openzeppelin/contracts` — ERC-721 utils, Ownable
-- `@prb/math` — mulDiv
-- `solady` — LibClone
+- Treat store changes as consensus-level changes for every repo that composes this hook.
+- Preview behavior and live behavior must stay aligned. If a preview lies, integrators misprice payments.
+- Be careful when adding metadata fields; many sibling repos depend on stable encoding conventions.
+- Keep hook-order assumptions explicit when this hook is composed with other data hooks through a wrapper deployer.
+- If you touch reserve logic, also inspect supply math and cash-out denominators.