@bananapus/omnichain-deployers-v6 0.0.18 → 0.0.20

package/ADMINISTRATION.md

@@ -2,6 +2,32 @@
 
 Admin privileges and their scope in nana-omnichain-deployers-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Omnichain project launch, hook composition, sucker deployment, and the deployer's data-hook proxy behavior. |
+| Operators | Project owners and delegates, the `JBOmnichainDeployer`, and the configured `JBSuckerRegistry` with its wildcard token-mapping grant. |
+| Highest-risk actions | Launching a project with the wrong hook composition, terminal configuration, or cross-chain setup, then assuming it can be rewritten later. |
+| Recovery posture | The deployer's immutable dependencies cannot be edited in place. Project-level recovery usually means launching corrected rulesets or redeploying the broader project path. |
+
+## Routine Operations
+
+- Validate all deploy-time hook choices, 721 settings, and sucker configuration before using `launchProjectFor` or `launchRulesetsFor`.
+- Keep the distinction clear between per-ruleset composed hooks and the deployer's permanent proxy role.
+- Use the deployer when you want its tax-free sucker and mint-permission behavior; otherwise, do not assume it is a drop-in replacement for arbitrary hook wiring.
+
+## One-Way Or High-Risk Actions
+
+- Constructor-time wildcard permissions and immutable references on the deployer cannot be changed afterward.
+- Launch-time hook composition choices determine how future pay and cash-out flows are merged for that ruleset.
+- A bad omnichain deployment can leave a project with a cross-chain shape that is expensive to unwind operationally.
+
+## Recovery Notes
+
+- If the project is still administratively flexible, queue new rulesets or use project-level migration paths to move to corrected hook composition.
+- If the deployer's own immutable assumptions are wrong, recovery means deploying a new deployer path rather than trying to hot-fix the existing one.
+
 ## Roles
 
 | Role | How Assigned | Scope |

package/ARCHITECTURE.md

@@ -1,107 +1,70 @@
-# nana-omnichain-deployers-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Omnichain project deployer for Juicebox V6. Wraps the project deployment flow to automatically configure cross-chain suckers and a 721 tiers hook, acting as a data hook that gives suckers 0% cash-out tax (bridging privilege) and mint permission. Every project gets a 721 hook (even with 0 initial tiers).
+`nana-omnichain-deployers-v6` launches Juicebox projects that are ready for both tiered NFTs and cross-chain suckers from day one. It also acts as a wrapper data hook so it can compose a 721 hook with an optional extra data hook while granting suckers tax-free cash outs and mint permission.
 
-## Contract Map
+## Boundaries
 
-```
-src/
-├── JBOmnichainDeployer.sol       — Deploys projects with sucker + 721 hook integration, acts as data hook wrapper
-├── interfaces/
-│   └── IJBOmnichainDeployer.sol  — Interface
-└── structs/
-    ├── JBDeployerHookConfig.sol      — Custom hook configuration for deployment
-    ├── JBOmnichain721Config.sol      — 721 hook deployment config (tiers + cashout flag + salt)
-    ├── JBTiered721HookConfig.sol     — Per-ruleset 721 hook configuration
-    └── JBSuckerDeploymentConfig.sol  — Sucker deployment parameters
-```
-
-## Hook Storage Mappings
+- `JBOmnichainDeployer` is both a deployer and a live hook wrapper. Those two roles are inseparable.
+- The repo composes `nana-721-hook-v6` and `nana-suckers-v6`; it should not duplicate their internal logic.
+- Project accounting still happens in the core protocol.
 
-The deployer maintains two internal mappings, both keyed by `(projectId, rulesetId)`:
+## Main Components
 
-- **`_tiered721HookOf`** — Stores the project's `IJB721TiersHook` reference and a `useDataHookForCashOut` flag. Always populated for every ruleset (every project gets a 721 hook). The hook is always consulted for payments (it controls NFT tier minting), and optionally consulted for cash outs based on the flag.
+| Component | Responsibility |
+| --- | --- |
+| `JBOmnichainDeployer` | Project launch, ruleset queueing, hook composition, and sucker-safe cash-out policy |
+| config structs | 721 hook config, extra hook config, and sucker deployment config |
+| `IJBOmnichainDeployer` | Public deployer and inspection interface |
 
-- **`_extraDataHookOf`** — Stores an optional secondary data hook (e.g., a buyback hook) extracted from the ruleset's original `metadata.dataHook` field before the deployer overwrites it with itself. Includes separate `useDataHookForPay` and `useDataHookForCashOut` flags, preserved from the original ruleset metadata. Only populated when the caller's ruleset config specifies a non-zero `dataHook`.
+## Runtime Model
 
-During `_setup721`, the deployer extracts any user-specified data hook into `_extraDataHookOf`, then replaces `metadata.dataHook` with itself and forces both pay/cashout flags to `true`. At runtime, the deployer delegates to the 721 hook first, then the extra hook (if present), and merges their results.
+### Launch
 
-## Key Data Flows
-
-### Omnichain Project Deployment
-```
-Caller → JBOmnichainDeployer.launchProjectFor()
-  → Deploy 721 hook via HOOK_DEPLOYER (always, even with 0 tiers)
-  → _setup721(): store hooks, insert deployer as data hook
-  → Launch JB project via controller.launchProjectFor
-  → Transfer 721 hook ownership to project (after project NFT exists)
-  → Deploy suckers via JBSuckerRegistry
-  → Transfer project NFT to owner
+```text
+caller
+  -> launch project or queue rulesets through the deployer
+  -> deployer installs itself as the ruleset data hook
+  -> deployer deploys or carries forward the 721 hook
+  -> deployer optionally deploys sucker pairs with deterministic salts
+  -> project ownership is transferred to the intended owner
 ```
 
-### Data Hook Behavior
-```
-Payment → JBOmnichainDeployer.beforePayRecordedWith()
-  → Calls 721 hook first (from _tiered721HookOf) for specs/split amounts
-  → If 721 hook returned specs: include in merged output
-  → Calls custom hook from _extraDataHookOf (if useDataHookForPay=true)
-  → Custom hook receives reduced amount (payment - splitAmount)
-  → Uses 721 hook's split-adjusted weight directly
-  → Merges both hook specs (721 first if any, then custom)
-
-Cash Out → JBOmnichainDeployer.beforeCashOutRecordedWith()
-  → If caller is a registered sucker: return 0% cash-out tax (early return)
-  → Calls 721 hook (from _tiered721HookOf, if useDataHookForCashOut=true)
-    → Updates cashOutTaxRate, cashOutCount, totalSupply from 721 hook response
-  → Calls custom hook (from _extraDataHookOf, if useDataHookForCashOut=true)
-    → Receives already-updated values from 721 hook
-    → Further updates cashOutTaxRate, cashOutCount, totalSupply
-  → Merges both hooks' specifications (721 specs first, then custom hook specs)
-  → If 721 hook has flag=true and reverts (fungible cashout): revert propagates
-  → If neither hook has the flag set: return original values
-```
+### Pay And Cash-Out Wrapping
 
-### Ruleset Management
-```
-Owner → JBOmnichainDeployer.queueRulesetsOf()
-  → If new tiers provided: deploy new 721 hook
-  → If no new tiers: carry forward 721 hook from latest ruleset
-  → _setup721(): store hooks, insert deployer as data hook
-  → Queue new rulesets via JBController
-
-Owner → JBOmnichainDeployer.launchRulesetsFor()
-  → Deploy new 721 hook
-  → Launch rulesets for an existing project
-  → Configure terminal integration
+```text
+runtime callback
+  -> if the actor is a registered sucker, return the special tax-free / mint-enabled path
+  -> otherwise call the 721 hook first when configured
+  -> then call the extra data hook when configured
+  -> merge hook specs in order and return the combined result
 ```
 
-## Extension Points
-
-| Point | Interface | Purpose |
-|-------|-----------|---------|
-| Data hook (pay) | `IJBRulesetDataHook.beforePayRecordedWith` | Compose 721 + custom hook for payments |
-| Data hook (cashout) | `IJBRulesetDataHook.beforeCashOutRecordedWith` | 0% tax for suckers, forward to hooks |
-| Sucker registry | `IJBSuckerRegistry` | Sucker deployment and discovery |
-| 721 hook deployer | `IJB721TiersHookDeployer` | 721 tiers hook deployment (always used) |
+## Critical Invariants
 
-## Design Decisions
+- Suckers must be able to bridge without getting trapped behind custom cash-out policies.
+- Hook order matters: the 721 hook runs first, and the extra hook receives the updated context.
+- The deployer's predicted ruleset IDs must stay aligned with `JBRulesets` behavior; the storage keys depend on it.
+- Every project launched through this repo gets a 721 hook surface, even if it starts with zero tiers.
 
-1. **Always deploy a 721 hook, even with 0 tiers.** Every project gets a 721 hook instance so that NFT tiers can be added later via `queueRulesetsOf` without changing the data hook architecture. The hook is also needed as the pay hook target for tier minting. Deploying with 0 tiers is a no-op at runtime (no specs returned) but keeps the infrastructure in place.
+## Where Complexity Lives
 
-2. **Deployer acts as a data hook wrapper instead of direct hook assignment.** The core protocol only supports a single `dataHook` per ruleset. The deployer inserts itself as that hook so it can compose two hooks (721 + custom) behind a single interface, while also injecting sucker-specific logic (0% cash-out tax for suckers, mint permission for suckers). Without this wrapper, projects would have to choose between NFT tiers, a buyback hook, and sucker privileges.
+- This repo hides composition complexity behind a simple launch surface, which makes stale assumptions dangerous.
+- Ruleset ID prediction is a subtle but central storage keying mechanism.
+- The sucker exception path intentionally short-circuits normal hook composition and must stay easy to reason about.
 
-3. **721 hook specs are merged first, custom hook specs second.** During payments, the 721 hook's split amount is subtracted from the payment before the custom hook sees it. This ordering ensures the 721 hook claims funds for tier mints at full price, and the custom hook (e.g., buyback) operates on the remaining amount. For cash outs, the 721 hook adjusts `cashOutTaxRate`/`cashOutCount`/`totalSupply` first, and the custom hook receives those already-updated values, allowing each hook to build on the previous hook's adjustments.
+## Dependencies
 
-4. **721 hook's weight is used directly after tier splits.** The 721 hook's `beforePayRecordedWith` returns a weight that is already adjusted for tier-split deductions (via `JB721TiersHookLib.calculateWeight`). The deployer uses this weight directly instead of re-scaling with `mulDiv`. This prevents double-counting: the 721 hook mints its own NFTs for the split amount, and the terminal mints fungible tokens only for the remainder at the hook's pre-adjusted weight.
+- `nana-core-v6` for project launch and hook interfaces
+- `nana-721-hook-v6` for tiered NFT behavior
+- `nana-suckers-v6` for cross-chain transport
+- `nana-ownable-v6` for project-following hook ownership
 
-5. **Ruleset IDs are predicted as `block.timestamp + i`.** The deployer must store hook configs keyed by ruleset ID before the rulesets are actually created. It predicts IDs using the core protocol's convention (`block.timestamp` for the first, incrementing for subsequent rulesets in the same transaction). `queueRulesetsOf` explicitly reverts if `latestRulesetId >= block.timestamp`, which would mean rulesets were already queued in the same block and the prediction would be wrong.
+## Safe Change Guide
 
-## Dependencies
-- `@bananapus/core-v6` — Core protocol (controller, directory, permissions)
-- `@bananapus/721-hook-v6` — NFT tier deployment
-- `@bananapus/ownable-v6` — JB-aware ownership
-- `@bananapus/permission-ids-v6` — Permission constants
-- `@bananapus/suckers-v6` — Cross-chain sucker registry
-- `@openzeppelin/contracts` — ERC2771, ERC721Receiver
+- Review launch-time logic and runtime-hook logic together. This repo is easy to break by fixing only one side.
+- When changing hook composition, verify both payment and cash-out ordering.
+- If you touch ruleset ID prediction, test same-block and queued-ruleset edge cases explicitly.
+- Keep deterministic salt handling stable across chains; address predictability is part of the feature.
+- Treat "transparent wrapper" claims as something to prove continuously, not assume.

package/AUDIT_INSTRUCTIONS.md

@@ -1,386 +1,72 @@
-# nana-omnichain-deployers-v6 -- Audit Instructions
+# Audit Instructions
 
-## Previous Audit Findings
+This repo launches projects that are immediately composed with 721 hooks and sucker deployments. Audit it as a privileged deployer and runtime data-hook participant.
 
-No prior formal audit with finding IDs has been conducted on this repository. Known risks and design trade-offs are documented in [`RISKS.md`](./RISKS.md).
+## Objective
 
-## Compiler and Version Info
-
-Settings from `foundry.toml`:
-
-| Setting | Value |
-|---------|-------|
-| Solidity version | `0.8.28` |
-| EVM target | `cancun` |
-| Intermediate representation | `via_ir = true` |
-| Optimizer runs | `200` |
-| Dependency paths | `node_modules`, `lib` |
-| Fuzz runs | `4,096` |
-| Invariant runs | `1,024` (depth: `100`, `fail_on_revert: false`) |
+Find issues that:
+- launch projects with incorrect rulesets, terminals, or hook ownership
+- grant cash-out or mint privileges to non-suckers
+- mis-scale weight or tax behavior during omnichain-specific data-hook flows
+- leave deployed hook or sucker ownership in the wrong hands
+- create inconsistent behavior between local-only and omnichain project launches
 
 ## Scope
 
-One contract, 872 lines, four structs. This repo wraps Juicebox V6 project deployment to automatically configure cross-chain suckers and a 721 tiers hook. The deployer itself acts as a data hook proxy, composing a 721 hook with an optional custom hook (e.g. buyback) while granting registered suckers 0% cash-out tax and mint permission.
-
-## Architecture
-
-| File | Lines | Role |
-|------|------:|------|
-| `src/JBOmnichainDeployer.sol` | 872 | Main contract. Deploys projects, queues rulesets, proxies data hook calls. Implements `IJBRulesetDataHook`, `IERC721Receiver`, `JBPermissioned`, `ERC2771Context`. |
-| `src/interfaces/IJBOmnichainDeployer.sol` | 171 | Public interface. |
-| `src/structs/JBDeployerHookConfig.sol` | 11 | Stores custom data hook address + pay/cashout flags per ruleset. |
-| `src/structs/JBOmnichain721Config.sol` | 16 | 721 hook deployment config: tiers config + cashout flag + salt. |
-| `src/structs/JBSuckerDeploymentConfig.sol` | 12 | Sucker deployer configs + salt for deterministic addresses. |
-| `src/structs/JBTiered721HookConfig.sol` | 10 | Stores 721 hook address + `useDataHookForCashOut` flag per ruleset. |
-
-**Total source**: ~1,092 lines.
-
-## External Dependencies
-
-| Dependency | What the deployer calls |
-|------------|------------------------|
-| `IJBController` | `launchProjectFor`, `launchRulesetsFor`, `queueRulesetsOf`, `DIRECTORY()`, `RULESETS()` |
-| `IJBProjects` | `count()`, `ownerOf()`, `transferFrom()` |
-| `IJBPermissions` | `setPermissionsFor()` (constructor), `hasPermission()` (via `_requirePermissionFrom`) |
-| `IJB721TiersHookDeployer` | `deployHookFor()` |
-| `IJBSuckerRegistry` | `isSuckerOf()`, `deploySuckersFor()` |
-| `JBOwnable` | `transferOwnershipToProject()` on deployed 721 hooks |
-| `IJBRulesetDataHook` | `beforePayRecordedWith()`, `beforeCashOutRecordedWith()`, `hasMintPermissionFor()` on stored hooks |
-| `@prb/math` | `mulDiv()` for weight scaling |
-
-## Storage Layout
-
-Two mappings, both `internal`:
-
-```solidity
-// Slot 0 (after inherited storage)
-mapping(uint256 projectId => mapping(uint256 rulesetId => JBDeployerHookConfig)) internal _extraDataHookOf;
-
-// Slot 1
-mapping(uint256 projectId => mapping(uint256 rulesetId => JBTiered721HookConfig)) internal _tiered721HookOf;
-```
-
-Both are keyed by `(projectId, rulesetId)` where `rulesetId` is predicted as `block.timestamp + i` during setup.
-
-## Key Constants
-
-- Constructor grants `MAP_SUCKER_TOKEN` permission to `SUCKER_REGISTRY` for `projectId = 0` (wildcard -- all projects).
-- Salt for 721 hook deployment: `keccak256(abi.encode(_msgSender(), config.salt))` -- includes sender for cross-chain replay protection. `bytes32(0)` salt bypasses determinism.
-- Salt for sucker deployment: `keccak256(abi.encode(suckerDeploymentConfiguration.salt, _msgSender()))`.
-- Sucker deployment skipped when `suckerDeploymentConfiguration.salt == bytes32(0)`.
-
-## Key Flows
-
-### 1. `launchProjectFor` (two overloads)
-
-```
-launchProjectFor(owner, projectUri, [deploy721Config], rulesetConfigurations, terminalConfigurations, memo, suckerDeploymentConfiguration, controller)
-```
-
-**Full signature (with explicit 721 config)**:
-```solidity
-function launchProjectFor(
-    address owner,
-    string calldata projectUri,
-    JBOmnichain721Config calldata deploy721Config,
-    JBRulesetConfig[] memory rulesetConfigurations,
-    JBTerminalConfig[] calldata terminalConfigurations,
-    string calldata memo,
-    JBSuckerDeploymentConfig calldata suckerDeploymentConfiguration,
-    IJBController controller
-) external returns (uint256 projectId, IJB721TiersHook hook, address[] memory suckers)
-```
-
-**Simplified overload** (omits `deploy721Config`, derives default from first ruleset's `baseCurrency`):
-```solidity
-function launchProjectFor(
-    address owner,
-    string calldata projectUri,
-    JBRulesetConfig[] memory rulesetConfigurations,
-    JBTerminalConfig[] calldata terminalConfigurations,
-    string calldata memo,
-    JBSuckerDeploymentConfig calldata suckerDeploymentConfiguration,
-    IJBController controller
-) external returns (uint256 projectId, IJB721TiersHook hook, address[] memory suckers)
-```
-
-**Execution order**:
-1. `projectId = PROJECTS.count() + 1` -- predicted before creation.
-2. `_deploy721Hook(projectId, config)` -- deploys 721 hook via `HOOK_DEPLOYER.deployHookFor()`.
-3. `_setup721(projectId, rulesetConfigurations, hook, use721ForCashOut)` -- stores hook mappings, replaces `metadata.dataHook` with `address(this)`.
-4. `controller.launchProjectFor(address(this), ...)` -- project NFT minted to deployer.
-5. Reverts with `JBOmnichainDeployer_ProjectIdMismatch` if returned ID does not match prediction.
-6. `JBOwnable(hook).transferOwnershipToProject(projectId)` -- transfers hook ownership.
-7. `SUCKER_REGISTRY.deploySuckersFor(...)` -- if salt is non-zero.
-8. `PROJECTS.transferFrom(address(this), owner, projectId)` -- transfers project NFT to intended owner.
-
-**No permission checks**: Anyone can call `launchProjectFor`. The caller-supplied `controller` is trusted because the project does not exist yet (no controller to validate against).
-
-### 2. `launchRulesetsFor` (two overloads)
-
-```solidity
-function launchRulesetsFor(
-    uint256 projectId,
-    JBOmnichain721Config memory deploy721Config,
-    JBRulesetConfig[] memory rulesetConfigurations,
-    JBTerminalConfig[] calldata terminalConfigurations,
-    string calldata memo,
-    IJBController controller
-) external returns (uint256 rulesetId, IJB721TiersHook hook)
-```
-
-**Permission checks**: Requires both `LAUNCH_RULESETS` and `SET_TERMINALS` from project owner.
-
-**Controller validation**: `_validateController(projectId, controller)` checks `controller.DIRECTORY().controllerOf(projectId) == controller`.
-
-**Execution**: Always deploys a new 721 hook, transfers ownership, then calls `controller.launchRulesetsFor()`.
-
-### 3. `queueRulesetsOf` (two overloads)
-
-```solidity
-function queueRulesetsOf(
-    uint256 projectId,
-    JBOmnichain721Config memory deploy721Config,
-    JBRulesetConfig[] memory rulesetConfigurations,
-    string calldata memo,
-    IJBController controller
-) external returns (uint256 rulesetId, IJB721TiersHook hook)
-```
-
-**Permission checks**: Requires `QUEUE_RULESETS` from project owner.
-
-**Controller validation**: Same as `launchRulesetsFor`.
-
-**Ruleset ID prediction guard**:
-```solidity
-uint256 latestRulesetId = controller.RULESETS().latestRulesetIdOf(projectId);
-if (latestRulesetId >= block.timestamp) {
-    revert JBOmnichainDeployer_RulesetIdsUnpredictable();
-}
-```
-
-**721 hook handling**:
-- If `deploy721Config.deployTiersHookConfig.tiersConfig.tiers.length > 0`: deploy new hook, transfer ownership.
-- Otherwise: carry forward `_tiered721HookOf[projectId][latestRulesetId].hook`.
-
-### 4. `deploySuckersFor`
-
-```solidity
-function deploySuckersFor(
-    uint256 projectId,
-    JBSuckerDeploymentConfig calldata suckerDeploymentConfiguration
-) external returns (address[] memory suckers)
-```
-
-**Permission checks**: Requires `DEPLOY_SUCKERS` from project owner.
-
-### 5. `beforePayRecordedWith` (data hook proxy -- view)
-
-```solidity
-function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
-    external view returns (uint256 weight, JBPayHookSpecification[] memory hookSpecifications)
-```
-
-**Composition logic**:
-1. Call 721 hook's `beforePayRecordedWith` (always, if hook exists). Extract `tiered721HookSpec` and `totalSplitAmount`.
-2. Compute `projectAmount = context.amount.value - totalSplitAmount` (clamped to 0).
-3. Call custom hook's `beforePayRecordedWith` with `hookContext.amount.value = projectAmount` (if `useDataHookForPay == true`).
-4. If custom hook not called, `weight = context.weight`.
-5. Scale weight: if `projectAmount == 0`, `weight = 0`. If `projectAmount < context.amount.value`, `weight = mulDiv(weight, projectAmount, context.amount.value)`.
-6. Merge specs: 721 spec first, then custom hook specs.
-
-### 6. `beforeCashOutRecordedWith` (data hook proxy -- view)
-
-```solidity
-function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
-    external view returns (uint256, uint256, uint256, JBCashOutHookSpecification[] memory)
-```
-
-**Sequential composition**:
-1. **Sucker check** (early return): If `SUCKER_REGISTRY.isSuckerOf(projectId, holder)` returns true, return `(0, cashOutCount, totalSupply, empty)`.
-2. **Initialize**: Set `cashOutTaxRate`, `cashOutCount`, `totalSupply` from context.
-3. **721 hook**: If stored and `useDataHookForCashOut == true`, call its `beforeCashOutRecordedWith` with current values. Updates `cashOutTaxRate`, `cashOutCount`, `totalSupply`, and stores returned specs (always 0 or 1).
-4. **Custom hook**: If stored and `useDataHookForCashOut == true`, call its `beforeCashOutRecordedWith` with the already-updated values from the 721 hook. Further updates values and stores returned specs.
-5. **Merge specs**: If either hook returned specs, merge them (721 first, then custom) into a single array.
-6. **Fallback**: If neither returned specs, return adjusted `(cashOutTaxRate, cashOutCount, totalSupply, empty)`.
-
-Note: Both hooks are called if both have the flag set. The 721 hook's output feeds into the custom hook's input. The sucker check always takes priority.
-
-### 7. `hasMintPermissionFor` (data hook proxy -- view)
-
-```solidity
-function hasMintPermissionFor(uint256 projectId, JBRuleset memory ruleset, address addr)
-    external view returns (bool)
-```
-
-1. If `SUCKER_REGISTRY.isSuckerOf(projectId, addr)` returns true, return `true`.
-2. If custom hook exists and its `hasMintPermissionFor` returns true, return `true`.
-3. The 721 hook is NOT checked for mint permission.
-4. Otherwise return `false`.
-
-## The `_setup721` Pattern (Critical)
-
-```solidity
-function _setup721(
-    uint256 projectId,
-    JBRulesetConfig[] memory rulesetConfigurations,
-    IJB721TiersHook hook721,
-    bool use721ForCashOut
-) internal returns (JBRulesetConfig[] memory)
-```
-
-For each ruleset config at index `i`:
-1. **Self-reference guard**: Reverts with `JBOmnichainDeployer_InvalidHook` if `metadata.dataHook == address(this)`.
-2. **Store 721 hook**: `_tiered721HookOf[projectId][block.timestamp + i] = JBTiered721HookConfig(hook721, use721ForCashOut)`.
-3. **Store custom hook**: If `metadata.dataHook != address(0)`, stores as `_extraDataHookOf[projectId][block.timestamp + i]`.
-4. **Replace metadata**: Sets `metadata.dataHook = address(this)`, forces `useDataHookForPay = true`, `useDataHookForCashOut = true`.
-
-**Ruleset ID prediction**: Keys are `block.timestamp + i`. This MUST match the IDs assigned by `JBRulesets` when the controller processes the configs. This is validated by:
-- `launchProjectFor`: The project ID prediction (`PROJECTS.count() + 1`) is validated post-hoc via the `ProjectIdMismatch` revert.
-- `queueRulesetsOf`: The `latestRulesetId >= block.timestamp` guard prevents same-block conflicts.
-- `launchRulesetsFor`: No explicit guard on the ruleset ID prediction. This is safe because `launchRulesetsFor` is called on the controller which assigns IDs starting from `block.timestamp`.
-
-## Gotchas for Auditors
-
-1. **Ruleset ID prediction is fragile**: The deployer predicts ruleset IDs as `block.timestamp + i`. If the core protocol changes how IDs are assigned (e.g. incrementing differently), stored hooks will be keyed to the wrong rulesets. The `queueRulesetsOf` guard (`latestRulesetId >= block.timestamp`) catches same-block conflicts but does NOT protect against multi-tx-in-block race conditions on `launchRulesetsFor`.
-
-2. **No reentrancy guard**: The contract does not use `ReentrancyGuard`. The `launchProjectFor` flow holds the project NFT temporarily. If `controller.launchProjectFor` calls back into the deployer, the project NFT is still held by the deployer. However, the entire tx would revert if the returned project ID doesn't match, so exploitation would require a cooperating controller.
-
-3. **721 hook always deployed**: Even with 0 tiers, a 721 hook is deployed for every project/ruleset launch. This is intentional -- it ensures the hook exists for future tier additions.
-
-4. **Cash-out hooks are now composed**: Like pay hooks, cash-out handling calls both hooks sequentially (721 hook first, then custom hook) and merges their specifications. The 721 hook's output values feed into the custom hook's input context.
-
-5. **Carry-forward can yield zero-address hook**: In `queueRulesetsOf` with 0 tiers, the hook is carried from `_tiered721HookOf[projectId][latestRulesetId]`. If no hook was stored for that ruleset (e.g. the project was created outside the deployer), this returns `address(0)`.
-
-6. **Custom hook receives reduced amount**: In `beforePayRecordedWith`, the custom data hook sees `amount.value = projectAmount` (original minus 721 splits). This is a modified `memory` copy of the original calldata context. The custom hook cannot see the original payment amount.
-
-7. **Weight can overflow from custom hooks**: The deployer passes whatever weight the custom hook returns through `mulDiv`. If a custom hook returns `type(uint256).max`, the `mulDiv` still works correctly (PRB math handles this), but the resulting token mint amount could be extremely large.
-
-8. **Constructor grants wildcard permission**: The deployer grants `MAP_SUCKER_TOKEN` to the `SUCKER_REGISTRY` for `projectId = 0` (wildcard). This means the sucker registry can map tokens for ANY project the deployer is associated with.
-
-9. **`launchProjectFor` has no permission checks**: Anyone can call it. The project is created with the deployer as owner, then transferred. The caller-supplied controller is not validated (there's no existing project to validate against).
-
-10. **`launchRulesetsFor` has no ruleset ID prediction guard**: Unlike `queueRulesetsOf`, `launchRulesetsFor` does not check `latestRulesetId >= block.timestamp`. This is acceptable because `launchRulesetsFor` is the first ruleset launch for an existing project, but could fail if called in the same block as another ruleset operation.
-
-## Error Conditions
-
-| Error | Trigger | Function |
-|-------|---------|----------|
-| `JBOmnichainDeployer_ControllerMismatch` | Provided controller does not match `directory.controllerOf(projectId)` | `queueRulesetsOf`, `launchRulesetsFor` |
-| `JBOmnichainDeployer_InvalidHook` | Ruleset's `metadata.dataHook == address(this)` | `_setup721` (called by all launch/queue functions) |
-| `JBOmnichainDeployer_ProjectIdMismatch` | `controller.launchProjectFor` returns unexpected project ID | `_launchProjectFor` |
-| `JBOmnichainDeployer_RulesetIdsUnpredictable` | `latestRulesetIdOf(projectId) >= block.timestamp` | `_queueRulesetsOf` |
-| `JBOmnichainDeployer_UnexpectedNFTReceived` | `onERC721Received` called by non-`PROJECTS` contract | `onERC721Received` |
-
-## Priority Audit Areas
-
-### P0 -- Critical
-
-1. **Sucker privilege escalation**: Can a non-sucker address obtain 0% cash-out tax? The only gate is `SUCKER_REGISTRY.isSuckerOf()`. If the registry is compromised or returns incorrect values, all omnichain projects are affected. Verify the sucker registry's access control for `deploySuckersFor`.
-
-2. **Ruleset ID prediction correctness**: Verify that `block.timestamp + i` matches the IDs assigned by `JBRulesets` in all scenarios. If the prediction is wrong, the deployer's stored hooks will never be consulted, and `beforePayRecordedWith` / `beforeCashOutRecordedWith` will return default values (no 721 integration, no sucker bypass).
-
-3. **Ownership transfer ordering**: In `launchProjectFor`, the 721 hook is deployed BEFORE the project exists. Hook ownership is transferred after `controller.launchProjectFor` returns. If the controller reverts, the hook exists but is owned by the deployer with no project to transfer to. Verify this is a safe failure mode (entire tx reverts atomically).
-
-### P1 -- High
-
-4. **Data hook proxy composition**: Verify that the weight scaling in `beforePayRecordedWith` is correct when 721 splits consume part of the payment. Specifically verify: `mulDiv(weight, projectAmount, context.amount.value)` when `totalSplitAmount > 0`.
-
-5. **Controller validation bypass**: `launchProjectFor` does not validate the controller because the project doesn't exist yet. Verify a malicious controller cannot exploit this (e.g. by returning a different project ID and tricking the deployer into configuring the wrong project).
-
-6. **Permission escalation via deploySuckersFor**: The deployer grants `MAP_SUCKER_TOKEN` with `projectId = 0` (wildcard). Verify this cannot be abused to map tokens for projects not created through the deployer.
-
-### P2 -- Medium
-
-7. **Carry-forward stale hook**: When `queueRulesetsOf` carries forward a 721 hook from `latestRulesetId`, verify the carried hook is correct even after multiple queue operations.
-
-8. **Custom hook isolation**: The custom hook receives a modified context (`amount.value = projectAmount`). Verify the hook cannot observe or manipulate the original amount. Verify the memory copy does not alias the original calldata.
-
-9. **ERC2771 interaction**: The deployer uses `_msgSender()` for salt computation and permission checks. Verify the trusted forwarder cannot be used to spoof senders in permission-gated functions.
-
-### P3 -- Low
-
-10. **onERC721Received guard**: Only accepts NFTs from `PROJECTS`. Verify no other ERC721 can be sent to the deployer.
-
-11. **supportsInterface completeness**: Verify the reported interfaces match actual implementations.
-
-## Invariants to Verify
-
-1. **Sucker always gets 0% tax**: For any `context` where `SUCKER_REGISTRY.isSuckerOf(projectId, holder)` returns true, `beforeCashOutRecordedWith` returns `cashOutTaxRate == 0`.
-
-2. **Sucker always gets mint permission**: For any `(projectId, ruleset, addr)` where `SUCKER_REGISTRY.isSuckerOf(projectId, addr)` returns true, `hasMintPermissionFor` returns `true`.
-
-3. **721 spec ordering**: In `beforePayRecordedWith`, if the 721 hook returns a spec, it is always the first element in the returned `hookSpecifications` array.
-
-4. **Data hook replacement**: After `_setup721`, every ruleset config has `metadata.dataHook == address(this)`, `useDataHookForPay == true`, `useDataHookForCashOut == true`.
-
-5. **Self-reference prevention**: `_setup721` reverts if any ruleset's `metadata.dataHook == address(this)`.
-
-6. **Weight scaling correctness**: `weight = mulDiv(hookWeight, projectAmount, totalAmount)` where `projectAmount = totalAmount - splitAmount`. When `splitAmount >= totalAmount`, `weight == 0`.
-
-7. **Controller validation**: `queueRulesetsOf` and `launchRulesetsFor` revert if the provided controller does not match `directory.controllerOf(projectId)`.
-
-8. **Deployer never holds ETH**: The deployer has no `receive()` or `fallback()`, so it should never hold ETH.
-
-9. **Hook storage consistency**: After `launchProjectFor` or `queueRulesetsOf`, `_tiered721HookOf[projectId][predictedRulesetId]` is non-zero for every queued ruleset.
-
-10. **Ownership transfer completeness**: After `launchProjectFor`, the project NFT is owned by `owner` (not the deployer). After any 721 hook deployment, the hook's JBOwnable ownership is transferred to the project.
-
-## Test Suite Overview
+In scope:
+- `src/JBOmnichainDeployer.sol`
+- `src/interfaces/`
+- `src/structs/`
+- deployment scripts in `script/`
 
-14 test files, ~5,000 lines of test code:
+Key dependencies:
+- `nana-core-v6`
+- `nana-721-hook-v6`
+- `nana-suckers-v6`
 
-| Category | Files | Coverage |
-|----------|-------|----------|
-| Unit tests | `JBOmnichainDeployer.t.sol` | Constructor, `supportsInterface`, `onERC721Received`, `beforePayRecordedWith`, `beforeCashOutRecordedWith`, `hasMintPermissionFor`, `deploySuckersFor`, simplified overloads |
-| Guard tests | `JBOmnichainDeployerGuard.t.sol` | Ruleset ID prediction guard, same-block queue revert, multi-ruleset conflict |
-| Attack tests | `OmnichainDeployerAttacks.t.sol` | Fake sucker bypass, reverting hook propagation, inflating hook weight, sucker bypass of reverting hooks |
-| Edge cases | `OmnichainDeployerEdgeCases.t.sol` | `InvalidHook` self-reference, `ProjectIdMismatch`, weight=0 on full splits, `mulDiv` safety with `type(uint256).max`, `useDataHookForCashOut` flag routing, mint permission delegation |
-| Composition | `Tiered721HookComposition.t.sol` | 721+buyback hook composition, split amount forwarding, weight adjustment, spec merging, cashout routing (721 vs custom vs fallback) |
-| Reentrancy | `OmnichainDeployerReentrancy.t.sol` | Pay hook re-entering pay, cashout hook re-entering cashout, pay hook re-entering cashout (fork tests) |
-| Invariants | `invariants/OmnichainDeployerInvariant.t.sol` + handler | Sucker 0% tax, 721 spec ordering, fund conservation, token supply consistency, deployer ETH balance, hook storage consistency |
-| Regression | `regression/HookOwnershipTransfer.t.sol` | Hook ownership transfer in `queueRulesetsOf` |
-| Regression | `regression/ValidateController.t.sol` | Controller validation rejects fake controllers |
-| Fork | `fork/TestOmnichain*.t.sol` (5 files) | Real V4 PoolManager + buyback hook integration, 721 queue-and-adjust, cashout fork, stress, weight fork, sucker deployment fork |
+## System Model
 
-## Testing Setup
+`JBOmnichainDeployer` is a launch surface that can:
+- create a new Juicebox project
+- deploy and configure a 721 hook
+- configure rulesets and terminals
+- deploy suckers and register them for the project
+- participate in pay or cash-out accounting as a data hook where needed
 
-```bash
-# Install dependencies
-npm install
+## Critical Invariants
 
-# Run unit tests
-forge test --match-path 'test/*.t.sol' -vvv
+1. Launch configuration is faithful
+The deployed project must end up with the exact hook, ruleset, and ownership configuration the caller requested.
 
-# Run fork tests (requires RPC)
-RPC_ETHEREUM_MAINNET=<your_rpc> forge test --match-path 'test/fork/*.t.sol' -vvv
+2. Sucker privileges stay restricted
+Zero-tax or mint-permission behavior intended for legitimate suckers must not be reachable by arbitrary contracts or stale registry entries.
 
-# Run invariant tests (requires RPC)
-RPC_ETHEREUM_MAINNET=<your_rpc> forge test --match-contract OmnichainDeployerInvariant -vvv
+3. Weight and accounting scaling are correct
+If the deployer proxies or modifies hook outputs, the resulting project token issuance and reclaim math must still match intended economics.
 
-# Compiler settings
-# Solidity 0.8.28, EVM version: cancun, via_ir: true, optimizer: 200 runs
-```
+4. Ownership transfer is complete
+Deployer-created hooks and helper contracts must not retain silent control after initialization.
 
-Foundry config is at `foundry.toml`. Fuzz runs: 4096. Invariant runs: 1024, depth: 100, `fail_on_revert: false`.
+## Threat Model
 
-## How to Report Findings
+Prioritize:
+- empty or malformed ruleset configurations
+- hook ownership transfer races
+- registry-based privilege spoofing
+- reentrancy around project launch and initialization
+- stale assumptions when optional sucker deployment is skipped
 
-Each finding should follow this 7-point structure:
+## Build And Verification
 
-1. **Title** -- A short, descriptive name (e.g. "Ruleset ID prediction fails on same-block queue").
-2. **Affected contract(s)** -- File path(s) and line number(s).
-3. **Description** -- What the issue is and why it matters. Include relevant code snippets.
-4. **Trigger sequence** -- Step-by-step instructions to reproduce the issue (transactions, parameters, state preconditions).
-5. **Impact** -- What can go wrong: fund loss, privilege escalation, denial of service, incorrect accounting, etc.
-6. **Proof** -- A Foundry test, call trace, or formal argument demonstrating the issue. Runnable PoC strongly preferred.
-7. **Fix** -- A concrete recommendation. Code diff preferred; otherwise a description of the required change.
+Standard workflow:
+- `npm install`
+- `forge build`
+- `forge test`
 
-### Severity Guide
+Existing tests emphasize:
+- reentrancy and attack paths
+- hook composition
+- weight scaling
+- omnichain fork and stress scenarios
 
-| Severity | Criteria |
-|----------|----------|
-| **CRITICAL** | Direct loss or theft of funds, permanent freezing of funds, or unauthorized minting/burning of tokens. Exploitable without unusual preconditions. |
-| **HIGH** | Significant fund loss under specific but realistic conditions, privilege escalation that bypasses access control, or corruption of core protocol state (e.g. wrong hook mappings that silently disable sucker bypass). |
-| **MEDIUM** | Conditional issues requiring atypical state or timing (e.g. same-block race conditions), griefing attacks with bounded cost, or incorrect accounting that does not directly lose funds but violates documented invariants. |
-| **LOW** | Code quality issues, gas inefficiencies, dead code, missing events, deviations from best practices, or edge cases with negligible economic impact. |
+High-value findings typically show either a bad project launch state or a non-sucker actor receiving omnichain-only privileges.