@croptop/core-v6 0.0.20 → 0.0.21

package/AUDIT_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 Audit preparation document for experienced Solidity auditors. This repo contains the Croptop content publishing system: three contracts that allow permissioned posting of NFT content as 721 tiers to Juicebox V6 projects, with fee accounting, an allowlist system, and a data hook proxy for cross-chain cash-out interception.
 
-Compiler: `solc 0.8.26`. Framework: Foundry.
+Compiler: `solc ^0.8.26`. Framework: Foundry.
 
 ---
 
@@ -14,8 +14,8 @@ Croptop is a thin orchestration layer on top of Juicebox V6 core and the 721 tie
 
 | Contract | File | Lines | Role |
 |----------|------|-------|------|
-| **CTPublisher** | `src/CTPublisher.sol` | ~580 | Core publishing engine. Validates posts against bit-packed allowances, creates 721 tiers, mints first copies, routes fees. Inherits `JBPermissioned`, `ERC2771Context`. |
-| **CTDeployer** | `src/CTDeployer.sol` | ~427 | Factory that deploys a JB project + 721 hook + posting criteria in one transaction. Acts as `IJBRulesetDataHook` proxy: forwards pay/cash-out calls to the underlying hook while granting fee-free cash outs to suckers. Inherits `JBPermissioned`, `ERC2771Context`, `IERC721Receiver`. |
+| **CTPublisher** | `src/CTPublisher.sol` | ~590 | Core publishing engine. Validates posts against bit-packed allowances, creates 721 tiers, mints first copies, routes fees. Inherits `JBPermissioned`, `ERC2771Context`. |
+| **CTDeployer** | `src/CTDeployer.sol` | ~433 | Factory that deploys a JB project + 721 hook + posting criteria in one transaction. Acts as `IJBRulesetDataHook` proxy: forwards pay/cash-out calls to the underlying hook while granting fee-free cash outs to suckers. Inherits `JBPermissioned`, `ERC2771Context`, `IERC721Receiver`. |
 | **CTProjectOwner** | `src/CTProjectOwner.sol` | ~82 | Receives project ownership NFT via `safeTransferFrom` and permanently grants `CTPublisher` the `ADJUST_721_TIERS` permission. Implements `IERC721Receiver`. |
 
 ### Struct Table
@@ -61,60 +61,74 @@ CTProjectOwner
 
 ---
 
+## Value Extraction Paths
+
+Quick reference for where the money is:
+
+| Path | Entry Point | Value at Risk | What to Verify |
+|------|------------|---------------|----------------|
+| Fee evasion | `CTPublisher.mintFrom()` | 5% fee on every mint | `totalPrice` computed from on-chain tier prices for existing tiers, not user-supplied `post.price` |
+| Fee-free cashout | `CTDeployer.beforeCashOutRecordedWith()` | Full treasury value | Only legitimate suckers (via registry) get 0% tax |
+| Unauthorized minting | `CTDeployer.hasMintPermissionFor()` | Arbitrary token minting | Only registered suckers get mint permission |
+| Tier spam | `CTPublisher._setupPosts()` | Gas griefing, hook degradation | Allowlist + price/supply floors gate tier creation |
+| Fee routing failure | `CTPublisher.mintFrom()` residual balance | Fee project loses 5% | `address(this).balance` after project payment is sent to fee project |
+
+---
+
 ## 2. Content Posting Flow
 
 The core flow is `CTPublisher.mintFrom()`. This is the primary entry point for all content publishing.
 
-### Step-by-step execution (CTPublisher.sol lines 307-420)
+### Step-by-step execution (CTPublisher.sol lines 310-430)
 
 ```
 Poster calls mintFrom(hook, posts[], nftBeneficiary, feeBeneficiary, additionalPayMetadata, feeMetadata)
   with msg.value = sum(post prices) + 5% fee
 
-1. Read projectId from hook.PROJECT_ID()                              [line 326]
-2. _setupPosts(hook, posts) returns:                                  [line 330-331]
+1. Read projectId from hook.PROJECT_ID()                              [line 329]
+2. _setupPosts(hook, posts) returns:                                  [line 333-334]
    (tiersToAdd[], tierIdsToMint[], totalPrice)
 
    For each post in the batch:
-     a. Revert if encodedIPFSUri == bytes32("")                       [line 463-464]
-     b. O(i) duplicate check against all prior posts in batch         [line 468-472]
-     c. Look up tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]       [line 477]
-        - If tier exists and NOT removed: reuse tier ID,              [line 486]
-          accumulate store.tierOf().price (on-chain price)            [line 491]
-        - If tier exists but removed: delete stale mapping,           [line 484]
+     a. Revert if encodedIPFSUri == bytes32("")                       [line 473-474]
+     b. O(i) duplicate check against all prior posts in batch         [line 478-482]
+     c. Look up tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]       [line 487]
+        - If tier exists and NOT removed: reuse tier ID,              [line 496]
+          accumulate store.tierOf().price (on-chain price)            [line 501]
+        - If tier exists but removed: delete stale mapping,           [line 494]
           fall through to new tier creation
-        - If no tier exists: validate against allowance:              [line 500-539]
+        - If no tier exists: validate against allowance:              [line 510-549]
           * Category must be configured (minimumTotalSupply > 0)
           * price >= minimumPrice
           * totalSupply >= minimumTotalSupply
           * totalSupply <= maximumTotalSupply
           * splitPercent <= maximumSplitPercent
           * caller in allowedAddresses (if non-empty)
-          Then build JB721TierConfig and accumulate post.price        [line 543-569]
-     d. Store tierIdForEncodedIPFSUriOf mapping for new tiers         [line 566]
+          Then build JB721TierConfig and accumulate post.price        [line 553-579]
+     d. Store tierIdForEncodedIPFSUriOf mapping for new tiers         [line 576]
 
-   Assembly-resize tiersToAdd if some posts reused existing tiers     [line 574-578]
+   Assembly-resize tiersToAdd if some posts reused existing tiers     [line 584-588]
 
-3. If projectId != FEE_PROJECT_ID:                                    [line 333]
-     payValue = msg.value - (totalPrice / FEE_DIVISOR)                [line 338]
+3. If projectId != FEE_PROJECT_ID:                                    [line 336]
+     payValue = msg.value - (totalPrice / FEE_DIVISOR)                [line 341/348]
    Else: payValue = msg.value (no fee for fee project)
 
-4. Revert if totalPrice > payValue                                    [line 342-344]
+4. Revert if totalPrice > payValue                                    [line 352-354]
 
-5. hook.adjustTiers(tiersToAdd, [])                                   [line 348]
+5. hook.adjustTiers(tiersToAdd, [])                                   [line 358]
 
-6. Build mint metadata:                                               [line 356-367]
+6. Build mint metadata:                                               [line 366-370]
    - JBMetadataResolver.addToMetadata with tier IDs
    - Assembly: write FEE_PROJECT_ID into first 32 bytes (referral)
 
-7. Emit Mint event                                                    [line 370-379]
+7. Emit Mint event                                                    [line 380-389]
 
-8. Look up project's primary ETH terminal via DIRECTORY               [line 383-384]
-   terminal.pay{value: payValue}(...)                                 [line 388-396]
+8. Look up project's primary ETH terminal via DIRECTORY               [line 393-394]
+   terminal.pay{value: payValue}(...)                                 [line 398-406]
 
-9. If address(this).balance != 0:                                     [line 403]
-   Look up fee project's primary ETH terminal                        [line 405-406]
-   feeTerminal.pay{value: address(this).balance}(...)                [line 410-418]
+9. If address(this).balance != 0:                                     [line 413]
+   Look up fee project's primary ETH terminal                        [line 415-416]
+   feeTerminal.pay{value: address(this).balance}(...)                [line 420-428]
 ```
 
 ### Fee Calculation
@@ -134,25 +148,25 @@ Poster calls mintFrom(hook, posts[], nftBeneficiary, feeBeneficiary, additionalP
 
 When a post's `encodedIPFSUri` has no existing mapping (or the mapped tier was removed), a new tier is created:
 
-1. Posting criteria are read from bit-packed `_packedAllowanceFor[hook][category]` (CTPublisher.sol lines 174-187)
+1. Posting criteria are read from bit-packed `_packedAllowanceFor[hook][category]` (CTPublisher.sol lines 177-190)
 2. Each field is validated against the post's parameters
-3. A `JB721TierConfig` is constructed with the post's values (lines 543-560)
-4. The tier ID is computed as `startingTierId + numberOfTiersBeingAdded++` (line 563)
-5. The mapping `tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]` is set (line 566)
-6. All new tiers are committed to the hook via `hook.adjustTiers()` after the loop (line 348)
+3. A `JB721TierConfig` is constructed with the post's values (lines 553-570)
+4. The tier ID is computed as `startingTierId + numberOfTiersBeingAdded++` (line 573)
+5. The mapping `tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]` is set (line 576)
+6. All new tiers are committed to the hook via `hook.adjustTiers()` after the loop (line 358)
 
 ### Existing Tier Path
 
 When a post's `encodedIPFSUri` already has a mapping to a live (non-removed) tier:
 
-1. The tier ID is reused (line 486)
-2. The fee is calculated from `store.tierOf().price` -- the on-chain price, not `post.price` (line 491)
+1. The tier ID is reused (line 496)
+2. The fee is calculated from `store.tierOf().price` -- the on-chain price, not `post.price` (line 501)
 3. No new `JB721TierConfig` is added to `tiersToAdd`
 4. The poster still gets a mint of the existing tier
 
 ### Stale Tier Cleanup
 
-If a tier was removed externally via `adjustTiers()`, the publisher detects this via `hook.STORE().isTierRemoved()` (line 483) and deletes the stale mapping (line 484), allowing the URI to be posted as a new tier.
+If a tier was removed externally via `adjustTiers()`, the publisher detects this via `hook.STORE().isTierRemoved()` (line 493) and deletes the stale mapping (line 494), allowing the URI to be posted as a new tier.
 
 ---
 
@@ -168,8 +182,8 @@ Bits 168-199  ( 32 bits): maximumSplitPercent(uint32)
 Bits 200-255  ( 56 bits): unused
 ```
 
-Packing logic: CTPublisher.sol lines 271-281
-Unpacking logic: CTPublisher.sol lines 174-187
+Packing logic: CTPublisher.sol lines 274-282
+Unpacking logic: CTPublisher.sol lines 177-190
 
 The address allowlist is stored separately in `_allowedAddresses[hook][category]` (a dynamic array).
 
@@ -179,18 +193,18 @@ The address allowlist is stored separately in `_allowedAddresses[hook][category]
 
 ### Configuration
 
-`configurePostingCriteriaFor()` (line 240) accepts an array of `CTAllowedPost` structs. For each:
+`configurePostingCriteriaFor()` (line 243) accepts an array of `CTAllowedPost` structs. For each:
 
-1. Emits `ConfigurePostingCriteria` event (line 249)
-2. Checks `ADJUST_721_TIERS` permission from `JBOwnable(hook).owner()` (lines 253-257)
-3. Validates `minimumTotalSupply > 0` (line 260)
-4. Validates `minimumTotalSupply <= maximumTotalSupply` (line 265)
-5. Packs numeric fields into `_packedAllowanceFor` (lines 271-281)
-6. Replaces the entire `_allowedAddresses` array (delete + push loop, lines 286-293)
+1. Emits `ConfigurePostingCriteria` event (line 252)
+2. Checks `ADJUST_721_TIERS` permission from `JBOwnable(hook).owner()` (lines 256-260)
+3. Validates `minimumTotalSupply > 0` (line 263)
+4. Validates `minimumTotalSupply <= maximumTotalSupply` (line 268)
+5. Packs numeric fields into `_packedAllowanceFor` (lines 274-284)
+6. Replaces the entire `_allowedAddresses` array (delete + push loop, lines 289-296)
 
 ### Enforcement
 
-In `_setupPosts()` at line 537:
+In `_setupPosts()` at line 547:
 
 ```solidity
 if (addresses.length != 0 && !_isAllowed({addrs: _msgSender(), addresses: addresses})) {
@@ -198,7 +212,7 @@ if (addresses.length != 0 && !_isAllowed({addrs: _msgSender(), addresses: addres
 }
 ```
 
-`_isAllowed()` (lines 207-217) is a linear scan: O(n) where n = allowlist size.
+`_isAllowed()` (lines 210-220) is a linear scan: O(n) where n = allowlist size.
 
 ### Key Behavior
 
@@ -213,7 +227,7 @@ if (addresses.length != 0 && !_isAllowed({addrs: _msgSender(), addresses: addres
 
 ### Architecture
 
-CTDeployer registers itself as the `dataHook` for every project it deploys (CTDeployer.sol line 286). It implements `IJBRulesetDataHook` and proxies calls:
+CTDeployer registers itself as the `dataHook` for every project it deploys (CTDeployer.sol line 289). It implements `IJBRulesetDataHook` and proxies calls:
 
 - **`beforePayRecordedWith(context)`** (line 160): Forwards directly to `dataHookOf[context.projectId]` (the JB721TiersHook).
 - **`beforeCashOutRecordedWith(context)`** (line 132): Checks `SUCKER_REGISTRY.isSuckerOf()` first. If the holder is a sucker, returns `cashOutTaxRate = 0` (fee-free). Otherwise forwards to the data hook.
@@ -225,7 +239,7 @@ CTDeployer registers itself as the `dataHook` for every project it deploys (CTDe
 
 - All `pay()` calls to the project will revert (line 168)
 - All `cashOut()` calls (for non-sucker holders) will revert (line 150)
-- Since `dataHookOf` is write-once (set at line 303, no setter), the project is permanently bricked
+- Since `dataHookOf` is write-once (set at line 306, no setter), the project is permanently bricked
 
 **Scenarios that could trigger this:**
 
@@ -280,7 +294,7 @@ If an attacker can make `SUCKER_REGISTRY.isSuckerOf()` return `true` for their a
 
 ### Current Implementation
 
-`_isAllowed()` at CTPublisher.sol lines 207-217:
+`_isAllowed()` at CTPublisher.sol lines 210-220:
 
 ```solidity
 function _isAllowed(address addrs, address[] memory addresses) internal pure returns (bool) {
@@ -303,7 +317,7 @@ function _isAllowed(address addrs, address[] memory addresses) internal pure ret
 
 ### Storage Scaling
 
-The `_allowedAddresses` array is also written during `configurePostingCriteriaFor()` via a push loop (lines 290-292). For large allowlists, the configuration transaction gas cost could also become prohibitive.
+The `_allowedAddresses` array is also written during `configurePostingCriteriaFor()` via a push loop (lines 293-295). For large allowlists, the configuration transaction gas cost could also become prohibitive.
 
 ### Recommendation for Auditors
 
@@ -315,13 +329,13 @@ Check that no realistic usage pattern could cause a revert due to gas limits. Th
 
 ### P0 -- Critical (fund loss or permanent DoS)
 
-1. **Fee accounting correctness in `_setupPosts()`** (CTPublisher.sol lines 432-579). Verify:
+1. **Fee accounting correctness in `_setupPosts()`** (CTPublisher.sol lines 442-589). Verify:
    - `totalPrice` is always computed from on-chain tier prices for existing tiers (not user-supplied `post.price`)
    - `totalPrice` is always computed from `post.price` for new tiers
    - No path exists where `totalPrice` can be manipulated to be less than the actual value of tiers being minted
-   - The duplicate URI check (lines 468-472) covers all batch orderings
+   - The duplicate URI check (lines 478-482) covers all batch orderings
 
-2. **Fee deduction and routing** (CTPublisher.sol lines 333-418). Verify:
+2. **Fee deduction and routing** (CTPublisher.sol lines 336-428). Verify:
    - `payValue = msg.value - (totalPrice / FEE_DIVISOR)` cannot underflow
    - The check `totalPrice > payValue` correctly prevents underpayment
    - `address(this).balance` after the project payment equals exactly the fee amount (plus any force-sent ETH)
@@ -338,7 +352,7 @@ Check that no realistic usage pattern could cause a revert due to gas limits. Th
    - Only legitimate suckers can trigger the zero-tax path
    - The `hasMintPermissionFor()` function cannot be abused for unauthorized minting
 
-5. **Permission enforcement in `configurePostingCriteriaFor()`** (CTPublisher.sol lines 253-257). Verify:
+5. **Permission enforcement in `configurePostingCriteriaFor()`** (CTPublisher.sol lines 256-260). Verify:
    - The permission check uses `JBOwnable(hook).owner()` and `IJB721TiersHook(hook).PROJECT_ID()` correctly
    - No one besides the hook owner (or permissioned delegate) can modify posting criteria
 
@@ -351,19 +365,19 @@ Check that no realistic usage pattern could cause a revert due to gas limits. Th
 
 7. **Tier spam / unbounded tier creation** (R-1 in RISKS.md). When allowlist is empty, anyone meeting price/supply floors can create unlimited tiers. Assess impact on hook gas costs.
 
-8. **Bit-packing correctness** in `_packedAllowanceFor` storage (CTPublisher.sol lines 271-281 write, lines 174-187 read). Verify no field overlap or silent truncation.
+8. **Bit-packing correctness** in `_packedAllowanceFor` storage (CTPublisher.sol lines 274-282 write, lines 177-190 read). Verify no field overlap or silent truncation.
 
-9. **Assembly metadata injection** (CTPublisher.sol lines 365-367). Verify the `mstore` correctly places `FEE_PROJECT_ID` in the referral position without corrupting the JBMetadataResolver lookup table.
+9. **Assembly metadata injection** (CTPublisher.sol lines 375-377). Verify the `mstore` correctly places `FEE_PROJECT_ID` in the referral position without corrupting the JBMetadataResolver lookup table.
 
-10. **Project deployment front-running** (CTDeployer.sol lines 258, 291-300). Verify the `assert(projectId == ...)` check correctly prevents ID mismatch without permanent fund loss.
+10. **Project deployment front-running** (CTDeployer.sol lines 261, 294-303). Verify the `assert(projectId == ...)` check correctly prevents ID mismatch without permanent fund loss.
 
 ### P3 -- Low (informational, code quality)
 
-11. **`uint56` vs `uint64` cast inconsistency** between CTProjectOwner (line 74) and CTDeployer (line 338). Confirm no truncation risk for realistic project IDs.
+11. **`uint64` project ID cast** in CTProjectOwner (line 77) and CTDeployer (line 344). Both now use `uint64`. Confirm no truncation risk for realistic project IDs.
 
-12. **Force-sent ETH routing** (CTPublisher.sol lines 403-418). Confirm this is the intended behavior and cannot be exploited.
+12. **Force-sent ETH routing** (CTPublisher.sol lines 413-428). Confirm this is the intended behavior and cannot be exploited.
 
-13. **Allowlist overwrite behavior** (CTPublisher.sol lines 286-293). Verify that `delete` followed by `push` loop correctly replaces the array with no residual state.
+13. **Allowlist overwrite behavior** (CTPublisher.sol lines 289-296). Verify that `delete` followed by `push` loop correctly replaces the array with no residual state.
 
 ---
 
@@ -418,9 +432,14 @@ ETHEREUM_RPC_URL=<your-rpc> forge test --match-contract ForkTest --fork-url $ETH
 
 | Test File | Focus | Tests |
 |-----------|-------|-------|
-| `test/CTPublisher.t.sol` | Allowance round-trip, bit packing fuzz, permission checks, split validation | 18 tests including fuzz |
+| `test/CTPublisher.t.sol` | Allowance round-trip, bit packing fuzz, permission checks, split validation | 26 tests including fuzz |
+| `test/CTDeployer.t.sol` | Deploy flow, data hook proxy, sucker permissions, onERC721Received, supportsInterface | 21 tests |
+| `test/CTProjectOwner.t.sol` | Permission grants on NFT receipt, rejection of non-project NFTs, rejection of transfers | 7 tests |
+| `test/ClaimCollectionOwnership.t.sol` | NM-002 scenario: ownership transfer, permission breakage, recovery path | 6 tests |
+| `test/TestAuditGaps.sol` | Data hook proxy forwarding failure, sucker impersonation, allowlist gas scaling, force-sent ETH | 19 tests |
 | `test/CroptopAttacks.t.sol` | Adversarial input validation, allowlist bypass, split percent enforcement | 12 tests |
 | `test/Fork.t.sol` | Full deployment integration with real JB infrastructure | 2 fork tests |
+| `test/fork/PublishFork.t.sol` | End-to-end mint flow, fee distribution, duplicate post reuse on mainnet fork | 4 fork tests |
 | `test/Test_MetadataGeneration.t.sol` | Metadata assembly correctness | 1 test |
 | `test/regression/DuplicateUriFeeEvasion.t.sol` | NM-001 fix: duplicate URI detection | 5 tests including fuzz |
 | `test/regression/FeeEvasion.t.sol` | H-19 fix: existing tier price used for fees | 2 tests |
@@ -428,11 +447,7 @@ ETHEREUM_RPC_URL=<your-rpc> forge test --match-contract ForkTest --fork-url $ETH
 
 ### Coverage Gaps (no existing tests)
 
-- Data hook proxy forwarding failure (CTDeployer -> hook reverts)
 - Force-sent ETH handling via selfdestruct
-- Allowlist gas scaling benchmarks
-- Sucker fee-free cash-out abuse / impersonation
-- CTProjectOwner receiving transfers (not just mints)
 - `deployProjectFor` front-running race condition
 - Multiple hooks sharing the same CTPublisher instance
 - Cross-category posting in a single batch (different categories, different allowlists)
@@ -447,12 +462,45 @@ Tests use Foundry's `vm.mockCall()` to isolate CTPublisher from its dependencies
 
 ## 12. Previous Audit Findings
 
-Three findings were fixed and have regression tests. Two findings remain open (low severity). See `RISKS.md` for full details.
+Six Nemesis findings plus two regression-test findings. See `.audit/findings/nemesis-verified.md` for full Nemesis details and `RISKS.md` for context.
 
 | ID | Severity | Status | Description |
 |----|----------|--------|-------------|
-| NM-001 | MEDIUM | FIXED | Duplicate URI fee evasion in batch mints |
-| H-19 | HIGH | FIXED | Fee evasion on existing tier mints via `post.price = 0` |
-| L-52 | LOW | FIXED | Stale tier ID mapping after external tier removal |
-| NM-005 | LOW | OPEN | `uint56` vs `uint64` project ID cast inconsistency |
+| NM-001 | MEDIUM | FALSE POSITIVE | `dataHookOf` write-once = permanent project bricking -- project owner can queue new ruleset to escape (`useDataHookForPay = false`) |
+| NM-002 | MEDIUM | OPEN | `claimCollectionOwnershipOf` breaks all `CTPublisher.mintFrom` calls -- hook ownership transfer does not update CTPublisher permissions |
+| NM-003 | LOW | OPEN | Permission grants to initial owner stale after project NFT transfer -- old owner retains 4 permissions |
+| NM-004 | LOW | OPEN | Stale `tierIdForEncodedIPFSUriOf` in `tiersFor()` view -- removed tiers still returned to off-chain consumers |
+| NM-005 | LOW | FIXED | Fee underflow gives generic panic (`0x11`) instead of custom `CTPublisher_InsufficientEthSent` error -- the `if (payValue < fee)` check now guards the subtraction |
 | NM-006 | LOW | OPEN | Cannot fully disable posting for a configured category |
+| H-19 | HIGH | FIXED | Fee evasion on existing tier mints via `post.price = 0` *(regression test naming, not from Nemesis audit)* |
+| L-52 | LOW | FIXED | Stale tier ID mapping after external tier removal *(regression test naming, not from Nemesis audit)* |
+
+---
+
+## Compiler and Version Info
+
+- **Solidity**: ^0.8.26
+- **EVM target**: Cancun
+- **Optimizer**: 200 runs
+- **Dependencies**: OpenZeppelin 5.x, nana-core-v6, nana-721-hook-v6, nana-suckers-v6
+- **Build**: `forge build` (Foundry)
+
+---
+
+## How to Report Findings
+
+For each finding:
+
+1. **Title** -- one line, starts with severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **Affected contract(s)** -- exact file path and line numbers
+3. **Description** -- what is wrong, in plain language
+4. **Trigger sequence** -- step-by-step
+5. **Impact** -- what an attacker gains, what the project/fee project loses
+6. **Proof** -- code trace or Foundry test
+7. **Fix** -- minimal code change
+
+**Severity guide:**
+- **CRITICAL**: Fee evasion at scale, unauthorized treasury drain, permanent project DoS.
+- **HIGH**: Conditional fee bypass, sucker impersonation, broken posting criteria.
+- **MEDIUM**: Tier spam, gas griefing, rounding errors in fee calculation.
+- **LOW**: Informational, cosmetic, testnet-only.

package/CHANGE_LOG.md

@@ -2,12 +2,20 @@
 
 This document describes all changes between `croptop-core` (v5) and `croptop-core-v6` (v6).
 
+## Summary
+
+- **Data hook proxy activated**: `CTDeployer` now sets itself as the data hook (`metadata.dataHook = address(this)`) instead of pointing directly to the 721 hook — enables sucker cashouts at 0% tax rate for cross-chain operations.
+- **Split support for posts**: `CTPost` gained `splitPercent` and `splits` fields, allowing poster-defined payment routing per NFT tier (bounded by `maximumSplitPercent`).
+- **Fee evasion fixes**: Existing tier mints now use on-chain price (not user-supplied), and duplicate posts within a batch are rejected.
+- **Stale tier recovery**: Externally-removed tiers are detected and re-created instead of silently failing.
+- **`projectId` cast widened**: `uint56` → `uint64` to match v6 `JBPermissionsData`.
+
 ---
 
 ## 1. Breaking Changes
 
 ### Solidity Version
-- Compiler version bumped from `0.8.23` to `0.8.26` across all implementation contracts (`CTDeployer`, `CTProjectOwner`, `CTPublisher`).
+- Compiler version bumped from `0.8.23` to `^0.8.26` across all implementation contracts (`CTDeployer`, `CTProjectOwner`, `CTPublisher`).
 
 ### Dependency Namespace Migration
 All imports updated from v5 to v6 namespaces:
@@ -51,6 +59,8 @@ All imports updated from v5 to v6 namespaces:
 - **v6:** Sets `metadata.dataHook = address(this)` (the CTDeployer itself is the data hook). Sets `metadata.cashOutTaxRate = JBConstants.MAX_CASH_OUT_TAX_RATE` and `metadata.useDataHookForCashOut = true`.
 - The CTDeployer now acts as a data hook proxy, forwarding pay/cashout calls to the stored `dataHookOf[projectId]`, while intercepting sucker cash outs to grant 0% tax rate. This is a fundamental architectural change.
 
+> **Why this change**: In v5, the CTDeployer already had the proxy methods (`beforePayRecordedWith`, `beforeCashOutRecordedWith`, `hasMintPermissionFor`) and the `dataHookOf` mapping, but `deployProjectFor` pointed `metadata.dataHook` directly at the 721 hook, bypassing the proxy entirely. v6 activates the proxy so the deployer can intercept sucker cashouts (verified via `SUCKER_REGISTRY.isSuckerOf`) and return a 0% tax rate for cross-chain operations. Without this, cross-chain token bridging via suckers would incur the full `MAX_CASH_OUT_TAX_RATE`, making omnichain projects economically unviable.
+
 ### `JB721InitTiersConfig` — `prices` Field Removed
 - **v5:** `JB721InitTiersConfig({ tiers, currency, decimals, prices: controller.PRICES() })`
 - **v6:** `JB721InitTiersConfig({ tiers, currency, decimals })` — the `prices` field no longer exists in the v6 721 hook config struct.
@@ -249,5 +259,7 @@ No field changes. Import path updated from `@bananapus/suckers-v5` to `@bananapu
 | `JB721TiersHookFlags`: 4 flags | `JB721TiersHookFlags`: 5 flags | Added `issueTokensForSplits` |
 | -- | `CTPublisher_DuplicatePost` | New error |
 | -- | `CTPublisher_SplitPercentExceedsMaximum` | New error |
-| Solidity `0.8.23` | Solidity `0.8.26` | Compiler bump |
+| Solidity `0.8.23` | Solidity `^0.8.26` | Compiler bump |
 | `@bananapus/*-v5` | `@bananapus/*-v6` | All dependency namespaces |
+
+> **Cross-repo impact**: The `CTPost.splitPercent` and `splits` fields feed directly into `nana-721-hook-v6`'s tier splits system. `nana-suckers-v6` suckers are detected via `SUCKER_REGISTRY.isSuckerOf` for the 0% tax cashout path. `nana-permission-ids-v6` `uint64` projectId width change drove the `CTProjectOwner` cast update.

package/README.md

@@ -4,6 +4,8 @@ Permissioned NFT publishing for Juicebox projects -- anyone can post content as
 
 [Docs](https://docs.juicebox.money) | [Discord](https://discord.gg/juicebox) | [Croptop](https://croptop.eth.limo)
 
+**Supported Chains:** Ethereum, Optimism, Base, Arbitrum (mainnets) and Ethereum Sepolia, Optimism Sepolia, Base Sepolia, Arbitrum Sepolia (testnets). See `script/Deploy.s.sol` for the Sphinx deployment configuration.
+
 ## Conceptual Overview
 
 Croptop turns any Juicebox project with a 721 tiers hook into a permissioned content marketplace. Project owners define posting criteria -- minimum price, supply bounds, address allowlists -- and anyone who meets those criteria can publish new NFT tiers on the project. The poster's content becomes a mintable NFT tier, and the first copy is minted to them automatically.
@@ -29,6 +31,33 @@ Croptop turns any Juicebox project with a 721 tiers hook into a permissioned con
    → Standard 721 tier minting via the project's hook
 ```
 
+```mermaid
+sequenceDiagram
+    participant Poster
+    participant CTPublisher
+    participant Hook as 721 Tiers Hook
+    participant Terminal as Project Terminal
+    participant FeeTerminal as Fee Project Terminal
+
+    Poster->>CTPublisher: mintFrom(hook, posts, ...)
+    CTPublisher->>CTPublisher: Validate each post against category criteria
+    loop For each post
+        CTPublisher->>Hook: adjustTiersOf() -- create new tier (or reuse existing)
+    end
+    CTPublisher->>Terminal: pay() -- total price minus fee
+    Note over Terminal: Mints first copy of each tier to poster
+    CTPublisher->>FeeTerminal: pay() -- 5% fee (totalPrice / 20)
+    Note over FeeTerminal: Routes fee to designated fee project
+```
+
+### Fee Structure
+
+Every `mintFrom` call collects a 5% fee on the total tier price. The fee is calculated as `totalPrice / FEE_DIVISOR` where `FEE_DIVISOR = 20`. The fee is paid to the primary ETH terminal of a designated fee project (`FEE_PROJECT_ID`, set at deployment). The remainder goes to the target project's primary terminal as a normal payment.
+
+- If the project being posted to **is** the fee project, no fee is collected (avoids circular payments).
+- Integer division truncates, so the fee loses up to 19 wei of dust per mint.
+- Any ETH remaining in the contract after the main payment (including force-sent ETH) is forwarded to the fee project terminal.
+
 ### One-Click Deployment
 
 `CTDeployer` creates a complete Juicebox project + 721 hook + posting criteria in a single transaction. It also:
@@ -83,16 +112,16 @@ forge install
 | Command | Description |
 |---------|-------------|
 | `forge build` | Compile contracts |
-| `forge test` | Run all tests (4 test files covering publishing, attacks, fork integration, metadata) |
+| `forge test` | Run all tests (12 test files covering publishing, deployer, attacks, fork integration, metadata, and regressions) |
 | `forge test -vvv` | Run tests with full trace |
 
 ## Repository Layout
 
 ```
 src/
-  CTPublisher.sol                        # Core publishing engine (~540 lines)
-  CTDeployer.sol                         # Project factory + data hook proxy (~425 lines)
-  CTProjectOwner.sol                     # Burn-lock ownership helper (~79 lines)
+  CTPublisher.sol                        # Core publishing engine (~590 lines)
+  CTDeployer.sol                         # Project factory + data hook proxy (~433 lines)
+  CTProjectOwner.sol                     # Burn-lock ownership helper (~84 lines)
   interfaces/
     ICTPublisher.sol                     # Publisher interface + events
     ICTDeployer.sol                      # Factory interface
@@ -104,10 +133,20 @@ src/
     CTProjectConfig.sol                  # Full project deployment config
     CTSuckerDeploymentConfig.sol         # Cross-chain sucker config
 test/
-  CTPublisher.t.sol                      # Unit tests (~672 lines, ~22 cases)
-  CroptopAttacks.t.sol                   # Security/adversarial tests (~440 lines, ~12 cases)
+  CTPublisher.t.sol                      # Unit tests (~865 lines, ~26 cases)
+  CTDeployer.t.sol                       # Deployer tests (~608 lines)
+  CTProjectOwner.t.sol                   # Project owner tests (~185 lines)
+  ClaimCollectionOwnership.t.sol         # Collection ownership claim tests (~315 lines)
+  CroptopAttacks.t.sol                   # Security/adversarial tests (~437 lines, ~12 cases)
   Fork.t.sol                             # Mainnet fork integration tests
+  TestAuditGaps.sol                      # Audit gap coverage tests (~689 lines)
   Test_MetadataGeneration.t.sol          # JBMetadataResolver roundtrip tests
+  fork/
+    PublishFork.t.sol                    # Fork-based publish tests (~437 lines)
+  regression/
+    DuplicateUriFeeEvasion.t.sol         # Duplicate URI fee evasion regression (~312 lines)
+    FeeEvasion.t.sol                     # Fee evasion regression (~279 lines)
+    StaleTierIdMapping.t.sol             # Stale tier ID mapping regression (~214 lines)
 script/
   Deploy.s.sol                           # Sphinx multi-chain deployment
   ConfigureFeeProject.s.sol              # Fee project configuration

package/RISKS.md

@@ -7,12 +7,13 @@
 - **Sucker registry.** `CTDeployer.beforeCashOutRecordedWith` trusts `SUCKER_REGISTRY.isSuckerOf()` for 0% tax cashouts, same risk as the omnichain deployer.
 - **CTProjectOwner as burn target.** Projects transferred to `CTProjectOwner` grant `ADJUST_721_TIERS` to `PUBLISHER`. The project NFT cannot be recovered -- this is intentional but irreversible.
 - **JBDirectory / Terminal resolution.** `CTPublisher.mintFrom` resolves terminals via `DIRECTORY.primaryTerminalOf()`. A compromised directory could redirect payment and fee flows.
+- **721 hook store.** `_setupPosts` calls `hook.STORE().tierOf()` and `hook.STORE().isTierRemoved()`. The store is trusted to return accurate tier data. A malicious hook returning a fake store can report manipulated prices, supply limits, and removal status, causing `_setupPosts` to miscalculate `totalPrice` or skip duplicate detection.
 
 ## 2. Economic / Manipulation Risks
 
 - **Fee evasion via duplicate posts across hooks.** `tierIdForEncodedIPFSUriOf` is keyed per hook. The same `encodedIPFSUri` can be posted to different hooks without duplicate detection, potentially creating fee-arbitrage opportunities.
 - **Fee calculation rounding.** Fee is `totalPrice / FEE_DIVISOR` (FEE_DIVISOR=20, so 5% fee). Integer division truncates, losing up to 19 wei per post. Negligible individually but could compound across many micro-priced posts. Explicit validation: reverts `CTPublisher_InsufficientEthSent` if `msg.value < fee` (before subtraction) or if `msg.value - fee < totalPrice` (after subtraction).
-- **Balance-based fee routing.** `CTPublisher.mintFrom` sends fees based on `address(this).balance` after the main payment. Force-sent ETH (via selfdestruct) is routed to the fee project.
+- **Pre-computed fee routing.** `CTPublisher.mintFrom` computes the fee as `msg.value - payValue` before the external payment call, so the fee amount is determined from `msg.value` alone. Force-sent ETH (via selfdestruct) does not affect fee calculation.
 - **Split percent manipulation.** Posters can set `splitPercent` up to `maximumSplitPercent`. Splits route funds away from the project treasury to poster-specified addresses. If `maximumSplitPercent` is set high, posters can redirect most of the tier revenue.
 
 ## 3. Access Control
@@ -30,15 +31,31 @@
 - **Terminal resolution failure.** If `DIRECTORY.primaryTerminalOf()` returns `address(0)` for the project or fee project, the `pay()` call will revert with a low-level error.
 - **adjustTiers revert.** `hook.adjustTiers()` can revert if tiers violate category ordering constraints or other hook-level rules. This blocks the entire `mintFrom` call.
 
-## 5. Integration Risks
+## 5. Reentrancy Surface
 
-- **CTDeployer forwards all pay/cashout calls to `dataHookOf`.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` delegate to the stored data hook without try-catch. If the data hook reverts, all payments/cashouts for the project are blocked.
+- **`mintFrom` external call chain.** `mintFrom` makes three categories of external calls: (1) `hook.adjustTiers()` to create new tiers, (2) `terminal.pay{value}()` to pay the project, (3) `terminal.pay{value}()` to pay the fee project. The first `terminal.pay` can trigger pay hooks on the target project, which could call back into `CTPublisher`. However, `mintFrom` has no mutable state between the tier adjustment and the payment — `totalPrice` and `payValue` are computed from local variables before the external calls. A re-entrant `mintFrom` call would process independently.
+- **Fee payment ordering.** The fee is sent AFTER the main payment (line ordering in `mintFrom`). If the main payment's pay hook re-enters and calls `mintFrom` again, the fee for the first call has not yet been sent. This is safe because the fee is pre-computed from `msg.value` before the external call (`msg.value - payValue`), and each call independently computes its own fee from its own `msg.value`. Force-sent ETH (via selfdestruct) does not affect fee calculation since the fee is derived from `msg.value`, not `address(this).balance`.
+- **No `ReentrancyGuard`.** The publisher relies on independent local state per call. This is safe for the current implementation but fragile if mutable contract storage is added in future versions.
+
+## 6. Integration Risks
+
+- **CTDeployer forwards pay/cashout calls to `dataHookOf` with null check.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` check for a null `dataHookOf` and return defaults (context weight, empty specs) instead of reverting. If a non-null data hook reverts, payments/cashouts for the project are still blocked.
 - **No mechanism for hook migration.** `dataHookOf` is written once in `deployProjectFor` and never updated. If the data hook becomes compromised, there is no governance path to replace it without deploying a new project.
 - **Tier ID prediction.** `_setupPosts` predicts new tier IDs as `maxTierIdOf(hook) + 1 + i`. If another transaction adds tiers between `maxTierIdOf` read and `adjustTiers` execution, tier IDs shift and the wrong tiers are minted. This is a race condition in concurrent posting.
 - **CTProjectOwner accepts any project NFT.** `onERC721Received` grants `ADJUST_721_TIERS` to `PUBLISHER` for whatever tokenId is received. If a non-Croptop project is accidentally transferred to `CTProjectOwner`, the publisher gains tier adjustment permission for it.
 - **Fee payment destination.** Fees are routed to `FEE_PROJECT_ID` via its primary terminal. If the fee project changes its terminal or token acceptance, fee payments could fail and block all minting.
 
-## 6. Invariants to Verify
+## 7. Accepted Behaviors
+
+### 7.1 O(n^2) duplicate detection in `_setupPosts` (bounded by practical limits)
+
+`_setupPosts` uses an inner loop (`j < i`) to detect duplicate `encodedIPFSUri` values within a single batch. This is O(n^2) in the number of posts. For typical batch sizes (1-20 posts), gas cost is negligible (~2k gas per comparison). At 100 posts, the quadratic cost adds ~10M gas. The practical limit is ~150 posts per batch before approaching block gas limits. No mitigation is needed because: (1) the quadratic detection prevents duplicate NFT tiers which would corrupt tier ID tracking, (2) real-world posting batches are small (marketplace UX limits), and (3) the gas cost is borne by the poster, not the protocol.
+
+### 7.2 Tier ID prediction assumes no concurrent transactions
+
+`_setupPosts` predicts new tier IDs as `maxTierIdOf(hook) + 1 + i`. A concurrent `adjustTiers` call between the `maxTierIdOf` read and the `adjustTiers` execution shifts all predicted IDs, causing the wrong tiers to be minted. This is a known race condition. Mitigation is at the application layer: frontends should use nonce-based transaction ordering or warn users about concurrent posting. The hook-level `adjustTiers` is atomic (all-or-nothing), so a failed prediction reverts the entire batch cleanly.
+
+## 8. Invariants to Verify
 
 - `tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]` is set exactly once per (hook, encodedIPFSUri) pair and points to a valid, non-removed tier.
 - `totalPrice` accumulated in `_setupPosts` equals the sum of prices for all posts (new tier price for new posts, existing tier price for existing posts).