@bananapus/omnichain-deployers-v6 0.0.34 → 0.0.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/omnichain-deployers-v6",
-  "version": "0.0.34",
+  "version": "0.0.37",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,7 +16,7 @@
     "src/"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": "25.9.0"
   },
   "scripts": {
     "test": "forge test",
@@ -30,7 +30,7 @@
     "@bananapus/core-v6": "0.0.39",
     "@bananapus/ownable-v6": "0.0.24",
     "@bananapus/permission-ids-v6": "0.0.22",
-    "@bananapus/suckers-v6": "0.0.32",
+    "@bananapus/suckers-v6": "0.0.34",
     "@openzeppelin/contracts": "5.6.1"
   },
   "devDependencies": {

package/src/JBOmnichainDeployer.sol

@@ -32,11 +32,17 @@ import {JBSuckerDeploymentConfig} from "./structs/JBSuckerDeploymentConfig.sol";
 import {JBTiered721HookConfig} from "./structs/JBTiered721HookConfig.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
 
-/// @notice Deploys, manages, and operates Juicebox projects with suckers.
-// Project NFTs sent to this contract are not recoverable. The deployer does not
-// implement any NFT rescue mechanism beyond onERC721Received for JBProjects. This is acceptable
-// because the deployer should never own project NFTs — it creates projects and transfers ownership
-// in the same transaction.
+/// @notice One-stop deployer and data hook wrapper for omnichain Juicebox projects. Launches a project with a tiered
+/// 721 hook and cross-chain suckers in a single transaction, then inserts itself as every ruleset's data hook so it can
+/// coordinate between the 721 hook, an optional extra hook (e.g. buyback), and the sucker registry at pay/cash-out
+/// time. At pay time it merges weight and hook specifications from both the 721 hook and the extra hook. At cash-out
+/// time it
+/// computes cross-chain total supply and surplus (so the bonding curve reflects all chains), grants suckers 0% cash-out
+/// tax, and delegates tax-rate adjustments to the underlying hooks.
+/// @dev Project NFTs sent to this contract are not recoverable. The deployer does not implement any NFT rescue
+/// mechanism beyond `onERC721Received` for `JBProjects`. This is acceptable because the deployer should never own
+/// project NFTs —
+/// it creates projects and transfers ownership in the same transaction.
 contract JBOmnichainDeployer is
     ERC2771Context,
     JBPermissioned,
@@ -142,10 +148,12 @@ contract JBOmnichainDeployer is
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Deploy new suckers for an existing project.
-    /// @dev Only the juicebox's owner or an operator with `JBPermissionIds.DEPLOY_SUCKERS` can call this entrypoint.
-    /// The downstream registry call also maps the configured tokens on each newly created sucker, so the same
-    /// end-to-end operation depends on the project's token-mapping authority being arranged for the registry.
+    /// @notice Deploy new cross-chain suckers for an existing project. Each sucker enables token bridging between this
+    /// chain and a peer chain. The registry also maps configured tokens on each new sucker in the same call.
+    /// @dev Only the project's owner or an operator with `JBPermissionIds.DEPLOY_SUCKERS` can call this. The salt
+    /// includes `msg.sender` for replay protection — the same sender must call on both chains for deterministic
+    /// address
+    /// matching.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param suckerDeploymentConfiguration The suckers to set up for the project.
     function deploySuckersFor(
@@ -388,8 +396,13 @@ contract JBOmnichainDeployer is
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Allow cash outs from suckers without a tax, and compute cross-chain tax supply for non-sucker cash outs.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a cash out.
+    /// @notice Called by the terminal before recording a cash out. Suckers get 0% tax so bridged tokens redeem at face
+    /// value. For all other holders, this function aggregates total supply and surplus across all peer chains so the
+    /// bonding curve reflects the project's global state, then delegates to the 721 hook and extra hook for further
+    /// adjustments.
+    /// @dev Part of `IJBRulesetDataHook`. The 721 hook's returned `totalSupply` and `effectiveSurplusValue` are used
+    /// when it handles cash outs (NFT redemptions use local denominators). Otherwise this contract's cross-chain values
+    /// take precedence.
     /// @param context Standard Juicebox cash out context. See `JBBeforeCashOutRecordedContext`.
     /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens which get cashed
     /// out.
@@ -503,13 +516,18 @@ contract JBOmnichainDeployer is
         return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
     }
 
-    /// @notice Forward the call to the original data hook.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a payment.
+    /// @notice Called by the terminal before recording a payment. Coordinates the 721 hook (which handles tier-based
+    /// NFT minting and split deductions) with the extra hook (e.g. buyback, which may swap for a better token price).
+    /// Merges
+    /// their weight adjustments and hook specifications into a single response for the terminal.
+    /// @dev Part of `IJBRulesetDataHook`. The 721 hook's weight already accounts for tier-split deductions. The extra
+    /// hook receives the post-split amount so it only routes funds actually entering the project. If both return
+    /// specifications, the 721 spec comes first.
     /// @param context Standard Juicebox payment context. See `JBBeforePayRecordedContext`.
     /// @return weight The weight which project tokens are minted relative to. This can be used to customize how many
     /// tokens get minted by a payment.
-    /// @return hookSpecifications Amounts (out of what's being paid in) to be sent to pay hooks instead of being paid
-    /// into the project. Useful for automatically routing funds from a treasury as payments come in.
+    /// @return hookSpecifications Amounts (out of the payment) to send to pay hooks instead of the project. Useful for
+    /// automatically routing funds from a treasury as payments come in.
     function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
         external
         view
@@ -624,8 +642,9 @@ contract JBOmnichainDeployer is
         return _extraDataHookOf[projectId][rulesetId];
     }
 
-    /// @notice A flag indicating whether an address has permission to mint a project's tokens on-demand.
-    /// @dev A project's data hook can allow any address to mint its tokens.
+    /// @notice Returns whether an address may mint a project's tokens on-demand. Suckers always get mint permission (so
+    /// bridged tokens can be minted on the destination chain). Otherwise delegates to the extra data hook.
+    /// @dev Part of `IJBRulesetDataHook`. The 721 hook never grants mint permission, so only the extra hook is checked.
     /// @param projectId The ID of the project whose token can be minted.
     /// @param ruleset The ruleset to check the token minting permission of.
     /// @param addr The address to check the token minting permission of.
@@ -899,9 +918,11 @@ contract JBOmnichainDeployer is
         });
     }
 
-    /// @notice Sets up a project's rulesets with a 721 hook.
+    /// @notice Wires up each ruleset so this contract acts as the data hook wrapper. Stores the 721 hook and any extra
+    /// data hook (from the ruleset's metadata) in per-project/per-ruleset mappings, then overwrites each ruleset's
+    /// metadata to point at this contract with both pay and cash-out delegation enabled.
     /// @dev Stores the 721 hook in `_tiered721HookOf` per-ruleset and any custom hook (from metadata) in
-    /// `_extraDataHookOf`.
+    /// `_extraDataHookOf`. Ruleset IDs are predicted as `block.timestamp + i`.
     /// @param projectId The ID of the project to set up.
     /// @param rulesetConfigurations The rulesets to set up.
     /// @param hook721 The 721 tiers hook.

package/src/interfaces/IJBOmnichainDeployer.sol

@@ -9,7 +9,10 @@ import {JBDeployerHookConfig} from "../structs/JBDeployerHookConfig.sol";
 import {JBOmnichain721Config} from "../structs/JBOmnichain721Config.sol";
 import {JBSuckerDeploymentConfig} from "../structs/JBSuckerDeploymentConfig.sol";
 
-/// @notice Deploys Juicebox projects with omnichain sucker support.
+/// @notice Interface for the omnichain deployer — a one-stop contract that launches Juicebox projects with a tiered
+/// 721
+/// hook and cross-chain suckers, then serves as the data hook wrapper that coordinates pay/cash-out logic across all
+/// chains.
 interface IJBOmnichainDeployer {
     /// @notice Get the extra data hook for a project and ruleset.
     /// @param projectId The ID of the project to get the extra data hook for.

package/src/structs/JBDeployerHookConfig.sol

@@ -3,6 +3,11 @@ pragma solidity ^0.8.0;
 
 import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDataHook.sol";
 
+/// @notice Configuration for an extra data hook (e.g. a buyback hook) that the omnichain deployer delegates to
+/// alongside the primary 721 hook. Stored per project per ruleset.
+/// @param dataHook The extra data hook contract to delegate to.
+/// @param useDataHookForPay Whether to call this hook's `beforePayRecordedWith` during payments.
+/// @param useDataHookForCashOut Whether to call this hook's `beforeCashOutRecordedWith` during cash outs.
 struct JBDeployerHookConfig {
     IJBRulesetDataHook dataHook;
     bool useDataHookForPay;

package/src/structs/JBOmnichain721Config.sol

@@ -4,7 +4,7 @@ pragma solidity ^0.8.0;
 import {JBDeploy721TiersHookConfig} from "@bananapus/721-hook-v6/src/structs/JBDeploy721TiersHookConfig.sol";
 
 /// @notice Configuration for deploying a 721 tiers hook alongside omnichain rulesets.
-/// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook being deployed.
+/// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook to deploy.
 /// @param useDataHookForCashOut Whether the 721 hook should handle cash outs (via beforeCashOutRecordedWith).
 /// @param salt A salt to use for the deterministic 721 hook deployment. Combined with `msg.sender` internally, so
 /// cross-chain deterministic addresses require the same sender on each chain.

package/src/structs/JBTiered721HookConfig.sol

@@ -3,6 +3,10 @@ pragma solidity ^0.8.0;
 
 import {IJB721TiersHook} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHook.sol";
 
+/// @notice Stored configuration for a project's tiered 721 hook within a specific ruleset.
+/// @param hook The tiered 721 hook contract used for NFT minting on payments.
+/// @param useDataHookForCashOut Whether the 721 hook should participate in cash-out tax calculations and NFT
+/// redemptions.
 struct JBTiered721HookConfig {
     IJB721TiersHook hook;
     bool useDataHookForCashOut;