@bananapus/suckers-v6 0.0.21 → 0.0.22

package/README.md

@@ -62,7 +62,7 @@ The shortest useful reading order is:
 | [`JBBaseSuckerDeployer`](src/deployers/JBBaseSuckerDeployer.sol) | Thin wrapper around `JBOptimismSuckerDeployer` for Base. |
 | [`JBCeloSuckerDeployer`](src/deployers/JBCeloSuckerDeployer.sol) | Deployer for `JBCeloSucker`. Extends `JBOptimismSuckerDeployer` with `wrappedNative` (`IWrappedNativeToken`) storage for the local chain's WETH address. |
 | [`JBArbitrumSuckerDeployer`](src/deployers/JBArbitrumSuckerDeployer.sol) | Deployer for `JBArbitrumSucker`. Stores Arbitrum Inbox, Gateway Router, and layer (`JBLayer.L1` or `JBLayer.L2`). |
-| [`MerkleLib`](src/utils/MerkleLib.sol) | Incremental merkle tree (depth 32, max ~4 billion leaves, modeled on eth2 deposit contract). Used for outbox/inbox trees. Gas-optimized with inline assembly for `root()` and `branchRoot()`. |
+| [`MerkleLib`](src/utils/MerkleLib.sol) | Incremental merkle tree (depth 32, max ~4 billion leaves, modeled on eth2 deposit contract). Used for outbox/inbox trees. `insert` and `root` operate directly on `Tree storage` (not memory copies) to avoid redundant SLOAD/SSTORE round-trips. Gas-optimized with inline assembly for `root()` and `branchRoot()`. |
 | [`CCIPHelper`](src/libraries/CCIPHelper.sol) | CCIP router addresses, chain selectors, and WETH addresses per chain. Covers Ethereum, Optimism, Arbitrum, Base, Polygon, Avalanche, and BNB Chain (mainnet and testnets). |
 | [`ARBAddresses`](src/libraries/ARBAddresses.sol) | Arbitrum bridge contract addresses (Inbox, Gateway Router) for mainnet and Sepolia. |
 | [`ARBChains`](src/libraries/ARBChains.sol) | Arbitrum chain ID constants. |

package/RISKS.md

@@ -91,7 +91,7 @@ This file focuses on the bridge-like risks in the sucker system: merkle-root pro
 - **uint128 cap for SVM compatibility.** `_insertIntoTree` reverts if `projectTokenCount` or `terminalTokenAmount` exceeds `type(uint128).max`. This is enforced for cross-VM compatibility but limits EVM-only use cases to ~3.4e38 wei per leaf.
 - **Arbitrum retryable ticket pricing.** `_toL2` uses `block.basefee` as `maxFeePerGas`. If L2 gas prices spike above L1's `block.basefee`, the retryable ticket may not auto-redeem and requires manual retry.
 - **CCIP fee volatility.** `_sendRootOverAMB` checks `CCIP_ROUTER.getFee()` at call time. If fees spike between estimation and execution, the transaction reverts with `JBSucker_InsufficientMsgValue`. No retry mechanism exists.
-- **`toRemote` fee fallback can strand ETH.** If the fee project's terminal is missing or `terminal.pay()` reverts, `toRemote()` keeps the fee ETH in the sucker so zero-cost bridges can still proceed with `transportPayment = msg.value - fee`. That retained ETH does increase `amountToAddToBalanceOf(NATIVE_TOKEN)`, but later `claim()` calls only forward each leaf's `terminalTokenAmount`, so the retained fee is not swept into the project's balance. There is no dedicated recovery function. This is an accepted tradeoff, and the stuck amount is bounded by `MAX_TO_REMOTE_FEE` (currently `0.001 ether`) per affected call.
+- **`toRemote` fee fallback retains ETH, absorbed by future claims.** If the fee project's terminal is missing or `terminal.pay()` reverts, `toRemote()` keeps the fee ETH in the sucker so zero-cost bridges can still proceed with `transportPayment = msg.value - fee`. That retained ETH is absorbed by future native token claims: `amountToAddToBalanceOf(NATIVE_TOKEN)` computes `_balanceOf(token, address(this)) - _outboxOf[token].balance`, so any extra ETH in the contract (including retained fees) increases the claimable amount and is forwarded to the project's terminal via `_addToBalance` when the next native token claim is processed. The retained amount per affected call is bounded by `MAX_TO_REMOTE_FEE` (currently `0.001 ether`).
 - **CCIP transport payment refund failure.** If `_msgSender()` is a non-payable contract, the refund `call` fails silently. The excess ETH (transportPayment - fees) is permanently stuck in the sucker. The contract emits `TransportPaymentRefundFailed` but has no sweep mechanism.
 - **Unbounded sucker count per project.** `JBSuckerRegistry._suckersOf` uses an EnumerableMap with no cap. `suckerPairsOf` iterates all suckers with external calls per iteration. Extremely large sucker counts could cause view functions to exceed gas limits.
 - **Unrestricted `receive()`.** Anyone can send ETH to the sucker, inflating `amountToAddToBalanceOf`. This is by design (needed for bridge/terminal returns) but means the project can receive unexpected balance additions.
@@ -127,6 +127,6 @@ The registry owner can adjust `toRemoteFee` via `JBSuckerRegistry.setToRemoteFee
 
 The fee is paid to `FEE_PROJECT_ID` (the protocol project), not to the sucker's own `projectId()`. This centralizes fee collection, but it is still only best-effort: if the fee project's native terminal is missing or its `pay` call reverts, the fee ETH stays in the sucker contract and is later recoverable through the normal claim path. The sucker's project does not directly benefit from the anti-spam fee.
 
-### 10.5 `mapTokens` does not refund ETH on enable-only batches
+### 10.5 `mapTokens` refunds ETH on enable-only batches
 
-`mapTokens()` only uses `msg.value` when one or more mappings are being disabled and need transport payment for the final root flush. If every mapping in the batch is enable-only, `numberToDisable == 0`, each `_mapToken` call receives `transportPaymentValue == 0`, and any ETH sent with the transaction is not used or refunded. Operators should avoid sending ETH on enable-only calls.
+`mapTokens()` only uses `msg.value` when one or more mappings are being disabled and need transport payment for the final root flush. If every mapping in the batch is enable-only (`numberToDisable == 0`), the full `msg.value` is refunded to `_msgSender()`. If the refund transfer fails (e.g., the caller is a non-payable contract), the call reverts with `JBSucker_RefundFailed`. When disables are present, any dust remainder from integer division (`msg.value % numberToDisable`) is also refunded on a best-effort basis.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "^1.2.1",
-    "@bananapus/core-v6": "^0.0.31",
+    "@bananapus/core-v6": "^0.0.32",
     "@bananapus/permission-ids-v6": "^0.0.15",
     "@chainlink/contracts-ccip": "^1.5.0",
     "@chainlink/local": "github:smartcontractkit/chainlink-local",

package/src/JBArbitrumSucker.sol

@@ -190,6 +190,9 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
     function _toL1(address token, uint256 amount, bytes memory data, JBRemoteToken memory remoteToken) internal {
         uint256 nativeValue;
 
+        // Cache peer address to avoid redundant calls.
+        address peerAddress = _toAddress(peer());
+
         // If the token is an ERC-20, bridge it to the peer.
         // If the amount is `0` then we do not need to bridge any ERC20.
         if (token != JBConstants.NATIVE_TOKEN && amount != 0) {
@@ -200,7 +203,7 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
             // slither-disable-next-line calls-loop,unused-return
             IArbL2GatewayRouter(address(GATEWAYROUTER))
                 .outboundTransfer({
-                    l1Token: _toAddress(remoteToken.addr), to: _toAddress(peer()), amount: amount, data: bytes("")
+                    l1Token: _toAddress(remoteToken.addr), to: peerAddress, amount: amount, data: bytes("")
                 });
         } else {
             // Otherwise, the token is the native token, and the amount will be sent as `msg.value`.
@@ -209,9 +212,8 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
 
         // Send the message to the peer with the reclaimed ETH.
         // Address `100` is the ArbSys precompile address.
-        // Convert bytes32 peer to address at the Arbitrum API boundary.
         // slither-disable-next-line calls-loop,unused-return
-        ArbSys(address(100)).sendTxToL1{value: nativeValue}({destination: _toAddress(peer()), data: data});
+        ArbSys(address(100)).sendTxToL1{value: nativeValue}({destination: peerAddress, data: data});
     }
 
     /// @notice Bridge the `token` and data to the remote L2 chain.

package/src/JBCCIPSucker.sol

@@ -199,6 +199,11 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
     //*********************************************************************//
 
     /// @notice Uses CCIP to send the root and assets over the bridge to the peer.
+    /// @dev CCIP transport payment refund failures emit a `TransportPaymentRefundFailed` event by design rather
+    /// than reverting. After `ccipSend` commits the bridge message and transfers tokens, reverting the transaction
+    /// would leave the CCIP message in-flight with no corresponding on-chain state update — the tokens would be
+    /// gone, the merkle root never processed, and the outbox inconsistent. Emitting an event preserves
+    /// observability while preventing a single failed refund from blocking the entire bridge operation.
     /// @param transportPayment the amount of `msg.value` that is going to get paid for sending this message.
     /// @param token The token to bridge the outbox tree for.
     /// @param remoteToken Information about the remote token being bridged to.

package/src/JBCeloSucker.sol

@@ -76,7 +76,8 @@ contract JBCeloSucker is JBOptimismSucker {
     /// and adds native ETH to the project's balance.
     /// @param token The terminal token to add to the project's balance.
     /// @param amount The amount of terminal tokens to add to the project's balance.
-    function _addToBalance(address token, uint256 amount) internal override {
+    /// @param projectId The cached project ID to avoid redundant storage reads.
+    function _addToBalance(address token, uint256 amount, uint256 projectId) internal override {
         if (token == address(WRAPPED_NATIVE)) {
             // Check addable amount against WETH balance before unwrapping.
             uint256 addableAmount = amountToAddToBalanceOf(token);
@@ -84,24 +85,22 @@ contract JBCeloSucker is JBOptimismSucker {
                 revert JBSucker_InsufficientBalance(amount, addableAmount);
             }
 
-            uint256 _projectId = projectId();
-
             // Unwrap WETH → native ETH.
             // slither-disable-next-line calls-loop
             WRAPPED_NATIVE.withdraw(amount);
 
             // Get the project's primary terminal for native token.
             // slither-disable-next-line calls-loop
-            IJBTerminal terminal = DIRECTORY.primaryTerminalOf({projectId: _projectId, token: JBConstants.NATIVE_TOKEN});
+            IJBTerminal terminal = DIRECTORY.primaryTerminalOf({projectId: projectId, token: JBConstants.NATIVE_TOKEN});
 
             if (address(terminal) == address(0)) {
-                revert JBSucker_NoTerminalForToken(_projectId, JBConstants.NATIVE_TOKEN);
+                revert JBSucker_NoTerminalForToken(projectId, JBConstants.NATIVE_TOKEN);
             }
 
             // Add native ETH to the project's balance.
             // slither-disable-next-line arbitrary-send-eth,calls-loop
             terminal.addToBalanceOf{value: amount}({
-                projectId: _projectId,
+                projectId: projectId,
                 token: JBConstants.NATIVE_TOKEN,
                 amount: amount,
                 shouldReturnHeldFees: false,
@@ -109,7 +108,7 @@ contract JBCeloSucker is JBOptimismSucker {
                 metadata: ""
             });
         } else {
-            super._addToBalance({token: token, amount: amount});
+            super._addToBalance({token: token, amount: amount, projectId: projectId});
         }
     }
 
@@ -139,42 +138,33 @@ contract JBCeloSucker is JBOptimismSucker {
             revert JBSucker_UnexpectedMsgValue(transportPayment);
         }
 
+        // Cache peer address to avoid redundant calls.
+        address peerAddress = _toAddress(peer());
+
         if (amount != 0) {
+            // Determine the local token to bridge — native ETH is wrapped to WETH first.
+            address bridgeToken = token;
             if (token == JBConstants.NATIVE_TOKEN) {
                 // Wrap native ETH → WETH so it can be bridged as ERC-20.
                 // slither-disable-next-line arbitrary-send-eth,calls-loop
                 WRAPPED_NATIVE.deposit{value: amount}();
-
-                // Approve the bridge to spend the WETH.
-                SafeERC20.forceApprove({
-                    token: IERC20(address(WRAPPED_NATIVE)), spender: address(OPBRIDGE), value: amount
-                });
-
-                // Bridge WETH as ERC-20.
-                // slither-disable-next-line reentrancy-events,calls-loop
-                OPBRIDGE.bridgeERC20To({
-                    localToken: address(WRAPPED_NATIVE),
-                    remoteToken: _toAddress(remoteToken.addr),
-                    to: _toAddress(peer()),
-                    amount: amount,
-                    minGasLimit: remoteToken.minGas,
-                    extraData: bytes("")
-                });
-            } else {
-                // ERC-20 token — bridge directly.
-                // slither-disable-next-line reentrancy-events
-                SafeERC20.forceApprove({token: IERC20(token), spender: address(OPBRIDGE), value: amount});
-
-                // slither-disable-next-line reentrancy-events,calls-loop
-                OPBRIDGE.bridgeERC20To({
-                    localToken: token,
-                    remoteToken: _toAddress(remoteToken.addr),
-                    to: _toAddress(peer()),
-                    amount: amount,
-                    minGasLimit: remoteToken.minGas,
-                    extraData: bytes("")
-                });
+                bridgeToken = address(WRAPPED_NATIVE);
             }
+
+            // Approve the bridge to spend the token.
+            // slither-disable-next-line reentrancy-events
+            SafeERC20.forceApprove({token: IERC20(bridgeToken), spender: address(OPBRIDGE), value: amount});
+
+            // Bridge the ERC-20 token to the peer.
+            // slither-disable-next-line reentrancy-events,calls-loop
+            OPBRIDGE.bridgeERC20To({
+                localToken: bridgeToken,
+                remoteToken: _toAddress(remoteToken.addr),
+                to: peerAddress,
+                amount: amount,
+                minGasLimit: remoteToken.minGas,
+                extraData: bytes("")
+            });
         }
 
         // Send the messenger message with nativeValue = 0.
@@ -182,7 +172,7 @@ contract JBCeloSucker is JBOptimismSucker {
         // On L1, the ETH was already wrapped and bridged as ERC-20 above.
         // slither-disable-next-line reentrancy-events,calls-loop
         OPMESSENGER.sendMessage({
-            target: _toAddress(peer()),
+            target: peerAddress,
             message: abi.encodeCall(JBSucker.fromRemote, (message)),
             gasLimit: MESSENGER_BASE_GAS_LIMIT
         });

package/src/JBOptimismSucker.sol

@@ -108,6 +108,9 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
             revert JBSucker_UnexpectedMsgValue(transportPayment);
         }
 
+        // Cache peer address to avoid redundant calls.
+        address peerAddress = _toAddress(peer());
+
         // If the token is an ERC20, bridge it to the peer.
         // If the amount is `0` then we do not need to bridge any ERC20.
         if (token != JBConstants.NATIVE_TOKEN && amount != 0) {
@@ -120,7 +123,7 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
             OPBRIDGE.bridgeERC20To({
                 localToken: token,
                 remoteToken: _toAddress(remoteToken.addr),
-                to: _toAddress(peer()),
+                to: peerAddress,
                 amount: amount,
                 minGasLimit: remoteToken.minGas,
                 extraData: bytes("")
@@ -131,10 +134,9 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
         }
 
         // Send the message to the peer with the reclaimed ETH.
-        // Convert bytes32 peer to address at the OP Messenger API boundary.
         // slither-disable-next-line arbitrary-send-eth,reentrancy-events,calls-loop
         OPMESSENGER.sendMessage{value: nativeValue}({
-            target: _toAddress(peer()),
+            target: peerAddress,
             message: abi.encodeCall(JBSucker.fromRemote, (message)),
             gasLimit: MESSENGER_BASE_GAS_LIMIT
         });

package/src/JBSucker.sol

@@ -65,6 +65,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     error JBSucker_NoTerminalForToken(uint256 projectId, address token);
     error JBSucker_NotPeer(bytes32 caller);
     error JBSucker_NothingToSend();
+    error JBSucker_RefundFailed();
     error JBSucker_TokenAlreadyMapped(address localToken, bytes32 mappedTo);
     error JBSucker_TokenHasInvalidEmergencyHatchState(address token);
     error JBSucker_TokenNotMapped(address token);
@@ -302,10 +303,17 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     )
         internal
         pure
-        returns (bytes32)
+        returns (bytes32 hash)
     {
+        // All three arguments are 32 bytes — hash from free memory to avoid abi.encode allocation overhead.
         // forge-lint: disable-next-line(asm-keccak256)
-        return keccak256(abi.encode(projectTokenCount, terminalTokenAmount, beneficiary));
+        assembly {
+            let ptr := mload(0x40)
+            mstore(ptr, projectTokenCount)
+            mstore(add(ptr, 0x20), terminalTokenAmount)
+            mstore(add(ptr, 0x40), beneficiary)
+            hash := keccak256(ptr, 0x60)
+        }
     }
 
     /// @dev ERC-2771 specifies the context as being a single address (20 bytes).
@@ -365,8 +373,11 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// claim).
     function claim(JBClaim[] calldata claims) external override {
         // Claim each.
-        for (uint256 i; i < claims.length; i++) {
+        for (uint256 i; i < claims.length;) {
             claim(claims[i]);
+            unchecked {
+                ++i;
+            }
         }
     }
 
@@ -416,10 +427,13 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         });
 
         // Enable the emergency hatch for each token.
-        for (uint256 i; i < tokens.length; i++) {
+        for (uint256 i; i < tokens.length;) {
             // We have an invariant where if emergencyHatch is true, enabled should be false.
             _remoteTokenFor[tokens[i]].enabled = false;
             _remoteTokenFor[tokens[i]].emergencyHatch = true;
+            unchecked {
+                ++i;
+            }
         }
 
         emit EmergencyHatchOpened(tokens, _msgSender());
@@ -543,23 +557,34 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
         // Loop over the number of mappings and increase numberToDisable to correctly set transportPaymentValue.
         // Note: if all mappings are enable-only (no disables), `numberToDisable` stays 0 and `transportPaymentValue`
-        // is set to 0 for each call. Any ETH sent with the transaction is not used or refunded — callers should
-        // not send ETH when only enabling mappings (no root flush is needed).
-        for (uint256 h; h < maps.length; h++) {
+        // is set to 0 for each call. Any ETH sent with the transaction is refunded after the second loop.
+        for (uint256 h; h < maps.length;) {
             JBOutboxTree storage _outbox = _outboxOf[maps[h].localToken];
             if (maps[h].remoteToken == bytes32(0) && _outbox.numberOfClaimsSent != _outbox.tree.count) {
                 numberToDisable++;
             }
+            unchecked {
+                ++h;
+            }
         }
 
         // Perform each token mapping.
-        for (uint256 i; i < maps.length; i++) {
+        for (uint256 i; i < maps.length;) {
             // slither-disable-next-line msg-value-loop
             _mapToken({map: maps[i], transportPaymentValue: numberToDisable > 0 ? msg.value / numberToDisable : 0});
+            unchecked {
+                ++i;
+            }
         }
 
-        // Refund any remainder from integer division so dust wei isn't stuck in the contract.
-        if (numberToDisable > 0) {
+        // If no tokens were disabled, the full `msg.value` is unused — refund it.
+        if (numberToDisable == 0) {
+            if (msg.value > 0) {
+                (bool _ok,) = _msgSender().call{value: msg.value}("");
+                if (!_ok) revert JBSucker_RefundFailed();
+            }
+        } else {
+            // Refund any remainder from integer division so dust wei isn't stuck in the contract.
             uint256 remainder = msg.value % numberToDisable;
             if (remainder > 0) {
                 // Best-effort refund — don't revert if caller can't accept ETH.
@@ -681,6 +706,11 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// (not added back to `transportPayment`) to avoid reverting the entire transaction. This preserves
     /// `transportPayment = msg.value - fee`, which is critical for zero-cost bridges (OP, Base, Celo, Arb L2->L1)
     /// that revert on non-zero transport payment. The fee amount is typically small (max 0.001 ETH).
+    /// @dev Retained fee ETH is absorbed by future native token claims. Because `amountToAddToBalanceOf` computes
+    /// `_balanceOf(token, address(this)) - _outboxOf[token].balance`, any extra ETH in the contract (including
+    /// retained fees) increases the claimable amount and will be forwarded to the project's terminal via
+    /// `_addToBalance` when the next native token claim is processed. This is by design — reverting on fee
+    /// failure would block all bridging.
     /// @param token The terminal token being bridged.
     function toRemote(address token) external payable override {
         JBRemoteToken memory remoteToken = _remoteTokenFor[token];
@@ -731,7 +761,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             }
         }
         // If no terminal exists, fee ETH stays in this contract. transportPayment is already correct.
-        // This retained ETH is an accepted stuck-funds edge case; later `claim` calls do not sweep it.
+        // This retained ETH is absorbed by future native token claims via `amountToAddToBalanceOf`.
 
         // Send the merkle root to the remote chain.
         _sendRoot({transportPayment: transportPayment, token: token, remoteToken: remoteToken});
@@ -759,22 +789,20 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @notice Adds funds to the projects balance.
     /// @param token The terminal token to add to the project's balance.
     /// @param amount The amount of terminal tokens to add to the project's balance.
-    function _addToBalance(address token, uint256 amount) internal virtual {
+    /// @param projectId The cached project ID to avoid redundant storage reads.
+    function _addToBalance(address token, uint256 amount, uint256 projectId) internal virtual {
         // Make sure that the current `amountToAddToBalance` is greater than or equal to the amount being added.
         uint256 addableAmount = amountToAddToBalanceOf(token);
         if (amount > addableAmount) {
             revert JBSucker_InsufficientBalance(amount, addableAmount);
         }
 
-        uint256 _projectId = projectId();
-
         // Get the project's primary terminal for the token.
-        // slither
         // slither-disable-next-line calls-loop
-        IJBTerminal terminal = DIRECTORY.primaryTerminalOf({projectId: _projectId, token: token});
+        IJBTerminal terminal = DIRECTORY.primaryTerminalOf({projectId: projectId, token: token});
 
         // slither-disable-next-line incorrect-equality
-        if (address(terminal) == address(0)) revert JBSucker_NoTerminalForToken(_projectId, token);
+        if (address(terminal) == address(0)) revert JBSucker_NoTerminalForToken(projectId, token);
 
         // Perform the `addToBalance`.
         if (token != JBConstants.NATIVE_TOKEN) {
@@ -785,7 +813,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
             // slither-disable-next-line calls-loop
             terminal.addToBalanceOf({
-                projectId: _projectId, token: token, amount: amount, shouldReturnHeldFees: false, memo: "", metadata: ""
+                projectId: projectId, token: token, amount: amount, shouldReturnHeldFees: false, memo: "", metadata: ""
             });
 
             // Sanity check: make sure we transfer the full amount.
@@ -795,7 +823,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             // If the token is the native token, use `msg.value`.
             // slither-disable-next-line arbitrary-send-eth,calls-loop
             terminal.addToBalanceOf{value: amount}({
-                projectId: _projectId, token: token, amount: amount, shouldReturnHeldFees: false, memo: "", metadata: ""
+                projectId: projectId, token: token, amount: amount, shouldReturnHeldFees: false, memo: "", metadata: ""
             });
         }
     }
@@ -813,13 +841,13 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     )
         internal
     {
+        uint256 cachedProjectId = projectId();
+
         // Add the cashed out funds to the project's balance.
         if (terminalTokenAmount != 0) {
-            _addToBalance({token: terminalToken, amount: terminalTokenAmount});
+            _addToBalance({token: terminalToken, amount: terminalTokenAmount, projectId: cachedProjectId});
         }
 
-        uint256 _projectId = projectId();
-
         // Cast the bytes32 beneficiary to an EVM address for the local mint.
         address beneficiaryAddress = _toAddress(beneficiary);
 
@@ -830,9 +858,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         //
         // Mint the project tokens for the beneficiary.
         // slither-disable-next-line calls-loop,unused-return
-        IJBController(address(DIRECTORY.controllerOf(_projectId)))
+        IJBController(address(DIRECTORY.controllerOf(cachedProjectId)))
             .mintTokensOf({
-                projectId: _projectId,
+                projectId: cachedProjectId,
                 tokenCount: projectTokenAmount,
                 beneficiary: beneficiaryAddress,
                 memo: "",
@@ -865,18 +893,15 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // Get the outbox in storage.
         JBOutboxTree storage outbox = _outboxOf[token];
 
-        // Create a new tree based on the outbox tree for the terminal token with the hash inserted.
-        MerkleLib.Tree memory tree = outbox.tree.insert(hashed);
-
-        // Update the outbox tree and balance for the terminal token.
-        outbox.tree = tree;
+        // Insert the hash directly into the storage-backed tree — writes only the changed branch slot and count.
+        outbox.tree.insert(hashed);
         outbox.balance += terminalTokenAmount;
 
         emit InsertToOutboxTree({
             beneficiary: beneficiary,
             token: token,
             hashed: hashed,
-            index: tree.count - 1, // Subtract 1 since we want the 0-based index.
+            index: outbox.tree.count - 1, // Subtract 1 since we want the 0-based index.
             root: outbox.tree.root(),
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
@@ -1051,7 +1076,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
         // Update the numberOfClaimsSent to the current count of the tree.
         // This is used as in the fallback to allow users to withdraw locally if the bridge is reverting.
-        outbox.numberOfClaimsSent = count;
+        outbox.numberOfClaimsSent = uint192(count);
         uint256 index = count - 1;
 
         // Emit an event for the relayers to watch for.

package/src/JBSuckerRegistry.sol

@@ -120,13 +120,16 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         pairs = new JBSuckersPair[](suckers.length);
 
         // Populate the array of pairs.
-        for (uint256 i; i < suckers.length; i++) {
+        for (uint256 i; i < suckers.length;) {
             // Get the sucker being iterated over.
             IJBSucker sucker = IJBSucker(suckers[i]);
 
             // slither-disable-next-line calls-loop
             pairs[i] =
                 JBSuckersPair({local: address(sucker), remote: sucker.peer(), remoteChainId: sucker.peerChainId()});
+            unchecked {
+                ++i;
+            }
         }
     }
 
@@ -174,14 +177,20 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     /// @dev Can only be called by this contract's owner (initially project ID 1, or JuiceboxDAO).
     /// @param deployers The address of the deployer to add.
     function allowSuckerDeployers(address[] calldata deployers) public override onlyOwner {
+        // Cache _msgSender() to avoid redundant calls in the loop.
+        address sender = _msgSender();
+
         // Iterate through the deployers and allow them.
-        for (uint256 i; i < deployers.length; i++) {
+        for (uint256 i; i < deployers.length;) {
             // Get the deployer being iterated over.
             address deployer = deployers[i];
 
             // Allow the deployer.
             suckerDeployerIsAllowed[deployer] = true;
-            emit SuckerDeployerAllowed({deployer: deployer, caller: _msgSender()});
+            emit SuckerDeployerAllowed({deployer: deployer, caller: sender});
+            unchecked {
+                ++i;
+            }
         }
     }
 
@@ -210,14 +219,17 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         // Create an array to store the suckers as they are deployed.
         suckers = new address[](configurations.length);
 
+        // Cache _msgSender() to avoid redundant calls in the loop.
+        address sender = _msgSender();
+
         // Calculate the salt using the sender's address and the provided `salt`.
         // This is an intentional part of the same-address peer invariant: if projects deploy suckers from
         // different sender addresses on different chains, the resulting sucker addresses will differ and the
         // default peer symmetry assumption will not hold.
-        salt = keccak256(abi.encode(_msgSender(), salt));
+        salt = keccak256(abi.encode(sender, salt));
 
         // Iterate through the configurations and deploy the suckers.
-        for (uint256 i; i < configurations.length; i++) {
+        for (uint256 i; i < configurations.length;) {
             // Get the configuration being iterated over.
             JBSuckerDeployerConfig memory configuration = configurations[i];
 
@@ -239,8 +251,11 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
             // slither-disable-next-line reentrancy-events,calls-loop
             sucker.mapTokens(configuration.mappings);
             emit SuckerDeployedFor({
-                projectId: projectId, sucker: address(sucker), configuration: configuration, caller: _msgSender()
+                projectId: projectId, sucker: address(sucker), configuration: configuration, caller: sender
             });
+            unchecked {
+                ++i;
+            }
         }
     }
 

package/src/structs/JBOutboxTree.sol

@@ -6,14 +6,14 @@ import {MerkleLib} from "../utils/MerkleLib.sol";
 /// @notice A merkle tree used to track the outbox for a given token in a `JBSucker`.
 /// @dev The outbox is used to send from the local chain to the remote chain.
 /// @custom:member nonce The nonce of the outbox.
+/// @custom:member numberOfClaimsSent the number of claims that have been sent to the peer. Used to determine which
+/// claims have been sent. Packed with `nonce` into one storage slot.
 /// @custom:member balance The balance of the outbox.
 /// @custom:member tree The merkle tree.
-/// @custom:member numberOfClaimsSent the number of claims that have been sent to the peer. Used to determine which
-/// claims have been sent.
 // forge-lint: disable-next-line(pascal-case-struct)
 struct JBOutboxTree {
     uint64 nonce;
+    uint192 numberOfClaimsSent;
     uint256 balance;
     MerkleLib.Tree tree;
-    uint256 numberOfClaimsSent;
 }

package/src/utils/MerkleLib.sol

@@ -80,14 +80,15 @@ library MerkleLib {
     //*********************************************************************//
 
     /**
-     * @notice Inserts a given node (leaf) into merkle tree. Operates on an in-memory tree and
-     * returns an updated version of that tree.
+     * @notice Inserts a given node (leaf) into the merkle tree in storage.
+     * @dev Operates directly on storage, writing only the single branch entry that changes (plus count).
+     * This avoids the 33-slot memory round-trip of the previous memory-based approach.
      * @dev Reverts if the tree is already full.
+     * @param tree The storage reference to the tree.
      * @param node Element to insert into tree.
-     * @return Tree Updated tree.
      *
      */
-    function insert(Tree memory tree, bytes32 node) internal pure returns (Tree memory) {
+    function insert(Tree storage tree, bytes32 node) internal {
         // Update tree.count to increase the current count by 1 since we'll be including a new node.
         uint256 size = ++tree.count;
         if (size > MAX_LEAVES) revert MerkleLib_InsertTreeIsFull();
@@ -101,10 +102,16 @@ library MerkleLib {
                 // If i > 0, then this node will be a hash of the original node with every layer up
                 // until layer `i`.
                 tree.branch[i] = node;
-                return tree;
+                return;
             }
             // If the size is not yet odd, we hash the current index in the tree branch with the node.
-            node = keccak256(abi.encodePacked(tree.branch[i], node));
+            // Use assembly to hash directly from scratch space, avoiding abi.encodePacked allocation.
+            bytes32 branchVal = tree.branch[i];
+            assembly {
+                mstore(0x00, branchVal)
+                mstore(0x20, node)
+                node := keccak256(0x00, 0x40)
+            }
             size >>= 1; // Cut size in half (statement equivalent to: `size /= 2`).
 
             unchecked {

package/test/SuckerDeepAttacks.t.sol

@@ -147,7 +147,7 @@ contract DeepAttackSucker is JBSucker {
     }
 
     function test_setNumberOfClaimsSent(address token, uint256 count) external {
-        _outboxOf[token].numberOfClaimsSent = count;
+        _outboxOf[token].numberOfClaimsSent = uint192(count);
     }
 
     function test_getInboxRoot(address token) external view returns (bytes32) {

package/test/TestAuditGaps.sol

@@ -139,7 +139,7 @@ contract AuditGapSucker is JBSucker {
     }
 
     function test_setNumberOfClaimsSent(address token, uint256 count) external {
-        _outboxOf[token].numberOfClaimsSent = count;
+        _outboxOf[token].numberOfClaimsSent = uint192(count);
     }
 
     function test_getNumberOfClaimsSent(address token) external view returns (uint256) {

package/test/audit/codex-MapTokensEnableOnlyValueStuck.t.sol

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+// forge-lint: disable-next-line(unaliased-plain-import)
+import "forge-std/Test.sol";
+
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+import {LibClone} from "solady/src/utils/LibClone.sol";
+
+import "../../src/JBSucker.sol";
+import "../../src/interfaces/IJBSuckerRegistry.sol";
+import "../../src/structs/JBMessageRoot.sol";
+import "../../src/structs/JBRemoteToken.sol";
+import "../../src/structs/JBTokenMapping.sol";
+
+contract CodexMapTokensHarness is JBSucker {
+    constructor(
+        IJBDirectory directory,
+        IJBPermissions permissions,
+        IJBTokens tokens
+    )
+        JBSucker(directory, permissions, tokens, 1, IJBSuckerRegistry(address(1)), address(0))
+    {}
+
+    function peerChainId() external view override returns (uint256) {
+        return block.chainid;
+    }
+
+    function _isRemotePeer(address sender) internal view override returns (bool) {
+        return sender == _toAddress(peer());
+    }
+
+    function _sendRootOverAMB(
+        uint256,
+        uint256,
+        address,
+        uint256,
+        JBRemoteToken memory,
+        JBMessageRoot memory
+    )
+        internal
+        override
+    {}
+}
+
+contract CodexMapTokensEnableOnlyValueStuckTest is Test {
+    address internal constant DIRECTORY = address(0x1000);
+    address internal constant PERMISSIONS = address(0x2000);
+    address internal constant TOKENS = address(0x3000);
+    address internal constant PROJECT = address(0x4000);
+
+    uint256 internal constant PROJECT_ID = 1;
+
+    function test_mapTokensEnableOnlyBatchRefundsMsgValue() external {
+        vm.mockCall(DIRECTORY, abi.encodeCall(IJBDirectory.PROJECTS, ()), abi.encode(PROJECT));
+        vm.mockCall(PROJECT, abi.encodeCall(IERC721.ownerOf, (PROJECT_ID)), abi.encode(address(this)));
+        vm.mockCall(PERMISSIONS, abi.encodeWithSelector(IJBPermissions.hasPermission.selector), abi.encode(true));
+
+        CodexMapTokensHarness singleton =
+            new CodexMapTokensHarness(IJBDirectory(DIRECTORY), IJBPermissions(PERMISSIONS), IJBTokens(TOKENS));
+        CodexMapTokensHarness sucker = CodexMapTokensHarness(
+            payable(address(LibClone.cloneDeterministic(address(singleton), bytes32("codex-enable-only-msgvalue"))))
+        );
+        sucker.initialize(PROJECT_ID);
+
+        JBTokenMapping[] memory maps = new JBTokenMapping[](1);
+        maps[0] = JBTokenMapping({
+            localToken: address(0xBEEF),
+            minGas: sucker.MESSENGER_ERC20_MIN_GAS_LIMIT(),
+            remoteToken: bytes32(uint256(uint160(address(0xCAFE))))
+        });
+
+        uint256 balanceBefore = address(this).balance;
+        sucker.mapTokens{value: 1 ether}(maps);
+
+        assertEq(address(sucker).balance, 0, "enable-only msg.value should not stay in the sucker");
+        assertEq(address(this).balance, balanceBefore, "enable-only msg.value should be refunded to caller");
+    }
+
+    receive() external payable {}
+}

package/test/unit/emergency.t.sol

@@ -314,5 +314,5 @@ contract TestSucker is JBSucker {
 
     /// @dev Override _addToBalance to be a no-op for fuzz testing.
     /// These tests focus on emergency exit state machine behavior, not token balance mechanics.
-    function _addToBalance(address, uint256) internal override {}
+    function _addToBalance(address, uint256, uint256) internal override {}
 }

package/test/unit/invariants.t.sol

@@ -133,7 +133,7 @@ contract InvariantSucker is JBSucker {
     }
 
     function test_setNumberOfClaimsSent(address token, uint256 count) external {
-        _outboxOf[token].numberOfClaimsSent = count;
+        _outboxOf[token].numberOfClaimsSent = uint192(count);
     }
 
     function test_setDeprecatedAfter(uint256 timestamp) external {

package/test/unit/merkle.t.sol

@@ -174,7 +174,7 @@ contract MerkleUnitTest is JBSucker, Test {
 
     /// @dev Override _addToBalance to be a no-op for merkle proof testing.
     /// These tests focus on merkle tree proof validation, not token balance mechanics.
-    function _addToBalance(address, uint256) internal override {}
+    function _addToBalance(address, uint256, uint256) internal override {}
 
     function _isRemotePeer(address) internal view virtual override returns (bool valid) {
         return false;