@bananapus/omnichain-deployers-v6 0.0.4 → 0.0.6

package/ADMINISTRATION.md

@@ -0,0 +1,92 @@
+# Administration
+
+Admin privileges and their scope in nana-omnichain-deployers-v6.
+
+## 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 (255) 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. |
+| `launch721RulesetsFor` | Project owner or operator | `QUEUE_RULESETS` + `SET_TERMINALS` | Per-project | Deploys a 721 tiers hook, launches new rulesets with terminal configuration for an existing project. |
+| `launchRulesetsFor` | Project owner or operator | `QUEUE_RULESETS` + `SET_TERMINALS` | Per-project | Launches new rulesets with terminal configuration for an existing project (no 721 hook). |
+| `queue721RulesetsOf` | Project owner or operator | `QUEUE_RULESETS` | Per-project | Deploys a 721 tiers hook and queues new rulesets for an existing project. |
+| `queueRulesetsOf` | Project owner or operator | `QUEUE_RULESETS` | Per-project | Queues new rulesets for an existing project (no 721 hook). |
+
+### Permissionless Functions
+
+| Function | Who Can Call | What It Does |
+|----------|-------------|--------------|
+| `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. |
+
+## Deployment Administration
+
+**Who can deploy omnichain projects:** Anyone. The `launchProjectFor` and `launch721ProjectFor` functions are permissionless. The caller specifies an `owner` address that receives the project ERC-721.
+
+**Deployment flow:**
+1. The deployer temporarily owns the project ERC-721 (minted to `address(this)`).
+2. It configures rulesets, sets itself as the data hook wrapper, and optionally deploys suckers.
+3. It transfers the project ERC-721 to the specified `owner`.
+
+**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).
+- Sucker deployment configuration (which chains, which deployers, token mappings).
+- Salt for deterministic cross-chain address matching.
+
+## Cross-Chain Controls
+
+| Action | Who | Mechanism |
+|--------|-----|-----------|
+| Deploy suckers for existing project | Project owner or DEPLOY_SUCKERS operator | `deploySuckersFor` calls `SUCKER_REGISTRY.deploySuckersFor` |
+| Deploy suckers during project launch | Project deployer (anyone) | Included in `launchProjectFor` / `launch721ProjectFor` 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` |
+
+**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.
+
+## 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. |
+
+**Data hook mappings** (`_dataHookOf[projectId][rulesetId]`) are write-once per ruleset ID. They are set during `_setup` and never updated or deleted.
+
+## Admin Boundaries
+
+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 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 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

@@ -0,0 +1,69 @@
+# nana-omnichain-deployers-v6 — Architecture
+
+## Purpose
+
+Omnichain project deployer for Juicebox V6. Wraps the project deployment flow to automatically configure cross-chain suckers, acting as a data hook that gives suckers 0% cash-out tax (bridging privilege) and mint permission.
+
+## Contract Map
+
+```
+src/
+├── JBOmnichainDeployer.sol       — Deploys projects with sucker integration, acts as data hook
+├── interfaces/
+│   └── IJBOmnichainDeployer.sol  — Interface
+└── structs/
+    ├── JBDeployerHookConfig.sol      — Hook configuration for deployment
+    └── JBSuckerDeploymentConfig.sol  — Sucker deployment parameters
+```
+
+## Key Data Flows
+
+### Omnichain Project Deployment
+```
+Deployer → JBOmnichainDeployer.deployProjectFor()
+  → Launch JB project via JB721TiersHookProjectDeployer
+  → Set JBOmnichainDeployer as data hook
+  → Deploy suckers via JBSuckerRegistry
+  → Configure sucker permissions (mint, 0% cashout tax)
+  → Transfer project ownership back to deployer
+```
+
+### Data Hook Behavior
+```
+Payment → JBOmnichainDeployer.beforePayRecordedWith()
+  → Pass through (no modification to pay behavior)
+  → Return empty pay hook specifications
+
+Cash Out → JBOmnichainDeployer.beforeCashOutRecordedWith()
+  → If caller is a registered sucker: return 0% cash-out tax
+  → Otherwise: return configured cash-out tax rate
+```
+
+### Ruleset Management
+```
+Owner → JBOmnichainDeployer.queueRulesetsOf()
+  → Queue new rulesets via JBController
+  → Maintains deployer as data hook
+  → Supports adding/removing suckers
+
+Owner → JBOmnichainDeployer.launchRulesetsFor()
+  → Launch rulesets for an existing project
+  → Configure sucker integration
+```
+
+## Extension Points
+
+| Point | Interface | Purpose |
+|-------|-----------|---------|
+| Data hook (pay) | `IJBRulesetDataHook.beforePayRecordedWith` | Pass-through for payments |
+| Data hook (cashout) | `IJBRulesetDataHook.beforeCashOutRecordedWith` | 0% tax for suckers |
+| Sucker registry | `IJBSuckerRegistry` | Sucker deployment and discovery |
+| 721 hook deployer | `IJB721TiersHookDeployer` | Optional NFT tier deployment |
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # Juicebox Omnichain Deployers
 
-Deploy Juicebox projects with cross-chain suckers and optional 721 tiers hooks in a single transaction. Acts as a transparent data hook wrapper that gives suckers tax-free cash outs and on-demand mint permission -- without interfering with any custom data hook the project uses.
+Deploy Juicebox projects with cross-chain suckers and optional 721 tiers hooks in a single transaction. Acts as a transparent data hook wrapper that gives suckers tax-free cash outs and on-demand mint permission -- without interfering with any custom data hook the project uses. Supports composing a 721 tiers hook alongside a custom data hook (e.g., a buyback hook) so both run on every payment.
 
 [Docs](https://docs.juicebox.money) | [Discord](https://discord.gg/juicebox)
 
@@ -8,12 +8,13 @@ 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 whatever hook the project actually wants in a mapping keyed by `(projectId, rulesetId)`. 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 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:
 
-- **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 real data hook would revert.
-- **Forwards everything else** to the real data hook, or returns default values if none was set.
+- **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.
 
-This wrapping is invisible to the project and its users. The project's custom hook (buyback hook, 721 hook, etc.) works exactly as configured.
+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.
 
 ### How It Works
 
@@ -47,10 +48,14 @@ sequenceDiagram
     Deployer->>Registry: isSuckerOf(projectId, holder)?
     alt Holder is a sucker
         Deployer-->>Terminal: 0% tax (early return)
-    else Not a sucker
+    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
         Deployer->>Hook: beforeCashOutRecordedWith(context)
         Hook-->>Deployer: taxRate, count, supply, specs
-        Deployer-->>Terminal: forward hook response
+        Deployer-->>Terminal: forward custom hook response
     end
 ```
 
@@ -59,9 +64,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. Converts 721-specific ruleset configs (`JBPayDataHookRulesetConfig`) to standard configs, enforcing `useDataHookForPay = true` and `allowSetCustomToken = false`
-3. Wraps the 721 hook with itself (as above)
-4. Transfers hook ownership to the project via `JBOwnable.transferOwnershipToProject()`
+2. Stores the 721 hook in `tiered721HookOf[projectId]` (separate from the custom data hook)
+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]`
+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.
 
 ### Deterministic Cross-Chain Addresses
 
@@ -92,7 +100,7 @@ The `queueRulesetsOf` and `queue721RulesetsOf` functions guard against predictio
 
 | Type | Description |
 |------|-------------|
-| `JBDeployerHookConfig` | Per-ruleset config storing the real data hook address and its `useDataHookForPay`/`useDataHookForCashOut` flags. |
+| `JBDeployerHookConfig` | Per-ruleset config storing the custom data hook address and its `useDataHookForPay`/`useDataHookForCashOut` flags. The 721 hook is stored separately 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. |
 
@@ -150,6 +158,9 @@ 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
+  regression/
+    H20_HookOwnershipTransfer.t.sol     # Hook ownership transfer regression
 script/
   Deploy.s.sol                          # Sphinx deployment script
   helpers/

package/RISKS.md

@@ -0,0 +1,35 @@
+# nana-omnichain-deployers-v6 — Risks
+
+## Trust Assumptions
+
+1. **JBOmnichainDeployer as Data Hook** — Acts as data hook for all projects it deploys. A bug in the deployer affects every omnichain project's cash-out behavior.
+2. **Sucker Registry** — Trusts JBSuckerRegistry to correctly track registered suckers. The deployer grants 0% cash-out tax to any address the registry identifies as a sucker.
+3. **Project Owner** — Can queue new rulesets, deploy additional suckers, and manage project configuration through the deployer.
+4. **Core Protocol** — Relies on JBController, JBDirectory, and JBMultiTerminal for correct operation.
+5. **Bridge Infrastructure** — Inherits all sucker trust assumptions (bridge liveness, remote peer authentication).
+
+## Known Risks
+
+| 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 |
+| 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 |
+
+## Privileged Roles
+
+| Role | Capabilities | Scope |
+|------|-------------|-------|
+| Project owner | Queue rulesets, deploy suckers, manage configuration | Per-project |
+| Registered suckers | 0% cash-out tax on token bridging | Per-project |
+| JBSuckerRegistry | Determines which addresses are valid suckers | Protocol-wide |
+
+## Reentrancy Considerations
+
+| Function | Protection | Risk |
+|----------|-----------|------|
+| `deployProjectFor` | Ownership transferred after all setup complete | LOW |
+| `beforeCashOutRecordedWith` | View-like function, returns data only | NONE |
+| `beforePayRecordedWith` | View-like function, returns data only | NONE |

package/SKILLS.md

@@ -2,7 +2,7 @@
 
 ## 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.
+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.
 
 ## Contracts
 
@@ -17,26 +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, salt, suckerConfig, controller)` | Same as above but also deploys a 721 tiers hook and transfers its ownership to the project. Returns `(projectId, hook, 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)`. |
 | `launchRulesetsFor(projectId, rulesetConfigs, terminalConfigs, memo, controller)` | Launches new rulesets + terminals for an existing project. Requires `QUEUE_RULESETS` + `SET_TERMINALS`. |
-| `launch721RulesetsFor(projectId, deployTiersHookConfig, launchRulesetsConfig, controller, salt)` | Launches rulesets with a new 721 tiers hook. 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`. |
 | `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, salt)` | Queues rulesets with a new 721 tiers hook. Same same-block guard. |
+| `queue721RulesetsOf(projectId, deployTiersHookConfig, queueRulesetsConfig, controller, dataHook, salt)` | Queues rulesets with a new 721 tiers hook + optional custom data hook. 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)` | Forwards to the stored real data hook if set and `useDataHookForPay` is true. Otherwise returns the original weight. |
-| `beforeCashOutRecordedWith(context)` | If holder is a sucker: returns 0% tax immediately (never calls real hook). Otherwise forwards to the real hook, or returns original values if none set. |
-| `hasMintPermissionFor(projectId, ruleset, addr)` | Returns `true` for registered suckers. Otherwise forwards to real hook, or returns `false` if none set. |
+| `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. |
 
 ### Views
 
 | Function | What it does |
 |----------|-------------|
-| `dataHookOf(projectId, rulesetId)` | Returns the stored `(useDataHookForPay, useDataHookForCashOut, dataHook)` for a given project and ruleset. |
+| `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. |
 | `supportsInterface(interfaceId)` | Returns `true` for `IJBOmnichainDeployer`, `IJBRulesetDataHook`, `IERC721Receiver`, `IERC165`. |
 | `onERC721Received(...)` | Accepts project NFTs from `PROJECTS` only. Reverts for any other NFT contract. |
 
@@ -55,7 +56,7 @@ 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)` |
+| `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`. |
 | `JBSuckerDeploymentConfig` | `JBSuckerDeployerConfig[] deployerConfigurations`, `bytes32 salt` | All launch and deploy functions |
 
 ## Permission IDs
@@ -85,8 +86,8 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 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 the real data hook entirely. This means suckers can cash out even if the real hook would revert.
-8. If no real data hook is stored (or `address(0)`), `hasMintPermissionFor` returns `false` for non-suckers. It does **not** return the default `true`.
+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.
 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.
@@ -95,6 +96,11 @@ Single-transaction deployment of Juicebox projects with cross-chain suckers and
 14. Setting a ruleset's `dataHook` to `address(this)` (the deployer itself) reverts with `JBOmnichainDeployer_InvalidHook`. 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.
 
 ## Example Integration
 
@@ -133,15 +139,17 @@ address[] memory newSuckers = omnichainDeployer.deploySuckersFor({
     suckerDeploymentConfiguration: suckerConfig
 });
 
-// --- Queue new rulesets with a 721 hook ---
+// --- Queue new rulesets with a 721 hook + buyback hook ---
 
 // Requires QUEUE_RULESETS permission. Must be called in a different block
 // than any previous ruleset queue for this project.
+// Pass the buyback hook as the custom data hook to compose alongside the 721 hook.
 (uint256 rulesetId, IJB721TiersHook hook) = omnichainDeployer.queue721RulesetsOf({
     projectId: projectId,
     deployTiersHookConfig: tiersHookConfig,
     queueRulesetsConfig: queueConfig,
     controller: controller,
+    dataHook: address(buybackHook), // custom data hook (or address(0) for none)
     salt: bytes32("my-hook-salt")
 });
 ```