@croptop/core-v6 0.0.33 → 0.0.35

package/README.md

@@ -1,26 +1,27 @@
 # Croptop Core
 
-Croptop turns a Juicebox project with a 721 hook into a permissioned publishing marketplace. Project owners define posting criteria, then anyone who meets those rules can publish new NFT tiers and mint the first copy of each post.
+Croptop turns a Juicebox project with a 721 hook into a permissioned publishing marketplace. Project owners define posting rules, then anyone who meets those rules can publish new NFT tiers and mint the first copy of each post.
 
 Docs: <https://docs.juicebox.money>  
 Site: <https://croptop.eth.limo>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
 Croptop is built around three ideas:
 
-- project owners set category-level posting criteria such as price floors, supply bounds, split limits, and optional allowlists
+- project owners set category-level posting rules such as price floors, supply bounds, split limits, and optional allowlists
 - publishers call `mintFrom` to create or reuse 721 tiers that represent their post
-- a one-click deployer can create a full Juicebox project, its 721 hook configuration, and its posting rules in a single transaction
+- a one-click deployer can create a full Juicebox project, its 721 hook config, and its posting rules in one transaction
 
-Every mint collects a 5% Croptop fee unless the target project is itself the fee project. If the configured fee
-terminal rejects that fee payment, Croptop refunds the fee portion to `_msgSender()` and still lets the publish
-continue. If `_msgSender()` cannot receive ETH, the mint reverts.
+Every mint collects a 5% Croptop fee unless the target project is itself the fee project. If the fee terminal rejects that fee payment, Croptop refunds the fee portion to `_msgSender()` and still lets the publish continue. If `_msgSender()` cannot receive ETH, the mint reverts.
 
-Use this repo when the product is "permissioned publishing on a Juicebox project." Do not use it when you only need plain 721 tier sales; that belongs in `nana-721-hook-v6`.
-
-If a bug looks like ordinary tier issuance or terminal accounting, start in the 721 hook or core repo first. Croptop is where posting policy, fee routing, and publishing-specific project wiring begin.
+Use this repo when the product is permissioned publishing on top of a Juicebox project. Do not use it for plain 721 tier sales.
 
 ## Key Contracts
 
@@ -28,16 +29,46 @@ If a bug looks like ordinary tier issuance or terminal accounting, start in the
 | --- | --- |
 | `CTPublisher` | Validates posts, adjusts 721 tiers, mints the first copy, and routes protocol and project payments. |
 | `CTDeployer` | Launches a project, configures Croptop posting rules, and can wire in omnichain sucker deployments. |
-| `CTProjectOwner` | Burn-lock ownership helper that can permanently route project administration through Croptop's publishing surface. |
+| `CTProjectOwner` | Ownership sink that can permanently hold a project NFT while still delegating the posting permissions Croptop needs. |
 
 ## Mental Model
 
 There are two separate concerns here:
 
-1. `CTPublisher` governs whether a post is allowed and how it becomes a tier
-2. `CTDeployer` governs how a Croptop-flavored project is packaged and launched
+1. `CTPublisher` decides whether a post is allowed and how it becomes a tier
+2. `CTDeployer` decides how a Croptop-flavored project is packaged and launched
+
+Many Croptop bugs are really deployment-shape bugs or posting-policy bugs, not generic 721 bugs.
+
+## Read These Files First
+
+1. `src/CTPublisher.sol`
+2. `src/CTDeployer.sol`
+3. `src/CTProjectOwner.sol`
+4. `test/CTPublisher.t.sol`
+5. `test/ClaimCollectionOwnership.t.sol`
+
+## High-Signal Tests
+
+1. `test/CTPublisher.t.sol`
+2. `test/CTDeployer.t.sol`
+3. `test/ClaimCollectionOwnership.t.sol`
+4. `test/audit/FeeFallbackBlackhole.t.sol`
+5. `test/regression/DuplicateUriFeeEvasion.t.sol`
 
-That distinction matters because many "Croptop bugs" are deployment-shape bugs rather than publishing-rule bugs.
+## Integration Traps
+
+- Croptop publishing policy is separate from ordinary 721 tier issuance
+- fee routing is part of the publish path and its fallback behavior matters
+- `CTProjectOwner` intentionally changes the ownership model and should be reviewed as part of the trust model
+- duplicate-content, stale-tier, and fee-evasion edge cases are runtime behavior, not just UI concerns
+
+## Where State Lives
+
+- posting criteria and publish-side enforcement live in `CTPublisher`
+- deployment-time project wiring lives in `CTDeployer`
+- ownership-sink behavior lives in `CTProjectOwner`
+- actual tier issuance and treasury accounting still live in sibling Juicebox repos
 
 ## Install
 
@@ -62,10 +93,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-Deployments are handled through Sphinx using the environments configured in the repo scripts. `CTDeployer` can also compose cross-chain sucker deployments when the target publishing project needs omnichain support.
-
-The deploy script now expects an explicit nonzero `FEE_PROJECT_ID` for canonical deployments. It does not safely
-autodiscover a fee project by scanning existing project IDs.
+Deployments are handled through Sphinx. `CTDeployer` can also compose cross-chain sucker deployments when a nonzero sucker configuration is supplied. The deploy script expects an explicit nonzero `FEE_PROJECT_ID` for production-style deployments.
 
 ## Repository Layout
 
@@ -87,9 +115,13 @@ script/
 ## Risks And Notes
 
 - posting criteria are only as safe as the project owner configures them
-- fee routing depends on the designated fee project remaining correctly configured; if its terminal rejects payments,
-  Croptop refunds the fee to `_msgSender()` instead of trapping ETH in `CTPublisher`
-- burn-lock ownership is intentionally irreversible and should only be used when immutability is desired
-- after burn-locking into `CTProjectOwner`, the previous owner no longer holds the project NFT directly; control is
-  intentionally mediated through Croptop's owner helper and hook-admin surface instead of remaining a plain owner EOA
-- duplicate-content and stale-tier edge cases are guarded by tests, but integrations should still treat metadata reuse carefully
+- fee routing depends on the fee project staying correctly configured
+- parking a project in `CTProjectOwner` is effectively irreversible
+- after routing ownership into `CTProjectOwner`, the old owner no longer holds the project NFT directly
+- duplicate-content and stale-tier edge cases are economically relevant, not cosmetic
+
+## For AI Agents
+
+- Do not describe Croptop as a generic 721 marketplace.
+- Read `CTPublisher` before `CTDeployer` when the question is about publish eligibility or fee behavior.
+- If the issue is basic tier minting or accounting, move to `nana-721-hook-v6` or `nana-core-v6`.

package/RISKS.md

@@ -4,88 +4,75 @@ This file focuses on the publishing, fee-routing, and hook-composition risks tha
 
 ## How to use this file
 
-- Read `Priority risks` first to understand the failure modes with the highest user or treasury impact.
+- Read `Priority risks` first.
 - Use the detailed sections for contract-level reasoning about posting criteria, fee routing, and deployer composition.
-- Treat `Accepted Behaviors` and `Invariants to Verify` as the line between intentional tradeoffs and defects.
+- Treat `Accepted Behaviors` and `Invariants to Verify` as the boundary between intentional tradeoffs and defects.
 
 ## Priority risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
 | P0 | Hook/store and terminal trust | `mintFrom` depends on hook storage and directory terminal resolution; a bad integration can misprice posts or redirect value. | Audit integration assumptions, verify hook/store pairings, and monitor terminal configuration. |
-| P1 | Tier ID race during concurrent posting | `_setupPosts` predicts future tier IDs before `adjustTiers`; concurrent writes can shift those IDs and break the batch. | Application-layer ordering, atomic reverts on mismatch, and operator awareness of concurrent posting. |
-| P1 | Fee-path degradation without mint failure | The fee terminal is fail-open via try/catch, so posting continues even if the fee project temporarily stops receiving revenue. | Terminal health monitoring, fallback beneficiary handling, and explicit operational checks around fee routing. |
-
+| P1 | Tier ID race during concurrent posting | `_setupPosts` predicts future tier IDs before `adjustTiers`; concurrent writes can shift those IDs and break the batch. | Application-layer ordering, atomic reverts on mismatch, and operator awareness. |
+| P1 | Fee-path degradation without mint failure | The fee terminal is fail-open via try/catch, so publishing continues even if the fee project temporarily stops receiving revenue. | Terminal health monitoring, fallback-beneficiary handling, and explicit fee-routing checks. |
 
 ## 1. Trust Assumptions
 
-- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted in both CTPublisher and CTDeployer for permission checks, allowlist validation, and payment routing. A compromised forwarder can post as any allowed address, deploy projects as any owner, and redirect payments.
-- **CTDeployer as permanent data hook proxy.** `CTDeployer` sets itself as the data hook for projects it deploys. `dataHookOf[projectId]` is set once during `deployProjectFor` and has no setter to update it. If the underlying data hook needs to change, there is no mechanism to do so without redeploying.
-- **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.
+- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted in both publisher and deployer for permission checks, allowlists, and payment routing.
+- **CTDeployer as permanent data-hook proxy.** `CTDeployer` sets itself as the data hook for projects it deploys. `dataHookOf[projectId]` is set once and has no setter.
+- **Sucker registry.** `CTDeployer.beforeCashOutRecordedWith` trusts `SUCKER_REGISTRY.isSuckerOf()` for 0% tax cash outs.
+- **Sucker deployment is fail-open at launch time.** Launch can continue on chains where the configured sucker deployer cascade cannot complete.
+- **CTProjectOwner as burn target.** Projects transferred to `CTProjectOwner` cannot be recovered.
+- **JBDirectory / terminal resolution.** `CTPublisher.mintFrom` trusts `DIRECTORY.primaryTerminalOf()`.
+- **721 hook store.** `_setupPosts` trusts the hook store for tier state, removal checks, and prices.
 
-## 2. Economic / Manipulation Risks
+## 2. Economic And 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).
-- **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.
-- **Fee terminal fallback refunds the caller.** If the configured fee terminal cannot accept the fee payment, `mintFrom` refunds the fee portion to `_msgSender()`. This preserves mint liveness for normal callers, but relayers or contracts that cannot receive ETH will still cause the mint to revert.
-- **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.
+- **Fee evasion via duplicate posts across hooks.** Duplicate-content checks are keyed per hook, so the same URI can be reused across different hooks.
+- **Fee calculation rounding.** Fee is `totalPrice / 20`, so integer division truncates small amounts.
+- **Fee is computed from `msg.value`.** Force-sent ETH does not affect the fee calculation.
+- **Fee terminal fallback refunds the caller.** If the fee project cannot accept the fee, Croptop refunds `_msgSender()`. Relayers or contracts that cannot receive ETH will make the mint revert.
+- **Split percent manipulation.** Posters can direct large shares of tier revenue away from the project if `maximumSplitPercent` is configured high.
 
 ## 3. Access Control
 
-- **Allowlist is O(n) linear scan.** `_isAllowed` iterates the entire allowlist array. Acceptable for small lists but gas-expensive for large allowlists. No Merkle proof alternative.
-- **Categories cannot be disabled.** Once `configurePostingCriteriaFor` is called for a category, it can only be restricted by setting very high `minimumPrice` or `minimumTotalSupply`, but never fully removed.
-- **CTDeployer grants broad permissions.** Constructor grants `MAP_SUCKER_TOKEN` (wildcard, projectId=0) to sucker registry and `ADJUST_721_TIERS` (wildcard, projectId=0) to publisher. These permissions apply to ALL projects deployed by this CTDeployer instance.
-- **CTDeployer.deployProjectFor permission gap.** No explicit permission check -- anyone can call `deployProjectFor` and create a project. A griefer could deploy many projects with arbitrary owners.
-- **CTDeployer.claimCollectionOwnershipOf.** Only checks `PROJECTS.ownerOf(projectId) == _msgSender()`. No Juicebox permission check. If the project NFT is transferred, the new owner can claim collection ownership. After claiming, the project owner must grant CTPublisher the `ADJUST_721_TIERS` permission for the project so that `mintFrom()` continues to work — without this, all subsequent posts revert.
+- **Allowlist is O(n).** `_isAllowed` linearly scans the full allowlist.
+- **Categories cannot be disabled cleanly.** Once configured, a category can only be made impractical through stricter bounds.
+- **CTDeployer grants broad permissions.** Wildcard permissions to the sucker registry and publisher apply to all projects deployed by that deployer instance.
+- **`deployProjectFor` is permissionless for new projects.** Anyone can create a project with arbitrary owners.
+- **`claimCollectionOwnershipOf` only checks current NFT ownership.** After claiming, the project owner must still grant `CTPublisher` the needed tier-adjust permission or publishing stops working.
 
 ## 4. DoS Vectors
 
-- **Large batch posts.** `_setupPosts` iterates all posts with O(n^2) duplicate detection (inner loop `j < i`). A batch of 100+ posts has quadratic gas growth.
-- **External hook calls in loops.** `_setupPosts` calls `hook.STORE().tierOf()` and `hook.STORE().isTierRemoved()` inside the post loop. A reverting or gas-expensive store blocks the entire mint.
-- **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.
+- **Large batch posts.** `_setupPosts` does O(n^2) duplicate detection within a batch.
+- **External hook calls in loops.** Tier-store calls inside the post loop can revert or become gas-heavy.
+- **Terminal resolution failure.** If `DIRECTORY.primaryTerminalOf()` returns `address(0)`, payment calls revert.
+- **`adjustTiers` revert.** Hook-level tier rules can block the whole `mintFrom` call.
 
 ## 5. Reentrancy Surface
 
-- **`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) `feeTerminal.pay{value}()` to pay the fee project (wrapped in try-catch, with fallback to `feeBeneficiary.call` then `msg.sender.call`). 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`. The fee terminal payment is wrapped in try-catch, so a reverting fee terminal does not block the mint — the fee falls back to `feeBeneficiary` then `msg.sender`.
-- **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.
+- **`mintFrom` external call chain.** The function calls into the hook and terminals. It currently relies on local-call state isolation rather than a `ReentrancyGuard`.
+- **Fee payment ordering.** The fee is sent after the main payment. This is safe under the current `msg.value`-based accounting model, but future mutable storage in the publisher would make the surface riskier.
 
 ## 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 incompatibly, `mintFrom` attempts to refund the fee to `_msgSender()`. If the caller cannot receive ETH, the mint reverts.
+- **Null data-hook forwarding in deployer.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` return defaults when `dataHookOf` is null.
+- **No hook migration path.** `dataHookOf` is written once and never updated.
+- **Sucker support can be absent even when requested.** A launch can complete while omnichain support is still missing.
+- **Tier ID prediction.** `_setupPosts` predicts new tier IDs ahead of the actual `adjustTiers` call.
+- **CTProjectOwner accepts any project NFT.** Accidentally transferring a non-Croptop project there still grants publisher permissions.
+- **Fee payment destination.** If the fee project changes terminal behavior incompatibly, mints fall back to refund or revert.
 
 ## 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
+### 7.1 O(n^2) duplicate detection is accepted
 
-`_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.
+Duplicate detection within a batch is quadratic, but expected real-world batch sizes are small enough that this tradeoff is acceptable.
 
-### 7.3 Project owners can bypass the publisher surface while they retain direct hook permissions
+### 7.2 Tier ID prediction assumes no concurrent tier writes
 
-`CTDeployer.deployProjectFor` intentionally grants the initial owner/operator enough hook permissions to manage the
-collection directly. That means the owner can bypass `CTPublisher`'s policy and fee path until ownership is moved into
-another authority surface or those permissions are narrowed. This is an accepted product tradeoff and should be treated
-as part of the trust model, not as a hidden invariant enforced by `CTPublisher`.
+This is a known race. The mitigation is application-layer ordering and the fact that a bad prediction reverts the whole batch cleanly.
 
-## 8. Invariants to Verify
+### 7.3 Project owners can bypass the publisher path while they still have direct hook permissions
 
-- `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).
-- Fee amount: `msg.value - payValue == totalPrice / FEE_DIVISOR` (within 19 wei rounding).
-- For every configured category, `minimumTotalSupply <= maximumTotalSupply` and `minimumTotalSupply > 0`.
-- Packed allowance encoding/decoding round-trips correctly for all valid input ranges.
-- After `CTDeployer.deployProjectFor`, the project NFT is owned by `owner`, and `dataHookOf[projectId]` is the deployed 721 hook.
-- `CTProjectOwner` only grants `ADJUST_721_TIERS` permission, never broader permissions.
+`CTDeployer.deployProjectFor` intentionally grants the initial owner enough hook permissions to manage the collection directly. That is part of the trust model until ownership is moved into a narrower surface.

package/SKILLS.md

@@ -2,8 +2,8 @@
 
 ## Use This File For
 
-- Use this file when the task touches Croptop publishing, project deployment, data-hook forwarding, fee routing, or burn-locked ownership behavior.
-- Start here, then jump into the publisher, deployer, or owner contract depending on which path the user is actually asking about.
+- Use this file when the task touches Croptop publishing, project deployment, data-hook forwarding, fee routing, or burn-locked ownership.
+- Start here, then decide whether the issue is posting-policy validation, tier reuse and content identity, deployer-packaged project shape, or burn-locked ownership.
 
 ## Read This Next
 
@@ -13,7 +13,9 @@
 | Publishing and metadata behavior | [`src/CTPublisher.sol`](./src/CTPublisher.sol) |
 | Deployment and fee-project wiring | [`src/CTDeployer.sol`](./src/CTDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/ConfigureFeeProject.s.sol`](./script/ConfigureFeeProject.s.sol) |
 | Ownership burn-lock behavior | [`src/CTProjectOwner.sol`](./src/CTProjectOwner.sol) |
-| Regression, attack, or fork coverage | [`test/regression/`](./test/regression/), [`test/fork/`](./test/fork/), [`test/`](./test/) |
+| Runtime and operational invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
+| Publishing, metadata, and attack coverage | [`test/CTPublisher.t.sol`](./test/CTPublisher.t.sol), [`test/Test_MetadataGeneration.t.sol`](./test/Test_MetadataGeneration.t.sol), [`test/CroptopAttacks.t.sol`](./test/CroptopAttacks.t.sol) |
+| Deployment, ownership, and fork coverage | [`test/CTDeployer.t.sol`](./test/CTDeployer.t.sol), [`test/CTProjectOwner.t.sol`](./test/CTProjectOwner.t.sol), [`test/ClaimCollectionOwnership.t.sol`](./test/ClaimCollectionOwnership.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
 
 ## Repo Map
 
@@ -30,12 +32,15 @@ Permissioned publishing layer for Juicebox 721 projects. Project owners define p
 
 ## Reference Files
 
-- Open [`references/runtime.md`](./references/runtime.md) when you need publisher behavior, fee routing, data-hook forwarding, or the main invariants around posting criteria and tier reuse.
-- Open [`references/operations.md`](./references/operations.md) when you need deployer behavior, burn-lock ownership implications, script breadcrumbs, or the common sources of stale assumptions.
+- Open [`references/runtime.md`](./references/runtime.md) for publisher behavior, fee routing, data-hook forwarding, and the main invariants around posting criteria and tier reuse.
+- Open [`references/operations.md`](./references/operations.md) for deployer behavior, burn-lock implications, script breadcrumbs, and common stale assumptions.
 
 ## Working Rules
 
 - Start in [`src/CTPublisher.sol`](./src/CTPublisher.sol) for posting-rule and fee behavior, but check [`src/CTDeployer.sol`](./src/CTDeployer.sol) when the bug might come from project shape or hook forwarding.
 - Treat posting criteria, fee routing, and duplicate-content handling as treasury-sensitive and product-sensitive at the same time.
+- Category policy is part of the product surface. Changes to allowlists, supply bounds, or split caps change what can be published.
 - If the task mentions project immutability or admin recovery, inspect [`src/CTProjectOwner.sol`](./src/CTProjectOwner.sol) before changing deployer or publisher code.
+- Metadata bugs can be publishing bugs, resolver-shape bugs, or duplicate-content bugs. Check all three before assuming a simple formatting issue.
+- Duplicate-post and tier-reuse behavior are runtime semantics, not convenience logic.
 - When a bug looks like generic 721 issuance, confirm it is not actually in `nana-721-hook-v6`.

package/USER_JOURNEYS.md

@@ -1,56 +1,132 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- project owners turning a Juicebox 721 project into a publishing marketplace
-- publishers creating or reusing NFT tiers as posts
-- operators locking project administration into Croptop-specific ownership patterns
+This repo turns a Juicebox 721 project into a permissioned publishing system. It owns post validation, Croptop fee routing, and the deployment packaging that turns a project into a Croptop-managed publisher. It does not own base terminal accounting or the underlying 721 tier mechanics.
+
+## Primary Actors
+
+- project owners creating a Croptop publishing surface
+- publishers minting posts into an existing Croptop project
+- auditors reviewing fee routing, posting policy, and owner-lock semantics
+
+## Key Surfaces
+
+- `CTPublisher`: validates posts, adjusts tiers, mints the first copy, and routes Croptop fees
+- `CTDeployer`: launches a Croptop-shaped project and can compose omnichain deployment
+- `CTProjectOwner`: owner helper that can burn-lock administration into Croptop
+- `mintFrom(...)`: main publishing entrypoint
 
 ## Journey 1: Turn A Project Into A Croptop Publisher
 
-**Starting state:** a project already exists or is about to launch, and the owner wants category-level posting rules.
+**Actor:** project owner.
+
+**Intent:** install Croptop publishing policy on a project.
+
+**Preconditions**
+
+- the project already exists or will be launched through `CTDeployer`
+- the owner has chosen category rules and the expected 721 hook shape
+
+**Main Flow**
+
+1. Configure category-level constraints such as price floor, supply, splits, and allowlists.
+2. Install or verify the expected 721 hook setup.
+3. Route publishing through Croptop so future posts are policy-checked instead of free-form tier edits.
 
-**Success:** Croptop posting criteria are installed and future posts must satisfy them.
+**Failure Modes**
 
-**Flow**
-1. Configure category-level posting constraints such as price floor, supply bounds, split limits, and optional allowlists.
-2. Install or verify the 721 hook shape the project expects.
-3. Route the project through Croptop's publisher logic so future post creation is policy-checked instead of free-form tier editing.
+- category rules do not match the intended publishing product
+- teams assume Croptop replaces the need to audit the underlying 721 hook
+
+**Postconditions**
+
+- the project now routes publishing through Croptop policy instead of direct free-form tier creation
 
 ## Journey 2: Publish Content Into An Existing Croptop Project
 
-**Starting state:** a publisher has a post that satisfies the target project's posting rules.
+**Actor:** publisher.
+
+**Intent:** publish one post into a Croptop project and mint the first copy.
+
+**Preconditions**
+
+- the post satisfies the target project's category policy
+- the caller can receive ETH if the fee refund fallback is needed
+- duplicate-content and stale-tier implications are understood
+
+**Main Flow**
+
+1. Call `mintFrom(...)` with the content URI and pricing data.
+2. `CTPublisher` validates the post against category and fee policy.
+3. It creates or reuses the underlying tier, mints the first copy, and routes project revenue plus the Croptop fee.
+
+**Failure Modes**
 
-**Success:** the post becomes a valid 721 tier and the first mint settles correctly.
+- duplicate URIs or stale tier mappings
+- publisher inputs satisfy the base 721 hook but violate Croptop's stricter rules
+- the fee terminal rejects the fee payment and `_msgSender()` cannot receive the refund
 
-**Flow**
-1. The publisher calls `mintFrom(...)` or the equivalent publishing surface with the content URI and pricing data.
-2. `CTPublisher` checks the post against category rules and fee policy.
-3. It creates or reuses the underlying 721 tier, mints the first copy, and routes both project revenue and the Croptop fee. If the fee terminal is unavailable, the fee is refunded to `_msgSender()` instead.
+**Postconditions**
 
-**Failure cases that matter:** duplicate URIs, split configurations that evade fees, stale tier mappings, publisher inputs that satisfy the 721 hook but violate Croptop's stricter publishing rules, and callers that cannot receive ETH when a fee refund fallback is needed.
+- the post is minted or reused as a tier under Croptop policy and the fee path is accounted for
 
 ## Journey 3: Launch A New Croptop Project End To End
 
-**Starting state:** the product wants a fresh project that already has Croptop deployment choices baked in.
+**Actor:** product team or deployer.
 
-**Success:** one deployment flow launches the project, wires the 721 hook, and installs the initial posting rules.
+**Intent:** launch a project already wired for Croptop publishing.
 
-**Flow**
-1. Use `CTDeployer` with project config, posting rules, and any omnichain deployment config.
-2. The deployer launches the Juicebox project, configures the Croptop-specific owner model, and wires in publisher behavior.
-3. The project is ready for publishers without a manual post-launch setup phase.
+**Preconditions**
+
+- the team has project config, posting rules, and any omnichain requirements ready
+- the correct `FEE_PROJECT_ID` is known
+
+**Main Flow**
+
+1. Use `CTDeployer` with project config, posting rules, and optional omnichain config.
+2. The deployer launches the project, configures Croptop ownership assumptions, and wires publisher behavior.
+3. The resulting project is ready for publishers without a manual post-launch setup gap.
+
+**Failure Modes**
+
+- the fee project is misconfigured or omitted
+- teams treat `CTDeployer` as packaging only and miss its policy implications
+
+**Postconditions**
+
+- the project is ready for Croptop publishers without a post-launch wiring gap
 
 ## Journey 4: Lock Administration Into Croptop's Owner Surface
 
-**Starting state:** the project should continue operating through Croptop's policy surface instead of ordinary project-owner discretion.
+**Actor:** project owner.
+
+**Intent:** keep governance inside Croptop's constrained owner surface.
 
-**Success:** the project's admin path is burn-locked or otherwise routed through `CTProjectOwner`.
+**Preconditions**
 
-**Flow**
-1. Transfer or configure ownership so Croptop's owner helper controls the relevant admin surface.
+- the owner wants irreversible product-shaping constraints, not ordinary owner flexibility
+
+**Main Flow**
+
+1. Transfer or configure ownership so `CTProjectOwner` controls the relevant admin surface.
 2. Restrict future edits to the paths Croptop intentionally exposes.
-3. Accept that this is a product-shaping choice, not a cosmetic deployment detail.
+3. Accept that this is an ownership-model decision, not cosmetic packaging.
+
+**Failure Modes**
+
+- teams burn-lock before validating the publishing policy in production-like conditions
+- reviewers miss that prior owner discretion no longer exists directly
+
+**Postconditions**
+
+- future administration is constrained to the Croptop owner surface instead of ordinary owner discretion
+
+## Trust Boundaries
+
+- this repo is trusted for publishing policy and fee routing
+- the underlying 721 hook remains trusted for tier issuance and lower-level NFT accounting
+- Croptop fee behavior depends on the fee project and its terminal remaining correctly configured
 
 ## Hand-Offs
 

package/foundry.toml

@@ -16,6 +16,8 @@ fail_on_revert = false
 [rpc_endpoints]
 ethereum = "${RPC_ETHEREUM_MAINNET}"
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,33 +1,33 @@
 {
-    "name": "@croptop/core-v6",
-    "version": "0.0.33",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/mejango/croptop-core-v6"
-    },
-    "scripts": {
-        "test": "forge test",
-        "coverage:integration": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
-        "deploy:mainnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
-        "deploy:mainnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks mainnets",
-        "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
-        "deploy:testnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks testnets",
-        "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'croptop-core-v5'"
-    },
-    "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.33",
-        "@bananapus/buyback-hook-v6": "^0.0.27",
-        "@bananapus/core-v6": "^0.0.34",
-        "@bananapus/ownable-v6": "^0.0.17",
-        "@bananapus/permission-ids-v6": "^0.0.17",
-        "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.25",
-        "@openzeppelin/contracts": "^5.6.1"
-    },
-    "devDependencies": {
-        "@bananapus/address-registry-v6": "^0.0.17",
-        "@rev-net/core-v6": "^0.0.31",
-        "@sphinx-labs/plugins": "^0.33.3"
-    }
+  "name": "@croptop/core-v6",
+  "version": "0.0.35",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mejango/croptop-core-v6"
+  },
+  "scripts": {
+    "test": "forge test",
+    "coverage:integration": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
+    "deploy:mainnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
+    "deploy:mainnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks mainnets",
+    "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
+    "deploy:testnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks testnets",
+    "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'croptop-core-v5'"
+  },
+  "dependencies": {
+    "@bananapus/721-hook-v6": "^0.0.35",
+    "@bananapus/buyback-hook-v6": "^0.0.27",
+    "@bananapus/core-v6": "^0.0.34",
+    "@bananapus/ownable-v6": "^0.0.17",
+    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/router-terminal-v6": "^0.0.26",
+    "@bananapus/suckers-v6": "^0.0.25",
+    "@openzeppelin/contracts": "^5.6.1"
+  },
+  "devDependencies": {
+    "@bananapus/address-registry-v6": "^0.0.17",
+    "@rev-net/core-v6": "^0.0.32",
+    "@sphinx-labs/plugins": "^0.33.3"
+  }
 }

package/references/operations.md

@@ -21,5 +21,5 @@
 
 ## Useful Proof Points
 
-- [`test/fork/`](../test/fork/) when deployment shape matters.
-- [`script/helpers/`](../script/helpers/) if the issue is really script/config assembly.
+- [`test/Fork.t.sol`](../test/Fork.t.sol) when deployment shape matters.
+- [`script/ConfigureFeeProject.s.sol`](../script/ConfigureFeeProject.s.sol) if the issue is really script/config assembly.

package/references/runtime.md

@@ -22,6 +22,6 @@
 
 ## Tests To Trust First
 
-- [`test/regression/`](../test/regression/) for pinned content and tier edge cases.
-- [`test/fork/`](../test/fork/) for live integration assumptions.
-- [`test/`](../test/) broadly when the issue could be in publisher or deployer behavior rather than one isolated function.
+- [`test/CTPublisher.t.sol`](../test/CTPublisher.t.sol) and [`test/Test_MetadataGeneration.t.sol`](../test/Test_MetadataGeneration.t.sol) for content and metadata behavior.
+- [`test/CTDeployer.t.sol`](../test/CTDeployer.t.sol) and [`test/Fork.t.sol`](../test/Fork.t.sol) for live deployment assumptions.
+- [`test/CroptopAttacks.t.sol`](../test/CroptopAttacks.t.sol) and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) when the issue could be in publisher or deployer behavior rather than one isolated function.

package/src/CTPublisher.sol

@@ -27,7 +27,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    // forge-lint: disable-next-line(mixed-case-variable)
     error CTPublisher_DuplicatePost(bytes32 encodedIPFSUri);
     error CTPublisher_EmptyEncodedIPFSUri();
     error CTPublisher_InsufficientEthSent(uint256 expected, uint256 sent);
@@ -66,7 +65,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     /// @notice The ID of the tier that an IPFS metadata has been saved to.
     /// @custom:param hook The hook for which the tier ID applies.
     /// @custom:param encodedIPFSUri The IPFS URI.
-    // forge-lint: disable-next-line(mixed-case-variable)
     mapping(address hook => mapping(bytes32 encodedIPFSUri => uint256)) public override tierIdForEncodedIPFSUriOf;
 
     //*********************************************************************//
@@ -324,7 +322,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     /// is returned.
     function tiersFor(
         address hook,
-        // forge-lint: disable-next-line(mixed-case-variable)
         bytes32[] memory encodedIPFSUris
     )
         external
@@ -332,7 +329,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
         override
         returns (JB721Tier[] memory tiers)
     {
-        // forge-lint: disable-next-line(mixed-case-variable)
         uint256 numberOfEncodedIPFSUris = encodedIPFSUris.length;
 
         // Initialize the tier array being returned.