@croptop/core-v6 0.0.66 → 0.0.67

package/README.md

@@ -1,6 +1,6 @@
 # Croptop Core
 
-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.
+`@croptop/core-v6` 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.
 
 Site: <https://croptop.eth.limo>
 
@@ -28,7 +28,7 @@ Every mint collects a 5% Croptop fee unless the target project is itself the fee
 
 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
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -36,7 +36,7 @@ Use this repo when the product is permissioned publishing on top of a Juicebox p
 | `CTDeployer` | Launches a project, configures Croptop posting rules, and can wire in omnichain sucker deployments. |
 | `CTProjectOwner` | Ownership sink that can permanently hold a project NFT while still delegating the posting permissions Croptop needs. |
 
-## Mental Model
+## Mental model
 
 There are two separate concerns here:
 
@@ -45,7 +45,7 @@ There are two separate concerns here:
 
 Many Croptop bugs are really deployment-shape bugs or posting-policy bugs, not generic 721 bugs.
 
-## Read These Files First
+## Read these files first
 
 1. `src/CTPublisher.sol`
 2. `src/CTDeployer.sol`
@@ -53,7 +53,7 @@ Many Croptop bugs are really deployment-shape bugs or posting-policy bugs, not g
 4. `test/CTPublisher.t.sol`
 5. `test/ClaimCollectionOwnership.t.sol`
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/CTPublisher.t.sol`
 2. `test/CTDeployer.t.sol`
@@ -61,14 +61,14 @@ Many Croptop bugs are really deployment-shape bugs or posting-policy bugs, not g
 4. `test/regression/FeeFallbackBlackhole.t.sol`
 5. `test/regression/DuplicateUriFeeEvasion.t.sol`
 
-## Integration Traps
+## 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 only UI concerns
 
-## Where State Lives
+## Where state lives
 
 - posting criteria and publish-side enforcement live in `CTPublisher`
 - deployment-time project wiring lives in `CTDeployer`
@@ -96,11 +96,11 @@ Useful scripts:
 - `npm run deploy:mainnets:project`
 - `npm run deploy:testnets:project`
 
-## Deployment Notes
+## Deployment notes
 
 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
+## Repository layout
 
 ```text
 src/
@@ -117,7 +117,7 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - posting criteria are only as safe as the project owner configures them
 - fee routing depends on the fee project staying correctly configured
@@ -125,7 +125,7 @@ script/
 - 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
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@croptop/core-v6",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/operations.md

@@ -1,25 +1,25 @@
 # Croptop Operations
 
-## Deployment Surface
+## Deployment surface
 
 - [`src/CTDeployer.sol`](../src/CTDeployer.sol) is the first stop for project launch shape, hook forwarding, and optional sucker integration.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) and [`script/ConfigureFeeProject.s.sol`](../script/ConfigureFeeProject.s.sol) cover the current deployment and fee-project wiring.
 - [`src/structs/`](../src/structs/) contains config types that often drift from memory.
 
-## Change Checklist
+## Change checklist
 
 - If you edit posting criteria, verify both direct publisher calls and deployer-created project flows.
 - If you edit fee behavior, check both the designated fee project path and any exemption behavior.
 - If you edit burn-lock ownership assumptions, confirm the intended irreversibility still holds.
 - If you edit data-hook forwarding, re-check sucker-related fee-free cash-out behavior.
 
-## Common Failure Modes
+## Common failure modes
 
 - Publishing bug is blamed on the publisher when the deployer packaged the project or hook incorrectly.
 - Immutable-owner expectations are missed after ownership moves into [`src/CTProjectOwner.sol`](../src/CTProjectOwner.sol).
 - Content reuse or duplicate-post behavior changes and silently alters user-facing publishing semantics.
 
-## Useful Proof Points
+## Useful proof points
 
 - [`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

@@ -1,26 +1,26 @@
 # Croptop Runtime
 
-## Contract Roles
+## Contract roles
 
 - [`src/CTPublisher.sol`](../src/CTPublisher.sol) validates posts, configures or reuses tiers, mints first copies, and routes Croptop fees.
 - [`src/CTDeployer.sol`](../src/CTDeployer.sol) packages project deployment, hook forwarding, and optional sucker support.
 - [`src/CTProjectOwner.sol`](../src/CTProjectOwner.sol) is the burn-lock ownership helper for immutable administration patterns.
 
-## Runtime Path
+## Runtime path
 
 1. A project is deployed or configured with Croptop posting rules.
 2. Publishers call into [`src/CTPublisher.sol`](../src/CTPublisher.sol) with content, supply, and pricing data.
 3. The publisher validates category-level rules, creates or reuses tiers, mints the first copy, and routes fees and proceeds.
 4. If the project uses the deployer wrapper, data-hook calls forward through [`src/CTDeployer.sol`](../src/CTDeployer.sol).
 
-## High-Risk Areas
+## High-risk areas
 
 - Posting criteria: category rules are the policy surface that protects the project from bad content or bad economics.
 - Fee routing: fee-project assumptions and fee exemptions are operationally important.
 - Tier reuse and duplicate content: content identity is part of runtime behavior, not only metadata.
 - Burn-lock ownership: once ownership moves into the lock helper, reversibility expectations change drastically.
 
-## Tests To Trust First
+## Tests to trust first
 
 - [`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.

package/src/CTDeployer.sol

@@ -48,6 +48,7 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
 
     /// @notice Thrown when a caller is not the Juicebox project owner for the hook being claimed.
     error CTDeployer_NotOwnerOfProject(uint256 projectId, address hook, address caller);
+
     //*********************************************************************//
     // ---------------------------- events -------------------------------- //
     //*********************************************************************//
@@ -83,7 +84,6 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
 
     /// @notice Each project's data hook provided on deployment.
     /// @custom:param projectId The ID of the project to get the data hook for.
-    /// @custom:param rulesetId The ID of the ruleset to get the data hook for.
     mapping(uint256 projectId => IJBRulesetDataHook) public dataHookOf;
 
     //*********************************************************************//
@@ -303,6 +303,7 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
     /// explicit non-default peer also requires `SET_SUCKER_PEER`, matching the registry's direct-call rule.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param suckerDeploymentConfiguration The suckers to set up for the project.
+    /// @return suckers The addresses of the deployed suckers.
     function deploySuckersFor(
         uint256 projectId,
         CTSuckerDeploymentConfig calldata suckerDeploymentConfiguration
@@ -414,7 +415,14 @@ contract CTDeployer is ERC2771Context, JBPermissioned, IJBRulesetDataHook, IERC7
         return SUCKER_REGISTRY.isSuckerOf({projectId: projectId, addr: addr});
     }
 
-    /// @dev Make sure only mints can be received.
+    /// @notice Accepts only freshly minted project NFTs sent directly by `JBProjects`.
+    /// @dev Rejecting transfers from a non-zero `from` ensures the deployer cannot be handed a project after launch.
+    /// @param operator Unused; the transfer is authenticated by `msg.sender` and `from`, not the operator.
+    /// @param from Unused except to gate acceptance; a non-zero prior owner means this is not a fresh mint, so it
+    /// reverts.
+    /// @param tokenId Unused; any freshly minted project NFT is accepted.
+    /// @param data Unused; no payload is expected on a project mint.
+    /// @return magicValue The `IERC721Receiver.onERC721Received` selector that signals a successful receipt.
     function onERC721Received(
         address operator,
         address from,

package/src/CTProjectOwner.sol

@@ -49,6 +49,11 @@ contract CTProjectOwner is IERC721Receiver, ICTProjectOwner {
 
     /// @notice Give the Croptop publisher permission to post to the project on this contract's behalf.
     /// @dev Configure posting criteria before transferring ownership here; this contract has no transfer-out function.
+    /// @param operator Unused; the transfer is authenticated by `msg.sender`, not the operator.
+    /// @param from Unused; any project NFT is accepted regardless of its prior owner.
+    /// @param tokenId The ID of the project NFT being received, used as the project ID the publisher is permitted on.
+    /// @param data Unused; no payload is expected on the transfer.
+    /// @return magicValue The `IERC721Receiver.onERC721Received` selector that signals a successful receipt.
     function onERC721Received(
         address operator,
         address from,

package/src/CTPublisher.sol

@@ -43,34 +43,84 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the caller's additional pay metadata already contains a pay ID, which would shadow Croptop's
+    /// tier selection.
     error CTPublisher_DuplicatePayMetadata(bytes4 payMetadataId);
+
+    /// @notice Thrown when the same encoded IPFS URI appears more than once within a single mint batch.
     error CTPublisher_DuplicatePost(bytes32 encodedIpfsUri);
+
+    /// @notice Thrown when a post is supplied without an encoded IPFS URI.
     error CTPublisher_EmptyEncodedIpfsUri(uint256 postIndex);
+
+    /// @notice Thrown when refunding a native-token fee to the caller fails.
     error CTPublisher_FeePaymentFailed(uint256 feeAmount);
+
+    /// @notice Thrown when the native token sent is less than the required price plus fee.
     error CTPublisher_InsufficientEthSent(uint256 expected, uint256 sent);
+
+    /// @notice Thrown when the ERC-20 amount supplied is less than the required price plus fee.
     error CTPublisher_InsufficientPayment(uint256 expected, uint256 sent);
+
+    /// @notice Thrown when the fee beneficiary is the zero address.
     error CTPublisher_InvalidFeeBeneficiary();
+
+    /// @notice Thrown when the terminal's accounting context does not match the payment token or has no currency.
     error CTPublisher_InvalidPaymentTokenContext(
         address token, uint256 tokenCurrency, uint256 tokenDecimals, uint256 pricingCurrency, uint256 pricingDecimals
     );
+
+    /// @notice Thrown when a configured maximum total supply is below the minimum total supply.
     error CTPublisher_MaxTotalSupplyLessThanMin(uint256 min, uint256 max);
+
+    /// @notice Thrown when the beneficiary's NFT balance did not increase by the expected mint count after payment.
     error CTPublisher_MintNotDelivered(
         address hook, address beneficiary, uint256 expectedBalance, uint256 actualBalance
     );
+
+    /// @notice Thrown when native value is sent alongside an ERC-20 payment.
     error CTPublisher_MsgValueNotAllowed(uint256 value);
+
+    /// @notice Thrown when the supplied amount does not equal `msg.value` for a native-token payment.
     error CTPublisher_NativeTokenAmountMismatch(uint256 amount, uint256 msgValue);
+
+    /// @notice Thrown when no posts are supplied to publish.
     error CTPublisher_NoPosts(address caller);
+
+    /// @notice Thrown when the caller is not in the category's allowlist.
     error CTPublisher_NotInAllowList(address addr, address[] allowedAddresses);
+
+    /// @notice Thrown when the amount exceeds the `uint160` maximum that Permit2 can transfer.
     error CTPublisher_OverflowAlert(uint256 value, uint256 limit);
+
+    /// @notice Thrown when the amount to pull exceeds the signed Permit2 allowance.
     error CTPublisher_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
+
+    /// @notice Thrown when no price feed is available to convert between the payment and pricing currencies.
     error CTPublisher_PriceFeedUnavailable(uint256 paymentCurrency, uint256 pricingCurrency);
+
+    /// @notice Thrown when a post's price is below the category's minimum price.
     error CTPublisher_PriceTooSmall(uint256 price, uint256 minimumPrice);
+
+    /// @notice Thrown when a token transfer is nested inside an in-progress balance-delta measurement.
     error CTPublisher_ReentrantTokenTransfer(address token);
+
+    /// @notice Thrown when a post's split percent exceeds the category's maximum split percent.
     error CTPublisher_SplitPercentExceedsMaximum(uint256 splitPercent, uint256 maximumSplitPercent);
+
+    /// @notice Thrown when a downstream terminal did not consume the exact-use ERC-20 allowance it was granted.
     error CTPublisher_TemporaryAllowanceNotConsumed(address token, address spender, uint256 allowance);
+
+    /// @notice Thrown when a post's total supply exceeds the category's maximum total supply.
     error CTPublisher_TotalSupplyTooBig(uint256 totalSupply, uint256 maximumTotalSupply);
+
+    /// @notice Thrown when a post's total supply is below the category's minimum total supply.
     error CTPublisher_TotalSupplyTooSmall(uint256 totalSupply, uint256 minimumTotalSupply);
+
+    /// @notice Thrown when posting to a category that has not been configured to allow posts.
     error CTPublisher_UnauthorizedToPostInCategory(address hook, uint24 category);
+
+    /// @notice Thrown when a category is configured with a zero minimum total supply.
     error CTPublisher_ZeroTotalSupply(address hook, uint24 category);
 
     //*********************************************************************//
@@ -78,7 +128,8 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     //*********************************************************************//
 
     /// @notice The divisor that describes the fee that should be taken.
-    /// @dev This is equal to 100 divided by the fee percent.
+    /// @dev A divisor of 20 yields a 5% fee. Expressing the fee as an integer divisor keeps the deduction
+    /// (`totalPrice / FEE_DIVISOR`) exact and rounds any dust in the payer's favor.
     uint256 public constant override FEE_DIVISOR = 20;
 
     //*********************************************************************//

package/src/structs/CTProjectConfig.sol

@@ -5,13 +5,15 @@ import {JBTerminalConfig} from "@bananapus/core-v6/src/structs/JBTerminalConfig.
 import {CTDeployerAllowedPost} from "../structs/CTDeployerAllowedPost.sol";
 
 /// @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 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).
+/// @custom:member terminalConfigurations The terminals that the project uses to accept payments through.
+/// @custom:member projectUri The metadata URI containing project info.
+/// @custom:member allowedPosts The posting criteria that define what kinds of NFTs can be published to each category.
+/// @custom:member contractUri A link to the 721 collection's metadata (e.g. OpenSea-compatible contract-level
+/// metadata).
+/// @custom:member name The name of the 721 collection where posts will be minted.
+/// @custom:member symbol The symbol of the 721 collection where posts will be minted.
+/// @custom:member salt A salt for deterministic deployment of the 721 hook (includes msg.sender for replay
+/// protection).
 struct CTProjectConfig {
     JBTerminalConfig[] terminalConfigurations;
     string projectUri;