@bannynet/core-v6 0.0.22 → 0.0.23

package/ADMINISTRATION.md

@@ -1,136 +1,87 @@
 # Administration
 
-Admin privileges and their scope in banny-retail-v6. The contract (`Banny721TokenUriResolver`) is a single-file system with one admin role (Ownable) and per-token owner privileges.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Resolver-level metadata, SVG asset commitments/uploads, and body-level outfit management for Banny NFTs. |
-| Operators | The resolver owner for global metadata and asset commitments, body owners for decoration actions, and anyone for permissionless SVG uploads that match committed hashes. |
-| Highest-risk actions | Committing the wrong SVG hash, changing global metadata unexpectedly, or locking outfit changes while assets are held custodially in the resolver. |
-| Recovery posture | Write-once SVG commitments cannot be corrected in place. If resolver behavior is wrong, recovery usually means deploying a replacement resolver rather than editing stored content. |
-
-## Routine Operations
+| --- | --- |
+| Scope | `Banny721TokenUriResolver` metadata, SVG commitments, and outfit-state control |
+| Control posture | Global `Ownable` metadata control plus per-body owner control |
+| Highest-risk actions | Wrong SVG hash commitments, incorrect metadata updates, and long outfit locks |
+| Recovery posture | Metadata is editable, but committed hashes, uploaded SVGs, and active locks are not reversible |
 
-- Commit SVG hashes only after verifying the exact UPC-to-content pairing, since the commitment is permanent.
-- Treat metadata and product-name changes as ecosystem-wide display changes that affect every token rendered through the resolver.
-- Remind users that equipped assets are held by the resolver contract until they are unequipped through the supported flow.
-- Use outfit locks deliberately, because they freeze body-level changes for the fixed lock window.
+## Purpose
 
-## One-Way Or High-Risk Actions
+`banny-retail-v6` has a small but real control plane. The resolver owner controls collection-wide metadata and SVG commitments. Body owners control decoration and outfit locks. No admin can rescue equipped NFTs from custody if resolver logic fails.
 
-- `setSvgHashesOf` is write-once per UPC.
-- `setSvgContentsOf` is also write-once once valid content is uploaded.
-- `lockOutfitChangesFor` can only extend the active lock, never shorten it.
-- There is no admin rescue path for custodially held outfit NFTs.
+## Control Model
 
-## Recovery Notes
-
-- If committed artwork is wrong, the practical recovery path is a new resolver or a new UPC strategy, not overwriting the existing entry.
-- If outfits become stuck because of a resolver bug, this contract exposes no owner rescue flow; recovery would require replacement infrastructure rather than an admin intervention.
+- `Banny721TokenUriResolver` is `Ownable`.
+- Global admin power is limited to metadata, product naming, and SVG hash commitments.
+- Actual SVG payload upload is permissionless once the hash is committed.
+- Body owners control decoration and locking for their own bodies.
+- Equipped accessories are held custodially by the resolver while attached.
 
 ## Roles
 
-| Role | How Assigned | Scope |
-|------|-------------|-------|
-| **Contract Owner** | Set via constructor `Ownable(owner)`. Transferable via OpenZeppelin `transferOwnership()`. | Global: SVG asset management, metadata, product naming |
-| **NFT Body Owner** | Whoever holds the banny body token on the JB721TiersHook contract. Checked via `IERC721(hook).ownerOf(bannyBodyId)`. | Per-token: decoration, locking |
-| **NFT Outfit/Background Owner** | Whoever holds the outfit or background token on the hook contract. | Per-token: authorize equipping to a body they own |
-| **Anyone (Permissionless)** | No restriction. | Upload SVG content (if matching hash exists) |
-| **Trusted Forwarder** | Set at construction via `ERC2771Context(trustedForwarder)`. Immutable after deploy. | Meta-transaction relay: `_msgSender()` resolves to the relayed sender |
-
-## Privileged Functions
-
-### Banny721TokenUriResolver -- Owner-Only Functions
-
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `setMetadata(description, url, baseUri)` | `onlyOwner` | Overwrites the token metadata description, external URL, and SVG base URI. All three fields are always written (pass current value to keep, empty string to clear). |
-| `setProductNames(upcs, names)` | `onlyOwner` | Sets custom display names for products identified by UPC. Names are stored in `_customProductNameOf` mapping. Can overwrite previously set names. |
-| `setSvgHashesOf(upcs, svgHashes)` | `onlyOwner` | Commits keccak256 hashes for SVG content keyed by UPC. Each hash can only be set once -- reverts with `HashAlreadyStored` if the UPC already has a hash. This is the gating step that controls which SVG content can later be uploaded permissionlessly. |
-
-### Banny721TokenUriResolver -- Permissionless Functions
-
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `setSvgContentsOf(upcs, svgContents)` | None (anyone) | Stores SVG content for a UPC, but only if: (1) a hash was previously committed by the owner via `setSvgHashesOf`, (2) `keccak256(content) == storedHash`, and (3) content has not already been stored (`ContentsAlreadyStored`). This is the permissionless "lazy upload" mechanism. |
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Resolver owner | `Ownable(owner)` at construction | Global | Can transfer ownership with OpenZeppelin `transferOwnership()` |
+| Body owner | `IERC721(hook).ownerOf(bannyBodyId)` | Per body | Can decorate and lock that body |
+| Anyone | No assignment | Global | Can upload SVG bytes only if they match a committed hash |
 
-### Banny721TokenUriResolver -- NFT-Owner Functions
+## Privileged Surfaces
 
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `decorateBannyWith(hook, bannyBodyId, backgroundId, outfitIds)` | `_checkIfSenderIsOwner` + `nonReentrant` | Equips/unequips outfits and background on a banny body. Caller must own the body token. For each outfit/background: caller must own the asset directly, OR own the banny body that currently wears/uses it. Transfers outfit NFTs into the resolver contract (custodial). |
-| `lockOutfitChangesFor(hook, bannyBodyId)` | `_checkIfSenderIsOwner` | Locks a banny body's outfit for 7 days (`_LOCK_DURATION`). Lock can only be extended, never shortened (`CantAccelerateTheLock`). Prevents `decorateBannyWith` during the lock period. |
+| Contract | Function | Who Can Call | Effect |
+| --- | --- | --- | --- |
+| `Banny721TokenUriResolver` | `setMetadata(...)` | Resolver owner | Changes global description, URL, and base URI |
+| `Banny721TokenUriResolver` | `setProductNames(...)` | Resolver owner | Changes display names for products |
+| `Banny721TokenUriResolver` | `setSvgHashesOf(...)` | Resolver owner | Commits write-once SVG hashes for UPCs |
+| `Banny721TokenUriResolver` | `setSvgContentsOf(...)` | Anyone with matching bytes | Uploads write-once SVG payloads for committed hashes |
+| `Banny721TokenUriResolver` | `decorateBannyWith(...)` | Current body owner | Equips or unequips accessories and updates custody |
+| `Banny721TokenUriResolver` | `lockOutfitChangesFor(...)` | Current body owner | Extends the outfit lock window for that body |
 
-### Banny721TokenUriResolver -- Restricted Receiver
+## Immutable And One-Way
 
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `onERC721Received(operator, from, tokenId, data)` | `operator == address(this)` | Only accepts incoming NFT transfers when the resolver itself initiated the transfer. Rejects all direct user transfers to the resolver contract with `UnauthorizedTransfer`. |
+- SVG hash commitments are write-once.
+- SVG contents are write-once once uploaded.
+- `lockOutfitChangesFor(...)` only extends the active lock; it never shortens it.
+- The lock duration is fixed by the `_LOCK_DURATION` constant.
+- Default art fragments, category semantics, and the trusted forwarder are constructor or code immutables.
 
-## Asset Management
+## Operational Notes
 
-**Who can add SVG assets:**
+- Treat `setSvgHashesOf(...)` like a release gate. A wrong hash usually means new resolver or new UPC strategy, not an edit.
+- Treat `setMetadata(...)` and `setProductNames(...)` as collection-wide display changes.
+- Remind users that equipped assets are in resolver custody while attached.
+- Only lock outfits when temporary non-editability is the intended user experience.
+- Use safe ERC-721 transfer flows when assets are sent into the resolver path; plain `transferFrom` can bypass receiver checks and strand NFTs without a recovery path.
 
-1. The contract **owner** commits SVG hashes via `setSvgHashesOf()`. This is the only gatekeeping step -- only the owner decides which UPCs get artwork.
-2. **Anyone** can then upload the actual SVG content via `setSvgContentsOf()`, provided the content's keccak256 hash matches the owner-committed hash. This is intentional: the owner sets the commitment, and anyone can fulfill it (useful for gas-efficient lazy uploading).
+## Machine Notes
 
-**Immutability of stored content:**
-- Once a hash is set for a UPC, it cannot be changed (`HashAlreadyStored`).
-- Once content is uploaded for a UPC, it cannot be replaced (`ContentsAlreadyStored`).
-- There is no function to delete or modify stored SVG hashes or content.
+- Do not infer a rescue path for equipped assets; there is none in this contract.
+- Treat `src/Banny721TokenUriResolver.sol` as the source of truth for lock extension and write-once SVG behavior.
+- If a committed hash and intended asset bytes differ, stop; the contract does not support overwrite repair.
+- If an asset arrived through non-safe ERC-721 transfer semantics, do not assume the resolver can detect or recover it.
 
-**Product names:**
-- Can be overwritten by the owner at any time via `setProductNames()`. There is no immutability guard on names -- the owner can rename products freely. The built-in names for UPCs 1-4 (Alien, Pink, Orange, Original) are hardcoded in `_productNameOf()` and cannot be overridden.
+## Recovery
 
-**Metadata:**
-- `svgDescription`, `svgExternalUrl`, and `svgBaseUri` can be changed by the owner at any time via `setMetadata()`. All three are always overwritten in a single call.
-
-## Custodial Model
-
-When a user equips an outfit or background on a banny body via `decorateBannyWith()`, the outfit/background NFT is transferred from the user's wallet into the `Banny721TokenUriResolver` contract. The resolver holds these NFTs in custody until the user unequips them (by calling `decorateBannyWith()` again with different outfits).
-
-**Trust assumptions:**
-- Users must trust that the resolver contract's `decorateBannyWith()` function correctly returns NFTs when outfits are changed. There is no separate `withdraw()` or `rescue()` function.
-- The `onERC721Received` guard (`operator == address(this)`) prevents anyone from sending arbitrary NFTs to the resolver. Only self-initiated transfers during `decorateBannyWith()` are accepted.
-- If the banny body NFT is transferred to a new owner while outfits are equipped, the new body owner can unequip and claim the outfit NFTs (the ownership check in `_checkIfSenderIsOwner` is against the current body owner).
-- The `lockOutfitChangesFor()` function can lock outfits for up to 7 days per call (extendable). During a lock, neither the body owner nor anyone else can change the equipped outfits.
-- There is no admin override to rescue stuck outfit NFTs. If a bug in `decorateBannyWith()` prevents unequipping, the outfits remain locked in the resolver permanently.
-
-## Immutable Configuration
-
-The following are set at construction and cannot be changed:
-
-| Property | Set At | Value |
-|----------|--------|-------|
-| `BANNY_BODY` | Constructor | Base SVG path for all banny body rendering |
-| `DEFAULT_NECKLACE` | Constructor | Default necklace SVG injected when no custom necklace equipped |
-| `DEFAULT_MOUTH` | Constructor | Default mouth SVG injected when no custom mouth equipped |
-| `DEFAULT_STANDARD_EYES` | Constructor | Default eyes SVG for non-alien bodies |
-| `DEFAULT_ALIEN_EYES` | Constructor | Default eyes SVG for alien bodies |
-| `trustedForwarder` | Constructor | ERC-2771 forwarder address for meta-transactions |
-| `_LOCK_DURATION` | Constant | 7 days -- hardcoded, not configurable |
-| Body color fills | Hardcoded in `_fillsFor()` | Color palettes for Alien, Pink, Orange, Original body types |
-| Category IDs | Constants | 18 category slots (0-17), hardcoded |
+- Bad metadata can be changed by the owner.
+- Bad SVG commitments or uploaded content cannot be corrected in place.
+- If equipped assets become stuck because of resolver logic, there is no owner rescue path in this contract.
+- If NFTs are stranded through non-safe transfer semantics, this contract does not provide a recovery flow.
 
 ## Admin Boundaries
 
-**What the owner CANNOT do:**
-
-- **Cannot move or steal user NFTs.** The resolver only holds custody of outfit/background NFTs that users voluntarily equip. The `onERC721Received` guard ensures only self-initiated transfers are accepted.
-- **Cannot modify stored SVG content.** Once hash + content are committed, they are permanent. No delete or update function exists.
-- **Cannot modify stored SVG hashes.** Each UPC's hash is write-once.
-- **Cannot change the lock duration.** The 7-day lock is a compile-time constant.
-- **Cannot force-equip or force-unequip outfits.** Only the body NFT's owner can call `decorateBannyWith` and `lockOutfitChangesFor`.
-- **Cannot override hardcoded body names.** UPCs 1-4 always resolve to Alien, Pink, Orange, Original regardless of `_customProductNameOf`.
-- **Cannot change the trusted forwarder.** It is immutable after construction.
-- **Cannot pause the contract.** There is no pause mechanism.
-- **Cannot upgrade the contract.** It is not upgradeable.
+- The owner cannot withdraw equipped user NFTs arbitrarily.
+- The owner cannot overwrite committed hashes or uploaded SVG contents.
+- The owner cannot bypass body-owner checks on decoration or locking.
+- Nobody can shorten an active outfit lock.
+- There is no pause, upgrade, or rescue mechanism.
 
-**What the owner CAN do that affects users:**
+## Source Map
 
-- **Change metadata** (`svgDescription`, `svgExternalUrl`, `svgBaseUri`). This affects how all tokens render in wallets/marketplaces. Clearing `svgBaseUri` would break IPFS-based fallback rendering for products without on-chain SVG content.
-- **Rename products.** Custom product names (UPC > 4) can be changed at any time, altering how NFTs display.
-- **Commit new SVG hashes.** This controls which new artwork can be uploaded, but cannot affect already-stored content.
-- **Transfer ownership.** Via OpenZeppelin `transferOwnership()`, the owner can hand off all admin privileges to a new address (including a multisig, DAO, or malicious actor).
+- `src/Banny721TokenUriResolver.sol`
+- `src/interfaces/IBanny721TokenUriResolver.sol`
+- `script/Deploy.s.sol`
+- `test/TestAuditGaps.sol`
+- `test/TestQALastMile.t.sol`

package/ARCHITECTURE.md

@@ -2,75 +2,100 @@
 
 ## Purpose
 
-`banny-retail-v6` provides the metadata layer for Banny collections. The repo does not mint or own the NFTs itself. Instead, a Juicebox 721 hook points at `Banny721TokenUriResolver`, and the resolver composes body, background, and outfit NFTs into a single on-chain representation.
+`banny-retail-v6` is the Banny-specific metadata and attachment layer for Juicebox 721 collections. It does not mint the NFTs or own treasury logic. It owns attachment custody, outfit-lock rules, and final token rendering.
 
-## Boundaries
+## System Overview
 
-- The repo owns Banny-specific composition logic, asset registration, and outfit locking.
-- `nana-721-hook-v6` still owns token minting, transfers, and collection-level ERC-721 behavior.
-- The resolver is intentionally application-specific. Generic 721 hook behavior should stay in `nana-721-hook-v6`.
+The repo is centered on `Banny721TokenUriResolver`. A 721 hook from `nana-721-hook-v6` points to this resolver for `tokenURI(...)`, while bodies, outfits, and backgrounds remain separate NFTs at the collection layer. The resolver escrows equipped accessories, records which assets are attached to each body, and composes the final SVG and JSON metadata on demand.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `Banny721TokenUriResolver` | Stores SVG content references, tracks equipped assets per body, enforces outfit-lock windows, and returns composed token metadata |
-| `IBanny721TokenUriResolver` | Integration surface for the 721 hook or external tooling |
+- A body can only reference accessories that are currently escrowed by the resolver.
+- Replacing an equipped item must atomically return the old item and escrow the new item.
+- Outfit locks must block both explicit removal and implicit replacement until the lock expires.
+- Equipped assets travel with the body NFT on transfer until the new owner unequips them.
+- Registered SVG payloads must match their pre-registered content hash before they become renderable.
+- Rendering must stay deterministic for the same stored body state.
 
-## Runtime Model
+## Modules
 
-### Decoration
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `Banny721TokenUriResolver` | Escrow, attachment state, lock windows, and metadata rendering | Main contract; application-specific |
+| `IBanny721TokenUriResolver` | External integration surface | Used by hooks and offchain tooling |
+
+## Trust Boundaries
+
+- Minting, ownership transfer, and collection-level ERC-721 semantics live in `nana-721-hook-v6`.
+- This repo is trusted for rendering correctness and custody of equipped assets.
+- Asset content upload is controlled by the registered content owner, but the contract verifies the uploaded bytes against the stored hash.
+
+## Critical Flows
+
+### Decorate
 
 ```text
 body owner
   -> calls decorateBannyWith(...)
-  -> resolver verifies ownership of the body token
-  -> resolver pulls the chosen background and outfit NFTs into escrow
-  -> resolver records which assets are attached to the body
-  -> resolver returns any replaced assets to the owner
+  -> resolver verifies body ownership and lock status
+  -> resolver pulls new accessories into escrow
+  -> resolver updates equipped slots
+  -> resolver returns replaced accessories to the owner
 ```
 
-### Rendering
+### Render
 
 ```text
 tokenURI(bodyId)
-  -> resolve body, background, and equipped outfit slots
-  -> fetch registered SVG fragments
-  -> compose layered SVG
-  -> return base64 JSON metadata
+  -> resolver loads body, background, and equipped slot state
+  -> fetches registered SVG fragments
+  -> composes layered SVG in Banny-specific order
+  -> returns base64 JSON metadata
 ```
 
-### Locking
+### Lock Outfit
 
 ```text
-owner
-  -> lockOutfitChangesFor(...)
-  -> body enters a temporary no-change window
-  -> decoration and removal paths must respect the lock
+body owner
+  -> calls lockOutfitChangesFor(...)
+  -> resolver stores a no-change window
+  -> later decoration and removal paths must respect it
 ```
 
-## Critical Invariants
+## Accounting Model
 
-- A body can only point at assets currently escrowed by the resolver.
-- Slot replacement must be one-for-one. Replacing an equipped item returns the old item instead of orphaning it.
-- Outfit locks must block both direct edits and indirect attempts to reclaim an equipped item through another decoration call.
-- Asset registration is split between hash registration and content upload so content can be trustlessly verified before it is stored on-chain.
+This repo does not own treasury accounting. Its critical state is custody accounting: which NFTs are escrowed, which body they belong to, and when a body is locked against changes.
 
-## Where Complexity Lives
+That custody model uses lazy reconciliation for some stale attachment records. Read paths filter against current ownership and attachment state instead of eagerly rewriting storage on every external transfer.
 
-- Escrow bookkeeping and slot replacement must stay synchronized.
-- Lock enforcement has to cover both explicit removal and implicit replacement paths.
-- SVG composition order is application logic, not a cosmetic detail.
+## Security Model
 
-## Dependencies
-
-- `nana-721-hook-v6` for collection ownership and transfer semantics
-- Juicebox metadata resolver patterns for token URI integration
+- The main failure mode is custody drift between slot state and actual escrowed NFTs.
+- Rendering order is part of application semantics, not cosmetic output.
+- Lazy reconciliation is intentional. Changes that assume attachment arrays are perfectly clean in storage can strand assets or mis-render bodies.
+- Any new asset category adds both a rendering concern and a custody concern.
 
 ## Safe Change Guide
 
-- Put new generic 721 behavior in `nana-721-hook-v6`, not here.
-- Treat slot accounting and escrow transfers as coupled logic. Changing one without the other is how equipment duplication bugs appear.
-- Changes to `tokenURI` should preserve deterministic output for the same body state.
-- If adding new asset categories, verify render order and replacement semantics together.
-- If a change touches both metadata composition and escrow state, test transfer lifecycle behavior, not just rendered output.
+- Keep generic ERC-721 behavior in `nana-721-hook-v6`, not here.
+- Review escrow writes and transfer behavior together whenever changing attachment logic.
+- If transfer or cleanup behavior changes, re-check lazy reconciliation assumptions alongside body-transfer inheritance of equipped assets.
+- If `tokenURI(...)` changes, test stable output for unchanged state and replacement behavior for changed state.
+- If adding slots or asset classes, update rendering order, slot replacement, and lock enforcement in one change.
+
+## Canonical Checks
+
+- accessory escrow, replacement, and decoration flow:
+  `test/DecorateFlow.t.sol`
+- burned-body custody edge cases:
+  `test/audit/BurnedBodyStrandsAssets.t.sol`
+- transfer-path protection against stranded attachments:
+  `test/audit/TryTransferFromStrandsAssets.t.sol`
+
+## Source Map
+
+- `src/Banny721TokenUriResolver.sol`
+- `test/DecorateFlow.t.sol`
+- `test/audit/BurnedBodyStrandsAssets.t.sol`
+- `test/audit/TryTransferFromStrandsAssets.t.sol`
+- `script/Deploy.s.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,87 +1,75 @@
 # Audit Instructions
 
-This repo is the Banny avatar composition layer. Its runtime surface is small, but it directly custodizes NFTs and decides what a Banny body can wear.
+This repo is the Banny avatar composition layer. It does not mint the base NFTs, but it does custody equipped accessories and define the metadata users see.
 
-## Objective
+## Audit Objective
 
 Find issues that:
-- strand body, outfit, or background NFTs in the resolver
-- let the wrong actor equip, unequip, steal, or overwrite accessories
-- bypass outfit-lock timing or freeze users longer than intended
-- return incorrect metadata for bodies, outfits, or backgrounds
-- break category exclusivity or layering assumptions
+- strand outfits or backgrounds in resolver custody
+- let the wrong actor equip, unequip, overwrite, or recover accessories
+- break outfit-lock timing or freeze a body longer than intended
+- return metadata that does not match stored attachment state
+- bypass category or layering constraints
 
 ## Scope
 
 In scope:
 - `src/Banny721TokenUriResolver.sol`
 - `src/interfaces/IBanny721TokenUriResolver.sol`
-- deployment scripts in `script/`
+- all deployment helpers in `script/`
 
-Primary integration assumptions to verify:
-- the resolver is used as a token URI resolver for a `JB721TiersHook`
-- the underlying 721 hook remains the token contract and tier source
-- the resolver temporarily holds accessory NFTs while they are equipped
+## Start Here
 
-## System Model
+1. `src/Banny721TokenUriResolver.sol`
+2. accessory receipt and release paths
+3. deployment wiring in `script/`
 
-The resolver does not mint project NFTs. It:
-- reads tier and token metadata from the attached 721 hook
-- receives outfit and background NFTs through safe transfers
-- records which body currently has which attachments
-- enforces category and conflict rules
-- renders composed metadata and SVG output
+## Security Model
 
-The critical custody model is:
-- body owner controls decoration
-- resolver holds equipped accessories
-- on unequip or invalidation, assets must become recoverable by the rightful owner
+The resolver is an attachment and rendering layer around a `JB721TiersHook` collection.
+- the underlying 721 hook remains the token contract and source of body ownership
+- the resolver temporarily holds accessory NFTs while they are equipped
+- body ownership should be the only authority that changes equipped state
+- accessory contracts may be hostile or malformed, so receipt and release ordering matters
 
-## Critical Invariants
+## Roles And Privileges
 
-1. No asset loss in custody
-Every outfit or background transferred into the resolver must remain attributable to exactly one body or be withdrawable back to the rightful owner.
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Body owner | Equip, unequip, and lock accessories | Must be derived from the current hook-reported owner |
+| Resolver owner | Update metadata and SVG-related admin state | Must not control equipped-state authorization |
+| Accessory NFT contract | Execute callbacks during custody changes | Must not corrupt bookkeeping or steal custody |
 
-2. Body ownership gates decoration
-Only an authorized actor for the body may change its equipped state.
+## Integration Assumptions
 
-3. Category exclusivity
-Conflicting categories must not be equipped together, and categories that are forbidden as accessories must never become equipped through edge paths.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `JB721TiersHook` | Reports authentic body ownership and tier metadata | Unauthorized decoration or incorrect rendering |
+| Accessory ERC-721s | Behave like standard transferable NFTs | Custody or release flows fail unexpectedly |
 
-4. Lock correctness
-`lockOutfitChangesFor` must only prevent changes for the intended body and duration. It must not be bypassable, extendable by unauthorized actors, or accidentally permanent.
+## Critical Invariants
 
-5. Metadata coherence
-`tokenURI` and related rendering helpers must reflect actual equipped state and should not expose stale or impossible compositions.
+1. Every accessory transferred into the resolver remains attributable to one body or is recoverable by the rightful owner.
+2. Only the current body owner or an intended delegate can change that body's equipped state.
+3. Conflicting categories cannot be equipped together, including through replacement or invalidation edge paths.
+4. Outfit-lock state only affects the intended body for the intended duration.
+5. Metadata and SVG generation reflect current state and do not expose impossible combinations.
 
-## Threat Model
+## Attack Surfaces
 
-Prioritize adversaries that:
-- transfer unexpected NFTs into the resolver
-- try to decorate using burned, removed, or mismatched token IDs
-- exploit reentrancy on NFT receipt or withdrawal
-- use invalid category order or duplicate categories to desync state
-- attempt to steal accessories by redecorating around lock windows
+- decoration entrypoints that replace one accessory with another
+- ERC-721 receipt hooks and any path that accepts custody
+- release paths after redecorating, burning, or invalid token state
+- category validation and conflict checks
+- metadata assembly that assumes on-chain assets or tier data remain available
 
-## Hotspots
+## Accepted Risks Or Behaviors
 
-- `decorateBannyWith`: ownership checks, state replacement, and asset movement ordering
-- any path that accepts NFT transfers into resolver custody
-- outfit/background release paths after redecorating, burning, or invalid token states
-- category validation and conflict checks
-- lock timestamp handling
-- token URI generation that assumes on-chain SVG data exists or remains consistent
+- Equipped accessories intentionally follow the body unless they are unequipped first.
+- Preserving attribution on failed transfer-out is safer than dropping custody state.
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-The current test tree emphasizes:
-- attack and regression coverage around stranding and exclusivity
-- decoration lifecycle flows
-- fork and QA scenarios
-
-Prefer proofs that show a body or accessory becoming inaccessible, transferable by the wrong party, or rendered inconsistently with stored state.

package/README.md

@@ -1,9 +1,14 @@
 # Banny Retail
 
-Banny Retail is an on-chain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, sit on a background NFT, and render the full composition as an on-chain SVG and base64 metadata payload.
+Banny Retail is an on-chain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, sit on a background NFT, and resolve to a base64-encoded JSON token URI whose image field contains an on-chain SVG.
 
 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
 
@@ -36,6 +41,36 @@ This repo owns three things:
 
 It does not own mint pricing, tier issuance, or project accounting.
 
+## Read These Files First
+
+1. `src/Banny721TokenUriResolver.sol`
+2. `test/DecorateFlow.t.sol`
+3. `test/OutfitTransferLifecycle.t.sol`
+4. `nana-721-hook-v6/src/JB721TiersHook.sol` for upstream mint and tier behavior
+
+## High-Signal Tests
+
+1. `test/DecorateFlow.t.sol`
+2. `test/OutfitTransferLifecycle.t.sol`
+3. `test/audit/BurnedBodyStrandsAssets.t.sol`
+4. `test/audit/TryTransferFromStrandsAssets.t.sol`
+5. `test/TestQALastMile.t.sol`
+
+## Integration Traps
+
+- the resolver custodies equipped assets, so transfer edge cases matter as much as rendering output
+- transferred bodies carry their equipped assets, so a new body holder can inherit control of those items
+- burned bodies and non-safe transfer patterns can strand expectations around resolver-held assets unless integrations model the attachment lifecycle correctly
+- outfit locks persist across body transfers until expiry, so a new holder can inherit a still-locked body
+- metadata quality depends on lazily uploaded asset payloads, not only on the token state
+- collection logic here assumes a Juicebox 721 hook upstream and should not be read as a generic NFT renderer
+
+## Where State Lives
+
+- equipped outfit and background state live in `Banny721TokenUriResolver`
+- layer rendering and token URI generation live in the same resolver
+- mint pricing, tier inventory, and treasury behavior live upstream in `nana-721-hook-v6`
+
 ## Install
 
 ```bash
@@ -83,4 +118,11 @@ script/
 - attached outfits and backgrounds are custodied by the resolver while equipped
 - outfit locks are fixed-duration and cannot be shortened once set
 - on-chain SVG content is immutable once uploaded for a given registered hash
+- ERC-721 `transferFrom` paths that bypass safe-receive checks can still create asset-tracking surprises around resolver custody
 - rendering quality and metadata correctness depend on the integrity of uploaded SVG assets
+
+## For AI Agents
+
+- Treat this repo as an application-layer resolver, not as the NFT issuance primitive.
+- Start with `Banny721TokenUriResolver` and the lifecycle tests before summarizing attachment behavior.
+- If the question is about mint economics or tier availability, inspect `nana-721-hook-v6` instead of inferring from this repo.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## Use This File For
 
 - Use this file when the task involves Banny outfit attachment, layered SVG rendering, token URI composition, or asset custody and lock behavior.
-- Start here, then open the resolver, scripts, or tests that match the exact rendering or attachment path in question.
+- Start here, then decide whether the issue is custody state, lock semantics, stored SVG content, or final token-URI composition. Those problems often look similar from the outside.
 
 ## Read This Next
 
@@ -11,9 +11,10 @@
 |---|---|
 | Repo overview and user-facing behavior | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Resolver implementation | [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) |
+| Runtime and content-management invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
 | Deployment or scripted drops | [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/Drop1.s.sol`](./script/Drop1.s.sol), [`script/Add.Denver.s.sol`](./script/Add.Denver.s.sol) |
-| Decoration lifecycle and regressions | [`test/DecorateFlow.t.sol`](./test/DecorateFlow.t.sol), [`test/OutfitTransferLifecycle.t.sol`](./test/OutfitTransferLifecycle.t.sol), [`test/regression/`](./test/regression/) |
-| Adversarial or QA coverage | [`test/BannyAttacks.t.sol`](./test/BannyAttacks.t.sol), [`test/TestQALastMile.t.sol`](./test/TestQALastMile.t.sol), [`test/audit/`](./test/audit/) |
+| Decoration lifecycle and custody invariants | [`test/DecorateFlow.t.sol`](./test/DecorateFlow.t.sol), [`test/OutfitTransferLifecycle.t.sol`](./test/OutfitTransferLifecycle.t.sol) |
+| Adversarial, fork, or final QA coverage | [`test/BannyAttacks.t.sol`](./test/BannyAttacks.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol), [`test/TestQALastMile.t.sol`](./test/TestQALastMile.t.sol) |
 
 ## Repo Map
 
@@ -36,5 +37,6 @@ Application-layer token URI resolver for Juicebox 721 collections that lets Bann
 
 - Start in [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) for both rendering and attachment behavior. This repo is mostly one contract with several tightly coupled responsibilities.
 - Treat custody, stale attachment cleanup, and lock timing as high-risk. Rendering bugs are visible, but custody bugs are worse.
+- Equipped outfits and backgrounds travel with the body NFT. Treat that inheritance behavior as intentional before calling it a custody bug.
 - When a task mentions minting, pricing, or terminal accounting, verify that the problem is not actually in the upstream 721 hook repo.
 - If you touch SVG or metadata behavior, check whether the issue is in stored content, rendering composition, or the hook-to-resolver integration point before patching.

package/USER_JOURNEYS.md

@@ -1,78 +1,167 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- Banny collection operators publishing body, outfit, and background tiers
-- collectors minting avatars and equipping accessories
-- teams managing on-chain art payloads and metadata composition
+This repo is the Banny-specific composition and metadata layer on top of a Juicebox 721 collection.
+It owns attachment custody, compatibility rules, outfit locks, and rendered token metadata. It does not own tier
+pricing, treasury accounting, or mint eligibility outside the resolver-specific checks.
+
+## Primary Actors
+
+- collection operators publishing bodies, outfits, backgrounds, and metadata
+- collectors equipping and unequipping avatar pieces
+- auditors reviewing custody, lock, and rendering behavior
+
+## Key Surfaces
+
+- `Banny721TokenUriResolver`: custody, compatibility, locks, and rendered SVG metadata
+- `decorateBannyWith(...)`: equips outfits and a background to a body and returns no-longer-equipped items when possible
+- `lockOutfitChangesFor(...)`: freezes appearance changes for the fixed lock window
+- `setSvgHashesOf(...)` / `setSvgContentsOf(...)`: publish or repair art payloads
+- `setMetadata(...)` / `setProductNames(...)`: update collection metadata and UPC naming
 
 ## Journey 1: Mint A Body, Outfit, And Background Set
 
-**Starting state:** the Banny collection is live through the 721 hook and the relevant tiers exist.
+**Actor:** collector.
+
+**Intent:** acquire the pieces needed to build a composed Banny.
+
+**Preconditions**
+- the Banny collection is live through the 721 hook
+- the required body, outfit, and background tiers exist
 
-**Success:** the collector owns the pieces needed to build a composed avatar.
+**Main Flow**
+1. Mint the body, outfit, and background NFTs through the underlying 721 project.
+2. Keep mint pricing and issuance assumptions anchored in the 721 hook, not this repo.
+3. Move to this resolver only once the user actually owns compatible pieces.
 
-**Flow**
-1. Mint the body, outfit, and background NFTs through the underlying Juicebox 721 project.
-2. Keep pricing, issuance, and treasury assumptions anchored in the 721 hook rather than this resolver.
-3. Treat this repo as the composition layer that activates once the user owns the right pieces.
+**Failure Modes**
+- the wrong tiers are minted or the pieces are not compatible
+- teams misread this repo as the minting or accounting surface
+
+**Postconditions**
+- the user holds the components needed for later composition
+- mint pricing, reserves, and treasury effects still belong to the underlying 721 project rather than this resolver
 
 ## Journey 2: Dress A Banny And Put Accessories Into Resolver Custody
 
-**Starting state:** the collector owns a body plus compatible accessories.
+**Actor:** body owner.
+
+**Intent:** equip a body with a background and outfits so the resolver serves the composed avatar.
 
-**Success:** the chosen outfit and background are attached to the body and the resolver renders the combined look.
+**Preconditions**
+- the caller controls the body and the accessories being equipped
+- no active outfit lock blocks the change
+- the selected pieces are compatible by category and collection rules
 
-**Flow**
+**Main Flow**
 1. Call `decorateBannyWith(...)` for the target body.
-2. `Banny721TokenUriResolver` checks compatibility rules and takes custody of the attached accessory NFTs while they are equipped.
-3. The body's token URI now resolves to a layered SVG and metadata payload reflecting the active composition.
+2. The resolver checks compatibility and diffs old versus new attachments.
+3. Equipped accessories move into resolver custody while attached.
+4. The token URI for the body now reflects the combined SVG and metadata.
+
+**Failure Modes**
+- duplicate outfit categories or incompatible combinations are provided
+- a transfer-back of previously attached items fails, leaving retained custody state that must be recovered later
+- reviewers forget that the resolver, not the user wallet, holds equipped accessories while active
+
+**Postconditions**
+- the body renders with the newly attached composition
+- attached accessories remain in resolver custody until replaced or cleared
 
 ## Journey 3: Lock A Banny's Appearance For A Period
 
-**Starting state:** the collector likes the current look and does not want it changed immediately.
+**Actor:** body owner.
+
+**Intent:** freeze the current appearance for the fixed lock window.
+
+**Preconditions**
+- the body already has a state worth freezing
+- the caller understands the lock is intentionally fixed-duration
 
-**Success:** the avatar's appearance is frozen for the lock window and later equipment changes must wait.
+**Main Flow**
+1. Call `lockOutfitChangesFor(...)`.
+2. The resolver extends the lock for that body.
+3. Future decoration or removal attempts must wait until the lock expires.
 
-**Flow**
-1. Call `lockOutfitChangesFor(...)` on the resolver.
-2. The resolver records the lock period for that body.
-3. Future decorate or removal actions respect the lock until it expires.
+**Failure Modes**
+- a seller locks just before transfer and the buyer cannot re-style immediately
+- integrations fail to surface lock state before listing or sale
+
+**Postconditions**
+- appearance changes are blocked until the lock expires
 
 ## Journey 4: Publish Or Repair On-Chain Art Assets
 
-**Starting state:** the collection's visual payloads are referenced by content hashes but the actual SVG payloads still need to be made available.
+**Actor:** collection operator or art publisher.
+
+**Intent:** make token URIs render complete onchain art.
+
+**Preconditions**
+- the relevant UPCs and content hashes are known
+- the operator understands hashes are the commitment and SVG content must match them exactly
 
-**Success:** token URIs render complete art instead of placeholders or missing layers.
+**Main Flow**
+1. Register hashes with `setSvgHashesOf(...)`.
+2. Upload matching payloads with `setSvgContentsOf(...)`.
+3. Re-check token URI output after publication or repair.
 
-**Flow**
-1. Register the content hashes for bodies, outfits, or backgrounds with `setSvgHashesOf(...)`.
-2. Upload or repair the corresponding SVG payloads with `setSvgContentsOf(...)`.
-3. Re-resolve token URIs to confirm the on-chain composition now renders correctly.
+**Failure Modes**
+- the uploaded SVG does not match the committed hash
+- product names are missing or stale
+- teams assume the 721 hook owns rendered output when this repo does
 
-**Failure cases that matter:** publishing content that does not match the registered hash, forgetting to set product names for new pieces, and assuming the 721 hook owns the art payload when this repo owns the rendered output.
+**Postconditions**
+- token URIs can render the intended onchain art payloads for published UPCs
 
 ## Journey 5: Update Collection Metadata And Product Catalog Entries
 
-**Starting state:** the collection exists, but its descriptive metadata or UPC-to-name catalog needs to change.
+**Actor:** collection operator.
 
-**Success:** token URIs and collection-level presentation reflect the intended description, external URL, base URI, and product naming.
+**Intent:** change collection-level metadata and human-readable product labels.
 
-**Flow**
+**Preconditions**
+- the operator has authority over the resolver metadata surface
+
+**Main Flow**
 1. Update collection metadata with `setMetadata(...)`.
-2. Set or repair product names for the UPCs the renderer should expose with `setProductNames(...)`.
-3. Re-check token URI output so the rendered Banny and its catalog labels agree.
+2. Set or repair UPC names with `setProductNames(...)`.
+3. Re-check a representative token URI so labels and art agree.
+
+**Failure Modes**
+- metadata and SVG state drift apart
+- operators update catalog labels without checking already-minted assets
+
+**Postconditions**
+- collection-level metadata and UPC names line up with the currently published art set
 
 ## Journey 6: Unequip And Recover Custodied Accessories
 
-**Starting state:** a body has attached pieces held by the resolver and the owner wants to rearrange or transfer them.
+**Actor:** body owner.
+
+**Intent:** recover attached accessories from resolver custody.
+
+**Preconditions**
+- the current lock window, if any, has expired
+- the owner understands old pieces may only be returned as part of a later decoration update
+
+**Main Flow**
+1. Replace or clear the equipped items through `decorateBannyWith(...)`.
+2. The resolver attempts to return no-longer-equipped accessories.
+3. Once returned, those NFTs can be transferred or re-used independently.
+
+**Failure Modes**
+- previously equipped pieces remain retained because transfer-back failed
+- burned or otherwise unrecoverable pieces leave cosmetic phantom state until corrected
+
+**Postconditions**
+- no-longer-equipped accessories are either returned to the owner or remain explicitly retained pending recovery
 
-**Success:** the accessories leave resolver custody and can be reused or transferred independently.
+## Trust Boundaries
 
-**Flow**
-1. Remove or replace the equipped items once no lock blocks the change.
-2. The resolver releases custody of the old accessory NFTs.
-3. The owner can now transfer, burn, or re-equip those pieces elsewhere.
+- this repo is trusted for custody of equipped accessories while attached
+- the underlying 721 hook remains the source of mint pricing, tier issuance, and treasury behavior
+- metadata correctness depends on operators publishing the intended SVG hashes and contents
 
 ## Hand-Offs
 

package/foundry.toml

@@ -14,6 +14,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,37 +1,37 @@
 {
-    "name": "@bannynet/core-v6",
-  "version": "0.0.22",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/mejango/banny-retail-v6"
-    },
-    "engines": {
-        "node": ">=20.0.0"
-    },
-    "scripts": {
-        "test": "forge test",
-        "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
-        "generate:migration": "node ./script/outfit_drop/generate-migration.js",
-        "deploy:mainnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
-        "deploy:testnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
-        "deploy:testnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks testnets",
-        "deploy:mainnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks mainnets",
-        "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'banny-core-v6'"
-    },
-    "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.35",
-        "@bananapus/core-v6": "^0.0.34",
-        "@bananapus/permission-ids-v6": "^0.0.17",
-        "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.25",
-        "@croptop/core-v6": "^0.0.33",
-        "@openzeppelin/contracts": "^5.6.1",
-        "@rev-net/core-v6": "^0.0.32",
-        "keccak": "^3.0.4"
-    },
-    "devDependencies": {
-        "@bananapus/address-registry-v6": "^0.0.17",
-        "@sphinx-labs/plugins": "^0.33.3"
-    }
+  "name": "@bannynet/core-v6",
+  "version": "0.0.23",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mejango/banny-retail-v6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "forge test",
+    "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
+    "generate:migration": "node ./script/outfit_drop/generate-migration.js",
+    "deploy:mainnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
+    "deploy:testnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
+    "deploy:testnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks testnets",
+    "deploy:mainnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks mainnets",
+    "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'banny-core-v6'"
+  },
+  "dependencies": {
+    "@bananapus/721-hook-v6": "^0.0.35",
+    "@bananapus/core-v6": "^0.0.34",
+    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/router-terminal-v6": "^0.0.26",
+    "@bananapus/suckers-v6": "^0.0.25",
+    "@croptop/core-v6": "^0.0.33",
+    "@openzeppelin/contracts": "^5.6.1",
+    "@rev-net/core-v6": "^0.0.32",
+    "keccak": "^3.0.4"
+  },
+  "devDependencies": {
+    "@bananapus/address-registry-v6": "^0.0.17",
+    "@sphinx-labs/plugins": "^0.33.3"
+  }
 }

package/references/operations.md

@@ -21,5 +21,5 @@
 
 ## Useful Proof Points
 
-- [`test/audit/`](../test/audit/) for security-sensitive assumptions.
-- [`script/helpers/`](../script/helpers/) when a deployment issue is really a script/config problem.
+- [`test/BannyAttacks.t.sol`](../test/BannyAttacks.t.sol) and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for security-sensitive assumptions.
+- [`script/Drop1.s.sol`](../script/Drop1.s.sol) and [`script/Add.Denver.s.sol`](../script/Add.Denver.s.sol) when a deployment issue is really a script/config problem.

package/references/runtime.md

@@ -24,4 +24,4 @@
 - [`test/DecorateFlow.t.sol`](../test/DecorateFlow.t.sol) for the main equip/unequip lifecycle.
 - [`test/OutfitTransferLifecycle.t.sol`](../test/OutfitTransferLifecycle.t.sol) for custody and return behavior.
 - [`test/BannyAttacks.t.sol`](../test/BannyAttacks.t.sol) for adversarial flows.
-- [`test/TestQALastMile.t.sol`](../test/TestQALastMile.t.sol) and [`test/regression/`](../test/regression/) for pinned edge cases.
+- [`test/Fork.t.sol`](../test/Fork.t.sol), [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol), and [`test/TestQALastMile.t.sol`](../test/TestQALastMile.t.sol) for integration and pinned edge cases.

package/src/Banny721TokenUriResolver.sol

@@ -109,15 +109,10 @@ contract Banny721TokenUriResolver is
     /// @custom:param upc The universal product code that the SVG hash represent.
     mapping(uint256 upc => bytes32) public override svgHashOf;
 
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_ALIEN_EYES;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_MOUTH;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_NECKLACE;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_STANDARD_EYES;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override BANNY_BODY;
 
     //*********************************************************************//