@bananapus/omnichain-deployers-v6 0.0.19 → 0.0.21

package/ADMINISTRATION.md

@@ -2,6 +2,32 @@
 
 Admin privileges and their scope in nana-omnichain-deployers-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Omnichain project launch, hook composition, sucker deployment, and the deployer's data-hook proxy behavior. |
+| Operators | Project owners and delegates, the `JBOmnichainDeployer`, and the configured `JBSuckerRegistry` with its wildcard token-mapping grant. |
+| Highest-risk actions | Launching a project with the wrong hook composition, terminal configuration, or cross-chain setup, then assuming it can be rewritten later. |
+| Recovery posture | The deployer's immutable dependencies cannot be edited in place. Project-level recovery usually means launching corrected rulesets or redeploying the broader project path. |
+
+## Routine Operations
+
+- Validate all deploy-time hook choices, 721 settings, and sucker configuration before using `launchProjectFor` or `launchRulesetsFor`.
+- Keep the distinction clear between per-ruleset composed hooks and the deployer's permanent proxy role.
+- Use the deployer when you want its tax-free sucker and mint-permission behavior; otherwise, do not assume it is a drop-in replacement for arbitrary hook wiring.
+
+## One-Way Or High-Risk Actions
+
+- Constructor-time wildcard permissions and immutable references on the deployer cannot be changed afterward.
+- Launch-time hook composition choices determine how future pay and cash-out flows are merged for that ruleset.
+- A bad omnichain deployment can leave a project with a cross-chain shape that is expensive to unwind operationally.
+
+## Recovery Notes
+
+- If the project is still administratively flexible, queue new rulesets or use project-level migration paths to move to corrected hook composition.
+- If the deployer's own immutable assumptions are wrong, recovery means deploying a new deployer path rather than trying to hot-fix the existing one.
+
 ## Roles
 
 | Role | How Assigned | Scope |
@@ -17,7 +43,7 @@ Admin privileges and their scope in nana-omnichain-deployers-v6.
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|--------------|
-| `deploySuckersFor` | Project owner or operator | `DEPLOY_SUCKERS` | Per-project | Deploys new cross-chain suckers for an existing project via the sucker registry. |
+| `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`. |
 
@@ -55,12 +81,14 @@ Admin privileges and their scope in nana-omnichain-deployers-v6.
 
 | Action | Who | Mechanism |
 |--------|-----|-----------|
-| Deploy suckers for existing project | Project owner or DEPLOY_SUCKERS operator | `deploySuckersFor` calls `SUCKER_REGISTRY.deploySuckersFor` |
+| 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` |
 
+**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.
+
 **Cross-chain determinism:** The salt for sucker deployment is combined with `_msgSender()` (`keccak256(abi.encode(salt, _msgSender()))`). Deploying from the same sender address with the same salt on each chain produces matching sucker addresses.
 
 ## Data Hook Proxy Pattern

package/ARCHITECTURE.md

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