@bananapus/suckers-v6 0.0.58 → 0.0.59

package/package.json

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

package/src/JBSucker.sol

@@ -140,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.
@@ -925,36 +934,31 @@ 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: ""
-            });
         }
     }
 
@@ -1320,15 +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 and compare it to the current inbox root.
-        _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
         });
     }
 
@@ -1336,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
     )
@@ -1355,16 +1360,7 @@ 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});
 
         // Revert if the computed root does not match the expected inbox root.
         if (root != expectedRoot) {
@@ -1451,10 +1447,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // 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

@@ -109,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.

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.
 ///
@@ -136,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.
@@ -177,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.
@@ -421,7 +403,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
             // Store pendingSwapOf for failed swaps now that nonce is validated.
             if (swapFailed) {
                 pendingSwapOf[localToken][nonce] =
-                    PendingSwap({bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal});
+                    JBPendingSwap({bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal});
             }
 
             // Zero-output swap guard: When a swap succeeds but returns zero local tokens, the
@@ -435,11 +417,12 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
             // 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});
+                    pendingSwapOf[localToken][nonce] = JBPendingSwap({
+                        bridgeToken: deliveredToken, bridgeAmount: deliveredAmount, leafTotal: leafTotal
+                    });
                 } else {
                     _conversionRateOf[localToken][nonce] =
-                        ConversionRate({leafTotal: leafTotal, localTotal: localAmount});
+                        JBConversionRate({leafTotal: leafTotal, localTotal: localAmount});
                 }
             }
         } else {
@@ -504,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
@@ -515,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;
@@ -571,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;
+}