@bananapus/721-hook-v6 0.0.34 → 0.0.36

package/ADMINISTRATION.md

@@ -1,189 +1,87 @@
 # 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 | Per-hook ownership, delegated 721 administration, and hook deployment flows |
+| Control posture | Per-instance owner or project-owner control with delegated `JBPermissions` |
+| Highest-risk actions | Tier adjustments, owner minting, metadata changes, and misassigned hook ownership |
+| Recovery posture | Project-specific config can sometimes be superseded with new rulesets, but bad clone wiring usually means replacement hooks |
 
-## 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` is administered per hook instance. The effective admin is the hook owner resolved through `JBOwnable`, plus any operators granted specific `JBPermissions`. The dangerous surfaces are tier adjustment, metadata changes, owner minting, discount changes, and hook deployment ownership.
 
-## 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.
+- Each hook instance has its own owner.
+- Ownership can follow an EOA or a Juicebox project NFT through `JBOwnable`.
+- Fine-grained operator delegation runs through `JBPermissions`.
+- Deployers are permissionless for new hooks, but existing-project launch and queue flows are permission-gated.
+- The store has no owner role; it trusts `msg.sender`-keyed namespaces.
 
 ## 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
-
-| 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. |
-
-### JB721TiersHookProjectDeployer
-
-| 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. |
-
-### JB721TiersHookDeployer
-
-| 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`. |
-
-### JB721Hook (Abstract Base)
-
-| 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`. |
-
-### JB721TiersHookStore (No Access Control -- msg.sender Keyed)
-
-| 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. |
-
-## Permission System
-
-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.
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Hook owner | `JBOwnable.owner()` | Per hook | May resolve dynamically through a project NFT |
+| Hook operator | Granted by `JBPermissions` | Per project | Usually `ADJUST_721_TIERS`, `MINT_721`, `SET_721_METADATA`, `SET_721_DISCOUNT_PERCENT` |
+| Project owner | `JBProjects.ownerOf(projectId)` | Per project | Relevant for project-deployer flows |
+| Terminal | `JBDirectory` routing | Per project | Can call pay and cash-out hook entrypoints |
+| Deployer caller | Anyone | Per deployment | Can deploy new standalone hooks |
 
-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.
+## Privileged Surfaces
 
-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.
+| Contract | Function | Who Can Call | Effect |
+| --- | --- | --- | --- |
+| `JB721TiersHook` | `adjustTiers(...)` | Owner or `ADJUST_721_TIERS` operator | Adds or removes tiers and updates split groups |
+| `JB721TiersHook` | `mintFor(...)` | Owner or `MINT_721` operator | Owner mint path, subject to tier flags |
+| `JB721TiersHook` | `setMetadata(...)` | Owner or `SET_721_METADATA` operator | Updates collection-level metadata and resolver references |
+| `JB721TiersHook` | `setDiscountPercentOf(...)`, `setDiscountPercentsOf(...)` | Owner or `SET_721_DISCOUNT_PERCENT` operator | Changes discount settings where allowed |
+| `JB721TiersHook` | `initialize(...)` | Anyone once per clone | One-time hook initialization and ownership setup |
+| `JB721TiersHookProjectDeployer` | `launchRulesetsFor(...)` | Project owner or relevant delegates | Launches hook-backed rulesets for an existing project |
+| `JB721TiersHookProjectDeployer` | `queueRulesetsOf(...)` | Project owner or `QUEUE_RULESETS` delegate | Queues hook-backed rulesets for an existing project |
 
-### Permission IDs Used
+## Immutable And One-Way
 
-| 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()` |
+- Implementation constructor dependencies are immutable.
+- Clone initialization is one-time.
+- Per-tier price, reserve frequency, and several flags are effectively set-once semantics.
+- Ownership transfers change every permission check because privileged functions check against `owner()`.
 
-## Immutable Configuration
+## Operational Notes
 
-The following are set at deploy/initialization time and **cannot be changed afterward**:
+- Grant narrow per-project permissions instead of owner-equivalent access where possible.
+- Treat `adjustTiers(...)` as an economic change, not just content management.
+- Verify hook ownership and pricing context before publishing a clone address.
+- When this hook is wrapped by deployers, review hook-order assumptions as part of administration.
 
-| 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 |
+## Machine Notes
 
-## 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.
+- Do not assume `owner()` is a static address; it may resolve through a project NFT.
+- Treat `src/JB721TiersHook.sol` and `src/JB721TiersHookStore.sol` together as the control-plane source of truth.
+- If a downstream deployer changes hook ownership or ruleset ordering, re-evaluate the admin model instead of reusing old assumptions.
 
-**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 |
+## Recovery
 
-These can change each ruleset cycle, giving the project owner temporary control over these behaviors without modifying the hook itself.
+- If the wrong immutable dependencies or ownership model were deployed, use a new hook clone.
+- If a project-specific configuration is bad, prefer migrating future rulesets to a replacement hook over trying to retrofit unsupported behavior.
 
 ## Admin Boundaries
 
-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).
+- The owner cannot change the store's constructor immutables or the clone's one-time initialization.
+- The owner cannot overwrite original tier price semantics used for cash-out weight.
+- The owner cannot bypass store-level flags such as non-removable tiers or discount increase restrictions.
+- There is no global admin who can rewrite every hook instance at once.
+
+## Source Map
+
+- `src/JB721TiersHook.sol`
+- `src/JB721TiersHookProjectDeployer.sol`
+- `src/JB721TiersHookDeployer.sol`
+- `src/JB721TiersHookStore.sol`
+- `script/Deploy.s.sol`
+- `script/helpers/Hook721DeploymentLib.sol`
+- `test/E2E/`
+- `test/TestAuditGaps.sol`

package/ARCHITECTURE.md

@@ -2,75 +2,90 @@
 
 ## 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 canonical tiered NFT issuance layer for Juicebox V6. It lets a project mint NFTs on payment, manage tier pricing and supply, accumulate NFT credits, lazily mint reserves, and optionally use NFT-aware cash-out behavior.
 
-## 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 project-facing hook surface. Through the shared `JB721Hook` base, it installs itself as both the ruleset data hook and the post-settlement pay and cash-out hook for the project. `JB721TiersHookStore` is the compact storage and validation backend that defines most tier semantics. The deployers package that behavior for existing projects or one-shot launches. The repo composes `nana-core-v6` rather than replacing terminal, controller, or surplus accounting.
 
-## Main Components
+## Core Invariants
 
-| 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 |
+- Tier ordering, category ordering, and tier IDs are part of storage semantics.
+- Original configured tier price drives cash-out weight; discounts affect mint price, not reclaim weight.
+- Reserve frequency and owner-mint settings must not combine into duplicate mint authority.
+- Pending reserves count in supply-sensitive logic before reserve tokens are lazily minted.
+- Preview behavior must stay aligned with live mint and cash-out behavior.
+- Tier splits can reduce the fungible-token mint weight before terminal settlement unless `issueTokensForSplits` is enabled.
+- If `useDataHookForCashOut` is enabled, NFT cash-out semantics intentionally displace fungible-token cash-out behavior.
 
-## Runtime Model
+## Modules
 
-### Payment Path
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JB721TiersHook` | Data-hook, pay-hook, and optional cash-out-hook behavior | Project-facing entrypoint |
+| `JB721TiersHookStore` | Tier storage, mint accounting, reserves, validation | Storage-critical |
+| `JB721Hook`, `ERC721` | Shared NFT machinery and metadata plumbing | Base abstractions |
+| `JB721TiersHookDeployer`, `JB721TiersHookProjectDeployer` | Clone and launch helpers | Deployment surface |
+
+## Trust Boundaries
+
+- Treasury accounting, controller semantics, and permissions live in `nana-core-v6`.
+- Resolver contracts such as Banny are outside this repo and are part of the trusted metadata surface when configured.
+- Hook composition order matters when this hook is wrapped by deployers such as `nana-omnichain-deployers-v6`.
+
+## Critical Flows
+
+### Payment
 
 ```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
+  -> data hook decodes metadata and requested tiers
+  -> hook computes mintable tiers, split forwarding, beneficiary resolution, and leftover value
   -> terminal settles the payment into the project
-  -> pay hook mints NFTs and stores any remaining value as credits when allowed
+  -> post-settlement pay hook mints NFTs and may store remaining value as credits
 ```
 
-### Reserve Path
+### Reserve Minting
 
 ```text
-tier purchases accumulate reserve entitlement
-  -> reserves are minted lazily via explicit reserve-mint calls
+tier purchases
+  -> accumulate reserve entitlement
+  -> reserve-mint call later realizes those pending reserve tokens
 ```
 
-### 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
+  -> data hook overrides fungible-token cash-out inputs when enabled
+  -> terminal settles the cash out using NFT-derived weight
+  -> post-settlement cash-out hook burns the specified NFTs
+  -> reclaim value is derived from the tier's original configured price
 ```
 
-## Critical Invariants
+## Accounting Model
 
-- 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.
+The repo owns tier accounting, reserve accounting, credit accounting, and NFT-specific cash-out inputs. It also owns the mapping from hook metadata to NFT mint and burn side effects after terminal settlement. It does not own the canonical treasury ledger, which remains in `nana-core-v6`.
 
-## Where Complexity Lives
+## Security Model
 
-- 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.
+- Store layout changes have repo-wide blast radius because many downstream packages assume stable tier semantics.
+- Metadata decoding is part of economic correctness because it chooses tiers, credits, and cash-out behavior.
+- Terminal authorization in the base hook is part of the trust model; arbitrary callers must not be able to trigger pay or cash-out hooks.
+- Initialization is one-time and ends by transferring ownership to the initializer. Clone deployers and launch flows depend on that handoff being preserved.
+- Reserve math and supply math must be reviewed together.
 
-## Dependencies
+## Safe Change Guide
 
-- `nana-core-v6` hooks, permissions, controller, and terminal surfaces
-- Optional token URI resolvers such as `banny-retail-v6` and `defifa`
+- Treat store changes as ecosystem-wide changes.
+- Keep previews aligned with state-changing behavior.
+- If you change split behavior, re-check both NFT mint side effects and the fungible-token weight returned to the terminal.
+- When adding metadata fields or flags, update wrapper deployers and downstream integrations in the same change set.
+- If reserve logic changes, re-check supply math, reserve minting, and cash-out denominators together.
 
-## Safe Change Guide
+## Source Map
 
-- 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.
+- `src/JB721TiersHook.sol`
+- `src/JB721TiersHookStore.sol`
+- `src/JB721TiersHookDeployer.sol`
+- `src/JB721TiersHookProjectDeployer.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 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.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - let users mint tiers more cheaply than intended
@@ -26,7 +26,13 @@ In scope:
 
 This repo is depended on by Defifa, Croptop, Banny, Revnets, and omnichain deployers. Bugs here often have ecosystem-wide blast radius.
 
-## System Model
+## Start Here
+
+1. `src/JB721TiersHookStore.sol`
+2. `src/JB721TiersHook.sol`
+3. `src/JB721TiersHookDeployer.sol` and `src/JB721TiersHookProjectDeployer.sol`
+
+## Security Model
 
 The hook can act as:
 - a data hook for payment and cash-out accounting inputs
@@ -45,6 +51,22 @@ The most important design subtlety is that this repo affects both:
 
 That combination is why small-looking mistakes here often become ecosystem-wide economic bugs.
 
+## Roles And Privileges
+
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Project authority | Adjust tiers, discounts, and resolver setup | Must not break supply, ordering, or accounting assumptions |
+| Hook instance | Mint, burn, and compute accounting inputs | Must stay isolated from other hook instances |
+| Store contract | Hold shared tier state | Must not leak or corrupt cross-project data |
+| Token URI resolver | Supply metadata only | Must not become a hidden control surface |
+
+## Integration Assumptions
+
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-core-v6` | Payment and cash-out semantics remain coherent | Downstream economic routing becomes unsafe |
+| Split recipients and hooks | Failures are handled in bounded ways | Mint accounting and treasury routing desync |
+
 ## Critical Invariants
 
 1. Supply caps hold
@@ -68,21 +90,7 @@ Unused payment value that becomes credits must not let a user later mint tiers,
 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.
 
-## Threat Model
-
-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
-
-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
-
-## Hotspots
+## Attack Surfaces
 
 - `beforePayRecordedWith`, `afterPayRecordedWith`, and cash-out hooks
 - credit handling when `payer != beneficiary`
@@ -91,24 +99,19 @@ Especially high-value attacker profiles:
 - `splitPercent` handling and hook distribution fallback behavior
 - deployers that transfer ownership or queue rulesets around the hook
 
-## Sequences Worth Replaying
+Replay these sequences:
+1. cross-currency payment with missing, stale, or asymmetric prices
+2. leftover credits across different payer and beneficiary arrangements
+3. split-routed tier purchases when downstream hooks or terminals fail
+4. reserve-heavy tiers followed by NFT cash-out before reserves are minted
+5. tier adjustment or discount changes around active minting and cash-out windows
 
-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.
+## Accepted Risks Or Behaviors
 
-## Build And Verification
+- Conservative behavior is preferable to optimistic behavior because downstream repos often treat these surfaces as economic truth.
+
+## 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.

package/README.md

@@ -3,18 +3,23 @@
 `@bananapus/721-hook-v6` is the tiered NFT issuance layer for Juicebox V6. It lets a project mint ERC-721s on payment, attach tier-specific pricing and supply rules, mint reserves, and integrate custom token URI resolvers.
 
 Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-This package is the standard NFT hook for the V6 ecosystem. Projects use it to:
+This package is the main shared tiered NFT hook used across the V6 ecosystem. Projects use it to:
 
 - sell fixed-price NFT tiers through Juicebox payments
 - apply tier supply, reserve frequency, voting unit, and discount rules
 - cash out tiers through the Juicebox terminal surface
 - compose custom metadata resolvers such as Banny or Defifa
 
-The deployer and project-deployer helpers make it practical to clone hooks for existing projects or launch a new project with a 721 hook already configured.
+The deployer helps clone hooks for existing projects, and the project-deployer helps launch new projects with a hook already attached.
 
 Use this repo when a project's NFT logic should be part of its payment and cash-out flow. Do not use it for collection-specific rendering or game logic; those belong in higher-level packages like Banny or Defifa.
 
@@ -70,6 +75,14 @@ The shortest useful reading order is:
 
 That split is why UI bugs, economic bugs, and deployment bugs often land in different repos even though users describe them all as "721 hook issues."
 
+## High-Signal Tests
+
+1. `test/E2E/Pay_Mint_Redeem_E2E.t.sol`
+2. `test/invariants/TierLifecycleInvariant.t.sol`
+3. `test/invariants/TieredHookStoreInvariant.t.sol`
+4. `test/audit/CodexSplitCreditsMismatch.t.sol`
+5. `test/regression/ProjectDeployerRulesets.t.sol`
+
 ## Install
 
 ```bash
@@ -121,3 +134,9 @@ script/
 - tier mutations after launch are powerful and should be permissioned carefully
 
 When people say "the 721 hook," they often mean three different things: the hook contract, the store, and the metadata resolver plugged into it. Audits and integrations should separate those concerns.
+
+## For AI Agents
+
+- Separate hook behavior, store behavior, and resolver behavior in your explanation.
+- Read the store invariants and end-to-end pay/mint/redeem tests before summarizing lifecycle guarantees.
+- If metadata or rendering behavior is project-specific, move to the downstream resolver repo.

package/RISKS.md

@@ -44,8 +44,9 @@ This file focuses on the tiered-NFT accounting, reserve-mint, and cash-out risks
 ## 3. Reentrancy Surface
 
 - **Split hook callbacks (`processSplitWith`).** During `afterPayRecordedWith` -> `_processPayment` -> `distributeAll`, the library calls `split.hook.processSplitWith{value}()` for each split with a hook. This executes arbitrary code. At callback time: NFTs already minted, `payCreditsOf` updated, `remainingSupply` decremented in the store. Reentering `afterPayRecordedWith` requires terminal authentication and processes as an independent payment. All split hook and terminal calls are wrapped in try-catch to prevent a single reverting recipient from bricking all payments to the project. For native token hooks, a revert returns false (ETH stays in the contract and routes to project balance). For ERC20 hooks, tokens are transferred before the callback; a revert still returns true because the tokens have already left the contract. Tested: `TestAuditGaps_Reentrancy` confirms reentrancy is blocked by terminal check.
-- **Split beneficiary ETH sends.** `_sendPayoutToSplit` uses `beneficiary.call{value: amount}("")`. If the beneficiary reverts, the function returns `false` and the failed amount is accumulated separately, then routed to the project's balance after the distribution loop via `addToBalanceOf`. Later split recipients receive only their proportional share, not the failed recipient's share. Does not revert the entire payment.
+- **Split beneficiary ETH sends.** `_sendPayoutToSplit` uses `beneficiary.call{value: amount}("")`. If the beneficiary reverts, the function returns `false` and the failed amount is accumulated separately, then routed toward the project's balance after the distribution loop via `addToBalanceOf`. Later split recipients receive only their proportional share, not the failed recipient's share. This does not revert the entire payment unless the fallback `addToBalanceOf` path also reverts.
 - **Terminal `.pay()` / `.addToBalanceOf()` during split distribution.** For project-targeted splits, the library calls the target project's primary terminal via try-catch. A reverting terminal returns false, routing the funds to the project's balance instead. For ERC20 terminal calls, approval is reset to zero on failure to prevent dangling approvals. The target terminal could call back into the hook, but the hook's state is fully settled (supply, credits, mint state). Reentrancy through this path cannot double-mint or corrupt state.
+- **Split fallback can still strand value if the project terminal rejects leftovers.** `_distributeSingleSplit` tries to route failed split payouts into the source project's primary terminal with `addToBalanceOf`. If that fallback also reverts, the whole hook call reverts with `JB721TiersHookLib_SplitFallbackFailed` after the hook has already received the forwarded funds. For native ETH, that leaves the ETH stranded in the hook. For ERC-20s, approval is reset but the tokens remain in the hook. There is no built-in recovery path.
 - **`afterCashOutRecordedWith` execution order.** Burns tokens via `_burn()` -> `_update()` -> `STORE.tierTransferInfoOfTokenId()` in a loop, then calls `STORE.recordBurn()`. ERC721 `_update` triggers the store's tier balance decrement. Burns go to `address(0)`, so no `onERC721Received` callback.
 - **No `ReentrancyGuard`.** Protection relies on state ordering (all `STORE.record*` calls before external calls), terminal authentication checks, and try-catch wrapping of all external calls in `_sendPayoutToSplit`. `_mint()` uses the non-safe variant, avoiding `onERC721Received` callbacks during minting.
 
@@ -83,6 +84,7 @@ This file focuses on the tiered-NFT accounting, reserve-mint, and cash-out risks
 - **Split group ID encoding.** Composite: `uint256(uint160(hookAddress)) | (tierId << 160)`. Tier IDs are capped at uint16, so no overflow. Splits are permanently coupled to a specific hook address -- migrating to a new hook requires re-creating all split groups.
 - **ERC-20 split distribution pulls from terminal.** `distributeAll` calls `SafeERC20.safeTransferFrom(token, msg.sender, address(this), amount)` to pull ERC-20s from the terminal. Requires the terminal to have granted allowance via its `_beforeTransferTo` pattern. If the terminal's allowance mechanism changes, distribution fails.
 - **Forwarded funds depend on non-empty split metadata.** `_processPayment` only calls `distributeAll` when both `context.forwardedAmount.value != 0` and `context.hookMetadata.length != 0`. If an integration ever forwards funds with empty hook metadata, distribution is skipped and the funds remain in the hook contract with no dedicated rescue path.
+- **Split-fallback success depends on the source project's active terminal.** Failed split payouts are not simply burned or refunded. They are re-routed into the source project's current primary terminal for the forwarded token. If that terminal is unset or rejects `addToBalanceOf`, the call reverts and the hook can retain the funds.
 - **Token URI resolver external calls.** `tokenURI()` and `tiersOf(..., includeResolvedUri=true)` call the resolver if set. A reverting resolver blocks all metadata reads (marketplace/frontend impact, no fund risk).
 
 ## 7. Invariants to Verify
@@ -117,3 +119,7 @@ If the payment currency differs from the tier pricing currency and `PRICES == ad
 ### 8.4 Tiny split allocations can round down to zero recipient amounts
 
 Split metadata is expressed in whole token units after conversion and capping. For very small allocations, each rounded per-tier split amount can become zero even though the overall forwarded amount is still reduced by the capped split total. This is an accepted precision tradeoff for dust-sized payments: integrations should not rely on sub-precision split routing and should expect tiny split allocations to be economically lossy.
+
+### 8.5 Failed split payouts only degrade cleanly if the fallback terminal path works
+
+The hook treats a reverting split hook, beneficiary, or target terminal as a soft failure and attempts to re-route that amount into the source project's balance. That graceful degradation depends on the source project's current primary terminal accepting `addToBalanceOf` for the forwarded token. If that terminal is missing or rejects the call, the transaction reverts after funds have already reached the hook, and the hook can retain those assets without a built-in rescue path.