@bananapus/suckers-v6 0.0.58 → 0.0.60

package/package.json

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

package/src/JBCCIPSucker.sol

@@ -38,7 +38,11 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
     //*********************************************************************//
 
     error JBCCIPSucker_InvalidRouter(address router);
+    error JBCCIPSucker_PositiveRootWithoutDelivery(uint256 rootAmount);
+    error JBCCIPSucker_UnderDeliveredAmount(uint256 delivered, uint256 rootAmount);
+    error JBCCIPSucker_UnexpectedDeliveredTokens(uint256 count);
     error JBCCIPSucker_UnknownMessageType(uint8 messageType);
+    error JBCCIPSucker_WrongDeliveredToken(address delivered, address expected);
 
     //*********************************************************************//
     // ------------------------------ events ----------------------------- //
@@ -175,6 +179,42 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
             // Decode the root message from the payload.
             JBMessageRoot memory root = abi.decode(payload, (JBMessageRoot));
 
+            // Cross-check the delivered tokens against the advertised root before recording anything.
+            //
+            // The send-side guarantees at most one entry in `destTokenAmounts`: length 0 for zero-value batches,
+            // length 1 for value-bearing batches. A compromised peer (or a malformed CCIP delivery) that violates
+            // these invariants would otherwise let `fromRemote` record a root advertising more value than was
+            // bridged, letting later claims mint project tokens against unrelated balance until the inbox runs dry.
+            // `JBSwapCCIPSucker.ccipReceive` already enforces equivalent reverts for the swap variant; mirror
+            // them here so both variants share a single defensive baseline.
+            uint256 deliveryCount = any2EvmMessage.destTokenAmounts.length;
+            if (deliveryCount > 1) {
+                revert JBCCIPSucker_UnexpectedDeliveredTokens(deliveryCount);
+            }
+            if (deliveryCount == 0) {
+                if (root.amount > 0) revert JBCCIPSucker_PositiveRootWithoutDelivery(root.amount);
+            } else {
+                Client.EVMTokenAmount calldata delivered = any2EvmMessage.destTokenAmounts[0];
+
+                // For NATIVE_TOKEN bridges the delivered ERC-20 is the wrapped native token (CCIP cannot transport
+                // raw native), so the token-identity check happens inside `unwrapReceivedTokens` against the
+                // router-reported wrapped native address. For everything else, the delivered token must equal the
+                // local mapped token the root advertises.
+                if (root.token != bytes32(uint256(uint160(JBConstants.NATIVE_TOKEN)))) {
+                    address expectedToken = _toAddress(root.token);
+                    if (delivered.token != expectedToken) {
+                        revert JBCCIPSucker_WrongDeliveredToken({delivered: delivered.token, expected: expectedToken});
+                    }
+                }
+
+                // The bridged amount must back at least the value the root advertises. A short delivery against a
+                // positive root is the structural twin of "no delivery + positive root" — both leave the inbox
+                // recording more claimable value than it actually holds.
+                if (delivered.amount < root.amount) {
+                    revert JBCCIPSucker_UnderDeliveredAmount({delivered: delivered.amount, rootAmount: root.amount});
+                }
+            }
+
             // Only unwrap wrapped native token when the root targets native token (not when claiming it as ERC-20).
             if (root.token == bytes32(uint256(uint160(JBConstants.NATIVE_TOKEN)))) {
                 JBCCIPLib.unwrapReceivedTokens({

package/src/JBSucker.sol

@@ -90,6 +90,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     error JBSucker_UnexpectedMsgValue(uint256 value);
     error JBSucker_ZeroBeneficiary(bytes32 beneficiary);
     error JBSucker_ZeroERC20Token(uint256 projectId);
+    error JBSucker_ZeroProjectTokenCount();
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -140,6 +141,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.
@@ -544,6 +554,14 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         external
         override
     {
+        // Reject zero-token prepares. A zero-token prepare burns nothing and reclaims nothing, but it still inserts a
+        // leaf into the outbox tree and lets `toRemote` ship a zero-value bridge message — a permissionless way to
+        // inflate the per-token populated-nonce list on swap-CCIP suckers, taxing every legitimate claim with extra
+        // lookup work and eventually exceeding the block gas limit.
+        if (projectTokenCount == 0) {
+            revert JBSucker_ZeroProjectTokenCount();
+        }
+
         // Make sure the beneficiary is not the zero address, as this would revert when minting on the remote chain.
         if (beneficiary == bytes32(0)) {
             revert JBSucker_ZeroBeneficiary({beneficiary: beneficiary});
@@ -925,36 +943,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 +1333,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 +1355,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 +1369,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 +1456,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.
@@ -394,7 +376,15 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
             // either a batch range (batchEnd > 0) or a conversion rate / pending swap recorded.
             // Record the batch range so _findNonceForLeafIndex can resolve leaf ownership
             // independently of nonce ordering. Each nonce is self-describing: [start, end).
-            if (batchEnd > 0) {
+            //
+            // Only record metadata for batches that carry value (`leafTotal > 0`). The base-sucker
+            // `prepare` revert on zero `projectTokenCount` blocks the legitimate spam entry point,
+            // but a compromised peer or a `projectTokenCount = 1`-style bypass could still ship a
+            // zero-leaf root over the bridge. Skipping the metadata write here ensures such roots
+            // cannot inflate `_populatedNonceByIndex` and tax future `_findNonceForLeafIndex`
+            // walks. Roots with `leafTotal == 0` carry no claimable leaves, so there is nothing
+            // for `_findNonceForLeafIndex` to resolve against them.
+            if (batchEnd > 0 && leafTotal > 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.
@@ -421,7 +411,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 +425,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 +495,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 +506,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 +562,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/libraries/JBSwapPoolLib.sol

@@ -619,7 +619,14 @@ library JBSwapPoolLib {
         });
     }
 
-    /// @notice Get a V4 quote with dynamic slippage. Hooked pools must serve TWAP; hookless pools use spot fallback.
+    /// @notice Get a V4 quote with dynamic slippage. Hooked pools must serve TWAP for BOTH the price tick and the
+    /// liquidity input into sigmoid slippage; hookless pools fall back to spot for both.
+    /// @dev Matches the buyback hook's TWAP pattern (`JBSwapLib.getQuoteFromOracle`): for hooked routes we derive
+    /// `harmonicMeanLiquidity` from the oracle's `secondsPerLiquidityCumulativeX128s`, not from
+    /// `PoolManager.getLiquidity` (which returns current spot and is JIT-LP-manipulable across a single block).
+    /// Sigmoid slippage tolerance is driven by `amountIn / liquidity`; feeding spot liquidity into a TWAP-derived
+    /// tick lets an LP shrink the denominator in the same block as a CCIP delivery, ballooning the tolerance to
+    /// `MAX_SLIPPAGE` (88%) for a one-shot per-batch immutable conversion rate that all claimers then inherit.
     /// @param config The swap configuration (pool manager, wrapped native token addresses).
     /// @param key The V4 pool key to quote against.
     /// @param normalizedTokenIn The normalized input token address.
@@ -644,37 +651,54 @@ library JBSwapPoolLib {
         PoolId id = key.toId();
 
         {
-            // If the pool has a hook, require a TWAP from the geomean oracle.
+            // If the pool has a hook, require a TWAP from the geomean oracle for both price AND liquidity.
             if (address(key.hooks) != address(0)) {
                 // Build the observation window: [_V4_TWAP_WINDOW seconds ago, now].
                 uint32[] memory secondsAgos = new uint32[](2);
                 secondsAgos[0] = _V4_TWAP_WINDOW;
                 secondsAgos[1] = 0;
 
-                // Read the TWAP from the hook's geomean oracle. The seconds-per-liquidity array is not used for
-                // price checks.
-                (int56[] memory tickCumulatives,) =
+                // Read both the TWAP tick and the seconds-per-liquidity series so liquidity is also time-averaged.
+                (int56[] memory tickCumulatives, uint160[] memory secondsPerLiquidityCumulativeX128s) =
                     IGeomeanOracle(address(key.hooks)).observe({key: key, secondsAgos: secondsAgos});
-                if (tickCumulatives.length < 2) {
+                if (tickCumulatives.length < 2 || secondsPerLiquidityCumulativeX128s.length < 2) {
                     revert JBSwapPoolLib_InsufficientTwapHistory({
                         pool: address(key.hooks), availableWindow: tickCumulatives.length, requiredWindow: 2
                     });
                 }
 
-                // Compute the arithmetic mean tick from the cumulative tick difference.
-                // The geomean oracle returns the same int24 tick domain used by Uniswap pools.
+                // Compute the arithmetic mean tick from the cumulative tick difference, rounding negative values
+                // toward negative infinity to match Uniswap's oracle pattern and the buyback hook.
+                int56 tickCumulativesDelta = tickCumulatives[1] - tickCumulatives[0];
                 // forge-lint: disable-next-line(unsafe-typecast)
-                tick = int24((tickCumulatives[1] - tickCumulatives[0]) / int56(int32(_V4_TWAP_WINDOW)));
+                tick = int24(tickCumulativesDelta / int56(int32(_V4_TWAP_WINDOW)));
+                // forge-lint: disable-next-line(unsafe-typecast)
+                if (tickCumulativesDelta < 0 && tickCumulativesDelta % int56(int32(_V4_TWAP_WINDOW)) != 0) {
+                    tick--;
+                }
+
+                // Derive harmonic-mean liquidity from the seconds-per-liquidity delta. This is the same shape the
+                // buyback hook uses (`JBSwapLib.getQuoteFromOracle`) and resists JIT-LP liquidity removal in the
+                // delivery block — the manipulation has to persist across the full TWAP window to move the average.
+                uint160 secondsPerLiquidityDelta =
+                    secondsPerLiquidityCumulativeX128s[1] - secondsPerLiquidityCumulativeX128s[0];
+
+                if (secondsPerLiquidityDelta > 0) {
+                    // Safe: `(uint256(_V4_TWAP_WINDOW) << 128) / secondsPerLiquidityDelta` fits in uint128 because
+                    // _V4_TWAP_WINDOW is at most a uint32 (~4.3B) and the divisor is > 0 in this branch.
+                    // forge-lint: disable-next-line(unsafe-typecast)
+                    liquidity = uint128((uint256(_V4_TWAP_WINDOW) << 128) / uint256(secondsPerLiquidityDelta));
+                }
+                // If `secondsPerLiquidityDelta == 0`, liquidity stays 0 and the no-liquidity revert below fires —
+                // refuse to quote a hooked route whose averaged liquidity is degenerate.
             } else {
                 // Hookless V4 spot pools are only selected when no TWAP-capable route exists.
                 (, tick,,) = config.poolManager.getSlot0(id);
+                liquidity = config.poolManager.getLiquidity(id);
             }
-
-            // Query the pool's current in-range liquidity.
-            liquidity = config.poolManager.getLiquidity(id);
         }
 
-        // Revert if the pool has no in-range liquidity.
+        // Revert if the pool has no usable in-range liquidity (spot for hookless, TWAP-derived for hooked).
         if (liquidity == 0) revert JBSwapPoolLib_NoLiquidity({pool: address(0), poolId: id});
 
         // V4 uses address(0) for native ETH — compute quoting addresses inline to save stack slots.
@@ -864,8 +888,8 @@ library JBSwapPoolLib {
         return _observationIsOldEnough({observationTimestamp: observationTimestamp, window: _DEFAULT_TWAP_WINDOW});
     }
 
-    /// @notice Check whether a V4 hooked pool can return cumulative ticks for the required TWAP window.
-    /// @dev Hookless pools return false. Reverting hooks and hooks that return fewer than two cumulative tick values
+    /// @notice Check whether a V4 hooked pool can return TWAP price and liquidity for the required window.
+    /// @dev Hookless pools return false. Reverting hooks and hooks that return incomplete or degenerate oracle data
     /// are treated as unusable for TWAP routing.
     /// @param key The V4 pool key whose hook should be probed.
     /// @return True if the hook can serve both the historical and current cumulative tick observations.
@@ -876,12 +900,12 @@ library JBSwapPoolLib {
         secondsAgos[0] = _V4_TWAP_WINDOW;
         secondsAgos[1] = 0;
 
-        // Pool discovery intentionally probes candidate hooks in a bounded pool list. The seconds-per-liquidity array
-        // is not needed for the history check.
+        // Pool discovery intentionally probes candidate hooks in a bounded pool list.
         try IGeomeanOracle(address(key.hooks)).observe({key: key, secondsAgos: secondsAgos}) returns (
-            int56[] memory tickCumulatives, uint160[] memory
+            int56[] memory tickCumulatives, uint160[] memory secondsPerLiquidityCumulativeX128s
         ) {
-            return tickCumulatives.length >= 2;
+            if (tickCumulatives.length < 2 || secondsPerLiquidityCumulativeX128s.length < 2) return false;
+            return secondsPerLiquidityCumulativeX128s[1] > secondsPerLiquidityCumulativeX128s[0];
         } catch {
             return false;
         }

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;
+}