@croptop/core-v6 0.0.27 → 0.0.29

package/README.md

@@ -1,99 +1,43 @@
 # Croptop Core
 
-Permissioned NFT publishing for Juicebox projects -- anyone can post content as NFT tiers to a project's 721 hook, provided the posts meet criteria set by the project owner. A 5% fee is routed to a designated fee project on each mint.
+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.
 
-[Docs](https://docs.juicebox.money) | [Discord](https://discord.gg/juicebox) | [Croptop](https://croptop.eth.limo)
+Docs: <https://docs.juicebox.money>  
+Site: <https://croptop.eth.limo>
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
 
-**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.
+## Overview
 
-## Conceptual Overview
+Croptop is built around three ideas:
 
-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.
+- project owners set category-level posting criteria 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
 
-### How It Works
+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.
 
-```
-1. Project owner configures posting criteria per category
-   → configurePostingCriteriaFor(allowedPosts)
-   → Sets min price, supply bounds, max split %, address allowlist
-   |
-2. Anyone posts content that meets the criteria
-   → mintFrom(hook, posts, nftBeneficiary, feeBeneficiary, ...)
-   → Validates each post against category rules
-   → Creates new 721 tiers on the hook (or reuses existing ones)
-   → Mints first copy of each tier to the poster
-   |
-3. Payment routing
-   → 5% fee (totalPrice / FEE_DIVISOR) sent to fee project
-   → Remainder paid into the project's primary terminal
-   |
-4. Anyone can mint additional copies
-   → 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.
-- The fee amount is pre-computed as `msg.value - payValue` (not derived from `address(this).balance`), so force-sent ETH does not affect fee routing. The fee terminal payment is wrapped in try-catch with a fallback to `feeBeneficiary` then `msg.sender`.
-
-### One-Click Deployment
-
-`CTDeployer` creates a complete Juicebox project + 721 hook + posting criteria in a single transaction. It also:
-- Acts as a data hook proxy, forwarding pay/cash-out calls to the underlying 721 hook
-- Grants fee-free cash outs to cross-chain suckers
-- Optionally deploys suckers for omnichain support
+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`.
 
-### Burn-Lock Ownership
+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.
 
-`CTProjectOwner` provides an ownership burn-lock pattern. Transferring a project's NFT to this contract permanently locks ownership while granting `CTPublisher` tier-adjustment permissions -- making the project's configuration immutable except through Croptop posts.
+## Key Contracts
 
-## Architecture
+| Contract | Role |
+| --- | --- |
+| `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. |
 
-| Contract | Description |
-|----------|-------------|
-| `CTPublisher` | Core publishing engine. Validates posts against owner-configured allowances (min price, supply bounds, address allowlists, max split percent), creates new 721 tiers on the hook, mints the first copy to the poster, and routes a 5% fee to a designated fee project. Inherits `JBPermissioned` and `ERC2771Context`. |
-| `CTDeployer` | One-click project factory. Deploys a Juicebox project with a 721 tiers hook pre-wired, configures posting criteria via `CTPublisher`, optionally deploys cross-chain suckers, and acts as an `IJBRulesetDataHook` proxy that forwards pay/cash-out calls to the underlying hook while granting fee-free cash outs to suckers. |
-| `CTProjectOwner` | Burn-lock ownership helper. Receives a project's ERC-721 ownership token and automatically grants `CTPublisher` the `ADJUST_721_TIERS` permission, effectively making the project's tier configuration immutable except through Croptop posts. |
+## Mental Model
 
-### Structs
+There are two separate concerns here:
 
-| Struct | Purpose |
-|--------|---------|
-| `CTAllowedPost` | Full posting criteria: hook address, category, price/supply bounds, max split percent, and address allowlist. |
-| `CTDeployerAllowedPost` | Same as `CTAllowedPost` but without the hook address (inferred during deployment). |
-| `CTPost` | A post to publish: encoded IPFS URI, total supply, price, category, split percent, and splits. |
-| `CTProjectConfig` | Project deployment configuration: terminals, metadata URIs, allowed posts, collection name/symbol, and deterministic salt. |
-| `CTSuckerDeploymentConfig` | Cross-chain sucker deployment: deployer configurations and deterministic salt. |
+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
 
-### Interfaces
-
-| Interface | Description |
-|-----------|-------------|
-| `ICTPublisher` | Publishing engine: `mintFrom`, `configurePostingCriteriaFor`, `allowanceFor`, `tiersFor`, plus events. |
-| `ICTDeployer` | Factory: `deployProjectFor`, `claimCollectionOwnershipOf`, `deploySuckersFor`. |
-| `ICTProjectOwner` | Burn-lock: `onERC721Received` (IERC721Receiver). |
+That distinction matters because many "Croptop bugs" are deployment-shape bugs rather than publishing-rule bugs.
 
 ## Install
 
@@ -101,76 +45,49 @@ Every `mintFrom` call collects a 5% fee on the total tier price. The fee is calc
 npm install @croptop/core-v6
 ```
 
-If using Forge directly:
+## Development
 
 ```bash
-forge install
+npm install
+forge build
+forge test
 ```
 
-## Develop
+Useful scripts:
+
+- `npm run deploy:mainnets`
+- `npm run deploy:testnets`
+- `npm run deploy:mainnets:project`
+- `npm run deploy:testnets:project`
+
+## 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.
 
-| Command | Description |
-|---------|-------------|
-| `forge build` | Compile contracts |
-| `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 |
+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.
 
 ## Repository Layout
 
-```
+```text
 src/
-  CTPublisher.sol                        # Core publishing engine (~590 lines)
-  CTDeployer.sol                         # Project factory + data hook proxy (~433 lines)
-  CTProjectOwner.sol                     # Burn-lock ownership helper (~84 lines)
+  CTPublisher.sol
+  CTDeployer.sol
+  CTProjectOwner.sol
   interfaces/
-    ICTPublisher.sol                     # Publisher interface + events
-    ICTDeployer.sol                      # Factory interface
-    ICTProjectOwner.sol                  # Burn-lock interface
   structs/
-    CTAllowedPost.sol                    # Posting criteria with hook address
-    CTDeployerAllowedPost.sol            # Posting criteria without hook (for deployment)
-    CTPost.sol                           # Post data: IPFS URI, supply, price, category
-    CTProjectConfig.sol                  # Full project deployment config
-    CTSuckerDeploymentConfig.sol         # Cross-chain sucker config
 test/
-  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)
+  publisher, deployer, fork, attack, audit, metadata, and regression coverage
 script/
-  Deploy.s.sol                           # Sphinx multi-chain deployment
-  ConfigureFeeProject.s.sol              # Fee project configuration
+  Deploy.s.sol
+  ConfigureFeeProject.s.sol
   helpers/
-    CroptopDeploymentLib.sol             # Deployment artifact reader
 ```
 
-## Permissions
-
-| Permission | Required For |
-|------------|-------------|
-| `ADJUST_721_TIERS` | `configurePostingCriteriaFor` -- set posting criteria on a hook (from hook owner) |
-| `DEPLOY_SUCKERS` | `deploySuckersFor` -- deploy cross-chain suckers for an existing project |
-
-`CTDeployer` grants the following to the project owner during deployment:
-- `ADJUST_721_TIERS` -- modify tiers directly
-- `SET_721_METADATA` -- update collection metadata
-- `MINT_721` -- mint NFTs directly
-- `SET_721_DISCOUNT_PERCENT` -- adjust discount rates
-
-## Risks
+## Risks And Notes
 
-- **Sucker registry compromise:** `CTDeployer.beforeCashOutRecordedWith` checks `SUCKER_REGISTRY.isSuckerOf` to grant fee-free cash outs. If the sucker registry is compromised, any address could cash out without tax.
-- **Fee skipping:** When `projectId == FEE_PROJECT_ID`, no fee is collected. This is intentional but means the fee project itself never pays Croptop fees.
-- **Allowlist scaling:** `_isAllowed()` uses linear scan over the address allowlist. Large allowlists (100+ addresses) increase gas costs proportionally.
-- **Tier reuse via IPFS URI:** If the same encoded IPFS URI has already been minted, the existing tier is reused rather than creating a new one. This prevents duplicate content but means a poster cannot create a second tier with the same content.
-- **Fee terminal failure:** The fee terminal payment is wrapped in try-catch. If the fee terminal reverts, the fee is sent to `feeBeneficiary` via low-level call, then to `msg.sender` if that also fails. A broken fee terminal never blocks mints, but the fee project loses revenue during the outage.
+- 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
+- duplicate-content and stale-tier edge cases are guarded by tests, but integrations should still treat metadata reuse carefully

package/RISKS.md

@@ -1,4 +1,21 @@
-# RISKS.md -- croptop-core-v6
+# Croptop Core Risk Register
+
+This file focuses on the publishing, fee-routing, and hook-composition risks that matter once third parties can create NFT tiers on someone else's Juicebox project.
+
+## How to use this file
+
+- Read `Priority risks` first to understand the failure modes with the highest user or treasury impact.
+- 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.
+
+## 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. |
+
 
 ## 1. Trust Assumptions
 
@@ -14,7 +31,7 @@
 - **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.
-- **Try-catch fee payment.** The fee terminal payment is wrapped in try-catch. If the fee terminal reverts, the fee is sent to `feeBeneficiary` via low-level call. If that also fails, the fee is sent to `msg.sender`. This means a broken fee terminal does not block mints, but the fee project may lose fee revenue during the outage.
+- **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.
 
 ## 3. Access Control
@@ -44,7 +61,7 @@
 - **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 will fail. However, the fee terminal payment is wrapped in try-catch: on failure, the fee is sent to `feeBeneficiary` via low-level call, then to `msg.sender` if that also fails. Minting is never blocked by a broken fee terminal, but the fee project loses revenue during the outage.
+- **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.
 
 ## 7. Accepted Behaviors
 
@@ -56,6 +73,13 @@
 
 `_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.
 
+### 7.3 Project owners can bypass the publisher surface while they retain direct hook permissions
+
+`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`.
+
 ## 8. Invariants to Verify
 
 - `tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]` is set exactly once per (hook, encodedIPFSUri) pair and points to a valid, non-removed tier.

package/SKILLS.md

@@ -1,200 +1,41 @@
 # Croptop Core
 
-## Purpose
-
-Permissioned NFT publishing system that lets anyone post content as 721 tiers to a Juicebox project, subject to owner-defined criteria for price, supply, split percentages, and poster identity. Routes a 5% fee on each mint to a designated fee project.
-
-## Contracts
-
-| Contract | Role |
-|----------|------|
-| `CTPublisher` | Core publishing engine. Validates posts against bit-packed allowances, creates 721 tiers on hooks, mints first copies to posters, and routes fees. Inherits `JBPermissioned`, `ERC2771Context`. |
-| `CTDeployer` | Factory that deploys a Juicebox project + 721 hook + posting criteria in one transaction. Also acts as `IJBRulesetDataHook` proxy that forwards pay/cash-out calls to the underlying hook while granting fee-free cash outs to suckers. |
-| `CTProjectOwner` | Burn-lock contract: receives the project ownership NFT and grants `CTPublisher` the `ADJUST_721_TIERS` permission permanently. Since `CTProjectOwner` has no `transferFrom`, `reconfigure`, or `withdraw` functions, ownership is effectively burned -- no one can reclaim the project NFT, change rulesets, or modify posting criteria after transfer. Use this when you want a fully autonomous project where only community posting (within pre-set criteria) is possible. If you need to retain the ability to reconfigure the project, adjust tiers, or withdraw funds, keep ownership yourself (or use a multisig) instead. Configure all desired posting criteria **before** transferring the project NFT here, as they become immutable once ownership moves. Accepts both mints and `safeTransferFrom` calls originating from the `PROJECTS` contract. |
-
-## Key Functions
-
-### Publishing
-
-| Function | What it does |
-|----------|-------------|
-| `CTPublisher.mintFrom(hook, posts, nftBeneficiary, feeBeneficiary, additionalPayMetadata, feeMetadata)` | Publishes posts as new 721 tiers, mints first copies to `nftBeneficiary`, deducts a 5% fee (`totalPrice / FEE_DIVISOR`) routed to `FEE_PROJECT_ID`, and pays the remainder into the project's primary terminal. Reuses existing tiers if the IPFS URI was already minted. |
-| `CTPublisher.configurePostingCriteriaFor(allowedPosts)` | Sets per-category posting rules (min price, min/max supply, max split percent, address allowlist) for a given hook. Requires `ADJUST_721_TIERS` permission from the hook owner. |
-
-### Views
-
-| Function | What it does |
-|----------|-------------|
-| `CTPublisher.allowanceFor(hook, category)` | Returns the posting criteria for a hook/category: minimum price (uint104), min supply (uint32), max supply (uint32), max split percent (uint32), plus the address allowlist. Reads from bit-packed storage. |
-| `CTPublisher.tiersFor(hook, encodedIPFSUris)` | Resolves an array of encoded IPFS URIs to their corresponding `JB721Tier` structs via the stored `tierIdForEncodedIPFSUriOf` mapping. |
-
-### Project Deployment
-
-| Function | What it does |
-|----------|-------------|
-| `CTDeployer.deployProjectFor(owner, projectConfig, suckerDeploymentConfiguration, controller)` | Deploys a new Juicebox project with a 721 tiers hook, configures posting criteria, optionally deploys suckers, and transfers project ownership to the specified owner. Uses `CTDeployer` as data hook proxy. Returns `(projectId, hook)`. |
-| `CTDeployer.claimCollectionOwnershipOf(hook)` | Transfers hook ownership to the project via `JBOwnable.transferOwnershipToProject`. Only callable by the project owner. After claiming, the project owner must grant CTPublisher `ADJUST_721_TIERS` permission for the project so that `mintFrom()` continues to work. |
-| `CTDeployer.deploySuckersFor(projectId, suckerDeploymentConfiguration)` | Deploys new cross-chain suckers for an existing project. Requires `DEPLOY_SUCKERS` permission. |
-
-### Data Hook Proxy
-
-| Function | What it does |
-|----------|-------------|
-| `CTDeployer.beforePayRecordedWith(context)` | Forwards pay context to the stored `dataHookOf[projectId]` (typically the 721 tiers hook). Hook specifications returned include a `noop` field — the 721 hook always returns `noop: false`. |
-| `CTDeployer.beforeCashOutRecordedWith(context)` | Returns zero tax rate for sucker addresses (fee-free cross-chain cash outs). Otherwise forwards to the stored data hook. Forwarded hook specifications preserve the inner hook's `noop` flag. |
-| `CTDeployer.hasMintPermissionFor(projectId, ruleset, addr)` | Returns `true` if `addr` is a sucker for the project. |
-
-### Burn-Lock Ownership
-
-| Function | What it does |
-|----------|-------------|
-| `CTProjectOwner.onERC721Received(operator, from, tokenId, data)` | On receiving the project NFT, grants `CTPublisher` the `ADJUST_721_TIERS` permission for that project. Accepts both mints and transfers from `PROJECTS` (reverts if `msg.sender` is not `PROJECTS`). |
-
-## Integration Points
+## Use This File For
 
-| Dependency | Import | Used For |
-|------------|--------|----------|
-| `@bananapus/core-v6` | `IJBDirectory`, `IJBPermissions`, `IJBTerminal`, `IJBProjects`, `IJBController`, `JBConstants`, `JBMetadataResolver` | Project lookup, permission enforcement, payment routing, project creation, metadata encoding |
-| `@bananapus/721-hook-v6` | `IJB721TiersHook`, `IJB721TiersHookDeployer`, `JB721TierConfig`, `JB721Tier` | Tier creation/adjustment, hook deployment, tier data resolution |
-| `@bananapus/ownable-v6` | `JBOwnable` | Ownership checks and transfers for hooks |
-| `@bananapus/suckers-v6` | `IJBSuckerRegistry`, `JBSuckerDeployerConfig` | Cross-chain sucker deployment and fee-free cash-out detection |
-| `@bananapus/permission-ids-v6` | `JBPermissionIds` | Permission ID constants (`ADJUST_721_TIERS`, `DEPLOY_SUCKERS`, `MAP_SUCKER_TOKEN`, etc.) |
-| `@openzeppelin/contracts` | `ERC2771Context`, `IERC721Receiver` | Meta-transaction support, safe project NFT receipt |
+- 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.
 
-## Key Types
+## Read This Next
 
-| Struct | Key Fields | Used In |
-|--------|------------|---------|
-| `CTAllowedPost` | `hook`, `category` (uint24), `minimumPrice` (uint104), `minimumTotalSupply` (uint32), `maximumTotalSupply` (uint32), `maximumSplitPercent` (uint32), `allowedAddresses[]` | `configurePostingCriteriaFor` -- used when calling `CTPublisher` directly on an existing hook |
-| `CTDeployerAllowedPost` | Same fields as `CTAllowedPost` minus `hook` | `CTProjectConfig.allowedPosts` -- used during `deployProjectFor` because the hook address is not yet known; `CTDeployer._configurePostingCriteriaFor` fills in the `hook` field automatically after deploying the hook |
-| `CTPost` | `encodedIPFSUri` (bytes32), `totalSupply` (uint32), `price` (uint104), `category` (uint24), `splitPercent` (uint32), `splits[]` (JBSplit[]) | `mintFrom` |
-| `CTProjectConfig` | `terminalConfigurations`, `projectUri`, `allowedPosts` (CTDeployerAllowedPost[]), `contractUri`, `name`, `symbol`, `salt` | `deployProjectFor` |
-| `CTSuckerDeploymentConfig` | `deployerConfigurations` (JBSuckerDeployerConfig[]), `salt` | `deployProjectFor`, `deploySuckersFor` |
+| If you need... | Open this next |
+|---|---|
+| Repo overview and expected flow | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| 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/) |
 
-## Events
+## Repo Map
 
-| Event | When |
-|-------|------|
-| `ConfigurePostingCriteria(hook, allowedPost, caller)` | Posting criteria set or updated for a hook/category |
-| `Mint(projectId, hook, nftBeneficiary, feeBeneficiary, posts, postValue, txValue, caller)` | Posts published and first copies minted |
+| Area | Where to look |
+|---|---|
+| Main contracts | [`src/`](./src/) |
+| Types | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/) |
+| Scripts | [`script/`](./script/) |
+| Tests | [`test/`](./test/) |
 
-## Errors
-
-| Error | When |
-|-------|------|
-| `CTPublisher_EmptyEncodedIPFSUri` | Post has `encodedIPFSUri == bytes32(0)` |
-| `CTPublisher_InsufficientEthSent` | `totalPrice + fee > msg.value` |
-| `CTPublisher_MaxTotalSupplyLessThanMin` | `minimumTotalSupply > maximumTotalSupply` in config |
-| `CTPublisher_NotInAllowList` | Caller not in allowlist (when allowlist is non-empty) |
-| `CTPublisher_PriceTooSmall` | Post price below `minimumPrice` |
-| `CTPublisher_SplitPercentExceedsMaximum` | Post `splitPercent > maximumSplitPercent` |
-| `CTPublisher_TotalSupplyTooSmall` | Post `totalSupply < minimumTotalSupply` |
-| `CTPublisher_TotalSupplyTooBig` | Post `totalSupply > maximumTotalSupply` (when max > 0) |
-| `CTPublisher_UnauthorizedToPostInCategory` | Category unconfigured (`minSupply == 0`) |
-| `CTPublisher_ZeroTotalSupply` | `configurePostingCriteriaFor` with `minimumTotalSupply == 0` |
-| `CTPublisher_DuplicatePost(bytes32 encodedIPFSUri)` | Same `encodedIPFSUri` appears more than once within the same `mintFrom` batch |
-| `CTDeployer_NotOwnerOfProject` | `claimCollectionOwnershipOf` called by non-owner |
-
-## Constants
-
-| Constant | Value | Purpose |
-|----------|-------|---------|
-| `FEE_DIVISOR` | 20 | 5% fee: `totalPrice / 20` |
-| `FEE_PROJECT_ID` | immutable | Fees routed to this project. Fee skipped when `projectId == FEE_PROJECT_ID` |
-
-## Storage
-
-### CTPublisher
-
-| Variable | Type | Purpose |
-|----------|------|---------|
-| `tierIdForEncodedIPFSUriOf` | `hook => encodedIPFSUri => uint256` | Maps IPFS URI to existing tier ID (prevents duplicates) |
-| `_packedAllowanceFor` | `hook => category => uint256` | Bit-packed allowance: price (0-103), minSupply (104-135), maxSupply (136-167), maxSplitPercent (168-199) |
-| `_allowedAddresses` | `hook => category => address[]` | Per-category address allowlist |
-
-### CTDeployer
-
-| Variable | Type | Purpose |
-|----------|------|---------|
-| `PROJECTS` | `IJBProjects` (immutable) | ERC-721 contract for Juicebox project ownership |
-| `DEPLOYER` | `IJB721TiersHookDeployer` (immutable) | Factory for deploying 721 tiers hooks |
-| `PUBLISHER` | `ICTPublisher` (immutable) | CTPublisher instance used for posting |
-| `SUCKER_REGISTRY` | `IJBSuckerRegistry` (immutable) | Registry for cross-chain sucker deployment and lookup |
-| `dataHookOf` | `projectId => IJBRulesetDataHook` | Stores original data hook per project (CTDeployer proxy pattern) |
-
-## Gotchas
-
-1. **Bit-packed allowances.** Allowances are packed into a single `uint256`: price in bits 0-103, min supply in 104-135, max supply in 136-167, max split percent in 168-199. Reading with wrong bit widths silently returns wrong values.
-2. **Fee is 1/20, not a percentage.** `FEE_DIVISOR = 20` means fee = `totalPrice / 20` = 5%. Integer division truncates (rounding down favors payer).
-3. **Fee skipped for fee project.** When `projectId == FEE_PROJECT_ID`, no fee is deducted. This prevents self-referential fee loops.
-4. **Fee payment is pre-computed and try-catch wrapped.** After the main payment, `mintFrom` computes the fee as `msg.value - payValue` and sends it to the fee terminal via try-catch. If the fee terminal reverts, the fee falls back to `feeBeneficiary.call{value}`, then `msg.sender.call{value}`. A broken fee terminal never blocks mints.
-5. **Tier reuse by IPFS URI.** If an encoded IPFS URI was already minted on the hook, the existing tier ID is reused instead of creating a new tier. The poster still gets a mint of the existing tier. The fee is calculated from the actual tier price stored on-chain (not from `post.price`), preventing fee evasion (H-19 fix).
-6. **Stale tier mapping cleanup.** If a tier was removed externally via `adjustTiers()`, the `tierIdForEncodedIPFSUriOf` mapping is automatically cleared when the same IPFS URI is posted again, allowing a new tier to be created (L-52 fix).
-7. **Array resizing via assembly.** `_setupPosts` resizes `tiersToAdd` via inline assembly when some posts reuse existing tiers. The `tierIdsToMint` array is NOT resized and may contain zeros for pre-existing tiers.
-8. **CTProjectOwner only accepts from PROJECTS contract.** `onERC721Received` reverts if `msg.sender != address(PROJECTS)`. It does NOT check the `from` address, so both mints and transfers through `PROJECTS.safeTransferFrom` are accepted.
-9. **CTDeployer rejects direct transfers.** `CTDeployer.onERC721Received` reverts if `from != address(0)`. It only accepts mints from `PROJECTS`.
-10. **Temporary ownership during deployment.** `CTDeployer` owns the project NFT temporarily during `deployProjectFor` (to configure permissions and hooks), then transfers it to the specified `owner`. If the transfer reverts, the entire deployment fails.
-11. **Data hook proxy pattern.** `CTDeployer` wraps itself as the data hook, forwarding to `dataHookOf[projectId]`. This is needed to intercept cash-out calls and grant fee-free cash outs to suckers. Both `useDataHookForPay` and `useDataHookForCashOut` are enabled (M-37 fix).
-12. **Sucker registry trust.** `CTDeployer.beforeCashOutRecordedWith` trusts `SUCKER_REGISTRY.isSuckerOf` to determine fee exemption. If the registry is compromised, any address could cash out without tax.
-13. **Allowlist uses linear scan.** `_isAllowed()` iterates the full allowlist array. Acceptable for <100 addresses; gas cost scales linearly with list size. This also affects `mintFrom` with large post batches: each post in the batch triggers a separate allowlist scan, so gas scales as `O(posts * allowlistSize)`. Keep batches under ~20 posts with allowlists under ~50 addresses to stay within block gas limits.
-14. **Referral ID in metadata.** `FEE_PROJECT_ID` is stored in the first 32 bytes of mint metadata (via assembly `mstore`), allowing the fee terminal to track referrals.
-15. **Deterministic deployment.** Hook salt is `keccak256(abi.encode(projectConfig.salt, msg.sender))` and sucker salt is `keccak256(abi.encode(suckerConfig.salt, msg.sender))`. Different callers with the same salt get different addresses.
-16. **Default project weight.** `CTDeployer` deploys projects with `weight = 1_000_000 * 10^18`, ETH currency, and `maxCashOutTaxRate`. These defaults are hardcoded.
-17. **ERC2771 meta-transaction support.** Both `CTPublisher` and `CTDeployer` support meta-transactions via `ERC2771Context` with a configurable trusted forwarder, allowing relayers to submit transactions on behalf of users.
-
-## Example Integration
-
-```solidity
-import {ICTPublisher} from "@croptop/core-v6/src/interfaces/ICTPublisher.sol";
-import {CTPost} from "@croptop/core-v6/src/structs/CTPost.sol";
-import {IJB721TiersHook} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHook.sol";
-
-// --- Post content to a Croptop-enabled project ---
-
-CTPost[] memory posts = new CTPost[](1);
-posts[0] = CTPost({
-    encodedIPFSUri: 0x1234..., // encoded IPFS CID
-    totalSupply: 100,
-    price: 0.01 ether,
-    category: 1,
-    splitPercent: 0,
-    splits: new JBSplit[](0)
-});
+## Purpose
 
-// Price + 5% fee
-uint256 totalCost = 0.01 ether + (0.01 ether / 20);
+Permissioned publishing layer for Juicebox 721 projects. Project owners define posting rules, publishers mint content as tiers through a 721 hook, Croptop routes fees, and the deployer can package the whole project shape in one transaction.
 
-publisher.mintFrom{value: totalCost}(
-    IJB721TiersHook(hookAddress),
-    posts,
-    msg.sender, // NFT beneficiary
-    msg.sender, // fee beneficiary
-    "",         // additional pay metadata
-    ""          // fee metadata
-);
+## Reference Files
 
-// --- Deploy a new Croptop project ---
+- 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.
 
-(uint256 projectId, IJB721TiersHook hook) = deployer.deployProjectFor({
-    owner: msg.sender,
-    projectConfig: CTProjectConfig({
-        terminalConfigurations: terminals,
-        projectUri: "ipfs://...",
-        allowedPosts: allowedPosts,
-        contractUri: "ipfs://...",
-        name: "My Collection",
-        symbol: "MYC",
-        salt: bytes32("my-project")
-    }),
-    suckerDeploymentConfiguration: CTSuckerDeploymentConfig({
-        deployerConfigurations: new JBSuckerDeployerConfig[](0),
-        salt: bytes32(0)
-    }),
-    controller: IJBController(controllerAddress)
-});
+## Working Rules
 
-// --- Lock ownership via CTProjectOwner ---
-// Transfer the project NFT to CTProjectOwner to burn-lock ownership
-// while keeping Croptop posting enabled.
-IERC721(projects).safeTransferFrom(msg.sender, address(projectOwner), projectId);
-```
+- 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.
+- If the task mentions project immutability or admin recovery, inspect [`src/CTProjectOwner.sol`](./src/CTProjectOwner.sol) before changing deployer or publisher code.
+- When a bug looks like generic 721 issuance, confirm it is not actually in `nana-721-hook-v6`.