@bananapus/omnichain-deployers-v6 0.0.25 → 0.0.27

package/ADMINISTRATION.md

@@ -1,156 +1,78 @@
 # Administration
 
-Admin privileges and their scope in nana-omnichain-deployers-v6.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Omnichain project launch, hook composition, sucker deployment, and the deployer's data-hook proxy behavior. |
-| Operators | Project owners and delegates, the `JBOmnichainDeployer`, and the configured `JBSuckerRegistry` with its wildcard token-mapping grant. |
-| Highest-risk actions | Launching a project with the wrong hook composition, terminal configuration, or cross-chain setup, then assuming it can be rewritten later. |
-| Recovery posture | The deployer's immutable dependencies cannot be edited in place. Project-level recovery usually means launching corrected rulesets or redeploying the broader project path. |
-
-## Routine Operations
-
-- Validate all deploy-time hook choices, 721 settings, and sucker configuration before using `launchProjectFor` or `launchRulesetsFor`.
-- Keep the distinction clear between per-ruleset composed hooks and the deployer's permanent proxy role.
-- Use the deployer when you want its tax-free sucker and mint-permission behavior; otherwise, do not assume it is a drop-in replacement for arbitrary hook wiring.
+| --- | --- |
+| 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 |
 
-## One-Way Or High-Risk Actions
+## Purpose
 
-- Constructor-time wildcard permissions and immutable references on the deployer cannot be changed afterward.
-- Launch-time hook composition choices determine how future pay and cash-out flows are merged for that ruleset.
-- A bad omnichain deployment can leave a project with a cross-chain shape that is expensive to unwind operationally.
+`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.
 
-## Recovery Notes
+## Control Model
 
-- If the project is still administratively flexible, queue new rulesets or use project-level migration paths to move to corrected hook composition.
-- If the deployer's own immutable assumptions are wrong, recovery means deploying a new deployer path rather than trying to hot-fix the existing one.
+- `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 |
-|------|-------------|-------|
-| Project owner | Holds the project's ERC-721 (minted by `JBProjects`) | Per-project. Can delegate via `JBPermissions`. |
-| Permitted operator | Granted specific permission IDs by the project owner through `JBPermissions` | Per-project, per-permission. ROOT (1) grants all. Wildcard projectId=0 grants across all projects. |
-| Registered sucker | Deployed via `JBSuckerRegistry.deploySuckersFor` (requires DEPLOY_SUCKERS permission) | Per-project. Gets 0% cash-out tax and mint permission automatically. |
-| JBSuckerRegistry | Set at construction, granted MAP_SUCKER_TOKEN for all projects (projectId=0 wildcard) | Protocol-wide. Maps tokens for sucker bridging. |
-
-## Privileged Functions
-
-### JBOmnichainDeployer
-
-| 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. The same operation also applies token mappings on the new suckers, so existing projects must already have the registry arranged as an authorized `MAP_SUCKER_TOKEN` operator for that project. |
-| `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
-
-| 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: 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). |
-| `tiered721HookOf` | Anyone | View function: returns the stored 721 hook and `useDataHookForCashOut` flag for a project/ruleset pair. |
-
-## Deployment Administration
-
-**Who can deploy omnichain projects:** Anyone. The `launchProjectFor` function is permissionless. The caller specifies an `owner` address that receives the project ERC-721.
+| 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 |
 
-**Deployment flow:**
-1. The deployer deploys a 721 tiers hook via `HOOK_DEPLOYER` (even with 0 tiers).
-2. It configures rulesets via `_setup721()`, sets itself as the data hook wrapper.
-3. It calls `controller.launchProjectFor`, which mints the project ERC-721 to `address(this)`.
-4. It transfers 721 hook ownership to the project (requires project NFT to exist).
-5. It optionally deploys suckers via the sucker registry.
-6. It transfers the project ERC-721 to the specified `owner`.
+## Privileged Surfaces
 
-**Configurable parameters at deployment:**
-- Ruleset configurations (duration, weight, decay, approval hooks, splits, fund access limits, metadata flags).
-- Terminal configurations (which terminals accept which tokens).
-- 721 tiers hook configuration (tier pricing, supply, metadata, categories — can be empty for 0 tiers).
-- Sucker deployment configuration (which chains, which deployers, token mappings).
-- Salt for deterministic cross-chain address matching.
+| 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 |
 
-## Cross-Chain Controls
+## Immutable And One-Way
 
-| Action | Who | Mechanism |
-|--------|-----|-----------|
-| Deploy suckers for existing project | Project owner or DEPLOY_SUCKERS operator | `deploySuckersFor` calls `SUCKER_REGISTRY.deploySuckersFor`; because the registry also applies the initial mappings, existing projects must pair this with a project-level `MAP_SUCKER_TOKEN` arrangement for the registry |
-| Deploy suckers during project launch | Project deployer (anyone) | Included in `launchProjectFor` if `salt != bytes32(0)` |
-| Map sucker tokens | JBSuckerRegistry | Granted MAP_SUCKER_TOKEN at construction with projectId=0 wildcard |
-| Grant 0% cash-out tax to suckers | Automatic | `beforeCashOutRecordedWith` checks `SUCKER_REGISTRY.isSuckerOf` |
-| Grant mint permission to suckers | Automatic | `hasMintPermissionFor` checks `SUCKER_REGISTRY.isSuckerOf` |
+- 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.
 
-**Existing-project operator note:** `deploySuckersFor` looks like a deployment-only action at the top level, but it is intentionally a deploy-and-map flow. If an existing project delegates `DEPLOY_SUCKERS` without also arranging `MAP_SUCKER_TOKEN` for the registry, the transaction will fail once the registry reaches the mapping step.
+## Operational Notes
 
-**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.
+- 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.
 
-## Data Hook Proxy Pattern
+## Machine Notes
 
-`JBOmnichainDeployer` acts as a data hook proxy. When set as a project's `dataHook` in ruleset metadata, it wraps up to two inner hooks:
+- 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.
 
-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.
+## Recovery
 
-### Call flow for `beforePayRecordedWith`:
+- 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.
 
-```
-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:
-
-| Property | Type | What It Is |
-|----------|------|-----------|
-| `PROJECTS` | `IJBProjects` | The ERC-721 contract for project ownership. |
-| `HOOK_DEPLOYER` | `IJB721TiersHookDeployer` | The deployer for 721 tiers hooks. |
-| `SUCKER_REGISTRY` | `IJBSuckerRegistry` | The registry for deploying and tracking suckers. |
-| `PERMISSIONS` | `IJBPermissions` | The permissions contract (inherited from JBPermissioned). |
-| Trusted forwarder | `address` | The ERC-2771 trusted forwarder for meta-transactions. |
-| MAP_SUCKER_TOKEN grant | Permission | Granted to SUCKER_REGISTRY at construction for all projects (projectId=0). Cannot be revoked by this contract. |
+## Admin Boundaries
 
-**Data hook mappings** (`_tiered721HookOf[projectId][rulesetId]` and `_extraDataHookOf[projectId][rulesetId]`) are write-once per ruleset ID. They are set during `_setup721()` and never updated or deleted.
+- 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.
 
-## Admin Boundaries
+## Source Map
 
-What admins **cannot** do:
-
-- **Cannot upgrade the deployer.** JBOmnichainDeployer has no upgrade mechanism, proxy pattern, or self-destruct.
-- **Cannot change immutable references.** PROJECTS, HOOK_DEPLOYER, SUCKER_REGISTRY, PERMISSIONS, and the trusted forwarder are all immutable.
-- **Cannot modify stored data hooks.** Once a ruleset's hooks are stored in `_tiered721HookOf` and `_extraDataHookOf`, they cannot be changed. New rulesets can use different hooks, but existing mappings are permanent.
-- **Cannot bypass permission checks.** All post-deployment admin functions require JBPermissions verification against the project owner.
-- **Cannot revoke sucker privileges.** Once a sucker is registered in JBSuckerRegistry, it automatically gets 0% cash-out tax and mint permission for its project. Revocation must happen at the registry level.
-- **Cannot set the deployer as its own data hook.** `_setup721()` explicitly reverts with `JBOmnichainDeployer_InvalidHook` if a hook is `address(this)`.
-- **Cannot use a controller that doesn't match the project.** `_validateController` reverts with `JBOmnichainDeployer_ControllerMismatch` if the provided controller is not the project's actual controller in the directory.
-- **Cannot steal project ownership during deployment.** The deployer holds the project ERC-721 only transiently and transfers it to the specified owner in the same transaction.
-- **Cannot drain funds.** The deployer never holds or manages token balances. It only orchestrates configuration.
+- `src/JBOmnichainDeployer.sol`
+- `src/interfaces/IJBOmnichainDeployer.sol`
+- `src/structs/`
+- `test/`

package/ARCHITECTURE.md

@@ -2,79 +2,109 @@
 
 ## Purpose
 
-`nana-omnichain-deployers-v6` launches Juicebox projects that are ready for both tiered NFTs and cross-chain suckers from day one. It also acts as a wrapper data hook so it can compose a 721 hook with an optional extra data hook while granting suckers tax-free cash outs and mint permission.
+`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.
 
-## Boundaries
+## System Overview
 
-- `JBOmnichainDeployer` is both a deployer and a live hook wrapper. Those two roles are inseparable.
-- The repo composes `nana-721-hook-v6` and `nana-suckers-v6`; it should not duplicate their internal logic.
-- Project accounting still happens in the core protocol.
+`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.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `JBOmnichainDeployer` | Project launch, ruleset queueing, hook composition, and sucker-safe cash-out policy |
-| config structs | 721 hook config, extra hook config, and sucker deployment config |
-| `IJBOmnichainDeployer` | Public deployer and inspection interface |
+- 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.
 
-## Runtime Model
+## 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 |
+
+## 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
-  -> launch project or queue rulesets through the deployer
+  -> launches a project or queues rulesets through the deployer
   -> deployer installs itself as the ruleset data hook
-  -> deployer deploys or carries forward the 721 hook
-  -> deployer optionally deploys sucker pairs with deterministic salts
-  -> project ownership is transferred to the intended owner
+  -> deploys or carries forward the 721 hook
+  -> optionally deploys sucker pairs with deterministic salts
+  -> transfers project ownership to the intended owner
 ```
 
-### 721 Hook Carry-Forward (Queue Path)
-
-When `queueRulesetsOf` is called without new tiers, the deployer carries the existing 721 hook forward. The source ruleset is chosen with this precedence:
+### Queue With Carry-Forward
 
-1. **Latest queued ruleset** — if its approval status is `Approved` or `Empty` (no approval hook) and it has a hook config stored in the deployer.
-2. **Current active ruleset** — fallback when no qualifying queued ruleset exists.
-
-This ensures that a recently queued (and approved) ruleset's hook config takes precedence over a potentially stale active ruleset. The `useDataHookForCashOut` flag is also preserved from whichever source ruleset is selected.
+```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
+```
 
-### Pay And Cash-Out Wrapping
+### Runtime Wrapping
 
 ```text
 runtime callback
-  -> if the actor is a registered sucker, return the special tax-free / mint-enabled path
-  -> otherwise call the 721 hook first when configured
-  -> then call the extra data hook when configured
-  -> merge hook specs in order and return the combined result
+  -> 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
 ```
 
-## Critical Invariants
-
-- Suckers must be able to bridge without getting trapped behind custom cash-out policies.
-- Hook order matters: the 721 hook runs first, and the extra hook receives the updated context.
-- The deployer's predicted ruleset IDs must stay aligned with `JBRulesets` behavior; the storage keys depend on it.
-- Every project launched through this repo gets a 721 hook surface, even if it starts with zero tiers.
-- Carry-forward must prefer the latest approved queued ruleset over the current ruleset to avoid losing hook config from a recently queued update.
+## Accounting Model
 
-## Where Complexity Lives
+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.
 
-- This repo hides composition complexity behind a simple launch surface, which makes stale assumptions dangerous.
-- Ruleset ID prediction is a subtle but central storage keying mechanism.
-- The sucker exception path intentionally short-circuits normal hook composition and must stay easy to reason about.
+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.
 
-## Dependencies
+## Security Model
 
-- `nana-core-v6` for project launch and hook interfaces
-- `nana-721-hook-v6` for tiered NFT behavior
-- `nana-suckers-v6` for cross-chain transport
-- `nana-ownable-v6` for project-following hook ownership
+- 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-time logic and runtime-hook logic together. This repo is easy to break by fixing only one side.
-- When changing hook composition, verify both payment and cash-out ordering.
-- If you touch ruleset ID prediction, test same-block and queued-ruleset edge cases explicitly.
-- Keep deterministic salt handling stable across chains; address predictability is part of the feature.
-- Treat "transparent wrapper" claims as something to prove continuously, not assume.
+- 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`
+
+## 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

@@ -2,7 +2,7 @@
 
 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.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - launch projects with incorrect rulesets, terminals, or hook ownership
@@ -24,7 +24,13 @@ Key dependencies:
 - `nana-721-hook-v6`
 - `nana-suckers-v6`
 
-## System Model
+## 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
@@ -33,6 +39,22 @@ Key dependencies:
 - 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
@@ -47,26 +69,16 @@ If the deployer proxies or modifies hook outputs, the resulting project token is
 4. Ownership transfer is complete
 Deployer-created hooks and helper contracts must not retain silent control after initialization.
 
-## Threat Model
+## Attack Surfaces
 
-Prioritize:
-- empty or malformed ruleset configurations
-- hook ownership transfer races
+- malformed launch configuration
+- hook and sucker ownership transfer
 - registry-based privilege spoofing
-- reentrancy around project launch and initialization
-- stale assumptions when optional sucker deployment is skipped
+- reentrancy around launch and initialization
+- local-only launches versus omnichain launches with optional components disabled
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-Existing tests emphasize:
-- reentrancy and attack paths
-- hook composition
-- weight scaling
-- omnichain fork and stress scenarios
-
-High-value findings typically show either a bad project launch state or a non-sucker actor receiving omnichain-only privileges.

package/README.md

@@ -3,7 +3,12 @@
 `@bananapus/omnichain-deployers-v6` launches Juicebox projects with cross-chain suckers and a 721 hook already wired in. It is the package you use when the default project shape should be omnichain from day one.
 
 Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
@@ -12,10 +17,10 @@ The deployer wraps multiple launch concerns into one surface:
 - deploy or carry forward a tiered 721 hook
 - install itself as the project's data-hook wrapper
 - compose the 721 hook with an optional extra custom hook
-- grant tax-free and mint-safe behavior to project suckers
+- wrap sucker flows so project-specific cash-out taxation and mint-permission logic can be handled safely
 - deploy suckers deterministically across chains
 
-The wrapper exists so suckers can bridge without being blocked by project-specific cash-out tax logic while the project still keeps its own data hooks.
+The wrapper exists so sucker-triggered flows can be exempted from project-specific cash-out taxation and related mint-gating logic where needed while the project still keeps its own inner data hooks.
 
 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.
 
@@ -42,6 +47,20 @@ This repo owns orchestration plus runtime wrapping:
 3. `nana-721-hook-v6/src/JB721TiersHook.sol`
 4. the extra hook repo, if the deployment composes one
 
+## 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
+
+## 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
+
 ## Install
 
 ```bash
@@ -85,3 +104,8 @@ script/
 - 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
+
+## For AI Agents
+
+- Describe this repo as an orchestration and wrapper layer, not as the source of sucker or 721 runtime behavior.
+- Start with `JBOmnichainDeployer`, then inspect the sibling repo that owns the behavior being questioned.

package/RISKS.md

@@ -29,6 +29,7 @@ This file focuses on the risks in the deployer layer that launches Juicebox proj
 - **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.
 
 ## 3. Access Control
 
@@ -41,6 +42,7 @@ This file focuses on the risks in the deployer layer that launches Juicebox proj
 - **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.
 
 ## 5. Reentrancy Surface
 
@@ -53,7 +55,8 @@ This file focuses on the risks in the deployer layer that launches Juicebox proj
 
 - **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`. Any other NFTs sent to this contract are permanently lost.
+- **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.
 
@@ -65,6 +68,7 @@ This file focuses on the risks in the deployer layer that launches Juicebox proj
 - `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.
 
 ## 8. Accepted Behaviors
 

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## 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 open the deployer or composition-focused tests depending on whether the question is about setup, permissions, hook wrapping, or runtime delegation.
+- 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.
 
 ## Read This Next
 
@@ -11,8 +11,10 @@
 |---|---|
 | 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, or hook composition behavior | [`test/JBOmnichainDeployerGuard.t.sol`](./test/JBOmnichainDeployerGuard.t.sol), [`test/OmnichainDeployerAttacks.t.sol`](./test/OmnichainDeployerAttacks.t.sol), [`test/Tiered721HookComposition.t.sol`](./test/Tiered721HookComposition.t.sol), [`test/regression/`](./test/regression/) |
+| 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
 
@@ -36,5 +38,7 @@ Single-transaction deployment and wrapper layer for Juicebox projects that need
 
 - 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.