@bananapus/omnichain-deployers-v6 0.0.57 → 0.0.58

package/README.md

@@ -2,7 +2,6 @@
 
 `@bananapus/omnichain-deployers-v6` launches Juicebox projects with cross-chain suckers and a 721 hook already wired in. It is the package you use when the default project shape should be omnichain from day one.
 
-
 ## Documentation
 
 - [INVARIANTS.md](./INVARIANTS.md) — runtime guarantees enforced by `JBOmnichainDeployer`, per-function caller / effect / invariant inventory, and cross-cutting invariants.
@@ -29,13 +28,13 @@ The wrapper exists so sucker-triggered flows can be exempted from project-specif
 
 Use this repo when the default project shape is "Juicebox project plus 721 hook plus cross-chain bridge." Do not use it when a project is single-chain or does not need the wrapper semantics around suckers.
 
-## Key Contract
+## Key contract
 
 | Contract | Role |
 | --- | --- |
 | `JBOmnichainDeployer` | Launches projects and rulesets, manages per-ruleset hook composition, and deploys suckers with deterministic salts. |
 
-## Mental Model
+## Mental model
 
 This repo owns orchestration plus runtime wrapping:
 
@@ -43,21 +42,21 @@ This repo owns orchestration plus runtime wrapping:
 2. remember which hook composition belongs to which ruleset
 3. special-case sucker behavior so bridge flows are not broken by project-specific logic
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBOmnichainDeployer.sol`
 2. `nana-suckers-v6/src/JBSucker.sol`
 3. `nana-721-hook-v6/src/JB721TiersHook.sol`
 4. the extra hook repo, if the deployment composes one
 
-## Integration Traps
+## Integration traps
 
 - this repo wraps hooks and bridge flows together, so ownership and hook-order assumptions matter as much as deployment salt
 - ruleset ID prediction is a real implementation dependency
 - the deployer can carry forward an existing 721 hook shape, so stale hook assumptions can leak across deployments
 - bridge-safe wrapper behavior is part of the runtime trust model
 
-## Where State Lives
+## Where state lives
 
 - orchestration and wrapper logic: `JBOmnichainDeployer`
 - bridge runtime state: `nana-suckers-v6`
@@ -83,11 +82,11 @@ Useful scripts:
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
 
-## Deployment Notes
+## Deployment notes
 
 This repo assumes the 721 hook, address registry, buyback hook, suckers, ownable, and core packages are already available. Matching salts from the same sender keep sucker addresses deterministic across chains.
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -101,14 +100,14 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - ruleset ID prediction is part of the implementation strategy
 - hook composition order matters because the 721 hook runs before any extra custom hook
 - default empty-tier 721 config is convenient, but teams should still decide explicitly whether the hook participates in cash-out behavior
 - deterministic salts only help with cross-chain address alignment when sender and configuration match exactly
 
-## For AI Agents
+## For AI agents
 
 - Describe this repo as an orchestration and wrapper layer, not as the source of sucker or 721 runtime behavior.
 - Start with `JBOmnichainDeployer`, then inspect the sibling repo that owns the behavior being questioned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/omnichain-deployers-v6",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/operations.md

@@ -1,19 +1,19 @@
 # Omnichain Deployer Operations
 
-## Deployment Surface
+## Deployment surface
 
 - [`src/JBOmnichainDeployer.sol`](../src/JBOmnichainDeployer.sol) is the first stop for launch, queue, and sucker-deployment behavior.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) is the deployment entry point when the question is about current wiring rather than wrapper semantics.
 - [`src/structs/`](../src/structs/) defines the deploy and queue config types that often drift from memory.
 
-## Change Checklist
+## Change checklist
 
 - If you edit launch or queue behavior, verify ruleset IDs, carry-forward behavior, and stored hook config keys together.
 - If you edit salt handling, confirm deterministic-address assumptions for both suckers and 721 hooks.
 - If you edit wrapper behavior, check both pay and cash-out paths, not only one.
 - If you touch mint-permission logic, confirm whether the permission should come from suckers, the extra hook, or neither.
 
-## Common Failure Modes
+## Common failure modes
 
 - Wrapper behavior is blamed on the composed hook, but the deployer stored the wrong hook config for the ruleset.
 - A same-block queue assumption breaks predicted ruleset IDs and silently strands stored config.
@@ -21,7 +21,7 @@
 - Deterministic deployment assumptions fail because sender or salt composition changed.
 - Existing-project sucker deployment is treated as a pure `DEPLOY_SUCKERS` flow even though the registry also performs token mapping, so missing `MAP_SUCKER_TOKEN` authority for the registry shows up only when the deploy path reaches `mapTokens`.
 
-## Useful Proof Points
+## Useful proof points
 
 - [`test/JBOmnichainDeployer.t.sol`](../test/JBOmnichainDeployer.t.sol) for baseline deploy and queue flows.
 - [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) for pinned edge cases.

package/references/runtime.md

@@ -1,10 +1,10 @@
 # Omnichain Deployer Runtime
 
-## Contract Role
+## Contract role
 
 - [`src/JBOmnichainDeployer.sol`](../src/JBOmnichainDeployer.sol) launches projects, deploys suckers, installs a 721 hook, wraps extra hooks, and serves as the live ruleset data-hook wrapper for the projects it creates.
 
-## Runtime Path
+## Runtime path
 
 1. Project launch or ruleset queue stores the relevant 721 hook and optional extra hook per ruleset.
 2. The deployer installs itself as the data-hook wrapper on the ruleset.
@@ -12,7 +12,7 @@
 4. On cash out, it can short-circuit for suckers, otherwise it forwards into the configured hook stack in order.
 5. Mint permission queries can be granted by suckers or by the configured extra hook.
 
-## High-Risk Areas
+## High-risk areas
 
 - Ruleset ID prediction: if the predicted ID is wrong, hook config can be stored under the wrong key.
 - Hook composition order: 721 logic runs before any extra hook, which affects both specs and accounting.
@@ -20,7 +20,7 @@
 - Carry-forward logic: queueing rulesets without new tiers intentionally reuses the latest 721 hook.
 - Meta-transaction sender handling: salt derivation uses `_msgSender()`, not raw `msg.sender`.
 
-## Tests To Trust First
+## Tests to trust first
 
 - [`test/Tiered721HookComposition.t.sol`](../test/Tiered721HookComposition.t.sol) for hook-composition behavior.
 - [`test/JBOmnichainDeployerGuard.t.sol`](../test/JBOmnichainDeployerGuard.t.sol) and [`test/OmnichainDeployerAttacks.t.sol`](../test/OmnichainDeployerAttacks.t.sol) for safety properties.

package/src/JBOmnichainDeployer.sol

@@ -158,6 +158,7 @@ contract JBOmnichainDeployer is
     /// 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.
+    /// @return suckers The addresses of the deployed suckers.
     function deploySuckersFor(
         uint256 projectId,
         JBSuckerDeploymentConfig calldata suckerDeploymentConfiguration
@@ -760,6 +761,9 @@ contract JBOmnichainDeployer is
     }
 
     /// @notice Internal implementation of `launchProjectFor`.
+    /// @return projectId The ID of the newly launched project.
+    /// @return hook The 721 tiers hook that was deployed for the project.
+    /// @return suckers The addresses of the deployed suckers.
     function _launchProjectFor(
         address owner,
         string calldata projectUri,
@@ -823,6 +827,8 @@ contract JBOmnichainDeployer is
     }
 
     /// @notice Internal implementation of `launchRulesetsFor`.
+    /// @return rulesetId The ID of the newly launched rulesets.
+    /// @return hook The 721 tiers hook that was deployed for the project.
     function _launchRulesetsFor(
         uint256 projectId,
         string calldata projectUri,
@@ -875,6 +881,8 @@ contract JBOmnichainDeployer is
     }
 
     /// @notice Internal implementation of `queueRulesetsOf`.
+    /// @return rulesetId The ID of the newly queued rulesets.
+    /// @return hook The 721 tiers hook (newly deployed or carried forward from the previous ruleset).
     function _queueRulesetsOf(
         uint256 projectId,
         JBOmnichain721Config memory deploy721Config,
@@ -919,7 +927,8 @@ contract JBOmnichainDeployer is
                 // (or has no approval hook), its hook config should take precedence.
                 // Conservative: only use Approved or Empty status. ApprovalExpected is intentionally
                 // excluded because hook selection is irreversible — if the pending ruleset is later rejected
-                // by the approval hook, we'd have locked in a hook from a ruleset that never became active.
+                // by the approval hook, the deployer would otherwise lock in a hook from a ruleset that never
+                // became active.
                 (JBRuleset memory latestQueued, JBApprovalStatus approvalStatus) =
                     CONTROLLER.RULESETS().latestQueuedOf(projectId);
                 if (

package/src/interfaces/IJBOmnichainDeployer.sol

@@ -13,6 +13,7 @@ import {JBSuckerDeploymentConfig} from "../structs/JBSuckerDeploymentConfig.sol"
 /// pay/cash-out logic through a data hook wrapper.
 interface IJBOmnichainDeployer {
     /// @notice The controller used for every project launch and ruleset queue.
+    /// @return controller The controller used for every project launch and ruleset queue.
     function CONTROLLER() external view returns (IJBController);
 
     /// @notice Get the extra data hook for a project and ruleset.

package/src/structs/JBDeployerHookConfig.sol

@@ -5,9 +5,9 @@ import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDa
 
 /// @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.
+/// @custom:member dataHook The extra data hook contract to delegate to.
+/// @custom:member useDataHookForPay Whether to call this hook's `beforePayRecordedWith` during payments.
+/// @custom:member useDataHookForCashOut Whether to call this hook's `beforeCashOutRecordedWith` during cash outs.
 struct JBDeployerHookConfig {
     IJBRulesetDataHook dataHook;
     bool useDataHookForPay;

package/src/structs/JBOmnichain721Config.sol

@@ -4,10 +4,10 @@ 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 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.
+/// @custom:member deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook to deploy.
+/// @custom:member useDataHookForCashOut Whether the 721 hook should handle cash outs (via beforeCashOutRecordedWith).
+/// @custom:member 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.
 struct JBOmnichain721Config {
     JBDeploy721TiersHookConfig deployTiersHookConfig;
     bool useDataHookForCashOut;

package/src/structs/JBSuckerDeploymentConfig.sol

@@ -3,6 +3,8 @@ pragma solidity ^0.8.0;
 
 import {JBSuckerDeployerConfig} from "@bananapus/suckers-v6/src/structs/JBSuckerDeployerConfig.sol";
 
+/// @notice Configuration for deploying a project's suckers in one call: the per-peer deployer configs plus the salt
+/// that seeds deterministic addresses.
 /// @custom:member deployerConfigurations Sucker deployer configs and token mappings for peer chains.
 /// @custom:member salt The salt combined with `_msgSender()` to create deterministic sucker addresses.
 struct JBSuckerDeploymentConfig {

package/src/structs/JBTiered721HookConfig.sol

@@ -4,8 +4,8 @@ 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
+/// @custom:member hook The tiered 721 hook contract used for NFT minting on payments.
+/// @custom:member useDataHookForCashOut Whether the 721 hook should participate in cash-out tax calculations and NFT
 /// redemptions.
 struct JBTiered721HookConfig {
     IJB721TiersHook hook;