@bannynet/core-v6 0.0.10 → 0.0.12

package/README.md

@@ -8,6 +8,8 @@ On-chain composable avatar system for Juicebox 721 collections -- manages Banny
 
 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.
 
+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.
+
 ### How It Works
 
 ```
@@ -23,7 +25,8 @@ Banny is a composable NFT character system built on top of Juicebox 721 hooks. E
    → Body's tokenURI now renders the full dressed composition
    |
 4. Outfit lock (optional): lockOutfitChangesFor(hook, bodyId)
-   → Freezes outfit changes for 7 days
+   → 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:
@@ -32,6 +35,41 @@ Banny is a composable NFT character system built on top of Juicebox 721 hooks. E
    → Falls back to IPFS base URI if on-chain content not yet stored
 ```
 
+### 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
+```
+
 ### Asset Categories
 
 | Category ID | Name | Slot Rules |
@@ -92,20 +130,32 @@ Requires `via_ir = true` in foundry.toml due to stack depth in SVG composition.
 | Command | Description |
 |---------|-------------|
 | `forge build` | Compile contracts (requires via-IR) |
-| `forge test` | Run all tests (3 test files: functionality, attacks, decoration flows) |
+| `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 |
 
 ## Repository Layout
 
 ```
 src/
-  Banny721TokenUriResolver.sol                  # Sole contract (~1,331 lines)
+  Banny721TokenUriResolver.sol                  # Sole contract (~1,428 lines)
   interfaces/
     IBanny721TokenUriResolver.sol               # Public interface + events
 test/
-  Banny721TokenUriResolver.t.sol                # Unit tests (~690 lines)
-  BannyAttacks.t.sol                            # Security/adversarial tests (~323 lines)
-  DecorateFlow.t.sol                            # Decoration flow tests (~1,057 lines)
+  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
 script/
   Deploy.s.sol                                  # Sphinx multi-chain deployment
   Drop1.s.sol                                   # Outfit drop deployment
@@ -126,9 +176,24 @@ script/
 | `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 the contract has a bug in the return logic, assets could be stuck.
+- **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.

package/RISKS.md

@@ -10,20 +10,19 @@
 ## 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.** `_tryTransferFrom` silently catches all transfer failures. If an outfit NFT is burned or its tier removed, the transfer fails silently. The outfit remains logically "equipped" in state but the NFT is lost. This can create phantom outfits that show in SVG rendering but cannot be recovered.
-- **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.
+- **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.** 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()`.
+- **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
 
-- **Unbounded outfit iteration.** `_attachedOutfitIdsOf` array grows with each decoration and is never compacted. Over time with repeated equip/unequip cycles, gas costs increase.
-- **On-chain SVG rendering gas.** `tokenUriOf` constructs full SVGs on-chain with string concatenation. Complex outfits with many layers can exceed block gas limits for `view` calls, making tokens unrenderable by off-chain indexers. 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`.
-- **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.
+- **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
 
@@ -37,6 +36,33 @@
 - 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 transferred back to `_msgSender()` (or silently failed via try-catch).
-- `_attachedOutfitIdsOf[hook][bannyBodyId]` matches the outfitIds passed to the most recent `decorateBannyWith` call.
+- 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.
 - 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.
+
+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 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

@@ -23,7 +23,7 @@ On-chain composable NFT avatar system that renders Banny characters with layered
 
 | Function | What it does |
 |----------|-------------|
-| `decorateBannyWith(hook, bannyBodyId, backgroundId, outfitIds)` | Attaches background and outfits to a body. Transfers assets to contract custody. Validates ownership, lock status, category ordering, slot conflicts. Returns previously attached items to caller. Emits `DecorateBanny`. |
+| `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
@@ -58,6 +58,46 @@ On-chain composable NFT avatar system that renders Banny characters with layered
 | `@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
+
+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:
+
+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
+
+For non-body tokens (outfits, backgrounds), the item is rendered on a grayscale mannequin Banny (`fill:#808080`) for preview.
+
+## SVG Format Requirements
+
+- **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.
+
 ## Key Types
 
 ### Asset Categories
@@ -141,7 +181,7 @@ On-chain composable NFT avatar system that renders Banny characters with layered
 | `_svgContentOf` | `upc => string` | On-chain SVG content (immutable once set) |
 | `svgHashOf` | `upc => bytes32` | Expected SVG content hash (immutable once set) |
 | `_customProductNameOf` | `upc => string` | Human-readable product name |
-| `outfitLockedUntil` | `hook => upc => uint256` | Timestamp until outfit changes locked |
+| `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 |
@@ -157,7 +197,7 @@ On-chain composable NFT avatar system that renders Banny characters with layered
 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).
+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.
@@ -166,6 +206,7 @@ On-chain composable NFT avatar system that renders Banny characters with layered
 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
 

package/STYLE_GUIDE.md

@@ -21,7 +21,7 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;