@bananapus/omnichain-deployers-v6 0.0.27 → 0.0.29

package/ADMINISTRATION.md

@@ -4,75 +4,26 @@
 
 | Item | Details |
 | --- | --- |
-| Scope | Omnichain project launch, ruleset queuing, runtime wrapper config, and sucker deployment integration |
-| Control posture | Mixed deployer/wrapper control plus project-local delegated authority |
-| Highest-risk actions | Queuing rulesets with bad wrapper config, launching with the wrong controller assumptions, and misconfigured sucker deployment |
-| Recovery posture | Some config can be superseded with new rulesets; wrong immutable dependencies require replacement infra |
+| Scope | Omnichain launch orchestration and wrapper behavior |
+| Control posture | Mixed deployer logic, project permissions, and registry trust |
+| Highest-risk actions | Wrong hook composition, wrong sucker wiring, and bad registry trust |
+| Recovery posture | Often requires redeploying or re-launching around bad wiring |
 
 ## Purpose
 
-`nana-omnichain-deployers-v6` combines deployment authority with runtime wrapper authority. The critical admin question is not just who can launch or queue rulesets, but also who controls the wrapped hook composition and registered sucker behavior afterward.
+This repo controls how omnichain projects are launched and wrapped, not the low-level runtime logic of suckers or 721 hooks.
 
 ## Control Model
 
-- `JBOmnichainDeployer` is both deployer and live data-hook wrapper.
-- Project-local authority flows through project ownership and `JBPermissions`.
-- `SUCKER_REGISTRY` holds structural `MAP_SUCKER_TOKEN` authority granted to the deployer.
-- Sucker deployment requires project-local `DEPLOY_SUCKERS` permission.
-- Hook composition data is stored by ruleset and then used at runtime.
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Project owner | `JBProjects.ownerOf(projectId)` | Per project | Can delegate through `JBPermissions` |
-| Project operator | `JBPermissions` grant | Per project | Often `DEPLOY_SUCKERS`, `QUEUE_RULESETS`, `LAUNCH_RULESETS`, `SET_TERMINALS` |
-| `JBOmnichainDeployer` | Immutable singleton | Global | Launch helper and runtime wrapper |
-| `SUCKER_REGISTRY` | Immutable dependency | Global | Receives wildcard `MAP_SUCKER_TOKEN` from the deployer |
-
-## Privileged Surfaces
-
-| Contract | Function | Who Can Call | Effect |
-| --- | --- | --- | --- |
-| `JBOmnichainDeployer` | `deploySuckersFor(...)` | Project owner or `DEPLOY_SUCKERS` delegate | Extends an existing project with suckers |
-| `JBOmnichainDeployer` | `launchProjectFor(...)` | Anyone | Launches a new omnichain-shaped project |
-| `JBOmnichainDeployer` | `launchRulesetsFor(...)` | Project owner or relevant delegates | Launches rulesets for an existing project |
-| `JBOmnichainDeployer` | `queueRulesetsOf(...)` | Project owner or `QUEUE_RULESETS` delegate | Queues rulesets and stores runtime wrapper config |
-
-## Immutable And One-Way
-
-- Constructor dependencies are immutable.
-- Ruleset-keyed hook configuration becomes the runtime source of truth once stored.
-- Deterministic sucker deployment assumptions depend on stable salts and deployer config.
-- The deployer's wildcard grant to `SUCKER_REGISTRY` is structural.
-
-## Operational Notes
-
-- Review launch and runtime-wrapper behavior together for every admin change.
-- Validate controller matching on existing-project flows before launch or queue operations.
-- Treat hook-order changes as runtime behavior changes, not just deployment metadata changes.
-- Arrange token-mapping authority for the registry before using the end-to-end sucker deployment path.
-
-## Machine Notes
-
-- Do not treat this repo as deployment-only; queued wrapper config is a live runtime input.
-- Inspect `src/JBOmnichainDeployer.sol` alongside project rulesets before assuming current behavior.
-- If directory/controller state and stored wrapper config diverge, stop and resolve the mismatch before further admin actions.
+- launch paths are largely permissionless for new projects
+- later ruleset changes depend on project permissions
+- registry and sucker trust surfaces can widen authority if misconfigured
 
 ## Recovery
 
-- If a ruleset was queued with bad wrapper config, recover through new rulesets if the project still has the necessary authority.
-- If the wrong deterministic deployment assumptions or constructor dependencies were used, recover with replacement infra.
+- bad launch wiring usually means a new deployment path rather than a local patch
 
 ## Admin Boundaries
 
-- The deployer cannot bypass project-local permission checks on existing-project launch, queue, or sucker deployment paths.
-- It cannot mutate constructor immutables after deployment.
-- It does not own core treasury accounting or project ownership semantics outside the flows it wraps.
-
-## Source Map
+- this repo does not override locked runtime behavior in sibling repos
 
-- `src/JBOmnichainDeployer.sol`
-- `src/interfaces/IJBOmnichainDeployer.sol`
-- `src/structs/`
-- `test/`

package/ARCHITECTURE.md

@@ -2,109 +2,30 @@
 
 ## Purpose
 
-`nana-omnichain-deployers-v6` launches Juicebox projects that are ready for both tiered NFTs and cross-chain suckers from day one. It is also a live wrapper data hook that composes a 721 hook with an optional extra hook while giving registered suckers the bridge-safe path they need.
+`nana-omnichain-deployers-v6` packages a Juicebox project, a 721 hook, and sucker deployment into one omnichain launch surface.
 
 ## System Overview
 
-`JBOmnichainDeployer` is both deployer and runtime wrapper; those roles are inseparable. At launch time it can deploy a project, install itself as the ruleset data hook, deploy or carry forward the 721 hook, and optionally deploy sucker pairs with deterministic salts. At runtime it composes hook specs and grants special behavior to registered suckers so bridging does not get trapped behind project-specific cash-out policy.
+`JBOmnichainDeployer` launches the project, stores per-ruleset hook composition, and wraps sucker behavior so bridge-triggered flows can bypass project-specific logic where intended.
 
 ## Core Invariants
 
-- Registered suckers must be able to bridge without getting blocked by custom cash-out or mint policy.
-- Hook order is intentional: the 721 hook runs first, then the optional extra hook.
-- Ruleset ID prediction must stay aligned with `JBRulesets`; stored hook config keys depend on it.
-- Every project launched through this repo gets a 721-hook surface, even if it starts with zero tiers.
-- This wrapper always becomes the on-chain ruleset data hook and forces both pay and cash-out callbacks through itself before delegating internally.
-- Extra pay hooks must see only the post-721 project amount and the 721-adjusted weight, not the raw terminal payment context.
-- Queue-path carry-forward must prefer the latest approved queued ruleset over the current active ruleset when recovering hook config.
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `JBOmnichainDeployer` | Launch, queue rulesets, compose hooks, and grant sucker-safe behavior | Deployer and runtime wrapper |
-| config structs | 721 config, extra hook config, and sucker deployment config | Launch-time inputs |
-| `IJBOmnichainDeployer` | External launch and inspection interface | Public surface |
+- launch wiring must match the intended omnichain project shape
+- hook composition must stay consistent with the created ruleset IDs
+- sucker-specific privileged paths must remain limited to trusted suckers
+- project NFT ownership and hook ownership must end in the intended place
 
 ## Trust Boundaries
 
-- Accounting and project ownership transfer remain rooted in `nana-core-v6`.
-- Tier behavior comes from `nana-721-hook-v6`.
-- Cross-chain transport comes from `nana-suckers-v6`.
-- Project-following ownership behavior comes from `nana-ownable-v6`.
-
-## Critical Flows
-
-### Launch
-
-```text
-caller
-  -> launches a project or queues rulesets through the deployer
-  -> deployer installs itself as the ruleset data hook
-  -> deploys or carries forward the 721 hook
-  -> optionally deploys sucker pairs with deterministic salts
-  -> transfers project ownership to the intended owner
-```
-
-### Queue With Carry-Forward
-
-```text
-caller
-  -> queues a new ruleset without new tiers
-  -> deployer selects carry-forward hook config from the latest approved queued ruleset when present
-  -> otherwise falls back to the current active ruleset
-  -> preserves useDataHookForCashOut from the chosen source ruleset
-```
-
-### Runtime Wrapping
-
-```text
-runtime callback
-  -> if the actor is a registered sucker, return the bridge-safe tax-free and mint-enabled path
-  -> otherwise run the 721 hook first when configured
-  -> pass the extra pay hook only the post-split project amount and 721-adjusted weight
-  -> then run the optional extra hook
-  -> merge and return the resulting specs
-```
-
-## Accounting Model
-
-This repo does not own the treasury ledger. Its critical state is hook configuration and ruleset-keyed carry-forward data that determine how downstream accounting hooks are composed.
-
-The wrapper also computes cross-chain cash-out context for non-sucker paths by augmenting local supply and surplus with remote sucker snapshots. Inner hooks may adjust tax rate or counts, but this repo keeps the omnichain supply/surplus view authoritative.
+- bridge runtime trust lives in `nana-suckers-v6`
+- 721 runtime trust lives in `nana-721-hook-v6`
+- this repo mainly owns orchestration and wrapper semantics
 
 ## Security Model
 
-- The largest risk is silent drift between deploy-time assumptions and runtime wrapper behavior.
-- Ruleset ID prediction is storage-key critical.
-- The sucker exception path intentionally short-circuits normal composition and should stay easy to reason about.
-- Suckers have two privileged behaviors by design: tax-free bridge cash-outs and unconditional mint permission. Those exceptions must remain tightly scoped to registry-recognized sucker addresses.
-- Salt derivation includes `_msgSender()` for replay protection. Cross-chain deterministic matching therefore depends on using the same sender on each chain.
-- Because this repo is both deployer and runtime hook, permission or hook-order changes can break already-launched projects, not just future launches.
-
-## Safe Change Guide
-
-- Review launch logic and runtime wrapper logic together.
-- If hook composition changes, test payment and cash-out ordering explicitly.
-- If ruleset prediction changes, test same-block and queued-ruleset edge cases.
-- If sucker exceptions or mint-permission behavior change, re-check bridge flows against normal custom-hook policy.
-- If salt derivation changes, re-check deterministic cross-chain deployment expectations and replay resistance together.
-- If wrapper metadata behavior changes, re-check the forced `useDataHookForPay/useDataHookForCashOut` install path and the extra-hook context shaping together.
-- Keep salt handling stable across chains when deterministic address expectations matter.
-
-## Canonical Checks
-
-- hook ordering and composition correctness:
-  `test/Tiered721HookComposition.t.sol`
-- carry-forward and queued-ruleset recovery behavior:
-  `test/audit/CarryForwardRejectedHook.t.sol`
-- wrapper invariants under adversarial sequences:
-  `test/invariants/OmnichainDeployerInvariant.t.sol`
+- the main risks are hook composition, ruleset ID prediction, and registry-trusted sucker bypasses
+- this repo is not the source of underlying bridge or 721 behavior, but it can wire them together incorrectly
 
 ## Source Map
 
 - `src/JBOmnichainDeployer.sol`
-- `src/structs/`
-- `test/Tiered721HookComposition.t.sol`
-- `test/audit/CarryForwardRejectedHook.t.sol`
-- `test/invariants/OmnichainDeployerInvariant.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,81 +1,26 @@
 # Audit Instructions
 
-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.
+Audit this repo as an orchestration layer that composes 721 hooks, suckers, and optional extra data hooks.
 
 ## Audit Objective
 
 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
+
+- launch the wrong project shape
+- miscompose hooks or wrapper behavior
+- grant privileged sucker behavior to the wrong addresses
+- create cross-chain drift or bad deterministic assumptions
 
 ## Scope
 
 In scope:
-- `src/JBOmnichainDeployer.sol`
-- `src/interfaces/`
-- `src/structs/`
-- deployment scripts in `script/`
 
-Key dependencies:
-- `nana-core-v6`
-- `nana-721-hook-v6`
-- `nana-suckers-v6`
+- `src/JBOmnichainDeployer.sol`
+- related tests under `test/`
 
 ## Start Here
 
 1. `src/JBOmnichainDeployer.sol`
-2. `script/Deploy.s.sol`
-3. `script/helpers/DeployersDeploymentLib.sol`
-
-## Security Model
-
-`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
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Launch caller | Supply desired project configuration | Should receive exactly the requested state |
-| Omnichain deployer | Create hooks, projects, and sucker composition | Must relinquish setup authority after launch |
-| Sucker registry | Grant omnichain-specific privileges | Must not bless arbitrary contracts |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| `nana-core-v6` | Launch and ruleset surfaces are authentic | Deployed economics drift from requested config |
-| `nana-721-hook-v6` | Hook ownership and tier setup complete correctly | Collection state or authority is wrong |
-| `nana-suckers-v6` | Registry identifies genuine peers | Fee or mint exemptions widen incorrectly |
-
-## Critical Invariants
-
-1. Launch configuration is faithful
-The deployed project must end up with the exact hook, ruleset, and ownership configuration the caller requested.
-
-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.
-
-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.
-
-4. Ownership transfer is complete
-Deployer-created hooks and helper contracts must not retain silent control after initialization.
-
-## Attack Surfaces
-
-- malformed launch configuration
-- hook and sucker ownership transfer
-- registry-based privilege spoofing
-- reentrancy around launch and initialization
-- local-only launches versus omnichain launches with optional components disabled
 
 ## Verification
 

package/README.md

@@ -24,8 +24,6 @@ The wrapper exists so sucker-triggered flows can be exempted from project-specif
 
 Use this repo when the default project shape is "Juicebox project plus 721 hook plus cross-chain bridge." Do not use it when a project is single-chain or does not need the wrapper semantics around suckers.
 
-If the question is "how do suckers bridge?" start in `nana-suckers-v6`. If the question is "how does a 721 hook behave?" start in `nana-721-hook-v6`. This repo is where those components are packaged together and wrapped.
-
 ## Key Contract
 
 | Contract | Role |
@@ -49,17 +47,17 @@ This repo owns orchestration plus runtime wrapping:
 
 ## Integration Traps
 
-- this repo wraps hooks and bridge flows together, so ownership and hook-order assumptions matter as much as the deployment salt
-- ruleset ID prediction is an implementation dependency and should be reviewed as an actual invariant
-- the deployer can carry forward an existing 721 hook shape, so stale assumptions about hook config can leak across deployments
-- bridge-safe wrapper behavior is part of the runtime trust model, not just deployment ergonomics
+- this repo wraps hooks and bridge flows together, so ownership and hook-order assumptions matter as much as deployment salt
+- ruleset ID prediction is a real implementation dependency
+- the deployer can carry forward an existing 721 hook shape, so stale hook assumptions can leak across deployments
+- bridge-safe wrapper behavior is part of the runtime trust model
 
 ## Where State Lives
 
-- orchestration and wrapper logic live in `JBOmnichainDeployer`
-- bridge runtime state lives in `nana-suckers-v6`
-- 721 tier state lives in `nana-721-hook-v6`
-- any extra hook behavior lives in the additional repo composed into the deployment
+- orchestration and wrapper logic: `JBOmnichainDeployer`
+- bridge runtime state: `nana-suckers-v6`
+- 721 tier state: `nana-721-hook-v6`
+- extra hook behavior: the additional repo composed into the deployment
 
 ## Install
 
@@ -100,10 +98,10 @@ script/
 
 ## Risks And Notes
 
-- ruleset ID prediction is part of the implementation strategy and should be treated as a real assumption
+- ruleset ID prediction is part of the implementation strategy
 - hook composition order matters because the 721 hook runs before any extra custom hook
-- using the default empty-tier 721 config is convenient, but teams should still decide explicitly whether the hook participates in cash-out behavior
-- deterministic salts help with cross-chain address alignment, but only when the sender and configuration match exactly
+- default empty-tier 721 config is convenient, but teams should still decide explicitly whether the hook participates in cash-out behavior
+- deterministic salts only help with cross-chain address alignment when sender and configuration match exactly
 
 ## For AI Agents
 

package/RISKS.md

@@ -1,81 +1,92 @@
 # Omnichain Deployers Risk Register
 
-This file focuses on the risks in the deployer layer that launches Juicebox projects across chains while composing 721 hooks, suckers, and optional custom data hooks.
+This file covers the risks in the deployer layer that launches Juicebox projects across chains while composing 721 hooks, suckers, and optional custom data hooks.
 
-## How to use this file
+## How To Use This File
 
-- Read `Priority risks` first; they capture the highest-blast-radius deployment and cash-out assumptions.
-- Use the detailed sections for access control, integration, and reentrancy analysis.
-- Treat `Invariants to Verify` as required checks for any new omnichain deployment flow.
+- Read `Priority risks` first. They capture the highest-blast-radius deployment and cash-out assumptions.
+- Treat `Invariants to verify` as required checks for any new omnichain deployment flow.
 
-## Priority risks
+## Priority Risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
 | P0 | Registry-trusted sucker bypass | This deployer gives suckers privileged cash-out behavior based on registry answers. A bad registry entry can affect many projects. | Registry allowlists, deployment verification, and explicit registry scrutiny. |
 | P1 | Cross-chain deployment drift | Omnichain assumptions fail if chain-specific wiring, peers, or composed hooks do not match. | Deterministic deploy ordering, parity checks, and post-deploy peer verification. |
-| P1 | Data-hook composition mistakes | The deployer wraps or forwards custom data hooks; a bad composition can alter pay or cash-out semantics unexpectedly. | Integration tests for wrapped hooks and careful review of forwarding logic. |
-
+| P1 | Data-hook composition mistakes | The deployer wraps or forwards custom data hooks. A bad composition can alter pay or cash-out semantics unexpectedly. | Integration tests and careful forwarding review. |
 
 ## 1. Trust Assumptions
 
-- **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 `controller.DIRECTORY().controllerOf(projectId)` (a reflexive lookup through the controller's own directory reference), but during `launchProjectFor` the project does not yet exist, so no pre-launch controller validation is possible. The post-launch safeguard is the explicit project-ID match check on `controller.launchProjectFor(...)`.
-- **Extra data hooks.** Arbitrary `IJBRulesetDataHook` addresses from ruleset metadata are stored and called directly from the deployer's pay/cash-out wrapper paths. A malicious hook can return arbitrary weight, cashout tax rate, or hook specifications, and can also consume all available gas or revert.
+- **Trusted forwarder is trusted.**
+- **Sucker registry answers are trusted.**
+- **Controller trust matters.**
+- **Extra data hooks are trusted code.**
 
-## 2. Economic / Manipulation Risks
+## 2. Economic 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`. 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.
-- **Cross-chain sender dependence in sucker deployment salts.** `deploySuckersFor` salts deployments with `keccak256(abi.encode(userSalt, _msgSender()))`. This prevents replay collisions, but it also means the same logical project deployed by different operators on different chains will not get matching deterministic sucker addresses.
+- **Sucker cashout bypass exists for registered suckers.**
+- **Extra data hooks can manipulate weight or cash-out behavior.**
+- **721 hook amount splitting can zero out project amount in edge cases.**
+- **Cross-chain sender dependence affects deterministic sucker salts.**
 
 ## 3. Access Control
 
-- **Wildcard MAP_SUCKER_TOKEN permission.** Constructor grants `SUCKER_REGISTRY` the `MAP_SUCKER_TOKEN` permission with `projectId=0` (wildcard). This grants the registry token-mapping rights across all projects ever deployed through this deployer.
-- **Permission checks on `launchRulesetsFor`.** Requires both `LAUNCH_RULESETS` and `SET_TERMINALS` from the project owner. If an operator has one but not the other, the call reverts. No combined permission ID exists.
-- **No permission check on `launchProjectFor`.** Anyone can call it because a new project is being created. The `owner` parameter receives the project NFT -- verify frontends do not allow this to be set to unexpected addresses.
+- **Wildcard `MAP_SUCKER_TOKEN` permission is broad.**
+- **`launchRulesetsFor` requires combined permissions.**
+- **`launchProjectFor` is intentionally permissionless for new projects.**
 
 ## 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. 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 direct call into the extra data hook has no gas limit, so 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.
-- **Unexpected safe NFT receipt reverts, but non-safe transfers can still strand assets.** `onERC721Received` only accepts `PROJECTS` NFTs. Safe transfers of any other ERC-721 revert instead of being accepted. The narrower residual risk is `transferFrom` or other non-safe delivery into the deployer, which bypasses the receiver hook and has no generalized rescue path.
+- **Ruleset ID collision can block queueing.**
+- **External hook reverts can block pay or cash-out flows.**
+- **721 hook deployment revert blocks launch.**
+- **Non-safe NFT transfers can still strand assets.**
 
 ## 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 calls the extra data hook directly. The 721 hook and extra hook 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.
+- **`launchProjectFor` makes several external calls in sequence.**
+- **`beforePayRecordedWith` delegates to external hooks.**
+- **`beforeCashOutRecordedWith` delegates to external hooks.**
+- **There is no `ReentrancyGuard`.** The deployer relies on being effectively stateless during pay and cash-out operations.
 
 ## 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 a previous ruleset. The source is selected by first checking `latestQueuedOf(projectId)` — if the queued ruleset's approval status is `Approved` or `Empty` and it has a stored hook config, that config is used. Otherwise it falls back to `currentOf(projectId)`. If neither has a hook deployed through this deployer, the mapping is empty and the call reverts with `JBOmnichainDeployer_InvalidHook`. The `useDataHookForCashOut` flag is also preserved from whichever source ruleset is selected.
-- **ERC721Receiver restriction.** `onERC721Received` only accepts from `PROJECTS`. Non-project NFTs sent via `safeTransferFrom` revert cleanly; non-safe transfers can still become stuck because the deployer has no generalized rescue function.
-- **Empty simplified launch config reverts.** The convenience overload that derives a default 721 config from `rulesetConfigurations[0]` reverts with `JBOmnichainDeployer_NoRulesetConfigurations()` when called with an empty ruleset array.
-- **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.
+- **Hook config is keyed by predicted ruleset ID.**
+- **Carried-forward 721 hook behavior on queue depends on prior ruleset state.**
+- **ERC721Receiver restrictions are narrow but non-safe transfers can still strand assets.**
+- **Empty simplified launch config reverts.**
 
-## 7. 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` 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.
-- `deploySuckersFor` uses the same `_msgSender()` on every chain when deterministic cross-chain peer symmetry is expected.
+- launched projects point at the intended controller
+- stored 721 hook config exists for every ruleset created through this deployer
+- sucker cashouts always get the intended zero-tax path
+- self-reference prevention holds after setup
+- the project NFT ends owned by the intended owner
 
 ## 8. Accepted Behaviors
 
-### 8.1 Controller validation skipped during `launchProjectFor` (by design)
+### 8.1 Controller validation is skipped during initial launch
+
+Pre-launch controller validation is impossible because the project does not yet exist. The accepted safeguard is the post-launch project ID match check.
+
+### 8.2 Registered suckers receive 0% cashout tax
+
+This is intentional and shares the same trust boundary as the sucker registry.
+
+## 9. Accepted Security Risks
+
+Documented risks that were reviewed and accepted.
+
+### Configuration Risks
+
+**Unvalidated extra data hooks can brick live flows.** *(Minor)*
+Extra data hooks provided by the project owner in `_setup721` configuration can fail and brick live pay/cashout flows. Accepted because this is self-inflicted misconfiguration — only the project owner can set these hooks.
 
-`_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 and no pre-launch validation is possible. The accepted safeguard is the explicit `ProjectIdMismatch` check immediately after `controller.launchProjectFor()` returns. 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.
+**Missing hook721 alias check enables double invocation.** *(Minor)*
+If the project owner configures the 721 hook as both the primary hook and as an extra data hook, it could be invoked twice. Accepted because this is self-inflicted misconfiguration — the deployer correctly processes each hook independently.
 
-### 8.2 Suckers receive 0% cashout tax (shared with revnet-core)
+### Cross-Chain Deployment
 
-`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.
+**`_msgSender()` in deployment salt breaks cross-chain determinism.** *(Minor)*
+`deploySuckersFor` includes `_msgSender()` in the CREATE2 salt, which means the same deployment from different callers produces different addresses across chains. Accepted because this is intentional replay protection — prevents frontrunning of cross-chain deployments.

package/SKILLS.md

@@ -2,43 +2,24 @@
 
 ## Use This File For
 
-- Use this file when the task involves deploying core projects with suckers and optional 721 or custom data-hook composition in one flow.
-- Start here, then decide whether the question is about deterministic deployment, ruleset-to-hook storage, wrapper pay/cash-out delegation, or sucker deployment authority. Those are distinct sources of failure here.
+- Use this file when the task involves omnichain project launch, sucker deployment, or wrapped 721-hook composition.
+- Start here, then decide whether the issue is in launch orchestration, hook composition, or bridge-specific runtime behavior.
 
 ## Read This Next
 
 | If you need... | Open this next |
 |---|---|
-| Repo overview and launch model | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Deployment implementation | [`src/JBOmnichainDeployer.sol`](./src/JBOmnichainDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
-| Runtime wrapper and config assumptions | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
-| Input and output types | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/) |
-| Guard rails, attacks, and hook-composition behavior | [`test/JBOmnichainDeployerGuard.t.sol`](./test/JBOmnichainDeployerGuard.t.sol), [`test/OmnichainDeployerAttacks.t.sol`](./test/OmnichainDeployerAttacks.t.sol), [`test/OmnichainDeployerReentrancy.t.sol`](./test/OmnichainDeployerReentrancy.t.sol), [`test/Tiered721HookComposition.t.sol`](./test/Tiered721HookComposition.t.sol) |
-| Baseline deployment and pinned edge cases | [`test/JBOmnichainDeployer.t.sol`](./test/JBOmnichainDeployer.t.sol), [`test/OmnichainDeployerEdgeCases.t.sol`](./test/OmnichainDeployerEdgeCases.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contract | [`src/JBOmnichainDeployer.sol`](./src/JBOmnichainDeployer.sol) |
-| Types | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/) |
-| Scripts | [`script/`](./script/) |
-| Tests | [`test/`](./test/) |
+| Repo overview and architecture | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Main deployer | [`src/JBOmnichainDeployer.sol`](./src/JBOmnichainDeployer.sol) |
+| Bridge runtime | [`../nana-suckers-v6/src/JBSucker.sol`](../nana-suckers-v6/src/JBSucker.sol) |
+| 721 hook runtime | [`../nana-721-hook-v6/src/JB721TiersHook.sol`](../nana-721-hook-v6/src/JB721TiersHook.sol) |
 
 ## Purpose
 
-Single-transaction deployment and wrapper layer for Juicebox projects that need a 721 hook, cross-chain sucker support, and optional extra data-hook composition from day one.
-
-## Reference Files
-
-- Open [`references/runtime.md`](./references/runtime.md) when you need hook-composition order, sucker exemptions, per-ruleset storage behavior, or the main runtime invariants.
-- Open [`references/operations.md`](./references/operations.md) when you need launch and queue behavior, permission and salt assumptions, test breadcrumbs, or the common stale-data traps.
+Orchestration and wrapper layer for launching projects with suckers and a 721 hook already wired in.
 
 ## Working Rules
 
-- Start in [`src/JBOmnichainDeployer.sol`](./src/JBOmnichainDeployer.sol) for both deployment and runtime wrapping behavior. This repo is orchestration plus a live data-hook wrapper, not a pure deploy script package.
-- Treat ruleset ID prediction, hook-carry-forward logic, and salt derivation as high-risk. Small changes there can orphan config or break deterministic deployment.
-- The deployer stores hook config per predicted ruleset ID. Same-block queue assumptions and carry-forward behavior are core correctness issues, not edge cases.
-- When a bug mentions suckers, tax-free cash outs, or mint permission, verify whether the early-return wrapper behavior is the real cause before changing downstream hooks.
-- Existing-project sucker deployment is not just “deploy clones”; it also depends on token-mapping authority landing correctly through the registry path.
-- If a task mentions 721 or custom-hook behavior, confirm whether the issue lives here or in the composed repo before patching wrapper logic.
+- Start in [`src/JBOmnichainDeployer.sol`](./src/JBOmnichainDeployer.sol).
+- Treat ruleset ID prediction as a real implementation dependency.
+- Keep wrapper behavior and the underlying 721 or sucker behavior separate in your reasoning.