@bannynet/core-v6 0.0.23 → 0.0.24

package/ADMINISTRATION.md

@@ -11,21 +11,21 @@
 
 ## 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.
+`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 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.
+- Actual SVG 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.
+- Equipped accessories are held by the resolver while attached.
 
 ## Roles
 
 | Role | How Assigned | Scope | Notes |
 | --- | --- | --- | --- |
-| Resolver owner | `Ownable(owner)` at construction | Global | Can transfer ownership with OpenZeppelin `transferOwnership()` |
+| Resolver owner | `Ownable(owner)` at construction | Global | Can transfer ownership with `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 |
 
@@ -44,35 +44,35 @@
 
 - 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.
+- `lockOutfitChangesFor(...)` only extends the active lock.
+- The lock duration is fixed by `_LOCK_DURATION`.
 - 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 `setSvgHashesOf(...)` like a release gate. A wrong hash usually means a new resolver or new UPC strategy, not a small 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.
+- Only lock outfits when temporary non-editability is the intended experience.
+- Use safe ERC-721 transfer flows when assets enter the resolver path. Plain `transferFrom` can strand NFTs without a recovery path.
 
 ## Machine Notes
 
-- Do not infer a rescue path for equipped assets; there is none in this contract.
+- Do not assume there is a rescue path for equipped assets. There is none.
 - 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 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.
+- If equipped assets become stuck because of resolver logic, there is no owner rescue path.
+- If NFTs are stranded through non-safe transfer semantics, this contract does not provide recovery.
 
 ## Admin Boundaries
 
-- The owner cannot withdraw equipped user NFTs arbitrarily.
+- The owner cannot arbitrarily withdraw equipped user NFTs.
 - 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.

package/ARCHITECTURE.md

@@ -2,33 +2,33 @@
 
 ## 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.
+`banny-retail-v6` is the Banny-specific metadata and attachment layer for Juicebox 721 collections. It does not mint 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.
+The repo centers on `Banny721TokenUriResolver`. A 721 hook from `nana-721-hook-v6` points to this resolver for `tokenURI(...)`. 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.
+- Equipped assets move with the body NFT on transfer until the new owner unequips them.
+- Registered SVG payloads must match their committed content hash before they can render.
 - 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 |
+| `Banny721TokenUriResolver` | Escrow, attachment state, lock windows, and metadata rendering | Main contract |
 | `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.
+- Asset-content upload is controlled by the registered content owner, but the contract verifies uploaded bytes against the stored hash.
 
 ## Critical Flows
 
@@ -66,20 +66,20 @@ body owner
 
 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.
+That custody model uses lazy reconciliation for some stale attachment records. Read paths filter against current ownership and attachment state instead of rewriting storage on every outside 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.
+- Rendering order is part of app semantics, not cosmetic output.
+- Lazy reconciliation is intentional. Changes that assume storage is always perfectly clean 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 transfer or cleanup behavior changes, re-check lazy reconciliation alongside body-transfer inheritance.
 - 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.
 

package/AUDIT_INSTRUCTIONS.md

@@ -1,10 +1,11 @@
 # 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.
+This repo is the Banny avatar composition layer. It does not mint the base NFTs, but it does hold 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
@@ -14,9 +15,10 @@ Find issues that:
 ## Scope
 
 In scope:
+
 - `src/Banny721TokenUriResolver.sol`
 - `src/interfaces/IBanny721TokenUriResolver.sol`
-- all deployment helpers in `script/`
+- deployment helpers in `script/`
 
 ## Start Here
 
@@ -27,6 +29,7 @@ In scope:
 ## 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
@@ -53,7 +56,7 @@ The resolver is an attachment and rendering layer around a `JB721TiersHook` coll
 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.
+5. Metadata and SVG generation reflect current state and do not show impossible combinations.
 
 ## Attack Surfaces
 
@@ -61,7 +64,7 @@ The resolver is an attachment and rendering layer around a `JB721TiersHook` coll
 - 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
+- metadata assembly that assumes onchain assets or tier data remain available
 
 ## Accepted Risks Or Behaviors
 

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
 
@@ -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/RISKS.md

@@ -1,89 +1,80 @@
 # 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.
+This file focuses on the failure modes that can break NFT custody, bypass hook 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.
+- Read `Priority risks` first.
+- Use `Accepted Behaviors` to separate intentional tradeoffs from 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. |
-
+| P0 | Untrusted `hook` or store integration | The resolver trusts the supplied hook for ownership checks, tier metadata, and transfers. A bad hook can fake authority or trap assets. | Restrict supported hooks, scrutinize the hook boundary, and test 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 asset is gone forever. | Explicit accepted-behavior rules, retained-item handling, and custody/state invariants. |
+| 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. |
 
 ## 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.
+- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted for ownership checks and admin functions.
+- **Hook contract.** The `hook` parameter is caller-supplied and not validated against a registry.
+- **Owner.** The contract owner controls SVG hashes, product names, and metadata URIs.
+- **721 hook store.** `_storeOf(hook)` trusts the hook to return a legitimate store.
 
-## 2. Economic / Manipulation Risks
+## 2. Economic And 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.
+- **Outfit theft via body transfer.** Equipped outfits and backgrounds move with the body NFT. If a body is sold while wearing valuable items, the buyer gains control of them.
+- **Try-catch silent failures with retention.** Failed transfer-outs preserve attachment records instead of clearing state. This avoids stranding but can create phantom render entries for burned or removed assets.
+- **Lock griefing.** `lockOutfitChangesFor` extends the lock to `block.timestamp + 7 days`. Locking just before a sale can block the buyer from changing the look for up to 7 days.
 
 ## 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.
+- **No hook validation.** Any address can be passed as `hook`. A malicious hook can fake `ownerOf`, execute arbitrary code during transfers, or return manipulated tier data.
+- **SVG content upload is permissionless once the hash is committed.** This is safe only if the committed hash is correct.
+- **`onERC721Received` restriction.** The contract only accepts NFTs when `operator == address(this)`. Plain `transferFrom` bypasses that and can permanently lock NFTs.
 
 ## 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.
+- **External call iteration scales with outfit count.** `decorateBannyWith` iterates both old and new outfit arrays, so gas cost scales with the number of outfits changed in one call.
+- **External hook calls in view functions.** `tokenUriOf` and `svgOf` call into the hook's store multiple times. A malicious or gas-heavy hook can make metadata unreadable.
 
 ## 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.
+- **Cross-contract NFT custody.** Outfits are held by the resolver via `safeTransferFrom`. If approval is revoked on the hook contract, equipping fails.
+- **Tier removal desync.** If a tier is removed while an outfit from that tier is equipped, the outfit may remain attached but render empty.
+- **Non-safe transfer loss.** Outfits sent directly via `transferFrom` can be permanently stuck because there is no rescue function.
+- **Reentrancy assumptions.** `decorateBannyWith` uses `nonReentrant`, but other functions rely on ordering and limited state impact instead.
 
 ## 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`).
+- Every outfit held by the contract has a corresponding wearer mapping to a valid body.
+- Every background held by the contract has a corresponding user mapping to a valid body.
+- `outfitLockedUntil` is monotonically non-decreasing per body.
+- After `decorateBannyWith`, old outfits not in the new set are either returned or explicitly retained because transfer-out failed.
+- Category exclusivity holds on the merged set of retained and newly supplied outfits.
+- SVG content integrity holds for all populated entries.
+- The number of held outfit NFTs should match the number of outfits still tracked as equipped for that hook.
 
 ## 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.
+### 7.1 Failed transfers retain attachment records
 
-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.
+If returning a previously equipped item fails, the resolver keeps the attachment record instead of dropping it. This avoids stranding NFTs held by the resolver, but it can leave cosmetic phantom state for permanently unrecoverable assets.
 
-### 7.2 Lock griefing window is bounded at 7 days
+### 7.2 Lock griefing 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.
+`lockOutfitChangesFor` can force a buyer to wait, but the window is fixed and cannot be extended arbitrarily beyond the current maximum.
 
-### 7.3 On-chain SVG rendering gas is well within limits
+### 7.3 Onchain SVG rendering gas is acceptable
 
-`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`.
+Full `tokenUriOf` rendering is expensive but still within practical RPC limits for the supported outfit counts.
 
 ### 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.
+If a body NFT is burned while outfits are equipped, those outfits are intentionally unrecoverable. Users who want to keep them must unequip first.
 
-### 7.5 Reentrancy in non-guarded functions is harmless
+### 7.5 Reentrancy in non-guarded functions is treated as harmless under the current model
 
-`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.
+`lockOutfitChangesFor` only extends a timestamp, and view functions do not write storage. That keeps the remaining reentrancy surface narrow.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## 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.
+- Start here, then decide whether the issue is custody state, lock timing, stored SVG content, or final token-URI composition.
 
 ## Read This Next
 
@@ -26,17 +26,17 @@
 
 ## 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.
+App-layer token URI resolver for Juicebox 721 collections. It lets Banny body NFTs equip outfit and background NFTs, holds them while equipped, and renders fully onchain 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.
+- Open [`references/runtime.md`](./references/runtime.md) for attachment and custody behavior, rendering order, and the main invariants that protect equipped assets.
+- Open [`references/operations.md`](./references/operations.md) for upload and metadata-management behavior, deployment breadcrumbs, and common stale-data traps around SVG content.
 
 ## 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.
+- Start in [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) for both rendering and attachment behavior.
 - 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.
+- Equipped outfits and backgrounds travel with the body NFT. Treat that inheritance as intentional before calling it a 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.

package/USER_JOURNEYS.md

@@ -2,9 +2,7 @@
 
 ## Repo Purpose
 
-This repo is the Banny-specific composition and metadata layer on top of a Juicebox 721 collection.
-It owns attachment custody, compatibility rules, outfit locks, and rendered token metadata. It does not own tier
-pricing, treasury accounting, or mint eligibility outside the resolver-specific checks.
+This repo is the Banny-specific composition and metadata layer on top of a Juicebox 721 collection. It owns attachment custody, compatibility rules, outfit locks, and rendered token metadata. It does not own tier pricing, treasury accounting, or mint eligibility outside resolver-specific checks.
 
 ## Primary Actors
 
@@ -15,7 +13,7 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 ## Key Surfaces
 
 - `Banny721TokenUriResolver`: custody, compatibility, locks, and rendered SVG metadata
-- `decorateBannyWith(...)`: equips outfits and a background to a body and returns no-longer-equipped items when possible
+- `decorateBannyWith(...)`: equips outfits and a background to a body and returns old items when possible
 - `lockOutfitChangesFor(...)`: freezes appearance changes for the fixed lock window
 - `setSvgHashesOf(...)` / `setSvgContentsOf(...)`: publish or repair art payloads
 - `setMetadata(...)` / `setProductNames(...)`: update collection metadata and UPC naming
@@ -27,21 +25,24 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 **Intent:** acquire the pieces needed to build a composed Banny.
 
 **Preconditions**
+
 - the Banny collection is live through the 721 hook
 - the required body, outfit, and background tiers exist
 
 **Main Flow**
+
 1. Mint the body, outfit, and background NFTs through the underlying 721 project.
 2. Keep mint pricing and issuance assumptions anchored in the 721 hook, not this repo.
-3. Move to this resolver only once the user actually owns compatible pieces.
+3. Move to this resolver only once the user owns compatible pieces.
 
 **Failure Modes**
-- the wrong tiers are minted or the pieces are not compatible
+
+- the wrong tiers are minted or the pieces are incompatible
 - teams misread this repo as the minting or accounting surface
 
 **Postconditions**
+
 - the user holds the components needed for later composition
-- mint pricing, reserves, and treasury effects still belong to the underlying 721 project rather than this resolver
 
 ## Journey 2: Dress A Banny And Put Accessories Into Resolver Custody
 
@@ -50,24 +51,28 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 **Intent:** equip a body with a background and outfits so the resolver serves the composed avatar.
 
 **Preconditions**
+
 - the caller controls the body and the accessories being equipped
 - no active outfit lock blocks the change
 - the selected pieces are compatible by category and collection rules
 
 **Main Flow**
+
 1. Call `decorateBannyWith(...)` for the target body.
 2. The resolver checks compatibility and diffs old versus new attachments.
 3. Equipped accessories move into resolver custody while attached.
 4. The token URI for the body now reflects the combined SVG and metadata.
 
 **Failure Modes**
+
 - duplicate outfit categories or incompatible combinations are provided
-- a transfer-back of previously attached items fails, leaving retained custody state that must be recovered later
-- reviewers forget that the resolver, not the user wallet, holds equipped accessories while active
+- transfer-back of previously attached items fails, leaving retained custody state for later recovery
+- reviewers forget that the resolver, not the wallet, holds equipped accessories while active
 
 **Postconditions**
-- the body renders with the newly attached composition
-- attached accessories remain in resolver custody until replaced or cleared
+
+- the body renders with the new composition
+- attached accessories stay in resolver custody until replaced or cleared
 
 ## Journey 3: Lock A Banny's Appearance For A Period
 
@@ -76,43 +81,51 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 **Intent:** freeze the current appearance for the fixed lock window.
 
 **Preconditions**
+
 - the body already has a state worth freezing
-- the caller understands the lock is intentionally fixed-duration
+- the caller understands the lock is fixed-duration
 
 **Main Flow**
+
 1. Call `lockOutfitChangesFor(...)`.
 2. The resolver extends the lock for that body.
 3. Future decoration or removal attempts must wait until the lock expires.
 
 **Failure Modes**
-- a seller locks just before transfer and the buyer cannot re-style immediately
-- integrations fail to surface lock state before listing or sale
+
+- a seller locks just before transfer and the buyer cannot restyle immediately
+- integrations fail to show lock state before listing or sale
 
 **Postconditions**
+
 - appearance changes are blocked until the lock expires
 
-## Journey 4: Publish Or Repair On-Chain Art Assets
+## Journey 4: Publish Or Repair Onchain Art Assets
 
 **Actor:** collection operator or art publisher.
 
 **Intent:** make token URIs render complete onchain art.
 
 **Preconditions**
+
 - the relevant UPCs and content hashes are known
-- the operator understands hashes are the commitment and SVG content must match them exactly
+- the operator understands that the hash is the commitment and SVG content must match it exactly
 
 **Main Flow**
+
 1. Register hashes with `setSvgHashesOf(...)`.
 2. Upload matching payloads with `setSvgContentsOf(...)`.
 3. Re-check token URI output after publication or repair.
 
 **Failure Modes**
-- the uploaded SVG does not match the committed hash
+
+- uploaded SVG does not match the committed hash
 - product names are missing or stale
 - teams assume the 721 hook owns rendered output when this repo does
 
 **Postconditions**
-- token URIs can render the intended onchain art payloads for published UPCs
+
+- token URIs can render the intended onchain art payloads
 
 ## Journey 5: Update Collection Metadata And Product Catalog Entries
 
@@ -121,19 +134,23 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 **Intent:** change collection-level metadata and human-readable product labels.
 
 **Preconditions**
+
 - the operator has authority over the resolver metadata surface
 
 **Main Flow**
+
 1. Update collection metadata with `setMetadata(...)`.
 2. Set or repair UPC names with `setProductNames(...)`.
 3. Re-check a representative token URI so labels and art agree.
 
 **Failure Modes**
+
 - metadata and SVG state drift apart
 - operators update catalog labels without checking already-minted assets
 
 **Postconditions**
-- collection-level metadata and UPC names line up with the currently published art set
+
+- collection-level metadata and UPC names line up with the published art set
 
 ## Journey 6: Unequip And Recover Custodied Accessories
 
@@ -142,20 +159,24 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 **Intent:** recover attached accessories from resolver custody.
 
 **Preconditions**
+
 - the current lock window, if any, has expired
-- the owner understands old pieces may only be returned as part of a later decoration update
+- the owner understands that old pieces may only be returned as part of a later decoration update
 
 **Main Flow**
+
 1. Replace or clear the equipped items through `decorateBannyWith(...)`.
 2. The resolver attempts to return no-longer-equipped accessories.
-3. Once returned, those NFTs can be transferred or re-used independently.
+3. Once returned, those NFTs can be transferred or reused independently.
 
 **Failure Modes**
+
 - previously equipped pieces remain retained because transfer-back failed
 - burned or otherwise unrecoverable pieces leave cosmetic phantom state until corrected
 
 **Postconditions**
-- no-longer-equipped accessories are either returned to the owner or remain explicitly retained pending recovery
+
+- no-longer-equipped accessories are either returned or remain explicitly retained pending recovery
 
 ## Trust Boundaries
 
@@ -166,4 +187,4 @@ pricing, treasury accounting, or mint eligibility outside the resolver-specific
 ## Hand-Offs
 
 - Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) for mint pricing, tier issuance, reserves, and treasury behavior.
-- Use this repo only once the question is about custody, compatibility, outfit locks, or SVG composition.
+- Use this repo once the question is about custody, compatibility, outfit locks, or SVG composition.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bannynet/core-v6",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,14 +20,14 @@
     "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",
+    "@bananapus/721-hook-v6": "^0.0.38",
+    "@bananapus/core-v6": "^0.0.36",
+    "@bananapus/permission-ids-v6": "^0.0.19",
+    "@bananapus/router-terminal-v6": "^0.0.30",
+    "@bananapus/suckers-v6": "^0.0.28",
+    "@croptop/core-v6": "^0.0.36",
     "@openzeppelin/contracts": "^5.6.1",
-    "@rev-net/core-v6": "^0.0.32",
+    "@rev-net/core-v6": "^0.0.35",
     "keccak": "^3.0.4"
   },
   "devDependencies": {