@bananapus/suckers-v6 0.0.31 → 0.0.33

package/README.md

@@ -72,8 +72,8 @@ That means every bridge path has two trust surfaces:
 1. `test/unit/registry.t.sol`
 2. `test/unit/multi_chain_evolution.t.sol`
 3. `test/ForkClaimMainnet.t.sol`
-4. `test/audit/codex-PeerSnapshotDesync.t.sol`
-5. `test/audit/codex-ToRemoteFeeIrrecoverable.t.sol`
+4. `test/audit/PeerSnapshotDesync.t.sol`
+5. `test/audit/ToRemoteFeeIrrecoverable.t.sol`
 
 ## Install
 

package/foundry.lock

@@ -1,11 +1,5 @@
 {
   "lib/forge-std": {
     "rev": "83c5d212a01f8950727da4095cdfe2654baccb5b"
-  },
-  "lib/sphinx": {
-    "branch": {
-      "name": "v0.23.0",
-      "rev": "5fb24a825f46bd6ae0b5359fe0da1d2346126b09"
-    }
   }
-}
+}

package/foundry.toml

@@ -14,8 +14,7 @@ depth = 100
 fail_on_revert = false
 
 [lint]
-exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
-lint_on_build = false
+exclude_lints = ["mixed-case-variable", "pascal-case-struct"]
 
 [fmt]
 number_underscore = "thousands"

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-suckers-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.lock",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/Deploy.s.sol",
+    "script/helpers/",
+    "sphinx.lock",
+    "src/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -18,19 +29,19 @@
     "analyze": "slither . --config-file slither-ci.config.json"
   },
   "dependencies": {
-    "@arbitrum/nitro-contracts": "^1.2.1",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@chainlink/contracts-ccip": "^1.6.0",
-    "@chainlink/local": "github:smartcontractkit/chainlink-local#v0.2.7",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@prb/math": "^4.1.0",
-    "@uniswap/v3-core": "github:Uniswap/v3-core#0.8",
-    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#0.8",
-    "@uniswap/v4-core": "^1.0.2",
-    "solady": "^0.1.26"
+    "@arbitrum/nitro-contracts": "3.2.0",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@chainlink/contracts-ccip": "1.6.4",
+    "@chainlink/local": "0.2.7",
+    "@openzeppelin/contracts": "5.6.1",
+    "@prb/math": "4.1.1",
+    "@uniswap/v3-core": "github:Uniswap/v3-core#6562c52e8f75f0c10f9deaf44861847585fc8129",
+    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#b325bb0905d922ae61fcc7df85ee802e8df5e96c",
+    "@uniswap/v4-core": "1.0.2",
+    "solady": "0.1.26"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/references/operations.md

@@ -25,4 +25,4 @@
 
 - [`test/SuckerAttacks.t.sol`](../test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](../test/SuckerDeepAttacks.t.sol), and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for security-sensitive assumptions.
 - [`test/InteropCompat.t.sol`](../test/InteropCompat.t.sol) when the problem is deployment wiring rather than runtime logic.
-- [`test/unit/invariants.t.sol`](../test/unit/invariants.t.sol), [`test/unit/peer_chain_state.t.sol`](../test/unit/peer_chain_state.t.sol), and [`test/audit/codex-PeerSnapshotDesync.t.sol`](../test/audit/codex-PeerSnapshotDesync.t.sol) when shared accounting or snapshot boundaries are in doubt.
+- [`test/unit/invariants.t.sol`](../test/unit/invariants.t.sol), [`test/unit/peer_chain_state.t.sol`](../test/unit/peer_chain_state.t.sol), and [`test/audit/PeerSnapshotDesync.t.sol`](../test/audit/PeerSnapshotDesync.t.sol) when shared accounting or snapshot boundaries are in doubt.

package/references/runtime.md

@@ -27,4 +27,4 @@
 - [`test/ForkMainnet.t.sol`](../test/ForkMainnet.t.sol), [`test/ForkArbitrum.t.sol`](../test/ForkArbitrum.t.sol), [`test/ForkCelo.t.sol`](../test/ForkCelo.t.sol), and [`test/ForkOPStack.t.sol`](../test/ForkOPStack.t.sol) for real transport assumptions.
 - [`test/ForkSwap.t.sol`](../test/ForkSwap.t.sol), [`test/ForkClaimMainnet.t.sol`](../test/ForkClaimMainnet.t.sol), and [`test/SuckerRegressions.t.sol`](../test/SuckerRegressions.t.sol) for pinned cross-chain edge cases.
 - [`test/unit/invariants.t.sol`](../test/unit/invariants.t.sol), [`test/unit/peer_chain_state.t.sol`](../test/unit/peer_chain_state.t.sol), and [`test/unit/registry.t.sol`](../test/unit/registry.t.sol) for shared-accounting invariants.
-- [`test/SuckerAttacks.t.sol`](../test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](../test/SuckerDeepAttacks.t.sol), [`test/audit/codex-PeerSnapshotDesync.t.sol`](../test/audit/codex-PeerSnapshotDesync.t.sol), and [`test/audit/codex-PeerDeterminism.t.sol`](../test/audit/codex-PeerDeterminism.t.sol) when the bug could involve base logic, registry behavior, or a specific bridge implementation.
+- [`test/SuckerAttacks.t.sol`](../test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](../test/SuckerDeepAttacks.t.sol), [`test/audit/PeerSnapshotDesync.t.sol`](../test/audit/PeerSnapshotDesync.t.sol), and [`test/audit/PeerDeterminism.t.sol`](../test/audit/PeerDeterminism.t.sol) when the bug could involve base logic, registry behavior, or a specific bridge implementation.

package/script/Deploy.s.sol

@@ -224,6 +224,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _opDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
+                    prices: address(core.prices),
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -275,6 +276,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _opDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
+                    prices: address(core.prices),
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -357,6 +359,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _baseDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
+                    prices: address(core.prices),
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -408,6 +411,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _baseDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
+                    prices: address(core.prices),
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -486,6 +490,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _arbDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
+                    prices: address(core.prices),
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -540,6 +545,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: _arbDeployer,
                     directory: core.directory,
                     permissions: core.permissions,
+                    prices: address(core.prices),
                     tokens: core.tokens,
                     feeProjectId: 1,
                     registry: REGISTRY,
@@ -715,6 +721,7 @@ contract DeployScript is Script, Sphinx {
             salt: salt,
             directory: core.directory,
             permissions: core.permissions,
+            prices: address(core.prices),
             tokens: core.tokens,
             configurator: safeAddress(),
             trustedForwarder: TRUSTED_FORWARDER,
@@ -731,6 +738,7 @@ contract DeployScript is Script, Sphinx {
         bytes32 salt,
         IJBDirectory directory,
         IJBPermissions permissions,
+        address prices,
         IJBTokens tokens,
         address configurator,
         address trustedForwarder,
@@ -786,6 +794,7 @@ contract DeployScript is Script, Sphinx {
                 directory: directory,
                 tokens: tokens,
                 permissions: permissions,
+                prices: prices,
                 feeProjectId: 1,
                 registry: REGISTRY,
                 trustedForwarder: trustedForwarder

package/src/JBArbitrumSucker.sol

@@ -26,7 +26,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 ------------------------- //
@@ -53,17 +55,19 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
 
     /// @param directory A contract storing directories of terminals and controllers for each project.
     /// @param permissions A contract storing permissions.
+    /// @param prices The price oracle used to convert peer-chain balances and surplus.
     /// @param tokens A contract that manages token minting and burning.
     constructor(
         JBArbitrumSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
+        address prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,
         address trustedForwarder
     )
-        JBSucker(directory, permissions, tokens, feeProjectId, registry, trustedForwarder)
+        JBSucker(directory, permissions, prices, tokens, feeProjectId, registry, trustedForwarder)
     {
         GATEWAYROUTER = JBArbitrumSuckerDeployer(deployer).arbGatewayRouter();
         ARBINBOX = JBArbitrumSuckerDeployer(deployer).arbInbox();

package/src/JBBaseSucker.sol

@@ -18,17 +18,19 @@ contract JBBaseSucker is JBOptimismSucker {
     /// @param deployer A contract that deploys the clones for this contracts.
     /// @param directory A contract storing directories of terminals and controllers for each project.
     /// @param permissions A contract storing permissions.
+    /// @param prices The price oracle used to convert peer-chain balances and surplus.
     /// @param tokens A contract that manages token minting and burning.
     constructor(
         JBOptimismSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
+        address prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,
         address trustedForwarder
     )
-        JBOptimismSucker(deployer, directory, permissions, tokens, feeProjectId, registry, trustedForwarder)
+        JBOptimismSucker(deployer, directory, permissions, prices, tokens, feeProjectId, registry, trustedForwarder)
     {}
 
     //*********************************************************************//

package/src/JBCCIPSucker.sol

@@ -28,7 +28,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 ------------------------- //
@@ -42,10 +44,10 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
     //*********************************************************************//
 
     /// @notice Emitted when a transport payment refund fails after a successful CCIP send.
-    /// @dev The refunded ETH is permanently stuck in this contract — there is no recovery function.
-    /// This is an accepted tradeoff to avoid reverting after CCIP has committed the bridge message.
+    /// @dev The refunded ETH is retained as account-scoped credit so the CCIP send does not revert after
+    /// committing the bridge message.
     /// @param recipient The address that was supposed to receive the refund.
-    /// @param amount The amount of the failed refund (permanently stuck in this contract).
+    /// @param amount The amount of the failed refund.
     event TransportPaymentRefundFailed(address indexed recipient, uint256 amount);
 
     //*********************************************************************//
@@ -74,21 +76,23 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
 
     /// @param deployer A contract that deploys the clones for this contract.
     /// @param directory A contract storing directories of terminals and controllers for each project.
-    /// @param tokens A contract that manages token minting and burning.
     /// @param permissions A contract storing permissions.
+    /// @param prices The price oracle used to convert peer-chain balances and surplus.
+    /// @param tokens A contract that manages token minting and burning.
     /// @param feeProjectId The ID of the project that receives fees.
     /// @param registry The sucker registry that tracks deployed suckers.
     /// @param trustedForwarder The trusted forwarder for ERC-2771 meta-transactions.
     constructor(
         JBCCIPSuckerDeployer deployer,
         IJBDirectory directory,
-        IJBTokens tokens,
         IJBPermissions permissions,
+        address prices,
+        IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,
         address trustedForwarder
     )
-        JBSucker(directory, permissions, tokens, feeProjectId, registry, trustedForwarder)
+        JBSucker(directory, permissions, prices, tokens, feeProjectId, registry, trustedForwarder)
     {
         // Read the remote chain ID from the deployer.
         REMOTE_CHAIN_ID = IJBCCIPSuckerDeployer(deployer).ccipRemoteChainId();
@@ -248,8 +252,13 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
             refundRecipient: _msgSender()
         });
 
-        // Emit an event if the excess transport payment refund failed.
-        if (refundFailed) emit TransportPaymentRefundFailed(_msgSender(), refundAmount);
+        // Retain failed refunds as caller credit instead of leaving them project-addable or stranded.
+        if (refundFailed) {
+            // Refund accounting is isolated per caller; reentry cannot increase the retained credit.
+            // slither-disable-next-line reentrancy-benign
+            _retainTransportPaymentRefund({account: _msgSender(), amount: refundAmount});
+            emit TransportPaymentRefundFailed({recipient: _msgSender(), amount: refundAmount});
+        }
     }
 
     //*********************************************************************//
@@ -282,7 +291,7 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
         // funds. CCIP wraps native tokens to WETH before bridging (see `_sendRootOverAMB`), so ALL tokens —
         // including native — need sufficient gas for an ERC-20 transfer on the remote chain.
         if (map.minGas < MESSENGER_ERC20_MIN_GAS_LIMIT) {
-            revert JBSucker_BelowMinGas(map.minGas, MESSENGER_ERC20_MIN_GAS_LIMIT);
+            revert JBSucker_BelowMinGas({minGas: map.minGas, minGasLimit: MESSENGER_ERC20_MIN_GAS_LIMIT});
         }
     }
 }

package/src/JBCeloSucker.sol

@@ -37,17 +37,19 @@ contract JBCeloSucker is JBOptimismSucker {
     /// @param deployer A contract that deploys the clones for this contracts.
     /// @param directory A contract storing directories of terminals and controllers for each project.
     /// @param permissions A contract storing permissions.
+    /// @param prices The price oracle used to convert peer-chain balances and surplus.
     /// @param tokens A contract that manages token minting and burning.
     constructor(
         JBCeloSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
+        address prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,
         address trustedForwarder
     )
-        JBOptimismSucker(deployer, directory, permissions, tokens, feeProjectId, registry, trustedForwarder)
+        JBOptimismSucker(deployer, directory, permissions, prices, tokens, feeProjectId, registry, trustedForwarder)
     {
         // Fetch the wrapped native token by doing a callback to the deployer contract.
         WRAPPED_NATIVE = JBCeloSuckerDeployer(deployer).wrappedNative();
@@ -82,7 +84,7 @@ contract JBCeloSucker is JBOptimismSucker {
             // Check addable amount against WETH balance before unwrapping.
             uint256 addableAmount = amountToAddToBalanceOf(token);
             if (amount > addableAmount) {
-                revert JBSucker_InsufficientBalance(amount, addableAmount);
+                revert JBSucker_InsufficientBalance({amount: amount, balance: addableAmount});
             }
 
             // Unwrap WETH → native ETH.
@@ -95,7 +97,7 @@ contract JBCeloSucker is JBOptimismSucker {
                 DIRECTORY.primaryTerminalOf({projectId: cachedProjectId, token: JBConstants.NATIVE_TOKEN});
 
             if (address(terminal) == address(0)) {
-                revert JBSucker_NoTerminalForToken(cachedProjectId, JBConstants.NATIVE_TOKEN);
+                revert JBSucker_NoTerminalForToken({projectId: cachedProjectId, token: JBConstants.NATIVE_TOKEN});
             }
 
             // Add native ETH to the project's balance.
@@ -186,7 +188,7 @@ contract JBCeloSucker is JBOptimismSucker {
         // Enforce a reasonable minimum gas limit for bridging. Since we always bridge as ERC-20
         // (wrapping native ETH to WETH), all tokens need sufficient gas for an ERC-20 transfer.
         if (map.minGas < MESSENGER_ERC20_MIN_GAS_LIMIT) {
-            revert JBSucker_BelowMinGas(map.minGas, MESSENGER_ERC20_MIN_GAS_LIMIT);
+            revert JBSucker_BelowMinGas({minGas: map.minGas, minGasLimit: MESSENGER_ERC20_MIN_GAS_LIMIT});
         }
     }
 }

package/src/JBOptimismSucker.sol

@@ -17,7 +17,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 ---------------- //
@@ -35,18 +37,20 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
 
     /// @param deployer A contract that deploys the clones for this contracts.
     /// @param directory A contract storing directories of terminals and controllers for each project.
-    /// @param tokens A contract that manages token minting and burning.
     /// @param permissions A contract storing permissions.
+    /// @param prices The price oracle used to convert peer-chain balances and surplus.
+    /// @param tokens A contract that manages token minting and burning.
     constructor(
         JBOptimismSuckerDeployer deployer,
         IJBDirectory directory,
         IJBPermissions permissions,
+        address prices,
         IJBTokens tokens,
         uint256 feeProjectId,
         IJBSuckerRegistry registry,
         address trustedForwarder
     )
-        JBSucker(directory, permissions, tokens, feeProjectId, registry, trustedForwarder)
+        JBSucker(directory, permissions, prices, tokens, feeProjectId, registry, trustedForwarder)
     {
         // Fetch the messenger and bridge by doing a callback to the deployer contract.
         OPBRIDGE = JBOptimismSuckerDeployer(deployer).opBridge();