@bananapus/721-hook-v6 0.0.35 → 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.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## Use This File For
 
 - Use this file when the task involves tiered NFT issuance, reserve minting, voting units, tier splits, or token URI resolver integration for Juicebox projects.
-- Start here, then open the hook, store, deployer, or tests that own the exact behavior you are changing.
+- Start here, then decide whether the bug is in hook runtime logic, store accounting, deployer initialization, or downstream token-URI resolution. This repo spans all four and they are easy to conflate.
 
 ## Read This Next
 
@@ -14,7 +14,8 @@
 | Tier storage and accounting | [`src/JB721TiersHookStore.sol`](./src/JB721TiersHookStore.sol) |
 | Deployment or project launch helpers | [`src/JB721TiersHookDeployer.sol`](./src/JB721TiersHookDeployer.sol), [`src/JB721TiersHookProjectDeployer.sol`](./src/JB721TiersHookProjectDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
 | Shared libraries, interfaces, and resolver surface | [`src/libraries/`](./src/libraries/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/) |
-| Invariants, E2E flows, and regressions | [`test/invariants/`](./test/invariants/), [`test/E2E/`](./test/E2E/), [`test/regression/`](./test/regression/), [`test/TestVotingUnitsLifecycle.t.sol`](./test/TestVotingUnitsLifecycle.t.sol) |
+| Mint, pricing, voting, and checkpoint behavior | [`test/TestVotingUnitsLifecycle.t.sol`](./test/TestVotingUnitsLifecycle.t.sol), [`test/TestCheckpoints.t.sol`](./test/TestCheckpoints.t.sol) |
+| Reentrancy, forks, and pinned edge cases | [`test/TestSafeTransferReentrancy.t.sol`](./test/TestSafeTransferReentrancy.t.sol), [`test/721HookAttacks.t.sol`](./test/721HookAttacks.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
 
 ## Repo Map
 
@@ -37,6 +38,11 @@ Tiered ERC-721 NFT issuance and cash-out hook for Juicebox V6. This repo control
 ## Working Rules
 
 - Start in [`src/JB721TiersHook.sol`](./src/JB721TiersHook.sol) for pay and cash-out behavior, but verify storage-side assumptions in [`src/JB721TiersHookStore.sol`](./src/JB721TiersHookStore.sol) before changing mint, burn, reserve, or supply logic.
+- The store is the source of truth for supply, reserve, removal, and tier-order invariants. Do not “fix” those concepts only in the hook layer.
+- Pending reserves are part of live economics, not deferred bookkeeping. Cash-out denominators and tier availability both depend on them before reserves are minted.
+- Pay credits, overspending protection, and tier split forwarding are economically relevant. Treat them like accounting, not just UX.
 - Treat tier splits, reserve minting, and discounted pricing as treasury-sensitive. Check both runtime code and regression coverage before assuming a change is local.
+- Discounted mint price and cash-out weight are intentionally not the same thing. Free or discounted mints can still carry full tier cash-out weight by design.
+- Changing the default reserve beneficiary is not cosmetic. It can change which tiers have pending reserves and therefore change redemption economics for existing mints.
 - When a task mentions token metadata or rendering, confirm whether the behavior lives in this repo or in an external resolver. Do not over-edit the hook when the real change belongs downstream.
 - When changing deployers or initialization, verify the hook, store, and project-launch path stay aligned. These flows are tightly coupled.

package/USER_JOURNEYS.md

@@ -1,96 +1,191 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
+
+This repo is the standard tiered NFT hook for V6 projects.
+It owns tier issuance, reserve accounting, hook-aware mint and cash-out behavior, and deployer packaging for hook
+clones or hook-shaped project launches. It does not own collection-specific rendering or app-layer policy built on top
+of the hook.
+
+## Primary Actors
 
 - project owners selling or rewarding supporters with tiered NFTs
 - operators managing tier supply, pricing, reserves, and ruleset-aware hook behavior
 - supporters minting or cashing out tier positions through normal Juicebox flows
-- integrators composing custom token URI resolvers on top of the standard 721 hook
+- integrators composing custom token URI resolvers or downstream products on top of the hook
+
+## Key Surfaces
+
+- `JB721TiersHook`: project-facing hook behavior for minting, reserves, metadata, and cash out
+- `JB721TiersHookStore`: tier definitions and accounting backend
+- `JB721TiersHookDeployer`: clone factory for existing projects
+- `JB721TiersHookProjectDeployer`: project-launch packaging for new hook-backed projects
 
 ## Journey 1: Add A Tiered 721 Hook To An Existing Project
 
-**Starting state:** the project already exists in Juicebox and needs tiered NFT issuance without relaunching.
+**Actor:** project owner or deployer.
+
+**Intent:** attach tiered NFT behavior to an existing project without relaunching it.
+
+**Preconditions**
+- the project already exists in Juicebox
+- the owner knows the tier config, reserve behavior, and resolver assumptions it wants
+- the next ruleset metadata can be updated safely
+
+**Main Flow**
+1. Use `JB721TiersHookDeployer` to clone a hook for the project.
+2. Define tier config, reserve behavior, resolver choice, and per-ruleset flags.
+3. Queue or install ruleset metadata that points at the hook.
+4. Future payments can now mint tiers under the configured constraints.
 
-**Success:** a hook clone is deployed, initialized, and attached to the project's ruleset metadata.
+**Failure Modes**
+- the hook is deployed correctly but the ruleset metadata does not actually activate it
+- teams treat the resolver as cosmetic when it is part of the trusted surface
 
-**Flow**
-1. Use `JB721TiersHookDeployer` to clone a hook for the target project.
-2. Define tier config, reserve behavior, token URI resolver, and per-ruleset flags.
-3. Queue or install ruleset metadata that tells the project when the hook should participate in pay and cash-out flows.
-4. Future payments into the project can now mint tiers under the configured constraints.
+**Postconditions**
+- the project has an attached hook and future rulesets can mint tiers under the configured constraints
 
 ## Journey 2: Launch A New Project With A 721 Hook Already Wired In
 
-**Starting state:** the product wants its project treasury and NFT logic created in one operation.
+**Actor:** product team or deployer.
 
-**Success:** the project launches with the hook, terminals, and initial tiers already aligned.
+**Intent:** launch a project whose treasury and tiered NFT logic are aligned from the first ruleset.
 
-**Flow**
-1. Use `JB721TiersHookProjectDeployer` with launch config, rulesets, and hook config.
-2. The deployer launches the project through the core protocol and deploys the hook in the same packaged flow.
-3. The initial ruleset metadata points at the newly created hook so there is no post-launch rewiring gap.
-4. The project starts life as a tiered 721 project instead of becoming one later.
+**Preconditions**
+- the team has launch config, terminal config, and initial tier config ready
+
+**Main Flow**
+1. Use `JB721TiersHookProjectDeployer` with launch and hook config.
+2. Launch the project and deploy the hook in the same packaged flow.
+3. Ensure the first ruleset already points at the created hook.
+4. Start life as a hook-backed project instead of converting later.
+
+**Failure Modes**
+- deployers assume the package is purely convenience and miss the initial ruleset implications
+- launch-time metadata drifts from the actual hook config
+
+**Postconditions**
+- the project launches with tiered NFT logic active from the first ruleset
 
 ## Journey 3: Mint Specific Tiers Through A Payment
 
-**Starting state:** the project has live tiers and the payer knows which tiers they want.
+**Actor:** payer.
 
-**Success:** the treasury receives funds and the beneficiary receives the intended NFT tiers plus any accompanying project-token behavior.
+**Intent:** mint one or more tiers through a normal payment flow.
 
-**Flow**
-1. The payer submits a payment with metadata encoding the desired tier selections.
-2. `JB721TiersHook` validates tier availability, quantity rules, discounts, category constraints, and any ruleset flags affecting minting.
+**Preconditions**
+- the project has live tiers
+- the payer submits metadata encoding the intended tier selections
+
+**Main Flow**
+1. Submit a payment with tier-selection metadata.
+2. `JB721TiersHook` validates availability, quantity rules, discounts, and ruleset flags.
 3. `JB721TiersHookStore` updates supply and reserve accounting.
-4. The hook mints the correct NFTs and the underlying terminal completes treasury accounting.
+4. The hook mints the intended NFTs and the terminal completes treasury accounting.
+
+**Failure Modes**
+- sold-out tiers, malformed metadata, or cross-currency pricing mistakes
+- pay-hook participation flags do not match the user's assumptions
+- split-routing or hook behavior changes what part of the payment actually mints
 
-**Failure cases that matter:** sold-out tiers, bad metadata, cross-currency pricing mistakes, paused pay-hook behavior, and split-routing edge cases when part of the payment should bypass normal minting assumptions.
+**Postconditions**
+- the intended tiers are minted and store accounting reflects the updated supply and reserve state
 
 ## Journey 4: Mint Reserves And Operate Tier Inventory Over Time
 
-**Starting state:** the collection is live and the owner needs to manage what exists for future minters versus reserve recipients.
+**Actor:** owner or authorized operator.
+
+**Intent:** manage tier inventory and reserve behavior after launch.
 
-**Success:** reserves, new tiers, removed tiers, and editable fields evolve without corrupting ownership or supply history.
+**Preconditions**
+- the collection is live
+- the operator has the required permission surfaces to mutate tiers or mint reserves
 
-**Flow**
-1. Authorized operators use the hook's tier-management surfaces to add, remove, or adjust tiers.
-2. Reserve minting uses the configured reserve frequency and reserve beneficiary settings instead of ad hoc treasury actions.
-3. The store keeps historical tier state coherent so existing token IDs continue to resolve correctly.
-4. Downstream products such as Croptop, Banny, and Revnets can continue assuming stable tier semantics.
+**Main Flow**
+1. Use tier-management surfaces to add, remove, or adjust tiers.
+2. Mint reserves through the configured reserve logic.
+3. Let the store preserve historical tier state so old token IDs still resolve correctly.
+4. Keep downstream products assuming stable tier semantics whenever possible.
+
+**Failure Modes**
+- tier mutations surprise downstream products or resolvers
+- reserve accounting is misread as ordinary minting
+
+**Postconditions**
+- live tier inventory and reserve state match the operator's configured collection policy
 
 ## Journey 5: Let Holders Cash Out Tier Positions
 
-**Starting state:** a holder owns one or more NFTs from a hook-enabled project and the active ruleset allows surplus-backed exits.
+**Actor:** holder.
+
+**Intent:** exit a tier position through the project's cash-out path.
 
-**Success:** the holder burns the intended tier exposure and receives the correct reclaim value through the core terminal.
+**Preconditions**
+- the holder owns one or more NFTs from the hook-enabled project
+- the active ruleset allows a surplus-backed exit
 
-**Flow**
-1. The holder calls the project's cash-out path on the terminal.
-2. The hook participates in the cash-out calculation so tier-specific weight and store state are reflected correctly.
-3. The terminal settles reclaim value and the NFT position is burned or otherwise marked as consumed by the exit path.
+**Main Flow**
+1. Call the project's cash-out path on the terminal.
+2. Let the hook participate in cash-out calculation so tier state is reflected.
+3. Burn or consume the tier exposure as required by the exit path.
+4. Receive the reclaim value through the terminal that holds the asset.
 
-**Edge conditions that change user experience:** ERC-20 cash-out surfaces, tier splits, reserve accounting drift, broken downstream terminals, and projects that use the hook for metadata only versus economically binding flows.
+**Failure Modes**
+- the project uses the hook for metadata only and the holder assumes an economic cash-out path exists
+- terminal behavior or reserve drift changes reclaim expectations
+
+**Postconditions**
+- the holder exits the tier position through the hook-aware terminal path or learns that no such economic path is active
 
 ## Journey 6: Compose A Custom Product On Top Of The Standard Hook
 
-**Starting state:** the team wants product-specific rendering or business rules but does not want to fork tier issuance.
+**Actor:** integrator or downstream product team.
+
+**Intent:** build collection-specific behavior without reimplementing hook economics.
+
+**Preconditions**
+- the team wants custom presentation or app-layer logic
+- the team does not want to fork pricing, reserve, and treasury behavior
 
-**Success:** the product resolver or wrapper composes with the hook instead of reimplementing pricing, tier accounting, and treasury logic.
+**Main Flow**
+1. Plug a custom resolver or wrapper into the hook.
+2. Keep collection-specific behavior outside this repo.
+3. Audit hook-store interactions here first, then audit the downstream wrapper.
 
-**Flow**
-1. Plug a custom resolver into the hook for metadata and product-specific presentation.
-2. Keep collection-specific behavior in the downstream repo while leaving pay, reserve, and cash-out semantics in this repo.
-3. Audit hook-store interactions here first, then audit the downstream resolver or wrapper.
+**Failure Modes**
+- downstream products reimplement hook behavior and drift from canonical accounting
+- teams blame the hook for bugs that actually live in the resolver or wrapper
+
+**Postconditions**
+- the custom product reuses canonical hook economics while isolating collection-specific behavior downstream
 
 ## Journey 7: Mint NFTs To The Correct Beneficiary During Cross-Chain Payments
 
-**Starting state:** a sucker pays the project on behalf of a remote user via `payRemote`, and the 721 hook needs to mint NFTs and accrue credits to the real user instead of the sucker contract.
+**Actor:** cross-chain payer or integrator.
+
+**Intent:** preserve the real remote beneficiary when a sucker relays a payment.
+
+**Preconditions**
+- a sucker or relay path pays on behalf of a remote user
+- relay-beneficiary metadata is encoded correctly
+
+**Main Flow**
+1. The sucker calls `terminal.pay()` with relay-beneficiary metadata.
+2. `_mintAndUpdateCredits` resolves the relay beneficiary when `payer == beneficiary`.
+3. NFT minting and credit accounting use the resolved remote user.
+
+**Failure Modes**
+- relay metadata is missing or malformed
+- downstream systems attribute NFTs or credits to the sucker instead of the user
+
+**Postconditions**
+- NFT minting and credit accounting attribute the remote payment to the correct beneficiary
 
-**Success:** NFTs mint to and pay credits accrue to the real remote user.
+## Trust Boundaries
 
-**Flow**
-1. The sucker calls `terminal.pay()` with itself as both payer and beneficiary, embedding the real user's address in the `JB_RELAY_BENEFICIARY` metadata key.
-2. `_mintAndUpdateCredits` detects that `payer == beneficiary` and finds relay-beneficiary metadata.
-3. All NFT minting and credit accounting uses the resolved relay beneficiary instead of the sucker address.
+- `JB721TiersHookStore` is the accounting backend and should be treated as part of the same economic surface as the hook
+- custom token URI resolvers are part of the trusted collection surface
+- core terminals remain the source of treasury accounting truth around the hook
 
 ## Hand-Offs
 

package/foundry.toml

@@ -13,6 +13,8 @@ runs = 1024
 depth = 100
 fail_on_revert = false
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

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

package/references/operations.md

@@ -9,7 +9,9 @@
 ## Change Checklist
 
 - If you edit hook initialization, verify deployer config structs and project-launch helpers still encode the same assumptions.
-- If you edit tier config or metadata behavior, inspect [`src/structs/`](../src/structs/) and the corresponding interfaces in [`src/interfaces/`](../src/interfaces/).
+- If you edit tier config or metadata behavior, inspect the corresponding structs and interfaces in `src/structs/` and `src/interfaces/`.
+- If you edit reserve behavior, verify pending reserve counts, default reserve beneficiary semantics, and cash-out denominator effects together.
+- If you edit discount behavior, verify mint price and cash-out weight separately. They are intentionally not the same quantity.
 - If you touch permissions, verify the caller path and permission constants still line up with the downstream ecosystem package that defines them.
 - If you touch URI behavior, confirm whether the issue belongs in this repo or in a downstream resolver contract that the hook calls.
 
@@ -24,5 +26,7 @@
 
 - [`test/Fork.t.sol`](../test/Fork.t.sol) for live-integration assumptions.
 - [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for known edge cases the repo authors considered worth pinning down.
-- [`test/unit/`](../test/unit/) when you need a narrow function-level proof before editing a broad runtime path.
-- [`script/helpers/`](../script/helpers/) when a deployment or launch question is really about config assembly rather than contract behavior.
+- [`test/TestCheckpoints.t.sol`](../test/TestCheckpoints.t.sol) when you need a narrow function-level proof before editing a broad runtime path.
+- [`test/invariants/TierLifecycleInvariant.t.sol`](../test/invariants/TierLifecycleInvariant.t.sol) and [`test/invariants/TieredHookStoreInvariant.t.sol`](../test/invariants/TieredHookStoreInvariant.t.sol) when a local patch may have broken store-level relationships.
+- [`test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol`](../test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol) when reserve-beneficiary or pending-reserve behavior changes.
+- [`script/Deploy.s.sol`](../script/Deploy.s.sol) when a deployment or launch question is really about config assembly rather than contract behavior.

package/references/runtime.md

@@ -22,11 +22,12 @@
 - Discount behavior: price discounts affect mint eligibility but cash-out weight still tracks the original tier price. Do not conflate the two.
 - Voting units: verify whether a tier uses explicit voting units or falls back to price-based voting power before changing governance-facing math.
 - Tier removal and cleanup: removing tiers is not the same as cleaning the sorted tier list. Storage cleanup behavior matters.
+- Default reserve beneficiary changes: they affect which tiers count pending reserves unless a tier-specific beneficiary overrides it. That is an economic change, not just an admin update.
 
 ## Tests To Trust First
 
-- [`test/invariants/`](../test/invariants/) for broad accounting invariants.
-- [`test/E2E/`](../test/E2E/) for launch and end-to-end payment flows.
-- [`test/regression/`](../test/regression/) for previously broken edge cases.
+- [`test/Fork.t.sol`](../test/Fork.t.sol) for launch and live integration flows.
 - [`test/TestVotingUnitsLifecycle.t.sol`](../test/TestVotingUnitsLifecycle.t.sol) for voting-unit lifecycle behavior.
-- [`test/TestSafeTransferReentrancy.t.sol`](../test/TestSafeTransferReentrancy.t.sol) and [`test/721HookAttacks.t.sol`](../test/721HookAttacks.t.sol) for reentrancy and attack-surface checks.
+- [`test/TestCheckpoints.t.sol`](../test/TestCheckpoints.t.sol) for checkpoint/module behavior.
+- [`test/invariants/TierLifecycleInvariant.t.sol`](../test/invariants/TierLifecycleInvariant.t.sol) and [`test/invariants/TieredHookStoreInvariant.t.sol`](../test/invariants/TieredHookStoreInvariant.t.sol) for store-level lifecycle invariants.
+- [`test/TestSafeTransferReentrancy.t.sol`](../test/TestSafeTransferReentrancy.t.sol), [`test/721HookAttacks.t.sol`](../test/721HookAttacks.t.sol), [`test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol`](../test/audit/CodexRetroactiveReserveBeneficiaryDilution.t.sol), and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for reentrancy and attack-surface checks.

package/src/JB721TiersHook.sol

@@ -457,9 +457,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         string calldata baseUri,
         string calldata contractUri,
         IJB721TokenUriResolver tokenUriResolver,
-        // forge-lint: disable-next-line(mixed-case-variable)
         uint256 encodedIPFSUriTierId,
-        // forge-lint: disable-next-line(mixed-case-variable)
         bytes32 encodedIPFSUri
     )
         external

package/src/JB721TiersHookProjectDeployer.sol

@@ -124,7 +124,6 @@ contract JB721TiersHookProjectDeployer is ERC2771Context, JBPermissioned, IJB721
         returns (uint256 rulesetId, IJB721TiersHook hook)
     {
         // Get the project's projects contract.
-        // forge-lint: disable-next-line(mixed-case-variable)
         IJBProjects PROJECTS = DIRECTORY.PROJECTS();
 
         // Enforce permissions.

package/src/JB721TiersHookStore.sol

@@ -66,7 +66,6 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @custom:param hook The 721 contract that the tier belongs to.
     /// @custom:param tierId The ID of the tier to get the encoded IPFS URI of.
     /// @custom:returns The encoded IPFS URI.
-    // forge-lint: disable-next-line(mixed-case-variable)
     mapping(address hook => mapping(uint256 tierId => bytes32)) public override encodedIPFSUriOf;
 
     /// @notice Returns the largest tier ID currently used on the provided 721 contract.
@@ -1344,7 +1343,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @notice Record a new encoded IPFS URI for a tier.
     /// @param tierId The ID of the tier to set the encoded IPFS URI of.
     /// @param encodedIPFSUri The encoded IPFS URI to set for the tier.
-    // forge-lint: disable-next-line(mixed-case-function, mixed-case-variable)
+    // forge-lint: disable-next-line(mixed-case-function)
     function recordSetEncodedIPFSUriOf(uint256 tierId, bytes32 encodedIPFSUri) external override {
         encodedIPFSUriOf[msg.sender][tierId] = encodedIPFSUri;
     }

package/src/abstract/JB721Hook.sol

@@ -49,7 +49,6 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     //*********************************************************************//
 
     /// @notice The ID of the project that this contract is associated with.
-    // forge-lint: disable-next-line(mixed-case-variable)
     uint256 public override PROJECT_ID;
 
     //*********************************************************************//

package/src/interfaces/IJB721TiersHook.sol

@@ -234,9 +234,7 @@ interface IJB721TiersHook is IJB721Hook {
         string calldata baseUri,
         string calldata contractUri,
         IJB721TokenUriResolver tokenUriResolver,
-        // forge-lint: disable-next-line(mixed-case-variable)
         uint256 encodedIPFSUriTierId,
-        // forge-lint: disable-next-line(mixed-case-variable)
         bytes32 encodedIPFSUri
     )
         external;

package/src/interfaces/IJB721TiersHookStore.sol

@@ -247,7 +247,7 @@ interface IJB721TiersHookStore {
     /// @notice Record a new encoded IPFS URI for a tier.
     /// @param tierId The ID of the tier to set the encoded IPFS URI of.
     /// @param encodedIPFSUri The encoded IPFS URI to set for the tier.
-    // forge-lint: disable-next-line(mixed-case-function, mixed-case-variable)
+    // forge-lint: disable-next-line(mixed-case-function)
     function recordSetEncodedIPFSUriOf(uint256 tierId, bytes32 encodedIPFSUri) external;
 
     /// @notice Record a newly set token URI resolver.

package/src/libraries/JB721Constants.sol

@@ -8,6 +8,5 @@ library JB721Constants {
     /// @notice The metadata ID used to identify the 721 beneficiary entry in payment metadata.
     /// @dev When a sucker pays on behalf of a remote user, the real user's address is embedded under this key
     /// so NFTs mint to the correct recipient.
-    // forge-lint: disable-next-line(mixed-case-variable)
     bytes4 public constant BENEFICIARY_METADATA_ID = bytes4(keccak256("JB_721_BENEFICIARY"));
 }

package/src/structs/JB721InitTiersConfig.sol

@@ -8,7 +8,6 @@ import {JB721TierConfig} from "./JB721TierConfig.sol";
 /// @custom:member tiers The tiers to initialize the hook with.
 /// @custom:member currency The currency that the tier prices are denoted in. See `JBPrices`.
 /// @custom:member decimals The number of decimals in the fixed point tier prices.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721InitTiersConfig {
     JB721TierConfig[] tiers;
     uint32 currency;

package/src/structs/JB721Tier.sol

@@ -21,7 +21,6 @@ import {JB721TierFlags} from "./JB721TierFlags.sol";
 /// an NFT from this tier is minted. Out of `JBConstants.SPLITS_TOTAL_PERCENT`.
 /// @custom:member resolvedUri A resolved token URI for NFTs in this tier. Only available if the NFT this tier belongs
 /// to has a resolver.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721Tier {
     uint32 id;
     uint104 price;
@@ -30,7 +29,6 @@ struct JB721Tier {
     uint104 votingUnits;
     uint16 reserveFrequency;
     address reserveBeneficiary;
-    // forge-lint: disable-next-line(mixed-case-variable)
     bytes32 encodedIPFSUri;
     uint24 category;
     uint8 discountPercent;

package/src/structs/JB721TierConfig.sol

@@ -23,14 +23,12 @@ import {JB721TierConfigFlags} from "./JB721TierConfigFlags.sol";
 /// an NFT from this tier is minted. Out of `JBConstants.SPLITS_TOTAL_PERCENT`.
 /// @custom:member splits The splits to use for this tier's split group. These define where the split portion of the
 /// tier's price gets routed when an NFT from this tier is minted.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TierConfig {
     uint104 price;
     uint32 initialSupply;
     uint32 votingUnits;
     uint16 reserveFrequency;
     address reserveBeneficiary;
-    // forge-lint: disable-next-line(mixed-case-variable)
     bytes32 encodedIPFSUri;
     uint24 category;
     uint8 discountPercent;

package/src/structs/JB721TierConfigFlags.sol

@@ -14,7 +14,6 @@ pragma solidity ^0.8.0;
 /// @custom:member cantIncreaseDiscountPercent If the tier cannot have its discount increased.
 /// @custom:member cantBuyWithCredits If true, this tier cannot be purchased using accumulated pay credits. Only fresh
 /// payment value counts toward this tier's price.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TierConfigFlags {
     bool allowOwnerMint;
     bool useReserveBeneficiaryAsDefault;

package/src/structs/JB721TierFlags.sol

@@ -7,7 +7,6 @@ pragma solidity ^0.8.0;
 /// @custom:member cantBeRemoved A boolean indicating whether attempts to remove this tier will revert.
 /// @custom:member cantIncreaseDiscountPercent If the tier cannot have its discount increased.
 /// @custom:member cantBuyWithCredits If true, this tier cannot be purchased using accumulated pay credits.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TierFlags {
     bool allowOwnerMint;
     bool transfersPausable;

package/src/structs/JB721TiersHookFlags.sol

@@ -11,7 +11,6 @@ pragma solidity ^0.8.0;
 /// the NFTs being minted will revert.
 /// @custom:member issueTokensForSplits A boolean indicating whether payers receive token credit for the portion of
 /// their payment that is routed to tier splits. When false (default), weight is reduced proportionally.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TiersHookFlags {
     bool noNewTiersWithReserves;
     bool noNewTiersWithVotes;

package/src/structs/JB721TiersMintReservesConfig.sol

@@ -3,7 +3,6 @@ pragma solidity ^0.8.0;
 
 /// @custom:member tierId The ID of the tier to mint from.
 /// @custom:member count The number of NFTs to mint from that tier.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TiersMintReservesConfig {
     uint32 tierId;
     uint16 count;

package/src/structs/JB721TiersRulesetMetadata.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// @custom:member pauseTransfers A boolean indicating whether NFT transfers are paused during this ruleset.
 /// @custom:member pauseMintPendingReserves A boolean indicating whether pending/outstanding NFT reserves can be minted
 /// during this ruleset.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TiersRulesetMetadata {
     bool pauseTransfers;
     bool pauseMintPendingReserves;

package/src/structs/JB721TiersSetDiscountPercentConfig.sol

@@ -3,7 +3,6 @@ pragma solidity ^0.8.0;
 
 /// @custom:member tierId The ID of the tier to set the discount percent for.
 /// @custom:member discountPercent The discount percent to set for the tier.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JB721TiersSetDiscountPercentConfig {
     uint32 tierId;
     uint16 discountPercent;

package/src/structs/JBBitmapWord.sol

@@ -5,7 +5,6 @@ pragma solidity ^0.8.0;
 /// `JBBitmap` matrix is a "word".
 /// @custom:member The information stored at the index.
 /// @custom:member The index.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBBitmapWord {
     uint256 currentWord;
     uint256 currentDepth;

package/src/structs/JBDeploy721TiersHookConfig.sol

@@ -12,7 +12,6 @@ import {IJB721TokenUriResolver} from "../interfaces/IJB721TokenUriResolver.sol";
 /// @custom:member contractUri The URI where this contract's metadata can be found.
 /// @custom:member tiersConfig The NFT tiers and pricing config to launch the hook with.
 /// @custom:member flags A set of boolean options to configure the hook with.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBDeploy721TiersHookConfig {
     string name;
     string symbol;

package/src/structs/JBLaunchProjectConfig.sol

@@ -10,7 +10,6 @@ import {JBPayDataHookRulesetConfig} from "./JBPayDataHookRulesetConfig.sol";
 /// @custom:member rulesetConfigurations The ruleset configurations to queue.
 /// @custom:member terminalConfigurations The terminal configurations to add for the project.
 /// @custom:member memo A memo to pass along to the emitted event.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBLaunchProjectConfig {
     string projectUri;
     JBPayDataHookRulesetConfig[] rulesetConfigurations;

package/src/structs/JBLaunchRulesetsConfig.sol

@@ -9,7 +9,6 @@ import {JBPayDataHookRulesetConfig} from "./JBPayDataHookRulesetConfig.sol";
 /// @custom:member rulesetConfigurations The ruleset configurations to queue.
 /// @custom:member terminalConfigurations The terminal configurations to add for the project.
 /// @custom:member memo A memo to pass along to the emitted event.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBLaunchRulesetsConfig {
     uint56 projectId;
     JBPayDataHookRulesetConfig[] rulesetConfigurations;

package/src/structs/JBPayDataHookRulesetConfig.sol

@@ -32,7 +32,6 @@ import {JBPayDataHookRulesetMetadata} from "./JBPayDataHookRulesetMetadata.sol";
 /// its balance in each payment terminal while the ruleset is active. Amounts are fixed point numbers using the same
 /// number of decimals as the corresponding terminal. The `payoutLimit` and `surplusAllowance` parameters must fit in
 /// a `uint232`.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBPayDataHookRulesetConfig {
     uint48 mustStartAtOrAfter;
     uint32 duration;

package/src/structs/JBPayDataHookRulesetMetadata.sol

@@ -28,7 +28,6 @@ pragma solidity ^0.8.0;
 /// during
 /// this ruleset.
 /// @custom:member metadata Metadata of the metadata, up to uint8 in size.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBPayDataHookRulesetMetadata {
     uint16 reservedPercent;
     uint16 cashOutTaxRate;

package/src/structs/JBQueueRulesetsConfig.sol

@@ -6,7 +6,6 @@ import {JBPayDataHookRulesetConfig} from "./JBPayDataHookRulesetConfig.sol";
 /// @custom:member projectId The ID of the project to queue rulesets for.
 /// @custom:member rulesetConfigurations The ruleset configurations to queue.
 /// @custom:member memo A memo to pass along to the emitted event.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBQueueRulesetsConfig {
     uint56 projectId;
     JBPayDataHookRulesetConfig[] rulesetConfigurations;

package/src/structs/JBStored721Tier.sol

@@ -13,7 +13,6 @@ pragma solidity ^0.8.0;
 /// purchased.
 /// @custom:member packedBools Packed boolean flags: allowOwnerMint, transfersPausable, useVotingUnits,
 /// cantBeRemoved, cantIncreaseDiscountPercent, cantBuyWithCredits.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBStored721Tier {
     uint104 price;
     uint32 remainingSupply;