@bananapus/omnichain-deployers-v6 0.0.27 → 0.0.28

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/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.

package/USER_JOURNEYS.md

@@ -2,141 +2,62 @@
 
 ## Repo Purpose
 
-This repo packages omnichain project launches and omnichain-aware ruleset evolution.
-It owns deployment-time composition of core launch config, 721 hook config, sucker deployment, and wrapper behavior
-that keeps later bridge paths safe. It does not own the lower-level bridge runtime once suckers are deployed.
+This repo launches projects that are omnichain from the start.
 
 ## Primary Actors
 
-- teams launching projects that should be cross-chain from day one
-- deployers composing a 721 hook, suckers, and optional extra hooks
-- operators evolving rulesets without breaking omnichain wrapper behavior
+- operators launching omnichain projects
+- teams composing 721 hooks with extra data hooks
+- auditors checking bridge-wrapper behavior
 
-## Key Surfaces
+## Journey 1: Launch An Omnichain Project
 
-- `JBOmnichainDeployer`: packaged omnichain launch and ruleset-evolution surface
+**Actor:** deployer.
 
-## Journey 1: Launch A Project Across Chains In One Flow
-
-**Actor:** launch team or deployer.
-
-**Intent:** launch a project with its 721 hook, sucker package, and wrapper behavior already wired in.
-
-**Preconditions**
-- the team has base launch config, 721 config, and sucker deployment config ready
-- the team wants omnichain packaging instead of separate post-launch setup
-
-**Main Flow**
-1. Call `JBOmnichainDeployer` with the project launch config, 721 config, sucker deployment config, and any extra hook composition.
-2. The deployer launches the base Juicebox project and either deploys or wires the tiered 721 hook.
-3. It wraps the hook composition so future rulesets can keep sucker-safe behavior while still preserving project-specific hook logic.
-4. Deterministic salts are used so sibling-chain deployments can be coordinated with confidence.
-
-**Failure Modes**
-- deterministic inputs differ across chains and break address or wrapper expectations
-- teams treat the wrapper as cosmetic and miss its effect on later bridge-safe ruleset evolution
-
-**Postconditions**
-- the project launches with its omnichain-capable shape already installed
-- future bridge and ruleset questions should move to the wrapper, sucker, or 721 surfaces this deployer packaged
-
-## Journey 2: Coordinate Deterministic Deployment Inputs Across Chains
-
-**Actor:** deployment operator.
-
-**Intent:** keep addresses, salts, and wrapper behavior predictable across chains.
-
-**Preconditions**
-- the deployment will happen on more than one chain
-- the team can reuse the same structured inputs where determinism matters
+**Intent:** launch a project with a 721 hook and suckers already wired in.
 
 **Main Flow**
-1. Fix the deployer inputs that drive deterministic addresses for suckers and hook packaging.
-2. Reuse those inputs consistently on each chain.
-3. Validate that the controller, hook ownership, and sucker expectations still line up across the resulting deployments.
+1. Build the intended ruleset and hook composition.
+2. Launch the project through `JBOmnichainDeployer`.
+3. Deploy or wire the sucker pair and transfer control to the intended owner.
 
 **Failure Modes**
-- teams reuse similar but not identical inputs and assume deterministic outputs still match
-- address prediction is checked for one chain only and not for the full deployment set
-
-**Postconditions**
-- teams can predict addresses, salts, and wrapper behavior before doing the live rollout
-
-## Journey 3: Carry Forward An Existing 721 Hook While Queueing New Omnichain Rulesets
+- wrong hook composition
+- cross-chain deployment drift
+- wrong sucker peer wiring
 
-**Actor:** operator evolving a live project.
+## Journey 2: Deploying Suckers for an Existing Project
 
-**Intent:** queue new omnichain-aware rulesets without dropping the existing 721 collection.
+**Actor:** project owner who wants to add cross-chain sucker bridges to an already-launched project.
 
-**Preconditions**
-- the project already has a 721 hook
-- the operator wants omnichain-aware future rulesets without replacing that hook
+**Intent:** deploy suckers via `JBOmnichainDeployer.deploySuckersFor()` for a project that was not originally launched through the omnichain deployer (or needs additional suckers after launch).
 
-**Main Flow**
-1. Queue the next ruleset through the deployer using the path that reuses the existing 721 hook (pass zero tiers).
-2. The deployer selects the source hook: it first checks the latest queued ruleset (if approved or with no approval hook), then falls back to the current active ruleset. This prevents losing a recently queued hook config.
-3. The `useDataHookForCashOut` flag is preserved from whichever source ruleset is selected.
-4. Validate the controller and queued ruleset inputs before relying on the result.
-5. Confirm the queued ruleset now points at the carried-forward hook rather than accidentally dropping the 721 layer.
-
-**Failure Modes**
-- a newly queued but not yet active hook configuration is accidentally ignored
-- operators assume zero tiers means "no 721 behavior" rather than "reuse the existing hook"
-
-**Postconditions**
-- the existing 721 hook is carried forward, stored against the queued ruleset, and kept bridge-safe
+**Background**
 
-## Journey 4: Compose A Tiered 721 Hook With A Custom Extra Hook
+When a project is freshly launched through the omnichain deployer, the deployer contract temporarily holds the project NFT. This means it automatically satisfies the `DEPLOY_SUCKERS` permission check because it is the project owner at that moment. After sucker deployment, it transfers the NFT to the intended owner.
 
-**Actor:** product team.
-
-**Intent:** add extra hook behavior without breaking the omnichain wrapper or the standard 721 hook.
-
-**Preconditions**
-- the project needs both standard tiered NFTs and additional product logic
-- the extra hook is understood well enough to evaluate its effect on bridge paths
+For projects that already exist and are owned by someone else, the deployer no longer holds the project NFT. The permission check in `deploySuckersFor()` requires that the caller has `DEPLOY_SUCKERS` permission from the project owner. Since the omnichain deployer enforces this check internally via `_requirePermissionFrom`, the project owner must explicitly grant this permission before calling the function.
 
 **Main Flow**
-1. Provide the extra-hook config when launching through `JBOmnichainDeployer`.
-2. Let the deployer remember which composition belongs to each ruleset.
-3. Make sure bridge flows still bypass or special-case the right tax and data-hook behavior.
+1. The project owner calls `JBPermissions.setPermissionsFor()` to grant the `DEPLOY_SUCKERS` permission (from `JBPermissionIds`) to the `JBOmnichainDeployer` contract address, scoped to their project ID.
+2. The project owner (or any caller with the appropriate permission) calls `JBOmnichainDeployer.deploySuckersFor()` with the project ID and sucker deployment configuration.
+3. The deployer verifies that the caller has `DEPLOY_SUCKERS` permission from the project owner.
+4. The deployer deploys the suckers via the sucker registry and returns their addresses.
 
 **Failure Modes**
-- the extra hook overrides or bypasses wrapper assumptions the bridge path depends on
-- teams audit the extra hook in isolation and miss the composed behavior
-
-**Postconditions**
-- the extra logic composes with the 721 hook and sucker wrapper instead of overriding them unsafely
+- Calling `deploySuckersFor()` without first granting the deployer `DEPLOY_SUCKERS` permission will revert with a permission error.
+- Granting the permission to the wrong address (e.g., the caller's EOA instead of the deployer contract) will not satisfy the check, since the deployer enforces permission on behalf of the project owner against its own address.
+- Forgetting to scope the permission to the correct project ID will cause the call to fail.
 
-## Journey 5: Evolve The Project After Launch Without Breaking Bridge Paths
-
-**Actor:** live-project operator.
-
-**Intent:** change future project behavior without breaking the special wrapper assumptions suckers rely on.
-
-**Preconditions**
-- the project is already live
-- future rulesets need new metadata, hook composition, or payout behavior
-
-**Main Flow**
-1. Queue the next ruleset through the omnichain-aware deployer surface.
-2. Keep track of which hook stack should apply for that future ruleset.
-3. Confirm that sucker flows still land on the mint-safe and tax-safe path the wrapper was designed to preserve.
-
-**Failure Modes**
-- operators queue rulesets through a non-omnichain path and silently lose wrapper guarantees
-- teams change payout or hook assumptions without rechecking bridge-special-case behavior
+**Key Difference from Journey 1**
 
-**Postconditions**
-- ruleset changes preserve the wrapper assumptions that let suckers bridge cleanly
+In Journey 1 (fresh launch), permission is implicit because the deployer owns the project NFT during deployment. In Journey 2 (existing project), permission must be explicitly granted via `JBPermissions` before sucker deployment can proceed.
 
 ## Trust Boundaries
 
-- this repo is trusted for wrapper composition and hook carry-forward decisions across rulesets
-- `JBSuckerRegistry` and deployed suckers remain trusted for the actual bridge runtime
-- the underlying 721 hook and any extra hook still need to be audited as part of the composed product
+- this repo wraps runtime behavior but does not replace the underlying 721 or sucker repos
 
 ## Hand-Offs
 
-- Use [nana-suckers-v6](../nana-suckers-v6/USER_JOURNEYS.md) for the bridge mechanics after the project has been launched with suckers.
-- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) for the standard tier and resolver behavior that this repo packages into the omnichain launch.
+- Use `nana-suckers-v6` for bridge runtime behavior.
+- Use `nana-721-hook-v6` for tiered NFT runtime behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/omnichain-deployers-v6",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBOmnichainDeployer.sol

@@ -412,7 +412,9 @@ contract JBOmnichainDeployer is
         // This prevents disproportionate reclaim when tokens bridge away but surplus stays.
         effectiveSurplusValue = context.surplus.value
             + SUCKER_REGISTRY.remoteSurplusOf({
-                projectId: context.projectId, decimals: 18, currency: uint256(uint160(context.surplus.token))
+                projectId: context.projectId,
+                decimals: context.surplus.decimals,
+                currency: uint256(context.surplus.currency)
             });
 
         // Will hold the 721 hook's cash out specifications (always 0 or 1 element).
@@ -444,6 +446,7 @@ contract JBOmnichainDeployer is
             hookContext.cashOutTaxRate = cashOutTaxRate;
             hookContext.cashOutCount = cashOutCount;
             hookContext.totalSupply = totalSupply;
+            hookContext.surplus.value = effectiveSurplusValue;
 
             // Forward to the extra hook. It may further change the tax rate, count, and return hook specs.
             // We discard the inner hook's effectiveSurplusValue — this contract computes the cross-chain values.
@@ -923,7 +926,9 @@ contract JBOmnichainDeployer is
     /// @param projectId The ID of the project to validate the controller for.
     /// @param controller The controller to validate.
     function _validateController(uint256 projectId, IJBController controller) internal view {
-        if (address(controller.DIRECTORY().controllerOf(projectId)) != address(controller)) {
+        address current = address(controller.DIRECTORY().controllerOf(projectId));
+        // Allow address(0) for fresh projects that haven't launched rulesets yet.
+        if (current != address(0) && current != address(controller)) {
             revert JBOmnichainDeployer_ControllerMismatch();
         }
     }

package/test/audit/CodexNemesisAudit.t.sol

@@ -57,27 +57,35 @@ contract CodexNemesisAudit is Test {
         vm.mockCall(hookAddr, abi.encodeWithSelector(IJBOwnable.transferOwnershipToProject.selector), abi.encode());
     }
 
-    function test_poc_launchRulesetsFor_revertsWhenProjectHasNoControllerYet() public {
+    function test_poc_launchRulesetsFor_succeedsWhenProjectHasNoControllerYet() public {
         JBOmnichainDeployer deployer =
             new JBOmnichainDeployer(mockSuckerRegistry, hookDeployer, permissions, projects, address(0));
 
         vm.mockCall(
             address(controller), abi.encodeWithSelector(IJBController.DIRECTORY.selector), abi.encode(directory)
         );
-        // A freshly created project with no controller yet is valid for core launchRulesetsFor,
-        // but the deployer rejects it before the controller can set itself as first controller.
+        // A freshly created project with no controller yet — the M-14 fix allows address(0) through.
         vm.mockCall(
             address(directory),
             abi.encodeWithSelector(IJBDirectory.controllerOf.selector, PROJECT_ID),
             abi.encode(IERC165(address(0)))
         );
+        // Mock controller.launchRulesetsFor to return a rulesetId.
+        vm.mockCall(
+            address(controller),
+            abi.encodeWithSelector(IJBController.launchRulesetsFor.selector),
+            abi.encode(uint256(1))
+        );
 
         JBRulesetConfig[] memory configs = new JBRulesetConfig[](1);
         configs[0] = _makeRulesetConfig();
 
         vm.prank(projectOwner);
-        vm.expectRevert(JBOmnichainDeployer.JBOmnichainDeployer_ControllerMismatch.selector);
-        deployer.launchRulesetsFor(PROJECT_ID, configs, new JBTerminalConfig[](0), "memo", controller);
+        (uint256 rulesetId,) =
+            deployer.launchRulesetsFor(PROJECT_ID, configs, new JBTerminalConfig[](0), "memo", controller);
+
+        // Verify the call succeeded and returned a valid rulesetId.
+        assertGt(rulesetId, 0, "launchRulesetsFor should succeed for fresh project with no controller");
     }
 
     function test_poc_deploySuckersFor_requiresHiddenPermissionForDeployerItself() public {