@bananapus/omnichain-deployers-v6 0.0.7 → 0.0.8

package/ADMINISTRATION.md

@@ -30,9 +30,10 @@ Admin privileges and their scope in nana-omnichain-deployers-v6.
 | `launchProjectFor` | Anyone | Creates a new project with suckers. The ERC-721 is minted to the specified `owner`. |
 | `launch721ProjectFor` | Anyone | Creates a new project with a 721 tiers hook and suckers. The ERC-721 is minted to the specified `owner`. |
 | `beforePayRecordedWith` | JBMultiTerminal (via controller) | View function: forwards pay data to the stored data hook, or passes through if none configured. |
-| `beforeCashOutRecordedWith` | JBMultiTerminal (via controller) | View function: returns 0% cash-out tax for registered suckers, otherwise forwards to stored data hook. |
-| `hasMintPermissionFor` | JBController | View function: returns true for registered suckers, otherwise forwards to stored data hook. |
-| `dataHookOf` | Anyone | View function: returns the stored data hook config for a project/ruleset pair. |
+| `beforeCashOutRecordedWith` | JBMultiTerminal (via controller) | View function: returns 0% cash-out tax for registered suckers. Checks 721 hook (from `_tiered721HookOf`) then custom hook (from `_extraDataHookOf`) — the first with `useDataHookForCashOut: true` handles it. 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
 
@@ -75,7 +76,7 @@ These values are set at deployment and cannot be changed:
 | 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. |
 
-**Data hook mappings** (`_dataHookOf[projectId][rulesetId]`) are write-once per ruleset ID. They are set during `_setup` and never updated or deleted.
+**Data hook mappings** (`_tiered721HookOf[projectId][rulesetId]` and `_extraDataHookOf[projectId][rulesetId]`) are write-once per ruleset ID. They are set during `_setup` / `_setup721` and never updated or deleted.
 
 ## Admin Boundaries
 
@@ -83,10 +84,10 @@ 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 data hook config is stored in `_dataHookOf`, it cannot be changed. New rulesets can use different hooks, but existing mappings are permanent.
+- **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.** The `_setup` function explicitly reverts with `JBOmnichainDeployer_InvalidHook` if `metadata.dataHook == address(this)`.
+- **Cannot set the deployer as its own data hook.** Both `_setup` and `_setup721` explicitly revert 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.

package/ARCHITECTURE.md

@@ -8,11 +8,12 @@ Omnichain project deployer for Juicebox V6. Wraps the project deployment flow to
 
 ```
 src/
-├── JBOmnichainDeployer.sol       — Deploys projects with sucker integration, acts as data hook
+├── JBOmnichainDeployer.sol       — Deploys projects with sucker integration, acts as data hook wrapper
 ├── interfaces/
 │   └── IJBOmnichainDeployer.sol  — Interface
 └── structs/
-    ├── JBDeployerHookConfig.sol      — Hook configuration for deployment
+    ├── JBDeployerHookConfig.sol      — Custom hook configuration for deployment
+    ├── JBTiered721HookConfig.sol     — Per-ruleset 721 hook configuration
     └── JBSuckerDeploymentConfig.sol  — Sucker deployment parameters
 ```
 
@@ -31,12 +32,18 @@ Deployer → JBOmnichainDeployer.deployProjectFor()
 ### Data Hook Behavior
 ```
 Payment → JBOmnichainDeployer.beforePayRecordedWith()
-  → Pass through (no modification to pay behavior)
-  → Return empty pay hook specifications
+  → Calls 721 hook first (from _tiered721HookOf) for specs/split amounts
+  → Calls custom hook from _extraDataHookOf (if useDataHookForPay=true)
+  → Custom hook receives reduced amount (payment - splitAmount)
+  → Adjusts weight proportionally for splits
+  → Merges both hook specs (721 first, then custom)
 
 Cash Out → JBOmnichainDeployer.beforeCashOutRecordedWith()
-  → If caller is a registered sucker: return 0% cash-out tax
-  → Otherwise: return configured cash-out tax rate
+  → If caller is a registered sucker: return 0% cash-out tax (early return)
+  → Checks 721 hook (from _tiered721HookOf, if useDataHookForCashOut=true)
+  → Then checks custom hook (from _extraDataHookOf, if useDataHookForCashOut=true)
+  → If 721 hook has flag=true and reverts (fungible cashout): revert propagates
+  → If neither hook has the flag set: return original values
 ```
 
 ### Ruleset Management

package/README.md

@@ -8,11 +8,12 @@ Deploy Juicebox projects with cross-chain suckers and optional 721 tiers hooks i
 
 Launching a cross-chain Juicebox project normally takes several steps: deploy the project, configure rulesets, set up terminals, deploy suckers, and wire up a data hook that exempts suckers from cash out taxes. `JBOmnichainDeployer` collapses all of this into one transaction.
 
-It works by inserting itself as the data hook on every ruleset it touches, storing the project's custom data hook in a mapping keyed by `(projectId, rulesetId)` and any 721 tiers hook separately in `tiered721HookOf`. When the protocol calls data hook functions during payments and cash outs, the deployer:
+It works by inserting itself as the data hook on every ruleset it touches, storing hooks in two separate mappings: the 721 tiers hook (if any) is stored per-ruleset in `_tiered721HookOf[projectId][rulesetId]` with its own `useDataHookForCashOut` flag, and an optional custom data hook (e.g., buyback hook) is stored per-ruleset in `_extraDataHookOf[projectId][rulesetId]` with `useDataHookForPay` and `useDataHookForCashOut` flags. When the protocol calls data hook functions during payments and cash outs, the deployer:
 
 - **Checks if the holder is a sucker** -- if so, returns 0% cash out tax and grants mint permission. This early return means suckers can always bridge tokens without interference, even if the project's hooks would revert.
-- **Composes the 721 hook and custom data hook** for payments -- the 721 hook is called first to get its specs (including split fund amounts), then the custom data hook is called with a reduced amount context (payment minus split amount) so it only considers the available funds. The deployer adjusts the returned weight proportionally for splits, ensuring the terminal only mints tokens for the amount that actually enters the project treasury. For cash outs, the 721 hook takes priority if present.
-- **Forwards to the custom data hook** if no 721 hook is set, or returns default values if neither is set.
+- **Composes the 721 hook and custom data hook** for payments -- the 721 hook is called first (via `tiered721HookOf`) to get its specs (including split fund amounts), then the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) is called with a reduced amount context (payment minus split amount) so it only considers the available funds. The deployer adjusts the returned weight proportionally for splits, ensuring the terminal only mints tokens for the amount that actually enters the project treasury.
+- **Checks hooks for cash outs** -- the 721 hook is checked first (if `useDataHookForCashOut: true`), then the custom hook. The first with the flag set handles the cash out. If the 721 hook has `useDataHookForCashOut: true` and reverts (e.g., for fungible-only cashouts), that revert propagates. Set `useDataHookForCashOut: false` on the 721 metadata to skip it and let the custom hook handle cashouts instead.
+- **Returns default values** if neither hook has the relevant flag set.
 
 This wrapping is invisible to the project and its users. The project's hooks (buyback hook, 721 hook, etc.) work exactly as configured, and can be composed together.
 
@@ -42,20 +43,18 @@ sequenceDiagram
     participant Terminal
     participant Deployer as JBOmnichainDeployer
     participant Registry as JBSuckerRegistry
-    participant Hook as Real Data Hook
+    participant Hook as 721 / Custom Hook
 
     Terminal->>Deployer: beforeCashOutRecordedWith(context)
     Deployer->>Registry: isSuckerOf(projectId, holder)?
     alt Holder is a sucker
         Deployer-->>Terminal: 0% tax (early return)
-    else 721 hook exists
-        Deployer->>721Hook: beforeCashOutRecordedWith(context)
-        721Hook-->>Deployer: taxRate, count, supply, specs
-        Deployer-->>Terminal: forward 721 hook response
-    else Custom data hook exists
+    else 721 or custom hook with useDataHookForCashOut=true
         Deployer->>Hook: beforeCashOutRecordedWith(context)
         Hook-->>Deployer: taxRate, count, supply, specs
-        Deployer-->>Terminal: forward custom hook response
+        Deployer-->>Terminal: forward hook response
+    else Neither hook has useDataHookForCashOut=true
+        Deployer-->>Terminal: original values (default)
     end
 ```
 
@@ -64,12 +63,12 @@ sequenceDiagram
 The `launch721*` and `queue721*` variants deploy a tiered ERC-721 hook alongside the project. The deployer:
 
 1. Deploys the 721 hook via `HOOK_DEPLOYER`
-2. Stores the 721 hook in `tiered721HookOf[projectId]` (separate from the custom data hook)
+2. Stores the 721 hook per-ruleset in `_tiered721HookOf[projectId][rulesetId]` with its `useDataHookForCashOut` flag
 3. Converts 721-specific ruleset configs (`JBPayDataHookRulesetConfig`) to standard configs, enforcing `useDataHookForPay = true` and `allowSetCustomToken = false`
-4. Stores the optional custom data hook (e.g., buyback hook) in `_dataHookOf[projectId][rulesetId]`
+4. Stores the optional custom hook (e.g., buyback hook) separately in `_extraDataHookOf[projectId][rulesetId]` with its own per-hook flags
 5. Transfers hook ownership to the project via `JBOwnable.transferOwnershipToProject()`
 
-This separation means a project can have both a 721 hook (for NFT minting on payments) and a custom data hook (for buyback, custom weight logic, etc.) running simultaneously. During payments, both hooks' specifications are merged. During cash outs, the 721 hook takes priority.
+This means a project can have both a 721 hook (for NFT minting on payments) and a custom data hook (for buyback, custom weight logic, etc.) running simultaneously. During payments, both hooks' specifications are merged. During cash outs, the 721 hook is checked first (if `useDataHookForCashOut: true`), then the custom hook.
 
 ### Deterministic Cross-Chain Addresses
 
@@ -100,9 +99,10 @@ The `queueRulesetsOf` and `queue721RulesetsOf` functions guard against predictio
 
 | Type | Description |
 |------|-------------|
-| `JBDeployerHookConfig` | Per-ruleset config storing the custom data hook address and its `useDataHookForPay`/`useDataHookForCashOut` flags. The 721 hook is stored separately in `tiered721HookOf`. |
+| `JBDeployerHookConfig` | Per-hook config with `dataHook`, `useDataHookForPay`, and `useDataHookForCashOut` flags. Stored as a single value per `(projectId, rulesetId)` in `_extraDataHookOf` for the custom data hook. |
+| `JBTiered721HookConfig` | Per-ruleset 721 hook config with `hook` (the `IJB721TiersHook`) and `useDataHookForCashOut` flag. Stored per `(projectId, rulesetId)` in `_tiered721HookOf`. |
 | `JBSuckerDeploymentConfig` | Wraps an array of `JBSuckerDeployerConfig` with a `bytes32` salt for deterministic cross-chain addresses. |
-| `IJBOmnichainDeployer` | Interface for all deployer entry points and the `dataHookOf` view. |
+| `IJBOmnichainDeployer` | Interface for all deployer entry points and the `extraDataHookOf` view. |
 
 ## Install
 
@@ -137,7 +137,7 @@ Add to `remappings.txt`:
 # foundry.toml
 [profile.default]
 solc = '0.8.26'
-evm_version = 'paris'
+evm_version = 'cancun'
 optimizer_runs = 100000
 
 [fuzz]
@@ -148,19 +148,23 @@ runs = 4096
 
 ```
 src/
-  JBOmnichainDeployer.sol               # Main contract (719 lines)
+  JBOmnichainDeployer.sol               # Main contract (~893 lines)
   interfaces/
     IJBOmnichainDeployer.sol            # Public interface
   structs/
-    JBDeployerHookConfig.sol            # Stored data hook config
+    JBDeployerHookConfig.sol            # Custom hook config (dataHook + flags)
+    JBTiered721HookConfig.sol           # Per-ruleset 721 hook config
     JBSuckerDeploymentConfig.sol        # Sucker deployment params
 test/
   JBOmnichainDeployer.t.sol             # Unit tests
   JBOmnichainDeployerGuard.t.sol        # Ruleset ID prediction tests
   OmnichainDeployerAttacks.t.sol        # Adversarial security tests
-  Tiered721HookComposition.t.sol       # 721 hook + custom hook composition tests
+  OmnichainDeployerEdgeCases.t.sol      # Edge case tests (weight, cashout, mint)
+  OmnichainDeployerReentrancy.t.sol     # Reentrancy tests
+  Tiered721HookComposition.t.sol        # 721 hook + custom hook composition tests
+  fork/                                 # Fork tests against mainnet
   regression/
-    H20_HookOwnershipTransfer.t.sol     # Hook ownership transfer regression
+    HookOwnershipTransfer.t.sol         # Hook ownership transfer regression
 script/
   Deploy.s.sol                          # Sphinx deployment script
   helpers/
@@ -180,7 +184,7 @@ Note: `launchProjectFor` and `launch721ProjectFor` require no permissions -- any
 
 ## Risks
 
-- **Ruleset ID mismatch**: If `_setup()` predictions are wrong (e.g., due to same-block queuing from another source), the stored hook configs will be keyed to the wrong rulesets. The `queueRulesetsOf` guard prevents this, but `launchProjectFor` relies on `PROJECTS.count()` being accurate at call time.
-- **Reverting real hook**: If the project's real data hook reverts on `beforePayRecordedWith`, payments are blocked. Suckers are immune to this for cash outs (early return), but not for payments.
+- **Ruleset ID mismatch**: If `_setup()` / `_setup721()` predictions are wrong (e.g., due to same-block queuing from another source), the stored hook configs will be keyed to the wrong rulesets. The `queueRulesetsOf` guard prevents this, but `launchProjectFor` relies on `PROJECTS.count()` being accurate at call time.
+- **Reverting real hook**: If any stored hook reverts on `beforePayRecordedWith`, payments are blocked. If the 721 hook has `useDataHookForCashOut: true`, its revert for fungible cashouts propagates. Suckers are immune to this for cash outs (early return), but not for payments.
 - **Hook forwarding is view-only**: The deployer's data hook functions are `view`, so any real hook that requires state changes in `beforePayRecordedWith` or `beforeCashOutRecordedWith` will fail.
 - **Meta-transaction trust**: ERC2771 `_msgSender()` is used for salt hashing. A compromised trusted forwarder could impersonate senders and create suckers at unexpected addresses.

package/RISKS.md

@@ -13,7 +13,7 @@
 | Risk | Description | Mitigation |
 |------|-------------|------------|
 | Sucker privilege abuse | Any registered sucker gets 0% cashout tax | Sucker registration requires DEPLOY_SUCKERS permission |
-| Data hook centralization | Deployer is the data hook for all omnichain projects | Simple pass-through logic minimizes attack surface |
+| Data hook centralization | Deployer is the data hook for all omnichain projects | Simple pass-through logic minimizes attack surface. The 721 hook (in `_tiered721HookOf`) and custom hook (in `_extraDataHookOf`) each have their own `useDataHookForCashOut` flag — set to `false` on the 721 metadata to skip it for fungible cashouts. Suckers always get the early return regardless of hook configuration. |
 | Controller mismatch | Reverts if provided controller doesn't match project's actual controller | Explicit validation via `JBOmnichainDeployer_ControllerMismatch` |
 | Invalid self-hook | Reverts if someone tries to set deployer as hook for deployer itself | `JBOmnichainDeployer_InvalidHook` check |
 | Ownership transfer | Project ownership transferred during deployment | Ownership returned to caller after setup |

package/SKILLS.md

@@ -2,13 +2,13 @@
 
 ## Purpose
 
-Single-transaction deployment of Juicebox projects with cross-chain suckers and optional 721 tiers hooks. Wraps the project's data hook to give suckers tax-free cash outs and mint permission without interfering with custom hooks. Supports composing a 721 hook alongside a custom data hook (e.g., buyback hook) — both run on every payment.
+Single-transaction deployment of Juicebox projects with cross-chain suckers and optional 721 tiers hooks. Wraps the project's data hooks to give suckers tax-free cash outs and mint permission without interfering with custom hooks. Stores the 721 hook per-ruleset in `_tiered721HookOf` and the optional custom hook per-ruleset in `_extraDataHookOf`, each with their own `useDataHookForCashOut` flag. Supports composing a 721 hook alongside a custom data hook (e.g., buyback hook) — both run on every payment.
 
 ## Contracts
 
 | Contract | Role |
 |----------|------|
-| `JBOmnichainDeployer` | Deploys projects/rulesets/suckers, wraps data hooks for sucker tax exemption. Implements `IJBRulesetDataHook`, `IERC721Receiver`, `ERC2771Context`, `JBPermissioned`. |
+| `JBOmnichainDeployer` | Deploys projects/rulesets/suckers, wraps data hooks for sucker tax exemption. Stores 721 hook per-ruleset in `_tiered721HookOf` and custom hook per-ruleset in `_extraDataHookOf`. Implements `IJBRulesetDataHook`, `IERC721Receiver`, `ERC2771Context`, `JBPermissioned`. |
 
 ## Key Functions
 
@@ -17,27 +17,27 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 | Function | What it does |
 |----------|-------------|
 | `launchProjectFor(owner, projectUri, rulesetConfigs, terminalConfigs, memo, suckerConfig, controller)` | Creates a new project with rulesets, terminals, and suckers in one tx. Temporarily holds the project NFT. Returns `(projectId, suckers)`. |
-| `launch721ProjectFor(owner, deployTiersHookConfig, launchProjectConfig, suckerConfig, controller, dataHook, salt)` | Same as above but also deploys a 721 tiers hook. Pass a custom `dataHook` (e.g., buyback hook) to compose alongside the 721 hook, or `address(0)` for none. Returns `(projectId, hook, suckers)`. |
+| `launch721ProjectFor(owner, deployTiersHookConfig, launchProjectConfig, suckerConfig, controller, dataHookConfig, salt)` | Same as above but also deploys a 721 tiers hook. Pass a `JBDeployerHookConfig` with a custom data hook (e.g., buyback hook) to compose alongside the 721 hook, or `dataHook: address(0)` for none. Each hook gets its own `useDataHookForPay`/`useDataHookForCashOut` flags. Returns `(projectId, hook, suckers)`. |
 | `launchRulesetsFor(projectId, rulesetConfigs, terminalConfigs, memo, controller)` | Launches new rulesets + terminals for an existing project. Requires `QUEUE_RULESETS` + `SET_TERMINALS`. |
-| `launch721RulesetsFor(projectId, deployTiersHookConfig, launchRulesetsConfig, controller, dataHook, salt)` | Launches rulesets with a new 721 tiers hook + optional custom data hook. Requires `QUEUE_RULESETS` + `SET_TERMINALS`. |
+| `launch721RulesetsFor(projectId, deployTiersHookConfig, launchRulesetsConfig, controller, dataHookConfig, salt)` | Launches rulesets with a new 721 tiers hook + optional custom data hook config. Requires `QUEUE_RULESETS` + `SET_TERMINALS`. |
 | `queueRulesetsOf(projectId, rulesetConfigs, memo, controller)` | Queues future rulesets. Requires `QUEUE_RULESETS`. Reverts if rulesets were already queued in the same block. |
-| `queue721RulesetsOf(projectId, deployTiersHookConfig, queueRulesetsConfig, controller, dataHook, salt)` | Queues rulesets with a new 721 tiers hook + optional custom data hook. Same same-block guard. |
+| `queue721RulesetsOf(projectId, deployTiersHookConfig, queueRulesetsConfig, controller, dataHookConfig, salt)` | Queues rulesets with a new 721 tiers hook + optional custom data hook config. Same same-block guard. |
 | `deploySuckersFor(projectId, suckerConfig)` | Deploys new suckers for an existing project. Requires `DEPLOY_SUCKERS`. |
 
 ### Data Hook (IJBRulesetDataHook)
 
 | Function | What it does |
 |----------|-------------|
-| `beforePayRecordedWith(context)` | Calls the 721 hook first for its specs (including split amounts), then calls the custom data hook with a reduced amount context (payment minus split amount) for weight + specs. Adjusts the returned weight proportionally so the terminal only mints tokens for the amount entering the project (`weight = mulDiv(weight, amount - splitAmount, amount)`). Merges both (721 hook specs first, then custom hook specs). |
-| `beforeCashOutRecordedWith(context)` | If holder is a sucker: returns 0% tax immediately. If 721 hook exists: delegates to it (takes priority). Otherwise forwards to the custom data hook, or returns defaults. |
-| `hasMintPermissionFor(projectId, ruleset, addr)` | Returns `true` for registered suckers, OR if the custom data hook grants permission, OR if the 721 hook grants permission. Returns `false` only if none grant it. |
+| `beforePayRecordedWith(context)` | Calls the 721 hook first (via `_tiered721HookOf`) for its specs (including split amounts), then calls the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) with a reduced amount context (payment minus split amount) for weight + specs. Adjusts the returned weight proportionally so the terminal only mints tokens for the amount entering the project (`weight = mulDiv(weight, amount - splitAmount, amount)`). Merges both (721 hook specs first, then custom hook specs). |
+| `beforeCashOutRecordedWith(context)` | If holder is a sucker: returns 0% tax immediately. Checks 721 hook first (if `useDataHookForCashOut: true`), then custom hook from `_extraDataHookOf`. The first with the flag set handles it. If the 721 hook has the flag set and reverts (e.g., fungible cashout), the revert propagates. If neither has the flag set, returns original values. |
+| `hasMintPermissionFor(projectId, ruleset, addr)` | Returns `true` for registered suckers, OR if the custom hook in `_extraDataHookOf` grants permission. Returns `false` only if it doesn't grant it. |
 
 ### Views
 
 | Function | What it does |
 |----------|-------------|
-| `dataHookOf(projectId, rulesetId)` | Returns the stored `(useDataHookForPay, useDataHookForCashOut, dataHook)` for a given project and ruleset. This is the custom data hook, not the 721 hook. |
-| `tiered721HookOf(projectId)` | Returns the project's 721 tiers hook, stored separately from the custom data hook. Returns `address(0)` if no 721 hook was deployed. |
+| `extraDataHookOf(projectId, rulesetId)` | Returns the stored `JBDeployerHookConfig` for a given project and ruleset. Contains the custom data hook (e.g., buyback hook) with its per-hook flags. Returns empty struct if none configured. |
+| `tiered721HookOf(projectId, rulesetId)` | Returns the 721 tiers hook and its `useDataHookForCashOut` flag for a given project and ruleset. Returns `(address(0), false)` if no 721 hook was deployed. |
 | `supportsInterface(interfaceId)` | Returns `true` for `IJBOmnichainDeployer`, `IJBRulesetDataHook`, `IERC721Receiver`, `IERC165`. |
 | `onERC721Received(...)` | Accepts project NFTs from `PROJECTS` only. Reverts for any other NFT contract. |
 
@@ -56,7 +56,8 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 
 | Struct | Key Fields | Used In |
 |--------|------------|---------|
-| `JBDeployerHookConfig` | `bool useDataHookForPay`, `bool useDataHookForCashOut`, `IJBRulesetDataHook dataHook` | `_dataHookOf` mapping keyed by `(projectId, rulesetId)`. Stores the custom data hook only — the 721 hook is in `tiered721HookOf`. |
+| `JBDeployerHookConfig` | `IJBRulesetDataHook dataHook`, `bool useDataHookForPay`, `bool useDataHookForCashOut` | `_extraDataHookOf` mapping keyed by `(projectId, rulesetId)` → single custom hook config. |
+| `JBTiered721HookConfig` | `IJB721TiersHook hook`, `bool useDataHookForCashOut` | `_tiered721HookOf` mapping keyed by `(projectId, rulesetId)` → per-ruleset 721 hook config. |
 | `JBSuckerDeploymentConfig` | `JBSuckerDeployerConfig[] deployerConfigurations`, `bytes32 salt` | All launch and deploy functions |
 
 ## Permission IDs
@@ -72,7 +73,7 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 
 | Error | When |
 |-------|------|
-| `JBOmnichainDeployer_InvalidHook` | `_setup()` detects `rulesetConfig.metadata.dataHook == address(this)` -- prevents infinite forwarding loops |
+| `JBOmnichainDeployer_InvalidHook` | `_setup()` or `_setup721()` detects the hook is `address(this)` -- prevents infinite forwarding loops |
 | `JBOmnichainDeployer_UnexpectedNFTReceived` | `onERC721Received` called by a contract other than `PROJECTS` |
 | `JBOmnichainDeployer_RulesetIdsUnpredictable` | `queueRulesetsOf`/`queue721RulesetsOf` called when `latestRulesetIdOf(projectId) >= block.timestamp` -- ruleset ID prediction would fail |
 | `JBOmnichainDeployer_ProjectIdMismatch` | `launchProjectFor`/`launch721ProjectFor` -- the project ID returned by the controller does not match the predicted `PROJECTS.count() + 1` |
@@ -82,25 +83,25 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 
 1. `launchProjectFor` and `launch721ProjectFor` require **no permissions** -- anyone can launch a project to any owner address.
 2. `queueRulesetsOf` and `queue721RulesetsOf` **revert if called in the same block** as a previous ruleset queue (whether via deployer or directly). The `launch*` functions don't have this guard because they predict IDs from `PROJECTS.count()`, which is always 0 for a new project.
-3. Ruleset IDs in `_dataHookOf` are keyed by `block.timestamp + i`. If the controller assigns different IDs than predicted, the stored hook config will be orphaned and the deployer will behave as if no hook was set (returning default values).
+3. Ruleset IDs in `_extraDataHookOf` are keyed by `block.timestamp + i`. If the controller assigns different IDs than predicted, the stored hook configs will be orphaned and the deployer will behave as if no hooks were set (returning default values).
 4. Sucker deployment salts are hashed with `_msgSender()`: `keccak256(abi.encode(salt, _msgSender()))`. Cross-chain deterministic addresses require using the **same sender** on each chain. For `launch721ProjectFor`, the 721 hook salt uses `keccak256(abi.encode(_msgSender(), salt))` (reversed order).
 5. `salt = bytes32(0)` **skips sucker deployment entirely**. Use a nonzero salt to deploy suckers.
-6. The deployer **always forces `useDataHookForCashOut = true`** on every ruleset it touches, even if the original config had it as `false`. This is required so the deployer can intercept cash outs to check for suckers.
-7. Suckers get an **early return** in `beforeCashOutRecordedWith` -- they bypass both the 721 hook and custom data hook entirely. This means suckers can cash out even if either hook would revert.
-8. If no hooks are stored, `hasMintPermissionFor` returns `false` for non-suckers. It does **not** return the default `true`. Both the custom data hook and 721 hook are checked — either one can grant permission.
+6. The deployer **always forces `useDataHookForCashOut = true`** at the protocol level so it can intercept cash outs for sucker tax exemption. However, the 721 hook's `useDataHookForCashOut` flag (stored in `_tiered721HookOf`) and the custom hook's flag (stored in `_extraDataHookOf`) each control whether that hook processes cash outs. Set `useDataHookForCashOut: false` on the 721 metadata to skip it for fungible cashouts (it reverts with `JB721Hook_UnexpectedTokenCashedOut` otherwise).
+7. Suckers get an **early return** in `beforeCashOutRecordedWith` -- they bypass all stored hooks entirely. This means suckers can cash out even if any hook would revert.
+8. If no custom hook is stored or it doesn't grant permission, `hasMintPermissionFor` returns `false` for non-suckers. Only the custom hook in `_extraDataHookOf` is checked — the 721 hook is not consulted.
 9. 721 ruleset config conversion enforces `useDataHookForPay = true` and `allowSetCustomToken = false`. These cannot be overridden.
 10. Hook ownership is transferred to the **project** (not the owner) via `JBOwnable.transferOwnershipToProject(projectId)`. The project owner controls the hook through project ownership.
 11. The deployer holds the project NFT temporarily during launch. If the controller's `launchProjectFor` reverts, the entire transaction reverts -- no stuck NFTs.
 12. The constructor grants `MAP_SUCKER_TOKEN` permission to `SUCKER_REGISTRY` with `projectId=0`, meaning the registry can map tokens for **any project** deployed through this deployer.
 13. All data hook functions (`beforePayRecordedWith`, `beforeCashOutRecordedWith`, `hasMintPermissionFor`) are `view`. If the project's real hook needs to modify state in these functions, it will fail.
-14. Setting a ruleset's `dataHook` to `address(this)` (the deployer itself) reverts with `JBOmnichainDeployer_InvalidHook`. This prevents infinite forwarding loops.
+14. Setting a hook's `dataHook` to `address(this)` (the deployer itself) reverts with `JBOmnichainDeployer_InvalidHook` in both `_setup()` and `_setup721()`. This prevents infinite forwarding loops.
 15. `onERC721Received` only accepts NFTs from the `PROJECTS` contract. Sending any other ERC-721 to the deployer will revert.
 16. ERC2771 meta-transaction support allows gasless deployments via a trusted forwarder. Salt hashing uses `_msgSender()` (not `msg.sender`), so forwarder-relayed transactions use the original sender's address for deterministic sucker addresses.
 17. **Prefer `launch721ProjectFor` over `launchProjectFor` even with empty tiers.** Using `launch721ProjectFor` with an empty tiers array wires up the 721 hook from the start, so the project owner can add and sell NFTs later without needing to reconfigure the data hook in a new ruleset. `launchProjectFor` skips hook deployment entirely.
-18. The 721 hook is stored **per-project** in `tiered721HookOf[projectId]`, not per-ruleset. It persists across all rulesets. The custom data hook is stored **per-ruleset** in `_dataHookOf[projectId][rulesetId]`.
-19. For payments, `beforePayRecordedWith` calls the 721 hook first to get its specs (including split fund amounts and tier metadata), then calls the custom data hook with a reduced amount context (payment minus split amount) so the buyback hook only considers the available amount. The deployer then adjusts the weight proportionally for splits (`weight = mulDiv(weight, amount - splitAmount, amount)`). The 721 hook's specs come first in the merged result.
-20. For cash outs, the 721 hook **takes priority** over the custom data hook. If a 721 hook exists, `beforeCashOutRecordedWith` delegates entirely to it, ignoring the custom data hook.
-21. The `launch721*` and `queue721*` functions now accept a `dataHook` parameter (type `address`) for the custom data hook to compose alongside the 721 hook. Pass `address(0)` for no custom hook.
+18. The 721 hook is stored per-ruleset in `_tiered721HookOf[projectId][rulesetId]` with its `useDataHookForCashOut` flag. The custom data hook (if any) is stored separately in `_extraDataHookOf[projectId][rulesetId]`. They are never in the same array.
+19. For payments, `beforePayRecordedWith` calls the 721 hook first (via `_tiered721HookOf`) to get its specs (including split fund amounts and tier metadata), then calls the custom hook from `_extraDataHookOf` (if `useDataHookForPay: true`) with a reduced amount context (payment minus split amount) so the buyback hook only considers the available amount. The deployer then adjusts the weight proportionally for splits (`weight = mulDiv(weight, amount - splitAmount, amount)`). The 721 hook's specs come first in the merged result.
+20. For cash outs, `beforeCashOutRecordedWith` checks the 721 hook first (from `_tiered721HookOf`, if `useDataHookForCashOut: true`), then the custom hook (from `_extraDataHookOf`). If the 721 hook has the flag set and reverts (e.g., `JB721Hook_UnexpectedTokenCashedOut` for fungible cashouts), the revert propagates. Set `useDataHookForCashOut: false` on the 721 metadata to skip it and let the custom hook handle cashouts.
+21. The `launch721*` and `queue721*` functions accept a `dataHookConfig` parameter (type `JBDeployerHookConfig`) for the custom data hook to compose alongside the 721 hook. Each hook gets its own `useDataHookForPay`/`useDataHookForCashOut` flags. Pass `dataHook: address(0)` for no custom hook.
 
 ## Example Integration
 
@@ -149,7 +150,11 @@ address[] memory newSuckers = omnichainDeployer.deploySuckersFor({
     deployTiersHookConfig: tiersHookConfig,
     queueRulesetsConfig: queueConfig,
     controller: controller,
-    dataHook: address(buybackHook), // custom data hook (or address(0) for none)
+    dataHookConfig: JBDeployerHookConfig({
+        dataHook: IJBRulesetDataHook(address(buybackHook)),
+        useDataHookForPay: true,
+        useDataHookForCashOut: false
+    }),
     salt: bytes32("my-hook-salt")
 });
 ```

package/STYLE_GUIDE.md

@@ -314,14 +314,11 @@ Standard config across all repos:
 ```toml
 [profile.default]
 solc = '0.8.26'
-evm_version = 'paris'
+evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]
 fs_permissions = [{ access = "read-write", path = "./"}]
 
-[profile.ci_sizes]
-optimizer_runs = 200
-
 [fuzz]
 runs = 4096
 
@@ -336,12 +333,14 @@ multiline_func_header = "all"
 wrap_comments = true
 ```
 
-**Variations:**
-- `evm_version = 'cancun'` for repos using transient storage (buyback-hook, router-terminal, univ4-router)
-- `via_ir = true` for repos hitting stack-too-deep (buyback-hook, banny-retail, univ4-lp-split-hook, deploy-all)
-- `optimizer = false` only for deploy-all-v6 (stack-too-deep with optimization)
+**Optional sections (add only when needed):**
+- `[rpc_endpoints]` — repos with fork tests. Maps named endpoints to env vars (e.g. `ethereum = "${RPC_ETHEREUM_MAINNET}"`).
+- `[profile.ci_sizes]` — only when CI needs different optimizer settings than defaults for the size check step (e.g. `optimizer_runs = 200` when the default profile uses a lower value).
 
-**This repo's deviations:** `[profile.fork]` with `via_ir = true` and `evm_version = 'cancun'` for fork tests. `[lint] lint_on_build = false`.
+**Common variations:**
+- `via_ir = true` when hitting stack-too-deep
+- `optimizer = false` when optimization causes stack-too-deep
+- `optimizer_runs` reduced when deep struct nesting causes stack-too-deep at 200 runs
 
 ### CI Workflows
 
@@ -374,7 +373,7 @@ jobs:
         env:
           RPC_ETHEREUM_MAINNET: ${{ secrets.RPC_ETHEREUM_MAINNET }}
       - name: Check contract sizes
-        run: FOUNDRY_PROFILE=ci_sizes forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils
+        run: forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils
 ```
 
 **lint.yml:**
@@ -396,11 +395,60 @@ jobs:
         run: forge fmt --check
 ```
 
+**slither.yml** (repos with `src/` contracts only):
+```yaml
+name: slither
+on:
+    pull_request:
+      branches:
+        - main
+    push:
+      branches:
+        - main
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-node@v4
+        with:
+          node-version: latest
+      - name: Install npm dependencies
+        run: npm install --omit=dev
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Run slither
+        uses: crytic/slither-action@v0.3.1
+        with:
+            slither-config: slither-ci.config.json
+            fail-on: medium
+```
+
+**slither-ci.config.json:**
+```json
+{
+  "detectors_to_exclude": "timestamp,uninitialized-local,naming-convention,solc-version,shadowing-local",
+  "exclude_informational": true,
+  "exclude_low": false,
+  "exclude_medium": false,
+  "exclude_high": false,
+  "disable_color": false,
+  "filter_paths": "(mocks/|test/|node_modules/|lib/)",
+  "legacy_ast": false
+}
+```
+
+**Variations:**
+- Deployer-only repos (no `src/`, only `script/`) skip slither entirely — the action's internal `forge build` skips `test/` and `script/` by default, leaving nothing to compile.
+- Use inline `// slither-disable-next-line <detector>` to suppress known false positives rather than adding to `detectors_to_exclude` in the config. The comment must be on the line immediately before the flagged expression.
+
 ### package.json
 
 ```json
 {
-  "name": "@bananapus/omnichain-deployers-v6",
+  "name": "@bananapus/package-name-v6",
   "version": "x.x.x",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/Org/repo.git" },
@@ -420,13 +468,62 @@ jobs:
 
 ### remappings.txt
 
-Every repo has a `remappings.txt`. Minimal content:
+Every repo has a `remappings.txt` as the **single source of truth** for import remappings. Never add remappings to `foundry.toml`.
+
+**Principle:** Import paths in Solidity source must match npm package names exactly. With `libs = ["node_modules", "lib"]`, Foundry auto-resolves `@scope/package/path/File.sol` → `node_modules/@scope/package/path/File.sol`. No remapping needed for packages installed as real directories.
+
+**Note:** Auto-resolution does **not** work for symlinked packages (e.g. npm workspace links). Workspace repos like `deploy-all-v6` and `nana-cli-v6` need explicit `@scope/package/=node_modules/@scope/package/` remappings for each symlinked dependency.
+
+**Minimal content** (most repos):
+
+```
+forge-std/=lib/forge-std/src/
+```
+
+Only add extra remappings for:
+- **`forge-std`** — always needed (git submodule with `src/` subdirectory)
+- **Repo-specific `lib/` submodules** that have no npm package (e.g., `hookmate/=lib/hookmate/src/`)
+- **Symlinked npm packages** — need explicit `@scope/package/=node_modules/@scope/package/` entries
+- **Nested transitive deps** — e.g., `@chainlink/contracts-ccip/` nested inside `@bananapus/suckers-v6/node_modules/`
+
+**Never add remappings for:**
+- npm packages that match their import path and are installed as real directories — they auto-resolve
+- Short-form aliases (e.g., `@bananapus/core/` → `@bananapus/core-v6/src/`) — fix the import instead
+- Packages available via npm that are also git submodules — remove the submodule, use npm
+
+**Import path convention:**
+
+| Package | Import path | Resolves to |
+|---------|------------|-------------|
+| `@bananapus/core-v6` | `@bananapus/core-v6/src/libraries/JBConstants.sol` | `node_modules/@bananapus/core-v6/src/...` |
+| `@openzeppelin/contracts` | `@openzeppelin/contracts/token/ERC20/IERC20.sol` | `node_modules/@openzeppelin/contracts/...` |
+| `@uniswap/v4-core` | `@uniswap/v4-core/src/interfaces/IPoolManager.sol` | `node_modules/@uniswap/v4-core/src/...` |
+
+### Linting
+
+Solar (Foundry's built-in linter) runs automatically during `forge build`. It scans all `.sol` files in `libs` directories, including `node_modules`.
 
+**All test helpers must use relative imports** (e.g. `../../src/structs/JBRuleset.sol`), not bare `src/` imports. This ensures solar can resolve paths when the helper is consumed via npm in downstream repos.
+
+### Fork Tests
+
+Fork tests use named RPC endpoints defined in `[rpc_endpoints]` of `foundry.toml`. No skip guards — fork tests should hard-fail if the RPC endpoint is unavailable, making CI failures explicit.
+
+```solidity
+function setUp() public {
+    vm.createSelectFork("ethereum");
+    // ... setup code
+}
 ```
-@sphinx-labs/contracts/=lib/sphinx/packages/contracts/contracts/foundry
+
+The endpoint name (e.g. `"ethereum"`) maps to an env var via `foundry.toml`:
+
+```toml
+[rpc_endpoints]
+ethereum = "${RPC_ETHEREUM_MAINNET}"
 ```
 
-Additional mappings as needed for repo-specific dependencies.
+For multi-chain fork tests, add all needed endpoints.
 
 ### Formatting
 
@@ -437,15 +534,6 @@ Run `forge fmt` before committing. The `[fmt]` config in `foundry.toml` enforces
 
 CI checks formatting via `forge fmt --check`.
 
-### CI Secrets
-
-| Secret | Purpose |
-|--------|--------|
-| `NPM_TOKEN` | npm publish access (used by `publish.yml`) |
-| `RPC_ETHEREUM_MAINNET` | Ethereum mainnet RPC URL for fork tests (used by `test.yml`) |
-
-Fork tests require `RPC_ETHEREUM_MAINNET` — they fail if it's missing.
-
 ### Branching
 
 - `main` is the primary branch
@@ -463,4 +551,8 @@ Fork tests require `RPC_ETHEREUM_MAINNET` — they fail if it's missing.
 
 ### Contract Size Checks
 
-CI runs `FOUNDRY_PROFILE=ci_sizes forge build --sizes` to catch contracts approaching the 24KB limit. The `ci_sizes` profile uses `optimizer_runs = 200` for realistic size measurement even when the default profile has different optimizer settings.
+CI runs `forge build --sizes` to catch contracts approaching the 24KB limit. When the repo's default `optimizer_runs` differs from what you want for size checking, use `FOUNDRY_PROFILE=ci_sizes forge build --sizes` with a `[profile.ci_sizes]` section in `foundry.toml`.
+
+## Repo-Specific Deviations
+
+None. This repo follows the standard configuration exactly.

package/foundry.toml

@@ -18,3 +18,6 @@ fail_on_revert = false
 number_underscore = "thousands"
 multiline_func_header = "all"
 wrap_comments = true
+
+[rpc_endpoints]
+ethereum = "${RPC_ETHEREUM_MAINNET}"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bananapus/omnichain-deployers-v6",
-    "version": "0.0.7",
+    "version": "0.0.8",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -17,12 +17,12 @@
         "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-omnichain-deployers-v6'"
     },
     "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.13",
+        "@bananapus/721-hook-v6": "^0.0.14",
         "@bananapus/buyback-hook-v6": "^0.0.10",
-        "@bananapus/core-v6": "^0.0.14",
+        "@bananapus/core-v6": "^0.0.15",
         "@bananapus/ownable-v6": "^0.0.7",
-        "@bananapus/permission-ids-v6": "^0.0.6",
-        "@bananapus/suckers-v6": "^0.0.8",
+        "@bananapus/permission-ids-v6": "^0.0.7",
+        "@bananapus/suckers-v6": "^0.0.9",
         "@openzeppelin/contracts": "^5.6.1",
         "@uniswap/v4-core": "^1.0.2"
     },

package/remappings.txt

@@ -1 +1 @@
-@sphinx-labs/contracts/=node_modules/@sphinx-labs/contracts/contracts/foundry
+forge-std/=lib/forge-std/src/

package/script/Deploy.s.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.26;
 
-import "@sphinx-labs/contracts/SphinxPlugin.sol";
+import "@sphinx-labs/contracts/contracts/foundry/SphinxPlugin.sol";
 import {Script, stdJson, VmSafe} from "forge-std/Script.sol";
 
 import "@bananapus/core-v6/script/helpers/CoreDeploymentLib.sol";

package/script/helpers/DeployersDeploymentLib.sol

@@ -3,7 +3,7 @@ pragma solidity 0.8.26;
 
 import {stdJson} from "forge-std/Script.sol";
 import {Vm} from "forge-std/Vm.sol";
-import {SphinxConstants, NetworkInfo} from "@sphinx-labs/contracts/SphinxConstants.sol";
+import {SphinxConstants, NetworkInfo} from "@sphinx-labs/contracts/contracts/foundry/SphinxConstants.sol";
 
 import {JBOmnichainDeployer} from "src/JBOmnichainDeployer.sol";