@croptop/core-v6 0.0.27 → 0.0.29

package/ADMINISTRATION.md

@@ -2,6 +2,33 @@
 
 Admin privileges and their scope in croptop-core-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Croptop project deployment, posting-criteria management, publisher permissions, and project burn-lock ownership flows. |
+| Operators | Project owners, hook owners and delegates, the `CTDeployer`, `CTPublisher`, optional `CTProjectOwner`, and the configured sucker registry. |
+| Highest-risk actions | Sending a project NFT to `CTProjectOwner`, misconfiguring posting criteria, or relying on the write-once `dataHookOf` mapping without validating the hook first. |
+| Recovery posture | Ownership burn-lock mistakes are not recoverable in place. Operational fixes usually mean updating criteria if the project is still controlled, or deploying a new project/hook if it is not. |
+
+## Routine Operations
+
+- Configure posting criteria before broad publisher access, because `mintFrom()` enforces those rules for every post.
+- Use `claimCollectionOwnershipOf()` when the project should own its hook directly instead of leaving hook control with the deployer path.
+- Treat sucker deployment as a project extension that still depends on the Croptop data-hook proxy remaining correct for the project.
+- Avoid transferring project NFTs to `CTProjectOwner` unless the intention is to burn human control permanently.
+
+## One-Way Or High-Risk Actions
+
+- `CTProjectOwner` permanently locks any JBProjects NFT it receives.
+- `dataHookOf[projectId]` is set during deployment and has no later setter.
+- Constructor-time wildcard permissions granted by `CTDeployer` are structural and cannot be revoked from within the deployer.
+
+## Recovery Notes
+
+- If posting rules are wrong but the project still controls the hook, fix them through the hook-owner surface.
+- If ownership was accidentally burned into `CTProjectOwner` or the wrong hook path was deployed, recovery generally means abandoning that control path and redeploying the project or hook composition.
+
 ## Roles
 
 ### 1. Project Owner
@@ -69,7 +96,7 @@ Admin privileges and their scope in croptop-core-v6.
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|-------------|
-| `onERC721Received()` | Anyone who transfers a JBProjects NFT | None | Per-project | On receiving a project NFT from `PROJECTS` (mint only, `from == address(0)` is NOT enforced here), grants `CTPublisher` the `ADJUST_721_TIERS` permission for that project. |
+| `onERC721Received()` | Anyone who transfers a JBProjects NFT | None | Per-project | On receiving a project NFT from `PROJECTS`, grants `CTPublisher` the `ADJUST_721_TIERS` permission for that project. The contract does not restrict this to mint receipts; any transferred JBProjects NFT will be accepted and effectively burn human ownership. |
 
 ### Permissions Granted at CTDeployer Construction
 
@@ -134,7 +161,7 @@ What admins CANNOT do:
 
 4. **Project owners cannot disable Croptop posting entirely for a category.** `configurePostingCriteriaFor()` requires `minimumTotalSupply > 0`. The workaround is to set an astronomically high `minimumPrice` with `minimumTotalSupply = maximumTotalSupply = 1`. See finding NM-006.
 
-5. **Project owners cannot bypass posting criteria to mint directly through CTPublisher.** They must use `mintFrom()` like anyone else, which enforces all configured rules. However, owners can adjust tiers directly on the hook (bypassing CTPublisher) if they have `ADJUST_721_TIERS` permission.
+5. **Project owners cannot bypass posting criteria through `CTPublisher`, but they may still bypass the publisher surface entirely.** `mintFrom()` enforces all configured rules. Separately, the initial owner/operator can hold direct hook-management permissions from `CTDeployer`, which lets them adjust tiers or mint without going through `CTPublisher` until ownership is claimed away or permissions are narrowed.
 
 6. **CTPublisher cannot mint without paying.** `mintFrom()` requires `msg.value >= totalPrice + fee`. There is no free-mint path through CTPublisher.
 
@@ -142,6 +169,6 @@ What admins CANNOT do:
 
 8. **No admin can modify existing tier prices.** Once a tier is created via `_setupPosts()`, the price is set in the `JB721TiersHookStore`. CTPublisher uses the stored price for fee calculation on subsequent mints (not `post.price`). See H-19 fix.
 
-9. **No admin can drain CTPublisher funds.** CTPublisher has no `withdraw()` function and no `receive()` / `fallback()`. The only ETH that enters the contract is during `mintFrom()` and it is fully routed to the project terminal and fee terminal (or fallback recipients) within the same transaction. The fee terminal payment is wrapped in try-catch with fallback to `feeBeneficiary` then `msg.sender`, so ETH is never stranded by a fee terminal failure.
+9. **No admin can drain CTPublisher funds.** CTPublisher has no `withdraw()` function and no `receive()` / `fallback()`. The only ETH that enters the contract is during `mintFrom()` and it is fully routed to the project terminal and fee terminal (or refunded to the caller if the fee terminal reverts) within the same transaction. If that refund also fails, the mint reverts rather than trapping ETH in the publisher.
 
 10. **Sucker registry trust is irrevocable.** The `MAP_SUCKER_TOKEN` permission is granted at CTDeployer construction with `projectId: 0` (wildcard). There is no function to revoke this permission from within CTDeployer.

package/ARCHITECTURE.md

@@ -1,179 +1,71 @@
-# croptop-core-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-NFT publishing platform built on Juicebox V6. Allows permissioned posting of NFT content to Juicebox projects. CTDeployer creates projects pre-configured for content publishing, and CTPublisher manages the posting workflow with configurable rules (price floors, supply limits, category restrictions).
+`croptop-core-v6` turns a Juicebox project with a 721 tiers hook into a permissioned publishing surface. Project owners define what kinds of posts are allowed, and third parties can mint new content tiers only if their post matches those rules. A fixed fee is routed to a designated fee project on every publish.
 
-## Contract Map
+## Boundaries
 
-```
-src/
-├── CTDeployer.sol       — Deploys Croptop projects with 721 hooks and publishing rules
-├── CTPublisher.sol      — Manages permissioned NFT posting to projects
-├── CTProjectOwner.sol   — Proxy owner for Croptop-deployed projects
-├── interfaces/
-│   ├── ICTDeployer.sol
-│   ├── ICTProjectOwner.sol
-│   └── ICTPublisher.sol
-└── structs/
-    ├── CTAllowedPost.sol         — Rules for what can be posted
-    ├── CTDeployerAllowedPost.sol — Deployer-level post rules (no hook field)
-    ├── CTPost.sol                — A post submission
-    ├── CTProjectConfig.sol       — Project configuration
-    └── CTSuckerDeploymentConfig.sol — Cross-chain config
-```
-
-## Key Data Flows
-
-### Project Deployment
-
-```
-Creator → CTDeployer.deployProjectFor(owner, projectConfig, suckerConfig, controller)
-  1. Deploy 721 hook via IJB721TiersHookDeployer (empty tiers, ETH currency)
-  2. Launch JB project with:
-     → weight = 1,000,000 * 10^18
-     → cashOutTaxRate = MAX (100%)
-     → dataHook = CTDeployer itself (see "Data Hook Behavior" below)
-     → useDataHookForPay = true, useDataHookForCashOut = true
-  3. Store dataHookOf[projectId] = the 721 hook (for pay forwarding)
-  4. Configure allowed post rules on CTPublisher
-  5. Deploy suckers for cross-chain support (if configured)
-  6. Transfer project NFT to the specified owner
-  7. Grant owner permissions: ADJUST_721_TIERS, SET_721_METADATA, MINT_721, SET_721_DISCOUNT_PERCENT
-```
-
-### Content Publishing (mintFrom)
-
-```
-Publisher → CTPublisher.mintFrom(hook, posts[], nftBeneficiary, feeBeneficiary, ...)
-  → _setupPosts: for each post:
-    1. Reject empty encodedIPFSUri
-    2. Reject duplicate encodedIPFSUri within the batch
-    3. If tier already exists for this encodedIPFSUri:
-       → Use existing tier ID, add tier's price to totalPrice
-       → (Prevents fee evasion by using actual on-chain price, not user-supplied)
-    4. If tier is new:
-       → Load allowance for (hook, category) — see "Allowed Post Rules" below
-       → Validate: category enabled, price >= minimum, supply in range,
-         splitPercent <= maximum, caller in allowlist (if restricted)
-       → Create JB721TierConfig with the post's price, supply, category,
-         splitPercent, and splits array
-       → Record tierIdForEncodedIPFSUriOf mapping
-       → Add post.price to totalPrice
-  → Calculate fee: totalPrice / FEE_DIVISOR (5% fee, FEE_DIVISOR = 20)
-     Fee is skipped when projectId == FEE_PROJECT_ID
-  → adjustTiers on the 721 hook to add new tiers
-  → Pay the project terminal: payValue = msg.value - fee
-     Metadata encodes tier IDs to mint, so the 721 hook mints one NFT per post
-  → Pay pre-computed fee to FEE_PROJECT_ID terminal (try-catch; falls back to feeBeneficiary, then msg.sender)
-```
-
-### Allowed Post Rules
-
-Each category on each 721 hook has an allowance stored as bit-packed values in `_packedAllowanceFor[hook][category]`. The project owner configures these via `configurePostingCriteriaFor`.
-
-| Field | Type | Bits | Purpose |
-|-------|------|------|---------|
-| `minimumPrice` | `uint104` | 0-103 | Floor price per NFT. Posts below this revert. |
-| `minimumTotalSupply` | `uint32` | 104-135 | Minimum editions. Must be >= 1; a zero value means the category is disabled. |
-| `maximumTotalSupply` | `uint32` | 136-167 | Maximum editions. Must be >= minimumTotalSupply. |
-| `maximumSplitPercent` | `uint32` | 168-199 | Cap on the publisher's split (out of `SPLITS_TOTAL_PERCENT = 1,000,000,000`). 0 means no splits allowed. |
-| `allowedAddresses` | `address[]` | separate storage | If non-empty, only these addresses may post in this category. Empty means anyone can post. |
-
-Validation order in `_setupPosts`: category enabled (minimumTotalSupply != 0) -> price check -> supply range check -> split percent cap -> allowlist check.
+- `CTPublisher` owns publishing policy and fee routing.
+- `CTDeployer` owns one-shot project creation and optional sucker setup.
+- The underlying 721 tier implementation remains in `nana-721-hook-v6`.
+- The repo does not reimplement terminal accounting; payments still settle through Juicebox terminals.
 
-Categories cannot be fully removed after creation. This is by design -- once a category exists, removing posting would break expectations for existing posters. Projects can set restrictive allowance configurations to effectively disable new posts.
+## Main Components
 
-## Data Hook Behavior
+| Component | Responsibility |
+| --- | --- |
+| `CTPublisher` | Validates posts, creates or reuses tiers, mints the first copy, and routes publish fees |
+| `CTDeployer` | Launches a Juicebox project plus hook configuration in one transaction and can proxy hook callbacks |
+| `CTProjectOwner` | Burn-lock helper that permanently delegates tier adjustment authority to Croptop |
+| `CTAllowedPost`, `CTPost`, related structs | Encode project-level publishing policy and publish requests |
 
-CTDeployer registers itself as the ruleset's `dataHook` so it can intercept both payments and cash-outs. It acts as a transparent proxy that adds sucker-awareness:
+## Runtime Model
 
-**`beforePayRecordedWith`**: Passthrough with null check. If `dataHookOf[projectId]` is `address(0)`, returns the context weight and empty hook specifications (defaults). Otherwise, forwards the call to the stored data hook (the project's 721 hook). The 721 hook returns the weight and pay hook specifications that handle NFT minting. CTDeployer does not modify pay behavior.
+### Publishing
 
-**`beforeCashOutRecordedWith`**: Checks if the `holder` is a sucker for the project (via `SUCKER_REGISTRY.isSuckerOf`). If yes, returns `cashOutTaxRate = 0` with no hook specifications -- suckers cash out without any tax. If no, forwards to `dataHookOf[projectId]` for standard cash-out behavior.
-
-**`hasMintPermissionFor`**: Returns `true` only for addresses that are suckers for the project. This allows suckers to mint tokens on-demand during cross-chain bridging.
-
-```
-Payment path:        CTDeployer.beforePayRecordedWith → 721 hook (passthrough)
-Cash-out (sucker):   CTDeployer.beforeCashOutRecordedWith → return 0% tax
-Cash-out (normal):   CTDeployer.beforeCashOutRecordedWith → 721 hook (forward)
-Mint permission:     Only suckers get on-demand mint permission
+```text
+poster
+  -> mintFrom(hook, posts, ...)
+  -> publisher validates each post against project-defined criteria
+  -> publisher calls the 721 hook to create or reuse tiers
+  -> project terminal receives the publish payment
+  -> fee project receives the fixed fee slice, or `_msgSender()` is refunded that fee if the fee terminal rejects it
+  -> first copy of each created tier is minted to the poster
 ```
 
-## Ownership Model
-
-### Why a Proxy Owner?
-
-When CTDeployer creates a project, it initially owns the project NFT (because `launchProjectFor` mints to `msg.sender`). CTDeployer needs to be the initial owner so it can:
-1. Configure posting criteria on CTPublisher (requires `ADJUST_721_TIERS` permission from the hook's owner, which is CTDeployer).
-2. Deploy suckers (requires project ownership).
-3. Grant the final owner NFT management permissions.
-
-After setup, CTDeployer transfers the project NFT to the specified `owner`. The 721 hook's ownership stays with CTDeployer, which has granted `ADJUST_721_TIERS` permission to CTPublisher with `projectId = 0` (wildcard). This means CTPublisher can add tiers to any Croptop-deployed project without further permission grants.
-
-### CTProjectOwner: The Immutable-Rules Pattern
-
-`CTProjectOwner` is a separate contract that serves as a "lockbox" for projects that want immutable posting rules. When the project owner transfers their project NFT to a CTProjectOwner instance:
-
-1. `onERC721Received` fires and grants CTPublisher the `ADJUST_721_TIERS` permission for that project.
-2. CTProjectOwner exposes no function to reconfigure posting criteria, queue new rulesets, or transfer the project further.
-3. The posting rules become permanently frozen -- content can still be published under the existing rules, but the rules themselves cannot change.
-
-This enables a trust model: creators can prove to publishers that the rules (price floors, supply caps, split percentages) will never change, providing a credible commitment that the economic terms are permanent.
-
-### Claiming Collection Ownership
-
-`CTDeployer.claimCollectionOwnershipOf(hook)` allows the project NFT holder to take direct ownership of the 721 hook by calling `JBOwnable.transferOwnershipToProject(projectId)`. After this, the hook's owner resolves to whoever holds the project NFT. The caller must then independently grant CTPublisher the `ADJUST_721_TIERS` permission, or subsequent posts will revert.
-
-## Publisher Fee and Split Mechanics
-
-### Fee Structure
-
-CTPublisher charges a 5% fee (`FEE_DIVISOR = 20`) on the total price of all posts in a `mintFrom` call. The fee is skipped when the target project is the fee project itself (`FEE_PROJECT_ID`).
+### Project Launch
 
+```text
+creator
+  -> CTDeployer launches the project, hook, posting criteria, and optional suckers
+  -> deployer can also stand in as a ruleset data-hook wrapper when needed
 ```
-msg.value breakdown:
-  totalPrice     → paid to the project's terminal (mints NFTs + project tokens)
-  totalPrice/20  → paid to FEE_PROJECT_ID's terminal (Croptop platform fee)
-  remainder      → reverts if insufficient, excess stays as overpayment
-```
-
-### Publisher Split Mechanism
-
-When a publisher creates a new post, they can set a `splitPercent` and a `splits` array on their `CTPost`. These are stored directly on the 721 tier via `JB721TierConfig.splitPercent` and `JB721TierConfig.splits`.
-
-The split mechanics work at the 721 hook level: whenever someone mints (buys) an NFT from that tier, the 721 hook routes `splitPercent` of the tier's price to the addresses in the `splits` array. The publisher typically sets themselves as a split recipient so they earn a share of every future mint from the tier they created.
-
-The project owner controls the maximum split a publisher can claim via `maximumSplitPercent` in the allowed post rules. If `maximumSplitPercent` is 0, publishers cannot set any splits. This gives project owners control over how much revenue publishers can capture versus how much flows to the project treasury.
 
-## Design Decisions
+## Critical Invariants
 
-**Permissioned publishing over open posting.** Posts are validated against per-category allowance rules rather than allowing anyone to post anything. This prevents spam, ensures minimum economic commitment (price floors), and lets project owners curate their collection's quality by restricting who can post and at what terms.
+- A post is valid only if it satisfies the configured category, price, supply, split, and allowlist constraints.
+- Fee routing must be computed from the payment value, not transient contract balance, so forced ETH cannot distort the fee.
+- Fee routing must not strand ETH in `CTPublisher`. If the fee terminal rejects payment, the fee is refunded to `_msgSender()`; if that refund fails, the mint reverts.
+- `CTProjectOwner` only makes sense as a lock, not a flexible admin layer. Once a project is burn-locked, Croptop becomes the only intended tier-adjustment path.
+- Publishing should not bypass the 721 hook's own invariants around tier creation and minting.
 
-**Publisher gets a split, not a direct payment.** Rather than paying publishers upfront, Croptop uses the 721 hook's split mechanism. The publisher earns a percentage of every future mint from their tier. This aligns incentives: publishers profit when their content is popular enough that others want to mint copies, not just from the act of posting.
+## Where Complexity Lives
 
-**CTDeployer as data hook proxy.** Instead of requiring projects to use a custom data hook, CTDeployer inserts itself as a transparent proxy. This lets it add sucker-awareness (tax-free cross-chain cash-outs) without requiring the underlying 721 hook to know about suckers. The 721 hook handles NFT minting logic; CTDeployer handles cross-chain policy.
+- Post validation is spread across category rules, split limits, supply bounds, and optional allowlists.
+- `CTDeployer` is subtle because it is both a launch helper and, in some flows, a runtime hook proxy.
+- Fee routing is intentionally liveness-first: it prefers refunding `_msgSender()` over blocking the mint when the fee terminal is down, but still reverts if the refund itself cannot be delivered.
 
-**Immutable rules via CTProjectOwner.** Rather than building immutability into CTPublisher (which would add complexity for all projects), immutability is opt-in: transfer the project to CTProjectOwner and the rules freeze. Projects that want governance flexibility simply keep the project NFT in a wallet or multisig.
-
-**Category-based organization.** Posts are organized by `category` (uint24), with each category having independent allowance rules. This lets a single project support multiple content types (e.g., category 1 for images at 0.01 ETH, category 2 for music at 0.1 ETH) with different price floors, supply limits, and access controls.
-
-**Duplicate prevention via encodedIPFSUri mapping.** `tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]` ensures each piece of content can only create one tier. If a tier already exists, the mint uses the existing tier (at its on-chain price, not the caller-supplied price). This prevents duplicate tiers and fee evasion.
-
-## Extension Points
+## Dependencies
 
-| Point | Interface | Purpose |
-|-------|-----------|---------|
-| Data hook | `IJBRulesetDataHook` | CTDeployer proxies pay/cash-out hooks, adds sucker-awareness |
-| 721 hook | `IJB721TiersHook` | NFT tier management, split routing on mints |
-| Publisher | `ICTPublisher` | Content posting workflow and allowance configuration |
+- `nana-721-hook-v6` for tier storage and minting
+- `nana-suckers-v6` and `nana-omnichain-deployers-v6` patterns when omnichain deployment is enabled
+- `nana-core-v6` terminals, permissions, and project ownership
 
-## Dependencies
+## Safe Change Guide
 
-- `@bananapus/core-v6` -- Core protocol (terminals, rulesets, permissions, directory)
-- `@bananapus/721-hook-v6` -- NFT tier system (tiers, minting, splits)
-- `@bananapus/ownable-v6` -- JB-aware ownership (ownership-to-project transfer)
-- `@bananapus/permission-ids-v6` -- Permission constants
-- `@bananapus/suckers-v6` -- Cross-chain support (sucker registry)
-- `@openzeppelin/contracts` -- ERC2771 (meta-transactions), ERC721Receiver
+- Keep publishing policy separate from 721 implementation details. If a change is generally useful for all tiered collections, it belongs downstream.
+- When modifying fee logic, reason through terminal payment ordering and failure fallback paths together.
+- Any change to `CTDeployer` should be reviewed as both a deployer and a live hook wrapper, because it participates in runtime flows after launch.
+- Changes to burn-lock semantics should be treated as governance changes, not UI conveniences.
+- Be wary of adding product-specific tier semantics here that really belong in the generic 721 hook.