@bannynet/core-v6 0.0.16 → 0.0.18

package/README.md

@@ -1,115 +1,40 @@
 # Banny Retail
 
-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.
+Banny Retail is an on-chain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, sit on a background NFT, and render the full composition as an on-chain SVG and base64 metadata payload.
 
-[Docs](https://docs.juicebox.money) | [Discord](https://discord.gg/juicebox)
+Docs: <https://docs.juicebox.money>
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
 
-## Conceptual Overview
+## 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.
+This is a resolver-centric application built on top of [`@bananapus/721-hook-v6`](https://www.npmjs.com/package/@bananapus/721-hook-v6). The resolver owns attached outfit and background NFTs while a body is decorated, then composes the active layers into a single token URI response.
 
-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.
+The main user flows are:
 
-### How It Works
+- mint body, outfit, and background NFTs through a Juicebox 721 hook
+- attach accessories to a body with `decorateBannyWith`
+- optionally freeze the current look for seven days with `lockOutfitChangesFor`
+- upload SVG payloads lazily after an owner registers their content hashes
 
-```
-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 and background changes for 7 days
-   → Prevents moving currently equipped assets away through another body's decoration call
-   → 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
-```
+Use this repo when you need collection-specific, fully on-chain metadata composition on top of Juicebox NFTs. Do not use it as a generic 721 hook; it is an application-layer resolver, not a protocol NFT primitive.
 
-### 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
-```
+If a bug changes tier pricing, mint eligibility, or treasury flow, it is probably not here first. Start in the 721 hook repo and only come here once the issue is clearly in attachment, custody, or rendering behavior.
+
+## Key Contract
+
+| Contract | Role |
+| --- | --- |
+| `Banny721TokenUriResolver` | Resolves token metadata, stores equipped accessories, enforces outfit locks, and renders layered SVG output for Banny collections. |
+
+## Mental Model
 
-### Asset Categories
-
-| 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 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 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 | 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. |
+This repo owns three things:
+
+1. custody of attached outfit and background NFTs while equipped
+2. rules around what a body can wear and when that can change
+3. rendering of the final token metadata payload
+
+It does not own mint pricing, tier issuance, or project accounting.
 
 ## Install
 
@@ -117,84 +42,45 @@ sequenceDiagram
 npm install @bannynet/core-v6
 ```
 
-If using Forge directly:
+## Development
+
+The contract stack relies on `via_ir = true` in `foundry.toml`.
 
 ```bash
-forge install
+npm install
+forge build
+forge test
 ```
 
-## Develop
+Useful scripts:
 
-Requires `via_ir = true` in foundry.toml due to stack depth in SVG composition.
+- `npm run deploy:mainnets`
+- `npm run deploy:testnets`
+- `npm run deploy:mainnets:drop:1`
+- `npm run deploy:testnets:drop:1`
 
-| Command | Description |
-|---------|-------------|
-| `forge build` | Compile contracts (requires via-IR) |
-| `forge test` | Run all tests (14 test files: functionality, attacks, decoration flows, fork integration, transfer lifecycle, audit gaps, QA, regressions) |
-| `forge test -vvv` | Run tests with full trace |
+## Deployment Notes
+
+Deployments are handled through Sphinx using the environments configured in `script/Deploy.s.sol`. The resolver is intended to be plugged into a Juicebox 721 hook as that hook's token URI resolver.
 
 ## Repository Layout
 
-```
+```text
 src/
-  Banny721TokenUriResolver.sol                  # Sole contract (~1,428 lines)
+  Banny721TokenUriResolver.sol
   interfaces/
-    IBanny721TokenUriResolver.sol               # Public interface + events
 test/
-  Banny721TokenUriResolver.t.sol                # Unit tests
-  BannyAttacks.t.sol                            # Security/adversarial tests
-  DecorateFlow.t.sol                            # Decoration flow tests
-  Fork.t.sol                                    # Fork integration tests
-  OutfitTransferLifecycle.t.sol                 # Transfer lifecycle tests
-  TestAuditGaps.sol                             # Audit gap coverage (meta-tx, SVG edge cases)
-  TestQALastMile.t.sol                          # QA tests (gas, round-trip, fallback)
-  regression/
-    ArrayLengthValidation.t.sol                 # Input validation regression
-    BodyCategoryValidation.t.sol                # Body category regression
-    BurnedTokenCheck.t.sol                      # Burned token regression
-    CEIReorder.t.sol                            # CEI ordering regression
-    ClearMetadata.t.sol                         # Metadata clearing regression
-    MsgSenderEvents.t.sol                       # Event emission regression
-    RemovedTierDesync.t.sol                     # Removed tier desync regression
+  unit, attack, fork, audit, QA, and regression coverage
 script/
-  Deploy.s.sol                                  # Sphinx multi-chain deployment
-  Drop1.s.sol                                   # Outfit drop deployment
-  Add.Denver.s.sol                              # Denver-specific deployment
+  Deploy.s.sol
+  Drop1.s.sol
+  Add.Denver.s.sol
   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 |
-
-## 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 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.
-- **Single resolver per hook.** The resolver is set on the 721 hook and applies to all tiers. Different collections would need different resolver instances.
+## Risks And Notes
+
+- attached outfits and backgrounds are custodied by the resolver while equipped
+- outfit locks are fixed-duration and cannot be shortened once set
+- on-chain SVG content is immutable once uploaded for a given registered hash
+- rendering quality and metadata correctness depend on the integrity of uploaded SVG assets

package/RISKS.md

@@ -1,4 +1,21 @@
-# RISKS.md -- banny-retail-v6
+# Banny Retail Risk Register
+
+This file focuses on failure modes that can break NFT custody, let untrusted hook integrations bypass assumptions, or leave a rendered Banny in a state that does not match the assets users think they own.
+
+## How to use this file
+
+- Read `Priority risks` first; those are the highest-signal failure modes for operators, auditors, and integrators.
+- Use `Accepted Behaviors` to separate intentional tradeoffs from genuine bugs.
+- Treat `Invariants to Verify` as required test and audit targets.
+
+## Priority risks
+
+| Priority | Risk | Why it matters | Primary controls |
+|----------|------|----------------|------------------|
+| P0 | Untrusted `hook` or store integration | The caller chooses the hook, and the resolver trusts it for ownership checks, tier metadata, and transfers. A bad hook can fake authority or trap assets. | Operationally restrict supported hooks, scrutinize sections 1, 3, and 5, and test with hostile hook behavior. |
+| P1 | Silent transfer failure retention | Failed returns intentionally keep attachment records to avoid stranding NFTs, but this can leave phantom render state if the underlying asset is gone forever. | Explicit accepted-behavior rules, retained-item handling, and invariants around custody/state correspondence. |
+| P1 | Sale-time outfit lock griefing | A seller can transfer a locked body and force the buyer to wait up to 7 days before changing outfits. | Fixed-duration lock, marketplace disclosure, and user education before secondary sales. |
+
 
 ## 1. Trust Assumptions
 

package/SKILLS.md

@@ -1,256 +1,40 @@
 # Banny Retail
 
-## Purpose
-
-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, on-chain SVG storage, and metadata generation. Inherits `Ownable`, `ReentrancyGuard`, `ERC2771Context`, `IERC721Receiver`. (~1,331 lines) |
-
-## Key Functions
-
-### 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. Attempts to return previously attached items to caller — if a return fails, the item is retained (not stranded). 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` | 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 |
-
-### Deployment / Setup Sequence
-
-The resolver is connected to a 721 hook in one of two ways:
-
-1. **At hook deployment**: Pass the resolver address as `tokenUriResolver` in `JBDeploy721TiersHookConfig` when calling `IJB721TiersHookDeployer.deployHookFor(...)`. The hook's `initialize()` stores it in the hook store via `recordSetTokenUriResolver`.
-2. **After deployment**: Call `hook.setMetadata(...)` with the resolver address as the `tokenUriResolver` parameter. Requires `SET_721_METADATA` permission. Pass `IJB721TokenUriResolver(address(this))` as a sentinel value to leave it unchanged, since `address(0)` clears the resolver.
-
-Once set, the hook's store maps `tokenUriResolverOf[hook]` to the resolver address. Any `tokenURI(tokenId)` call on the hook delegates to `resolver.tokenUriOf(hook, tokenId)`, which composes the on-chain SVG.
-
-## Rendering Order
+## Use This File For
 
-The composed SVG layers elements back-to-front. Later layers are drawn on top of earlier layers. The full rendering order for a dressed body is:
+- Use this file when the task involves Banny outfit attachment, layered SVG rendering, token URI composition, or asset custody and lock behavior.
+- Start here, then open the resolver, scripts, or tests that match the exact rendering or attachment path in question.
 
-1. **Background** (category 1) -- if attached and `shouldIncludeBackgroundOnBannyBody` is true
-2. **Body** (category 0) -- the base Banny character with color-fill styles (`b1`-`b4`, `a1`-`a3`)
-3. **Backside** (category 2) -- rendered behind the body in the SVG source but layered by the SVG's internal z-ordering
-4. **Necklace** (category 3) -- default injected if none attached; custom necklaces are deferred and rendered after suit top (category 11)
-5. **Head** (category 4) -- if present, suppresses default injection of eyes, mouth
-6. **Eyes** (category 5) -- default alien or standard eyes injected if no head and no explicit eyes
-7. **Glasses** (category 6)
-8. **Mouth** (category 7) -- default mouth injected if no head and no explicit mouth
-9. **Legs** (category 8)
-10. **Suit** (category 9)
-11. **Suit Bottom** (category 10)
-12. **Suit Top** (category 11)
-13. **Custom Necklace** -- rendered here (after suit top) if a custom necklace was provided, so it layers on top of clothing
-14. **Headtop** (category 12)
-15. **Hand** (category 13)
-16. **Special overlays** (categories 14-17) -- suit, legs, head, body specials
+## Read This Next
 
-For non-body tokens (outfits, backgrounds), the item is rendered on a grayscale mannequin Banny (`fill:#808080`) for preview.
+| If you need... | Open this next |
+|---|---|
+| Repo overview and user-facing behavior | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Resolver implementation | [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) |
+| Deployment or scripted drops | [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/Drop1.s.sol`](./script/Drop1.s.sol), [`script/Add.Denver.s.sol`](./script/Add.Denver.s.sol) |
+| Decoration lifecycle and regressions | [`test/DecorateFlow.t.sol`](./test/DecorateFlow.t.sol), [`test/OutfitTransferLifecycle.t.sol`](./test/OutfitTransferLifecycle.t.sol), [`test/regression/`](./test/regression/) |
+| Adversarial or QA coverage | [`test/BannyAttacks.t.sol`](./test/BannyAttacks.t.sol), [`test/TestQALastMile.t.sol`](./test/TestQALastMile.t.sol), [`test/audit/`](./test/audit/) |
 
-## SVG Format Requirements
+## Repo Map
 
-- **Canvas**: All SVGs are rendered within a `400x400` viewport: `<svg width="400" height="400" viewBox="0 0 400 400">`.
-- **Fragment, not document**: SVG content stored via `setSvgContentsOf` must NOT include the parent `<svg>` element. The resolver wraps all fragments in the outer SVG element with shared styles (`.o{fill:#050505;}.w{fill:#f9f9f9;}`).
-- **Hash verification only**: The contract validates uploaded SVG content against a pre-registered `keccak256` hash but performs no structural validation (no dimension checks, no viewBox enforcement). Ensuring content renders correctly at 400x400 is the uploader's responsibility.
-- **Body color classes**: Body SVGs use CSS classes `b1`-`b4` (body fills) and `a1`-`a3` (accent fills) which are injected as `<style>` elements based on the body's UPC. Outfit SVGs can reference `.o` (dark, #050505) and `.w` (light, #f9f9f9) classes provided by the wrapper.
-- **Immutability**: Once stored, SVG content cannot be changed. A content or hash error requires deploying a new resolver instance.
+| Area | Where to look |
+|---|---|
+| Main contract | [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) |
+| Scripts | [`script/`](./script/) |
+| Tests | [`test/`](./test/) |
 
-## Key Types
-
-### 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 => bannyBodyId => uint256` | Timestamp until outfit changes locked (declared as `upc` but keyed by token ID) |
-| `_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
-
-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). If the 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 transfer issue is resolved.
-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.
-17. **Outfit locks persist through transfers.** The `outfitLockedUntil` mapping is keyed by `(hook, bannyBodyId)` and is never cleared on transfer. When a locked body NFT is transferred, the new owner inherits the lock and cannot change outfits until it expires. Equipped outfits also travel with the body -- the new owner can unequip them after the lock expires. Sellers should unequip valuable outfits before transferring a body.
-
-## Example Integration
-
-```solidity
-import {IBanny721TokenUriResolver} from "@bannynet/core-v6/src/interfaces/IBanny721TokenUriResolver.sol";
-
-// --- Get the composed SVG for a dressed Banny ---
-
-string memory svg = resolver.svgOf(
-    hookAddress,
-    bannyBodyTokenId,
-    true,  // dress the banny with attached outfits
-    true   // include the attached background
-);
-
-// --- 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)
-
-// Caller must own the body, background, and all outfits on the same hook
-resolver.decorateBannyWith(
-    hookAddress,
-    bannyBodyTokenId,
-    backgroundTokenId,
-    outfitIds  // MUST be in ascending category order
-);
+## Purpose
 
-// --- Lock outfit changes for 7 days ---
+Application-layer token URI resolver for Juicebox 721 collections that lets Banny body NFTs equip outfit and background NFTs, custody them while equipped, and render fully on-chain layered SVG metadata.
 
-resolver.lockOutfitChangesFor(hookAddress, bannyBodyTokenId);
+## Reference Files
 
-// --- Register and upload SVG content ---
+- Open [`references/runtime.md`](./references/runtime.md) when you need attachment and custody behavior, rendering order, or the main invariants that protect equipped assets.
+- Open [`references/operations.md`](./references/operations.md) when you need upload and metadata-management behavior, deployment breadcrumbs, or the common stale-data traps around SVG content and scripts.
 
-// 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);
+## Working Rules
 
-// Step 2: Anyone uploads matching content
-string[] memory contents = new string[](1);
-contents[0] = svgContent;
-resolver.setSvgContentsOf(upcs, contents);
-```
+- Start in [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) for both rendering and attachment behavior. This repo is mostly one contract with several tightly coupled responsibilities.
+- Treat custody, stale attachment cleanup, and lock timing as high-risk. Rendering bugs are visible, but custody bugs are worse.
+- When a task mentions minting, pricing, or terminal accounting, verify that the problem is not actually in the upstream 721 hook repo.
+- If you touch SVG or metadata behavior, check whether the issue is in stored content, rendering composition, or the hook-to-resolver integration point before patching.