@bananapus/suckers-v6 0.0.57 → 0.0.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "3.2.0",
-    "@bananapus/core-v6": "^0.0.60",
+    "@bananapus/core-v6": "^0.0.66",
     "@bananapus/permission-ids-v6": "^0.0.27",
     "@chainlink/contracts-ccip": "1.6.4",
     "@chainlink/local": "0.2.7",

package/src/JBBaseSucker.sol

@@ -16,7 +16,7 @@ contract JBBaseSucker is JBOptimismSucker {
     // ---------------------------- constructor -------------------------- //
     //*********************************************************************//
 
-    /// @param deployer A contract that deploys the clones for this contracts.
+    /// @param deployer A contract that deploys clones of this contract.
     /// @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.

package/src/JBCeloSucker.sol

@@ -35,7 +35,7 @@ contract JBCeloSucker is JBOptimismSucker {
     // ---------------------------- constructor -------------------------- //
     //*********************************************************************//
 
-    /// @param deployer A contract that deploys the clones for this contracts.
+    /// @param deployer A contract that deploys clones of this contract.
     /// @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.
@@ -135,7 +135,7 @@ contract JBCeloSucker is JBOptimismSucker {
     {
         index; // Silence unused parameter warning (not needed for Celo bridge).
 
-        // Revert if there's a `msg.value`. The OP bridge does not expect to be paid.
+        // Revert if there's a `msg.value`. The Celo bridge does not expect to be paid.
         if (transportPayment != 0) {
             revert JBSucker_UnexpectedMsgValue({value: transportPayment});
         }

package/src/JBOptimismSucker.sol

@@ -36,7 +36,7 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
     // ---------------------------- constructor -------------------------- //
     //*********************************************************************//
 
-    /// @param deployer A contract that deploys the clones for this contracts.
+    /// @param deployer A contract that deploys clones of this contract.
     /// @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.

package/src/JBSucker.sol

@@ -95,12 +95,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     // ------------------------- public constants ------------------------ //
     //*********************************************************************//
 
-    /// @notice A reasonable minimum gas limit for a basic cross-chain call. The minimum amount of gas required to call
-    /// the `fromRemote` (successfully/safely) on the remote chain.
+    /// @notice A reasonable minimum gas limit for a basic cross-chain call to `fromRemote` on the remote chain.
     uint32 public constant override MESSENGER_BASE_GAS_LIMIT = 300_000;
 
-    /// @notice A reasonable minimum gas limit used when bridging ERC-20s. The minimum amount of gas required to
-    /// (successfully/safely) perform a transfer on the remote chain.
+    /// @notice A reasonable minimum gas limit for performing an ERC-20 transfer on the remote chain.
     uint32 public constant override MESSENGER_ERC20_MIN_GAS_LIMIT = 200_000;
 
     /// @notice The message format version. Used to reject incompatible messages from remote chains.
@@ -142,6 +140,15 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @notice The address of this contract's deployer.
     address public override deployer;
 
+    /// @notice The keccak256 hash of the leaf data committed at execution time, keyed by `(terminalToken,
+    /// leafIndex)`. Beneficiary contracts (e.g. `JBReferralSplitHook`) use this to authenticate post-hoc
+    /// settlement when their `claim()` call was front-run by a direct external caller — they re-derive the
+    /// hash from the claim data they hold and compare. Returns `bytes32(0)` for unexecuted indices —
+    /// `_buildTreeHash` is pre-image-resistant so zero unambiguously means "not executed".
+    /// @custom:param token The token whose inbox tree contains the leaf.
+    /// @custom:param index The leaf's index in the inbox tree.
+    mapping(address token => mapping(uint256 index => bytes32)) public override executedLeafHashOf;
+
     /// @notice The last known total token supply on the peer chain, updated each time a bridge message is received.
     /// @dev Used by data hooks to compute `effectiveTotalSupply = localSupply + sum(peerChainTotalSupply)` across all
     /// suckers, preventing cash out tax bypass on chains where a holder dominates the local supply.
@@ -601,7 +608,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             account: _ownerOf(_projectId), projectId: _projectId, permissionId: JBPermissionIds.SET_SUCKER_DEPRECATION
         });
 
-        // This is the earliest time for when the sucker can be considered deprecated.
+        // This is the earliest time the sucker can be considered deprecated.
         // There is a mandatory delay to allow for remaining messages to be received.
         // This should be called on both sides of the suckers, preferably with a matching timestamp.
         uint256 nextEarliestDeprecationTime = block.timestamp + _maxMessagingDelay();
@@ -804,7 +811,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             return JBSuckerState.ENABLED;
         }
 
-        // The sucker will soon be considered deprecated, this functions only as a warning to users.
+        // The sucker is close to deprecation; this state only warns users.
         // Deprecation state is intentionally time-based.
         // forge-lint: disable-next-line(block-timestamp)
         if (block.timestamp < _deprecatedAfter - _maxMessagingDelay()) {
@@ -927,40 +934,35 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             revert JBSucker_NoTerminalForToken({projectId: cachedProjectId, token: token});
         }
 
-        // Perform the `addToBalance` for ERC-20 tokens.
-        if (token != JBConstants.NATIVE_TOKEN) {
-            // Record the balance before the transfer for the sanity check.
-            uint256 balanceBefore = IERC20(token).balanceOf(address(this));
-
-            // Approve the terminal to spend the ERC-20 tokens.
+        // Native and ERC-20 differ only in (a) value attachment to the call, and (b) ERC-20 requires an
+        // allowance grant + post-transfer balance assertion to catch fee-on-transfer / non-conforming tokens.
+        // The terminal call itself is identical for both, so it lives outside the branch.
+        uint256 nativeValue;
+        uint256 balanceBefore;
+        bool isErc20 = token != JBConstants.NATIVE_TOKEN;
+        if (isErc20) {
+            balanceBefore = IERC20(token).balanceOf(address(this));
             SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
+        } else {
+            nativeValue = amount;
+        }
 
-            // Add the tokens to the project's balance.
-            terminal.addToBalanceOf({
-                projectId: cachedProjectId,
-                token: token,
-                amount: amount,
-                shouldReturnHeldFees: false,
-                memo: "",
-                metadata: ""
-            });
+        terminal.addToBalanceOf{value: nativeValue}({
+            projectId: cachedProjectId,
+            token: token,
+            amount: amount,
+            shouldReturnHeldFees: false,
+            memo: "",
+            metadata: ""
+        });
 
-            // Sanity check: make sure we transferred the full amount.
+        if (isErc20) {
+            // Sanity check: catches fee-on-transfer / non-conforming ERC-20s that move less than `amount`.
             assert(IERC20(token).balanceOf(address(this)) == balanceBefore - amount);
-        } else {
-            // If the token is the native token, send ETH with the call.
-            terminal.addToBalanceOf{value: amount}({
-                projectId: cachedProjectId,
-                token: token,
-                amount: amount,
-                shouldReturnHeldFees: false,
-                memo: "",
-                metadata: ""
-            });
         }
     }
 
-    /// @notice The action(s) to perform after a user has succesfully proven their claim.
+    /// @notice Actions to perform after a user has successfully proven their claim.
     /// @param terminalToken The terminal token to suck.
     /// @param terminalTokenAmount The amount of terminal tokens.
     /// @param projectTokenAmount The amount of project tokens.
@@ -1204,10 +1206,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     }
 
     /// @notice Send the outbox root for the specified token to the remote peer.
-    /// @dev The call may have a `transportPayment` for bridging native tokens. Require it to be `0` if it is not
-    /// needed. Make sure if a value being paid to the bridge is expected to revert if the given value is `0`.
-    /// @param transportPayment the amount of `msg.value` that is going to get paid for sending this message. (usually
-    /// derived from `msg.value`)
+    /// @dev Some bridges require a nonzero `transportPayment`; zero-cost bridges must reject nonzero values.
+    /// @param transportPayment The amount of `msg.value` paid to the transport for this message.
     /// @param token The terminal token to bridge the merkle tree of.
     /// @param remoteToken The remote token which the `token` is mapped to.
     function _sendRoot(uint256 transportPayment, address token, JBRemoteToken memory remoteToken) internal virtual {
@@ -1324,16 +1324,21 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // Register the leaf as executed to prevent double-spending.
         _executedFor[terminalToken].set(index);
 
-        // Calculate the root based on the leaf, the branch, and the index.
-        // Compare to the current root, Revert if they do not match.
-        _validateBranchRoot({
-            expectedRoot: _inboxOf[terminalToken].root,
+        // Compute the leaf hash once. It's used twice: stored in `executedLeafHashOf` (so beneficiary contracts
+        // can authenticate post-hoc settlement when their `claim()` was front-run) and passed to
+        // `_validateBranchRoot` for merkle verification. The bare executed bitmap proves "some leaf at index I
+        // was executed" but not "which leaf"; storing the hash binds the index to the actual leaf content.
+        bytes32 leafHash = _buildTreeHash({
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
             beneficiary: beneficiary,
-            metadata: metadata,
-            index: index,
-            leaves: leaves
+            metadata: metadata
+        });
+        executedLeafHashOf[terminalToken][index] = leafHash;
+
+        // Calculate the root and compare it to the current inbox root.
+        _validateBranchRoot({
+            expectedRoot: _inboxOf[terminalToken].root, leafHash: leafHash, index: index, leaves: leaves
         });
     }
 
@@ -1341,17 +1346,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @dev This is a virtual function to allow a tests to override the behavior, it should never be overwritten
     /// otherwise.
     /// @param expectedRoot The expected merkle root to validate against.
-    /// @param projectTokenCount The number of project tokens in the leaf.
-    /// @param terminalTokenAmount The amount of terminal tokens in the leaf.
-    /// @param beneficiary The beneficiary address in the leaf (bytes32 for cross-VM compatibility).
+    /// @param leafHash The precomputed leaf hash (`_buildTreeHash` output) for the leaf being validated.
     /// @param index The index of the leaf in the merkle tree.
     /// @param leaves The merkle branch proving the leaf's inclusion.
     function _validateBranchRoot(
         bytes32 expectedRoot,
-        uint256 projectTokenCount,
-        uint256 terminalTokenAmount,
-        bytes32 beneficiary,
-        bytes32 metadata,
+        bytes32 leafHash,
         uint256 index,
         bytes32[_TREE_DEPTH] calldata leaves
     )
@@ -1360,18 +1360,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     {
         // Calculate the root based on the leaf, the branch, and the index.
         // Delegates to JBSuckerLib (via DELEGATECALL) to keep MerkleLib.branchRoot bytecode out of each sucker.
-        bytes32 root = JBSuckerLib.computeBranchRoot({
-            item: _buildTreeHash({
-                projectTokenCount: projectTokenCount,
-                terminalTokenAmount: terminalTokenAmount,
-                beneficiary: beneficiary,
-                metadata: metadata
-            }),
-            branch: leaves,
-            index: index
-        });
+        bytes32 root = JBSuckerLib.computeBranchRoot({item: leafHash, branch: leaves, index: index});
 
-        // Compare to the current root, Revert if they do not match.
+        // Revert if the computed root does not match the expected inbox root.
         if (root != expectedRoot) {
             revert JBSucker_InvalidProof({root: root, inboxRoot: expectedRoot});
         }
@@ -1453,14 +1444,15 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             _executedFor[emergencyExitAddress].set(index);
         }
 
-        // Calculate the root based on the leaf, the branch, and the index.
-        // Compare to the current root, Revert if they do not match.
+        // Calculate the root and compare it to the current outbox root.
         _validateBranchRoot({
             expectedRoot: _computeOutboxRoot(_outboxOf[terminalToken].tree),
-            projectTokenCount: projectTokenCount,
-            terminalTokenAmount: terminalTokenAmount,
-            beneficiary: beneficiary,
-            metadata: metadata,
+            leafHash: _buildTreeHash({
+                projectTokenCount: projectTokenCount,
+                terminalTokenAmount: terminalTokenAmount,
+                beneficiary: beneficiary,
+                metadata: metadata
+            }),
             index: index,
             leaves: leaves
         });

package/src/JBSuckerRegistry.sol

@@ -35,6 +35,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     error JBSuckerRegistry_InvalidDeployer(IJBSuckerDeployer deployer);
     error JBSuckerRegistry_SuckerDoesNotBelongToProject(uint256 projectId, address sucker);
     error JBSuckerRegistry_SuckerIsNotDeprecated(address sucker, JBSuckerState suckerState);
+    error JBSuckerRegistry_ZeroPeerChainId(address sucker);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -108,6 +109,18 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
+    /// @notice All suckers for a project, INCLUDING deprecated entries that are no longer listed in `suckersOf`.
+    /// @dev Used by consumers that need to detect "has any sucker ever peered to chain X?" — e.g. to prevent
+    /// premature burn of bridgeable credit by `JBReferralSplitHook.burnUnbridgeableCreditFor`. Returns every key
+    /// from `_suckersOf[projectId]` regardless of active/deprecated state. Order matches the underlying
+    /// `EnumerableMap` iteration order (insertion order, with swap-and-pop semantics on removal — which this
+    /// registry doesn't trigger, since deprecation transitions to `_SUCKER_DEPRECATED` rather than deleting).
+    /// @param projectId The ID of the project to get the suckers of.
+    /// @return suckers The addresses of every sucker ever registered for `projectId`.
+    function allSuckersOf(uint256 projectId) external view override returns (address[] memory suckers) {
+        return _suckersOf[projectId].keys();
+    }
+
     /// @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.
@@ -142,8 +155,9 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
             (, uint256 val) = _suckersOf[projectId].tryGet(allSuckers[i]);
             if (val == _SUCKER_EXISTS) {
                 IJBSucker sucker = IJBSucker(allSuckers[i]);
-                pairs[j] =
-                    JBSuckersPair({local: address(sucker), remote: sucker.peer(), remoteChainId: sucker.peerChainId()});
+                pairs[j] = JBSuckersPair({
+                    local: address(sucker), remote: sucker.peer(), remoteChainId: _peerChainIdOf(sucker)
+                });
                 unchecked {
                     ++j;
                 }
@@ -220,7 +234,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
                 try IJBSucker(allSuckers[i]).peerChainBalanceOf({decimals: decimals, currency: currency}) returns (
                     JBDenominatedAmount memory amt
                 ) {
-                    uint256 chainId = IJBSucker(allSuckers[i]).peerChainId();
+                    uint256 chainId = _peerChainIdOf(IJBSucker(allSuckers[i]));
                     scratch.chainCount = _recordPeerValue({
                         scratch: scratch,
                         chainId: chainId,
@@ -276,7 +290,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
                 try IJBSucker(allSuckers[i]).peerChainSurplusOf({decimals: decimals, currency: currency}) returns (
                     JBDenominatedAmount memory amt
                 ) {
-                    uint256 chainId = IJBSucker(allSuckers[i]).peerChainId();
+                    uint256 chainId = _peerChainIdOf(IJBSucker(allSuckers[i]));
                     scratch.chainCount = _recordPeerValue({
                         scratch: scratch,
                         chainId: chainId,
@@ -319,7 +333,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
             // Include both active and deprecated suckers in aggregate economic views.
             if (val == _SUCKER_EXISTS || val == _SUCKER_DEPRECATED) {
                 try IJBSucker(allSuckers[i]).peerChainTotalSupply() returns (uint256 supply) {
-                    uint256 chainId = IJBSucker(allSuckers[i]).peerChainId();
+                    uint256 chainId = _peerChainIdOf(IJBSucker(allSuckers[i]));
                     scratch.chainCount = _recordPeerValue({
                         scratch: scratch,
                         chainId: chainId,
@@ -377,6 +391,14 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         scratch.hasActiveValue = new bool[](len);
     }
 
+    /// @notice Reads a sucker's peer chain ID, reverting if the sucker cannot identify a real peer chain.
+    /// @param sucker The sucker to query.
+    /// @return chainId The non-zero peer chain ID.
+    function _peerChainIdOf(IJBSucker sucker) internal view returns (uint256 chainId) {
+        chainId = sucker.peerChainId();
+        if (chainId == 0) revert JBSuckerRegistry_ZeroPeerChainId({sucker: address(sucker)});
+    }
+
     /// @notice Records a project-scoped peer-chain aggregate value.
     /// @dev Callers pass scratch arrays sized from `_suckersOf[projectId].keys()`, so entries are already scoped to
     /// the project being aggregated. For each peer chain, active suckers replace deprecated suckers; deprecated
@@ -544,6 +566,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
             // Create the sucker.
             IJBSucker sucker = configuration.deployer
             .createForSender({localProjectId: projectId, salt: salt, peer: configuration.peer});
+            _peerChainIdOf(sucker);
             suckers[i] = address(sucker);
 
             // Store the sucker as being deployed for this project.

package/src/JBSwapCCIPSucker.sol

@@ -39,7 +39,9 @@ import {JBSwapPoolLib} from "./libraries/JBSwapPoolLib.sol";
 
 // Local: structs (alphabetized).
 import {JBClaim} from "./structs/JBClaim.sol";
+import {JBConversionRate} from "./structs/JBConversionRate.sol";
 import {JBMessageRoot} from "./structs/JBMessageRoot.sol";
+import {JBPendingSwap} from "./structs/JBPendingSwap.sol";
 import {JBRemoteToken} from "./structs/JBRemoteToken.sol";
 
 /// @notice A `JBCCIPSucker` extension that swaps between local and bridge tokens using the best
@@ -71,7 +73,7 @@ import {JBRemoteToken} from "./structs/JBRemoteToken.sol";
 ///
 /// **Inbound swap resilience**: If a swap reverts during `ccipReceive` (due to insufficient
 /// liquidity, stale TWAP observations, or extreme price impact), the CCIP message still succeeds.
-/// The unswapped bridge tokens are stored in a `PendingSwap` and the merkle root is recorded
+/// The unswapped bridge tokens are stored in a `JBPendingSwap` and the merkle root is recorded
 /// normally. Claims for the affected batch are gated until `retrySwap` is called successfully.
 /// Anyone can call `retrySwap` once swap conditions improve.
 ///
@@ -88,6 +90,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
 
     error JBSwapCCIPSucker_BatchNotReceived(uint64 nonce);
     error JBSwapCCIPSucker_CallerNotPoolManager(address caller);
+    error JBSwapCCIPSucker_DuplicateBatch(uint64 nonce);
     error JBSwapCCIPSucker_InvalidBridgeToken(address bridgeToken, address wrappedNativeToken);
     error JBSwapCCIPSucker_NoPendingSwap(address localToken, uint64 nonce, bool retrySwapLocked);
     error JBSwapCCIPSucker_OnlySelf(address caller, address expected);
@@ -135,31 +138,11 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
     // ------------------- internal stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice Bridge tokens from a failed inbound swap, stored for later retry via `retrySwap`.
-    /// @custom:member bridgeToken The bridge token received from CCIP.
-    /// @custom:member bridgeAmount Amount of bridge tokens to swap.
-    /// @custom:member leafTotal Original leaf-denomination total (for conversion rate).
-    struct PendingSwap {
-        address bridgeToken;
-        uint256 bridgeAmount;
-        uint256 leafTotal;
-    }
-
     /// @notice Pending (failed) inbound swaps, keyed by local token and batch nonce.
     /// @dev Populated when `ccipReceive` swap fails; cleared when `retrySwap` succeeds.
     /// @custom:param localToken The local token the swap targets.
     /// @custom:param nonce The CCIP nonce identifying the batch.
-    mapping(address localToken => mapping(uint64 nonce => PendingSwap)) public pendingSwapOf;
-
-    /// @notice Immutable conversion rate for one received root batch, keyed by nonce.
-    /// @dev Each batch stores its total leaf and local amounts. Individual claims compute their
-    /// scaled amount as `claimLeafAmount * localTotal / leafTotal` — no mutable state changes.
-    /// @custom:member leafTotal Total leaf-denomination (source chain) amount for this batch.
-    /// @custom:member localTotal Total local-denomination (after swap) amount for this batch.
-    struct ConversionRate {
-        uint256 leafTotal;
-        uint256 localTotal;
-    }
+    mapping(address localToken => mapping(uint64 nonce => JBPendingSwap)) public pendingSwapOf;
 
     /// @notice End leaf index (exclusive) for each received root batch, keyed by token and nonce.
     /// @custom:param token The local token address.
@@ -176,7 +159,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
     /// @notice Conversion rate for each received root batch, keyed by token and nonce.
     /// @custom:param token The local token address.
     /// @custom:param nonce The CCIP nonce identifying the batch.
-    mapping(address token => mapping(uint64 nonce => ConversionRate)) internal _conversionRateOf;
+    mapping(address token => mapping(uint64 nonce => JBConversionRate)) internal _conversionRateOf;
 
     /// @notice Count of populated batch nonces per token. Appended exactly once per batch in
     /// `ccipReceive`, so it equals the number of received batches independent of CCIP ordering.
@@ -336,6 +319,19 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
                 }
             }
 
+            // Detect an already-processed batch before the swap path. The inbox nonce alone cannot be used here:
+            // CCIP can deliver nonce 2 before nonce 1, and nonce 1 still needs its self-described batch metadata.
+            if (
+                _batchEndOf[localToken][nonce] != 0 || _conversionRateOf[localToken][nonce].leafTotal != 0
+                    || pendingSwapOf[localToken][nonce].bridgeAmount != 0
+            ) {
+                if (deliveredAmount != 0) {
+                    revert JBSwapCCIPSucker_DuplicateBatch({nonce: nonce});
+                }
+
+                return;
+            }
+
             // After the validation block above, `deliveredToken != address(0)` iff a delivery was present,
             // because the invariants ensure it equals `BRIDGE_TOKEN` (a non-zero ERC-20) whenever there is one.
             if (deliveredToken != address(0)) {
@@ -378,61 +374,55 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
             //
             // Detect "already seen" without extra storage: a nonce has been processed if it has
             // either a batch range (batchEnd > 0) or a conversion rate / pending swap recorded.
-            if (
-                _batchEndOf[localToken][nonce] == 0 && _conversionRateOf[localToken][nonce].leafTotal == 0
-                    && pendingSwapOf[localToken][nonce].leafTotal == 0
-            ) {
-                // Record the batch range so _findNonceForLeafIndex can resolve leaf ownership
-                // independently of nonce ordering. Each nonce is self-describing: [start, end).
-                if (batchEnd > 0) {
-                    // Record this batch's half-open leaf range `[batchStart, batchEnd)`. Self-
-                    // describing per-nonce — no implicit chain across nonces — so out-of-order
-                    // delivery can still resolve a leaf to its batch.
-                    _batchStartOf[localToken][nonce] = batchStart;
-                    _batchEndOf[localToken][nonce] = batchEnd;
-
-                    // Append `nonce` to the populated-nonce list for this token. The outer
-                    // `_batchEndOf == 0 && _conversionRateOf == 0 && pendingSwapOf == 0` guard
-                    // fires at most once per (token, nonce), so each populated nonce is appended
-                    // exactly once — the array stays duplicate-free without extra checks.
-                    //
-                    // Reading `_populatedNonceCount[localToken]` first into a local lets us write
-                    // the new slot and the new count in a single read-modify-write pair (one
-                    // SLOAD, two SSTOREs to distinct slots). The `unchecked` increment is safe:
-                    // `priorCount` is bounded by the total number of populated nonces, which is
-                    // upper-bounded by the CCIP nonce space (`uint64`) — overflow requires more
-                    // batches than `uint64.max`, which the inbox can never produce.
-                    uint64 priorCount = _populatedNonceCount[localToken];
-                    _populatedNonceByIndex[localToken][priorCount] = nonce;
-                    unchecked {
-                        _populatedNonceCount[localToken] = priorCount + 1;
-                    }
+            // Record the batch range so _findNonceForLeafIndex can resolve leaf ownership
+            // independently of nonce ordering. Each nonce is self-describing: [start, end).
+            if (batchEnd > 0) {
+                // Record this batch's half-open leaf range `[batchStart, batchEnd)`. Self-
+                // describing per-nonce — no implicit chain across nonces — so out-of-order
+                // delivery can still resolve a leaf to its batch.
+                _batchStartOf[localToken][nonce] = batchStart;
+                _batchEndOf[localToken][nonce] = batchEnd;
+
+                // Append `nonce` to the populated-nonce list for this token. The duplicate guard
+                // above fires at most once per (token, nonce), so each populated nonce is appended
+                // exactly once — the array stays duplicate-free without extra checks.
+                //
+                // Reading `_populatedNonceCount[localToken]` first into a local lets us write
+                // the new slot and the new count in a single read-modify-write pair (one
+                // SLOAD, two SSTOREs to distinct slots). The `unchecked` increment is safe:
+                // `priorCount` is bounded by the total number of populated nonces, which is
+                // upper-bounded by the CCIP nonce space (`uint64`) — overflow requires more
+                // batches than `uint64.max`, which the inbox can never produce.
+                uint64 priorCount = _populatedNonceCount[localToken];
+                _populatedNonceByIndex[localToken][priorCount] = nonce;
+                unchecked {
+                    _populatedNonceCount[localToken] = priorCount + 1;
                 }
+            }
 
-                // Store pendingSwapOf for failed swaps now that nonce is validated.
-                if (swapFailed) {
-                    pendingSwapOf[localToken][nonce] =
-                        PendingSwap({bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal});
-                }
+            // Store pendingSwapOf for failed swaps now that nonce is validated.
+            if (swapFailed) {
+                pendingSwapOf[localToken][nonce] =
+                    JBPendingSwap({bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal});
+            }
 
-                // Zero-output swap guard: When a swap succeeds but returns zero local tokens, the
-                // batch must NOT be marked claimable. Without this guard, `_addToBalance` would see
-                // `pendingSwapOf.bridgeAmount == 0` (no pending swap stored) and allow claims to
-                // proceed — minting the full bridged project-token amount while adding zero terminal
-                // backing, breaking cross-chain solvency.
-                //
-                // Route zero-output swaps into `pendingSwapOf` so the swap can be retried via
-                // `retrySwap` once pool conditions improve. Only store the conversion rate when
-                // the swap produced a positive local amount.
-                if (leafTotal > 0 && !swapFailed) {
-                    if (localAmount == 0 && deliveredAmount > 0) {
-                        pendingSwapOf[localToken][nonce] = PendingSwap({
-                            bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal
-                        });
-                    } else {
-                        _conversionRateOf[localToken][nonce] =
-                            ConversionRate({leafTotal: leafTotal, localTotal: localAmount});
-                    }
+            // Zero-output swap guard: When a swap succeeds but returns zero local tokens, the
+            // batch must NOT be marked claimable. Without this guard, `_addToBalance` would see
+            // `pendingSwapOf.bridgeAmount == 0` (no pending swap stored) and allow claims to
+            // proceed — minting the full bridged project-token amount while adding zero terminal
+            // backing, breaking cross-chain solvency.
+            //
+            // Route zero-output swaps into `pendingSwapOf` so the swap can be retried via
+            // `retrySwap` once pool conditions improve. Only store the conversion rate when
+            // the swap produced a positive local amount.
+            if (leafTotal > 0 && !swapFailed) {
+                if (localAmount == 0 && deliveredAmount > 0) {
+                    pendingSwapOf[localToken][nonce] = JBPendingSwap({
+                        bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal
+                    });
+                } else {
+                    _conversionRateOf[localToken][nonce] =
+                        JBConversionRate({leafTotal: leafTotal, localTotal: localAmount});
                 }
             }
         } else {
@@ -497,7 +487,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
         }
         _retrySwapLocked = true;
 
-        PendingSwap memory pending = pendingSwapOf[localToken][nonce];
+        JBPendingSwap memory pending = pendingSwapOf[localToken][nonce];
         if (pending.bridgeAmount == 0) {
             revert JBSwapCCIPSucker_NoPendingSwap({
                 localToken: localToken, nonce: nonce, retrySwapLocked: _retrySwapLocked
@@ -508,7 +498,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
             _executeSwapOrRevert({tokenIn: pending.bridgeToken, tokenOut: localToken, amount: pending.bridgeAmount});
 
         // Update the conversion rate so claims can proceed, then clear the pending swap.
-        _conversionRateOf[localToken][nonce] = ConversionRate({leafTotal: pending.leafTotal, localTotal: localAmount});
+        _conversionRateOf[localToken][nonce] = JBConversionRate({leafTotal: pending.leafTotal, localTotal: localAmount});
         delete pendingSwapOf[localToken][nonce];
 
         _retrySwapLocked = false;
@@ -564,7 +554,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
                 if (pendingSwapOf[token][nonce].bridgeAmount > 0) {
                     revert JBSwapCCIPSucker_SwapPending({nonce: nonce});
                 }
-                ConversionRate storage rate = _conversionRateOf[token][nonce];
+                JBConversionRate storage rate = _conversionRateOf[token][nonce];
                 if (rate.leafTotal > 0) {
                     amount = amount * rate.localTotal / rate.leafTotal;
                 }

package/src/interfaces/IJBSucker.sol

@@ -108,6 +108,18 @@ interface IJBSucker is IERC165 {
     /// @return The deployer address.
     function deployer() external view returns (address);
 
+    /// @notice The keccak256 hash of the leaf data committed at execution time, for the leaf at the given
+    /// `(terminalToken, index)`. Returns `bytes32(0)` for unexecuted indices.
+    /// @dev Beneficiary contracts (e.g. `JBReferralSplitHook`) use this to authenticate post-hoc settlement when
+    /// their `claim()` call was front-run by a direct external caller — they re-derive the hash from the claim
+    /// data they hold and compare. The hash is computed via `_buildTreeHash(projectTokenCount,
+    /// terminalTokenAmount, beneficiary, metadata)` and is pre-image-resistant, so zero unambiguously means
+    /// "not executed".
+    /// @param token The terminal token whose tree contains the leaf.
+    /// @param index The index of the leaf in the inbox tree.
+    /// @return hash The committed leaf hash (or `bytes32(0)` if unexecuted).
+    function executedLeafHashOf(address token, uint256 index) external view returns (bytes32 hash);
+
     /// @notice The inbox merkle tree root for a given token.
     /// @param token The local terminal token.
     /// @return The inbox tree root.

package/src/interfaces/IJBSuckerRegistry.sol

@@ -54,6 +54,14 @@ interface IJBSuckerRegistry {
     /// @return The projects contract.
     function PROJECTS() external view returns (IJBProjects);
 
+    /// @notice All suckers for a project, INCLUDING deprecated entries that are no longer listed in `suckersOf`.
+    /// @dev Used by consumers that need to detect "has any sucker ever peered to chain X?" — e.g. to prevent
+    /// premature burn of bridgeable credit by `JBReferralSplitHook.burnUnbridgeableCreditFor`. Returns every key
+    /// from `_suckersOf[projectId]` regardless of active/deprecated state.
+    /// @param projectId The ID of the project.
+    /// @return The addresses of every sucker ever registered for `projectId`.
+    function allSuckersOf(uint256 projectId) external view returns (address[] memory);
+
     /// @notice Returns true if the specified sucker belongs to the specified project and was deployed through this
     /// registry.
     /// @param projectId The ID of the project to check for.

package/src/structs/JBConversionRate.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Immutable conversion rate for one received root batch, keyed by nonce.
+/// @dev Each batch stores its total leaf and local amounts. Individual claims compute their scaled amount as
+/// `claimLeafAmount * localTotal / leafTotal` — no mutable state changes.
+/// @custom:member leafTotal Total leaf-denomination (source chain) amount for this batch.
+/// @custom:member localTotal Total local-denomination (after swap) amount for this batch.
+struct JBConversionRate {
+    uint256 leafTotal;
+    uint256 localTotal;
+}

package/src/structs/JBPendingSwap.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Bridge tokens from a failed inbound swap, stored for later retry via `retrySwap`.
+/// @custom:member bridgeToken The bridge token received from CCIP.
+/// @custom:member bridgeAmount Amount of bridge tokens to swap.
+/// @custom:member leafTotal Original leaf-denomination total (for conversion rate).
+struct JBPendingSwap {
+    address bridgeToken;
+    uint256 bridgeAmount;
+    uint256 leafTotal;
+}