@bannynet/core-v6 0.0.2 → 0.0.4

package/README.md

@@ -1,53 +1,135 @@
-# banny-retail-v5
+# Banny Retail
 
-On-chain composable avatar system for Juicebox 721 collections -- manages Banny character bodies, backgrounds, and outfit NFTs with layered SVG rendering.
+On-chain composable avatar system for Juicebox 721 collections -- manages Banny character bodies, backgrounds, and outfit NFTs with layered SVG rendering. Bodies can be dressed with outfits and placed on backgrounds, all composed into fully on-chain SVG images with base64-encoded JSON metadata.
 
-## Architecture
+[Docs](https://docs.juicebox.money) | [Discord](https://discord.gg/juicebox)
 
-| Contract | Description |
-|----------|-------------|
-| `Banny721TokenUriResolver` | The sole contract. Implements `IJB721TokenUriResolver` to serve fully on-chain SVG token URIs for any Juicebox 721 hook. Manages a composable asset system where Banny body NFTs can be dressed with outfit NFTs and placed on background NFTs, all rendered as layered SVGs with base64-encoded JSON metadata. Owner can register SVG content and hashes for product IDs (UPCs). |
+## Conceptual Overview
+
+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.
+
+### How It Works
+
+```
+1. A Juicebox 721 hook registers Banny721TokenUriResolver as its token URI resolver
+   → All tokenURI() calls are forwarded to the resolver
+   |
+2. Users mint Banny body NFTs + outfit/background NFTs via the 721 hook
+   → Bodies are the "base" layer; outfits and backgrounds are accessories
+   |
+3. Body owner calls decorateBannyWith(hook, bodyId, backgroundId, outfitIds)
+   → Outfit and background NFTs are transferred to the resolver contract
+   → Resolver tracks which body wears which outfits
+   → Body's tokenURI now renders the full dressed composition
+   |
+4. Outfit lock (optional): lockOutfitChangesFor(hook, bodyId)
+   → Freezes outfit changes for 7 days
+   → Proves the Banny's look is stable (useful for PFPs, displays)
+   |
+5. SVG content is stored on-chain via a two-step process:
+   → Owner registers content hashes: setSvgHashesOf(upcs, hashes)
+   → Anyone uploads matching content: setSvgContentsOf(upcs, contents)
+   → Falls back to IPFS base URI if on-chain content not yet stored
+```
 
 ### Asset Categories
 
-| Category ID | Name | Role |
-|-------------|------|------|
-| 0 | Body | The base Banny character. Owns outfits and backgrounds. |
+| Category ID | Name | Slot Rules |
+|-------------|------|------------|
+| 0 | Body | Base character. One of four types: Alien, Pink, Orange, Original. |
 | 1 | Background | Scene behind the Banny. One per body. |
-| 2 | Backside | Layer behind the body. |
-| 3 | Necklace | Accessory layer (default provided). |
-| 4 | Head | Head accessory. One per body. |
-| 5 | Eyes | Eye style (defaults: standard, alien). |
-| 6 | Glasses | Eyewear layer. |
-| 7 | Mouth | Mouth expression (default provided). |
+| 2 | Backside | Layer rendered behind the body. |
+| 3 | Necklace | Accessory (default provided if none attached). |
+| 4 | Head | Full head accessory. Blocks eyes, glasses, mouth, and headtop. |
+| 5 | Eyes | Eye style (defaults: alien or standard based on body type). |
+| 6 | Glasses | Eyewear layer. Blocked by head. |
+| 7 | Mouth | Mouth expression (default provided). Blocked by head. |
 | 8 | Legs | Lower body clothing. |
-| 9 | Suit | Full body suit (one-piece). |
-| 10 | Suit Bottom | Lower suit piece. |
-| 11 | Suit Top | Upper suit piece. |
-| 12 | Headtop | Top-of-head accessory. |
+| 9 | Suit | Full body one-piece. Blocks suit top and suit bottom. |
+| 10 | Suit Bottom | Lower suit piece. Blocked by full suit. |
+| 11 | Suit Top | Upper suit piece. Blocked by full suit. |
+| 12 | Headtop | Top-of-head accessory. Blocked by head. |
 | 13 | Hand | Held item layer. |
-| 14-17 | Special variants | Special suit, legs, head, and body overlays. |
+| 14-17 | Special | Special suit, legs, head, and body overlays. |
+
+### Body Types
+
+| UPC | Type | Color Palette |
+|-----|------|--------------|
+| 1 | Alien | Green tones (`67d757`, `30a220`, `217a15`, `09490f`) with purple accents |
+| 2 | Pink | Pink tones (`ffd8c5`, `ff96a9`, `fe588b`, `c92f45`) |
+| 3 | Orange | Orange tones (`f3a603`, `ff7c02`, `fd3600`, `c32e0d`) |
+| 4 | Original | Yellow tones (`ffe900`, `ffc700`, `f3a603`, `965a1a`) |
+
+## Architecture
+
+| Contract | Description |
+|----------|-------------|
+| `Banny721TokenUriResolver` | The sole contract. Implements `IJB721TokenUriResolver` to serve fully on-chain SVG token URIs for any Juicebox 721 hook. Manages outfit attachment, background assignment, outfit locking, on-chain SVG storage, and layered SVG rendering. Inherits `Ownable`, `ReentrancyGuard`, `ERC2771Context`, `IERC721Receiver`. |
+
+### Interface
+
+| Interface | Description |
+|-----------|-------------|
+| `IBanny721TokenUriResolver` | Public API: `tokenUriOf`, `svgOf`, `decorateBannyWith`, `lockOutfitChangesFor`, `assetIdsOf`, `namesOf`, `userOf`, `wearerOf`, SVG management, metadata management, plus all events. |
 
 ## Install
 
 ```bash
-npm install @bannynet/core-v5
+npm install @bannynet/core-v6
 ```
 
-## Develop
-
-`banny-retail-v5` uses [npm](https://www.npmjs.com/) for package management and [Foundry](https://github.com/foundry-rs/foundry) for builds, tests, and deployments. Requires `via-ir = true` in foundry.toml.
+If using Forge directly:
 
 ```bash
-curl -L https://foundry.paradigm.xyz | sh
-npm install && forge install
+forge install
 ```
 
+## Develop
+
+Requires `via_ir = true` in foundry.toml due to stack depth in SVG composition.
+
 | Command | Description |
 |---------|-------------|
-| `forge build` | Compile contracts and write artifacts to `out`. |
-| `forge test` | Run the test suite. |
-| `forge fmt` | Lint Solidity files. |
-| `forge build --sizes` | Get contract sizes. |
-| `forge coverage` | Generate a test coverage report. |
-| `forge clean` | Remove build artifacts and cache. |
+| `forge build` | Compile contracts (requires via-IR) |
+| `forge test` | Run all tests (3 test files: functionality, attacks, decoration flows) |
+| `forge test -vvv` | Run tests with full trace |
+
+## Repository Layout
+
+```
+src/
+  Banny721TokenUriResolver.sol                  # Sole contract (~1,331 lines)
+  interfaces/
+    IBanny721TokenUriResolver.sol               # Public interface + events
+test/
+  Banny721TokenUriResolver.t.sol                # Unit tests (~690 lines)
+  BannyAttacks.t.sol                            # Security/adversarial tests (~323 lines)
+  DecorateFlow.t.sol                            # Decoration flow tests (~1,057 lines)
+script/
+  Deploy.s.sol                                  # Sphinx multi-chain deployment
+  Drop1.s.sol                                   # Outfit drop deployment
+  Add.Denver.s.sol                              # Denver-specific deployment
+  helpers/
+    BannyverseDeploymentLib.sol                 # Deployment artifact reader
+    MigrationHelper.sol                         # Migration utilities
+```
+
+## Permissions
+
+| Action | Who Can Do It |
+|--------|--------------|
+| `decorateBannyWith` | Body owner (must also own or have worn-by-body access to outfits/backgrounds) |
+| `lockOutfitChangesFor` | Body owner |
+| `setSvgHashesOf` | Contract owner only |
+| `setSvgContentsOf` | Anyone (content validated against registered hash) |
+| `setProductNames` | Contract owner only |
+| `setMetadata` | Contract owner only |
+
+## 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.
+- **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.
+- **Single resolver per hook.** The resolver is set on the 721 hook and applies to all tiers. Different collections would need different resolver instances.

package/SKILLS.md

@@ -1,77 +1,179 @@
-# banny-retail-v5
+# Banny Retail
 
 ## Purpose
 
-On-chain composable NFT avatar system that renders Banny characters with layered SVG outfits and backgrounds for Juicebox 721 collections.
+On-chain composable NFT avatar system that renders Banny characters with layered SVG outfits and backgrounds for Juicebox 721 collections. Bodies can be dressed, locked, and rendered entirely on-chain.
 
 ## Contracts
 
 | Contract | Role |
 |----------|------|
-| `Banny721TokenUriResolver` | Resolves token URIs for any Juicebox 721 hook by composing layered SVGs from registered asset content. Manages outfit attachment, background assignment, outfit locking, and on-chain SVG storage. |
+| `Banny721TokenUriResolver` | Resolves token URIs for any Juicebox 721 hook by composing layered SVGs from registered asset content. Manages outfit attachment, background assignment, outfit locking, on-chain SVG storage, and metadata generation. Inherits `Ownable`, `ReentrancyGuard`, `ERC2771Context`, `IERC721Receiver`. (~1,331 lines) |
 
 ## Key Functions
 
-| Function | Contract | What it does |
-|----------|----------|--------------|
-| `tokenUriOf` | `Banny721TokenUriResolver` | Returns a base64-encoded JSON metadata URI with an on-chain SVG image. For body tokens, composes the full dressed Banny with attached outfits and background. For outfit/background tokens, renders the item on a mannequin Banny. |
-| `decorateBannyWith` | `Banny721TokenUriResolver` | Attaches a background and outfit NFTs to a Banny body. Validates ownership (caller must own the body, background, and all outfits via the same 721 hook). Enforces category ordering and uniqueness (one head, one suit, etc.). Detaches previously worn items. |
-| `lockOutfitChangesFor` | `Banny721TokenUriResolver` | Locks a Banny body's outfit for 7 days. Cannot accelerate an existing lock. Caller must own the body NFT. |
-| `svgOf` | `Banny721TokenUriResolver` | Returns the composed SVG for a token. For bodies, layers: background + backside + body + necklace + eyes + mouth + outfits (in category order). Falls back to SVG base URI + hash if on-chain content is not stored. |
-| `assetIdsOf` | `Banny721TokenUriResolver` | Returns the background ID and outfit IDs currently attached to a Banny body. |
-| `namesOf` | `Banny721TokenUriResolver` | Returns the product name, category name, and Banny type (Alien/Pink/Orange/Original) for a token. |
-| `setSvgContentsOf` | `Banny721TokenUriResolver` | Owner-only. Stores SVG content strings on-chain for given UPCs. Content must match the previously registered hash. Cannot overwrite existing content. |
-| `setSvgHashsOf` | `Banny721TokenUriResolver` | Owner-only. Registers SVG content hashes for UPCs. Hash cannot be changed once set. |
-| `setProductNames` | `Banny721TokenUriResolver` | Owner-only. Sets human-readable names for product UPCs. |
-| `setSvgBaseUri` | `Banny721TokenUriResolver` | Owner-only. Sets the base URI for lazily-loaded SVG files (used when on-chain content is not yet stored). |
-| `userOf` | `Banny721TokenUriResolver` | Returns the Banny body ID that a background is attached to. |
-| `wearerOf` | `Banny721TokenUriResolver` | Returns the Banny body ID that an outfit is worn by. |
-| `onERC721Received` | `Banny721TokenUriResolver` | Handles receiving 721 tokens. Validates the transfer is authorized (outfit must be worn by sender's Banny, or sender is hook). Used for outfit management. |
+### Token URI & Rendering
+
+| Function | What it does |
+|----------|-------------|
+| `tokenUriOf(hook, tokenId)` | Returns base64-encoded JSON metadata URI with on-chain SVG image. For bodies: composes dressed Banny with attached outfits and background. For outfit/background tokens: renders the item on a grayscale mannequin Banny. |
+| `svgOf(hook, tokenId, shouldDressBannyBody, shouldIncludeBackgroundOnBannyBody)` | Returns the composed SVG string. Layers (in order): background, backside, body, necklace, eyes, mouth, outfits by category. Falls back to IPFS base URI if on-chain content not stored. |
+
+### Decoration
+
+| Function | What it does |
+|----------|-------------|
+| `decorateBannyWith(hook, bannyBodyId, backgroundId, outfitIds)` | Attaches background and outfits to a body. Transfers assets to contract custody. Validates ownership, lock status, category ordering, slot conflicts. Returns previously attached items to caller. Emits `DecorateBanny`. |
+| `lockOutfitChangesFor(hook, bannyBodyId)` | Locks a body's outfit for 7 days. Cannot accelerate an existing lock. Caller must own the body NFT. |
+
+### Views
+
+| Function | What it does |
+|----------|-------------|
+| `assetIdsOf(hook, bannyBodyId)` | Returns `(backgroundId, outfitIds[])` currently attached to body. Filters out stale entries where `_wearerOf` no longer matches. |
+| `namesOf(hook, tokenId)` | Returns `(fullName, categoryName, productName)`. Full name includes inventory count (e.g., "42/100"). |
+| `userOf(hook, backgroundId)` | Returns the body ID using a background, or 0 if unused. Validates consistency. |
+| `wearerOf(hook, outfitId)` | Returns the body ID wearing an outfit, or 0 if unworn. Validates outfit is in body's attached array. |
+
+### SVG Content Management
+
+| Function | Who | What it does |
+|----------|-----|-------------|
+| `setSvgHashesOf(upcs, svgHashes)` | Owner only | Registers expected SVG content hashes for UPCs. Immutable once set. |
+| `setSvgContentsOf(upcs, svgContents)` | **Anyone** | Stores on-chain SVG content. Must match previously registered hash. Cannot overwrite existing content. |
+| `setProductNames(upcs, names)` | Owner only | Sets human-readable names for product UPCs. |
+| `setMetadata(description, url, baseUri)` | Owner only | Updates token metadata description, external URL, and SVG base URI. Empty strings clear the field. |
+
+### Token Receipt
+
+| Function | What it does |
+|----------|-------------|
+| `onERC721Received(operator, from, tokenId, data)` | Validates token receipt. Reverts unless `operator == address(this)`. Called when contract takes custody of outfits/backgrounds during decoration. |
 
 ## Integration Points
 
 | Dependency | Import | Used For |
 |------------|--------|----------|
-| `@bananapus/721-hook-v6` | `IJB721TiersHook`, `IJB721TiersHookStore`, `IJB721TokenUriResolver`, `JB721Tier`, `JBIpfsDecoder`, `IERC721` (custom ERC721) | Token ownership checks, tier data resolution, IPFS URI decoding, hook store queries. |
-| `@openzeppelin/contracts` | `Ownable`, `ReentrancyGuard`, `ERC2771Context`, `IERC721Receiver`, `Strings` | Access control, reentrancy protection, meta-transactions, safe NFT receipt, string utilities. |
-| `lib/base64` | `Base64` | Base64 encoding for on-chain SVG and JSON metadata. |
+| `@bananapus/721-hook-v6` | `IJB721TiersHook`, `IJB721TiersHookStore`, `IJB721TokenUriResolver`, `JB721Tier`, `JBIpfsDecoder`, `IERC721` | Token ownership checks, tier/product data resolution, IPFS URI decoding, hook store queries, safe transfers |
+| `@openzeppelin/contracts` | `Ownable`, `ReentrancyGuard`, `ERC2771Context`, `IERC721Receiver`, `Strings` | Access control, reentrancy protection, meta-transactions, safe NFT receipt, string utilities |
+| `lib/base64` | `Base64` | Base64 encoding for on-chain SVG and JSON metadata |
 
 ## Key Types
 
-| Struct/Enum | Key Fields | Used In |
-|-------------|------------|---------|
-| `JB721Tier` | `id`, `category`, `encodedIPFSUri`, `price` | `tokenUriOf` (product resolution via tier store) |
-
-### Internal Mappings (not structs, but critical state)
-
-| Mapping | Key | Value | Purpose |
-|---------|-----|-------|---------|
-| `_attachedOutfitIdsOf` | `hook => bannyBodyId` | `uint256[]` | Outfit token IDs attached to a body. |
-| `_attachedBackgroundIdOf` | `hook => bannyBodyId` | `uint256` | Background token ID attached to a body. |
-| `_svgContentOf` | `upc` | `string` | On-chain SVG content for a product. |
-| `svgHashOf` | `upc` | `bytes32` | Keccak256 hash of expected SVG content. |
-| `_customProductNameOf` | `upc` | `string` | Human-readable product name. |
-| `outfitLockedUntil` | `hook => upc` | `uint256` | Timestamp until outfit changes are locked. |
-| `_userOf` | `hook => backgroundId` | `uint256` | Which body is using a background. |
-| `_wearerOf` | `hook => outfitId` | `uint256` | Which body is wearing an outfit. |
+### Asset Categories
+
+| ID | Name | Slot Rules |
+|----|------|------------|
+| 0 | Body | Base character. Owns outfits and backgrounds. |
+| 1 | Background | One per body. |
+| 2 | Backside | Behind body layer. |
+| 3 | Necklace | Default provided if none attached. |
+| 4 | Head | Blocks eyes, glasses, mouth, headtop. |
+| 5 | Eyes | Defaults: alien eyes (UPC 1) or standard eyes (UPC 2-4). |
+| 6 | Glasses | Blocked by head. |
+| 7 | Mouth | Default provided. Blocked by head. |
+| 8 | Legs | Lower body clothing. |
+| 9 | Suit | Full one-piece. Blocks suit top and suit bottom. |
+| 10 | Suit Bottom | Blocked by full suit. |
+| 11 | Suit Top | Blocked by full suit. |
+| 12 | Headtop | Blocked by head. |
+| 13 | Hand | Held item. |
+| 14-17 | Special | Special suit, legs, head, body overlays. |
+
+### Body Types (by UPC)
+
+| UPC | Type | Default Eyes |
+|-----|------|-------------|
+| 1 | Alien | `DEFAULT_ALIEN_EYES` (purple) |
+| 2 | Pink | `DEFAULT_STANDARD_EYES` |
+| 3 | Orange | `DEFAULT_STANDARD_EYES` |
+| 4 | Original | `DEFAULT_STANDARD_EYES` |
+
+## Events
+
+| Event | When |
+|-------|------|
+| `DecorateBanny(hook, bannyBodyId, backgroundId, outfitIds, caller)` | Body decorated with new outfits/background |
+| `SetMetadata(description, externalUrl, baseUri, caller)` | Metadata updated |
+| `SetProductName(upc, name, caller)` | Product name set |
+| `SetSvgContent(upc, svgContent, caller)` | SVG content stored on-chain |
+| `SetSvgHash(upc, svgHash, caller)` | SVG hash registered |
+
+## Errors
+
+| Error | When |
+|-------|------|
+| `Banny721TokenUriResolver_ArrayLengthMismatch` | Batch setter called with mismatched array lengths |
+| `Banny721TokenUriResolver_BannyBodyNotBodyCategory` | Passing a non-body-category token as bannyBodyId to decorateBannyWith |
+| `Banny721TokenUriResolver_CantAccelerateTheLock` | Trying to lock a body that's already locked for longer |
+| `Banny721TokenUriResolver_ContentsAlreadyStored` | SVG content already exists for this UPC |
+| `Banny721TokenUriResolver_ContentsMismatch` | Uploaded content doesn't match registered hash |
+| `Banny721TokenUriResolver_HashAlreadyStored` | Hash already registered for this UPC |
+| `Banny721TokenUriResolver_HashNotFound` | No hash registered for UPC (must register before uploading content) |
+| `Banny721TokenUriResolver_HeadAlreadyAdded` | Trying to add eyes/glasses/mouth/headtop when head is already attached |
+| `Banny721TokenUriResolver_OutfitChangesLocked` | Body is locked (7-day lock active) |
+| `Banny721TokenUriResolver_SuitAlreadyAdded` | Trying to add suit top/bottom when full suit is already attached |
+| `Banny721TokenUriResolver_UnauthorizedBannyBody` | Caller doesn't own the body |
+| `Banny721TokenUriResolver_UnauthorizedOutfit` | Caller doesn't own the outfit or the body wearing it |
+| `Banny721TokenUriResolver_UnauthorizedBackground` | Caller doesn't own the background or the body using it |
+| `Banny721TokenUriResolver_UnorderedCategories` | Outfit IDs not in ascending category order |
+| `Banny721TokenUriResolver_UnrecognizedCategory` | Category ID not in valid range (0-17) |
+| `Banny721TokenUriResolver_UnrecognizedBackground` | Token is not a background category |
+| `Banny721TokenUriResolver_UnrecognizedProduct` | Token's UPC doesn't map to a known product |
+| `Banny721TokenUriResolver_UnauthorizedTransfer` | `onERC721Received` called by non-self operator |
+
+## Constants
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `_LOCK_DURATION` | 7 days | Fixed outfit lock period |
+| `_ONE_BILLION` | 1,000,000,000 | Token ID encoding: `tokenId = upc * 1B + sequenceNumber` |
+| `_BODY_CATEGORY` | 0 | Category ID for base Banny body |
+| `_BACKGROUND_CATEGORY` | 1 | Category ID for backgrounds |
+| Categories 2-17 | 2-17 | Backside, necklace, head, eyes, glasses, mouth, legs, suit, suit bottom, suit top, headtop, hand, specials |
+
+## Storage
+
+| Mapping | Type | Purpose |
+|---------|------|---------|
+| `_attachedOutfitIdsOf` | `hook => bannyBodyId => uint256[]` | Outfit token IDs attached to a body |
+| `_attachedBackgroundIdOf` | `hook => bannyBodyId => uint256` | Background token ID attached to a body |
+| `_svgContentOf` | `upc => string` | On-chain SVG content (immutable once set) |
+| `svgHashOf` | `upc => bytes32` | Expected SVG content hash (immutable once set) |
+| `_customProductNameOf` | `upc => string` | Human-readable product name |
+| `outfitLockedUntil` | `hook => upc => uint256` | Timestamp until outfit changes locked |
+| `_userOf` | `hook => backgroundId => uint256` | Which body uses a background |
+| `_wearerOf` | `hook => outfitId => uint256` | Which body wears an outfit |
+| `svgBaseUri` | `string` | IPFS/HTTP base URI for fallback SVG loading |
+| `svgDescription` | `string` | Token metadata description |
+| `svgExternalUrl` | `string` | Token metadata external URL |
 
 ## Gotchas
 
-- The `_LOCK_DURATION` is hardcoded to 7 days. `lockOutfitChangesFor` prevents reducing an existing lock (reverts with `CantAccelerateTheLock`).
-- SVG content is immutable once stored. `setSvgContentsOf` reverts if content already exists. The content must hash-match the previously registered `svgHashOf[upc]`.
-- SVG hashes are also immutable. `setSvgHashsOf` reverts if a hash is already registered for a UPC.
-- `decorateBannyWith` enforces strict ascending category order for outfits. Passing outfits in wrong order reverts with `UnorderedCategories`.
-- Only one item per "slot" category is allowed on a body: one head, one suit (full suit XOR suit top + suit bottom), one background.
-- Body type detection uses the UPC modulo: UPC 1 = Alien, 2 = Pink, 3 = Orange, 4 = Original. Alien bodies get `DEFAULT_ALIEN_EYES`, others get `DEFAULT_STANDARD_EYES`.
-- Outfit/background ownership is validated against the 721 hook, not `msg.sender` directly. The caller must own the body AND all attached items through the same hook contract.
-- `via-ir = true` is required in `foundry.toml` due to stack-too-deep in the complex SVG composition logic.
+1. **7-day lock is fixed and non-cancellable.** `lockOutfitChangesFor` always sets `outfitLockedUntil = block.timestamp + 7 days`. Cannot be shortened, cancelled, or accelerated. Only extended.
+2. **SVG content is immutable.** Once `setSvgContentsOf` stores content for a UPC, it cannot be changed. A mistake requires deploying a new resolver.
+3. **SVG hashes are also immutable.** `setSvgHashesOf` reverts if a hash already exists for a UPC. Register carefully.
+4. **Hash registration is owner-only, but content upload is permissionless.** Anyone can call `setSvgContentsOf` as long as the content matches the registered hash. This enables community-driven lazy uploads.
+5. **Strict ascending category order.** `decorateBannyWith` requires outfits passed in ascending category order. Reverts with `UnorderedCategories` if violated.
+6. **Slot conflicts block combinations.** Head (4) blocks eyes (5), glasses (6), mouth (7), and headtop (12). Full suit (9) blocks suit top (11) and suit bottom (10). These are enforced at decoration time.
+7. **Default injection.** If no explicit necklace, eyes, or mouth outfit is attached, the resolver auto-injects defaults during SVG rendering. Alien bodies get `DEFAULT_ALIEN_EYES`; others get `DEFAULT_STANDARD_EYES`.
+8. **Outfits are held in contract custody.** Attached outfits and backgrounds are transferred to `address(this)` via `safeTransferFrom`. They are returned to the caller when detached (by passing a new outfit set that excludes them).
+9. **Complex outfit ownership rules.** If an outfit is unworn: only its owner can attach it. If already worn by another body: the caller must own THAT body to reassign the outfit. This allows body owners to swap outfits between their own bodies.
+10. **Token ID encoding.** `tokenId = upc * 1_000_000_000 + sequenceNumber`. The resolver extracts UPC via integer division and sequence via modulo to display inventory counts like "42/100".
+11. **`onERC721Received` only accepts self-transfers.** Reverts unless `operator == address(this)`. The contract calls `safeTransferFrom` on itself during decoration, triggering this callback.
+12. **Via-IR required.** `foundry.toml` must have `via_ir = true` due to stack-too-deep in the SVG composition logic.
+13. **SVG fallback chain.** If on-chain content exists: use it. Else if category <= 17: fall back to `svgBaseUri + IPFS URI`. Else: use the hook's `baseURI() + IPFS URI`.
+14. **Mannequin rendering.** Outfit and background tokens (not bodies) are rendered on a grayscale mannequin Banny for preview purposes. The mannequin has `fill:#808080` styling.
+15. **ERC2771 meta-transaction support.** Constructor takes a `trustedForwarder` address. All `_msgSender()` calls use `ERC2771Context`, allowing relayers to submit decoration transactions on behalf of users.
+16. **Empty metadata fields clear the value.** `setMetadata` always writes all three fields. Passing an empty string clears that field. To keep a field unchanged, pass its current value.
 
 ## Example Integration
 
 ```solidity
 import {IBanny721TokenUriResolver} from "@bannynet/core-v6/src/interfaces/IBanny721TokenUriResolver.sol";
 
-// Get the composed SVG for a dressed Banny
+// --- Get the composed SVG for a dressed Banny ---
+
 string memory svg = resolver.svgOf(
     hookAddress,
     bannyBodyTokenId,
@@ -79,7 +181,8 @@ string memory svg = resolver.svgOf(
     true   // include the attached background
 );
 
-// Dress a Banny body with outfits
+// --- Dress a Banny body with outfits ---
+
 uint256[] memory outfitIds = new uint256[](2);
 outfitIds[0] = hatTokenId;   // must be category 4 (head)
 outfitIds[1] = shirtTokenId; // must be category 11 (suit top)
@@ -89,6 +192,24 @@ resolver.decorateBannyWith(
     hookAddress,
     bannyBodyTokenId,
     backgroundTokenId,
-    outfitIds  // must be in ascending category order
+    outfitIds  // MUST be in ascending category order
 );
+
+// --- Lock outfit changes for 7 days ---
+
+resolver.lockOutfitChangesFor(hookAddress, bannyBodyTokenId);
+
+// --- Register and upload SVG content ---
+
+// Step 1: Owner registers content hashes
+uint256[] memory upcs = new uint256[](1);
+upcs[0] = 42;
+bytes32[] memory hashes = new bytes32[](1);
+hashes[0] = keccak256(bytes(svgContent));
+resolver.setSvgHashesOf(upcs, hashes);
+
+// Step 2: Anyone uploads matching content
+string[] memory contents = new string[](1);
+contents[0] = svgContent;
+resolver.setSvgContentsOf(upcs, contents);
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bannynet/core-v6",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -20,15 +20,15 @@
         "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.3",
-        "@bananapus/core-v6": "^0.0.4",
-        "@bananapus/suckers-v6": "^0.0.2",
-        "@bananapus/router-terminal-v6": "^0.0.2",
-        "@openzeppelin/contracts": "^5.2.0",
-        "@rev-net/core-v6": "^0.0.2",
+        "@bananapus/721-hook-v6": "^0.0.9",
+        "@bananapus/core-v6": "^0.0.9",
+        "@bananapus/router-terminal-v6": "^0.0.6",
+        "@bananapus/suckers-v6": "^0.0.6",
+        "@openzeppelin/contracts": "5.2.0",
+        "@rev-net/core-v6": "^0.0.6",
         "keccak": "^3.0.4"
     },
     "devDependencies": {
-        "@sphinx-labs/plugins": "0.33.2"
+        "@sphinx-labs/plugins": "0.33.3"
     }
 }

package/script/Add.Denver.s.sol

@@ -23,7 +23,7 @@ contract Drop1Script is Script, Sphinx {
 
     function configureSphinx() public override {
         // TODO: Update to contain revnet devs.
-        sphinxConfig.projectName = "banny-core";
+        sphinxConfig.projectName = "banny-core-v6";
         sphinxConfig.mainnets = ["ethereum", "optimism", "base", "arbitrum"];
         sphinxConfig.testnets = ["ethereum_sepolia", "optimism_sepolia", "base_sepolia", "arbitrum_sepolia"];
     }
@@ -37,8 +37,10 @@ contract Drop1Script is Script, Sphinx {
         );
 
         // Get the deployment addresses for the 721 hook contracts for this chain.
-        bannyverse =
-            BannyverseDeploymentLib.getDeployment(vm.envOr("BANNYVERSE_CORE_DEPLOYMENT_PATH", string("deployments/")));
+        bannyverse = BannyverseDeploymentLib.getDeployment(
+            vm.envOr("BANNYVERSE_CORE_DEPLOYMENT_PATH", string("deployments/")),
+            vm.envOr("BANNYVERSE_REVNET_ID", uint256(4))
+        );
 
         // Get the hook address by using the deployer.
         hook = JB721TiersHook(address(revnet.basic_deployer.tiered721HookOf(bannyverse.revnetId)));
@@ -73,6 +75,16 @@ contract Drop1Script is Script, Sphinx {
             splits: new JBSplit[](0)
         });
 
+        // Get the next tier ID so we can set names and hashes for the new product.
+        uint256 nextTierId = hook.STORE().maxTierIdOf(address(hook)) + 1;
+
         hook.adjustTiers(products, new uint256[](0));
+
+        // Build the product IDs array for the newly added tier(s).
+        uint256[] memory productIds = new uint256[](1);
+        productIds[0] = nextTierId;
+
+        bannyverse.resolver.setSvgHashesOf(productIds, svgHashes);
+        bannyverse.resolver.setProductNames(productIds, names);
     }
 }

package/script/Drop1.s.sol

@@ -37,8 +37,10 @@ contract Drop1Script is Script, Sphinx {
         );
 
         // Get the deployment addresses for the 721 hook contracts for this chain.
-        bannyverse =
-            BannyverseDeploymentLib.getDeployment(vm.envOr("BANNYVERSE_CORE_DEPLOYMENT_PATH", string("deployments/")));
+        bannyverse = BannyverseDeploymentLib.getDeployment(
+            vm.envOr("BANNYVERSE_CORE_DEPLOYMENT_PATH", string("deployments/")),
+            vm.envOr("BANNYVERSE_REVNET_ID", uint256(4))
+        );
 
         // Get the hook address by using the deployer.
         hook = JB721TiersHook(address(revnet.basic_deployer.tiered721HookOf(bannyverse.revnetId)));
@@ -1045,29 +1047,8 @@ contract Drop1Script is Script, Sphinx {
             productIds[i] = i + 5;
         }
 
-        if (false) {
-            bytes memory adjustTiersData = abi.encodeCall(JB721TiersHook.adjustTiers, (products, new uint256[](0)));
-            vm.writeFile(
-                string.concat("./", vm.toString(block.chainid), "-adjustTiers.hex.txt"), vm.toString(adjustTiersData)
-            );
-
-            bytes memory setSvgHashData =
-                abi.encodeCall(Banny721TokenUriResolver.setSvgHashesOf, (productIds, svgHashes));
-
-            vm.writeFile(
-                string.concat("./", vm.toString(block.chainid), "-setSvgHashOf.hex.txt"), vm.toString(setSvgHashData)
-            );
-
-            bytes memory setProductNamesData =
-                abi.encodeCall(Banny721TokenUriResolver.setProductNames, (productIds, names));
-            vm.writeFile(
-                string.concat("./", vm.toString(block.chainid), "-setProductNames.hex.txt"),
-                vm.toString(setProductNamesData)
-            );
-        } else {
-            hook.adjustTiers(products, new uint256[](0));
-            bannyverse.resolver.setSvgHashesOf(productIds, svgHashes);
-            bannyverse.resolver.setProductNames(productIds, names);
-        }
+        hook.adjustTiers(products, new uint256[](0));
+        bannyverse.resolver.setSvgHashesOf(productIds, svgHashes);
+        bannyverse.resolver.setProductNames(productIds, names);
     }
 }

package/script/helpers/BannyverseDeploymentLib.sol

@@ -18,7 +18,13 @@ library BannyverseDeploymentLib {
     address internal constant VM_ADDRESS = address(uint160(uint256(keccak256("hevm cheat code"))));
     Vm internal constant vm = Vm(VM_ADDRESS);
 
-    function getDeployment(string memory path) internal returns (BannyverseDeployment memory deployment) {
+    function getDeployment(
+        string memory path,
+        uint256 revnetId
+    )
+        internal
+        returns (BannyverseDeployment memory deployment)
+    {
         // get chainId for which we need to get the deployment.
         uint256 chainId = block.chainid;
 
@@ -29,7 +35,7 @@ library BannyverseDeploymentLib {
 
         for (uint256 _i; _i < networks.length; _i++) {
             if (networks[_i].chainId == chainId) {
-                return getDeployment(path, networks[_i].name);
+                return getDeployment(path, networks[_i].name, revnetId);
             }
         }
 
@@ -38,7 +44,8 @@ library BannyverseDeploymentLib {
 
     function getDeployment(
         string memory path,
-        string memory network_name
+        string memory network_name,
+        uint256 revnetId
     )
         internal
         view
@@ -48,7 +55,7 @@ library BannyverseDeploymentLib {
             _getDeploymentAddress(path, "banny-core-v6", network_name, "Banny721TokenUriResolver")
         );
 
-        deployment.revnetId = 4;
+        deployment.revnetId = revnetId;
     }
 
     /// @notice Get the address of a contract that was deployed by the Deploy script.