@bananapus/721-hook-v6 0.0.35 → 0.0.37

package/ADMINISTRATION.md

@@ -1,189 +1,75 @@
 # Administration
 
-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.
+| --- | --- |
+| Scope | Tiered NFT hook configuration, tier adjustment, and deployer wiring |
+| Control posture | Mixed project-owner and delegated control |
+| Highest-risk actions | Adjusting tiers, setting discount or metadata behavior, and wiring the wrong hook or resolver |
+| Recovery posture | Some configuration is mutable, but many tier properties are intentionally one-way |
 
-## One-Way Or High-Risk Actions
+## Purpose
 
-- 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.
+`nana-721-hook-v6` splits control between project-level hook ownership and the tier rules enforced by the store. Many important settings can be changed only in limited ways after launch.
 
-## Recovery Notes
+## Control Model
 
-- 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.
+- project owners or delegates control hook-level configuration
+- tier creation and mutation are permissioned and partially one-way
+- the store trusts the calling hook for its own state namespace
+- deployers package setup, but do not remove the need for runtime review
 
 ## Roles
 
-### Hook Owner (JBOwnable)
-
-- **Assigned by**: `initialize()` transfers ownership to the caller. When deployed via `JB721TiersHookProjectDeployer.launchProjectFor()`, ownership is transferred to the project NFT, meaning the project owner controls the hook.
-- **Scope**: Per-hook instance. Each cloned hook has its own independent owner.
-- **Inheritance**: `JBOwnable` supports both EOA ownership and project-based ownership (owner = holder of the project's ERC-721 NFT). When ownership is transferred to a project via `transferOwnershipToProject()`, whoever owns that project NFT becomes the hook's owner.
-
-### Permission Operators
-
-- **Assigned by**: The hook owner grants permissions via the `JBPermissions` contract.
-- **Scope**: Per-project. Operators can be granted specific permission IDs scoped to the hook's `PROJECT_ID`.
-- **How it works**: Each privileged function calls `_requirePermissionFrom(account: owner(), projectId: PROJECT_ID, permissionId: ...)`. This passes if the caller IS the owner, OR if the caller has been granted the specified permission ID by the owner for the project.
-
-### Terminal (Protocol-Level Caller)
-
-- **Assigned by**: The project's `JBDirectory` configuration.
-- **Scope**: Only a contract registered as a terminal for the hook's project in `JBDirectory` can call `afterPayRecordedWith()` and `afterCashOutRecordedWith()`.
-- **Verification**: `DIRECTORY.isTerminalOf(projectId, IJBTerminal(msg.sender))` is checked in `JB721Hook.sol`.
-
-### Store Callers (msg.sender Trust Model)
-
-- **Assigned by**: Implicit. `JB721TiersHookStore` trusts `msg.sender` as the hook contract.
-- **Scope**: All `record*` functions in the store use `msg.sender` as the hook address key. Any contract can call the store, but state changes are scoped to `msg.sender`'s own data namespace.
-- **Why this is safe**: Each hook clone has its own address, and the store keys all data by `[msg.sender][tierId]`. A malicious contract calling the store can only modify its own namespace.
-
-## Privileged Functions
-
-### JB721TiersHook
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Project owner | `owner()` or project control surface | Per hook | Main authority |
+| Tier delegate | `JBPermissions` grant | Per project | Usually tier, mint, discount, or metadata permissions |
+| Reserve beneficiary | Tier config | Per tier | Receives reserve NFTs |
 
-| 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 `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. |
-| `initialize()` | None (one-time) | `_initialized` flag check | Initializes a cloned hook. Can only be called once. Transfers ownership to caller on completion. |
+## Privileged Surfaces
 
-### JB721TiersHookProjectDeployer
+- `adjustTiers(...)`
+- `mintFor(...)`
+- `setDiscountPercentOf(...)`
+- `setMetadata(...)`
+- deployer setup and hook ownership transfer paths
 
-| 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 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. |
+## Immutable And One-Way
 
-### JB721TiersHookDeployer
+- many tier properties are immutable once created
+- removed tiers do not reduce `maxTierIdOf`
+- pool-like mutable rescue does not exist here; bad tier design is often expensive to unwind
 
-| Function | Permission ID | Checked Against | What It Does |
-|----------|--------------|-----------------|--------------|
-| `deployHookFor()` | None | Anyone can call | Clones and initializes a new hook instance. Ownership starts with the deployer contract, then is transferred to `msg.sender`. |
+## Operational Notes
 
-### JB721Hook (Abstract Base)
+- review tier parameters before launch as if they were economic policy
+- treat discount changes and metadata changes as meaningful authority, not cosmetic controls
+- be explicit about whether the hook participates in pay, cash out, or both
+- separate resolver trust from hook and store trust
 
-| Function | Required Caller | What It Does |
-|----------|----------------|--------------|
-| `afterPayRecordedWith()` | Project terminal | Processes payment, mints NFTs. Verifies caller via `DIRECTORY.isTerminalOf()`. |
-| `afterCashOutRecordedWith()` | Project terminal | Burns NFTs on cash out. Verifies caller via `DIRECTORY.isTerminalOf()` and that `msg.value == 0`. |
+## Machine Notes
 
-### JB721TiersHookStore (No Access Control -- msg.sender Keyed)
+- do not reason from the hook alone when the bug may live in the store
+- if a resolver is involved, inspect it separately
+- if tier counts are large, re-check gas-sensitive reads and writes before operational changes
 
-| 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 `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 `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. |
+## Recovery
 
-## Permission System
+- some mistakes can be corrected through allowed metadata or discount changes
+- many tier-design mistakes are effectively permanent once live
+- deployer mistakes may require a new hook path rather than in-place repair
 
-Permissions flow through two mechanisms:
-
-1. **JBOwnable** (`JB721TiersHook` inherits from it): The hook has a single `owner()` that can be an EOA or a Juicebox project. When owned by a project, the holder of that project's ERC-721 NFT is the effective owner.
-
-2. **JBPermissions** (protocol-wide permission registry): The owner can grant specific permission IDs to operator addresses. Each permission is scoped to a `(operator, account, projectId, permissionId)` tuple. The `ROOT` permission (ID 1) grants all permissions.
-
-The `_requirePermissionFrom()` check (inherited from `JBOwnable` via `JBPermissioned`) passes if:
-- `msg.sender == account` (the owner themselves), OR
-- `JBPermissions.hasPermission(msg.sender, account, projectId, permissionId)` returns true.
-
-### Permission IDs Used
-
-| Permission ID | Constant Name | Used By |
-|--------------|---------------|---------|
-| `JBPermissionIds.ADJUST_721_TIERS` | `ADJUST_721_TIERS` | `adjustTiers()` |
-| `JBPermissionIds.MINT_721` | `MINT_721` | `mintFor()` |
-| `JBPermissionIds.SET_721_DISCOUNT_PERCENT` | `SET_721_DISCOUNT_PERCENT` | `setDiscountPercentOf()`, `setDiscountPercentsOf()` |
-| `JBPermissionIds.SET_721_METADATA` | `SET_721_METADATA` | `setMetadata()` |
-| `JBPermissionIds.QUEUE_RULESETS` | `QUEUE_RULESETS` | `launchRulesetsFor()`, `queueRulesetsOf()` |
-| `JBPermissionIds.SET_TERMINALS` | `SET_TERMINALS` | `launchRulesetsFor()` |
-
-## Immutable Configuration
-
-The following are set at deploy/initialization time and **cannot be changed afterward**:
-
-| Property | Set In | Scope |
-|----------|--------|-------|
-| `DIRECTORY` | Constructor | Which terminal/controller directory is trusted |
-| `PRICES` | Constructor | Which prices contract is used for cross-currency conversions |
-| `RULESETS` | Constructor | Which rulesets contract is consulted |
-| `STORE` | Constructor | Which store manages tier data |
-| `SPLITS` | Constructor | Which splits contract manages tier split groups |
-| `METADATA_ID_TARGET` | Constructor | The address used for metadata ID derivation (original implementation address for clones) |
-| `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 `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 |
-| Per-tier `category` | `recordAddTiers()` | The category grouping for sort order |
-
-## Clone Pattern
-
-`JB721TiersHook` is deployed as an implementation contract and then cloned via `LibClone.clone()` in `JB721TiersHookDeployer`. Each clone is a minimal proxy that delegates all calls to the implementation.
-
-**Admin implications:**
-- The implementation contract cannot be self-destructed or modified after deployment. Even if it could be, clones would break since they `delegatecall` to the implementation address.
-- Each clone has its own storage (including `PROJECT_ID`, ownership, and tier data). The implementation's storage is unused.
-- `METADATA_ID_TARGET` is set to the original implementation address, ensuring consistent metadata ID derivation across all clones.
-- The `initialize()` function uses an `_initialized` bool flag to prevent re-initialization. The implementation contract's constructor sets `_initialized = true`, blocking direct initialization. Clones start with `_initialized = false` and set it to `true` during `initialize()`.
-
-## Ruleset-Level Pauses
-
-Two behaviors are controlled by the project's current ruleset metadata (packed into the 14-bit `metadata` field of `JBRulesetMetadata`), parsed by `JB721TiersRulesetMetadataResolver`:
-
-| Bit | Flag | Effect |
-|-----|------|--------|
-| 0 | `transfersPaused` | When set, NFT transfers are blocked for tiers that have `flags.transfersPausable` enabled |
-| 1 | `mintPendingReservesPaused` | When set, `mintPendingReservesFor()` reverts |
+## Admin Boundaries
 
-These can change each ruleset cycle, giving the project owner temporary control over these behaviors without modifying the hook itself.
+- no one can rewrite immutable tier properties after creation
+- deployers do not bypass runtime permissions after setup
+- resolver behavior cannot fix broken hook accounting
 
-## Admin Boundaries
+## Source Map
 
-What the hook owner **cannot** do:
-
-- **Cannot steal or redirect existing NFTs.** The ERC-721 transfer logic is standard; the owner has no backdoor to move tokens between arbitrary addresses.
-- **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 `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.
-- **Cannot mint more reserves than the formula allows.** Reserve mints are bounded by `ceil(nonReserveMints / reserveFrequency)`.
-- **Cannot modify the split groups outside of `adjustTiers()`.** Tier split groups are set during tier addition via the library; there is no separate admin function to change them directly on the hook (though the project owner could call `JBSplits.setSplitGroupsOf()` directly if they have the appropriate permission).
+- `src/JB721TiersHook.sol`
+- `src/JB721TiersHookStore.sol`
+- `src/JB721TiersHookDeployer.sol`
+- `src/JB721TiersHookProjectDeployer.sol`

package/ARCHITECTURE.md

@@ -2,75 +2,97 @@
 
 ## Purpose
 
-`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.
+`nana-721-hook-v6` is the shared tiered NFT layer for Juicebox V6. It lets projects sell NFT tiers, track reserves, route split payouts, and cash out NFTs without replacing core treasury accounting.
 
-## Boundaries
+## System Overview
 
-- `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.
+`JB721TiersHook` is the runtime hook. `JB721TiersHookStore` is the accounting backend for tiers, supply, reserves, and lookup. The deployers package that hook into reusable flows for existing projects and new project launches.
 
-## Main Components
+Custom token URI resolvers usually live outside this repo, but they still affect the trusted surface seen by users.
 
-| 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 |
+## Core Invariants
 
-## Runtime Model
+- the hook must not create alternate treasury accounting
+- tier supply, burned counts, and reserves must stay coherent
+- cash-out weight must reflect the intended tier economics
+- reserve minting and split routing must not drift from stored tier state
+- store-linked list and bitmap assumptions must stay valid under tier add, remove, and clean operations
+- deployer wiring must preserve the expected ruleset and hook shape
 
-### Payment Path
+## Modules
 
-```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
-```
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JB721TiersHook` | Pay hook, cash-out hook, permissions, and project-facing execution | Runtime core |
+| `JB721TiersHookStore` | Tier definitions, balances, reserve tracking, and accounting | Shared state |
+| `JB721TiersHookDeployer` | Clone deployer for existing projects | Wiring helper |
+| `JB721TiersHookProjectDeployer` | Project-launch deployer with hook setup | Launch helper |
+| `JB721Hook` | Abstract 721 hook base | Shared behavior |
+
+## Trust Boundaries
 
-### Reserve Path
+- core accounting, pricing, and terminal authentication remain in `nana-core-v6`
+- metadata resolvers can be project-specific and should be treated as trusted external surfaces
+- the store is trusted by every hook that uses it
+- deployers are trusted to wire the hook into the intended project and ruleset shape
+
+## Critical Flows
+
+### Pay And Mint
 
 ```text
-tier purchases accumulate reserve entitlement
-  -> reserves are minted lazily via explicit reserve-mint calls
+payment arrives
+  -> hook decodes metadata and tier choices
+  -> store records mints, credits, supply changes, and reserve effects
+  -> hook may route split payouts from forwarded funds
+  -> collection state and balances update for the beneficiary
 ```
 
-### Cash-Out Path
+### Cash Out
 
 ```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
+cash out requested
+  -> hook checks NFT-specific metadata and selected token IDs
+  -> hook burns NFTs
+  -> store records burn and supply effects
+  -> terminal reclaims value using hook-aware cash-out math
 ```
 
-## Critical Invariants
-
-- 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.
+## Accounting Model
 
-## Where Complexity Lives
+This repo owns tier accounting and NFT lifecycle logic. It does not own the canonical project ledger for balances, fees, or surplus.
 
-- 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.
+The most important state lives in the store: remaining supply, burned counts, reserve tracking, and per-tier configuration.
 
-## Dependencies
+## Security Model
 
-- `nana-core-v6` hooks, permissions, controller, and terminal surfaces
-- Optional token URI resolvers such as `banny-retail-v6` and `defifa`
+- store corruption has ecosystem-wide blast radius because many products reuse it
+- reserve logic, discounts, and cash-out weight are the main economic risk surfaces
+- split distribution and fallback behavior are part of correctness, not a secondary concern
+- gas costs matter because some reads and writes scale with tier count
 
 ## Safe Change Guide
 
-- 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.
+- review hook and store behavior together when changing tier lifecycle logic
+- if reserve logic changes, re-check cash-out weight and pending reserve effects together
+- if deployer behavior changes, re-check ruleset wiring and ownership transfer paths
+- do not treat resolver behavior as proof that hook accounting is correct
+
+## Canonical Checks
+
+- pay, mint, and redeem end-to-end behavior:
+  `test/E2E/Pay_Mint_Redeem_E2E.t.sol`
+- store and lifecycle invariants:
+  `test/invariants/TierLifecycleInvariant.t.sol`
+  `test/invariants/TieredHookStoreInvariant.t.sol`
+- split-credit and deployer regressions:
+  `test/audit/CodexSplitCreditsMismatch.t.sol`
+  `test/regression/ProjectDeployerRulesets.t.sol`
+
+## Source Map
+
+- `src/JB721TiersHook.sol`
+- `src/JB721TiersHookStore.sol`
+- `src/JB721TiersHookDeployer.sol`
+- `src/JB721TiersHookProjectDeployer.sol`
+- `src/libraries/JB721TiersHookLib.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,114 +1,77 @@
 # Audit Instructions
 
-This repo is the tiered ERC-721 hook system for Juicebox payments and NFT cash-outs. Audit it as a shared primitive used by many other repos.
+This repo adds tiered NFT issuance and cash-out behavior to Juicebox projects. Audit it as a shared accounting layer whose mistakes can affect many downstream products.
 
-## Objective
+## Audit Objective
 
 Find issues that:
-- let users mint tiers more cheaply than intended
-- over-mint, under-burn, or miscount reserves, credits, or supply
-- route split funds incorrectly or let split paths distort token issuance
-- let NFT cash-outs reclaim more value than intended
-- corrupt shared store state across different hook instances
+
+- corrupt tier supply, reserve state, or burn accounting
+- misprice cash outs or split routing
+- let permissions or deployer wiring create unsafe lifecycle changes
+- create gas or liveness failures in tier-heavy deployments
+- break trust boundaries between hook, store, and resolver behavior
 
 ## Scope
 
 In scope:
+
 - `src/JB721TiersHook.sol`
 - `src/JB721TiersHookStore.sol`
-- `src/JB721TiersHookDeployer.sol`
-- `src/JB721TiersHookProjectDeployer.sol`
-- `src/abstract/`
-- `src/interfaces/`
-- `src/libraries/`
-- `src/structs/`
+- deployers, libraries, interfaces, and structs under `src/`
 - deployment scripts in `script/`
 
-This repo is depended on by Defifa, Croptop, Banny, Revnets, and omnichain deployers. Bugs here often have ecosystem-wide blast radius.
-
-## System Model
-
-The hook can act as:
-- a data hook for payment and cash-out accounting inputs
-- a pay hook that mints NFTs
-- a cash-out hook that burns NFTs and computes reclaim weight
-
-Key moving parts:
-- `JB721TiersHookStore` holds compact tier state
-- hook instances read and mutate tier data through the store
-- tier prices, discounts, reserves, credits, split percentages, and category order shape mint behavior
-- optional token URI resolvers can override metadata generation
-
-The most important design subtlety is that this repo affects both:
-- NFT state
-- core Juicebox accounting inputs and fulfillment order
-
-That combination is why small-looking mistakes here often become ecosystem-wide economic bugs.
+## Start Here
 
-## Critical Invariants
-
-1. Supply caps hold
-No tier may mint beyond its configured total supply once purchases, owner mints, and pending reserves are all considered.
-
-2. Reserve accounting is exact
-Pending reserves must neither disappear nor inflate reclaim denominators beyond what the design intends.
-
-3. Split routing matches accounting
-If part of a mint price is routed to splits, token issuance and treasury accounting must reflect only the intended project portion.
+1. `src/JB721TiersHook.sol`
+2. `src/JB721TiersHookStore.sol`
+3. `src/libraries/JB721TiersHookLib.sol`
 
-4. Cash-out weight is consistent
-The reclaim value for NFTs must match documented tier economics and must not be manipulable through discounts, credits, cross-currency inputs, or reserve timing.
+## Security Model
 
-5. Shared store isolation
-One hook instance must not corrupt or observe mutable state belonging to another project unexpectedly.
+The hook:
 
-6. Credit semantics remain bounded
-Unused payment value that becomes credits must not let a user later mint tiers, trigger splits, or receive project-token issuance on terms they did not actually fund.
+- mints and burns tiered NFTs through Juicebox flows
+- records tier lifecycle state in a shared store
+- can route split payouts from forwarded value
+- composes with project-specific metadata resolvers
 
-7. Resolver trust stays read-only unless explicitly intended
-Token URI resolvers must not become an implicit control plane for mint, burn, or accounting behavior.
+## Roles And Privileges
 
-## Threat Model
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Project authority | Configure tiers, metadata, and minting policy | Must stay inside explicit permission checks |
+| Store caller | Mutate store state in its own namespace | Must not corrupt tier accounting |
+| Resolver | Serve metadata and URI behavior | Must not be confused with accounting truth |
 
-Prioritize:
-- overspending and leftover-credit edge cases
-- cross-currency pricing with missing or stale feeds
-- tier additions or adjustments with invalid sort order or percent bounds
-- split hooks or terminal recipients that revert or partially fail
-- data-hook and pay-hook interactions inside the same payment
+## Integration Assumptions
 
-Especially high-value attacker profiles:
-- a payer crafting metadata and tier selections to desync credits, split routing, and token issuance
-- a project owner adjusting tiers between preview and execution windows
-- a downstream app assuming tier cash-out weight tracks discounted price when the primitive uses different economics
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-core-v6` | Terminal auth and pricing behavior are accurate | Pay and cash-out behavior drift |
+| Resolver repo | Metadata reads behave as expected | UI and marketplace behavior break |
 
-## Hotspots
+## Critical Invariants
 
-- `beforePayRecordedWith`, `afterPayRecordedWith`, and cash-out hooks
-- credit handling when `payer != beneficiary`
-- discount logic versus cash-out pricing
-- pending reserve minting and denominator logic
-- `splitPercent` handling and hook distribution fallback behavior
-- deployers that transfer ownership or queue rulesets around the hook
+1. Tier supply stays coherent.  
+   Remaining supply, burned counts, and outstanding ownership must reconcile.
+2. Reserve logic stays bounded.  
+   Pending reserves and reserve minting must not over-allocate.
+3. Cash-out weight is consistent.  
+   NFT reclaim value must match the tier model the hook and store intend.
+4. Split and fallback behavior is safe.  
+   Failed split paths must not silently corrupt value or lifecycle state.
 
-## Sequences Worth Replaying
+## Attack Surfaces
 
-1. Cross-currency payment where prices are missing, stale, or intentionally asymmetric.
-2. Payment with leftover value that becomes credits, then a second payment from a different payer/beneficiary arrangement.
-3. Tier purchases with split routing enabled, especially when split hooks or downstream terminals fail.
-4. Reserve-heavy tiers followed by NFT cash-out before pending reserves are minted.
-5. Tier adjustment or discount updates around active minting and cash-out windows.
+- pay and cash-out hook entrypoints
+- tier add, remove, and clean flows
+- reserve minting
+- split distribution and fallback paths
+- resolver integration
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-Current tests emphasize:
-- audit and regression fixes around split accounting and cross-currency behavior
-- invariants on tier lifecycle and store state
-- fork coverage for ERC-20 cash-out and tier split routes
-
-High-value findings in this repo tend to become repeatable vulnerabilities in downstream repos, so favor proofs that show the primitive itself returning or recording the wrong value.