@bannynet/core-v6 0.0.11 → 0.0.12

package/ADMINISTRATION.md

@@ -6,40 +6,40 @@ Admin privileges and their scope in banny-retail-v6. The contract (`Banny721Toke
 
 | Role | How Assigned | Scope |
 |------|-------------|-------|
-| **Contract Owner** | Set via constructor `Ownable(owner)` (line 174). 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)` (line 605). | Per-token: decoration, locking |
+| **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)` (line 175). Immutable after deploy. | Meta-transaction relay: `_msgSender()` resolves to the relayed sender |
+| **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 | Line | Guard | What It Does |
-|----------|------|-------|-------------|
-| `setMetadata(description, url, baseUri)` | 1054-1068 | `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)` | 1073-1084 | `onlyOwner` | Sets custom display names for products identified by UPC. Names are stored in `_customProductNameOf` mapping. Can overwrite previously set names. |
-| `setSvgHashesOf(upcs, svgHashes)` | 1119-1134 | `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. |
+| 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 | Line | Guard | What It Does |
-|----------|------|-------|-------------|
-| `setSvgContentsOf(upcs, svgContents)` | 1089-1113 | 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. |
+| 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. |
 
 ### Banny721TokenUriResolver -- NFT-Owner Functions
 
-| Function | Line | Guard | What It Does |
-|----------|------|-------|-------------|
-| `decorateBannyWith(hook, bannyBodyId, backgroundId, outfitIds)` | 969-999 | `_checkIfSenderIsOwner` (line 979) + `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)` | 1005-1019 | `_checkIfSenderIsOwner` (line 1007) | Locks a banny body's outfit for 7 days (`_LOCK_DURATION`). Lock can only be extended, never shortened (`CantAccelerateTheLock`, line 1016). Prevents `decorateBannyWith` during the lock period. |
+| 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. |
 
 ### Banny721TokenUriResolver -- Restricted Receiver
 
-| Function | Line | Guard | What It Does |
-|----------|------|-------|-------------|
-| `onERC721Received(operator, from, tokenId, data)` | 1027-1046 | `operator == address(this)` (line 1043) | Only accepts incoming NFT transfers when the resolver itself initiated the transfer. Rejects all direct user transfers to the resolver contract with `UnauthorizedTransfer`. |
+| 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`. |
 
 ## Asset Management
 
@@ -49,37 +49,48 @@ Admin privileges and their scope in banny-retail-v6. The contract (`Banny721Toke
 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).
 
 **Immutability of stored content:**
-- Once a hash is set for a UPC, it cannot be changed (line 1127: `HashAlreadyStored`).
-- Once content is uploaded for a UPC, it cannot be replaced (line 1097: `ContentsAlreadyStored`).
+- 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.
 
 **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()` (lines 888-902) and cannot be overridden.
+- 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.
 
 **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 (line 177) | Base SVG path for all banny body rendering |
-| `DEFAULT_NECKLACE` | Constructor (line 178) | Default necklace SVG injected when no custom necklace equipped |
-| `DEFAULT_MOUTH` | Constructor (line 179) | Default mouth SVG injected when no custom mouth equipped |
-| `DEFAULT_STANDARD_EYES` | Constructor (line 180) | Default eyes SVG for non-alien bodies |
-| `DEFAULT_ALIEN_EYES` | Constructor (line 181) | Default eyes SVG for alien bodies |
-| `trustedForwarder` | Constructor (line 175) | ERC-2771 forwarder address for meta-transactions |
-| `_LOCK_DURATION` | Constant (line 63) | 7 days -- hardcoded, not configurable |
-| Body color fills | Hardcoded in `_fillsFor()` (lines 661-685) | Color palettes for Alien, Pink, Orange, Original body types |
-| Category IDs | Constants (lines 65-82) | 18 category slots (0-17), hardcoded |
+| `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 |
 
 ## 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 (line 1043) ensures only self-initiated transfers are accepted.
+- **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.

package/ARCHITECTURE.md

@@ -13,6 +13,16 @@ src/
     └── IBanny721TokenUriResolver.sol — Interface for outfit and asset operations
 ```
 
+## UPC System
+
+A UPC (Universal Product Code) is the tier ID from the 721 hook's tier system, used as the primary identifier for every asset type (bodies, backgrounds, outfits). Each tier in the `IJB721TiersHook` has an `id` and a `category` -- the UPC is that `id`.
+
+- **Bodies** (category 0) have hardcoded UPCs with built-in color palettes: Alien (1), Pink (2), Orange (3), Original (4).
+- **Outfits and backgrounds** use arbitrary UPCs assigned when their tiers are created in the 721 hook. Their SVG content is stored on-chain via the hash-then-upload flow described below.
+- **Token IDs** encode the UPC: `tokenId = UPC * 1_000_000_000 + mintNumber`. The resolver recovers the tier (and thus UPC and category) via `tierOfTokenId` from the hook's store.
+
+All asset storage, outfit attachment, and SVG generation are keyed by UPC.
+
 ## Key Operations
 
 ### Asset Storage
@@ -22,7 +32,8 @@ Owner → setSvgHashesOf(upcs, hashes)
 
 Anyone → setSvgContentsOf(upcs, contents)
   → Upload SVG content matching registered hashes
-  → Content validated against hash before storage
+  → Content validated: keccak256(content) must equal stored hash
+  → Content is immutable once stored (cannot be overwritten)
 
 Owner → setProductNames(upcs, names)
   → Register product names for UPCs
@@ -33,7 +44,7 @@ Owner → setProductNames(upcs, names)
 Body Owner → decorateBannyWith(hook, bodyId, backgroundId, outfitIds)
   → Attach outfit and background NFTs to a body NFT
   → Outfit/background NFTs transferred to resolver contract
-  → Previous outfits returned to owner
+  → Previous outfits returned to owner (if transfer fails, retained in attached list)
   → Composite SVG generated from layered components
 
 Body Owner → lockOutfitChangesFor(hook, bodyId)
@@ -45,11 +56,26 @@ Body Owner → lockOutfitChangesFor(hook, bodyId)
 JB721TiersHook → tokenURI(tokenId)
   → Banny721TokenUriResolver.tokenURI(hook, tokenId)
     → Look up body tier and any attached outfits
-    → Compose SVG layers (background → body → outfits)
+    → Compose SVG layers in fixed z-order (back to front):
+        1. Background (if attached)
+        2. Body (with color palette fills from UPC)
+        3. Outfits in category order:
+           Backside(2) → Necklace(3)* → Head(4) → Eyes(5)† →
+           Glasses(6) → Mouth(7)† → Legs(8) → Suit(9) →
+           Suit Bottom(10) → Suit Top(11) → Necklace‡ →
+           Headtop(12) → Hand(13) → Special categories(14-17)
+           (* = default necklace inserted if no custom equipped)
+           († = default inserted if no custom equipped and no full Head)
+           (‡ = custom necklace rendered here, above suit layers)
+    → Wrap in <svg> container (400x400 viewBox)
     → Encode as base64 data URI with JSON metadata
     → Return fully on-chain SVG
 ```
 
+Non-body tokens are shown on a grey mannequin Banny (body fills set to `none`, outline to `#808080`).
+
+For IPFS-backed assets without on-chain SVG content, the resolver falls back to an `<image href="...">` tag referencing the tier's encoded IPFS URI at 400x400 pixels.
+
 ## Dependencies
 - `@bananapus/721-hook-v6` — NFT tier system (IJB721TiersHook, IJB721TokenUriResolver)
 - `@bananapus/core-v6` — Core protocol interfaces
@@ -58,3 +84,15 @@ JB721TiersHook → tokenURI(tokenId)
 - `@rev-net/core-v6` — Revnet integration
 - `@openzeppelin/contracts` — Ownable, ERC2771, ReentrancyGuard, Strings
 - `keccak` — Hashing utilities
+
+## Design Decisions
+
+**Hash-then-upload for SVG storage.** The owner registers a keccak256 hash first (`setSvgHashesOf`, owner-only), then anyone can upload the matching content (`setSvgContentsOf`, permissionless). This separates content approval from upload gas costs -- the owner commits to exactly which artwork is valid, and community members or bots can pay the gas to actually store it. Both hash and content are immutable once set, preventing artwork tampering after mint.
+
+**7-day outfit lock.** `lockOutfitChangesFor` freezes a body's outfit for 7 days (`_LOCK_DURATION`). This exists so that a dressed Banny can be used as a stable visual identity (e.g. a PFP or on-chain avatar) without risk of the outfit changing underneath external references. The lock can be extended but never shortened -- calling it again resets the timer to 7 days from now, and reverts if the existing lock expires later than the new one would.
+
+**UPC as tier ID.** Rather than introducing a separate asset registry, the resolver reuses the 721 hook's tier ID as the universal product code. This means asset identity, pricing, supply caps, and category are all managed by the existing tier system with no additional storage. The resolver is purely a read/compose layer on top of the hook's data.
+
+**Fixed category ordering for outfit layering.** Outfits must be passed in ascending category order (2-17) and only one outfit per category is allowed. This constraint eliminates ambiguity in SVG z-ordering -- the category number directly determines the layer position. It also enables the resolver to insert default accessories (necklace, eyes, mouth) at the correct z-position when no custom one is equipped and no full-head item occludes them.
+
+**Equipped assets travel with the body.** When a body NFT is transferred, all equipped outfits and backgrounds remain attached. The new owner inherits them and can unequip to receive the outfit NFTs. This was chosen over auto-unequip to preserve the dressed Banny as a complete visual unit, but it means sellers should unequip valuable outfits before listing.

package/AUDIT_INSTRUCTIONS.md

@@ -6,12 +6,12 @@ Target: `Banny721TokenUriResolver` -- a single-contract system that manages on-c
 
 | Contract | Lines | Role |
 |----------|-------|------|
-| `Banny721TokenUriResolver` | ~1,404 | Token URI resolver, outfit custody, SVG storage, decoration logic, lock mechanism |
+| `Banny721TokenUriResolver` | ~1,428 | Token URI resolver, outfit custody, SVG storage, decoration logic, lock mechanism |
 | `IBanny721TokenUriResolver` | ~175 | Interface: events, view functions, mutating functions |
 
 Inheritance chain: `Ownable`, `ERC2771Context`, `ReentrancyGuard`, `IJB721TokenUriResolver`, `IBanny721TokenUriResolver`, `IERC721Receiver`.
 
-Compiler: Solidity 0.8.26, Cancun EVM, via-IR optimizer (200 runs).
+Compiler: Solidity ^0.8.26, Cancun EVM, via-IR optimizer (200 runs).
 
 ## Architecture Overview
 
@@ -63,15 +63,15 @@ There are 18 categories (0-17), each representing a layer or slot:
 | 16 | `_SPECIAL_HEAD_CATEGORY` | Special Head | Special outfit slot |
 | 17 | `_SPECIAL_BODY_CATEGORY` | Special Body | Special outfit slot |
 
-Categories 0 and 1 cannot be used as outfits (enforced at line 1275). Outfits must be categories 2-17.
+Categories 0 and 1 cannot be used as outfits (enforced at line 1299). Outfits must be categories 2-17.
 
 ### Conflict Rules
 
 Two conflict rules prevent contradictory outfits:
-1. **Head blocks face pieces**: If category 4 (Head) is equipped, categories 5 (Eyes), 6 (Glasses), 7 (Mouth), and 12 (HeadTop) are rejected (line 1289-1294).
-2. **Suit blocks top/bottom**: If category 9 (Suit) is equipped, categories 10 (SuitBottom) and 11 (SuitTop) are rejected (line 1295-1299).
+1. **Head blocks face pieces**: If category 4 (Head) is equipped, categories 5 (Eyes), 6 (Glasses), 7 (Mouth), and 12 (HeadTop) are rejected (line 1312-1318).
+2. **Suit blocks top/bottom**: If category 9 (Suit) is equipped, categories 10 (SuitBottom) and 11 (SuitTop) are rejected (line 1319-1323).
 
-Outfits must be passed in **ascending category order** (line 1280-1281). No two outfits can share a category.
+Outfits must be passed in **ascending category order** (line 1304-1305). No two outfits can share a category.
 
 ## Outfit Decoration System
 
@@ -80,13 +80,13 @@ Outfits must be passed in **ascending category order** (line 1280-1281). No two
 `decorateBannyWith(hook, bannyBodyId, backgroundId, outfitIds)` is the single entry point for all decoration changes. There is no separate "undress" function -- undressing is accomplished by calling `decorateBannyWith` with an empty `outfitIds` array and `backgroundId = 0`.
 
 The function:
-1. Verifies the caller owns the banny body (line 987).
-2. Verifies the body token is actually category 0 (line 990).
-3. Verifies the body is not locked (line 995).
-4. Delegates background handling to `_decorateBannyWithBackground` (line 1004).
-5. Delegates outfit handling to `_decorateBannyWithOutfits` (line 1007).
+1. Verifies the caller owns the banny body (line 993).
+2. Verifies the body token is actually category 0 (line 996).
+3. Verifies the body is not locked (line 1001).
+4. Delegates background handling to `_decorateBannyWithBackground` (line 1010).
+5. Delegates outfit handling to `_decorateBannyWithOutfits` (line 1013).
 
-### Background Decoration (`_decorateBannyWithBackground`, line 1155)
+### Background Decoration (`_decorateBannyWithBackground`, line 1173)
 
 - If `backgroundId != 0`, the caller must own the background NFT or own the banny body currently using it.
 - The background must be category 1 (`_BACKGROUND_CATEGORY`).
@@ -94,19 +94,19 @@ The function:
 - The old background is returned via `_tryTransferFrom` (silent failure on burned tokens).
 - The new background is transferred into the resolver via `_transferFrom` (reverts on failure).
 
-### Outfit Decoration (`_decorateBannyWithOutfits`, line 1222)
+### Outfit Decoration (`_decorateBannyWithOutfits`, line 1243)
 
 This is the most complex function. It performs a **merge-style iteration** over two arrays: the new `outfitIds` and the previously equipped `previousOutfitIds`.
 
 For each new outfit:
-1. Authorization: caller must own the outfit OR own the banny body currently wearing it (lines 1257-1268).
-2. Category validation: must be 2-17, ascending order, no conflicts (lines 1275-1300).
-3. The inner `while` loop transfers out old outfits up to the current category (lines 1308-1326).
-4. If the outfit is not already worn by this body, state is updated and the outfit is transferred in (lines 1329-1337).
+1. Authorization: caller must own the outfit OR own the banny body currently wearing it (lines 1278-1293).
+2. Category validation: must be 2-17, ascending order, no conflicts (lines 1299-1324).
+3. The inner `while` loop transfers out old outfits up to the current category (lines 1332-1350).
+4. If the outfit is not already worn by this body, state is updated and the outfit is transferred in (lines 1353-1361).
 
-After all new outfits are processed, a second `while` loop (line 1348) transfers out any remaining old outfits.
+After all new outfits are processed, a second `while` loop (line 1372) transfers out any remaining old outfits.
 
-Finally, `_attachedOutfitIdsOf[hook][bannyBodyId]` is overwritten wholesale with the new array (line 1368).
+Finally, `_attachedOutfitIdsOf[hook][bannyBodyId]` is overwritten wholesale with the new array (line 1392).
 
 ## Custody Model
 
@@ -132,8 +132,8 @@ Every outfit NFT held by the resolver must be recoverable by the current owner o
 `lockOutfitChangesFor(hook, bannyBodyId)` locks a body for 7 days (`_LOCK_DURATION = 7 days = 604,800 seconds`). While locked, `decorateBannyWith` reverts with `OutfitChangesLocked`.
 
 Rules:
-- Only the body owner can lock (line 1015).
-- Lock can only be extended, never shortened (line 1024). Attempting to set a shorter lock reverts with `CantAccelerateTheLock`.
+- Only the body owner can lock (line 1021).
+- Lock can only be extended, never shortened (line 1030). Attempting to set a shorter lock reverts with `CantAccelerateTheLock`.
 - Equal-time relocks succeed (the `>` check allows `currentLockedUntil == newLockUntil`).
 - The lock survives body transfers -- a buyer who receives a locked body cannot change outfits until the lock expires.
 - The `outfitLockedUntil` mapping is public and readable by marketplaces.
@@ -144,19 +144,19 @@ Rules:
 
 ### Hash-Then-Reveal Pattern
 
-1. Owner calls `setSvgHashesOf(upcs, svgHashes)` to commit `keccak256` hashes (line 1130). Hashes are write-once per UPC.
-2. Anyone calls `setSvgContentsOf(upcs, svgContents)` to reveal content (line 1100). Content must match the stored hash. Content is write-once per UPC.
-3. If content is not yet uploaded, `_svgOf` falls back to IPFS resolution via `JBIpfsDecoder` (line 936-942).
+1. Owner calls `setSvgHashesOf(upcs, svgHashes)` to commit `keccak256` hashes (line 1138). Hashes are write-once per UPC.
+2. Anyone calls `setSvgContentsOf(upcs, svgContents)` to reveal content (line 1108). Content must match the stored hash. Content is write-once per UPC.
+3. If content is not yet uploaded, `_svgOf` falls back to IPFS resolution via `JBIpfsDecoder` (line 936-949).
 
 ### SVG Composition
 
-`tokenUriOf` (line 200) builds a complete on-chain data URI:
+`tokenUriOf` (line 203) builds a complete on-chain data URI:
 1. For non-body tokens: renders the outfit SVG on a grey mannequin banny.
 2. For body tokens: composes background + body + all outfit layers in category order.
 
 The body SVG uses CSS classes (`.b1`-`.b4`, `.a1`-`.a3`) with color fills specific to each body type (Alien=green, Pink=pink, Orange=orange, Original=yellow).
 
-Default accessories (necklace, eyes, mouth) are injected when no custom outfit occupies that slot. The necklace has special layering: it is stored during iteration but rendered after `_SUIT_TOP_CATEGORY` (line 880-884).
+Default accessories (necklace, eyes, mouth) are injected when no custom outfit occupies that slot. The necklace has special layering: it is stored during iteration but rendered after `_SUIT_TOP_CATEGORY` (line 885-890).
 
 ### SVG Sanitization
 
@@ -174,7 +174,7 @@ If a non-zero forwarder is set, that forwarder contract can append arbitrary sen
 
 ## `onERC721Received` Gate
 
-The resolver implements `IERC721Receiver.onERC721Received` (line 1038) and rejects all incoming transfers unless `operator == address(this)`. This means:
+The resolver implements `IERC721Receiver.onERC721Received` (line 1044) and rejects all incoming transfers unless `operator == address(this)`. This means:
 - Only the resolver itself can send NFTs to itself (via its own `_transferFrom` calls).
 - Users cannot accidentally send NFTs directly to the resolver.
 - If a user sends an NFT via `transferFrom` (not `safeTransferFrom`), the callback is not triggered and the NFT is silently deposited. This is an inherent ERC-721 limitation.
@@ -183,24 +183,24 @@ The resolver implements `IERC721Receiver.onERC721Received` (line 1038) and rejec
 
 ### 1. Outfit Authorization Logic (CRITICAL)
 
-File: `src/Banny721TokenUriResolver.sol`, lines 1254-1268.
+File: `src/Banny721TokenUriResolver.sol`, lines 1278-1293.
 
 The authorization check for outfits allows the caller to use an outfit if they either own it directly or own the banny body currently wearing it. A historical bug (L18, now fixed) allowed `ownerOf(0)` bypass when `wearerOf` returned 0 for unworn outfits. Verify the current fix is sound:
-- Line 1262: `if (wearerId == 0) revert` -- ensures unworn outfits require direct ownership.
-- Line 1266: `ownerOf(wearerId)` -- verifies caller owns the body wearing the outfit.
+- Line 1283: `if (wearerId == 0) revert` -- ensures unworn outfits require direct ownership.
+- Line 1287: `ownerOf(wearerId)` -- verifies caller owns the body wearing the outfit.
 
 Look for: any path where an attacker can pass authorization without actually owning the outfit or the body wearing it.
 
 ### 2. Merge Iteration in `_decorateBannyWithOutfits` (HIGH)
 
-Lines 1250-1368. The merge between new `outfitIds` and `previousOutfitIds` is complex. The inner `while` loop advances through previous outfits, transferring them out. The second `while` loop (line 1348) handles remaining previous outfits.
+Lines 1271-1392. The merge between new `outfitIds` and `previousOutfitIds` is complex. The inner `while` loop advances through previous outfits, transferring them out. The second `while` loop (line 1372) handles remaining previous outfits.
 
 Look for:
 - Off-by-one errors in the `previousOutfitIndex` counter.
 - Skipped outfits that should be returned.
 - Double-transfer of outfits (both in the inner while and the tail while).
 - Removed-tier outfits (category=0) causing infinite loops or skipped entries.
-- The `_isInArray` check at line 1352 preventing outfits in the new set from being transferred out.
+- The `_isInArray` check at line 1376 preventing outfits in the new set from being transferred out.
 
 ### 3. Custody Accounting Consistency (HIGH)
 
@@ -211,11 +211,11 @@ These four mappings must remain consistent. After every `decorateBannyWith` call
 - The background in `_attachedBackgroundIdOf[hook][bodyId]` should have `_userOf[hook][backgroundId] == bodyId`.
 - Every outfit/background held by the resolver should be tracked in these mappings.
 
-**Note**: `_attachedOutfitIdsOf` is overwritten wholesale at line 1368, but `_wearerOf` is only set for *new* outfits at line 1331. Outfits that were already worn by this body retain their `_wearerOf` entry from the previous call. Verify this does not cause stale state.
+**Note**: `_attachedOutfitIdsOf` is overwritten wholesale at line 1392, but `_wearerOf` is only set for *new* outfits at line 1355. Outfits that were already worn by this body retain their `_wearerOf` entry from the previous call. Verify this does not cause stale state.
 
 ### 4. `_tryTransferFrom` Silent Failures (MEDIUM)
 
-Line 1390-1393. When returning old outfits, transfer failures are silently caught. This is intentional (handles burned tokens) but could mask real bugs.
+Line 1424-1428. When returning old outfits, transfer failures are silently caught. This is intentional (handles burned tokens) but could mask real bugs.
 
 Look for: scenarios where `_tryTransferFrom` silently fails but the state mappings (`_wearerOf`, `_attachedOutfitIdsOf`) have already been updated, causing an outfit to be "lost" -- not held by the resolver, not returned to the owner, but still tracked as worn.
 
@@ -227,13 +227,13 @@ Verify: a malicious hook cannot affect outfits custodied from a different (legit
 
 ### 6. CEI Ordering in Background Replacement (MEDIUM)
 
-`_decorateBannyWithBackground` (lines 1192-1203) updates state before transfers. Verify:
-- `_attachedBackgroundIdOf` and `_userOf` are updated at lines 1192-1193 before the try-transfer at line 1197 and the incoming transfer at line 1202.
-- No reachable state where a reentrancy callback during the safeTransferFrom at line 1202 could observe inconsistent state.
+`_decorateBannyWithBackground` (lines 1212-1224) updates state before transfers. Verify:
+- `_attachedBackgroundIdOf` and `_userOf` are updated at lines 1213-1214 before the try-transfer at line 1218 and the incoming transfer at line 1223.
+- No reachable state where a reentrancy callback during the safeTransferFrom at line 1223 could observe inconsistent state.
 
 ### 7. SVG Content Safety (LOW)
 
-SVG content is stored verbatim. While this is a view-function-only concern, verify that the encoding in `_encodeTokenUri` (line 622) cannot produce malformed JSON that breaks parsers. Specifically check for unescaped characters in `svgDescription`, `svgExternalUrl`, and custom product names injected into the JSON.
+SVG content is stored verbatim. While this is a view-function-only concern, verify that the encoding in `_encodeTokenUri` (line 628) cannot produce malformed JSON that breaks parsers. Specifically check for unescaped characters in `svgDescription`, `svgExternalUrl`, and custom product names injected into the JSON.
 
 ## Key Invariants to Test
 
@@ -266,7 +266,7 @@ RPC_ETHEREUM_MAINNET=<your-rpc-url> forge test --match-path test/Fork.t.sol -vvv
 forge test --gas-report
 ```
 
-**Test suite**: 11 test files, ~130+ tests.
+**Test suite**: 14 test files, ~230+ tests.
 
 | File | Purpose |
 |------|---------|
@@ -281,10 +281,13 @@ forge test --gas-report
 | `regression/MsgSenderEvents.t.sol` | ERC-2771 event correctness |
 | `regression/BurnedTokenCheck.t.sol` | Burned token handling |
 | `regression/ClearMetadata.t.sol` | Metadata clearing |
+| `OutfitTransferLifecycle.t.sol` | Outfit transfer lifecycle flows |
+| `TestAuditGaps.sol` | Audit gap coverage: ERC-2771 meta-transaction flows (forwarder relay, spoofing prevention, owner-only relay), SVG rendering edge cases (special characters, script tags, unicode, long content, JSON-breaking chars), SVG composition validation (default decorations, alien vs standard eyes, background inclusion/exclusion) |
+| `TestQALastMile.t.sol` | QA last-mile edge cases |
 
 **Untested areas** (potential audit additions):
-- Meta-transaction flows with a real forwarder (all tests use `address(0)`).
-- SVG content containing special characters or potential injection payloads.
+- Meta-transaction flows with a real forwarder (basic coverage exists in TestAuditGaps.sol; advanced scenarios with a real forwarder remain untested -- all tests use `address(0)`).
+- SVG content containing special characters or potential injection payloads (basic coverage exists in TestAuditGaps.sol for script tags, unicode, JSON-breaking chars, and long content; advanced payloads remain untested).
 - Gas consumption for `tokenUriOf` with maximum outfit count.
 - Ownership transfer of the resolver (`transferOwnership`) and continued admin access.
 - Product name overwriting (no write-once protection on `_customProductNameOf`).
@@ -325,3 +328,27 @@ The resolver makes external calls to the `hook` and its `STORE()` but does not c
 | `UnrecognizedBackground` | Token is not category 1 |
 | `UnrecognizedCategory` | Outfit category not in 2-17 range |
 | `UnrecognizedProduct` | Body UPC not 1-4 (Alien/Pink/Orange/Original) |
+
+## How to Report Findings
+
+For each finding:
+
+1. **Title** -- one line, starts with severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **Affected contract(s)** -- exact file path and line numbers
+3. **Description** -- what is wrong, in plain language
+4. **Trigger sequence** -- step-by-step, minimal steps to reproduce
+5. **Impact** -- what an attacker gains, what a user loses
+6. **Proof** -- code trace or Foundry test
+7. **Fix** -- minimal code change
+
+**Severity guide:**
+- **CRITICAL**: Permanent NFT custody loss, unauthorized outfit theft.
+- **HIGH**: Conditional NFT loss, authorization bypass, broken custody invariant.
+- **MEDIUM**: State inconsistency without fund loss, griefing that locks outfits.
+- **LOW**: Cosmetic SVG issues, informational, edge-case-only.
+
+## Previous Audit Findings
+
+| ID | Severity | Status | Description |
+|----|----------|--------|-------------|
+| L18 | HIGH | FIXED | `ownerOf(0)` bypass in outfit authorization. When `wearerOf` returned 0 for unworn outfits, `hook.ownerOf(0)` could succeed for some hooks, allowing unauthorized outfit use. Fixed by adding `if (wearerId == 0) revert` guard at line 1283. Regression test in `DecorateFlow.t.sol`. |

package/CHANGE_LOG.md

@@ -2,13 +2,21 @@
 
 This document describes all changes between `banny-retail` (v5) and `banny-retail-v6` (v6).
 
+## Summary
+
+- **Key bug fixes**: Default eyes incorrectly selected based on outfit UPC instead of body UPC; decoration operations blocked when a previously-equipped item was burned/removed.
+- **Fault-tolerant transfers**: New `_tryTransferFrom()` wraps returns of previously-equipped items in try-catch — a burned or removed outfit no longer blocks the entire `decorateBannyWith()` operation.
+- **Richer metadata**: `setSvgBaseUri()` replaced by `setMetadata()` which sets description, external URL, and base URI together. Token JSON `description` and `external_url` are now dynamic.
+- **Body category validation**: `decorateBannyWith()` now verifies the `bannyBodyId` actually belongs to a body-category tier before proceeding.
+- **Batch setter safety**: Array length mismatch checks added to `setProductNames()`, `setSvgContentsOf()`, and `setSvgHashesOf()`.
+
 ---
 
 ## 1. Breaking Changes
 
 ### Solidity Version Bump
 - **v5:** `pragma solidity 0.8.23;`
-- **v6:** `pragma solidity 0.8.26;`
+- **v6:** `pragma solidity ^0.8.26;`
 
 ### Dependency Imports Updated
 All `@bananapus/721-hook-v5` imports replaced with `@bananapus/721-hook-v6`:
@@ -46,11 +54,20 @@ All `@bananapus/721-hook-v5` imports replaced with `@bananapus/721-hook-v6`:
 - **v6 adds:** A check that the `bannyBodyId` actually belongs to a body-category tier (`_BODY_CATEGORY == 0`). If not, reverts with `Banny721TokenUriResolver_BannyBodyNotBodyCategory()`.
 - **v5:** No such check existed; any token ID could be passed as a banny body.
 
-### `_tryTransferFrom()` -- Fault-Tolerant Transfers
-- **v6 adds:** `_tryTransferFrom(address hook, address from, address to, uint256 assetId)` -- wraps `safeTransferFrom` in a try-catch, silently succeeding if the transfer fails (e.g., if the token was burned or its tier removed).
+### `_tryTransferFrom()` -- Fault-Tolerant, Return-Aware Transfers
+- **v6 adds:** `_tryTransferFrom(address hook, address from, address to, uint256 assetId) returns (bool success)` -- wraps `safeTransferFrom` in a try-catch and returns whether the transfer succeeded.
 - Used in `_decorateBannyWithBackground()` and `_decorateBannyWithOutfits()` when returning previously equipped items.
+- When the return transfer fails, **state is preserved** instead of cleared — preventing NFT stranding:
+  - **Backgrounds**: Failed return aborts the entire background change (old background stays attached, new one is not equipped).
+  - **Outfits**: Failed-to-return outfits are retained in the attached list via `_storeOutfitsWithRetained()`.
 - **v5:** Used `_transferFrom()` (which reverts on failure) for all transfers, meaning a single burned/removed outfit could block the entire decoration operation.
 
+> **Why this mattered**: In v5, if a project owner removed a tier that contained an equipped outfit, the Banny body owner could never change decorations again — the `safeTransferFrom` for the removed item would revert, permanently blocking the `decorateBannyWith()` function. This was the most-reported user issue.
+
+### `_storeOutfitsWithRetained()` -- Anti-Stranding Merge
+- **v6 adds:** `_storeOutfitsWithRetained(address hook, uint256 bannyBodyId, uint256[] memory outfitIds, uint256[] memory previousOutfitIds)` -- stores the new outfit array, appending any previously equipped outfits whose return transfer failed (non-zero entries in `previousOutfitIds`).
+- This ensures that NFTs held by the resolver but not successfully returned to the owner remain tracked and recoverable in subsequent `decorateBannyWith` calls.
+
 ### `_isInArray()` Helper
 - **v6 adds:** `_isInArray(uint256 value, uint256[] memory array)` -- checks if a value is present in an array.
 - Used during outfit cleanup to skip outfits being re-equipped rather than transferring them out and back in.
@@ -72,6 +89,8 @@ All `@bananapus/721-hook-v5` imports replaced with `@bananapus/721-hook-v6`:
 - **v5 (bug):** `_outfitContentsFor()` used the current outfit's `upc` to decide alien vs. standard default eyes: `if (upc == ALIEN_UPC)`. This checked the UPC of the *outfit being iterated*, not the banny body.
 - **v6 (fix):** `_outfitContentsFor()` now accepts an additional `bodyUpc` parameter and uses `if (bodyUpc == ALIEN_UPC)` to correctly select default eyes based on the banny body type.
 
+> **Why this mattered**: The bug caused alien Bannys to get standard eyes and vice versa when any outfit was equipped, breaking the visual identity of the NFT. The fix ensures default eyes are always selected based on the body type, not whatever outfit happens to be iterated.
+
 ### Improved Background Authorization Logic
 - **v6:** `_decorateBannyWithBackground()` now explicitly checks if an unused background (where `userId == 0`) can only be attached by its owner. In v5, the authorization check `_msgSender() != owner && _msgSender() != IERC721(hook).ownerOf(userOf(hook, backgroundId))` could behave unexpectedly when `userOf()` returned 0 (querying `ownerOf(0)` on the hook).
 
@@ -171,7 +190,7 @@ No struct changes. Both versions use `JB721Tier` from the respective `721-hook`
 
 ### `_bannyBodySvgOf()` Relocated
 - **v5:** Located after `_msgSender()` / `_msgData()` overrides (line ~700).
-- **v6:** Relocated to immediately after `_categoryNameOf()` (line ~532), grouped with other internal view functions.
+- **v6:** Relocated to immediately before `_categoryNameOf()` (line ~538), grouped with other internal view functions.
 
 ### `_contextSuffixLength()` Relocated
 - **v5:** Located before `_bannyBodySvgOf()` (line ~562).
@@ -194,8 +213,8 @@ No struct changes. Both versions use `JB721Tier` from the respective `721-hook`
 - **v6 adds:** `// forge-lint: disable-next-line(mixed-case-variable)` above `DEFAULT_ALIEN_EYES`, `DEFAULT_MOUTH`, `DEFAULT_NECKLACE`, `DEFAULT_STANDARD_EYES`, and `BANNY_BODY`.
 
 ### Import Order Change
-- **v5:** OpenZeppelin imports mixed with `@bananapus` imports.
-- **v6:** OpenZeppelin imports first, then `@bananapus` imports, separated by a blank line.
+- **v5:** `@bananapus` imports first, then OpenZeppelin imports.
+- **v6:** OpenZeppelin imports first, then `@bananapus` imports.
 
 ### Slither Annotations
 - **v6 adds:** `// slither-disable-next-line calls-loop` on several `IERC721(hook).ownerOf()` calls inside loops.
@@ -219,4 +238,6 @@ No struct changes. Both versions use `JB721Tier` from the respective `721-hook`
 | N/A | `_encodeTokenUri()` | Extracted from `tokenUriOf()` |
 | `_outfitContentsFor(hook, outfitIds)` | `_outfitContentsFor(hook, outfitIds, bodyUpc)` | Added `bodyUpc` param (bug fix) |
 | `@bananapus/721-hook-v5` | `@bananapus/721-hook-v6` | Dependency upgrade |
-| `pragma solidity 0.8.23` | `pragma solidity 0.8.26` | Compiler version bump |
+| `pragma solidity 0.8.23` | `pragma solidity ^0.8.26` | Compiler version bump |
+
+> **Cross-repo impact**: The `pricingContext()` return change (3 values → 2) is driven by the upstream `nana-721-hook-v6` `IJB721TiersHook` interface change. The `@bananapus/721-hook-v6` dependency brings in the new tier splits system, though Banny Retail does not use tier splits.

package/README.md

@@ -8,6 +8,8 @@ On-chain composable avatar system for Juicebox 721 collections -- manages Banny
 
 Banny is a composable NFT character system built on top of Juicebox 721 hooks. Each Banny is a body NFT (Alien, Pink, Orange, or Original) that can wear outfit NFTs and sit on a background NFT. The resolver composes these layers into a single SVG image, fully on-chain.
 
+Outfit changes can be locked for 7 days via `lockOutfitChangesFor`. This proves that a Banny's appearance is stable -- useful for PFPs, social displays, or any context where others rely on a Banny looking the way it does right now. While locked, neither the owner nor anyone else can change or remove the body's outfits or background.
+
 ### How It Works
 
 ```
@@ -33,6 +35,41 @@ Banny is a composable NFT character system built on top of Juicebox 721 hooks. E
    → Falls back to IPFS base URI if on-chain content not yet stored
 ```
 
+### Decoration Flow
+
+```mermaid
+sequenceDiagram
+    participant Owner as Body Owner
+    participant Resolver as Banny721TokenUriResolver
+    participant Hook as 721 Hook (NFT Contract)
+
+    Owner->>Resolver: decorateBannyWith(hook, bodyId, bgId, outfitIds)
+    Resolver->>Hook: ownerOf(bodyId) -- verify caller owns body
+    Hook-->>Resolver: owner address
+
+    Note over Resolver: Check body is not locked
+
+    alt Background is changing
+        Resolver->>Hook: transferFrom(owner, resolver, bgId)
+        Note over Resolver: Store bgId as body's background
+        opt Previous background exists
+            Resolver->>Hook: transferFrom(resolver, owner, prevBgId)
+        end
+    end
+
+    loop Each outfit in outfitIds
+        Resolver->>Hook: transferFrom(owner, resolver, outfitId)
+        Note over Resolver: Track outfitId as worn by body
+        opt Previous outfit in same category
+            Resolver->>Hook: transferFrom(resolver, owner, prevOutfitId)
+        end
+    end
+
+    Note over Resolver: tokenURI(bodyId) now renders composed SVG
+    Owner->>Resolver: tokenURI(bodyId)
+    Resolver-->>Owner: base64-encoded JSON with layered SVG
+```
+
 ### Asset Categories
 
 | Category ID | Name | Slot Rules |
@@ -139,9 +176,24 @@ script/
 | `setProductNames` | Contract owner only |
 | `setMetadata` | Contract owner only |
 
+## Supported Chains
+
+Deployed via Sphinx deterministic deployment (`script/Deploy.s.sol`).
+
+| Network | Chain ID |
+|---------|----------|
+| Ethereum | 1 |
+| Optimism | 10 |
+| Base | 8453 |
+| Arbitrum | 42161 |
+| Ethereum Sepolia | 11155111 |
+| Optimism Sepolia | 11155420 |
+| Base Sepolia | 84532 |
+| Arbitrum Sepolia | 421614 |
+
 ## Risks
 
-- **Outfit custody:** Attached outfits and backgrounds are held by the resolver contract. If the contract has a bug in the return logic, assets could be stuck.
+- **Outfit custody:** Attached outfits and backgrounds are held by the resolver contract. If a return transfer fails (e.g., owner is a non-receiver contract), the asset is retained in the attached list rather than stranded — the owner can retry once the issue is resolved. Permanently unrecoverable assets (burned NFTs) create phantom entries in SVG rendering.
 - **7-day lock is fixed.** Cannot be shortened or cancelled once set. The lock duration is hardcoded.
 - **SVG immutability.** Once SVG content is stored on-chain for a UPC, it cannot be changed. A mistake in the content requires deploying a new resolver.
 - **Hash registration is owner-only, but content upload is not.** Anyone can call `setSvgContentsOf` as long as the content matches the registered hash. This is by design for lazy uploads.