@croptop/core-v6 0.0.38 → 0.0.40

package/ARCHITECTURE.md

@@ -1,96 +0,0 @@
-# Architecture
-
-## Purpose
-
-`croptop-core-v6` turns a Juicebox project with a 721 tiers hook into a permissioned publishing market. Project owners define what posts are valid, third parties publish content by minting or reusing tiers, and Croptop routes a fixed publish fee to the canonical fee project.
-
-## System Overview
-
-`CTPublisher` is the runtime policy and fee-routing surface. `CTDeployer` is the launch wrapper that can package a project, its 721 hook config, posting rules, and optional omnichain setup in one transaction. `CTProjectOwner` is the irreversible ownership helper for projects that want Croptop-mediated administration instead of a plain owner EOA.
-
-## Core Invariants
-
-- A post can only be published if it satisfies the configured category, pricing, supply, split, and allowlist rules.
-- Publish fees must be computed from the call value, not from ambient contract balance.
-- `CTPublisher` must not trap fee funds. If fee-project payment fails, the fee is refunded to `_msgSender()`, and if that refund fails the publish reverts.
-- Tier creation and minting must still respect `nana-721-hook-v6` invariants.
-- `CTDeployer` intentionally creates a temporary owner-bypass period before collection ownership is claimed away from the deployer.
-- `CTProjectOwner` is a burn-lock primitive, not a flexible admin panel.
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `CTPublisher` | Post validation, tier reuse or creation, first-copy minting, fee routing | Main runtime contract |
-| `CTDeployer` | Project launch, hook wiring, optional sucker setup, wrapper behavior | Launch-time and runtime wrapper |
-| `CTProjectOwner` | Irreversible ownership helper | Governance-sensitive |
-| `CTAllowedPost`, `CTPost`, related structs | Publishing policy and request encoding | Shared config surface |
-
-## Trust Boundaries
-
-- Tier storage and minting semantics live in `nana-721-hook-v6`.
-- Terminal accounting and project ownership live in `nana-core-v6`.
-- When omnichain setup is enabled, this repo composes patterns from `nana-suckers-v6` and `nana-omnichain-deployers-v6`.
-
-## Critical Flows
-
-### Publish
-
-```text
-poster
-  -> calls mintFrom(...)
-  -> publisher validates each post against project policy
-  -> publisher creates or reuses 721 tiers
-  -> project terminal receives the publish payment
-  -> fee project receives the fixed fee slice, or _msgSender() is refunded if that fee payment fails
-  -> first copy of each post tier is minted to the poster
-```
-
-### Launch
-
-```text
-creator
-  -> CTDeployer launches the project and 721-hook shape
-  -> configures Croptop posting rules
-  -> optionally wires omnichain sucker deployment
-  -> may remain in the flow as a runtime wrapper when hook composition is enabled
-```
-
-## Accounting Model
-
-This repo does not define treasury accounting. Its critical economic logic is publish-fee routing and the mapping from valid post data to tier creation or reuse.
-
-`CTPublisher` also relies on duplicate-content and pricing checks to stop fee evasion through batch composition or tier reuse.
-
-## Security Model
-
-- Fee routing is liveness-first but still value-sensitive; fallback refunds must stay correct.
-- `CTDeployer` has a larger review surface than a normal deployer because it can also participate at runtime.
-- Croptop's product boundary is partly social: until collection ownership is claimed away from `CTDeployer`, the project owner can interact through the granted permissions rather than only through the publisher surface.
-- Posting-policy bugs are product-level authorization bugs, not just metadata bugs.
-
-## Safe Change Guide
-
-- Put generic tier logic in `nana-721-hook-v6`, not here.
-- If fee behavior changes, review payment ordering, fee-project fallback, and refund failure handling together.
-- If deployer ownership or permission grants change, re-check the temporary bypass window and post-claim ownership behavior together.
-- If `CTDeployer` changes, test both project launch and any wrapped hook flow it participates in.
-- Treat `CTProjectOwner` changes as governance changes.
-
-## Canonical Checks
-
-- publish-path fee routing and policy enforcement:
-  `test/CTPublisher.t.sol`
-- fee fallback and refund safety:
-  `test/audit/FeeFallbackBlackhole.t.sol`
-- duplicate-content and batch-fee-evasion resistance:
-  `test/regression/DuplicateUriFeeEvasion.t.sol`
-
-## Source Map
-
-- `src/CTPublisher.sol`
-- `src/CTDeployer.sol`
-- `src/CTProjectOwner.sol`
-- `test/CTPublisher.t.sol`
-- `test/audit/FeeFallbackBlackhole.t.sol`
-- `test/regression/DuplicateUriFeeEvasion.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,88 +0,0 @@
-# Audit Instructions
-
-Croptop is a publishing layer on top of Juicebox projects and the tiered 721 stack. Audit it as a permissions, fee-routing, and project-launch system.
-
-## Audit Objective
-
-Find issues that:
-
-- let publishers create or mint posts outside configured criteria
-- let users evade Croptop fees or route them incorrectly
-- grant fee-free or privileged cash-outs to the wrong actors
-- make tier reuse bypass stale-content, fee, or policy checks
-- leave a project in an unintended ownership or admin state
-
-## Scope
-
-In scope:
-
-- `src/CTPublisher.sol`
-- `src/CTDeployer.sol`
-- `src/CTProjectOwner.sol`
-- all interfaces in `src/interfaces/`
-- all structs in `src/structs/`
-- deployment helpers in `script/`
-
-## Start Here
-
-1. `src/CTPublisher.sol`
-2. `src/CTDeployer.sol`
-3. `src/CTProjectOwner.sol`
-
-## Security Model
-
-Croptop composes several subsystems:
-
-- `CTPublisher` enforces posting criteria, creates or adjusts tiers, and routes fees
-- `CTDeployer` launches projects and wires hooks, criteria, and ownership helpers
-- `CTProjectOwner` lets a project follow Croptop-specific admin rules instead of a fixed EOA
-
-Trust boundaries that matter:
-
-- project owners choose policy, but should not be able to bypass the policy they configured
-- fee recipients and external hooks may revert or reenter
-- sucker-based privileges must stay limited to genuine omnichain components
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Project owner | Choose policy and ownership mode | Must not bypass the active policy through helper paths |
-| `CTPublisher` | Create or reuse tiers and route fees | Must stay within configured criteria |
-| `CTDeployer` | Launch projects and wire helpers | Must not retain unexpected post-launch authority |
-| Sucker integration | Access narrow omnichain-only paths | Must be backed by authentic registry state |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| `nana-721-hook-v6` | Tier state and tier adjustments match Croptop policy checks | Posting criteria and tier-reuse safety break |
-| `nana-core-v6` | Terminal and project routing are authentic | Fee routing and publish settlement drift |
-| `nana-ownable-v6` | Ownership helper resolves the intended admin | Projects can end up misowned or stranded |
-| `nana-suckers-v6` | Registry identifies genuine omnichain actors | Fee-free or privileged paths widen incorrectly |
-
-## Critical Invariants
-
-1. Minimum price, supply bounds, split limits, category restrictions, and allowlists stay binding on every publish path.
-2. Every Croptop mint either pays the configured fee or takes the documented fallback path without underpaying Croptop.
-3. Existing tiers cannot be reused in a way that revives stale criteria or dodges fee collection.
-4. Sucker-only or fee-exempt paths cannot be reached through spoofed registry state or stale deployment wiring.
-5. Ownership handoff and burn-lock flows do not accidentally widen privileges or strand administration.
-
-## Attack Surfaces
-
-- publish and mint entrypoints
-- fee computation from user input versus onchain state
-- tier creation, adjustment, and reuse logic
-- deployer-mediated pay or cash-out data-hook behavior
-- permission grants during deployment and ownership transfer
-
-## Accepted Risks Or Behaviors
-
-- Fee routing may degrade to a fallback path rather than block publishing entirely.
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`

package/RISKS.md

@@ -1,78 +0,0 @@
-# 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.
-- 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 boundary between intentional tradeoffs and defects.
-
-## Priority risks
-
-| Priority | Risk | Why it matters | Primary controls |
-|----------|------|----------------|------------------|
-| P0 | Hook/store and terminal trust | `mintFrom` depends on hook storage and directory terminal resolution; a bad integration can misprice posts or redirect value. | Audit integration assumptions, verify hook/store pairings, and monitor terminal configuration. |
-| P1 | Tier ID race during concurrent posting | `_setupPosts` predicts future tier IDs before `adjustTiers`; concurrent writes can shift those IDs and break the batch. | Application-layer ordering, atomic reverts on mismatch, and operator awareness. |
-| P1 | Fee-path degradation without mint failure | The fee terminal is fail-open via try/catch, so publishing continues even if the fee project temporarily stops receiving revenue. | Terminal health monitoring, fallback-beneficiary handling, and explicit fee-routing checks. |
-
-## 1. Trust Assumptions
-
-- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted in both publisher and deployer for permission checks, allowlists, and payment routing.
-- **CTDeployer as permanent data-hook proxy.** `CTDeployer` sets itself as the data hook for projects it deploys. `dataHookOf[projectId]` is set once and has no setter.
-- **Sucker registry.** `CTDeployer.beforeCashOutRecordedWith` trusts `SUCKER_REGISTRY.isSuckerOf()` for 0% tax cash outs.
-- **Sucker deployment is fail-open at launch time.** Launch can continue on chains where the configured sucker deployer cascade cannot complete.
-- **CTProjectOwner as burn target.** Projects transferred to `CTProjectOwner` cannot be recovered.
-- **JBDirectory / terminal resolution.** `CTPublisher.mintFrom` trusts `DIRECTORY.primaryTerminalOf()`.
-- **721 hook store.** `_setupPosts` trusts the hook store for tier state, removal checks, and prices.
-
-## 2. Economic And Manipulation Risks
-
-- **Fee evasion via duplicate posts across hooks.** Duplicate-content checks are keyed per hook, so the same URI can be reused across different hooks.
-- **Fee calculation rounding.** Fee is `totalPrice / 20`, so integer division truncates small amounts.
-- **Fee is computed from `msg.value`.** Force-sent ETH does not affect the fee calculation.
-- **Fee terminal fallback refunds the caller.** If the fee project cannot accept the fee, Croptop refunds `_msgSender()`. Relayers or contracts that cannot receive ETH will make the mint revert.
-- **Split percent manipulation.** Posters can direct large shares of tier revenue away from the project if `maximumSplitPercent` is configured high.
-
-## 3. Access Control
-
-- **Allowlist is O(n).** `_isAllowed` linearly scans the full allowlist.
-- **Categories cannot be disabled cleanly.** Once configured, a category can only be made impractical through stricter bounds.
-- **CTDeployer grants broad permissions.** Wildcard permissions to the sucker registry and publisher apply to all projects deployed by that deployer instance.
-- **`deployProjectFor` is permissionless for new projects.** Anyone can create a project with arbitrary owners.
-- **`claimCollectionOwnershipOf` only checks current NFT ownership.** After claiming, the project owner must still grant `CTPublisher` the needed tier-adjust permission or publishing stops working.
-
-## 4. DoS Vectors
-
-- **Large batch posts.** `_setupPosts` does O(n^2) duplicate detection within a batch.
-- **External hook calls in loops.** Tier-store calls inside the post loop can revert or become gas-heavy.
-- **Terminal resolution failure.** If `DIRECTORY.primaryTerminalOf()` returns `address(0)`, payment calls revert.
-- **`adjustTiers` revert.** Hook-level tier rules can block the whole `mintFrom` call.
-
-## 5. Reentrancy Surface
-
-- **`mintFrom` external call chain.** The function calls into the hook and terminals. It currently relies on local-call state isolation rather than a `ReentrancyGuard`.
-- **Fee payment ordering.** The fee is sent after the main payment. This is safe under the current `msg.value`-based accounting model, but future mutable storage in the publisher would make the surface riskier.
-
-## 6. Integration Risks
-
-- **Null data-hook forwarding in deployer.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` return defaults when `dataHookOf` is null.
-- **No hook migration path.** `dataHookOf` is written once and never updated.
-- **Sucker support can be absent even when requested.** A launch can complete while omnichain support is still missing.
-- **Tier ID prediction.** `_setupPosts` predicts new tier IDs ahead of the actual `adjustTiers` call.
-- **CTProjectOwner accepts any project NFT.** Accidentally transferring a non-Croptop project there still grants publisher permissions.
-- **Fee payment destination.** If the fee project changes terminal behavior incompatibly, mints fall back to refund or revert.
-
-## 7. Accepted Behaviors
-
-### 7.1 O(n^2) duplicate detection is accepted
-
-Duplicate detection within a batch is quadratic, but expected real-world batch sizes are small enough that this tradeoff is acceptable.
-
-### 7.2 Tier ID prediction assumes no concurrent tier writes
-
-This is a known race. The mitigation is application-layer ordering and the fact that a bad prediction reverts the whole batch cleanly.
-
-### 7.3 Project owners can bypass the publisher path while they still have direct hook permissions
-
-`CTDeployer.deployProjectFor` intentionally grants the initial owner enough hook permissions to manage the collection directly. That is part of the trust model until ownership is moved into a narrower surface.

package/SKILLS.md

@@ -1,46 +0,0 @@
-# Croptop Core
-
-## Use This File For
-
-- Use this file when the task touches Croptop publishing, project deployment, data-hook forwarding, fee routing, or burn-locked ownership.
-- Start here, then decide whether the issue is posting-policy validation, tier reuse and content identity, deployer-packaged project shape, or burn-locked ownership.
-
-## Read This Next
-
-| 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) |
-| Runtime and operational invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
-| Publishing, metadata, and attack coverage | [`test/CTPublisher.t.sol`](./test/CTPublisher.t.sol), [`test/Test_MetadataGeneration.t.sol`](./test/Test_MetadataGeneration.t.sol), [`test/CroptopAttacks.t.sol`](./test/CroptopAttacks.t.sol) |
-| Deployment, ownership, and fork coverage | [`test/CTDeployer.t.sol`](./test/CTDeployer.t.sol), [`test/CTProjectOwner.t.sol`](./test/CTProjectOwner.t.sol), [`test/ClaimCollectionOwnership.t.sol`](./test/ClaimCollectionOwnership.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contracts | [`src/`](./src/) |
-| Types | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/) |
-| Scripts | [`script/`](./script/) |
-| Tests | [`test/`](./test/) |
-
-## Purpose
-
-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.
-
-## Reference Files
-
-- Open [`references/runtime.md`](./references/runtime.md) for publisher behavior, fee routing, data-hook forwarding, and the main invariants around posting criteria and tier reuse.
-- Open [`references/operations.md`](./references/operations.md) for deployer behavior, burn-lock implications, script breadcrumbs, and common stale assumptions.
-
-## Working Rules
-
-- Start in [`src/CTPublisher.sol`](./src/CTPublisher.sol) for posting-rule and fee behavior, but check [`src/CTDeployer.sol`](./src/CTDeployer.sol) when the bug might come from project shape or hook forwarding.
-- Treat posting criteria, fee routing, and duplicate-content handling as treasury-sensitive and product-sensitive at the same time.
-- Category policy is part of the product surface. Changes to allowlists, supply bounds, or split caps change what can be published.
-- If the task mentions project immutability or admin recovery, inspect [`src/CTProjectOwner.sol`](./src/CTProjectOwner.sol) before changing deployer or publisher code.
-- Metadata bugs can be publishing bugs, resolver-shape bugs, or duplicate-content bugs. Check all three before assuming a simple formatting issue.
-- Duplicate-post and tier-reuse behavior are runtime semantics, not convenience logic.
-- When a bug looks like generic 721 issuance, confirm it is not actually in `nana-721-hook-v6`.