@croptop/core-v6 0.0.27 → 0.0.29

package/USER_JOURNEYS.md

@@ -1,729 +1,58 @@
-# croptop-core-v6 -- User Journeys
+# User Journeys
 
-Complete user path documentation for auditors. Each journey describes the entry point, who can call, parameters, state changes, events, external calls, and edge cases.
+## Who This Repo Serves
 
----
+- project owners turning a Juicebox 721 project into a publishing marketplace
+- publishers creating or reusing NFT tiers as posts
+- operators locking project administration into Croptop-specific ownership patterns
 
-## Journey 1: Deploy a Croptop Project
+## Journey 1: Turn A Project Into A Croptop Publisher
 
-**Actor:** Project creator
-**Entry point:** `CTDeployer.deployProjectFor(address owner, CTProjectConfig calldata projectConfig, CTSuckerDeploymentConfig calldata suckerDeploymentConfiguration, IJBController controller) external returns (uint256 projectId, IJB721TiersHook hook)`
-**Who can call:** Anyone. No access control on this function.
-**Source:** `src/CTDeployer.sol` lines 244-348
+**Starting state:** a project already exists or is about to launch, and the owner wants category-level posting rules.
 
-### Parameters
+**Success:** Croptop posting criteria are installed and future posts must satisfy them.
 
-- `owner` (`address`): Final owner of the project NFT after deployment.
-- `projectConfig` (`CTProjectConfig`): Name, symbol, URIs, terminal configs, allowed posts, salt.
-- `suckerDeploymentConfiguration` (`CTSuckerDeploymentConfig`): Cross-chain sucker deployer configs + salt (set salt to `bytes32(0)` to skip).
-- `controller` (`IJBController`): The JB controller that will manage the project.
+**Flow**
+1. Configure category-level posting constraints such as price floor, supply bounds, split limits, and optional allowlists.
+2. Install or verify the 721 hook shape the project expects.
+3. Route the project through Croptop's publisher logic so future post creation is policy-checked instead of free-form tier editing.
 
-### Execution Flow
+## Journey 2: Publish Content Into An Existing Croptop Project
 
-1. **Controller validation** (line 254): Reverts if `controller.PROJECTS() != PROJECTS`.
+**Starting state:** a publisher has a post that satisfies the target project's posting rules.
 
-2. **Ruleset configuration -- phase 1** (lines 256-258):
-   - Weight: `1_000_000 * 10^18`
-   - Base currency: ETH
-   - The remaining ruleset metadata (data hook, cash-out tax rate) cannot be set yet because the hook address is not known until after deployment (step 4).
+**Success:** the post becomes a valid 721 tier and the first mint settles correctly.
 
-3. **Project ID prediction** (line 261): `projectId = PROJECTS.count() + 1`
+**Flow**
+1. The publisher calls `mintFrom(...)` or the equivalent publishing surface with the content URI and pricing data.
+2. `CTPublisher` checks the post against category rules and fee policy.
+3. It creates or reuses the underlying 721 tier, mints the first copy, and routes both project revenue and the Croptop fee. If the fee terminal is unavailable, the fee is refunded to `_msgSender()` instead.
 
-4. **Hook deployment** (lines 265-286):
-   ```
-   DEPLOYER.deployHookFor(projectId, config, salt)
-   ```
-   - Salt: `keccak256(abi.encode(projectConfig.salt, _msgSender()))`
-   - Deployed with empty tiers, ETH currency, 18 decimals
-   - All `false` flags: new tiers with reserves, votes, and owner minting are allowed; overspending is not prevented; tokens are not issued for splits
+**Failure cases that matter:** duplicate URIs, split configurations that evade fees, stale tier mappings, publisher inputs that satisfy the 721 hook but violate Croptop's stricter publishing rules, and callers that cannot receive ETH when a fee refund fallback is needed.
 
-5. **Ruleset configuration -- phase 2** (lines 288-291): Now that the hook is deployed, the remaining metadata fields are set:
-   - Cash-out tax rate: `MAX_CASH_OUT_TAX_RATE` (100%)
-   - Data hook: `address(this)` (CTDeployer)
-   - `useDataHookForPay = true`, `useDataHookForCashOut = true`
+## Journey 3: Launch A New Croptop Project End To End
 
-6. **Project launch** (lines 294-303):
-   ```
-   controller.launchProjectFor(owner: address(this), ...)
-   ```
-   - CTDeployer receives the project NFT temporarily
-   - `assert(projectId == returned ID)` -- reverts on mismatch (front-running protection)
+**Starting state:** the product wants a fresh project that already has Croptop deployment choices baked in.
 
-7. **Data hook registration** (line 306):
-   ```
-   dataHookOf[projectId] = IJBRulesetDataHook(hook)
-   ```
-   This is write-once. No setter exists.
+**Success:** one deployment flow launches the project, wires the 721 hook, and installs the initial posting rules.
 
-8. **Posting criteria** (lines 309-311): If `projectConfig.allowedPosts.length > 0`, calls internal `_configurePostingCriteriaFor()` which formats `CTDeployerAllowedPost` into `CTAllowedPost` (adding the hook address) and delegates to `PUBLISHER.configurePostingCriteriaFor()`.
+**Flow**
+1. Use `CTDeployer` with project config, posting rules, and any omnichain deployment config.
+2. The deployer launches the Juicebox project, configures the Croptop-specific owner model, and wires in publisher behavior.
+3. The project is ready for publishers without a manual post-launch setup phase.
 
-9. **Sucker deployment** (lines 317-324): If `suckerDeploymentConfiguration.salt != bytes32(0)`:
-   ```
-   SUCKER_REGISTRY.deploySuckersFor(projectId, salt, configurations)
-   ```
+## Journey 4: Lock Administration Into Croptop's Owner Surface
 
-10. **Ownership transfer** (line 327):
-    ```
-    PROJECTS.transferFrom(address(this), owner, projectId)
-    ```
+**Starting state:** the project should continue operating through Croptop's policy surface instead of ordinary project-owner discretion.
 
-11. **Permission grants** (lines 329-347): Grants `owner` four permissions from CTDeployer's account:
-    - `ADJUST_721_TIERS`
-    - `SET_721_METADATA`
-    - `MINT_721`
-    - `SET_721_DISCOUNT_PERCENT`
+**Success:** the project's admin path is burn-locked or otherwise routed through `CTProjectOwner`.
 
-### Constructor (One-Time Setup)
+**Flow**
+1. Transfer or configure ownership so Croptop's owner helper controls the relevant admin surface.
+2. Restrict future edits to the paths Croptop intentionally exposes.
+3. Accept that this is a product-shaping choice, not a cosmetic deployment detail.
 
-The CTDeployer constructor (lines 82-118) grants two wildcard (`projectId = 0`) permissions from CTDeployer's account. These are set once at contract deployment, not on every `deployProjectFor` call:
+## Hand-Offs
 
-1. `JBPermissions` -- sucker registry granted `MAP_SUCKER_TOKEN` (wildcard, all projects).
-2. `JBPermissions` -- CTPublisher granted `ADJUST_721_TIERS` (wildcard, all projects).
-
-These wildcard permissions allow the sucker registry and publisher to act on behalf of CTDeployer for any project it deploys, without needing per-project permission grants.
-
-### State Changes (Per Call)
-
-1. `CTDeployer.dataHookOf[projectId]` -- set to the deployed hook address (permanent, write-once).
-2. `JBProjects` (ERC-721) -- new token minted, transferred from CTDeployer to `owner`.
-3. `JBPermissions` -- 4 permission entries set for `owner` from CTDeployer's account (`ADJUST_721_TIERS`, `SET_721_METADATA`, `MINT_721`, `SET_721_DISCOUNT_PERCENT`), scoped to the new `projectId`.
-4. `CTPublisher._packedAllowanceFor[hook][category]` -- set for each allowed post category (if any).
-5. `CTPublisher._allowedAddresses[hook][category]` -- set for each allowed post category with allowlists (if any).
-
-### Events
-
-- `ConfigurePostingCriteria(hook, allowedPost, caller)` -- emitted by CTPublisher for each allowed post entry (only if `projectConfig.allowedPosts` is non-empty). See Journey 3 for the full event signature.
-- No events are emitted directly by CTDeployer itself. External calls to `controller.launchProjectFor()`, `DEPLOYER.deployHookFor()`, `PROJECTS.transferFrom()`, and `PERMISSIONS.setPermissionsFor()` emit their own events from those contracts.
-
-### Edge Cases
-
-- **Front-running:** If another project is created between `PROJECTS.count()` and `launchProjectFor()`, the `assert` fails and the transaction reverts. No funds are lost.
-- **`owner = address(0)`:** The project NFT transfer to `address(0)` would revert (ERC-721 constraint). The deployment fails.
-- **`owner` is a contract without `onERC721Received`:** The `transferFrom` (not `safeTransferFrom`) succeeds even if the owner cannot handle ERC-721s. The project NFT could become stuck.
-- **Sucker deployment failure:** If `deploySuckersFor` reverts, the entire deployment reverts. The sucker deployer uses a try-catch cascade internally, but registry-level reverts propagate.
-- **Empty `terminalConfigurations`:** The project launches with no terminals. Payments and cash-outs are not possible until terminals are added separately.
-- **Salt collision:** If `keccak256(abi.encode(salt, _msgSender()))` collides with a previously deployed hook, `DEPLOYER.deployHookFor()` reverts (Create2 collision).
-
----
-
-## Journey 2: Post Content (Mint NFTs)
-
-**Actor:** Content poster (any address, or allowlisted address)
-**Entry point:** `CTPublisher.mintFrom(IJB721TiersHook hook, CTPost[] calldata posts, address nftBeneficiary, address feeBeneficiary, bytes calldata additionalPayMetadata, bytes calldata feeMetadata) external payable`
-**Who can call:** Anyone, subject to per-category allowlist restrictions. If a category has a non-empty `allowedAddresses` list, only those addresses may post in that category. Checked via `_isAllowed(_msgSender(), addresses)`.
-**Source:** `src/CTPublisher.sol` lines 310-430
-**Value:** Must send `msg.value >= sum(tier prices) + 5% fee`
-
-### Parameters
-
-- `hook` (`IJB721TiersHook`): The 721 hook to post to.
-- `posts` (`CTPost[]`): Array of posts (URI, supply, price, category, splits).
-- `nftBeneficiary` (`address`): Receives the minted NFTs.
-- `feeBeneficiary` (`address`): Receives fee project tokens.
-- `additionalPayMetadata` (`bytes`): Extra metadata appended to the payment.
-- `feeMetadata` (`bytes`): Metadata sent with the fee payment.
-
-### Execution Flow
-
-**Phase 1: Validation and setup** (`_setupPosts`, lines 442-589)
-
-For each post in the batch:
-
-1. **URI check:** `encodedIPFSUri != bytes32("")` or revert `CTPublisher_EmptyEncodedIPFSUri`
-2. **Duplicate check:** O(i) scan against all prior posts. Revert `CTPublisher_DuplicatePost` on match.
-3. **Existing tier lookup:** Check `tierIdForEncodedIPFSUriOf[hook][encodedIPFSUri]`
-   - **Tier exists and live:** Reuse tier ID. Accumulate `store.tierOf().price`.
-   - **Tier exists but removed:** Delete mapping. Fall through to new tier.
-   - **No tier:** Validate against category allowance, create `JB721TierConfig`.
-
-**Phase 2: Fee calculation** (lines 336-354)
-
-```
-payValue = msg.value
-
-if (projectId != FEE_PROJECT_ID) {
-    fee = totalPrice / FEE_DIVISOR       (integer division, 5%)
-    require(payValue >= fee)             (reverts CTPublisher_InsufficientEthSent if not)
-    payValue -= fee                      (fee portion held in contract balance)
-}
-
-require(totalPrice <= payValue)          (reverts CTPublisher_InsufficientEthSent if not)
-```
-
-When `projectId == FEE_PROJECT_ID`, no fee is deducted; `payValue` remains `msg.value` and the full amount goes to the project payment. Any remaining `address(this).balance` after the project payment (which would be 0 in this case) is skipped in Phase 6.
-
-**Phase 3: Tier creation** (line 358)
-
-```
-hook.adjustTiers(tiersToAdd, [])
-```
-
-**Phase 4: Metadata construction** (lines 361-377)
-
-Build JBMetadataResolver-compatible metadata with tier IDs and referral ID.
-
-**Phase 5: Project payment** (lines 398-406)
-
-```
-projectTerminal.pay{value: payValue}(projectId, NATIVE_TOKEN, payValue, nftBeneficiary, 0, "Minted from Croptop", mintMetadata)
-```
-
-**Phase 6: Fee payment** (lines 409-438)
-
-```
-payValue = msg.value - payValue   // reuse payValue for pre-computed fee amount
-
-if (payValue != 0) {
-    feeTerminal = DIRECTORY.primaryTerminalOf(FEE_PROJECT_ID, NATIVE_TOKEN)
-    try feeTerminal.pay{value: payValue}(FEE_PROJECT_ID, ...) {}
-    catch {
-        // Fallback: send fee to feeBeneficiary, then msg.sender
-        feeBeneficiary.call{value: payValue}("")
-        // If that fails too, msg.sender.call{value: payValue}("")
-    }
-}
-```
-
-### State Changes
-
-1. `CTPublisher.tierIdForEncodedIPFSUriOf[hook][uri]` -- set for each new tier created.
-2. `CTPublisher.tierIdForEncodedIPFSUriOf[hook][uri]` -- deleted if stale mapping detected (removed tier).
-3. `JB721TiersHookStore` (external) -- new tiers added via `adjustTiers`.
-4. Project terminal (external) -- balance increased by `payValue`.
-5. Fee project terminal (external) -- balance increased by fee amount.
-
-### Events
-
-- `Mint(projectId, hook, nftBeneficiary, feeBeneficiary, posts, postValue, txValue, caller)` -- emitted at line 380 after setup is complete, before the project payment. Full signature:
-  ```solidity
-  event Mint(
-      uint256 indexed projectId,
-      IJB721TiersHook indexed hook,
-      address indexed nftBeneficiary,
-      address feeBeneficiary,
-      CTPost[] posts,
-      uint256 postValue,
-      uint256 txValue,
-      address caller
-  );
-  ```
-
-### Edge Cases
-
-- **Empty posts array:** `_setupPosts` returns with `totalPrice = 0`, `tiersToAdd` and `tierIdsToMint` both empty. `adjustTiers` is called with an empty array (no-op). The project terminal receives `msg.value` (no fee deducted since `totalPrice / 20 = 0`). The fee terminal receives nothing.
-- **All posts reuse existing tiers:** No new tiers are created. `tiersToAdd` is resized to length 0 via assembly. `adjustTiers` is a no-op. Fees are calculated from on-chain tier prices.
-- **Mixed new and existing tiers:** `tiersToAdd` is resized via assembly to contain only new tiers. `tierIdsToMint` contains a mix of new and existing IDs.
-- **`msg.value` exceeds required amount:** Excess ETH goes to the fee project via the pre-computed fee (`msg.value - payValue`). The poster overpays the fee project.
-- **`msg.value` is exactly right:** The pre-computed fee amount equals the expected fee. Fee project receives the correct amount.
-- **`projectId == FEE_PROJECT_ID`:** No fee is deducted. Full `msg.value` goes to the project terminal. The pre-computed fee is 0 (no fee payment occurs).
-- **Tier price is 0:** Posting criteria allow `minimumPrice = 0`. A post with `price = 0` creates a free tier. Fee on a free tier is 0. The poster sends 0 ETH (or only ETH for other posts in the batch).
-- **`nftBeneficiary = address(0)`:** The terminal payment may succeed (depending on terminal implementation), but the NFTs would be minted to `address(0)`, effectively burning them.
-- **`hook.adjustTiers()` reverts:** The entire transaction reverts. No state changes are committed. The poster's ETH is returned.
-- **Terminal payment reverts:** The entire transaction reverts. The `adjustTiers` state change is also rolled back.
-- **Fee terminal payment reverts:** This occurs after the project payment has already succeeded. If the fee terminal reverts, the entire transaction reverts, undoing the project payment too.
-- **Batch with posts in different categories:** Each post is validated against its own category's allowance independently. A batch can contain posts in multiple categories.
-- **Re-posting a removed tier's URI:** The stale mapping is cleared and a new tier is created. The new tier may have different price/supply/splits than the original.
-
----
-
-## Journey 3: Configure Posting Criteria (Allowlist Setup)
-
-**Actor:** Hook owner (or permissioned delegate)
-**Entry point:** `CTPublisher.configurePostingCriteriaFor(CTAllowedPost[] memory allowedPosts) external`
-**Who can call:** The hook's owner (as returned by `JBOwnable(hook).owner()`) or any address that has been granted the `ADJUST_721_TIERS` permission for the hook's `PROJECT_ID()` from that owner. Checked per-entry via `_requirePermissionFrom(account: JBOwnable(hook).owner(), projectId: hook.PROJECT_ID(), permissionId: JBPermissionIds.ADJUST_721_TIERS)`.
-**Source:** `src/CTPublisher.sol` lines 243-298
-
-### Parameters
-
-- `allowedPosts` (`CTAllowedPost[]`): Array of per-category posting rules.
-
-Each `CTAllowedPost` contains:
-
-| Field | Type | Constraints |
-|-------|------|-------------|
-| `hook` | `address` | Must be a JBOwnable + IJB721TiersHook |
-| `category` | `uint24` | 0 to 16,777,215 |
-| `minimumPrice` | `uint104` | Must fit in 104 bits |
-| `minimumTotalSupply` | `uint32` | Must be > 0 |
-| `maximumTotalSupply` | `uint32` | Must be >= `minimumTotalSupply` |
-| `maximumSplitPercent` | `uint32` | 0 = splits disabled, up to `SPLITS_TOTAL_PERCENT` (1,000,000,000) |
-| `allowedAddresses` | `address[]` | Empty = permissionless, non-empty = restricted |
-
-### Execution Flow
-
-For each `CTAllowedPost` in the array:
-
-1. **Emit event** (line 252): `ConfigurePostingCriteria(hook, allowedPost, caller)`
-
-2. **Permission check** (lines 256-260):
-   ```
-   _requirePermissionFrom(
-       account: JBOwnable(hook).owner(),
-       projectId: IJB721TiersHook(hook).PROJECT_ID(),
-       permissionId: JBPermissionIds.ADJUST_721_TIERS
-   )
-   ```
-
-3. **Validation:**
-   - `minimumTotalSupply > 0` or revert `CTPublisher_ZeroTotalSupply` (line 263)
-   - `minimumTotalSupply <= maximumTotalSupply` or revert `CTPublisher_MaxTotalSupplyLessThanMin` (line 268)
-
-4. **Pack and store** (lines 274-284):
-   ```
-   packed = minimumPrice | (minimumTotalSupply << 104) | (maximumTotalSupply << 136) | (maximumSplitPercent << 168)
-   _packedAllowanceFor[hook][category] = packed
-   ```
-
-5. **Allowlist storage** (lines 287-296):
-   ```
-   delete _allowedAddresses[hook][category]
-   for each address in allowedAddresses:
-       _allowedAddresses[hook][category].push(address)
-   ```
-
-### State Changes
-
-1. `CTPublisher._packedAllowanceFor[hook][category]` -- overwritten with new packed values.
-2. `CTPublisher._allowedAddresses[hook][category]` -- deleted and repopulated.
-
-### Events
-
-- `ConfigurePostingCriteria(address indexed hook, CTAllowedPost allowedPost, address caller)` -- emitted once per entry in the `allowedPosts` array (line 252), **before** the permission check. Full signature:
-  ```solidity
-  event ConfigurePostingCriteria(address indexed hook, CTAllowedPost allowedPost, address caller);
-  ```
-  Note: the event is emitted before `_requirePermissionFrom`, so an unauthorized call will emit the event then revert, rolling back the event emission.
-
-### Edge Cases
-
-- **Overwriting existing criteria:** The entire packed value and allowlist are replaced. There is no merge or append behavior.
-- **Multiple categories in one call:** Each `CTAllowedPost` can target a different hook/category pair. A single call can configure multiple categories across multiple hooks (provided the caller has permission for each).
-- **Same category twice in one call:** The second entry overwrites the first. No duplicate check on the input array.
-- **`maximumSplitPercent = 0`:** Splits are disabled. Any post with `splitPercent > 0` will revert with `CTPublisher_SplitPercentExceedsMaximum`.
-- **`maximumTotalSupply = type(uint32).max`:** Effectively unlimited supply (4,294,967,295).
-- **Large allowlist:** Stored via a push loop. A 1,000-address allowlist costs approximately 20M gas for the SSTORE operations. A 10,000-address list is infeasible in a single transaction.
-- **Empty allowlist after previously non-empty:** `delete _allowedAddresses[hook][category]` clears the array. Posting becomes permissionless for that category.
-- **Cannot disable category:** There is no way to set `minimumTotalSupply = 0` (it reverts). To effectively disable a category, set `minimumPrice = type(uint104).max` and `minimumTotalSupply = maximumTotalSupply = 1`. This makes posting economically infeasible.
-- **Permission check uses `hook.owner()`:** If hook ownership has been transferred (e.g., to the project via `claimCollectionOwnershipOf`), the new owner (or their delegate) must call this function.
-- **ERC2771 context:** `_msgSender()` is used for the permission check. If a trusted forwarder relays the call, the original sender (appended to calldata) is checked against permissions.
-
----
-
-## Journey 4: Collect Posting Fees
-
-**Actor:** Passive (fee project). Fees are collected automatically during `mintFrom()`.
-**Entry point:** Triggered within `CTPublisher.mintFrom()` at lines 413-429
-**Who can call:** N/A -- this is an internal sub-flow of Journey 2, not independently callable.
-**Beneficiary:** The project with ID `FEE_PROJECT_ID` (immutable, set at construction)
-
-### Fee Calculation
-
-```
-totalPrice = sum of all post prices in the batch
-    (on-chain tier price for existing tiers, post.price for new tiers)
-
-payValue = msg.value
-
-if (projectId != FEE_PROJECT_ID) {
-    fee = totalPrice / FEE_DIVISOR   (FEE_DIVISOR = 20, so fee = 5%)
-    require(payValue >= fee)         (reverts if msg.value < fee)
-    payValue -= fee                  (fee held in contract balance for later routing)
-}
-
-require(totalPrice <= payValue)      (reverts if insufficient ETH for the posts)
-```
-
-When `projectId == FEE_PROJECT_ID`, the fee calculation is skipped entirely. The full `msg.value` is sent as `payValue` to the project terminal. After that payment, `address(this).balance` is 0, so the fee routing step (below) is a no-op.
-
-### Fee Routing
-
-After the project payment completes, the fee amount is pre-computed as `msg.value - payValue`:
-
-```solidity
-payValue = msg.value - payValue;  // reuse payValue for the pre-computed fee amount
-
-if (payValue != 0) {
-    IJBTerminal feeTerminal = DIRECTORY.primaryTerminalOf(FEE_PROJECT_ID, NATIVE_TOKEN);
-    try feeTerminal.pay{value: payValue}({
-        projectId: FEE_PROJECT_ID,
-        amount: payValue,
-        token: NATIVE_TOKEN,
-        beneficiary: feeBeneficiary,
-        minReturnedTokens: 0,
-        memo: "",
-        metadata: feeMetadata
-    }) {}
-    catch {
-        // Fallback: send fee to feeBeneficiary, then msg.sender if that fails too.
-        (bool success,) = feeBeneficiary.call{value: payValue}("");
-        if (!success) {
-            (success,) = msg.sender.call{value: payValue}("");
-        }
-    }
-}
-```
-
-### Fee Project Token Distribution
-
-The `feeBeneficiary` parameter in `mintFrom()` determines who receives the fee project's tokens minted from the fee payment. The `feeMetadata` parameter allows the caller to pass arbitrary metadata to the fee payment (e.g., for data hooks on the fee project).
-
-### Fee Accounting Details
-
-| Scenario | Fee Behavior |
-|----------|-------------|
-| Normal mint (1 post, 1 ETH price) | `fee = 1 ether / 20 = 0.05 ether`. Poster sends >= 1.05 ETH. |
-| Batch mint (3 posts, 1 ETH each) | `fee = 3 ether / 20 = 0.15 ether`. Poster sends >= 3.15 ETH. |
-| Existing tier reuse (1 ETH on-chain price) | Fee uses on-chain price, not `post.price`. `fee = 1 ether / 20`. |
-| Free tier (price = 0) | `fee = 0 / 20 = 0`. No fee payment occurs. |
-| `projectId == FEE_PROJECT_ID` | Fee deduction skipped entirely. Full `msg.value` goes to project. |
-| `msg.value` exceeds requirement | Excess goes to fee project. Poster overpays. |
-| Dust from integer division | Up to 19 wei lost per tx. Fee project receives slightly less. |
-
-### Events
-
-- No events are emitted by the fee sub-flow itself. The `Mint` event (see Journey 2) is emitted before the fee payment. The fee terminal's `pay()` call emits its own events from the terminal contract.
-
-### Edge Cases
-
-- **Fee project has no primary terminal:** `DIRECTORY.primaryTerminalOf()` returns `address(0)`. The `pay()` call to address(0) reverts inside the try-catch. The fee falls back to `feeBeneficiary.call{value}`, then `msg.sender.call{value}`. The main project payment is not affected.
-- **Fee terminal reverts:** 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`. The main project payment is never rolled back due to a fee terminal failure. The fee project loses revenue during the outage.
-- **Pre-computed fee is 0:** This happens when `fee == 0` (e.g., `totalPrice < FEE_DIVISOR` or `projectId == FEE_PROJECT_ID`). The fee payment is skipped entirely.
-- **Force-sent ETH (via `selfdestruct`):** The fee amount is now pre-computed as `msg.value - payValue` rather than using `address(this).balance`. Force-sent ETH does not affect fee calculation or routing. CTPublisher has no `receive()` or `fallback()`, so normal sends revert. Only `selfdestruct` (deprecated post-Dencun) can force-send ETH, and it remains in the contract.
-
----
-
-## Journey 5: Deploy a Croptop Project via CTDeployer with Posting Criteria
-
-**Actor:** Project creator
-**Entry point:** `CTDeployer.deployProjectFor(address owner, CTProjectConfig calldata projectConfig, CTSuckerDeploymentConfig calldata suckerDeploymentConfiguration, IJBController controller) external returns (uint256 projectId, IJB721TiersHook hook)` with non-empty `projectConfig.allowedPosts`
-**Who can call:** Anyone. No access control on this function. Same as Journey 1.
-**Source:** `src/CTDeployer.sol` lines 244-348, internal `_configurePostingCriteriaFor()` at lines 382-411
-
-This is an extension of Journey 1 that details the posting criteria configuration during deployment.
-
-### Posting Criteria Flow
-
-1. CTDeployer receives `CTDeployerAllowedPost[]` (which omits the `hook` field, since the hook hasn't been deployed yet).
-2. After the hook is deployed, `_configurePostingCriteriaFor()` converts each `CTDeployerAllowedPost` to a `CTAllowedPost` by injecting `hook: address(hook)` (lines 398-406).
-3. Calls `PUBLISHER.configurePostingCriteriaFor(formattedAllowedPosts)` (line 410).
-4. The publisher validates each entry (supply bounds, permissions) and stores the packed allowances and allowlists.
-
-### Permission Flow
-
-The `PUBLISHER.configurePostingCriteriaFor()` call checks `ADJUST_721_TIERS` permission from `JBOwnable(hook).owner()`. At this point in the deployment:
-
-- The hook was deployed by `DEPLOYER.deployHookFor()` on behalf of CTDeployer
-- Hook ownership is set to CTDeployer (the deployer is the effective owner after deployment)
-- The permission check passes because CTDeployer is both the caller and the hook owner (or has wildcard permission)
-
-After the deployment completes and ownership is transferred to `owner`, only the new owner (or their delegate) can reconfigure posting criteria.
-
-### State Changes
-
-1. `CTPublisher._packedAllowanceFor[hook][category]` -- set for each allowed post category.
-2. `CTPublisher._allowedAddresses[hook][category]` -- set for each allowed post category with allowlists.
-
-### Events
-
-- `ConfigurePostingCriteria(address indexed hook, CTAllowedPost allowedPost, address caller)` -- emitted by CTPublisher once per `allowedPosts` entry. The `caller` is CTDeployer's address (since CTDeployer calls the publisher). The `hook` is the newly deployed hook address.
-
-### Edge Cases
-
-- **Empty `allowedPosts`:** The `_configurePostingCriteriaFor()` call is skipped (line 309 condition). The project has no posting categories configured. Content cannot be posted until the owner configures criteria manually.
-- **Invalid criteria in deployment:** If any `CTDeployerAllowedPost` has `minimumTotalSupply == 0` or `minimumTotalSupply > maximumTotalSupply`, the publisher reverts, and the entire deployment fails.
-
----
-
-## Journey 6: Lock Project Ownership (Burn-Lock)
-
-**Actor:** Project owner
-**Entry point:** `IERC721(PROJECTS).safeTransferFrom(address from, address to, uint256 tokenId)` where `to = address(ctProjectOwner)`
-**Who can call:** The current owner of the project NFT, or an approved operator. The `safeTransferFrom` is an ERC-721 function with standard ownership/approval checks. CTProjectOwner itself has no caller restrictions in `onERC721Received` beyond requiring `msg.sender == address(PROJECTS)`.
-**Source:** `src/CTProjectOwner.sol` lines 50-83
-
-### Parameters
-
-- `from` (`address`): Current holder of the project NFT (not checked by CTProjectOwner, unlike CTDeployer).
-- `to` (`address`): Must be `address(ctProjectOwner)`.
-- `tokenId` (`uint256`): The project ID to lock.
-
-### Execution Flow
-
-1. The project owner calls `safeTransferFrom` on the JBProjects ERC-721 contract, transferring their project NFT to the CTProjectOwner contract.
-2. The ERC-721 contract calls `CTProjectOwner.onERC721Received()`.
-3. **Validation** (line 65): `msg.sender == address(PROJECTS)` -- only accepts tokens from the JBProjects contract. Reverts with empty revert on failure.
-4. **Permission grant** (lines 68-80):
-   ```
-   PERMISSIONS.setPermissionsFor(
-       account: address(this),
-       permissionsData: JBPermissionsData({
-           operator: address(PUBLISHER),
-           projectId: uint64(tokenId),
-           permissionIds: [ADJUST_721_TIERS]
-       })
-   )
-   ```
-5. Returns `IERC721Receiver.onERC721Received.selector`.
-
-### State Changes
-
-1. `JBProjects` (ERC-721) -- token transferred from owner to CTProjectOwner.
-2. `JBPermissions` -- CTPublisher granted `ADJUST_721_TIERS` for this project from CTProjectOwner's account.
-
-### Events
-
-- No events are emitted directly by CTProjectOwner. The ERC-721 `Transfer(from, to, tokenId)` event is emitted by JBProjects. The `JBPermissions.setPermissionsFor()` call emits its own event from the permissions contract.
-
-### Consequences
-
-- The project NFT is now held by CTProjectOwner. Since CTProjectOwner has no transfer function, ownership is effectively burned.
-- CTPublisher can still adjust tiers (post content) because it has `ADJUST_721_TIERS` permission.
-- The project owner can no longer change rulesets, add terminals, or perform any owner-only operations.
-- This is irreversible. There is no recovery mechanism.
-
-### Edge Cases
-
-- **`from != address(0)`:** Unlike CTDeployer, CTProjectOwner does NOT check `from != address(0)`. It accepts both mints and transfers. Any project holder can transfer their project to CTProjectOwner.
-- **`tokenId` truncation:** The `uint64(tokenId)` cast truncates if `tokenId > type(uint64).max`. For realistic sequential project IDs, this is not a concern.
-- **Transfer vs. `safeTransferFrom`:** Only `safeTransferFrom` triggers `onERC721Received`. A raw `transferFrom` would transfer the NFT without granting the publisher permission, leaving the project locked without posting capability.
-- **Double transfer:** If two different project NFTs are transferred to CTProjectOwner, each gets its own scoped permission. The contract can hold multiple projects simultaneously.
-- **Accidental transfer:** There is no confirmation, cooling period, or undo. A user who accidentally sends their project NFT to CTProjectOwner loses ownership permanently.
-
----
-
-## Journey 7: Claim Hook Collection Ownership
-
-**Actor:** Project owner
-**Entry point:** `CTDeployer.claimCollectionOwnershipOf(IJB721TiersHook hook) external`
-**Who can call:** Only the current owner of the project NFT (`PROJECTS.ownerOf(hook.PROJECT_ID())`). Checked via `PROJECTS.ownerOf(projectId) != _msgSender()` -- reverts with `CTDeployer_NotOwnerOfProject(projectId, address(hook), _msgSender())` on failure.
-**Source:** `src/CTDeployer.sol` lines 224-235
-
-### Parameters
-
-- `hook` (`IJB721TiersHook`): The 721 hook to claim ownership of.
-
-### Execution Flow
-
-1. **Read project ID** (line 226): `projectId = hook.PROJECT_ID()`
-2. **Owner check** (lines 229-231): `PROJECTS.ownerOf(projectId) == _msgSender()` or revert `CTDeployer_NotOwnerOfProject(projectId, address(hook), _msgSender())`
-3. **Transfer ownership** (line 234):
-   ```
-   JBOwnable(address(hook)).transferOwnershipToProject(projectId)
-   ```
-
-### State Changes
-
-1. Hook's `JBOwnable` storage -- owner changed from CTDeployer to the project (ownership tied to project NFT holder via `PROJECTS.ownerOf(projectId)`).
-
-### Events
-
-- No events are emitted directly by CTDeployer. The `JBOwnable.transferOwnershipToProject()` call emits its own ownership transfer event from the hook contract.
-
-### Consequences
-
-After claiming, the hook's ownership follows the project NFT. Whoever owns the project NFT can call owner-only functions on the hook (tier adjustments, metadata changes, etc.) directly, without going through CTDeployer.
-
-**Important:** After claiming, the project owner must grant CTPublisher the `ADJUST_721_TIERS` permission for the project so that `mintFrom()` continues to work. Without this permission grant, all subsequent posts will revert.
-
-### Edge Cases
-
-- **Already claimed:** If hook ownership has already been transferred, `transferOwnershipToProject` may revert (depending on JBOwnable implementation). CTDeployer is no longer the owner.
-- **Project transferred after deployment:** If the project was sold or transferred, the new owner can claim the hook. The original deployer cannot.
-- **Hook not deployed by CTDeployer:** If the `hook` was deployed independently, `JBOwnable(hook).transferOwnershipToProject()` will revert because CTDeployer is not the owner.
-
----
-
-## Journey 8: Deploy Suckers for Existing Project
-
-**Actor:** Project owner (or permissioned delegate)
-**Entry point:** `CTDeployer.deploySuckersFor(uint256 projectId, CTSuckerDeploymentConfig calldata suckerDeploymentConfiguration) external returns (address[] memory suckers)`
-**Who can call:** The project owner (`PROJECTS.ownerOf(projectId)`) or any address that has been granted the `DEPLOY_SUCKERS` permission for that project. Checked via `_requirePermissionFrom(account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.DEPLOY_SUCKERS)`.
-**Source:** `src/CTDeployer.sol` lines 354-373
-
-### Parameters
-
-- `projectId` (`uint256`): The project to deploy suckers for.
-- `suckerDeploymentConfiguration` (`CTSuckerDeploymentConfig`): Deployer configs + salt.
-
-### Execution Flow
-
-1. **Permission check** (lines 362-364):
-   ```
-   _requirePermissionFrom(
-       account: PROJECTS.ownerOf(projectId),
-       projectId: projectId,
-       permissionId: JBPermissionIds.DEPLOY_SUCKERS
-   )
-   ```
-
-2. **Sucker deployment** (lines 368-372):
-   ```
-   suckers = SUCKER_REGISTRY.deploySuckersFor(
-       projectId,
-       keccak256(abi.encode(suckerDeploymentConfiguration.salt, _msgSender())),
-       suckerDeploymentConfiguration.deployerConfigurations
-   )
-   ```
-
-### State Changes
-
-1. Sucker Registry -- new suckers registered for the project.
-2. Deployed sucker contracts -- new contracts deployed via Create2.
-
-### Events
-
-- No events are emitted directly by CTDeployer. The `SUCKER_REGISTRY.deploySuckersFor()` call emits its own events from the registry contract.
-
-### Edge Cases
-
-- **Permission not granted:** Reverts. The project owner must explicitly grant `DEPLOY_SUCKERS` to the caller, or the caller must be the project owner.
-- **Salt collision:** If the computed salt matches a previously deployed sucker, the Create2 deployment reverts.
-- **Empty `deployerConfigurations`:** The sucker registry call succeeds with zero suckers deployed.
-
----
-
-## Journey 9: Data Hook Interception (Pay)
-
-**Actor:** Anyone paying a Croptop-deployed project
-**Entry point:** `CTDeployer.beforePayRecordedWith(JBBeforePayRecordedContext calldata context) external view returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)`
-**Who can call:** Intended to be called by JBMultiTerminal during the `pay()` flow. No explicit access control -- any address can call this function, but it is only meaningful when called by the terminal as part of a payment.
-**Source:** `src/CTDeployer.sol` lines 160-169
-
-### Parameters
-
-- `context` (`JBBeforePayRecordedContext`): Standard Juicebox payment context containing `projectId`, payer details, amount, and metadata.
-
-### Execution Flow
-
-1. JBMultiTerminal calls `CTDeployer.beforePayRecordedWith(context)` because CTDeployer is registered as the project's data hook.
-2. CTDeployer forwards the call directly to `dataHookOf[context.projectId]` (line 168), which is the JB721TiersHook.
-3. The hook returns `(weight, hookSpecifications)` which determine token issuance and pay hook routing.
-
-### State Changes
-
-- None. This is a `view` function.
-
-### Events
-
-- None. This is a `view` function.
-
-### Edge Cases
-
-- **`dataHookOf[projectId]` is `address(0)`:** If a project was somehow created without setting the data hook (not possible via normal deployment flow), the forwarding call reverts on the zero address.
-- **Hook reverts:** The entire `pay()` call reverts. The payer's ETH is returned. This can cause permanent DoS for a project if the hook is in a broken state.
-
----
-
-## Journey 10: Data Hook Interception (Cash Out)
-
-**Actor:** Token holder cashing out from a Croptop-deployed project
-**Entry point:** `CTDeployer.beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context) external view returns (uint256 cashOutTaxRate, uint256 cashOutCount, uint256 totalSupply, JBCashOutHookSpecification[] memory hookSpecifications)`
-**Who can call:** Intended to be called by JBMultiTerminal during the `cashOut()` flow. No explicit access control -- any address can call this function, but it is only meaningful when called by the terminal as part of a cash-out.
-**Source:** `src/CTDeployer.sol` lines 132-151
-
-### Parameters
-
-- `context` (`JBBeforeCashOutRecordedContext`): Standard Juicebox cash-out context containing `projectId`, `holder`, `cashOutCount`, `totalSupply`, and metadata.
-
-### Execution Flow
-
-1. JBMultiTerminal calls `CTDeployer.beforeCashOutRecordedWith(context)`.
-
-2. **Sucker check** (line 144):
-   ```
-   if (SUCKER_REGISTRY.isSuckerOf(context.projectId, context.holder))
-       return (0, context.cashOutCount, context.totalSupply, [])
-   ```
-   If the holder is a registered sucker: return zero tax rate (fee-free cash out). Skip the hook entirely.
-
-3. **Normal path** (line 150): Forward to `dataHookOf[context.projectId].beforeCashOutRecordedWith(context)`.
-
-### State Changes
-
-- None. This is a `view` function.
-
-### Events
-
-- None. This is a `view` function.
-
-### Edge Cases
-
-- **Sucker impersonation:** If an attacker can register as a sucker (via compromised registry), they get zero-tax cash outs from any Croptop project.
-- **Sucker registry reverts:** If `isSuckerOf()` reverts, the entire cash-out reverts. This could DoS cash-outs.
-- **Hook reverts (non-sucker path):** Same as Journey 9 -- permanent DoS for non-sucker cash-outs.
-- **Sucker cashing out:** The sucker receives full treasury value without paying the project's configured cash-out tax. This is intentional (cross-chain bridging needs lossless value transfer).
-
----
-
-## Journey 11: Read Posting Allowance
-
-**Actor:** Anyone (view function)
-**Entry point:** `CTPublisher.allowanceFor(address hook, uint256 category) public view returns (uint256 minimumPrice, uint256 minimumTotalSupply, uint256 maximumTotalSupply, uint256 maximumSplitPercent, address[] memory allowedAddresses)`
-**Who can call:** Anyone. This is a public view function with no access control.
-**Source:** `src/CTPublisher.sol` lines 161-193
-
-### Parameters
-
-- `hook` (`address`): The hook contract.
-- `category` (`uint256`): The posting category.
-
-### Returns
-
-| Return | Type | Description |
-|--------|------|-------------|
-| `minimumPrice` | `uint256` | Extracted from bits 0-103 of packed storage |
-| `minimumTotalSupply` | `uint256` | Extracted from bits 104-135 |
-| `maximumTotalSupply` | `uint256` | Extracted from bits 136-167 |
-| `maximumSplitPercent` | `uint256` | Extracted from bits 168-199 |
-| `allowedAddresses` | `address[]` | Full copy of the allowlist array |
-
-### State Changes
-
-- None. This is a `view` function.
-
-### Events
-
-- None. This is a `view` function.
-
-### Edge Cases
-
-- **Unconfigured category:** Returns all zeros and empty array. A `minimumTotalSupply` of 0 means posting is not allowed.
-- **Gas cost for large allowlists:** The function copies the entire `_allowedAddresses` array to memory. For a 10,000-address list, this is approximately 200,000 gas for the memory copy.
-
----
-
-## Journey 12: Look Up Tiers by IPFS URI
-
-**Actor:** Anyone (view function)
-**Entry point:** `CTPublisher.tiersFor(address hook, bytes32[] memory encodedIPFSUris) external view returns (JB721Tier[] memory tiers)`
-**Who can call:** Anyone. This is an external view function with no access control.
-**Source:** `src/CTPublisher.sol` lines 118-145
-
-### Parameters
-
-- `hook` (`address`): The hook contract.
-- `encodedIPFSUris` (`bytes32[]`): Array of encoded IPFS URIs to look up.
-
-### Returns
-
-`JB721Tier[]` -- one tier per URI. Empty tier (all zeros) if the URI has no associated tier.
-
-### Execution Flow
-
-For each URI:
-1. Look up `tierIdForEncodedIPFSUriOf[hook][uri]`
-2. If non-zero, call `hook.STORE().tierOf(hook, tierId, false)` (line 142)
-3. If zero, return an empty `JB721Tier`
-
-### State Changes
-
-- None. This is a `view` function.
-
-### Events
-
-- None. This is a `view` function.
-
-### Edge Cases
-
-- **Stale mapping:** If a tier was removed but the mapping was not yet cleared (only cleared on re-post), `tierOf()` may return a tier with `remainingSupply = 0` or the store may revert.
-- **Large array:** Each URI requires an external call to the store. Gas scales linearly with array length.
+- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) for the underlying tier issuance behavior Croptop wraps.
+- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) when the question is about base project accounting rather than post validation or fee routing.