@bannynet/core-v6 0.0.8 → 0.0.10

package/AUDIT_INSTRUCTIONS.md

@@ -0,0 +1,327 @@
+# banny-retail-v6 -- Audit Instructions
+
+Target: `Banny721TokenUriResolver` -- a single-contract system that manages on-chain SVG-based NFT composition for the Juicebox V6 Banny ecosystem.
+
+## Contract Table
+
+| Contract | Lines | Role |
+|----------|-------|------|
+| `Banny721TokenUriResolver` | ~1,404 | 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).
+
+## Architecture Overview
+
+The resolver serves as both a **token URI generator** and an **NFT custodian**. It is registered as the URI resolver for a `JB721TiersHook` (the Juicebox 721 tier system). When a marketplace or wallet requests `tokenURI()`, the hook delegates to this resolver, which composes layered SVG artwork on-chain.
+
+The resolver does not mint or burn tokens. It holds outfit and background NFTs in custody on behalf of banny body owners, and generates composed SVG output by layering those assets.
+
+```
+JB721TiersHook (the NFT contract)
+    |
+    v
+Banny721TokenUriResolver (this contract)
+    |-- holds outfit/background NFTs in custody
+    |-- generates composed SVG token URIs
+    |-- enforces decoration rules and lock mechanism
+    |
+    v
+JB721TiersHookStore (read-only: tier metadata lookups)
+```
+
+## Core Concepts
+
+### Token ID Structure
+
+Token IDs encode product information: `tierId * 1_000_000_000 + sequenceNumber`. The `tierId` (called "UPC" or "product ID" in the codebase) maps to a tier in `JB721TiersHookStore`, which returns a `JB721Tier` struct containing `id`, `category`, `price`, `initialSupply`, `remainingSupply`, and other fields.
+
+### Category System
+
+There are 18 categories (0-17), each representing a layer or slot:
+
+| ID | Constant | Name | Role |
+|----|----------|------|------|
+| 0 | `_BODY_CATEGORY` | Banny body | Base character (Alien, Pink, Orange, Original) |
+| 1 | `_BACKGROUND_CATEGORY` | Background | Scene behind the banny |
+| 2 | `_BACKSIDE_CATEGORY` | Backside | Behind-body accessories |
+| 3 | `_NECKLACE_CATEGORY` | Necklace | Has special layering (after suit top) |
+| 4 | `_HEAD_CATEGORY` | Head | Full head piece -- **blocks** Eyes, Glasses, Mouth, HeadTop |
+| 5 | `_EYES_CATEGORY` | Eyes | Blocked by Head |
+| 6 | `_GLASSES_CATEGORY` | Glasses | Blocked by Head |
+| 7 | `_MOUTH_CATEGORY` | Mouth | Blocked by Head |
+| 8 | `_LEGS_CATEGORY` | Legs | Leg wear |
+| 9 | `_SUIT_CATEGORY` | Suit | Full suit -- **blocks** SuitBottom, SuitTop |
+| 10 | `_SUIT_BOTTOM_CATEGORY` | Suit bottom | Blocked by Suit |
+| 11 | `_SUIT_TOP_CATEGORY` | Suit top | Blocked by Suit |
+| 12 | `_HEADTOP_CATEGORY` | Head top | Blocked by Head |
+| 13 | `_HAND_CATEGORY` | Fist | Hand accessory |
+| 14 | `_SPECIAL_SUIT_CATEGORY` | Special Suit | Special outfit slot |
+| 15 | `_SPECIAL_LEGS_CATEGORY` | Special Legs | Special outfit 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.
+
+### 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).
+
+Outfits must be passed in **ascending category order** (line 1280-1281). No two outfits can share a category.
+
+## Outfit Decoration System
+
+### How Dressing Works
+
+`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).
+
+### Background Decoration (`_decorateBannyWithBackground`, line 1155)
+
+- 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`).
+- State updates (`_attachedBackgroundIdOf`, `_userOf`) happen before external transfers (CEI pattern).
+- 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)
+
+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).
+
+After all new outfits are processed, a second `while` loop (line 1348) transfers out any remaining old outfits.
+
+Finally, `_attachedOutfitIdsOf[hook][bannyBodyId]` is overwritten wholesale with the new array (line 1368).
+
+## Custody Model
+
+This is the highest-stakes part of the system.
+
+**Who holds the NFT**: When an outfit or background is equipped, the NFT is transferred from the caller to the resolver contract via `safeTransferFrom`. The resolver holds custody. The NFT is returned to the body owner when:
+- The body is redressed and the outfit is no longer in the new set.
+- The body is dressed with an empty outfit array (full undress).
+- The outfit is moved to a different body owned by the same person.
+
+**Transfer implications**: When a banny body NFT is transferred on the hook contract, all equipped outfits and the background remain associated with that body. The new body owner can call `decorateBannyWith` with empty arrays to receive all equipped NFTs. This is by design but creates a significant gotcha for sellers who forget to undress before selling.
+
+**No admin rescue**: The owner role has no function to force-return custody NFTs. If a bug prevents undressing, equipped NFTs are permanently locked.
+
+**`_tryTransferFrom` vs `_transferFrom`**: Returning old outfits uses `_tryTransferFrom` (try-catch, silent failure) because the token may have been burned or its tier removed. Equipping new outfits uses `_transferFrom` (reverts on failure) because the caller is asserting ownership of a token that must exist.
+
+### Key Invariant
+
+Every outfit NFT held by the resolver must be recoverable by the current owner of the banny body it is associated with.
+
+## Lock Mechanism
+
+`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`.
+- 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.
+
+**Purpose**: Enables trustless NFT marketplace sales of dressed bannys. A seller locks the body, lists it, and the buyer is guaranteed to receive the advertised outfit set.
+
+## SVG Storage and Rendering
+
+### 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).
+
+### SVG Composition
+
+`tokenUriOf` (line 200) 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).
+
+### SVG Sanitization
+
+**There is none.** SVG content is stored and rendered verbatim. The hash-commit pattern ensures only owner-approved content is stored, but the content itself is not sanitized. A malicious or compromised owner could commit hashes for SVGs containing `<script>` tags, external resource references (`<image href="https://...">`), or CSS injection.
+
+## Meta-Transaction Support (ERC-2771)
+
+The contract inherits `ERC2771Context` with an immutable `trustedForwarder` set at construction. All authorization checks use `_msgSender()` instead of `msg.sender`.
+
+If `trustedForwarder == address(0)` (the default in all test setups), meta-transactions are effectively disabled -- `_msgSender()` returns `msg.sender`.
+
+If a non-zero forwarder is set, that forwarder contract can append arbitrary sender addresses to calldata, allowing gasless transactions. The forwarder is fully trusted and can impersonate any address for all operations.
+
+**Risk**: If the forwarder is compromised, all authorization checks (body ownership, outfit authorization, lock, admin functions) can be bypassed.
+
+## `onERC721Received` Gate
+
+The resolver implements `IERC721Receiver.onERC721Received` (line 1038) 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.
+
+## Priority Audit Areas
+
+### 1. Outfit Authorization Logic (CRITICAL)
+
+File: `src/Banny721TokenUriResolver.sol`, lines 1254-1268.
+
+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.
+
+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.
+
+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.
+
+### 3. Custody Accounting Consistency (HIGH)
+
+State variables: `_attachedOutfitIdsOf`, `_attachedBackgroundIdOf`, `_wearerOf`, `_userOf`.
+
+These four mappings must remain consistent. After every `decorateBannyWith` call:
+- Every outfit in `_attachedOutfitIdsOf[hook][bodyId]` should have `_wearerOf[hook][outfitId] == bodyId`.
+- 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.
+
+### 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.
+
+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.
+
+### 5. Cross-Hook Isolation (MEDIUM)
+
+All state mappings are keyed by `address hook`. The `hook` parameter is caller-supplied and never validated. A malicious hook contract could return arbitrary data from `ownerOf()`, `STORE()`, `tierOfTokenId()`.
+
+Verify: a malicious hook cannot affect outfits custodied from a different (legitimate) hook. The per-hook mapping keys should provide full isolation.
+
+### 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.
+
+### 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.
+
+## Key Invariants to Test
+
+1. **Outfit recoverability**: Every outfit NFT held by the resolver can be recovered by the current body owner via `decorateBannyWith(hook, bodyId, 0, [])`.
+2. **No orphaned custody**: After `decorateBannyWith`, the resolver does not hold any outfit NFTs that are not tracked in `_attachedOutfitIdsOf` or `_attachedBackgroundIdOf`.
+3. **Category ascending order**: `_attachedOutfitIdsOf[hook][bodyId]` always contains outfits in ascending category order.
+4. **Lock monotonicity**: `outfitLockedUntil[hook][bodyId]` can only increase or remain the same.
+5. **Cross-hook isolation**: Operations on hook A never transfer, modify, or read custody state from hook B.
+6. **SVG hash/content immutability**: Once `svgHashOf[upc]` is set, it cannot be changed. Once `_svgContentOf[upc]` is set, it cannot be changed.
+7. **ReentrancyGuard blocks re-entry**: No call to `decorateBannyWith` can re-enter itself.
+
+## Testing Setup
+
+**Framework**: Foundry (forge). Config in `foundry.toml`.
+
+```bash
+# Run all tests
+forge test
+
+# Run with verbosity
+forge test -vvv
+
+# Run specific test file
+forge test --match-path test/Fork.t.sol -vvv
+
+# Run fork tests (requires RPC_ETHEREUM_MAINNET env var)
+RPC_ETHEREUM_MAINNET=<your-rpc-url> forge test --match-path test/Fork.t.sol -vvv
+
+# Gas report
+forge test --gas-report
+```
+
+**Test suite**: 11 test files, ~130+ tests.
+
+| File | Purpose |
+|------|---------|
+| `Banny721TokenUriResolver.t.sol` | Unit tests with mock hook/store |
+| `DecorateFlow.t.sol` | Authorization flows, L18 fix proof, multi-party |
+| `BannyAttacks.t.sol` | Adversarial: outfit theft, lock bypass, category abuse |
+| `Fork.t.sol` | End-to-end with real JB infrastructure, reentrancy |
+| `regression/CEIReorder.t.sol` | CEI ordering verification |
+| `regression/RemovedTierDesync.t.sol` | Removed tier handling |
+| `regression/ArrayLengthValidation.t.sol` | Array mismatch reverts |
+| `regression/BodyCategoryValidation.t.sol` | Non-body token rejection |
+| `regression/MsgSenderEvents.t.sol` | ERC-2771 event correctness |
+| `regression/BurnedTokenCheck.t.sol` | Burned token handling |
+| `regression/ClearMetadata.t.sol` | Metadata clearing |
+
+**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.
+- 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`).
+- The `transferFrom` (non-safe) path where NFTs bypass `onERC721Received`.
+
+## External Dependencies
+
+| Dependency | Used For |
+|------------|----------|
+| OpenZeppelin `Ownable` | Admin access control |
+| OpenZeppelin `ERC2771Context` | Meta-transaction sender extraction |
+| OpenZeppelin `ReentrancyGuard` | Reentrancy protection on `decorateBannyWith` |
+| OpenZeppelin `Strings` | `uint256.toString()` for metadata |
+| `base64` (lib) | Base64 encoding for data URIs |
+| `@bananapus/721-hook-v6` | `IJB721TiersHook`, `IJB721TiersHookStore`, `JBIpfsDecoder`, `JB721Tier`, `IERC721` |
+
+The resolver makes external calls to the `hook` and its `STORE()` but does not call any core Juicebox protocol contracts (no terminal, controller, or directory interactions).
+
+## Error Reference
+
+| Error | Trigger |
+|-------|---------|
+| `ArrayLengthMismatch` | `upcs.length != svgHashes/svgContents/names.length` |
+| `BannyBodyNotBodyCategory` | `bannyBodyId` is not category 0 |
+| `CantAccelerateTheLock` | New lock expires sooner than current lock |
+| `ContentsAlreadyStored` | SVG content already set for this UPC |
+| `ContentsMismatch` | SVG content hash does not match stored hash |
+| `HashAlreadyStored` | SVG hash already set for this UPC |
+| `HashNotFound` | No hash set for this UPC (cannot upload content) |
+| `HeadAlreadyAdded` | Conflict: Head + Eyes/Glasses/Mouth/HeadTop |
+| `OutfitChangesLocked` | Body is locked, cannot change outfits |
+| `SuitAlreadyAdded` | Conflict: Suit + SuitBottom/SuitTop |
+| `UnauthorizedBackground` | Caller does not own the background |
+| `UnauthorizedBannyBody` | Caller does not own the banny body |
+| `UnauthorizedOutfit` | Caller does not own the outfit or its wearer's body |
+| `UnauthorizedTransfer` | NFT sent to resolver not by resolver itself |
+| `UnorderedCategories` | Outfits not in ascending category order |
+| `UnrecognizedBackground` | Token is not category 1 |
+| `UnrecognizedCategory` | Outfit category not in 2-17 range |
+| `UnrecognizedProduct` | Body UPC not 1-4 (Alien/Pink/Orange/Original) |

package/CHANGE_LOG.md

@@ -0,0 +1,222 @@
+# banny-retail-v6 Changelog (v5 → v6)
+
+This document describes all changes between `banny-retail` (v5) and `banny-retail-v6` (v6).
+
+---
+
+## 1. Breaking Changes
+
+### Solidity Version Bump
+- **v5:** `pragma solidity 0.8.23;`
+- **v6:** `pragma solidity 0.8.26;`
+
+### Dependency Imports Updated
+All `@bananapus/721-hook-v5` imports replaced with `@bananapus/721-hook-v6`:
+- `IERC721`, `IJB721TiersHook`, `IJB721TiersHookStore`, `IJB721TokenUriResolver`, `JB721Tier`, `JBIpfsDecoder`
+
+### `setSvgBaseUri()` Removed and Replaced by `setMetadata()`
+- **v5:** `setSvgBaseUri(string calldata baseUri)` -- sets only the SVG base URI. Emits `SetSvgBaseUri`.
+- **v6:** `setMetadata(string calldata description, string calldata url, string calldata baseUri)` -- sets description, external URL, and base URI in a single call. Emits `SetMetadata`.
+- Callers that previously used `setSvgBaseUri()` must migrate to `setMetadata()`.
+
+### `setSvgHashsOf()` Renamed to `setSvgHashesOf()`
+- **v5:** `setSvgHashsOf(uint256[] memory upcs, bytes32[] memory svgHashs)`
+- **v6:** `setSvgHashesOf(uint256[] memory upcs, bytes32[] memory svgHashes)`
+- Function name and parameter name corrected for proper English pluralization.
+
+### `pricingContext()` Return Value Change
+- **v5:** `(uint256 currency, uint256 decimals,) = IJB721TiersHook(hook).pricingContext();` -- three return values (third ignored).
+- **v6:** `(uint256 currency, uint256 decimals) = IJB721TiersHook(hook).pricingContext();` -- two return values.
+- Reflects an upstream change in `IJB721TiersHook` where `pricingContext()` now returns only two values.
+
+### Token Metadata `description` and `external_url` Are Now Dynamic
+- **v5:** Hardcoded in `tokenUriOf()`: `"description":"A piece of Banny Retail."` and `"external_url":"https://retail.banny.eth.sucks"`.
+- **v6:** Read from state variables `svgDescription` and `svgExternalUrl`, set via `setMetadata()`. These default to empty strings until the owner sets them.
+
+---
+
+## 2. New Features
+
+### New State Variables: `svgDescription` and `svgExternalUrl`
+- `string public svgDescription` -- the description used in token metadata JSON.
+- `string public svgExternalUrl` -- the external URL used in token metadata JSON.
+- Both are settable via the new `setMetadata()` function.
+
+### Body Category Validation in `decorateBannyWith()`
+- **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).
+- Used in `_decorateBannyWithBackground()` and `_decorateBannyWithOutfits()` when returning previously equipped items.
+- **v5:** Used `_transferFrom()` (which reverts on failure) for all transfers, meaning a single burned/removed outfit could block the entire decoration operation.
+
+### `_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.
+
+### Array Length Validation on Batch Setters
+- **v6 adds:** `Banny721TokenUriResolver_ArrayLengthMismatch()` error.
+- `setProductNames()`, `setSvgContentsOf()`, and `setSvgHashesOf()` now validate that the `upcs` and values arrays have matching lengths. v5 had no such check, risking out-of-bounds reverts.
+
+### `assetIdsOf()` Array Resize via Assembly
+- **v6 adds:** After filtering outfits, the returned `outfitIds` array is resized via inline assembly (`mstore(outfitIds, numberOfIncludedOutfits)`) to remove trailing zeros.
+- **v5:** Returned the full-length array with trailing zero entries for unincluded outfits.
+
+### `_encodeTokenUri()` Extracted Helper
+- **v6 adds:** `_encodeTokenUri(uint256 tokenId, JB721Tier memory product, string memory extraMetadata, string memory imageContents)` -- an internal view function that encodes the token URI JSON with base64.
+- Uses nested `abi.encodePacked()` calls to avoid "stack too deep" errors.
+- **v5:** Inlined the entire JSON encoding in `tokenUriOf()` as a single large `abi.encodePacked()` call.
+
+### Default Eyes Bug Fix (`_outfitContentsFor`)
+- **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.
+
+### 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).
+
+### CEI Pattern in `_decorateBannyWithBackground()`
+- **v6:** Updates all state (`_attachedBackgroundIdOf`, `_userOf`) before any external transfers. Previous background transfer-out happens after state updates.
+- **v5:** Transferred the previous background out *before* updating state for the new background, creating a less safe interaction ordering.
+
+### Background Category Validation
+- **v5:** Only checked `backgroundProduct.id == 0` to reject invalid backgrounds.
+- **v6:** Also checks `backgroundProduct.category != _BACKGROUND_CATEGORY`, ensuring only actual background-category items can be used as backgrounds.
+
+### Outfit Re-equip Optimization
+- **v6:** When cleaning up remaining previous outfits, checks `_isInArray(previousOutfitId, outfitIds)` to skip outfits being re-equipped, avoiding unnecessary transfer-out-and-back-in cycles.
+- **v5:** Would transfer the outfit out and then transfer it back in during the same transaction.
+
+### Improved Loop Guard in `_decorateBannyWithOutfits()`
+- **v5:** `while (previousOutfitProductCategory <= outfitProductCategory && previousOutfitProductCategory != 0)` -- stops on category 0 but could re-enter after exhaustion.
+- **v6:** `while (previousOutfitId != 0 && previousOutfitProductCategory <= outfitProductCategory)` -- guards on `previousOutfitId != 0` as primary condition, correctly handling removed tiers (category 0) by always processing and advancing past them.
+
+### Re-check Ownership Before Transfer in `_decorateBannyWithOutfits()`
+- **v5:** Cached `owner = IERC721(hook).ownerOf(outfitId)` at the top of the loop, then later checked `if (owner != address(this))`.
+- **v6:** Re-checks `IERC721(hook).ownerOf(outfitId) != address(this)` at transfer time, avoiding stale ownership data after intermediate transfers.
+
+---
+
+## 3. Event Changes
+
+### Added
+| Event | Signature |
+|-------|-----------|
+| `SetMetadata` | `SetMetadata(string description, string externalUrl, string baseUri, address caller)` |
+
+### Removed
+| Event | Signature |
+|-------|-----------|
+| `SetSvgBaseUri` | `SetSvgBaseUri(string baseUri, address caller)` |
+
+### Unchanged
+| Event | Notes |
+|-------|-------|
+| `DecorateBanny` | Same signature in both versions |
+| `SetProductName` | Same signature in both versions |
+| `SetSvgContent` | Same signature in both versions |
+| `SetSvgHash` | Same signature in both versions |
+
+### `msg.sender` Replaced with `_msgSender()` in Event Emissions
+- **v5:** `setProductNames()`, `setSvgBaseUri()`, `setSvgContentsOf()`, and `setSvgHashsOf()` used `msg.sender` in event emissions.
+- **v6:** All event emissions consistently use `_msgSender()` (ERC-2771 compatible).
+
+---
+
+## 4. Error Changes
+
+### Added
+| Error | Purpose |
+|-------|---------|
+| `Banny721TokenUriResolver_ArrayLengthMismatch()` | Reverts when batch setter arrays have mismatched lengths |
+| `Banny721TokenUriResolver_BannyBodyNotBodyCategory()` | Reverts when `decorateBannyWith()` is called with a non-body-category token |
+
+### Unchanged
+| Error |
+|-------|
+| `Banny721TokenUriResolver_CantAccelerateTheLock()` |
+| `Banny721TokenUriResolver_ContentsAlreadyStored()` |
+| `Banny721TokenUriResolver_ContentsMismatch()` |
+| `Banny721TokenUriResolver_HashAlreadyStored()` |
+| `Banny721TokenUriResolver_HashNotFound()` |
+| `Banny721TokenUriResolver_HeadAlreadyAdded()` |
+| `Banny721TokenUriResolver_OutfitChangesLocked()` |
+| `Banny721TokenUriResolver_SuitAlreadyAdded()` |
+| `Banny721TokenUriResolver_UnauthorizedBackground()` |
+| `Banny721TokenUriResolver_UnauthorizedBannyBody()` |
+| `Banny721TokenUriResolver_UnauthorizedOutfit()` |
+| `Banny721TokenUriResolver_UnauthorizedTransfer()` |
+| `Banny721TokenUriResolver_UnorderedCategories()` |
+| `Banny721TokenUriResolver_UnrecognizedBackground()` |
+| `Banny721TokenUriResolver_UnrecognizedCategory()` |
+| `Banny721TokenUriResolver_UnrecognizedProduct()` |
+
+---
+
+## 5. Struct Changes
+
+No struct changes. Both versions use `JB721Tier` from the respective `721-hook` dependency. Any changes to `JB721Tier` are upstream in `nana-721-hook-v6`.
+
+---
+
+## 6. Implementation Changes (Non-Interface)
+
+### Token URI JSON Encoding Refactored
+- **v5:** Single large `abi.encodePacked()` call with all JSON fields inlined in `tokenUriOf()`.
+- **v6:** Split into `pricingMetadata` string built separately, then delegated to `_encodeTokenUri()`. Uses nested `abi.encodePacked()` to avoid "stack too deep".
+
+### `_outfitContentsFor()` Signature Change
+- **v5:** `_outfitContentsFor(address hook, uint256[] memory outfitIds)`
+- **v6:** `_outfitContentsFor(address hook, uint256[] memory outfitIds, uint256 bodyUpc)` -- added `bodyUpc` parameter for correct default eyes selection.
+
+### `_bannyBodySvgOf()` Relocated
+- **v5:** Located after `_msgSender()` / `_msgData()` overrides (line ~700).
+- **v6:** Relocated to immediately after `_categoryNameOf()` (line ~532), grouped with other internal view functions.
+
+### `_contextSuffixLength()` Relocated
+- **v5:** Located before `_bannyBodySvgOf()` (line ~562).
+- **v6:** Relocated after `_categoryNameOf()` and `_bannyBodySvgOf()` (line ~616).
+
+### Named Parameters in `JBIpfsDecoder.decode()` Calls
+- **v5:** Positional arguments: `JBIpfsDecoder.decode(baseUri, ...)`.
+- **v6:** Named arguments: `JBIpfsDecoder.decode({baseUri: baseUri, hexString: ...})`.
+
+### NatDoc / Comment Improvements
+- Typo fixes: "Nakes" to "Naked", "receieved" to "received", "prefered" to "preferred", "categorie's" to "category's", "transfered" to "transferred", "scg" to "svg", "lateset" to "latest".
+- Added detailed NatDoc to all interface functions (v5 interface had no NatDoc).
+- Added documentation for outfit travel behavior on banny body transfer.
+- Added documentation for unbounded array gas considerations on `_attachedOutfitIdsOf`.
+- Added detailed authorization rules in `decorateBannyWith()` NatDoc (6-point checklist).
+- Added warning about outfit/background travel on banny body transfer.
+- Added comment about `transferFrom` vs `safeTransferFrom` limitation in `onERC721Received`.
+
+### Lint Suppression Comments
+- **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.
+
+### Slither Annotations
+- **v6 adds:** `// slither-disable-next-line calls-loop` on several `IERC721(hook).ownerOf()` calls inside loops.
+- **v6 adds:** `// slither-disable-next-line encode-packed-collision` on the `_encodeTokenUri()` return.
+
+---
+
+## 7. Migration Table
+
+| v5 Function / Event | v6 Equivalent | Notes |
+|---|---|---|
+| `setSvgBaseUri(string)` | `setMetadata(string, string, string)` | Now sets description + external URL + base URI together |
+| `setSvgHashsOf(uint256[], bytes32[])` | `setSvgHashesOf(uint256[], bytes32[])` | Renamed (typo fix) |
+| `SetSvgBaseUri` event | `SetMetadata` event | Different parameters |
+| N/A | `svgDescription` (state variable) | New |
+| N/A | `svgExternalUrl` (state variable) | New |
+| N/A | `Banny721TokenUriResolver_ArrayLengthMismatch` | New error |
+| N/A | `Banny721TokenUriResolver_BannyBodyNotBodyCategory` | New error |
+| `_transferFrom()` (for returning items) | `_tryTransferFrom()` | Fault-tolerant; `_transferFrom()` still exists for mandatory transfers |
+| N/A | `_isInArray()` | New helper |
+| 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 |