@bannynet/core-v6 0.0.23 → 0.0.25

package/README.md

@@ -1,6 +1,6 @@
 # Banny Retail
 
-Banny Retail is an on-chain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, sit on a background NFT, and resolve to a base64-encoded JSON token URI whose image field contains an on-chain SVG.
+Banny Retail is an onchain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, use a background NFT, and resolve to a base64 JSON token URI whose image is an onchain SVG.
 
 Docs: <https://docs.juicebox.money>
 Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
@@ -12,34 +12,32 @@ Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-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.
+This is a resolver-centric app built on top of [`@bananapus/721-hook-v6`](https://www.npmjs.com/package/@bananapus/721-hook-v6). The resolver holds attached outfit and background NFTs while a body is decorated, then composes the active layers into a single token URI response.
 
 The main user flows are:
 
 - 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
+- optionally freeze the look for seven days with `lockOutfitChangesFor`
+- upload SVG payloads after an owner registers the content hashes
 
-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.
-
-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.
+Use this repo when you need collection-specific, fully onchain metadata composition on top of Juicebox NFTs. Do not use it as a generic 721 hook. It is an app-layer resolver, not a protocol NFT primitive.
 
 ## Key Contract
 
 | Contract | Role |
 | --- | --- |
-| `Banny721TokenUriResolver` | Resolves token metadata, stores equipped accessories, enforces outfit locks, and renders layered SVG output for Banny collections. |
+| `Banny721TokenUriResolver` | Resolves metadata, stores equipped accessories, enforces outfit locks, and renders layered SVG output for Banny collections. |
 
 ## Mental Model
 
 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
+1. custody of outfit and background NFTs while they are equipped
+2. rules for what a body can wear and when that can change
+3. rendering of the final metadata payload
 
-It does not own mint pricing, tier issuance, or project accounting.
+It does not own mint pricing, tier issuance, or treasury accounting.
 
 ## Read These Files First
 
@@ -58,12 +56,11 @@ It does not own mint pricing, tier issuance, or project accounting.
 
 ## Integration Traps
 
-- the resolver custodies equipped assets, so transfer edge cases matter as much as rendering output
-- transferred bodies carry their equipped assets, so a new body holder can inherit control of those items
-- burned bodies and non-safe transfer patterns can strand expectations around resolver-held assets unless integrations model the attachment lifecycle correctly
-- outfit locks persist across body transfers until expiry, so a new holder can inherit a still-locked body
-- metadata quality depends on lazily uploaded asset payloads, not only on the token state
-- collection logic here assumes a Juicebox 721 hook upstream and should not be read as a generic NFT renderer
+- the resolver holds equipped assets, so transfer edge cases matter as much as rendering output
+- transferred bodies carry their equipped assets, so a new body holder can inherit control of them
+- burned bodies and non-safe transfer patterns can strand expectations around resolver-held assets
+- outfit locks survive body transfers until expiry
+- metadata quality depends on lazily uploaded asset payloads, not only token state
 
 ## Where State Lives
 
@@ -83,8 +80,8 @@ The contract stack relies on `via_ir = true` in `foundry.toml`.
 
 ```bash
 npm install
-forge build
-forge test
+forge build --deny notes
+forge test --deny notes
 ```
 
 Useful scripts:
@@ -96,7 +93,7 @@ Useful scripts:
 
 ## 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.
+Deployments are handled through Sphinx using the environments configured in `script/Deploy.s.sol`. The resolver is meant to be plugged into a Juicebox 721 hook as that hook's token URI resolver.
 
 ## Repository Layout
 
@@ -115,14 +112,14 @@ script/
 
 ## Risks And Notes
 
-- attached outfits and backgrounds are custodied by the resolver while equipped
+- attached outfits and backgrounds are held by the resolver while equipped
 - outfit locks are fixed-duration and cannot be shortened once set
-- on-chain SVG content is immutable once uploaded for a given registered hash
-- ERC-721 `transferFrom` paths that bypass safe-receive checks can still create asset-tracking surprises around resolver custody
-- rendering quality and metadata correctness depend on the integrity of uploaded SVG assets
+- onchain SVG content is immutable once uploaded for a committed hash
+- plain `transferFrom` can still create asset-tracking surprises around resolver custody
+- rendering quality depends on the integrity of uploaded SVG assets
 
 ## For AI Agents
 
-- Treat this repo as an application-layer resolver, not as the NFT issuance primitive.
+- Treat this repo as an app-layer resolver, not as the NFT issuance primitive.
 - Start with `Banny721TokenUriResolver` and the lifecycle tests before summarizing attachment behavior.
-- If the question is about mint economics or tier availability, inspect `nana-721-hook-v6` instead of inferring from this repo.
+- If the question is about mint economics or tier availability, inspect `nana-721-hook-v6` instead.

package/foundry.toml

@@ -15,7 +15,8 @@ depth = 100
 fail_on_revert = false
 
 [lint]
-exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
+exclude_lints = ["mixed-case-variable", "pascal-case-struct"]
+
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@bannynet/core-v6",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mejango/banny-retail-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/Add.Denver.s.sol",
+    "script/Deploy.s.sol",
+    "script/Drop1.s.sol",
+    "script/helpers/",
+    "script/outfit_drop/",
+    "src/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -20,18 +32,16 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'banny-core-v6'"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.35",
-    "@bananapus/core-v6": "^0.0.34",
-    "@bananapus/permission-ids-v6": "^0.0.17",
-    "@bananapus/router-terminal-v6": "^0.0.26",
-    "@bananapus/suckers-v6": "^0.0.25",
-    "@croptop/core-v6": "^0.0.33",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@rev-net/core-v6": "^0.0.32",
-    "keccak": "^3.0.4"
+    "@bananapus/721-hook-v6": "0.0.43",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/router-terminal-v6": "0.0.36",
+    "@bananapus/suckers-v6": "0.0.33",
+    "@openzeppelin/contracts": "5.6.1",
+    "@rev-net/core-v6": "0.0.39",
+    "keccak": "3.0.4"
   },
   "devDependencies": {
-    "@bananapus/address-registry-v6": "^0.0.17",
-    "@sphinx-labs/plugins": "^0.33.3"
+    "@bananapus/address-registry-v6": "0.0.25",
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/src/Banny721TokenUriResolver.sol

@@ -291,6 +291,8 @@ contract Banny721TokenUriResolver is
 
             // If the token has an owner, check if the owner has locked the token.
             uint256 lockedUntil = outfitLockedUntil[hook][tokenId];
+            // Outfit locks are user-selected display locks; timestamp tolerance is acceptable here.
+            // forge-lint: disable-next-line(block-timestamp)
             if (lockedUntil > block.timestamp) {
                 extraMetadata = string.concat(extraMetadata, '"changesLockedUntil": ', lockedUntil.toString(), ",");
                 attributes = string.concat(
@@ -945,6 +947,8 @@ contract Banny721TokenUriResolver is
     /// @param bannyBodyId The body currently using the asset.
     /// @param exemptBodyId The destination body currently being decorated.
     function _revertIfBodyLocked(address hook, uint256 bannyBodyId, uint256 exemptBodyId) internal view {
+        // Outfit locks are user-selected display locks; timestamp tolerance is acceptable here.
+        // forge-lint: disable-next-line(block-timestamp)
         if (bannyBodyId != 0 && bannyBodyId != exemptBodyId && outfitLockedUntil[hook][bannyBodyId] > block.timestamp) {
             revert Banny721TokenUriResolver_OutfitChangesLocked();
         }
@@ -1118,6 +1122,8 @@ contract Banny721TokenUriResolver is
         }
 
         // Can't decorate a banny that's locked.
+        // Outfit locks are user-selected display locks; timestamp tolerance is acceptable here.
+        // forge-lint: disable-next-line(block-timestamp)
         if (outfitLockedUntil[hook][bannyBodyId] > block.timestamp) {
             revert Banny721TokenUriResolver_OutfitChangesLocked();
         }

package/ADMINISTRATION.md

@@ -1,87 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | `Banny721TokenUriResolver` metadata, SVG commitments, and outfit-state control |
-| Control posture | Global `Ownable` metadata control plus per-body owner control |
-| Highest-risk actions | Wrong SVG hash commitments, incorrect metadata updates, and long outfit locks |
-| Recovery posture | Metadata is editable, but committed hashes, uploaded SVGs, and active locks are not reversible |
-
-## Purpose
-
-`banny-retail-v6` has a small but real control plane. The resolver owner controls collection-wide metadata and SVG commitments. Body owners control decoration and outfit locks. No admin can rescue equipped NFTs from custody if resolver logic fails.
-
-## Control Model
-
-- `Banny721TokenUriResolver` is `Ownable`.
-- Global admin power is limited to metadata, product naming, and SVG hash commitments.
-- Actual SVG payload upload is permissionless once the hash is committed.
-- Body owners control decoration and locking for their own bodies.
-- Equipped accessories are held custodially by the resolver while attached.
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Resolver owner | `Ownable(owner)` at construction | Global | Can transfer ownership with OpenZeppelin `transferOwnership()` |
-| Body owner | `IERC721(hook).ownerOf(bannyBodyId)` | Per body | Can decorate and lock that body |
-| Anyone | No assignment | Global | Can upload SVG bytes only if they match a committed hash |
-
-## Privileged Surfaces
-
-| Contract | Function | Who Can Call | Effect |
-| --- | --- | --- | --- |
-| `Banny721TokenUriResolver` | `setMetadata(...)` | Resolver owner | Changes global description, URL, and base URI |
-| `Banny721TokenUriResolver` | `setProductNames(...)` | Resolver owner | Changes display names for products |
-| `Banny721TokenUriResolver` | `setSvgHashesOf(...)` | Resolver owner | Commits write-once SVG hashes for UPCs |
-| `Banny721TokenUriResolver` | `setSvgContentsOf(...)` | Anyone with matching bytes | Uploads write-once SVG payloads for committed hashes |
-| `Banny721TokenUriResolver` | `decorateBannyWith(...)` | Current body owner | Equips or unequips accessories and updates custody |
-| `Banny721TokenUriResolver` | `lockOutfitChangesFor(...)` | Current body owner | Extends the outfit lock window for that body |
-
-## Immutable And One-Way
-
-- SVG hash commitments are write-once.
-- SVG contents are write-once once uploaded.
-- `lockOutfitChangesFor(...)` only extends the active lock; it never shortens it.
-- The lock duration is fixed by the `_LOCK_DURATION` constant.
-- Default art fragments, category semantics, and the trusted forwarder are constructor or code immutables.
-
-## Operational Notes
-
-- Treat `setSvgHashesOf(...)` like a release gate. A wrong hash usually means new resolver or new UPC strategy, not an edit.
-- Treat `setMetadata(...)` and `setProductNames(...)` as collection-wide display changes.
-- Remind users that equipped assets are in resolver custody while attached.
-- Only lock outfits when temporary non-editability is the intended user experience.
-- Use safe ERC-721 transfer flows when assets are sent into the resolver path; plain `transferFrom` can bypass receiver checks and strand NFTs without a recovery path.
-
-## Machine Notes
-
-- Do not infer a rescue path for equipped assets; there is none in this contract.
-- Treat `src/Banny721TokenUriResolver.sol` as the source of truth for lock extension and write-once SVG behavior.
-- If a committed hash and intended asset bytes differ, stop; the contract does not support overwrite repair.
-- If an asset arrived through non-safe ERC-721 transfer semantics, do not assume the resolver can detect or recover it.
-
-## Recovery
-
-- Bad metadata can be changed by the owner.
-- Bad SVG commitments or uploaded content cannot be corrected in place.
-- If equipped assets become stuck because of resolver logic, there is no owner rescue path in this contract.
-- If NFTs are stranded through non-safe transfer semantics, this contract does not provide a recovery flow.
-
-## Admin Boundaries
-
-- The owner cannot withdraw equipped user NFTs arbitrarily.
-- The owner cannot overwrite committed hashes or uploaded SVG contents.
-- The owner cannot bypass body-owner checks on decoration or locking.
-- Nobody can shorten an active outfit lock.
-- There is no pause, upgrade, or rescue mechanism.
-
-## Source Map
-
-- `src/Banny721TokenUriResolver.sol`
-- `src/interfaces/IBanny721TokenUriResolver.sol`
-- `script/Deploy.s.sol`
-- `test/TestAuditGaps.sol`
-- `test/TestQALastMile.t.sol`

package/ARCHITECTURE.md

@@ -1,101 +0,0 @@
-# Architecture
-
-## Purpose
-
-`banny-retail-v6` is the Banny-specific metadata and attachment layer for Juicebox 721 collections. It does not mint the NFTs or own treasury logic. It owns attachment custody, outfit-lock rules, and final token rendering.
-
-## System Overview
-
-The repo is centered on `Banny721TokenUriResolver`. A 721 hook from `nana-721-hook-v6` points to this resolver for `tokenURI(...)`, while bodies, outfits, and backgrounds remain separate NFTs at the collection layer. The resolver escrows equipped accessories, records which assets are attached to each body, and composes the final SVG and JSON metadata on demand.
-
-## Core Invariants
-
-- A body can only reference accessories that are currently escrowed by the resolver.
-- Replacing an equipped item must atomically return the old item and escrow the new item.
-- Outfit locks must block both explicit removal and implicit replacement until the lock expires.
-- Equipped assets travel with the body NFT on transfer until the new owner unequips them.
-- Registered SVG payloads must match their pre-registered content hash before they become renderable.
-- Rendering must stay deterministic for the same stored body state.
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `Banny721TokenUriResolver` | Escrow, attachment state, lock windows, and metadata rendering | Main contract; application-specific |
-| `IBanny721TokenUriResolver` | External integration surface | Used by hooks and offchain tooling |
-
-## Trust Boundaries
-
-- Minting, ownership transfer, and collection-level ERC-721 semantics live in `nana-721-hook-v6`.
-- This repo is trusted for rendering correctness and custody of equipped assets.
-- Asset content upload is controlled by the registered content owner, but the contract verifies the uploaded bytes against the stored hash.
-
-## Critical Flows
-
-### Decorate
-
-```text
-body owner
-  -> calls decorateBannyWith(...)
-  -> resolver verifies body ownership and lock status
-  -> resolver pulls new accessories into escrow
-  -> resolver updates equipped slots
-  -> resolver returns replaced accessories to the owner
-```
-
-### Render
-
-```text
-tokenURI(bodyId)
-  -> resolver loads body, background, and equipped slot state
-  -> fetches registered SVG fragments
-  -> composes layered SVG in Banny-specific order
-  -> returns base64 JSON metadata
-```
-
-### Lock Outfit
-
-```text
-body owner
-  -> calls lockOutfitChangesFor(...)
-  -> resolver stores a no-change window
-  -> later decoration and removal paths must respect it
-```
-
-## Accounting Model
-
-This repo does not own treasury accounting. Its critical state is custody accounting: which NFTs are escrowed, which body they belong to, and when a body is locked against changes.
-
-That custody model uses lazy reconciliation for some stale attachment records. Read paths filter against current ownership and attachment state instead of eagerly rewriting storage on every external transfer.
-
-## Security Model
-
-- The main failure mode is custody drift between slot state and actual escrowed NFTs.
-- Rendering order is part of application semantics, not cosmetic output.
-- Lazy reconciliation is intentional. Changes that assume attachment arrays are perfectly clean in storage can strand assets or mis-render bodies.
-- Any new asset category adds both a rendering concern and a custody concern.
-
-## Safe Change Guide
-
-- Keep generic ERC-721 behavior in `nana-721-hook-v6`, not here.
-- Review escrow writes and transfer behavior together whenever changing attachment logic.
-- If transfer or cleanup behavior changes, re-check lazy reconciliation assumptions alongside body-transfer inheritance of equipped assets.
-- If `tokenURI(...)` changes, test stable output for unchanged state and replacement behavior for changed state.
-- If adding slots or asset classes, update rendering order, slot replacement, and lock enforcement in one change.
-
-## Canonical Checks
-
-- accessory escrow, replacement, and decoration flow:
-  `test/DecorateFlow.t.sol`
-- burned-body custody edge cases:
-  `test/audit/BurnedBodyStrandsAssets.t.sol`
-- transfer-path protection against stranded attachments:
-  `test/audit/TryTransferFromStrandsAssets.t.sol`
-
-## Source Map
-
-- `src/Banny721TokenUriResolver.sol`
-- `test/DecorateFlow.t.sol`
-- `test/audit/BurnedBodyStrandsAssets.t.sol`
-- `test/audit/TryTransferFromStrandsAssets.t.sol`
-- `script/Deploy.s.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,75 +0,0 @@
-# Audit Instructions
-
-This repo is the Banny avatar composition layer. It does not mint the base NFTs, but it does custody equipped accessories and define the metadata users see.
-
-## Audit Objective
-
-Find issues that:
-- strand outfits or backgrounds in resolver custody
-- let the wrong actor equip, unequip, overwrite, or recover accessories
-- break outfit-lock timing or freeze a body longer than intended
-- return metadata that does not match stored attachment state
-- bypass category or layering constraints
-
-## Scope
-
-In scope:
-- `src/Banny721TokenUriResolver.sol`
-- `src/interfaces/IBanny721TokenUriResolver.sol`
-- all deployment helpers in `script/`
-
-## Start Here
-
-1. `src/Banny721TokenUriResolver.sol`
-2. accessory receipt and release paths
-3. deployment wiring in `script/`
-
-## Security Model
-
-The resolver is an attachment and rendering layer around a `JB721TiersHook` collection.
-- the underlying 721 hook remains the token contract and source of body ownership
-- the resolver temporarily holds accessory NFTs while they are equipped
-- body ownership should be the only authority that changes equipped state
-- accessory contracts may be hostile or malformed, so receipt and release ordering matters
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Body owner | Equip, unequip, and lock accessories | Must be derived from the current hook-reported owner |
-| Resolver owner | Update metadata and SVG-related admin state | Must not control equipped-state authorization |
-| Accessory NFT contract | Execute callbacks during custody changes | Must not corrupt bookkeeping or steal custody |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| `JB721TiersHook` | Reports authentic body ownership and tier metadata | Unauthorized decoration or incorrect rendering |
-| Accessory ERC-721s | Behave like standard transferable NFTs | Custody or release flows fail unexpectedly |
-
-## Critical Invariants
-
-1. Every accessory transferred into the resolver remains attributable to one body or is recoverable by the rightful owner.
-2. Only the current body owner or an intended delegate can change that body's equipped state.
-3. Conflicting categories cannot be equipped together, including through replacement or invalidation edge paths.
-4. Outfit-lock state only affects the intended body for the intended duration.
-5. Metadata and SVG generation reflect current state and do not expose impossible combinations.
-
-## Attack Surfaces
-
-- decoration entrypoints that replace one accessory with another
-- ERC-721 receipt hooks and any path that accepts custody
-- release paths after redecorating, burning, or invalid token state
-- category validation and conflict checks
-- metadata assembly that assumes on-chain assets or tier data remain available
-
-## Accepted Risks Or Behaviors
-
-- Equipped accessories intentionally follow the body unless they are unequipped first.
-- Preserving attribution on failed transfer-out is safer than dropping custody state.
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`

package/RISKS.md

@@ -1,89 +0,0 @@
-# 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
-
-- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted for all ownership checks in `decorateBannyWith`, `lockOutfitChangesFor`, and admin functions. A compromised forwarder can dress/undress any banny and steal equipped outfits.
-- **Hook contract.** The `hook` parameter is caller-supplied and not validated against any registry. A malicious hook contract could return arbitrary tier data, manipulate ownership checks, or trap NFTs.
-- **Owner (Ownable).** The contract owner controls SVG hashes, product names, and metadata URIs. A compromised owner can set malicious SVG content hashes, enabling XSS via on-chain SVG injection after the matching content is uploaded.
-- **721 hook store.** `_storeOf(hook)` calls `IJB721TiersHook(hook).STORE()` -- trusts the hook to return a legitimate store. A malicious hook can return a fake store with manipulated tier data.
-
-## 2. Economic / Manipulation Risks
-
-- **Outfit theft via banny body transfer.** Equipped outfits and backgrounds travel with the banny body NFT on transfer. If a banny body is sold with valuable outfits equipped, the buyer gains control of all equipped items. Sellers must unequip before selling. Marketplaces may not surface this risk.
-- **try-catch silent failures with retention.** `_tryTransferFrom` silently catches all transfer failures and returns `false`. When a transfer fails, the resolver preserves the attachment record instead of clearing state. For backgrounds, the entire background change is aborted. For outfits, failed-to-return items are retained in the attached list via `_storeOutfitsWithRetained`. This prevents NFT stranding — assets remain tracked and recoverable once the transfer issue is resolved (e.g., the owner contract becomes receivable). However, if an outfit NFT is burned or its tier removed, the retained record refers to a non-existent asset, creating a phantom entry in the SVG rendering.
-- **Lock griefing.** `lockOutfitChangesFor` extends the lock to `block.timestamp + 7 days`. Locking just before selling prevents the buyer from changing outfits for up to 7 days. The lock now also freezes reassignment of currently equipped outfits/backgrounds away from that body during the lock window.
-
-## 3. Access Control
-
-- **No hook validation (HIGH impact).** Any address can be passed as `hook`. A malicious hook can return `_msgSender()` from `ownerOf()` to pass authorization checks, execute arbitrary code during `safeTransferFrom`, or return manipulated tier data from `STORE().tierOfTokenId()`.
-- **SVG content upload is permissionless (with hash).** `setSvgContentsOf` only requires the content to match a pre-committed hash. Safe if hashes are correctly committed.
-- **onERC721Received restriction.** Only accepts NFTs when `operator == address(this)`. `transferFrom` (non-safe) bypasses this -- NFTs sent via `transferFrom` are permanently locked with no rescue function.
-
-## 4. DoS Vectors
-
-- **External call iteration scales with outfit count.** `_attachedOutfitIdsOf[hook][bannyBodyId]` is replaced wholesale on each `decorateBannyWith` call (not appended to), so the array is bounded by the number of currently equipped outfits, not cumulative history. However, `decorateBannyWith` iterates over both the previous and new outfit arrays to diff them (transferring removed outfits back and new outfits in), so gas cost scales with the number of outfits being equipped/unequipped in a single call.
-- **External hook calls in view functions.** `tokenUriOf` and `svgOf` call into the hook's store multiple times per outfit. A malicious hook that consumes excessive gas or reverts can make token metadata unretrievable. Measured: `tokenUriOf` with a well-behaved hook and 9 equipped outfits costs ~609k gas (see `test_tokenUri_gasSnapshot_9outfits`). The practical ceiling for a malicious hook is bounded only by the caller's gas limit — RPC nodes typically cap `eth_call` at 30M+ gas, so even expensive hooks won't fail for off-chain reads, but on-chain consumers (e.g., other contracts calling `tokenURI`) could revert.
-
-## 5. Integration Risks
-
-- **Cross-contract NFT custody.** Outfits are held by `Banny721TokenUriResolver` via `safeTransferFrom`. If approval is revoked on the hook contract, equipping fails.
-- **Tier removal desync.** If a tier is removed from the 721 hook while an outfit from that tier is equipped, `_productOfTokenId` returns a product with `id == 0`. The outfit remains equipped but renders as empty. `_tryTransferFrom` may fail silently when trying to return it.
-- **Non-safe transfer loss.** Outfits sent directly to this contract via `transferFrom` (not `safeTransferFrom`) are permanently stuck since there is no rescue function.
-- **ReentrancyGuard.** `decorateBannyWith` uses `nonReentrant`, but `lockOutfitChangesFor` and view functions do not. Reentrancy through hook callbacks is possible but state updates follow CEI pattern.
-
-## 6. Invariants to Verify
-
-- Every outfit held by this contract has a corresponding `_wearerOf[hook][outfitId]` pointing to a valid banny body.
-- Every background held by this contract has a corresponding `_userOf[hook][backgroundId]` pointing to a valid banny body.
-- `outfitLockedUntil[hook][bannyBodyId]` is monotonically non-decreasing per banny body (lock can only be extended, never shortened).
-- After `decorateBannyWith`, all previously equipped outfits not in the new set are either transferred back to `_msgSender()` or retained in the attached list if the transfer failed.
-- `_attachedOutfitIdsOf[hook][bannyBodyId]` contains the outfitIds passed to the most recent `decorateBannyWith` call, plus any retained outfits whose return transfer failed. Category exclusivity is enforced on the merged set (retained + new outfits), not just the new outfit set alone. Additionally, duplicate categories in the merged set are rejected with `Banny721TokenUriResolver_DuplicateCategory()` to prevent retained outfits from silently duplicating a category supplied in the new set.
-- SVG content integrity: `keccak256(_svgContentOf[upc]) == svgHashOf[upc]` for all populated entries.
-- NFT custody balance: the number of outfit NFTs held by this contract (`IERC721(hook).balanceOf(address(this))`) equals the total number of outfits currently equipped across all banny bodies for that hook. Violations indicate phantom outfits (equipped in state but NFT lost via try-catch silent failure) or orphaned NFTs (held by contract but not tracked in `_wearerOf`).
-
-## 7. Accepted Behaviors
-
-### 7.1 Failed transfers retain attachment records (anti-stranding)
-
-`_tryTransferFrom` catches all transfer failures and returns `false`. When returning a previously equipped item fails, the resolver preserves the attachment record rather than clearing state:
-
-- **Backgrounds**: If returning the old background fails, the entire background change is aborted (`return` in `_decorateBannyWithBackground`). The old background stays attached and the new one is not equipped.
-- **Background removal**: If returning the background fails during removal (backgroundId=0), `_attachedBackgroundIdOf` is not cleared. The background stays attached.
-- **Outfits**: Failed-to-return outfits remain non-zero in the `previousOutfitIds` array. `_storeOutfitsWithRetained` appends them to the new outfit list, preserving their attachment record. After merging, the resolver verifies no two outfits share the same category (reverts with `DuplicateCategory` if a retained outfit conflicts with a newly supplied one).
-
-This prevents NFT stranding — assets held by the resolver stay tracked and recoverable. Once the transfer issue is resolved (e.g., the owner contract implements `IERC721Receiver`), a subsequent `decorateBannyWith` call will successfully return the retained items.
-
-For permanently unrecoverable assets (burned NFTs, removed tiers), the retained record creates a phantom entry in the SVG rendering and attached list. This is cosmetically incorrect but not economically exploitable — phantom entries cannot be transferred or sold. The alternative — reverting on any failed transfer — would make `decorateBannyWith` fragile: a single burned outfit would prevent the banny owner from changing ANY outfits.
-
-### 7.2 Lock griefing window is bounded at 7 days
-
-`lockOutfitChangesFor` extends the lock to `block.timestamp + 7 days`. A seller who locks just before transferring the banny forces the buyer to wait up to 7 days. This is accepted because: (1) marketplaces can check `outfitLockedUntil` before displaying the item, (2) the lock duration is fixed (not owner-configurable), and (3) the lock prevents a more severe attack where a buyer immediately strips valuable outfits — the lock gives the previous owner time to arrange the sale intentionally.
-
-### 7.3 On-chain SVG rendering gas is well within limits
-
-`tokenUriOf` constructs full SVGs on-chain with string concatenation. Measured gas ceiling: ~609K gas for the worst case (9 non-conflicting outfits + background with on-chain SVG content), well within typical RPC node limits (30M+). Regression test: `test_tokenUri_gasSnapshot_9outfits` in `test/TestQALastMile.t.sol`.
-
-### 7.4 Outfits burn alongside the body
-
-When a banny body NFT is burned (e.g. via cash-out), any equipped outfits and backgrounds held by the resolver are permanently unrecoverable. The resolver has no recovery function and this is intentional — outfits are part of the body's identity and share its fate. Users who want to preserve outfits must unequip them before burning the body.
-
-### 7.5 Reentrancy in non-guarded functions is harmless
-
-`lockOutfitChangesFor` and all view functions (`tokenUriOf`, `svgOf`) are not protected by `nonReentrant`. A malicious hook's `STORE().tierOfTokenId()` could re-enter `lockOutfitChangesFor` during a `tokenUriOf` call, but this is harmless -- `lockOutfitChangesFor` only extends the lock timestamp (monotonically non-decreasing) and has no state that could be corrupted by reentrancy. The view functions themselves are read-only at the contract level (no storage writes), so reentrancy through them cannot extract value.

package/SKILLS.md

@@ -1,42 +0,0 @@
-# Banny Retail
-
-## Use This File For
-
-- Use this file when the task involves Banny outfit attachment, layered SVG rendering, token URI composition, or asset custody and lock behavior.
-- Start here, then decide whether the issue is custody state, lock semantics, stored SVG content, or final token-URI composition. Those problems often look similar from the outside.
-
-## Read This Next
-
-| 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) |
-| Runtime and content-management invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
-| Deployment or scripted drops | [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/Drop1.s.sol`](./script/Drop1.s.sol), [`script/Add.Denver.s.sol`](./script/Add.Denver.s.sol) |
-| Decoration lifecycle and custody invariants | [`test/DecorateFlow.t.sol`](./test/DecorateFlow.t.sol), [`test/OutfitTransferLifecycle.t.sol`](./test/OutfitTransferLifecycle.t.sol) |
-| Adversarial, fork, or final QA coverage | [`test/BannyAttacks.t.sol`](./test/BannyAttacks.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol), [`test/TestQALastMile.t.sol`](./test/TestQALastMile.t.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contract | [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) |
-| Scripts | [`script/`](./script/) |
-| Tests | [`test/`](./test/) |
-
-## Purpose
-
-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.
-
-## Reference Files
-
-- 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.
-
-## Working Rules
-
-- Start in [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) for both rendering and attachment behavior. This repo is mostly one contract with several tightly coupled responsibilities.
-- Treat custody, stale attachment cleanup, and lock timing as high-risk. Rendering bugs are visible, but custody bugs are worse.
-- Equipped outfits and backgrounds travel with the body NFT. Treat that inheritance behavior as intentional before calling it a custody bug.
-- When a task mentions minting, pricing, or terminal accounting, verify that the problem is not actually in the upstream 721 hook repo.
-- If you touch SVG or metadata behavior, check whether the issue is in stored content, rendering composition, or the hook-to-resolver integration point before patching.