@bananapus/suckers-v6 0.0.32 → 0.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",

package/script/Deploy.s.sol

@@ -4,6 +4,7 @@ pragma solidity 0.8.28;
 import {IInbox} from "@arbitrum/nitro-contracts/src/bridge/IInbox.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 import {CoreDeployment, CoreDeploymentLib} from "@bananapus/core-v6/script/helpers/CoreDeploymentLib.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
@@ -224,7 +225,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _opDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
-                    prices: address(core.prices),
+                    prices: core.prices,
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -276,7 +277,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _opDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
-                    prices: address(core.prices),
+                    prices: core.prices,
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -359,7 +360,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _baseDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
-                    prices: address(core.prices),
+                    prices: core.prices,
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -411,7 +412,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _baseDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
-                    prices: address(core.prices),
+                    prices: core.prices,
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -490,7 +491,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _arbDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
-                    prices: address(core.prices),
+                    prices: core.prices,
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -545,7 +546,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _arbDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
-                    prices: address(core.prices),
+                    prices: core.prices,
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -721,7 +722,7 @@ contract DeployScript is Script, Sphinx {
             salt: salt,
             directory: core.directory,
             permissions: core.permissions,
-            prices: address(core.prices),
+            prices: core.prices,
             tokens: core.tokens,
             configurator: safeAddress(),
             trustedForwarder: TRUSTED_FORWARDER,
@@ -738,7 +739,7 @@ contract DeployScript is Script, Sphinx {
         bytes32 salt,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         address configurator,
         address trustedForwarder,

package/src/JBArbitrumSucker.sol

@@ -8,6 +8,7 @@ import {AddressAliasHelper} from "@arbitrum/nitro-contracts/src/libraries/Addres
 import {ArbSys} from "@arbitrum/nitro-contracts/src/precompiles/ArbSys.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -26,7 +27,9 @@ import {ARBChains} from "./libraries/ARBChains.sol";
 import {JBMessageRoot} from "./structs/JBMessageRoot.sol";
 import {JBRemoteToken} from "./structs/JBRemoteToken.sol";
 
-/// @notice A `JBSucker` implementation to suck tokens between two chains connected by an Arbitrum bridge.
+/// @notice A `JBSucker` implementation that bridges Juicebox project tokens and terminal-token funds between Ethereum
+/// L1 and Arbitrum L2 using the native Arbitrum Inbox/Outbox (for messages) and Gateway Router (for ERC-20 transfers).
+/// Deploys on both layers — L1 instances create retryable tickets, L2 instances call `ArbSys` for L2-to-L1 messages.
 contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -59,7 +62,7 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
         JBArbitrumSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,

package/src/JBBaseSucker.sol

@@ -3,6 +3,7 @@ pragma solidity 0.8.28;
 
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 
 import {JBOptimismSucker} from "./JBOptimismSucker.sol";
@@ -24,7 +25,7 @@ contract JBBaseSucker is JBOptimismSucker {
         JBOptimismSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,

package/src/JBCCIPSucker.sol

@@ -4,6 +4,7 @@ pragma solidity 0.8.28;
 // External packages (alphabetized)
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {IAny2EVMMessageReceiver} from "@chainlink/contracts-ccip/contracts/interfaces/IAny2EVMMessageReceiver.sol";
@@ -28,7 +29,9 @@ import {JBMessageRoot} from "./structs/JBMessageRoot.sol";
 import {JBRemoteToken} from "./structs/JBRemoteToken.sol";
 import {JBTokenMapping} from "./structs/JBTokenMapping.sol";
 
-/// @notice A `JBSucker` implementation to suck tokens between chains with Chainlink CCIP
+/// @notice A `JBSucker` implementation that bridges Juicebox project tokens and terminal-token funds across any pair of
+/// chains supported by Chainlink CCIP. Messages and token transfers are bundled into a single CCIP lane message, with
+/// the CCIP Router handling cross-chain delivery and fee estimation.
 contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -84,7 +87,7 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
         JBCCIPSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,

package/src/JBCeloSucker.sol

@@ -3,6 +3,7 @@ pragma solidity 0.8.28;
 
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
@@ -43,7 +44,7 @@ contract JBCeloSucker is JBOptimismSucker {
         JBCeloSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,

package/src/JBOptimismSucker.sol

@@ -3,6 +3,7 @@ pragma solidity 0.8.28;
 
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -17,7 +18,9 @@ import {IOPStandardBridge} from "./interfaces/IOPStandardBridge.sol";
 import {JBMessageRoot} from "./structs/JBMessageRoot.sol";
 import {JBRemoteToken} from "./structs/JBRemoteToken.sol";
 
-/// @notice A `JBSucker` implementation to suck tokens between two chains connected by an OP Bridge.
+/// @notice A `JBSucker` implementation that bridges Juicebox project tokens and terminal-token funds between two
+/// chains connected by an OP Stack bridge (Optimism, Base, etc.). Uses the `CrossDomainMessenger` for merkle-root
+/// messages and the `StandardBridge` for ERC-20/native token transfers.
 contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -42,7 +45,7 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
         JBOptimismSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,

package/src/JBSucker.sol

@@ -43,17 +43,19 @@ import {JBOutboxTree} from "./structs/JBOutboxTree.sol";
 import {JBRemoteToken} from "./structs/JBRemoteToken.sol";
 import {JBTokenMapping} from "./structs/JBTokenMapping.sol";
 
-/// @notice An abstract contract for bridging a Juicebox project's tokens and the corresponding funds to and from a
-/// remote chain.
-/// @dev Beneficiaries and balances are tracked on two merkle trees: the outbox tree is used to send from the local
-/// chain to the remote chain, and the inbox tree is used to receive from the remote chain to the local chain.
+/// @notice Bridges a Juicebox project's tokens and their backing terminal-token funds between two chains. Token
+/// holders call `prepare` to cash out their project tokens and queue the resulting funds+tokens into an outbox merkle
+/// tree. Anyone can then call `toRemote` to send that tree's root (and the locked funds) across the bridge to the
+/// peer sucker on the remote chain. Once the root arrives, beneficiaries call `claim` with a merkle proof to mint
+/// project tokens and deposit the corresponding terminal tokens into the remote project's balance.
+///
+/// @dev Dual merkle trees: the **outbox** accumulates leaves for tokens leaving the local chain; the **inbox** stores
+/// the root received from the remote chain so claims can be verified locally.
 /// @dev Throughout this contract, "terminal token" refers to any token accepted by a project's terminal.
-/// @dev This contract does *NOT* support tokens that have a fee on regular transfers and rebasing tokens.
-/// @dev Cross-chain message authentication is delegated entirely to each bridge-specific subclass via the
-/// `_isRemotePeer` virtual function. Each implementation authenticates differently: Optimism uses its native
-/// `CrossDomainMessenger`, Arbitrum validates against the `Bridge` and `Outbox` contracts, and CCIP verifies
-/// through the Chainlink `Router`. Deployers of new bridge integrations must implement `_isRemotePeer` to
-/// guarantee that only messages from the legitimate remote peer are accepted.
+/// @dev This contract does *NOT* support fee-on-transfer or rebasing tokens.
+/// @dev Cross-chain message authentication is delegated to each bridge-specific subclass via `_isRemotePeer`.
+/// Optimism uses `CrossDomainMessenger`, Arbitrum validates against `Bridge`/`Outbox`, and CCIP verifies through
+/// Chainlink's `Router`.
 abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC165, IJBSuckerExtended {
     using BitMaps for BitMaps.BitMap;
     using MerkleLib for MerkleLib.Tree;
@@ -223,7 +225,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     constructor(
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,
@@ -234,7 +236,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     {
         DIRECTORY = directory;
         FEE_PROJECT_ID = feeProjectId;
-        PRICES = IJBPrices(prices);
+        PRICES = prices;
         PROJECTS = directory.PROJECTS();
         REGISTRY = registry;
         TOKENS = tokens;
@@ -265,7 +267,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     // --------------------- external transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Performs multiple claims.
+    /// @notice Claim multiple bridged entries in a single transaction. Each claim mints project tokens for the
+    /// beneficiary and deposits the corresponding terminal tokens into the project's local balance.
     /// @param claims A list of claims to perform (including the terminal token, merkle tree leaf, and proof for each
     /// claim).
     function claim(JBClaim[] calldata claims) external override {
@@ -278,7 +281,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         }
     }
 
-    /// @notice `JBClaim` project tokens which have been bridged from the remote chain for their beneficiary.
+    /// @notice Claim a single bridged entry: verifies the merkle proof against the inbox root, mints the specified
+    /// project tokens for the beneficiary, and deposits the terminal tokens into the project's local balance.
     /// @param claimData The terminal token, merkle tree leaf, and proof for the claim.
     function claim(JBClaim calldata claimData) public virtual override {
         // Attempt to validate the proof against the inbox tree for the terminal token.
@@ -334,8 +338,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         emit EmergencyHatchOpened({tokens: tokens, caller: _msgSender()});
     }
 
-    /// @notice Lets user exit on the chain they deposited in a scenario where the bridge is no longer functional.
-    /// @param claimData The terminal token, merkle tree leaf, and proof for the claim
+    /// @notice Emergency escape hatch: lets a user reclaim their project tokens and terminal tokens on the chain they
+    /// originally deposited from, when the bridge has become permanently non-functional. Must be enabled by the project
+    /// owner via the registry's `setEmergencyHatchStatusOf`.
+    /// @param claimData The terminal token, merkle tree leaf, and proof for the claim.
     function exitThroughEmergencyHatch(JBClaim calldata claimData) external override {
         // Does all the needed validation to ensure that the claim is valid *and* that claiming through the emergency
         // hatch is allowed.
@@ -368,7 +374,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         });
     }
 
-    /// @notice Receive a merkle root for a terminal token from the remote project.
+    /// @notice Receive a merkle root and peer-chain accounting snapshot from the remote sucker. Updates the inbox tree
+    /// so that users can claim bridged tokens. Also accepts any native-token funds delivered with the message.
     /// @dev This can only be called by the messenger contract on the local chain, with a message from the remote peer.
     /// @dev Nonce ordering: This function accepts any nonce strictly greater than the current inbox nonce, rather than
     /// requiring sequential (nonce == inbox.nonce + 1) processing. This is intentional because some bridges (e.g.,
@@ -448,8 +455,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         }
     }
 
-    /// @notice Map multiple ERC-20 tokens on the local chain to ERC-20 tokens on the remote chain, allowing those
-    /// tokens to be bridged.
+    /// @notice Configure which remote-chain tokens each local terminal token maps to, enabling (or disabling) those
+    /// tokens for cross-chain bridging. Setting a remote token to `bytes32(0)` disables bridging and flushes any
+    /// pending outbox entries. Requires `MAP_SUCKER_TOKEN` permission from the project owner (or called by the
+    /// registry during deployment).
     /// @param maps A list of local and remote terminal token addresses to map, and minimum amount/gas limits for
     /// bridging them.
     function mapTokens(JBTokenMapping[] calldata maps) external payable override {
@@ -495,7 +504,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         }
     }
 
-    /// @notice Prepare project tokens and the cash out amount backing them to be bridged to the remote chain.
+    /// @notice Queue project tokens for bridging to the remote chain. Transfers the caller's project tokens into this
+    /// contract, cashes them out for the specified terminal token, and inserts a leaf into the outbox merkle tree. The
+    /// queued entry will be bridged the next time anyone calls `toRemote` for the same `token`.
     /// @dev This adds the tokens and funds to the outbox tree for the `token`. They will be bridged by the next call to
     /// `toRemote` for the same `token`.
     /// @dev Reentrancy protection: This function has implicit reentrancy protection through `_pullBackingAssets`.
@@ -562,8 +573,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         });
     }
 
-    /// @notice Set or remove the time after which this sucker will be deprecated, once deprecated the sucker will no
-    /// longer be functional and it will let all users exit.
+    /// @notice Schedule (or cancel) the deprecation of this sucker. Once deprecated, no new outbound transfers are
+    /// accepted and users can exit via the emergency hatch. Requires `SET_SUCKER_DEPRECATION` permission. A mandatory
+    /// 14-day buffer ensures in-flight messages have time to arrive before the sucker fully shuts down.
     /// @param timestamp The time after which the sucker will be deprecated. Or `0` to remove the upcoming deprecation.
     function setDeprecation(uint40 timestamp) external override {
         // As long as the sucker has not started letting users withdrawal, its deprecation time can be
@@ -599,9 +611,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         emit DeprecationTimeUpdated({timestamp: timestamp, caller: _msgSender()});
     }
 
-    /// @notice Bridge the project tokens, cashed out funds, and beneficiary information for a given `token` to the
-    /// remote
-    /// chain.
+    /// @notice Send the accumulated outbox merkle root and locked terminal-token funds for a given `token` across the
+    /// bridge to the remote peer sucker. Anyone can call this once entries exist in the outbox. Requires `msg.value`
+    /// to cover the registry's `toRemoteFee` plus any bridge transport payment.
     /// @dev This sends the outbox root for the specified `token` to the remote chain.
     /// @dev Fee payment failure handling: The registry fee payment uses a best-effort pattern (try/catch). If the
     /// fee project's terminal doesn't exist or the `pay` call reverts, the fee ETH is retained as a refundable balance

package/src/JBSuckerRegistry.sol

@@ -19,7 +19,10 @@ import {IJBSuckerRegistry} from "./interfaces/IJBSuckerRegistry.sol";
 import {JBSuckerDeployerConfig} from "./structs/JBSuckerDeployerConfig.sol";
 import {JBSuckersPair} from "./structs/JBSuckersPair.sol";
 
-/// @notice A registry for deploying and tracking suckers across projects.
+/// @notice The canonical registry that deploys, tracks, and governs cross-chain suckers for Juicebox projects. It
+/// maintains an allowlist of approved deployer contracts, enforces one active sucker per peer chain per project,
+/// manages the global `toRemoteFee` (paid into the protocol fee project on each bridge send), and provides aggregate
+/// views of remote-chain balances, surplus, and token supply across all of a project's suckers.
 contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerRegistry {
     using EnumerableMap for EnumerableMap.AddressToUintMap;
 
@@ -55,7 +58,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
 
-    /// @notice The juicebox directory.
+    /// @notice The Juicebox directory used to look up project terminals and controllers.
     IJBDirectory public immutable override DIRECTORY;
 
     /// @notice A contract which mints ERC-721s that represent project ownership and transfers.
@@ -105,8 +108,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Returns true if the specified sucker belongs to the specified project, and was deployed through this
-    /// registry.
+    /// @notice Whether the given address is a sucker (active or deprecated) that was deployed through this registry for
+    /// the specified project. Used by controllers to authorize mint calls from suckers.
     /// @param projectId The ID of the project to check for.
     /// @param addr The address of the sucker to check.
     /// @return flag A flag indicating if the sucker belongs to the project, and was deployed through this registry.
@@ -115,7 +118,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         return exists && (val == _SUCKER_EXISTS || val == _SUCKER_DEPRECATED);
     }
 
-    /// @notice Helper function for retrieving the projects suckers and their metadata.
+    /// @notice All active (non-deprecated) suckers for a project, with their remote peer address and chain ID.
     /// @param projectId The ID of the project to get the suckers of.
     /// @return pairs The pairs of suckers and their metadata.
     function suckerPairsOf(uint256 projectId) external view override returns (JBSuckersPair[] memory pairs) {
@@ -498,10 +501,10 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
-    /// @notice Deploy one or more suckers for the specified project.
-    /// @dev The caller must be the project's owner or have `JBPermissionIds.DEPLOY_SUCKERS` from the project's owner.
-    /// Each newly created sucker is immediately configured by calling `mapTokens`, so successful execution also
-    /// depends on this registry being authorized to perform `MAP_SUCKER_TOKEN` for the project.
+    /// @notice Deploy one or more cross-chain suckers for a project in a single transaction. Each sucker is created via
+    /// its deployer, registered in this registry, checked for duplicate peer chains, and immediately configured with
+    /// its token mappings. The caller must have `DEPLOY_SUCKERS` permission, and this registry must hold
+    /// `MAP_SUCKER_TOKEN` permission for the project.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param salt The salt used to deploy the contract. For the suckers to be peers, this must be the same value on
     /// each chain where suckers are deployed.

package/src/JBSwapCCIPSucker.sol

@@ -4,6 +4,7 @@ pragma solidity 0.8.28;
 // Core JB imports.
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
 // CCIP imports.
 import {Client} from "@chainlink/contracts-ccip/contracts/libraries/Client.sol";
@@ -209,7 +210,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
         JBSwapCCIPSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
-        address prices,
+        IJBPrices prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,

package/src/deployers/JBArbitrumSuckerDeployer.sol

@@ -17,7 +17,8 @@ import {IJBArbitrumSuckerDeployer} from "../interfaces/IJBArbitrumSuckerDeployer
 // Local: deployers.
 import {JBSuckerDeployer} from "./JBSuckerDeployer.sol";
 
-/// @notice An `IJBSuckerDeployer` implementation to deploy `JBArbitrumSucker` contracts.
+/// @notice Deployer for Arbitrum suckers. Stores the Inbox and Gateway Router for the target layer (L1 or L2) and
+/// clones `JBArbitrumSucker` instances via CREATE2.
 contract JBArbitrumSuckerDeployer is JBSuckerDeployer, IJBArbitrumSuckerDeployer {
     //*********************************************************************//
     // ---------------------- public stored properties ------------------- //

package/src/deployers/JBCCIPSuckerDeployer.sol

@@ -13,7 +13,8 @@ import {IJBCCIPSuckerDeployer} from "../interfaces/IJBCCIPSuckerDeployer.sol";
 // Local: deployers.
 import {JBSuckerDeployer} from "./JBSuckerDeployer.sol";
 
-/// @notice An `IJBSuckerDeployer` implementation to deploy `JBCCIPSucker` contracts.
+/// @notice Deployer for Chainlink CCIP suckers. Stores the CCIP router, remote chain ID, and remote chain selector,
+/// then clones `JBCCIPSucker` instances via CREATE2.
 contract JBCCIPSuckerDeployer is JBSuckerDeployer, IJBCCIPSuckerDeployer {
     //*********************************************************************//
     // ---------------------- public stored properties ------------------- //

package/src/deployers/JBOptimismSuckerDeployer.sol

@@ -14,7 +14,8 @@ import {IOPStandardBridge} from "../interfaces/IOPStandardBridge.sol";
 // Local: deployers.
 import {JBSuckerDeployer} from "./JBSuckerDeployer.sol";
 
-/// @notice An `IJBSuckerDeployer` implementation to deploy `JBOptimismSucker` contracts.
+/// @notice Deployer for OP Stack suckers (Optimism, Base, etc.). Stores the CrossDomainMessenger and StandardBridge
+/// for this chain and clones `JBOptimismSucker` instances via CREATE2.
 contract JBOptimismSuckerDeployer is JBSuckerDeployer, IJBOpSuckerDeployer {
     //*********************************************************************//
     // ---------------------- public stored properties ------------------- //

package/src/deployers/JBSuckerDeployer.sol

@@ -17,7 +17,10 @@ import {JBSucker} from "../JBSucker.sol";
 import {IJBSucker} from "../interfaces/IJBSucker.sol";
 import {IJBSuckerDeployer} from "../interfaces/IJBSuckerDeployer.sol";
 
-/// @notice A base implementation for deploying suckers.
+/// @notice Base factory for deploying cross-chain suckers using CREATE2 clones. Each bridge-specific deployer (OP,
+/// Arbitrum, CCIP) extends this contract with its own chain configuration. Setup is two-step: first the configurator
+/// calls `setChainSpecificConstants` (bridge addresses, chain selectors), then `configureSingleton` (the
+/// implementation to clone). After setup, anyone may call `createForSender` to deploy a new sucker for a project.
 abstract contract JBSuckerDeployer is ERC2771Context, JBPermissioned, IJBSuckerDeployer {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -47,7 +50,7 @@ abstract contract JBSuckerDeployer is ERC2771Context, JBPermissioned, IJBSuckerD
     // ---------------------- public stored properties ------------------- //
     //*********************************************************************//
 
-    /// @notice A mapping of suckers deployed by this contract.
+    /// @notice Whether a given address was deployed by this deployer.
     mapping(address => bool) public override isSucker;
 
     /// @notice The singleton used to clone suckers.
@@ -117,8 +120,8 @@ abstract contract JBSuckerDeployer is ERC2771Context, JBPermissioned, IJBSuckerD
     // --------------------- external transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Configure the singleton instance that is used to clone suckers.
-    /// @dev Can only be called *once* by the layer specific configurator.
+    /// @notice Set the implementation contract that all future suckers will be cloned from. Can only be called once.
+    /// @dev Must be called by the layer-specific configurator after `setChainSpecificConstants`.
     /// @param _singleton The address of the singleton.
     function configureSingleton(JBSucker _singleton) external {
         // Make sure only the configurator can call this function.
@@ -138,8 +141,9 @@ abstract contract JBSuckerDeployer is ERC2771Context, JBPermissioned, IJBSuckerD
         singleton = _singleton;
     }
 
-    /// @notice Create a new `JBSucker` for a specific project with an explicit remote peer.
-    /// @dev Uses the sender address as the salt, which means the same sender must call this function on both chains.
+    /// @notice Deploy a new sucker clone for a project via CREATE2. The same sender must call this on both chains to
+    /// produce matching deterministic addresses.
+    /// @dev Called by the registry during `deploySuckersFor`.
     /// @param localProjectId The project's ID on the local chain.
     /// @param salt The salt to use for the `create2` address.
     /// @param peer The remote peer address. Leave zero to use the default deterministic same-address peer.

package/src/libraries/ARBAddresses.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-/// @notice Global constants used across Juicebox contracts.
+/// @notice Arbitrum bridge infrastructure addresses (Inbox and Gateway Routers) for mainnet and Sepolia.
 library ARBAddresses {
     /// @notice The respective Inbox used by L1 or Testnet L1
     address public constant L1_ETH_INBOX = 0x4Dbd4fc535Ac27206064B68FfCf827b0A60BAB3f;

package/src/libraries/ARBChains.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-/// @notice Global constants used across Juicebox contracts.
+/// @notice Arbitrum chain IDs for mainnet and Sepolia testnet pairs.
 library ARBChains {
     /// @notice Arbitrum relevant chains and their respective ids.
     uint256 public constant ETH_CHAINID = 1;