@croptop/core-v6 0.0.38 → 0.0.40

package/README.md

@@ -80,8 +80,8 @@ npm install @croptop/core-v6
 
 ```bash
 npm install
-forge build
-forge test
+forge build --deny notes
+forge test --deny notes --fail-fast --summary --detailed --skip "*/script/**"
 ```
 
 Useful scripts:

package/foundry.toml

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

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "@croptop/core-v6",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mejango/croptop-core-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/ConfigureFeeProject.s.sol",
+    "script/Deploy.s.sol",
+    "script/helpers/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "scripts": {
     "test": "forge test",
     "coverage:integration": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
@@ -13,21 +26,20 @@
     "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'"
+    "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'croptop-core-v6'"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.38",
-    "@bananapus/buyback-hook-v6": "^0.0.30",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/ownable-v6": "^0.0.20",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@bananapus/router-terminal-v6": "^0.0.30",
-    "@bananapus/suckers-v6": "^0.0.28",
-    "@openzeppelin/contracts": "^5.6.1"
+    "@bananapus/721-hook-v6": "0.0.43",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/ownable-v6": "0.0.24",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/router-terminal-v6": "0.0.36",
+    "@bananapus/suckers-v6": "0.0.33",
+    "@openzeppelin/contracts": "5.6.1",
+    "@rev-net/core-v6": "0.0.37"
   },
   "devDependencies": {
-    "@bananapus/address-registry-v6": "^0.0.17",
-    "@rev-net/core-v6": "^0.0.32",
-    "@sphinx-labs/plugins": "^0.33.3"
+    "@bananapus/address-registry-v6": "0.0.25",
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/script/ConfigureFeeProject.s.sol

@@ -248,14 +248,16 @@ contract ConfigureFeeProjectScript is Script, Sphinx {
             if (block.chainid == 1 || block.chainid == 11_155_111) {
                 suckerDeployerConfigurations = new JBSuckerDeployerConfig[](3);
                 // OP
-                suckerDeployerConfigurations[0] =
-                    JBSuckerDeployerConfig({deployer: suckers.optimismDeployer, mappings: tokenMappings});
+                suckerDeployerConfigurations[0] = JBSuckerDeployerConfig({
+                    deployer: suckers.optimismDeployer, peer: bytes32(0), mappings: tokenMappings
+                });
 
                 suckerDeployerConfigurations[1] =
-                    JBSuckerDeployerConfig({deployer: suckers.baseDeployer, mappings: tokenMappings});
+                    JBSuckerDeployerConfig({deployer: suckers.baseDeployer, peer: bytes32(0), mappings: tokenMappings});
 
-                suckerDeployerConfigurations[2] =
-                    JBSuckerDeployerConfig({deployer: suckers.arbitrumDeployer, mappings: tokenMappings});
+                suckerDeployerConfigurations[2] = JBSuckerDeployerConfig({
+                    deployer: suckers.arbitrumDeployer, peer: bytes32(0), mappings: tokenMappings
+                });
             } else {
                 suckerDeployerConfigurations = new JBSuckerDeployerConfig[](1);
                 // L2 -> Mainnet
@@ -263,6 +265,7 @@ contract ConfigureFeeProjectScript is Script, Sphinx {
                     deployer: address(suckers.optimismDeployer) != address(0)
                         ? suckers.optimismDeployer
                         : address(suckers.baseDeployer) != address(0) ? suckers.baseDeployer : suckers.arbitrumDeployer,
+                    peer: bytes32(0),
                     mappings: tokenMappings
                 });
 

package/src/CTDeployer.sol

@@ -36,24 +36,33 @@ import {CTDeployerAllowedPost} from "./structs/CTDeployerAllowedPost.sol";
 import {CTProjectConfig} from "./structs/CTProjectConfig.sol";
 import {CTSuckerDeploymentConfig} from "./structs/CTSuckerDeploymentConfig.sol";
 
-/// @notice A contract that facilitates deploying a simple Juicebox project to receive posts from Croptop templates.
+/// @notice Deploys Juicebox projects pre-configured for Croptop — a permissionless NFT publishing system. Each
+/// deployed project gets a tiered 721 hook (for minting posted NFTs), an optional set of cross-chain suckers, and this
+/// contract set as the data hook so suckers get 0% cash-out tax and mint permission. The hook initially remains owned
+/// by this deployer (allowing the publisher to add tiers); the project owner can later claim full hook ownership via
+/// `claimCollectionOwnershipOf`.
 contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC721Receiver, ICTDeployer {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
     error CTDeployer_NotOwnerOfProject(uint256 projectId, address hook, address caller);
+    //*********************************************************************//
+    // ---------------------------- events -------------------------------- //
+    //*********************************************************************//
+
+    event CTDeployer_SuckerDeploymentFailed(uint256 indexed projectId, bytes32 indexed salt, bytes reason);
 
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //
     //*********************************************************************//
 
-    /// @notice Mints ERC-721s that represent Juicebox project ownership and transfers.
-    IJBProjects public immutable override PROJECTS;
-
     /// @notice The deployer to launch Croptop recorded collections from.
     IJB721TiersHookDeployer public immutable override DEPLOYER;
 
+    /// @notice Mints ERC-721s that represent Juicebox project ownership and transfers.
+    IJBProjects public immutable override PROJECTS;
+
     /// @notice The Croptop publisher.
     ICTPublisher public immutable override PUBLISHER;
 
@@ -95,25 +104,13 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         PUBLISHER = publisher;
         SUCKER_REGISTRY = suckerRegistry;
 
-        // Give the sucker registry permission to map tokens for all revnets.
+        // Set permission for the CTPublisher to adjust tiers while the deployer temporarily owns new hooks.
         uint8[] memory permissionIds = new uint8[](1);
-        permissionIds[0] = JBPermissionIds.MAP_SUCKER_TOKEN;
-
-        // Give the operator the permission.
-        // Set up the permission data.
-        JBPermissionsData memory permissionData =
-            JBPermissionsData({operator: address(SUCKER_REGISTRY), projectId: 0, permissionIds: permissionIds});
-
-        // Set the permissions.
-        PERMISSIONS.setPermissionsFor({account: address(this), permissionsData: permissionData});
-
-        // Set permission for the CTPublisher to adjust the tier.
         permissionIds[0] = JBPermissionIds.ADJUST_721_TIERS;
 
-        // Set permission for the CTPublisher to mint the NFT.
-        permissionData = JBPermissionsData({operator: address(PUBLISHER), projectId: 0, permissionIds: permissionIds});
+        JBPermissionsData memory permissionData =
+            JBPermissionsData({operator: address(PUBLISHER), projectId: 0, permissionIds: permissionIds});
 
-        // Set permission for the CTPublisher to adjust the tier.
         PERMISSIONS.setPermissionsFor({account: address(this), permissionsData: permissionData});
     }
 
@@ -137,7 +134,7 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
 
         // Make sure the caller is the owner of the project.
         if (PROJECTS.ownerOf(projectId) != _msgSender()) {
-            revert CTDeployer_NotOwnerOfProject(projectId, address(hook), _msgSender());
+            revert CTDeployer_NotOwnerOfProject({projectId: projectId, hook: address(hook), caller: _msgSender()});
         }
 
         // Transfer the hook's ownership to the project.
@@ -145,9 +142,9 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
     }
 
     /// @notice Deploy a simple project meant to receive posts from Croptop templates.
-    /// @dev The initial project owner is intentionally granted direct hook-management permissions from
-    /// `CTDeployer`. This means the owner/operator can bypass the Croptop publisher path and interact
-    /// with the hook directly if they choose to. That is an explicit product tradeoff.
+    /// @dev The deployed hook remains owned by `CTDeployer` until the project owner claims collection ownership.
+    /// The initial owner is granted direct deployer-scoped hook permissions as a launch-time convenience. Those
+    /// permissions can bypass Croptop's publisher surface until ownership is claimed away from the deployer.
     /// @param owner The address that'll own the project.
     /// @param projectConfig The configuration for the project.
     /// @param suckerDeploymentConfiguration The configuration for the suckers to deploy.
@@ -170,8 +167,8 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         rulesetConfigurations[0].weight = 1_000_000 * (10 ** 18);
         rulesetConfigurations[0].metadata.baseCurrency = JBCurrencyIds.ETH;
 
-        // Get the next project ID.
-        projectId = PROJECTS.count() + 1;
+        // Reserve the project ID up front so permissionless project creations cannot invalidate hook deployment.
+        projectId = PROJECTS.createFor(address(this));
 
         // Deploy a blank project.
         // slither-disable-next-line reentrancy-benign
@@ -202,17 +199,15 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         rulesetConfigurations[0].metadata.useDataHookForPay = true;
         rulesetConfigurations[0].metadata.useDataHookForCashOut = true;
 
-        // Launch the project, and sanity check the project ID.
-        assert(
-            projectId
-                == controller.launchProjectFor({
-                    owner: address(this),
-                    projectUri: projectConfig.projectUri,
-                    rulesetConfigurations: rulesetConfigurations,
-                    terminalConfigurations: projectConfig.terminalConfigurations,
-                    memo: "Deployed from Croptop"
-                })
-        );
+        // Launch the rulesets for the reserved project.
+        // slither-disable-next-line unused-return
+        controller.launchRulesetsFor({
+            projectId: projectId,
+            projectUri: projectConfig.projectUri,
+            rulesetConfigurations: rulesetConfigurations,
+            terminalConfigurations: projectConfig.terminalConfigurations,
+            memo: "Deployed from Croptop"
+        });
 
         // Set the data hook for the project.
         dataHookOf[projectId] = IJBRulesetDataHook(hook);
@@ -227,23 +222,32 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         // intentionally ordered. If both deployers fail, the deployment proceeds without suckers rather than reverting,
         // allowing projects to launch on unsupported chains with manual sucker setup later.
         if (suckerDeploymentConfiguration.salt != bytes32(0)) {
+            bytes32 suckerSalt = keccak256(abi.encode(suckerDeploymentConfiguration.salt, _msgSender()));
+
+            // Successful deployments are discoverable from the registry, and failures are reported without reverting
+            // the project launch.
             // slither-disable-next-line unused-return
-            SUCKER_REGISTRY.deploySuckersFor({
+            try SUCKER_REGISTRY.deploySuckersFor({
                 projectId: projectId,
-                salt: keccak256(abi.encode(suckerDeploymentConfiguration.salt, _msgSender())),
+                salt: suckerSalt,
                 configurations: suckerDeploymentConfiguration.deployerConfigurations
-            });
+            }) returns (
+                address[] memory
+            ) {
+            // no-op
+            }
+            catch (bytes memory reason) {
+                // slither-disable-next-line reentrancy-events
+                emit CTDeployer_SuckerDeploymentFailed({projectId: projectId, salt: suckerSalt, reason: reason});
+            }
         }
 
-        //transfer to _owner.
+        // Transfer the project NFT to its intended owner.
         PROJECTS.transferFrom({from: address(this), to: owner, tokenId: projectId});
 
-        // Set permission for the project's owner to do all the NFT things.
-        // These permissions are granted from CTDeployer (address(this)) to the initial owner.
-        // The hook checks permissions against hook.owner(), which after claimCollectionOwnershipOf() resolves
-        // dynamically via PROJECTS.ownerOf(projectId). Before claiming, CTDeployer is the static hook owner,
-        // so these permissions allow the project owner to manage tiers through CTDeployer. As a tradeoff,
-        // the owner can also bypass the Croptop publisher surface until ownership is claimed away.
+        // Give the initial project owner direct collection-control permissions while CTDeployer remains the hook's
+        // owner. This preserves the documented Croptop launch tradeoff: the owner can manage the collection directly
+        // before calling `claimCollectionOwnershipOf(...)`, after which hook permissions follow the project NFT owner.
         uint8[] memory permissionIds = new uint8[](4);
         permissionIds[0] = JBPermissionIds.ADJUST_721_TIERS;
         permissionIds[1] = JBPermissionIds.SET_721_METADATA;
@@ -253,7 +257,7 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         PERMISSIONS.setPermissionsFor({
             account: address(this),
             permissionsData: JBPermissionsData({
-                operator: address(owner),
+                operator: owner,
                 // forge-lint: disable-next-line(unsafe-typecast)
                 projectId: uint64(projectId),
                 permissionIds: permissionIds
@@ -272,12 +276,13 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         external
         returns (address[] memory suckers)
     {
-        // Enforce permissions.
-        _requirePermissionFrom({
-            account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.DEPLOY_SUCKERS
-        });
+        address owner = PROJECTS.ownerOf(projectId);
+
+        // First prove the external caller is allowed to request sucker deployment for the project owner.
+        _requirePermissionFrom({account: owner, projectId: projectId, permissionId: JBPermissionIds.DEPLOY_SUCKERS});
 
-        // Deploy the suckers.
+        // Deploy the suckers. The sucker registry performs its own permission check against this forwarding helper,
+        // so an unapproved CTDeployer fails at the downstream registry boundary without an extra preflight read here.
         // slither-disable-next-line unused-return
         suckers = SUCKER_REGISTRY.deploySuckersFor({
             projectId: projectId,
@@ -290,8 +295,10 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Allow cash outs from suckers without a tax.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a cash out.
+    /// @notice Called before a cash out is recorded. Grants suckers 0% tax so bridged tokens redeem at full value.
+    /// For non-sucker holders, delegates to the project's stored data hook (if any) or passes through the original
+    /// context values.
+    /// @dev Part of `IJBRulesetDataHook`.
     /// @param context Standard Juicebox cash out context. See `JBBeforeCashOutRecordedContext`.
     /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens which get cashed
     /// out.
@@ -331,8 +338,9 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         return hook.beforeCashOutRecordedWith(context);
     }
 
-    /// @notice Forward the call to the original data hook.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a payment.
+    /// @notice Called before a payment is recorded. Delegates to the project's stored data hook (the 721 hook) so NFT
+    /// tier minting logic runs. If no hook is set, passes through the original weight.
+    /// @dev Part of `IJBRulesetDataHook`.
     /// @param context Standard Juicebox payment context. See `JBBeforePayRecordedContext`.
     /// @return weight The weight which project tokens are minted relative to. This can be used to customize how many
     /// tokens get minted by a payment.
@@ -354,8 +362,9 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         return hook.beforePayRecordedWith(context);
     }
 
-    /// @notice A flag indicating whether an address has permission to mint a project's tokens on-demand.
-    /// @dev A project's data hook can allow any address to mint its tokens.
+    /// @notice Returns whether an address may mint a project's tokens on-demand. Only suckers get this permission, so
+    /// bridged tokens can be minted on the destination chain.
+    /// @dev Part of `IJBRulesetDataHook`.
     /// @param projectId The ID of the project whose token can be minted.
     /// @param addr The address to check the token minting permission of.
     /// @return flag A flag indicating whether the address has permission to mint the project's tokens on-demand.

package/src/CTProjectOwner.sol

@@ -10,10 +10,12 @@ import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.
 import {ICTProjectOwner} from "./interfaces/ICTProjectOwner.sol";
 import {ICTPublisher} from "./interfaces/ICTPublisher.sol";
 
-/// @notice A contract that can be sent a project to be burned, while still allowing croptop posts.
-/// @dev This contract does not expose any function to reconfigure posting criteria. This is by design: posting
-/// criteria are set before transferring the project here, and become immutable once ownership is transferred.
-/// The project owner should configure all desired posting criteria before sending the project NFT to this contract.
+/// @notice A dead-end owner for Juicebox projects that locks ownership while preserving Croptop posting. When a project
+/// NFT is transferred to this contract via `safeTransferFrom`, it automatically grants the Croptop publisher
+/// `ADJUST_721_TIERS` permission so posts can continue. The project can never be transferred out again — effectively
+/// burning ownership while keeping the collection alive.
+/// @dev This contract does not expose any function to reconfigure posting criteria. Criteria are set before
+/// transferring the project here and become immutable once ownership is transferred.
 contract CTProjectOwner is IERC721Receiver, ICTProjectOwner {
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //

package/src/CTPublisher.sol

@@ -21,7 +21,11 @@ import {ICTPublisher} from "./interfaces/ICTPublisher.sol";
 import {CTAllowedPost} from "./structs/CTAllowedPost.sol";
 import {CTPost} from "./structs/CTPost.sol";
 
-/// @notice A contract that facilitates the permissioned publishing of NFT posts to a Juicebox project.
+/// @notice The Croptop publishing engine. Allows anyone to publish NFT posts to a Juicebox project's 721 hook, subject
+/// to per-category posting criteria set by the collection owner (minimum price, supply bounds, allowlist, max split
+/// percent). On each mint, the publisher creates new 721 tiers, routes a 5% fee to the fee project, and pays the
+/// remainder into the project's terminal. Duplicate IPFS URIs are tracked so subsequent mints of the same content reuse
+/// the existing tier rather than creating a new one.
 contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -109,7 +113,10 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Collection owners can set the allowed criteria for publishing a new NFT to their project.
+    /// @notice Lets collection owners define the rules for what can be posted in each category — minimum price,
+    /// supply
+    /// bounds, maximum split percent, and an optional allowlist of addresses. Each call replaces the existing criteria
+    /// for the specified categories.
     /// @param allowedPosts An array of criteria for allowed posts.
     // Categories cannot be fully disabled after creation. This is by design — once a category is
     // created, removing posting would break expectations for existing posters. Projects can set restrictive
@@ -171,8 +178,11 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
         }
     }
 
-    /// @notice Publish an NFT to become mintable, and mint a first copy.
-    /// @dev A fee is taken into the appropriate treasury.
+    /// @notice Publish one or more NFT posts to a project's 721 hook and mint a first copy of each. For each new post,
+    /// a tier is created on the hook. A 5% fee (1/FEE_DIVISOR) is taken from the total tier prices and routed to the
+    /// fee
+    /// project; the remainder is paid into the project's terminal, minting NFTs for the beneficiary.
+    /// @dev Reverts if any post violates the category's configured allowance (price, supply, split, allowlist).
     /// @param hook The hook to mint from.
     /// @param posts An array of posts that should be published as NFTs to the specified project.
     /// @param nftBeneficiary The beneficiary of the NFT mints.

package/src/interfaces/ICTDeployer.sol

@@ -24,8 +24,8 @@ interface ICTDeployer {
     function PUBLISHER() external view returns (ICTPublisher);
 
     /// @notice Claim ownership of a tiered ERC-721 hook collection by transferring it to the project.
-    /// @dev After claiming, CTPublisher is atomically granted the ADJUST_721_TIERS permission so that mintFrom()
-    /// continues to work.
+    /// @dev After claiming, hook ownership resolves through the current project NFT owner. That owner must grant
+    /// CTPublisher the ADJUST_721_TIERS permission separately for mintFrom() to continue working.
     /// @param hook The hook to claim ownership of. The caller must own the project the hook belongs to.
     function claimCollectionOwnershipOf(IJB721TiersHook hook) external;
 

package/src/structs/CTProjectConfig.sol

@@ -4,13 +4,14 @@ pragma solidity ^0.8.0;
 import {JBTerminalConfig} from "@bananapus/core-v6/src/structs/JBTerminalConfig.sol";
 import {CTDeployerAllowedPost} from "../structs/CTDeployerAllowedPost.sol";
 
-/// @param terminalConfigurations The terminals that the network uses to accept payments through.
+/// @notice Configuration for deploying a new Croptop project via CTDeployer.
+/// @param terminalConfigurations The terminals that the project uses to accept payments through.
 /// @param projectUri The metadata URI containing project info.
-/// @param allowedPosts The type of posts that the project should allow.
-/// @param contractUri A link to the collection's metadata.
-/// @param name The name of the collection where posts will go.
-/// @param symbol The symbol of the collection where posts will go.
-/// @param salt A salt to use for the deterministic deployment.
+/// @param allowedPosts The posting criteria that define what kinds of NFTs can be published to each category.
+/// @param contractUri A link to the 721 collection's metadata (e.g. OpenSea-compatible contract-level metadata).
+/// @param name The name of the 721 collection where posts will be minted.
+/// @param symbol The symbol of the 721 collection where posts will be minted.
+/// @param salt A salt for deterministic deployment of the 721 hook (includes msg.sender for replay protection).
 struct CTProjectConfig {
     JBTerminalConfig[] terminalConfigurations;
     string projectUri;

package/ADMINISTRATION.md

@@ -1,94 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Croptop deployment flow, publish-policy administration, and irreversible project owner sink behavior |
-| Control posture | Mixed deployer-managed and project-local control |
-| Highest-risk actions | Burn-locking a project into `CTProjectOwner`, misconfiguring posting criteria, and deploying suckers with the wrong authority assumptions |
-| Recovery posture | Posting policy can often be changed, but burn-lock and some deployer wiring choices usually require replacement flows |
-
-## Purpose
-
-`croptop-core-v6` has two distinct control planes: project-local publishing control and deployer-level structural wiring. The high-risk surfaces are posting criteria, hook ownership, publisher permissions, and the irreversible `CTProjectOwner` burn-lock path.
-
-## Control Model
-
-- `CTPublisher` enforces publish policy but does not own the project.
-- `CTDeployer` is both a deployment helper and a live ruleset data-hook wrapper.
-- The initial project owner receives direct hook-management permissions from `CTDeployer` at deployment time.
-- Project owners or delegates administer publishing through the hook owner and `JBPermissions`.
-- `CTProjectOwner` is an irreversible ownership sink for projects that want Croptop-mediated control.
-- `SUCKER_REGISTRY` and `PUBLISHER` receive structural permissions from `CTDeployer`.
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Project owner | `JBProjects.ownerOf(projectId)` | Per project | May grant delegates through `JBPermissions` |
-| Hook owner | `JBOwnable(hook).owner()` | Per hook | Often resolves to the project owner after claim |
-| `CTDeployer` | Immutable singleton | Global | Launch helper and runtime wrapper |
-| `CTPublisher` | Immutable singleton | Global runtime surface | Needs `ADJUST_721_TIERS` authority on relevant hooks |
-| `CTProjectOwner` | Receives project NFT transfer | Per project | Burn-lock path with no return function |
-| `SUCKER_REGISTRY` | Immutable dependency | Global | Holds wildcard `MAP_SUCKER_TOKEN` from the deployer |
-
-## Privileged Surfaces
-
-| Contract | Function | Who Can Call | Effect |
-| --- | --- | --- | --- |
-| `CTDeployer` | `deployProjectFor(...)` | Anyone | Launches a Croptop-shaped project and configures initial permissions |
-| `CTDeployer` | `claimCollectionOwnershipOf(...)` | Current project owner | Transfers hook ownership from the deployer path to the project |
-| `CTDeployer` | `deploySuckersFor(...)` | Project owner or `DEPLOY_SUCKERS` delegate | Extends a project with suckers |
-| `CTPublisher` | `configurePostingCriteriaFor(...)` | Hook owner or `ADJUST_721_TIERS` delegate | Changes posting policy for a hook and category |
-| `CTPublisher` | `mintFrom(...)` | Anyone subject to policy | Publishes posts, mints first copies, and routes the Croptop fee |
-| `CTProjectOwner` | `onERC721Received(...)` | Any project NFT transfer into it | Locks the project into the Croptop owner helper and grants `CTPublisher` tier-adjust authority |
-
-Important nuance:
-
-- after `deployProjectFor(...)`, the initial project owner can directly manage tiers, metadata, minting, and discount percent through permissions granted from `CTDeployer`
-- that means the owner can bypass the publisher path until ownership is claimed away from `CTDeployer`
-
-## Immutable And One-Way
-
-- `CTDeployer`'s wildcard permission grants to `SUCKER_REGISTRY` and `CTPublisher` are structural.
-- `dataHookOf[projectId]` is write-once through deployment flow.
-- Sending a project NFT into `CTProjectOwner` is effectively irreversible.
-- `FEE_PROJECT_ID` in `CTPublisher` is constructor-immutable.
-
-## Operational Notes
-
-- Validate posting criteria before broad publisher access.
-- Decide intentionally whether the project should keep the initial direct-management path or move to project-owned hook control with `claimCollectionOwnershipOf(...)`.
-- Use `claimCollectionOwnershipOf(...)` when the project should own the hook directly instead of relying on the deployer as the ownership bridge.
-- Treat the burn-lock path as governance finality, not convenience.
-- Review Croptop deployer changes as both launch-time and runtime changes.
-
-## Machine Notes
-
-- Do not treat `CTDeployer` as a passive script helper; it is also part of the live runtime path.
-- Treat `src/CTPublisher.sol`, `src/CTDeployer.sol`, and `src/CTProjectOwner.sol` as the minimum source set for control-plane review.
-- If a project NFT has already been sent to `CTProjectOwner`, stop assuming the original owner can recover it.
-
-## Recovery
-
-- If posting policy is wrong but the project still controls the hook, fix it through `configurePostingCriteriaFor(...)`.
-- If the wrong hook path or burn-lock path was chosen, recovery usually means a new project or new hook arrangement.
-- `CTProjectOwner` is not a reversible safety valve.
-
-## Admin Boundaries
-
-- Neither project owners nor Croptop can change the fixed fee divisor in `CTPublisher`.
-- `CTPublisher` cannot trap fee ETH intentionally; failed fee-terminal payments refund `_msgSender()` or revert.
-- `CTProjectOwner` cannot return project ownership once it receives the NFT.
-- `CTDeployer` cannot later rewrite `dataHookOf[projectId]` through a setter.
-- `CTDeployer` does not stop the initial project owner from using the directly granted hook permissions before ownership is claimed away.
-
-## Source Map
-
-- `src/CTPublisher.sol`
-- `src/CTDeployer.sol`
-- `src/CTProjectOwner.sol`
-- `script/Deploy.s.sol`
-- `script/helpers/CroptopDeploymentLib.sol`
-- `test/TestAuditGaps.sol`