@bananapus/omnichain-deployers-v6 0.0.56 → 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.56",
+  "version": "0.0.58",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "@bananapus/core-v6": "^0.0.78",
     "@bananapus/ownable-v6": "^0.0.34",
     "@bananapus/permission-ids-v6": "^0.0.28",
-    "@bananapus/suckers-v6": "^0.0.67",
+    "@bananapus/suckers-v6": "^0.0.69",
     "@openzeppelin/contracts": "5.6.1"
   },
   "devDependencies": {

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

@@ -22,6 +22,7 @@ import {JBOwnable} from "@bananapus/ownable-v6/src/JBOwnable.sol";
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {IJBPeerChainAdjustedAccounts} from "@bananapus/suckers-v6/src/interfaces/IJBPeerChainAdjustedAccounts.sol";
 import {IJBSuckerRegistry} from "@bananapus/suckers-v6/src/interfaces/IJBSuckerRegistry.sol";
+import {JBSourceContext} from "@bananapus/suckers-v6/src/structs/JBSourceContext.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
 import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol";
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
@@ -157,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
@@ -434,7 +436,7 @@ contract JBOmnichainDeployer is
         // If the ruleset aggregates cross-chain state, add remote supply and surplus.
         if (!context.scopeCashOutsToLocalBalances) {
             totalSupply += SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
-            effectiveSurplusValue += SUCKER_REGISTRY.remoteSurplusOf({
+            effectiveSurplusValue += SUCKER_REGISTRY.totalRemoteSurplusOf({
                 projectId: context.projectId,
                 decimals: context.surplus.decimals,
                 currency: uint256(context.surplus.currency)
@@ -682,44 +684,38 @@ contract JBOmnichainDeployer is
     }
 
     /// @notice Forwards peer-chain adjusted accounts from the stored extra data hook. Suckers call this on the active
-    /// data hook (which is this deployer after wrapping) to learn about additional supply/surplus/balance that should
-    /// be included in cross-chain snapshots. Without forwarding, the extra hook's peer-chain adjustments are silently
-    /// masked, causing the bonding curve to use only local values and over-reclaiming on peer chains.
+    /// data hook (which is this deployer after wrapping) to learn about additional supply and per-context surplus and
+    /// balance that should be included in cross-chain snapshots. Without forwarding, the extra hook's peer-chain
+    /// adjustments are silently masked, causing the bonding curve to use only local values and over-reclaiming on peer
+    /// chains.
     /// @dev Part of `IJBPeerChainAdjustedAccounts`. Uses staticcall to safely handle extra hooks that do not implement
     /// this interface.
     /// @param projectId The ID of the project to snapshot.
-    /// @param decimals The decimals the returned surplus and balance should use.
-    /// @param currency The currency the returned surplus and balance should be in terms of.
     /// @return supply The extra supply to include in `sourceTotalSupply`.
-    /// @return surplus The extra surplus to include in `sourceSurplus`.
-    /// @return balance The extra balance to include in `sourceBalance`.
-    function peerChainAdjustedAccountsOf(
-        uint256 projectId,
-        uint256 decimals,
-        uint256 currency
-    )
+    /// @return contexts The extra per-context surplus and balance to include in the snapshot, un-valued.
+    function peerChainAdjustedAccountsOf(uint256 projectId)
         external
         view
         override
-        returns (uint256 supply, uint256 surplus, uint256 balance)
+        returns (uint256 supply, JBSourceContext[] memory contexts)
     {
         // Get the current ruleset from the canonical controller to look up the stored extra hook.
         (JBRuleset memory ruleset,) = CONTROLLER.currentRulesetOf(projectId);
 
         // Look up the extra data hook for this project's current ruleset.
         JBDeployerHookConfig memory extraHook = _extraDataHookOf[projectId][ruleset.id];
-        if (address(extraHook.dataHook) == address(0)) return (0, 0, 0);
+        if (address(extraHook.dataHook) == address(0)) return (0, new JBSourceContext[](0));
 
         // Forward via staticcall — the extra hook may or may not implement IJBPeerChainAdjustedAccounts.
         (bool success, bytes memory data) = address(extraHook.dataHook)
-            .staticcall(
-                abi.encodeCall(
-                    IJBPeerChainAdjustedAccounts.peerChainAdjustedAccountsOf, (projectId, decimals, currency)
-                )
-            );
-        if (!success || data.length < 96) return (0, 0, 0);
-
-        return abi.decode(data, (uint256, uint256, uint256));
+            .staticcall(abi.encodeCall(IJBPeerChainAdjustedAccounts.peerChainAdjustedAccountsOf, (projectId)));
+
+        // A well-formed `(uint256, JBSourceContext[])` return is at least three words: the supply, the array offset,
+        // and the array length. Anything shorter (an empty return, a hook with no code, or a mismatched ABI) is
+        // treated as no contribution rather than letting the decode revert.
+        if (!success || data.length < 96) return (0, new JBSourceContext[](0));
+
+        return abi.decode(data, (uint256, JBSourceContext[]));
     }
 
     //*********************************************************************//
@@ -765,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,
@@ -828,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,
@@ -880,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,
@@ -924,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;