@bananapus/721-hook-v6 0.0.36 → 0.0.38

package/ADMINISTRATION.md

@@ -4,84 +4,84 @@
 
 | Item | Details |
 | --- | --- |
-| 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 |
+| Scope | Tiered NFT hook configuration, tier adjustment, and deployer wiring |
+| Control posture | Mixed project-owner and delegated control |
+| Highest-risk actions | Adjusting tiers, setting discount or metadata behavior, and wiring the wrong hook or resolver |
+| Recovery posture | Some configuration is mutable, but many tier properties are intentionally one-way |
 
 ## Purpose
 
-`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.
+`nana-721-hook-v6` splits control between project-level hook ownership and the tier rules enforced by the store. Many important settings can be changed only in limited ways after launch.
 
 ## Control Model
 
-- 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.
+- project owners or delegates control hook-level configuration
+- tier creation and mutation are permissioned and partially one-way
+- the store trusts the calling hook for its own state namespace
+- deployers package setup, but do not remove the need for runtime review
 
 ## Roles
 
 | 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 |
+| Project owner | `owner()` or project control surface | Per hook | Main authority |
+| Tier delegate | `JBPermissions` grant | Per project | Usually tier, mint, discount, or metadata permissions |
+| Reserve beneficiary | Tier config | Per tier | Receives reserve NFTs |
 
 ## Privileged Surfaces
 
-| 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 |
+- `adjustTiers(...)`
+- `mintFor(...)`
+- `setDiscountPercentOf(...)`
+- `setMetadata(...)`
+- deployer setup and hook ownership transfer paths
+
+## Deployer Permission Model
+
+`JB721TiersHookProjectDeployer` requires callers to hold the correct Juicebox permission for each operation:
+
+| Function | Required Permissions |
+| --- | --- |
+| `launchProjectFor(...)` | None (creates a new project) |
+| `launchRulesetsFor(...)` | `LAUNCH_RULESETS` + `SET_TERMINALS` |
+| `queueRulesetsOf(...)` | `QUEUE_RULESETS` |
+
+Permissions are checked against the project owner via `_requirePermissionFrom`. The deployer calls the controller on the caller's behalf, so the controller sees the deployer as `msg.sender`.
 
 ## Immutable And One-Way
 
-- 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()`.
+- many tier properties are immutable once created
+- removed tiers do not reduce `maxTierIdOf`
+- pool-like mutable rescue does not exist here; bad tier design is often expensive to unwind
 
 ## Operational Notes
 
-- 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.
+- review tier parameters before launch as if they were economic policy
+- treat discount changes and metadata changes as meaningful authority, not cosmetic controls
+- be explicit about whether the hook participates in pay, cash out, or both
+- separate resolver trust from hook and store trust
 
 ## Machine Notes
 
-- 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.
+- do not reason from the hook alone when the bug may live in the store
+- if a resolver is involved, inspect it separately
+- if tier counts are large, re-check gas-sensitive reads and writes before operational changes
 
 ## Recovery
 
-- 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.
+- some mistakes can be corrected through allowed metadata or discount changes
+- many tier-design mistakes are effectively permanent once live
+- deployer mistakes may require a new hook path rather than in-place repair
 
 ## Admin Boundaries
 
-- 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.
+- no one can rewrite immutable tier properties after creation
+- deployers do not bypass runtime permissions after setup
+- resolver behavior cannot fix broken hook accounting
 
 ## 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`
+- `src/JB721TiersHookDeployer.sol`
+- `src/JB721TiersHookProjectDeployer.sol`

package/ARCHITECTURE.md

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

package/AUDIT_INSTRUCTIONS.md

@@ -1,114 +1,74 @@
 # Audit Instructions
 
-This repo is the tiered ERC-721 hook system for Juicebox payments and NFT cash-outs. Audit it as a shared primitive used by many other repos.
+This repo adds tiered NFT issuance and cash-out behavior to Juicebox projects. Audit it as a shared accounting layer whose mistakes can affect many downstream products.
 
 ## Audit Objective
 
 Find issues that:
-- let users mint tiers more cheaply than intended
-- over-mint, under-burn, or miscount reserves, credits, or supply
-- route split funds incorrectly or let split paths distort token issuance
-- let NFT cash-outs reclaim more value than intended
-- corrupt shared store state across different hook instances
+
+- corrupt tier supply, reserve state, or burn accounting
+- misprice cash outs or split routing
+- let permissions or deployer wiring create unsafe lifecycle changes
+- create gas or liveness failures in tier-heavy deployments
+- break trust boundaries between hook, store, and resolver behavior
 
 ## Scope
 
 In scope:
+
 - `src/JB721TiersHook.sol`
 - `src/JB721TiersHookStore.sol`
-- `src/JB721TiersHookDeployer.sol`
-- `src/JB721TiersHookProjectDeployer.sol`
-- `src/abstract/`
-- `src/interfaces/`
-- `src/libraries/`
-- `src/structs/`
+- deployers, libraries, interfaces, and structs under `src/`
 - deployment scripts in `script/`
 
-This repo is depended on by Defifa, Croptop, Banny, Revnets, and omnichain deployers. Bugs here often have ecosystem-wide blast radius.
-
 ## Start Here
 
-1. `src/JB721TiersHookStore.sol`
-2. `src/JB721TiersHook.sol`
-3. `src/JB721TiersHookDeployer.sol` and `src/JB721TiersHookProjectDeployer.sol`
+1. `src/JB721TiersHook.sol`
+2. `src/JB721TiersHookStore.sol`
+3. `src/libraries/JB721TiersHookLib.sol`
 
 ## Security Model
 
-The hook can act as:
-- a data hook for payment and cash-out accounting inputs
-- a pay hook that mints NFTs
-- a cash-out hook that burns NFTs and computes reclaim weight
-
-Key moving parts:
-- `JB721TiersHookStore` holds compact tier state
-- hook instances read and mutate tier data through the store
-- tier prices, discounts, reserves, credits, split percentages, and category order shape mint behavior
-- optional token URI resolvers can override metadata generation
+The hook:
 
-The most important design subtlety is that this repo affects both:
-- NFT state
-- core Juicebox accounting inputs and fulfillment order
-
-That combination is why small-looking mistakes here often become ecosystem-wide economic bugs.
+- mints and burns tiered NFTs through Juicebox flows
+- records tier lifecycle state in a shared store
+- can route split payouts from forwarded value
+- composes with project-specific metadata resolvers
 
 ## 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 |
+| Project authority | Configure tiers, metadata, and minting policy | Must stay inside explicit permission checks |
+| Store caller | Mutate store state in its own namespace | Must not corrupt tier accounting |
+| Resolver | Serve metadata and URI behavior | Must not be confused with accounting truth |
 
 ## 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 |
+| `nana-core-v6` | Terminal auth and pricing behavior are accurate | Pay and cash-out behavior drift |
+| Resolver repo | Metadata reads behave as expected | UI and marketplace behavior break |
 
 ## Critical Invariants
 
-1. Supply caps hold
-No tier may mint beyond its configured total supply once purchases, owner mints, and pending reserves are all considered.
-
-2. Reserve accounting is exact
-Pending reserves must neither disappear nor inflate reclaim denominators beyond what the design intends.
-
-3. Split routing matches accounting
-If part of a mint price is routed to splits, token issuance and treasury accounting must reflect only the intended project portion.
-
-4. Cash-out weight is consistent
-The reclaim value for NFTs must match documented tier economics and must not be manipulable through discounts, credits, cross-currency inputs, or reserve timing.
-
-5. Shared store isolation
-One hook instance must not corrupt or observe mutable state belonging to another project unexpectedly.
-
-6. Credit semantics remain bounded
-Unused payment value that becomes credits must not let a user later mint tiers, trigger splits, or receive project-token issuance on terms they did not actually fund.
-
-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.
+1. Tier supply stays coherent.  
+   Remaining supply, burned counts, and outstanding ownership must reconcile.
+2. Reserve logic stays bounded.  
+   Pending reserves and reserve minting must not over-allocate.
+3. Cash-out weight is consistent.  
+   NFT reclaim value must match the tier model the hook and store intend.
+4. Split and fallback behavior is safe.  
+   Failed split paths must not silently corrupt value or lifecycle state.
 
 ## Attack Surfaces
 
-- `beforePayRecordedWith`, `afterPayRecordedWith`, and cash-out hooks
-- credit handling when `payer != beneficiary`
-- discount logic versus cash-out pricing
-- pending reserve minting and denominator logic
-- `splitPercent` handling and hook distribution fallback behavior
-- deployers that transfer ownership or queue rulesets around the hook
-
-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
-
-## Accepted Risks Or Behaviors
-
-- Conservative behavior is preferable to optimistic behavior because downstream repos often treat these surfaces as economic truth.
+- pay and cash-out hook entrypoints
+- tier add, remove, and clean flows
+- reserve minting
+- split distribution and fallback paths
+- resolver integration
 
 ## Verification
 

package/CHANGELOG.md

@@ -20,6 +20,10 @@ This file describes the verified change from `nana-721-hook-v5` to the current `
 - The repo now carries a dedicated helper library to keep the hook surface manageable and to support the larger v6 feature set.
 - The repo was upgraded from the v5 Solidity baseline to `0.8.28`.
 
+## Local audit remediations
+
+- `JB721TiersHookProjectDeployer.launchRulesetsFor` now checks `LAUNCH_RULESETS` instead of `QUEUE_RULESETS`. The previous check was semantically wrong — launching active rulesets should require the launch permission, not the queue permission.
+
 ## Verified deltas
 
 - `IJB721TiersHook.pricingContext()` changed from a three-value return to `(currency, decimals)`.

package/README.md

@@ -15,15 +15,15 @@ Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 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
+- apply tier supply, reserve frequency, voting units, and discount rules
 - cash out tiers through the Juicebox terminal surface
-- compose custom metadata resolvers such as Banny or Defifa
+- plug in custom metadata resolvers such as Banny or Defifa
 
-The deployer helps clone hooks for existing projects, and the project-deployer helps launch new projects with a hook already attached.
+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.
+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.
 
-The important architectural point is that this repo does not just "mint NFTs on pay." It changes how payment value, tier state, reserves, and cash-out behavior interact.
+This repo does more than "mint NFTs on pay." It changes how payment value, tier state, reserves, and cash-out behavior interact.
 
 ## Key Contracts
 
@@ -41,17 +41,10 @@ Think about the repo in three pieces:
 
 1. `JB721TiersHook` defines behavior at the project edge
 2. `JB721TiersHookStore` is the tier accounting backend
-3. deployers package the hook into reusable project-launch and clone flows
+3. deployers package the hook into reusable launch and clone flows
 
 If a bug affects supply, reserve minting, or tier lookup, it usually lives in the hook-store interaction. If it affects project wiring, it usually lives in the deployer path or in how the hook is attached to rulesets.
 
-The shortest useful reading order is:
-
-1. `JB721TiersHook`
-2. `JB721TiersHookStore`
-3. the relevant deployer
-4. the resolver plugged into the hook, if the project uses one
-
 ## Read These Files First
 
 1. `src/JB721TiersHook.sol`
@@ -62,18 +55,18 @@ The shortest useful reading order is:
 
 ## Integration Traps
 
-- this hook participates in treasury-facing execution, not only metadata. Teams often underestimate the economic implications of tier splits, reserve behavior, and weight adjustments.
-- custom token URI resolvers should be treated as part of the project's trusted surface.
-- adding a 721 hook through a deployer is easy; carrying forward the right ruleset behavior over time is where mistakes happen.
-- projects should be explicit about whether the hook should affect pay, cash out, or only metadata-facing paths.
+- this hook participates in treasury-facing execution, not only metadata
+- custom token URI resolvers should be treated as part of the trusted surface
+- adding a 721 hook through a deployer is easy; carrying the right ruleset behavior forward is where mistakes happen
+- projects should be explicit about whether the hook affects pay, cash out, or only metadata-facing paths
 
 ## Where State Lives
 
-- tier definitions and accounting live primarily in `JB721TiersHookStore`
-- project-facing execution and permission checks live in `JB721TiersHook`
-- collection-specific presentation usually lives outside this repo in a resolver contract
+- tier definitions and accounting: `JB721TiersHookStore`
+- project-facing execution and permission checks: `JB721TiersHook`
+- collection-specific presentation: usually outside this repo in a resolver contract
 
-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."
+That split is why UI bugs, economic bugs, and deployment bugs often land in different repos even when users describe them all as "721 hook issues."
 
 ## High-Signal Tests
 
@@ -104,7 +97,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-Hooks are deployed as clones and typically registered in the address registry. The package is designed to compose with Omnichain, Croptop, Defifa, Banny, and other ecosystem packages that rely on tier-aware NFT issuance.
+Hooks are deployed as clones and typically registered in the address registry. The package is designed to compose with Omnichain, Croptop, Defifa, Banny, and other packages that rely on tier-aware NFT issuance.
 
 ## Repository Layout
 
@@ -128,12 +121,12 @@ script/
 ## Risks And Notes
 
 - tier accounting is sensitive to reserve minting, split routing, and cross-currency normalization
-- tiny split allocations can round down to zero recipient amounts; integrations should not rely on dust-sized split routing
-- custom token URI resolvers are part of the security surface because they define how metadata is served
-- projects need to be deliberate about whether the hook participates in pay, cash-out, or both paths
+- tiny split allocations can round down to zero recipient amounts
+- custom token URI resolvers are part of the security surface
+- projects need to be deliberate about whether the hook participates in pay, cash out, or both paths
 - 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.
+When people say "the 721 hook," they often mean three different things: the hook contract, the store, and the metadata resolver plugged into it.
 
 ## For AI Agents