@bananapus/omnichain-deployers-v6 0.0.13 → 0.0.15

package/ADMINISTRATION.md

@@ -18,7 +18,7 @@ Admin privileges and their scope in nana-omnichain-deployers-v6.
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|--------------|
 | `deploySuckersFor` | Project owner or operator | `DEPLOY_SUCKERS` | Per-project | Deploys new cross-chain suckers for an existing project via the sucker registry. |
-| `launchRulesetsFor` | Project owner or operator | `QUEUE_RULESETS` + `SET_TERMINALS` | Per-project | Deploys a 721 tiers hook, launches new rulesets with terminal configuration for an existing project. Has a simplified overload without `deploy721Config`. |
+| `launchRulesetsFor` | Project owner or operator | `LAUNCH_RULESETS` + `SET_TERMINALS` | Per-project | Deploys a 721 tiers hook, launches new rulesets with terminal configuration for an existing project. Has a simplified overload without `deploy721Config`. |
 | `queueRulesetsOf` | Project owner or operator | `QUEUE_RULESETS` | Per-project | Queues new rulesets for an existing project. If tiers provided, deploys a new 721 hook. Otherwise, carries forward the 721 hook from the latest ruleset. Has a simplified overload without `deploy721Config`. |
 
 ### Permissionless Functions
@@ -26,7 +26,7 @@ Admin privileges and their scope in nana-omnichain-deployers-v6.
 | Function | Who Can Call | What It Does |
 |----------|-------------|--------------|
 | `launchProjectFor` | Anyone | Creates a new project with a 721 tiers hook (even with 0 tiers) and suckers. The ERC-721 is minted to the specified `owner`. Returns `(projectId, hook, suckers)`. Has a simplified overload without `deploy721Config` that uses a default empty-tier 721 config. |
-| `beforePayRecordedWith` | JBMultiTerminal (via controller) | View function: calls 721 hook for specs, then custom hook (if configured) with reduced amount. Merges results. |
+| `beforePayRecordedWith` | JBMultiTerminal (via controller) | View function: always calls the 721 hook (when its address is non-zero) for specs, then calls the custom hook (if configured and `useDataHookForPay` is set) with the reduced amount. Merges results. |
 | `beforeCashOutRecordedWith` | JBMultiTerminal (via controller) | View function: returns 0% cash-out tax for registered suckers. Calls 721 hook first (from `_tiered721HookOf`, if `useDataHookForCashOut: true`), then calls custom hook (from `_extraDataHookOf`, if `useDataHookForCashOut: true`) with the updated values from the 721 hook. Both hooks' specifications are merged. If neither has the flag set, returns original values. |
 | `hasMintPermissionFor` | JBController | View function: returns true for registered suckers, otherwise checks the custom hook in `_extraDataHookOf`. |
 | `extraDataHookOf` | Anyone | View function: returns the stored `JBDeployerHookConfig` for a project/ruleset pair (the custom data hook). |
@@ -63,6 +63,41 @@ Admin privileges and their scope in nana-omnichain-deployers-v6.
 
 **Cross-chain determinism:** The salt for sucker deployment is combined with `_msgSender()` (`keccak256(abi.encode(salt, _msgSender()))`). Deploying from the same sender address with the same salt on each chain produces matching sucker addresses.
 
+## Data Hook Proxy Pattern
+
+`JBOmnichainDeployer` acts as a data hook proxy. When set as a project's `dataHook` in ruleset metadata, it wraps up to two inner hooks:
+
+1. **721 tiers hook** (`_tiered721HookOf[projectId][rulesetId]`): Handles NFT-based pay/cashout logic.
+2. **Extra data hook** (`_extraDataHookOf[projectId][rulesetId]`): An optional custom hook for additional pay/cashout logic.
+
+### Call flow for `beforePayRecordedWith`:
+
+```
+Terminal -> Controller -> JBOmnichainDeployer.beforePayRecordedWith()
+  1. Call 721 hook's beforePayRecordedWith (always, when its address is non-zero)
+     -> Get pay hook specifications and the total split amount
+  2. Call extra hook's beforePayRecordedWith (if useDataHookForPay is set on extra hook config)
+     -> Amount is reduced by what the 721 hook already allocated
+  3. Scale the extra hook's weight proportionally to the project's share of the payment
+  4. Merge both hooks' specifications and return
+```
+
+### Call flow for `beforeCashOutRecordedWith`:
+
+```
+Terminal -> Controller -> JBOmnichainDeployer.beforeCashOutRecordedWith()
+  1. Check if caller is a registered sucker -> return 0% cash-out tax (fee-free bridging)
+  2. Call 721 hook's beforeCashOutRecordedWith (if useDataHookForCashOut is set on 721 config)
+     -> Get cashout hook specifications and adjusted values
+  3. Call extra hook's beforeCashOutRecordedWith (if useDataHookForCashOut is set on extra config)
+     -> Receives updated values from 721 hook
+  4. Merge both hooks' specifications and return
+```
+
+**`useDataHookForCashOut` / `useDataHookForPay` flags:** These flags control whether each hook participates in a given operation. For the **extra data hook**, the flags are stored per-ruleset in the `JBDeployerHookConfig` struct -- if the flag is `false`, that hook is skipped entirely and the original values are returned unchanged for that hook's portion. The **721 hook** behaves differently: it is **always** called during `beforePayRecordedWith` when its address is non-zero (no `useDataHookForPay` check), but for `beforeCashOutRecordedWith` it respects the `useDataHookForCashOut` flag stored in `JBTiered721HookConfig`.
+
+**Write-once storage:** Both `_tiered721HookOf` and `_extraDataHookOf` mappings are written once during `_setup721()` and never updated. New rulesets can reference different hooks, but existing ruleset-to-hook mappings are permanent.
+
 ## Immutable Configuration
 
 These values are set at deployment and cannot be changed:

package/ARCHITECTURE.md

@@ -18,6 +18,16 @@ src/
     └── JBSuckerDeploymentConfig.sol  — Sucker deployment parameters
 ```
 
+## Hook Storage Mappings
+
+The deployer maintains two internal mappings, both keyed by `(projectId, rulesetId)`:
+
+- **`_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.
+
+- **`_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`.
+
+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.
+
 ## Key Data Flows
 
 ### Omnichain Project Deployment
@@ -38,7 +48,7 @@ Payment → JBOmnichainDeployer.beforePayRecordedWith()
   → If 721 hook returned specs: include in merged output
   → Calls custom hook from _extraDataHookOf (if useDataHookForPay=true)
   → Custom hook receives reduced amount (payment - splitAmount)
-  → Adjusts weight proportionally for splits
+  → Uses 721 hook's split-adjusted weight directly
   → Merges both hook specs (721 first if any, then custom)
 
 Cash Out → JBOmnichainDeployer.beforeCashOutRecordedWith()
@@ -76,6 +86,18 @@ Owner → JBOmnichainDeployer.launchRulesetsFor()
 | Sucker registry | `IJBSuckerRegistry` | Sucker deployment and discovery |
 | 721 hook deployer | `IJB721TiersHookDeployer` | 721 tiers hook deployment (always used) |
 
+## Design Decisions
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
 ## Dependencies
 - `@bananapus/core-v6` — Core protocol (controller, directory, permissions)
 - `@bananapus/721-hook-v6` — NFT tier deployment
@@ -83,4 +105,3 @@ Owner → JBOmnichainDeployer.launchRulesetsFor()
 - `@bananapus/permission-ids-v6` — Permission constants
 - `@bananapus/suckers-v6` — Cross-chain sucker registry
 - `@openzeppelin/contracts` — ERC2771, ERC721Receiver
-- `@prb/math` — Fixed-point math (`mulDiv` for weight scaling)

package/AUDIT_INSTRUCTIONS.md

@@ -1,21 +1,39 @@
 # nana-omnichain-deployers-v6 -- Audit Instructions
 
+## Previous Audit Findings
+
+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).
+
+## 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`) |
+
 ## Scope
 
-One contract, 816 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.
+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` | 816 | Main contract. Deploys projects, queues rulesets, proxies data hook calls. Implements `IJBRulesetDataHook`, `IERC721Receiver`, `JBPermissioned`, `ERC2771Context`. |
+| `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,036 lines.
+**Total source**: ~1,092 lines.
 
 ## External Dependencies
 
@@ -111,7 +129,7 @@ function launchRulesetsFor(
 ) external returns (uint256 rulesetId, IJB721TiersHook hook)
 ```
 
-**Permission checks**: Requires both `QUEUE_RULESETS` and `SET_TERMINALS` from project owner.
+**Permission checks**: Requires both `LAUNCH_RULESETS` and `SET_TERMINALS` from project owner.
 
 **Controller validation**: `_validateController(projectId, controller)` checks `controller.DIRECTORY().controllerOf(projectId) == controller`.
 
@@ -252,7 +270,6 @@ For each ruleset config at index `i`:
 | `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_UnexpectedNFT` | **Declared but never used** (dead code). | N/A |
 | `JBOmnichainDeployer_UnexpectedNFTReceived` | `onERC721Received` called by non-`PROJECTS` contract | `onERC721Received` |
 
 ## Priority Audit Areas
@@ -311,7 +328,7 @@ For each ruleset config at index `i`:
 
 ## Test Suite Overview
 
-15 test files, ~2,500 lines of test code:
+14 test files, ~5,000 lines of test code:
 
 | Category | Files | Coverage |
 |----------|-------|----------|
@@ -324,7 +341,7 @@ For each ruleset config at index `i`:
 | 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` (4 files) | Real V4 PoolManager + buyback hook integration, 721 queue-and-adjust, cashout fork, stress, weight fork |
+| 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 |
 
 ## Testing Setup
 
@@ -342,7 +359,28 @@ RPC_ETHEREUM_MAINNET=<your_rpc> forge test --match-path 'test/fork/*.t.sol' -vvv
 RPC_ETHEREUM_MAINNET=<your_rpc> forge test --match-contract OmnichainDeployerInvariant -vvv
 
 # Compiler settings
-# Solidity 0.8.26, EVM version: cancun, via_ir: true, optimizer: 200 runs
+# Solidity 0.8.28, EVM version: cancun, via_ir: true, optimizer: 200 runs
 ```
 
 Foundry config is at `foundry.toml`. Fuzz runs: 4096. Invariant runs: 1024, depth: 100, `fail_on_revert: false`.
+
+## How to Report Findings
+
+Each finding should follow this 7-point structure:
+
+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.
+
+### Severity Guide
+
+| 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. |

package/CHANGE_LOG.md

@@ -2,6 +2,14 @@
 
 This document describes all changes between `nana-omnichain-deployers` (v5) and `nana-omnichain-deployers-v6` (v6).
 
+## Summary
+
+- **Every project gets a 721 hook**: All projects launched through the omnichain deployer now receive a 721 hook (even without tiers), unifying the deployment model.
+- **Dual-hook architecture**: Separate tracking of 721 hooks (`_tiered721HookOf`) and extra data hooks (`_extraDataHookOf`) enables composing both in `beforePayRecordedWith` with proportional weight scaling.
+- **v5 ownership bug fixed**: `queue721RulesetsOf` in v5 deployed 721 hooks but never transferred ownership to the project — v6 properly calls `transferOwnershipToProject` on all paths.
+- **Function consolidation**: `launch721ProjectFor`, `launch721RulesetsFor`, and `queue721RulesetsOf` merged into overloads of their non-721 counterparts using `JBOmnichain721Config`.
+- **New safety checks**: Controller validation, ruleset ID collision protection, and explicit reverts replace `assert()`.
+
 ---
 
 ## 1. Breaking Changes
@@ -51,6 +59,8 @@ Both v6 overloads now return `IJB721TiersHook hook` alongside `rulesetId`.
 
 v6 also fixes v5's `queue721RulesetsOf` which deployed the 721 hook but never called `JBOwnable(hook).transferOwnershipToProject(projectId)`, leaving the hook owned by the deployer contract rather than the project. In v6, all paths that deploy a 721 hook — including `_queueRulesetsOf` — properly transfer hook ownership to the project.
 
+> **⚠️ This was a v5 bug**: Any project that used v5's `queue721RulesetsOf` to deploy a 721 hook has that hook owned by the deployer contract, not the project. Projects affected should manually transfer hook ownership.
+
 ### 1.6 `queue721RulesetsOf` removed
 
 Replaced by the `queueRulesetsOf(... JBOmnichain721Config ...)` overload described above.
@@ -73,7 +83,7 @@ The `dataHook` field moved from last to first. This changes ABI encoding and is
 ### 1.9 Solidity version bumped
 
 **v5**: `pragma solidity 0.8.23`
-**v6**: `pragma solidity 0.8.26`
+**v6**: `pragma solidity 0.8.28`
 
 ### 1.10 721 hook config types replaced
 
@@ -311,3 +321,5 @@ v6: `if (msg.sender != address(PROJECTS)) revert JBOmnichainDeployer_UnexpectedN
 | `queue721RulesetsOf(projectId, deployTiersHookConfig, queueRulesetsConfig, controller, salt)` | `queueRulesetsOf(projectId, deploy721Config, rulesetConfigs, memo, controller)` | 721 config bundled into `JBOmnichain721Config`. Standard `JBRulesetConfig[]` replaces `JBQueueRulesetsConfig`. |
 | `dataHookOf(projectId, rulesetId)` | `extraDataHookOf(projectId, rulesetId)` + `tiered721HookOf(projectId, rulesetId)` | Split into two views. `extraDataHookOf` returns `JBDeployerHookConfig memory`. `tiered721HookOf` returns `(IJB721TiersHook, bool)`. |
 | `deploySuckersFor(projectId, suckerConfig)` | `deploySuckersFor(projectId, suckerConfig)` | Unchanged. |
+
+> **Cross-repo impact**: Uses `LAUNCH_RULESETS` from `nana-permission-ids-v6` (split from `QUEUE_RULESETS`). The dual-hook composition pattern in `beforePayRecordedWith` uses `mulDiv` from `@prb/math` to scale weight proportionally — `revnet-core-v6` implements a similar pattern for its buyback hook + 721 hook composition.

package/README.md

@@ -11,7 +11,7 @@ Launching a cross-chain Juicebox project normally takes several steps: deploy th
 It works by inserting itself as the data hook on every ruleset it touches, storing hooks in two separate mappings: the 721 tiers hook is stored per-ruleset in `_tiered721HookOf[projectId][rulesetId]` with its own `useDataHookForCashOut` flag, and an optional custom data hook (e.g., buyback hook) is stored per-ruleset in `_extraDataHookOf[projectId][rulesetId]` with `useDataHookForPay` and `useDataHookForCashOut` flags. When the protocol calls data hook functions during payments and cash outs, the deployer:
 
 - **Checks if the holder is a sucker** -- if so, returns 0% cash out tax and grants mint permission. This early return means suckers can always bridge tokens without interference, even if the project's hooks would revert.
-- **Composes the 721 hook and custom data hook** for payments -- the 721 hook is called first (via `tiered721HookOf`) to get its specs (including split fund amounts), then the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) is called with a reduced amount context (payment minus split amount) so it only considers the available funds. The deployer adjusts the returned weight proportionally for splits, ensuring the terminal only mints tokens for the amount that actually enters the project treasury. If the 721 hook returns no specs (0 tiers), it is skipped in the merged output.
+- **Composes the 721 hook and custom data hook** for payments -- the 721 hook is called first (via `tiered721HookOf`) to get its specs (including split fund amounts), then the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) is called with a reduced amount context (payment minus split amount) so it only considers the available funds. The 721 hook's weight (already split-adjusted by `JB721TiersHookLib.calculateWeight`) is used directly, ensuring the terminal only mints tokens for the amount that actually enters the project treasury. If the 721 hook returns no specs (0 tiers), it is skipped in the merged output.
 - **Composes hooks for cash outs** -- the 721 hook is called first (if `useDataHookForCashOut: true`), updating the cash out parameters (tax rate, count, supply). Then the custom hook is called (if `useDataHookForCashOut: true`) with the already-updated values from the 721 hook. Both hooks' specifications are merged into a single array (721 specs first, then custom hook specs). If the 721 hook has `useDataHookForCashOut: true` and reverts (e.g., for fungible-only cashouts), that revert propagates. Set `useDataHookForCashOut: false` on the 721 config to skip it.
 - **Returns default values** if neither hook has the relevant flag set.
 
@@ -84,7 +84,7 @@ This means a project can have both a 721 hook (for NFT minting on payments) and
 
 ### Simplified Overloads
 
-Each of `launchProjectFor`, `launchRulesetsFor`, and `queueRulesetsOf` has a simplified overload that omits the `deploy721Config` parameter. These use `_default721Config(rulesetConfigurations)`, which creates an empty-tier 721 config with `currency` from the first ruleset's `baseCurrency`, `decimals = 18`, `useDataHookForCashOut = false`, and no salt. For `queueRulesetsOf`, since the default config has 0 tiers, the existing 721 hook is always carried forward.
+Each of `launchProjectFor`, `launchRulesetsFor`, and `queueRulesetsOf` has a simplified overload that omits the `deploy721Config` parameter. These use `_default721Config(rulesetConfigurations)`, which creates an empty-tier 721 config with `currency` from the first ruleset's `baseCurrency`, `decimals = 18`, `useDataHookForCashOut = false`, and no salt. At least one ruleset configuration is required. For `queueRulesetsOf`, since the default config has 0 tiers, the existing 721 hook is always carried forward.
 
 ### Deterministic Cross-Chain Addresses
 
@@ -99,6 +99,15 @@ This means:
 - Different senders can't collide, even with the same salt
 - `salt = bytes32(0)` skips sucker deployment entirely
 
+### Supported Chains
+
+`JBOmnichainDeployer` supports the same chains as the sucker deployers it wraps. Currently supported:
+
+- **Mainnets**: Ethereum, Optimism, Base, Arbitrum
+- **Testnets**: Ethereum Sepolia, Optimism Sepolia, Base Sepolia, Arbitrum Sepolia
+
+To deploy a cross-chain project, call `launchProjectFor` on each chain with the same salt. The sucker deployers use CREATE2 so that matching salts from the same sender produce deterministic addresses across chains.
+
 ### Ruleset ID Prediction
 
 The deployer stores hook configs keyed by predicted ruleset IDs (`block.timestamp + i`). This works because `JBRulesets` assigns IDs as `latestId >= block.timestamp ? latestId + 1 : block.timestamp`. For new projects, `latestId` starts at 0, so the first ID is always `block.timestamp`.
@@ -155,7 +164,8 @@ Add to `remappings.txt`:
 [profile.default]
 solc = '0.8.26'
 evm_version = 'cancun'
-optimizer_runs = 100000
+via_ir = true
+optimizer_runs = 200
 
 [fuzz]
 runs = 4096
@@ -165,28 +175,40 @@ runs = 4096
 
 ```
 src/
-  JBOmnichainDeployer.sol               # Main contract (~817 lines)
+  JBOmnichainDeployer.sol                       # Main contract (~817 lines)
   interfaces/
-    IJBOmnichainDeployer.sol            # Public interface
+    IJBOmnichainDeployer.sol                    # Public interface
   structs/
-    JBDeployerHookConfig.sol            # Custom hook config (dataHook + flags)
-    JBOmnichain721Config.sol            # 721 hook deployment config
-    JBTiered721HookConfig.sol           # Per-ruleset 721 hook config
-    JBSuckerDeploymentConfig.sol        # Sucker deployment params
+    JBDeployerHookConfig.sol                    # Custom hook config (dataHook + flags)
+    JBOmnichain721Config.sol                    # 721 hook deployment config
+    JBSuckerDeploymentConfig.sol                # Sucker deployment params
+    JBTiered721HookConfig.sol                   # Per-ruleset 721 hook config
 test/
-  JBOmnichainDeployer.t.sol             # Unit tests
-  JBOmnichainDeployerGuard.t.sol        # Ruleset ID prediction tests
-  OmnichainDeployerAttacks.t.sol        # Adversarial security tests
-  OmnichainDeployerEdgeCases.t.sol      # Edge case tests (weight, cashout, mint)
-  OmnichainDeployerReentrancy.t.sol     # Reentrancy tests
-  Tiered721HookComposition.t.sol        # 721 hook + custom hook composition tests
-  fork/                                 # Fork tests against mainnet
+  JBOmnichainDeployer.t.sol                     # Unit tests
+  JBOmnichainDeployerGuard.t.sol                # Ruleset ID prediction tests
+  OmnichainDeployerAttacks.t.sol                # Adversarial security tests
+  OmnichainDeployerEdgeCases.t.sol              # Edge case tests (weight, cashout, mint)
+  OmnichainDeployerReentrancy.t.sol             # Reentrancy tests
+  TestAuditGaps.sol                             # Audit gap coverage tests
+  Tiered721HookComposition.t.sol                # 721 hook + custom hook composition tests
+  fork/
+    OmnichainForkTestBase.sol                   # Shared fork test base
+    TestOmnichain721QueueAndAdjust.t.sol        # Fork: queue and adjust 721 tiers
+    TestOmnichainCashOutFork.t.sol              # Fork: cash out flows
+    TestOmnichainStressFork.t.sol               # Fork: stress / load tests
+    TestOmnichainWeightFork.t.sol               # Fork: weight decay tests
+    TestSuckerDeploymentFork.t.sol              # Fork: sucker deployment
+  invariants/
+    OmnichainDeployerInvariant.t.sol            # Invariant tests
+    handlers/
+      OmnichainDeployerHandler.sol              # Invariant handler
   regression/
-    HookOwnershipTransfer.t.sol         # Hook ownership transfer regression
+    HookOwnershipTransfer.t.sol                 # Hook ownership transfer regression
+    ValidateController.t.sol                    # Controller validation regression
 script/
-  Deploy.s.sol                          # Sphinx deployment script
+  Deploy.s.sol                                  # Sphinx deployment script
   helpers/
-    DeployersDeploymentLib.sol          # Deployment address helper
+    DeployersDeploymentLib.sol                  # Deployment address helper
 ```
 
 ## Permissions

package/RISKS.md

@@ -4,14 +4,14 @@
 
 - **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted to append the real sender. A compromised forwarder can impersonate any address for `deploySuckersFor`, `launchProjectFor`, `queueRulesetsOf`, and `launchRulesetsFor`.
 - **Sucker registry.** `SUCKER_REGISTRY.isSuckerOf()` is the sole gatekeeper for 0% cashout tax and mint permission. A compromised or malicious registry lets any address bypass cashout taxes and mint tokens freely.
-- **Controller trust.** The deployer passes an arbitrary `IJBController controller` parameter. `_validateController` checks `DIRECTORY.controllerOf(projectId)`, but during `launchProjectFor` the project does not yet exist -- validation is skipped, relying on the controller returning the correct project ID.
+- **Controller trust.** The deployer passes an arbitrary `IJBController controller` parameter. `_validateController` checks `controller.DIRECTORY().controllerOf(projectId)` (a reflexive lookup through the controller's own directory reference), but during `launchProjectFor` the project does not yet exist -- validation is skipped, relying on the controller returning the correct project ID.
 - **Extra data hooks.** Arbitrary `IJBRulesetDataHook` addresses from ruleset metadata are stored and delegated to with `staticcall`. A malicious hook can return arbitrary weight, cashout tax rate, or hook specifications.
 
 ## 2. Economic / Manipulation Risks
 
 - **Sucker cashout bypass.** Any address registered as a sucker for a project gets 0% cashout tax rate and full reclaim. If a malicious sucker is registered (via compromised `SUCKER_REGISTRY`), it can drain the project's surplus.
 - **Weight manipulation via extra data hook.** `beforePayRecordedWith` forwards to the extra data hook, which can return any `weight`. A malicious hook can inflate token minting or set weight=0 to block minting.
-- **721 hook amount splitting.** The deployer computes `projectAmount = context.amount.value - totalSplitAmount` and scales weight proportionally. If the 721 hook returns a `totalSplitAmount >= context.amount.value`, `projectAmount` is set to 0 and weight becomes 0 -- no tokens are minted for the payment.
+- **721 hook amount splitting.** The deployer computes `projectAmount = context.amount.value - totalSplitAmount`. The 721 hook's returned weight (already adjusted for splits via `JB721TiersHookLib.calculateWeight`) is used directly -- no proportional scaling is applied. If the 721 hook returns a `totalSplitAmount >= context.amount.value`, `projectAmount` is set to 0 and weight becomes 0 -- no tokens are minted for the payment.
 
 ## 3. Access Control
 
@@ -21,21 +21,40 @@
 
 ## 4. DoS Vectors
 
-- **Ruleset ID collision.** `_setup721` stores hook configs at `block.timestamp + i`. If `latestRulesetIdOf >= block.timestamp` (rulesets already queued this block), `queueRulesetsOf` reverts with `RulesetIdsUnpredictable`. An attacker who queues rulesets in the same block as the legitimate owner can front-run and block their queue attempt.
-- **External hook revert.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` call external hooks without try-catch. A reverting hook blocks all payments or cashouts for that project/ruleset. For cash-outs, if the 721 hook reverts, the custom hook is never reached (the revert propagates before it).
+- **Ruleset ID collision.** `_setup721` stores hook configs at `block.timestamp + i`. If `latestRulesetIdOf >= block.timestamp` (rulesets already queued this block), `queueRulesetsOf` reverts with `RulesetIdsUnpredictable`. An attacker who queues rulesets in the same block as the legitimate owner can front-run and block their queue attempt. Gas impact: `queueRulesetsOf` costs ~200-400k gas per ruleset queued. The collision only occurs when two transactions queue rulesets in the same block for the same project — race condition window is one block (~12 seconds on L1, 2 seconds on L2).
+- **External hook revert.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` call external hooks without try-catch. A reverting hook blocks all payments or cashouts for that project/ruleset. For cash-outs, if the 721 hook reverts, the custom hook is never reached (the revert propagates before it). Gas impact: the `staticcall` to the extra data hook has no gas limit — a gas-griefing hook can consume the entire transaction gas. The 721 hook call is similarly unbounded.
 - **721 hook deployment revert.** `HOOK_DEPLOYER.deployHookFor` is called without try-catch. A failing deployment blocks the entire project launch.
 
-## 5. Integration Risks
+## 5. Reentrancy Surface
+
+- **`launchProjectFor` external call chain.** The function makes external calls to: (1) `_deploy721Hook()` via `HOOK_DEPLOYER.deployHookFor()` (deploys 721 hook clone), (2) `controller.launchProjectFor()` (creates project, deploys rulesets), (3) `JBOwnable(hook).transferOwnershipToProject()` (transfers hook ownership to the new project), (4) `SUCKER_REGISTRY.deploySuckersFor()` (deploys suckers if configured), (5) `PROJECTS.transferFrom()` (transfers the project NFT to the owner). None of these calls are try-catch wrapped — a revert in any of them fails the entire launch. Reentrancy from the controller callback during project creation could call back into `launchProjectFor`, but the new project would get a different ID (monotonically incrementing), so state corruption is not possible.
+- **`beforePayRecordedWith` delegates to external hooks.** Calls `IJBRulesetDataHook(tiered721Hook).beforePayRecordedWith(context)` (not try-caught) and optionally delegates to the extra data hook via `staticcall`. The 721 hook call can execute arbitrary code. At callback time, no deployer state has been modified (the deployer is stateless during payments — it only routes). Reentrancy through the pay path processes as an independent payment.
+- **`beforeCashOutRecordedWith` delegates to external hooks.** Same pattern as pay: calls the 721 hook (not try-caught), then optionally the extra data hook. Sucker check via `SUCKER_REGISTRY.isSuckerOf` is a view call. No deployer state is modified during cashouts.
+- **No `ReentrancyGuard`.** Safe because the deployer is effectively stateless during pay/cashout operations — it reads `_tiered721HookOf` and `_extraDataHookOf` mappings but never writes them outside of deployment functions.
+
+## 6. Integration Risks
 
 - **Hook config keyed by predicted rulesetId.** Configs stored at `block.timestamp + i` must match the actual rulesetId assigned by the controller. If the controller assigns different IDs (e.g., due to approval hook delays), the stored configs become unreachable -- payments/cashouts fall through to default behavior (no 721 handling, no extra hook).
 - **Carried-forward 721 hook on queue.** When `tiers.length == 0`, `queueRulesetsOf` carries forward the hook from `_tiered721HookOf[projectId][latestRulesetId]`. If the latest ruleset was not deployed through this deployer, the mapping is empty and the call reverts with `JBOmnichainDeployer_InvalidHook`.
 - **ERC721Receiver restriction.** `onERC721Received` only accepts from `PROJECTS`. Any other NFTs sent to this contract are permanently lost.
+- **Cross-reference: sucker registration.** The deployer grants `MAP_SUCKER_TOKEN` to `SUCKER_REGISTRY` with `projectId=0` (wildcard). This means the registry can map tokens for ALL projects deployed through this deployer. See [nana-suckers-v6 RISKS.md](../nana-suckers-v6/RISKS.md) for the full sucker lifecycle risks.
+- **Cross-reference: core reentrancy.** The deployer delegates to `JBController` and `JBMultiTerminal` for all fund operations. See [nana-core-v6 RISKS.md](../nana-core-v6/RISKS.md) section 3 for the reentrancy surface of these contracts.
 
-## 6. Invariants to Verify
+## 7. Invariants to Verify
 
 - For any project launched through this deployer, `DIRECTORY.controllerOf(projectId)` matches the controller used during launch.
 - `_tiered721HookOf[projectId][rulesetId]` is non-zero for every rulesetId created through this deployer.
 - Sucker cashouts always receive 0% tax rate (no path where `isSuckerOf` returns true but tax > 0).
-- `beforePayRecordedWith` weight scaling: `weight * projectAmount / context.amount.value` never exceeds the original hook-returned weight.
+- `beforePayRecordedWith` uses the 721 hook's weight directly (already split-adjusted by `JB721TiersHookLib.calculateWeight`), so no additional scaling is applied.
 - Self-reference prevention: `rulesetConfigurations[i].metadata.dataHook` cannot be `address(this)` after `_setup721`.
 - Project NFT ownership: after `_launchProjectFor`, the project NFT is owned by `owner`, not the deployer.
+
+## 8. Accepted Behaviors
+
+### 8.1 Controller validation skipped during `launchProjectFor` (by design)
+
+`_validateController` checks `controller.DIRECTORY().controllerOf(projectId)` to verify the provided controller matches the project's registered controller. During `launchProjectFor`, the project does not yet exist, so no directory entry exists. Validation is skipped, relying on `controller.launchProjectFor()` to return the correct project ID. This is accepted because: (1) the project is created atomically within the same transaction, (2) the caller provides the controller address, so they choose their own trust boundary, and (3) validating against a non-existent project would always fail, making the check useless.
+
+### 8.2 Suckers receive 0% cashout tax (shared with revnet-core)
+
+`beforeCashOutRecordedWith` returns `cashOutTaxRate = 0` for addresses registered in `SUCKER_REGISTRY`. This is the same trust model as REVDeployer. The security boundary is the sucker registry — only addresses deployed through authorized deployers receive this privilege. See [revnet-core-v6 RISKS.md](../revnet-core-v6/RISKS.md) section 4 for the full sucker bypass analysis.

package/SKILLS.md

@@ -29,7 +29,7 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 | Function | What it does |
 |----------|-------------|
 | `beforePayRecordedWith(context)` | Calls the 721 hook first (via `_tiered721HookOf`) for its specs (including split amounts), then calls the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) with a reduced amount context (payment minus split amount) for weight + specs. Adjusts the returned weight proportionally so the terminal only mints tokens for the amount entering the project (`weight = mulDiv(weight, amount - splitAmount, amount)`). Merges specs (721 hook specs first if any, then custom hook specs). If the 721 hook returns no specs (0 tiers), its slot is omitted from the output. |
-| `beforeCashOutRecordedWith(context)` | If holder is a sucker: returns 0% tax immediately. Calls the 721 hook first (if `useDataHookForCashOut: true`), updating cash out parameters. Then calls the custom hook from `_extraDataHookOf` (if `useDataHookForCashOut: true`) with the already-updated values. Both hooks' specifications are merged (721 specs first, then custom hook specs). If the 721 hook has the flag set and reverts (e.g., fungible cashout), the revert propagates. If neither has the flag set, returns original values. |
+| `beforeCashOutRecordedWith(context)` | If holder is a sucker: returns 0% tax immediately. Calls the 721 hook first (if `useDataHookForCashOut: true`), updating cash out parameters. Then calls the custom hook from `_extraDataHookOf` (if `useDataHookForCashOut: true`) with the already-updated values. Both hooks' specifications are merged (721 specs first, then custom hook specs). If the 721 hook has the flag set and reverts (e.g., fungible cashout), the revert propagates. If neither has the flag set, returns original values. Hook specifications include a `noop` field — the 721 hook always returns `noop: false` (it needs its callback), while a custom hook like the buyback hook may return `noop: true` with routing diagnostics when the protocol path wins. |
 | `hasMintPermissionFor(projectId, ruleset, addr)` | Returns `true` for registered suckers, OR if the custom hook in `_extraDataHookOf` grants permission. Returns `false` only if it doesn't grant it. |
 
 ### Views
@@ -82,30 +82,54 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 | `JBOmnichainDeployer_ProjectIdMismatch` | `launchProjectFor` -- the project ID returned by the controller does not match the predicted `PROJECTS.count() + 1` |
 | `JBOmnichainDeployer_ControllerMismatch` | `launchRulesetsFor`/`queueRulesetsOf` -- the provided controller does not match the project's controller in `JBDirectory` |
 
+## Events
+
+`JBOmnichainDeployer` does not declare any custom events. All observable state changes (project creation, ruleset queuing, sucker deployment) are emitted by the underlying contracts it calls (`IJBController`, `IJBSuckerRegistry`, `IJB721TiersHookDeployer`).
+
+## Constants
+
+| Name | Value | Context |
+|------|-------|---------|
+| `PROJECTS` | Set at construction | `IJBProjects` -- mints project NFTs. Immutable. |
+| `HOOK_DEPLOYER` | Set at construction | `IJB721TiersHookDeployer` -- deploys 721 tiers hooks. Immutable. |
+| `SUCKER_REGISTRY` | Set at construction | `IJBSuckerRegistry` -- deploys/tracks suckers, `isSuckerOf` checks. Immutable. |
+| `projectId = 0` (wildcard) | Used in constructor | `MAP_SUCKER_TOKEN` permission granted to `SUCKER_REGISTRY` with `projectId=0`, giving it token mapping rights for all projects. |
+| `decimals = 18` | Used in `_default721Config` | Default decimal precision when 721 config is omitted (simplified overloads). |
+| `baseCurrency` | From first ruleset | When 721 config is omitted, `baseCurrency` is read from `rulesetConfigurations[0].metadata.baseCurrency`. Reverts with `JBOmnichainDeployer_NoRulesetConfigurations` if the array is empty. |
+
 ## Gotchas
 
-1. `launchProjectFor` requires **no permissions** -- anyone can launch a project to any owner address.
-2. `queueRulesetsOf` **reverts if called in the same block** as a previous ruleset queue (whether via deployer or directly). The `launchProjectFor` function doesn't have this guard because it predicts IDs from `PROJECTS.count()`, which is always 0 for a new project.
-3. Ruleset IDs in `_extraDataHookOf` are keyed by `block.timestamp + i`. If the controller assigns different IDs than predicted, the stored hook configs will be orphaned and the deployer will behave as if no hooks were set (returning default values).
-4. Sucker deployment salts are hashed with `_msgSender()`: `keccak256(abi.encode(salt, _msgSender()))`. Cross-chain deterministic addresses require using the **same sender** on each chain. The 721 hook salt uses `keccak256(abi.encode(_msgSender(), salt))` (reversed order).
-5. `salt = bytes32(0)` **skips sucker deployment entirely**. Use a nonzero salt to deploy suckers.
-6. The deployer **always forces `useDataHookForCashOut = true`** at the protocol level so it can intercept cash outs for sucker tax exemption. However, the 721 hook's `useDataHookForCashOut` flag (stored in `_tiered721HookOf`) and the custom hook's flag (stored in `_extraDataHookOf`) each control whether that hook processes cash outs. Set `useDataHookForCashOut: false` on the 721 config to skip it for fungible cashouts (it reverts with `JB721Hook_UnexpectedTokenCashedOut` otherwise).
-7. Suckers get an **early return** in `beforeCashOutRecordedWith` -- they bypass all stored hooks entirely. This means suckers can cash out even if any hook would revert.
-8. If no custom hook is stored or it doesn't grant permission, `hasMintPermissionFor` returns `false` for non-suckers. Only the custom hook in `_extraDataHookOf` is checked — the 721 hook is not consulted.
-9. `_setup721()` sets `metadata.dataHook = address(this)`, `metadata.useDataHookForPay = true`, and `metadata.useDataHookForCashOut = true` on every ruleset. These cannot be overridden.
-10. Hook ownership is transferred to the **project** (not the owner) via `JBOwnable.transferOwnershipToProject(projectId)`. This happens **after** the project NFT is minted — in `launchProjectFor`, the hook is deployed before `controller.launchProjectFor`, and ownership is transferred after the project exists.
-11. The deployer holds the project NFT temporarily during launch. If the controller's `launchProjectFor` reverts, the entire transaction reverts -- no stuck NFTs.
-12. The constructor grants `MAP_SUCKER_TOKEN` permission to `SUCKER_REGISTRY` with `projectId=0`, meaning the registry can map tokens for **any project** deployed through this deployer.
-13. All data hook functions (`beforePayRecordedWith`, `beforeCashOutRecordedWith`, `hasMintPermissionFor`) are `view`. If the project's real hook needs to modify state in these functions, it will fail.
-14. Setting a hook's `dataHook` to `address(this)` (the deployer itself) reverts with `JBOmnichainDeployer_InvalidHook` in `_setup721()`. This prevents infinite forwarding loops.
-15. `onERC721Received` only accepts NFTs from the `PROJECTS` contract. Sending any other ERC-721 to the deployer will revert.
-16. ERC2771 meta-transaction support allows gasless deployments via a trusted forwarder. Salt hashing uses `_msgSender()` (not `msg.sender`), so forwarder-relayed transactions use the original sender's address for deterministic sucker addresses.
-17. Every project always gets a 721 hook, even with an empty tiers array. This wires up the 721 hook from the start, so the project owner can add and sell NFTs later without needing to reconfigure the data hook in a new ruleset.
-18. The 721 hook is stored per-ruleset in `_tiered721HookOf[projectId][rulesetId]` with its `useDataHookForCashOut` flag. The custom data hook (if any) is stored separately in `_extraDataHookOf[projectId][rulesetId]`. They are never in the same array.
-19. For payments, `beforePayRecordedWith` calls the 721 hook first (via `_tiered721HookOf`) to get its specs (including split fund amounts and tier metadata), then calls the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) with a reduced amount context (payment minus split amount) so the buyback hook only considers the available amount. The deployer then adjusts the weight proportionally for splits (`weight = mulDiv(weight, amount - splitAmount, amount)`). The 721 hook's specs come first in the merged result, but only if the hook returned specs (0-tier hooks produce no specs).
-20. For cash outs, `beforeCashOutRecordedWith` calls the 721 hook first (from `_tiered721HookOf`, if `useDataHookForCashOut: true`), updating the cash out parameters (tax rate, count, supply). Then calls the custom hook (from `_extraDataHookOf`, if `useDataHookForCashOut: true`) with the already-updated values from the 721 hook. Both hooks' specifications are merged (721 specs first, then custom hook specs). If the 721 hook has the flag set and reverts (e.g., `JB721Hook_UnexpectedTokenCashedOut` for fungible cashouts), the revert propagates. Set `useDataHookForCashOut: false` on the 721 config to skip it.
-21. The `JBOmnichain721Config` parameter bundles the 721 hook deployment config (`deployTiersHookConfig`), the `useDataHookForCashOut` flag, and the `salt`. Custom data hooks are read from each ruleset's `metadata.dataHook` field.
-22. For `queueRulesetsOf`, if no new tiers are provided (`deploy721Config.deployTiersHookConfig.tiersConfig.tiers.length == 0`), the 721 hook from the **latest ruleset** is carried forward instead of deploying a new one. This is looked up from `_tiered721HookOf[projectId][latestRulesetId]`.
+### Deployment
+
+- `launchProjectFor` requires **no permissions** -- anyone can launch a project to any owner address.
+- `queueRulesetsOf` **reverts if called in the same block** as a previous ruleset queue (whether via deployer or directly). The `launchProjectFor` function doesn't have this guard because it predicts IDs from `PROJECTS.count()`, which is always 0 for a new project.
+- Ruleset IDs in `_extraDataHookOf` are keyed by `block.timestamp + i`. If the controller assigns different IDs than predicted, the stored hook configs will be orphaned and the deployer will behave as if no hooks were set (returning default values).
+- Sucker deployment salts are hashed with `_msgSender()`: `keccak256(abi.encode(salt, _msgSender()))`. Cross-chain deterministic addresses require using the **same sender** on each chain. The 721 hook salt uses `keccak256(abi.encode(_msgSender(), salt))` (reversed order).
+- `salt = bytes32(0)` **skips sucker deployment entirely**. Use a nonzero salt to deploy suckers.
+- Hook ownership is transferred to the **project** (not the owner) via `JBOwnable.transferOwnershipToProject(projectId)`. This happens **after** the project NFT is minted.
+- The deployer holds the project NFT temporarily during launch. If the controller's `launchProjectFor` reverts, the entire transaction reverts -- no stuck NFTs.
+- Every project always gets a 721 hook, even with an empty tiers array. This wires up the 721 hook from the start, so tiers can be added later without reconfiguring the data hook.
+- For `queueRulesetsOf`, if no new tiers are provided, the 721 hook from the **latest ruleset** is carried forward instead of deploying a new one. Looked up from `_tiered721HookOf[projectId][latestRulesetId]`.
+
+### Data Hook Behavior
+
+- The deployer **always forces `useDataHookForCashOut = true`** at the protocol level so it can intercept cash outs for sucker tax exemption. However, the 721 hook's `useDataHookForCashOut` flag (stored in `_tiered721HookOf`) and the custom hook's flag (stored in `_extraDataHookOf`) each control whether that hook processes cash outs. Set `useDataHookForCashOut: false` on the 721 config to skip it for fungible cashouts (it reverts with `JB721Hook_UnexpectedTokenCashedOut` otherwise).
+- Suckers get an **early return** in `beforeCashOutRecordedWith` -- they bypass all stored hooks entirely. Suckers can cash out even if any hook would revert.
+- If no custom hook is stored or it doesn't grant permission, `hasMintPermissionFor` returns `false` for non-suckers. Only the custom hook in `_extraDataHookOf` is checked -- the 721 hook is not consulted.
+- `_setup721()` sets `metadata.dataHook = address(this)`, `metadata.useDataHookForPay = true`, and `metadata.useDataHookForCashOut = true` on every ruleset. These cannot be overridden.
+- All data hook functions (`beforePayRecordedWith`, `beforeCashOutRecordedWith`, `hasMintPermissionFor`) are `view`. If the project's real hook needs to modify state in these functions, it will fail.
+- Setting a hook's `dataHook` to `address(this)` (the deployer itself) reverts with `JBOmnichainDeployer_InvalidHook`. This prevents infinite forwarding loops.
+- The 721 hook is stored per-ruleset in `_tiered721HookOf[projectId][rulesetId]` with its `useDataHookForCashOut` flag. The custom data hook (if any) is stored separately in `_extraDataHookOf[projectId][rulesetId]`. They are never in the same mapping.
+- The `JBOmnichain721Config` parameter bundles the 721 hook deployment config, the `useDataHookForCashOut` flag, and the `salt`. Custom data hooks are read from each ruleset's `metadata.dataHook` field.
+
+### Permissions
+
+- The constructor grants `MAP_SUCKER_TOKEN` permission to `SUCKER_REGISTRY` with `projectId=0`, meaning the registry can map tokens for **any project** deployed through this deployer.
+
+### Edge Cases
+
+- `onERC721Received` only accepts NFTs from the `PROJECTS` contract. Sending any other ERC-721 to the deployer will revert.
+- ERC2771 meta-transaction support allows gasless deployments via a trusted forwarder. Salt hashing uses `_msgSender()` (not `msg.sender`), so forwarder-relayed transactions use the original sender's address for deterministic sucker addresses.
 
 ## Example Integration
 
@@ -172,3 +196,58 @@ JBOmnichain721Config memory queue721Config = JBOmnichain721Config({
     controller: controller
 });
 ```
+
+## Buyback Hook + 721 Hook Composition
+
+The most complex use case: a project with NFT tiers (721 hook) AND a buyback hook, both running on every payment. The deployer composes them automatically.
+
+```solidity
+import {IJBBuybackHook} from "@bananapus/buyback-hook-v6/src/interfaces/IJBBuybackHook.sol";
+import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadata.sol";
+
+// --- Key concept: the buyback hook goes in metadata.dataHook ---
+// The deployer extracts it, stores it in _extraDataHookOf, and replaces
+// metadata.dataHook with address(this) so it can intercept all calls.
+
+// 1. Configure the buyback hook as the ruleset's custom data hook.
+JBRulesetConfig[] memory rulesetConfigs = new JBRulesetConfig[](1);
+rulesetConfigs[0].metadata = JBRulesetMetadata({
+    // ... other metadata fields ...
+    dataHook: address(buybackHook),   // <-- deployer extracts this
+    useDataHookForPay: true,          // buyback hook processes payments
+    useDataHookForCashOut: false      // buyback hook does NOT process cashouts
+    // ...
+});
+
+// 2. Configure the 721 hook with NFT tiers.
+JBOmnichain721Config memory deploy721Config = JBOmnichain721Config({
+    deployTiersHookConfig: tiersHookConfig,  // your NFT tier config
+    useDataHookForCashOut: false,            // false = skip 721 on fungible cashouts
+    salt: bytes32("my-hook-salt")
+});
+
+// 3. Launch -- both hooks are wired up automatically.
+(uint256 projectId, IJB721TiersHook hook, address[] memory suckers) =
+    omnichainDeployer.launchProjectFor({
+        owner: msg.sender,
+        projectUri: "ipfs://metadata",
+        deploy721Config: deploy721Config,
+        rulesetConfigurations: rulesetConfigs,
+        terminalConfigurations: terminalConfigs,
+        memo: "Buyback + 721 project",
+        suckerDeploymentConfiguration: suckerConfig,
+        controller: controller
+    });
+
+// --- What happens on each payment: ---
+// 1. beforePayRecordedWith calls the 721 hook first (tier matching, NFT minting specs)
+// 2. Reduces the payment amount by the 721 split amount
+// 3. Calls the buyback hook with the reduced amount (so it only buys back with leftover)
+// 4. Adjusts weight proportionally: weight = mulDiv(weight, amount - splitAmount, amount)
+// 5. Merges specs: 721 specs first, then buyback specs
+//
+// --- What happens on cashout: ---
+// With useDataHookForCashOut: false on both hooks:
+//   - Suckers still get 0% tax (the deployer intercepts before any hook)
+//   - Regular users get standard bonding curve cashout (no hook interference)
+```