@zoralabs/coins 2.3.1 → 2.4.1

package/src/interfaces/IZoraLimitOrderBookCoinsInterface.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: ZORA-DELAYED-OSL-v1
+// This software is licensed under the Zora Delayed Open Source License.
+// Under this license, you may use, copy, modify, and distribute this software for
+// non-commercial purposes only. Commercial use and competitive products are prohibited
+// until the "Open Date" (3 years from first public distribution or earlier at Zora's discretion),
+// at which point this software automatically becomes available under the MIT License.
+// Full license terms available at: https://docs.zora.co/coins/license
+pragma solidity ^0.8.23;
+
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+
+interface IZoraLimitOrderBookCoinsInterface {
+    /// @notice Fills limit orders within a tick window.
+    /// @param key Pool key whose orders should be processed.
+    /// @param isCurrency0 Whether currency0 orders are targeted; otherwise currency1.
+    /// @param startTick Inclusive starting tick. Use `-type(int24).max` for the default lower bound.
+    /// @param endTick Inclusive ending tick. Use `type(int24).max` for the default upper bound.
+    /// @param maxFillCount Maximum orders to fill in this pass.
+    /// @param fillReferral Address to receive accrued LP fees; use address(0) to give fees to maker.
+    function fill(PoolKey calldata key, bool isCurrency0, int24 startTick, int24 endTick, uint256 maxFillCount, address fillReferral) external;
+}

package/src/interfaces/IZoraV4CoinHook.sol

@@ -44,6 +44,9 @@ interface IZoraV4CoinHook is IUpgradeableV4Hook {
     /// @notice Upgrade gate cannot be the zero address.
     error UpgradeGateCannotBeZeroAddress();
 
+    /// @notice Trusted message sender lookup cannot be the zero address.
+    error TrustedMsgSenderLookupCannotBeZeroAddress();
+
     /// @notice Thrown when a pool is not initialized for the hook.
     /// @param key The pool key struct to identify the pool.
     error NoCoinForHook(PoolKey key);
@@ -54,6 +57,12 @@ interface IZoraV4CoinHook is IUpgradeableV4Hook {
     /// @notice Thrown when a non-coin is used to access the functionality of a coin.
     error OnlyCoin(address caller, address expectedCoin);
 
+    /// @notice Thrown when the Zora limit order book is the zero address.
+    error ZoraLimitOrderBookCannotBeZeroAddress();
+
+    /// @notice Thrown when the Zora hook registry is the zero address.
+    error ZoraHookRegistryCannotBeZeroAddress();
+
     /// @notice The pool coin struct. Lists all the contract-created positions for the coin.
     struct PoolCoin {
         /// @notice The address of the coin.

package/src/libs/CoinConstants.sol

@@ -8,6 +8,12 @@
 pragma solidity ^0.8.23;
 
 library CoinConstants {
+    /// @dev Slot for transiently storing the tick before a swap.
+    bytes32 internal constant _BEFORE_SWAP_TICK_SLOT = keccak256("ZoraV4CoinHook.beforeSwap.tick");
+
+    /// @dev Constant used to indicate the max fill count for limit orders
+    uint256 internal constant SENTINEL_DEFAULT_LIMIT_ORDER_FILL_COUNT = 0;
+
     /// @dev Constant used to increase precision during calculations
     uint256 internal constant WAD = 1e18;
 

package/src/libs/CoinDopplerMultiCurve.sol

@@ -105,7 +105,7 @@ library CoinDopplerMultiCurve {
         bool isCoinToken0,
         PoolConfiguration memory poolConfiguration,
         uint256 totalSupply
-    ) internal pure returns (LpPosition[] memory positions) {
+    ) external pure returns (LpPosition[] memory positions) {
         positions = new LpPosition[](poolConfiguration.numPositions);
 
         uint256 discoverySupply;

package/src/libs/CoinRewardsV4.sol

@@ -27,7 +27,6 @@ import {IHasRewardsRecipients} from "../interfaces/IHasRewardsRecipients.sol";
 import {ICoin} from "../interfaces/ICoin.sol";
 import {IZoraV4CoinHook} from "../interfaces/IZoraV4CoinHook.sol";
 import {IHasSwapPath} from "../interfaces/ICoin.sol";
-import {V4Liquidity} from "./V4Liquidity.sol";
 import {UniV4SwapToCurrency} from "./UniV4SwapToCurrency.sol";
 import {ICreatorCoinHook} from "../interfaces/ICreatorCoinHook.sol";
 import {IHasCoinType} from "../interfaces/ICoin.sol";

package/src/libs/HooksDeployment.sol

@@ -14,6 +14,7 @@ import {HookMiner} from "@uniswap/v4-periphery/src/utils/HookMiner.sol";
 import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
 import {Create2} from "@openzeppelin/contracts/utils/Create2.sol";
 import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
+import {ITrustedMsgSenderProviderLookup} from "../interfaces/ITrustedMsgSenderProviderLookup.sol";
 
 Vm constant vm = Vm(address(bytes20(uint160(uint256(keccak256("hevm cheat code"))))));
 
@@ -62,7 +63,7 @@ library HooksDeployment {
     bytes32 constant VALID_CREATOR_COIN_SALT = 0x00000000000000000000000000000000000000000000000000000000000031af;
 
     function mineForSalt(address deployer, bytes memory hookCreationCode) internal view returns (address hookAddress, bytes32 salt) {
-        uint160 flags = uint160(Hooks.AFTER_SWAP_FLAG | Hooks.AFTER_INITIALIZE_FLAG) ^ (0x4444 << 144);
+        uint160 flags = uint160(Hooks.BEFORE_SWAP_FLAG | Hooks.AFTER_SWAP_FLAG | Hooks.AFTER_INITIALIZE_FLAG) ^ (0x4444 << 144);
         return HookMinerWithCreationCodeArgs.find(deployer, flags, hookCreationCode);
     }
 
@@ -86,10 +87,12 @@ library HooksDeployment {
         address deployer,
         address poolManager,
         address coinVersionLookup,
-        address[] memory trustedMessageSenders,
-        address upgradeGate
+        ITrustedMsgSenderProviderLookup trustedMsgSenderLookup,
+        address upgradeGate,
+        address orderFiller,
+        address hookRegistry
     ) internal returns (address hookAddress, bytes32 salt) {
-        bytes memory hookCreationCode = makeHookCreationCode(poolManager, coinVersionLookup, trustedMessageSenders, upgradeGate);
+        bytes memory hookCreationCode = makeHookCreationCode(poolManager, coinVersionLookup, trustedMsgSenderLookup, upgradeGate, orderFiller, hookRegistry);
         (salt, ) = mineAndCacheSalt(deployer, hookCreationCode);
         hookAddress = HookMinerWithCreationCodeArgs.deterministicHookAddress(deployer, salt, hookCreationCode);
     }
@@ -131,19 +134,27 @@ library HooksDeployment {
     function hookConstructorArgs(
         address poolManager,
         address coinVersionLookup,
-        address[] memory trustedMessageSenders,
-        address upgradeGate
+        ITrustedMsgSenderProviderLookup trustedMsgSenderLookup,
+        address upgradeGate,
+        address orderFiller,
+        address hookRegistry
     ) internal pure returns (bytes memory) {
-        return abi.encode(poolManager, coinVersionLookup, trustedMessageSenders, upgradeGate);
+        return abi.encode(poolManager, coinVersionLookup, trustedMsgSenderLookup, upgradeGate, orderFiller, hookRegistry);
     }
 
     function makeHookCreationCode(
         address poolManager,
         address coinVersionLookup,
-        address[] memory trustedMessageSenders,
-        address upgradeGate
+        ITrustedMsgSenderProviderLookup trustedMsgSenderLookup,
+        address upgradeGate,
+        address orderFiller,
+        address hookRegistry
     ) internal pure returns (bytes memory) {
-        return abi.encodePacked(type(ZoraV4CoinHook).creationCode, hookConstructorArgs(poolManager, coinVersionLookup, trustedMessageSenders, upgradeGate));
+        return
+            abi.encodePacked(
+                type(ZoraV4CoinHook).creationCode,
+                hookConstructorArgs(poolManager, coinVersionLookup, trustedMsgSenderLookup, upgradeGate, orderFiller, hookRegistry)
+            );
     }
 
     /// @notice Deploys or returns existing ContentCoinHook using deterministic deployment.  Ensures that if a hooks is already
@@ -151,11 +162,13 @@ library HooksDeployment {
     function deployZoraV4CoinHook(
         address poolManager,
         address coinVersionLookup,
-        address[] memory trustedMessageSenders,
+        ITrustedMsgSenderProviderLookup trustedMsgSenderLookup,
         address upgradeGate,
+        address orderFiller,
+        address hookRegistry,
         bytes32 salt
     ) internal returns (IHooks hook) {
-        bytes memory creationCode = makeHookCreationCode(poolManager, coinVersionLookup, trustedMessageSenders, upgradeGate);
+        bytes memory creationCode = makeHookCreationCode(poolManager, coinVersionLookup, trustedMsgSenderLookup, upgradeGate, orderFiller, hookRegistry);
         return deployHookWithSalt(creationCode, salt);
     }
 

package/src/libs/UniV4SwapHelper.sol

@@ -22,6 +22,41 @@ import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
 import {PathKey} from "@uniswap/v4-periphery/src/libraries/PathKey.sol";
 
 library UniV4SwapHelper {
+    function buildExactInputMultiSwapCommand(
+        address currencyIn,
+        uint128 amountIn,
+        PoolKey[] memory keys,
+        uint128 minAmountOut,
+        bytes[] memory hopHookData
+    ) internal pure returns (bytes memory commands, bytes[] memory inputs) {
+        require(keys.length > 0 && hopHookData.length == keys.length, "invalid lengths");
+
+        PathKey[] memory path = new PathKey[](keys.length);
+
+        Currency currency = Currency.wrap(currencyIn);
+        Currency finalCurrencyOut;
+
+        for (uint256 i; i < keys.length; ++i) {
+            Currency out = currency == keys[i].currency0 ? keys[i].currency1 : keys[i].currency0;
+            path[i] = PathKey({intermediateCurrency: out, fee: keys[i].fee, tickSpacing: keys[i].tickSpacing, hooks: keys[i].hooks, hookData: hopHookData[i]});
+            currency = out;
+            finalCurrencyOut = out;
+        }
+
+        bytes memory actions = abi.encodePacked(uint8(Actions.SWAP_EXACT_IN), uint8(Actions.SETTLE), uint8(Actions.TAKE_ALL));
+        bytes[] memory params = new bytes[](3);
+        params[0] = abi.encode( // 1) SWAP_EXACT_IN({ currencyIn, path, amountIn, amountOutMinimum })
+                IV4Router.ExactInputParams({currencyIn: Currency.wrap(currencyIn), path: path, amountIn: amountIn, amountOutMinimum: minAmountOut})
+            );
+        params[1] = abi.encode(currencyIn, amountIn, true); // 2) SETTLE(tokenIn, amountIn, payerIsUser=true) — pulls from user via Permit2
+        params[2] = abi.encode(Currency.unwrap(finalCurrencyOut), minAmountOut); // 3) TAKE_ALL(finalCurrencyOut, minOut)
+
+        commands = abi.encodePacked(uint8(Commands.V4_SWAP));
+
+        inputs = new bytes[](1);
+        inputs[0] = abi.encode(actions, params);
+    }
+
     function buildExactInputSingleSwapCommand(
         address currencyIn,
         uint128 amountIn,

package/src/libs/V3ToV4SwapLib.sol

@@ -0,0 +1,261 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {Currency, CurrencyLibrary} from "@uniswap/v4-core/src/types/Currency.sol";
+import {IPoolManager, SwapParams} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {TickMath} from "@uniswap/v4-core/src/libraries/TickMath.sol";
+import {BalanceDelta, BalanceDeltaLibrary} from "@uniswap/v4-core/src/types/BalanceDelta.sol";
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {ISwapRouter} from "../interfaces/ISwapRouter.sol";
+import {Path} from "@zoralabs/shared-contracts/libs/UniswapV3/Path.sol";
+import {IAllowanceTransfer} from "permit2/src/interfaces/IAllowanceTransfer.sol";
+import {SafeCast160} from "permit2/src/libraries/SafeCast160.sol";
+
+/// @title V3ToV4SwapLib
+/// @notice Shared library for executing V3-to-V4 swap routing
+/// @dev Provides common functionality for:
+///      - V3 route validation and connection to V4 routes
+///      - Input currency validation and transfer (ETH vs ERC20)
+///      - V3 swap execution via ISwapRouter.exactInput()
+///      - V4 multi-hop swap execution
+///      - Delta settlement with poolManager
+///      - V3 route parsing utilities
+library V3ToV4SwapLib {
+    using SafeERC20 for IERC20;
+    using BalanceDeltaLibrary for BalanceDelta;
+    using CurrencyLibrary for Currency;
+    using Path for bytes;
+    using SafeCast160 for uint256;
+
+    // ============ ERRORS ============
+
+    error InsufficientInputCurrency(uint256 inputAmount, uint256 availableAmount);
+    error V3RouteCannotStartWithInputCurrency();
+    error V3RouteDoesNotConnectToV4RouteStart();
+
+    // ============ STRUCTS ============
+
+    /// @notice Parameters for V3 swap execution
+    struct V3SwapParams {
+        bytes v3Route; // V3 route path
+        address inputCurrency; // Input currency (address(0) for ETH)
+        uint256 inputAmount; // Amount of input currency
+        address recipient; // Recipient of swap output
+    }
+
+    /// @notice Parameters for V4 multi-hop swap execution
+    struct V4SwapParams {
+        PoolKey[] v4Route; // Array of pool keys to swap through
+        uint256 amountIn; // Starting amount
+        Currency startingCurrency; // Starting currency
+    }
+
+    /// @notice Result from V4 multi-hop swap
+    struct V4SwapResult {
+        uint128 outputAmount; // Final output amount
+        Currency outputCurrency; // Final output currency
+    }
+
+    // ============ VALIDATION ============
+
+    /// @notice Validates that V3 route output connects to V4 route start
+    /// @param v3Route The V3 route path (empty if no V3 swap)
+    /// @param inputCurrency The input currency for the swap
+    /// @param v4Route The V4 route (first pool must accept V3 output or input currency)
+    function validateRoutes(bytes memory v3Route, address inputCurrency, PoolKey[] memory v4Route) internal pure {
+        if (v4Route.length == 0) {
+            return; // No V4 route to validate
+        }
+
+        // Determine what currency should be the input to the V4 route
+        address v4InputCurrency;
+        if (v3Route.length == 0) {
+            // No V3 swap - input currency should directly match V4 route start
+            v4InputCurrency = inputCurrency;
+        } else {
+            // V3 swap exists - V3 output should match V4 route start
+            v4InputCurrency = getV3RouteOutputCurrency(v3Route);
+        }
+
+        PoolKey memory firstPool = v4Route[0];
+
+        require(
+            v4InputCurrency == Currency.unwrap(firstPool.currency0) || v4InputCurrency == Currency.unwrap(firstPool.currency1),
+            V3RouteDoesNotConnectToV4RouteStart()
+        );
+    }
+
+    /// @notice Validates and transfers input currency from sender to contract
+    /// @param inputCurrency The input currency address (address(0) for ETH)
+    /// @param inputAmount The amount to transfer
+    /// @param from The address to transfer from
+    /// @param msgValue The msg.value sent with the transaction
+    function validateAndTransferInputCurrency(address inputCurrency, uint256 inputAmount, address from, uint256 msgValue) internal {
+        if (inputCurrency == address(0)) {
+            // ETH payment
+            require(msgValue == inputAmount, InsufficientInputCurrency(inputAmount, msgValue));
+        } else {
+            // ERC20 payment
+            uint256 allowanceAmount = IERC20(inputCurrency).allowance(from, address(this));
+            require(allowanceAmount >= inputAmount, InsufficientInputCurrency(inputAmount, allowanceAmount));
+
+            uint256 balanceAmount = IERC20(inputCurrency).balanceOf(from);
+            require(balanceAmount >= inputAmount, InsufficientInputCurrency(inputAmount, balanceAmount));
+
+            IERC20(inputCurrency).safeTransferFrom(from, address(this), inputAmount);
+        }
+    }
+
+    /// @notice Validates and transfers input currency from sender using Permit2
+    /// @param permit2 The Permit2 contract
+    /// @param inputCurrency The input currency address (address(0) for ETH)
+    /// @param inputAmount The amount to transfer
+    /// @param from The address to transfer from
+    /// @param to The address to transfer to (recipient)
+    /// @param msgValue The msg.value sent with the transaction
+    function permit2TransferFrom(IAllowanceTransfer permit2, address inputCurrency, uint256 inputAmount, address from, address to, uint256 msgValue) internal {
+        if (inputCurrency == address(0)) {
+            // ETH payment - no Permit2 needed
+            require(msgValue == inputAmount, InsufficientInputCurrency(inputAmount, msgValue));
+        } else {
+            // ERC20 payment via Permit2
+            require(msgValue == 0, InsufficientInputCurrency(0, msgValue));
+            permit2.transferFrom(from, to, inputAmount.toUint160(), inputCurrency);
+        }
+    }
+
+    // ============ V3 SWAP LOGIC ============
+
+    /// @notice Executes a V3 swap if v3Route is provided, otherwise returns input
+    /// @param swapRouter The Uniswap V3 swap router
+    /// @param params The V3 swap parameters
+    /// @return amountCurrency The amount received from V3 swap (or input if no swap)
+    /// @return currencyReceived The currency received (output of V3 or input if no swap)
+    function executeV3Swap(ISwapRouter swapRouter, V3SwapParams memory params) internal returns (uint256 amountCurrency, address currencyReceived) {
+        if (params.v3Route.length == 0) {
+            // No V3 swap needed - return input directly
+            return (params.inputAmount, params.inputCurrency);
+        }
+
+        // Handle ERC20 input - approve swapRouter to spend tokens
+        if (params.inputCurrency != address(0)) {
+            IERC20(params.inputCurrency).safeIncreaseAllowance(address(swapRouter), params.inputAmount);
+        }
+
+        // Build swap router call for exactInput
+        ISwapRouter.ExactInputParams memory swapParams = ISwapRouter.ExactInputParams({
+            path: params.v3Route,
+            recipient: params.recipient,
+            amountIn: params.inputAmount,
+            amountOutMinimum: 0 // Slippage protection should be handled at higher level
+        });
+
+        // Conditional value passing - ETH if inputCurrency is address(0), otherwise 0
+        uint256 value = params.inputCurrency == address(0) ? params.inputAmount : 0;
+        amountCurrency = swapRouter.exactInput{value: value}(swapParams);
+        currencyReceived = getV3RouteOutputCurrency(params.v3Route);
+    }
+
+    // ============ V4 SWAP LOGIC ============
+
+    /// @notice Executes a multi-hop V4 swap through multiple pools
+    /// @param poolManager The Uniswap V4 pool manager
+    /// @param params The V4 swap parameters
+    /// @return result The swap result containing output amount and currency
+    function executeV4MultiHopSwap(IPoolManager poolManager, V4SwapParams memory params) internal returns (V4SwapResult memory result) {
+        Currency currentCurrency = params.startingCurrency;
+        uint128 currentAmount = uint128(params.amountIn);
+
+        // Execute swaps through the route
+        for (uint256 i = 0; i < params.v4Route.length; i++) {
+            PoolKey memory poolKey = params.v4Route[i];
+
+            // Determine swap direction based on current currency
+            bool zeroForOne = currentCurrency == poolKey.currency0;
+
+            BalanceDelta delta = poolManager.swap(
+                poolKey,
+                SwapParams(zeroForOne, -(int128(currentAmount)), zeroForOne ? TickMath.MIN_SQRT_PRICE + 1 : TickMath.MAX_SQRT_PRICE - 1),
+                ""
+            );
+
+            // Extract output amount from delta
+            uint128 outputAmount = zeroForOne ? uint128(delta.amount1()) : uint128(delta.amount0());
+
+            // Update for next iteration
+            currentAmount = outputAmount;
+            currentCurrency = zeroForOne ? poolKey.currency1 : poolKey.currency0;
+        }
+
+        result.outputAmount = currentAmount;
+        result.outputCurrency = currentCurrency;
+    }
+
+    // ============ DELTA SETTLEMENT ============
+
+    /// @notice Settles currency deltas with the pool manager
+    /// @param poolManager The Uniswap V4 pool manager
+    /// @param inputCurrency The input currency to settle
+    /// @param outputCurrency The output currency to take
+    /// @param to The recipient of the output currency
+    /// @param inputAmount The amount of input currency to settle
+    /// @param outputAmount The amount of output currency to take
+    function settleDeltas(
+        IPoolManager poolManager,
+        Currency inputCurrency,
+        Currency outputCurrency,
+        address to,
+        uint256 inputAmount,
+        uint128 outputAmount
+    ) internal {
+        // Pay the input amount
+        if (inputCurrency.isAddressZero()) {
+            // For ETH, settle with msg.value
+            poolManager.settle{value: inputAmount}();
+        } else {
+            // For ERC20, sync and transfer
+            poolManager.sync(inputCurrency);
+            inputCurrency.transfer(address(poolManager), inputAmount);
+            poolManager.settle();
+        }
+
+        // Transfer the output amount to the recipient
+        poolManager.take(outputCurrency, to, outputAmount);
+    }
+
+    // ============ UTILITIES ============
+
+    /// @notice Gets the output currency from a V3 route path
+    /// @param path The V3 route path
+    /// @return tokenOut The output token address
+    function getV3RouteOutputCurrency(bytes memory path) internal pure returns (address tokenOut) {
+        if (path.length == 0) {
+            return address(0);
+        }
+
+        // Traverse to the end of the path to find the final token
+        bytes memory currentPath = path;
+
+        // Keep skipping tokens until we reach the final pool
+        while (currentPath.hasMultiplePools()) {
+            currentPath = currentPath.skipToken();
+        }
+
+        // The final segment contains the last pool, decode to get the output token
+        (, tokenOut, ) = currentPath.decodeFirstPool();
+    }
+
+    /// @notice Gets the input currency from a V3 route path
+    /// @param path The V3 route path
+    /// @return tokenIn The input token address
+    function getV3RouteInputCurrency(bytes memory path) internal pure returns (address tokenIn) {
+        if (path.length == 0) {
+            return address(0);
+        }
+
+        // Use Path library to get the input token (first token in the path)
+        (tokenIn, , ) = path.decodeFirstPool();
+    }
+}

package/src/libs/V4Liquidity.sol

@@ -269,13 +269,14 @@ library V4Liquidity {
                 salt: 0
             });
 
-            (BalanceDelta liquidityDelta, BalanceDelta feesAccrued) = poolManager.modifyLiquidity(poolKey, params, "");
+            // callerDelta already includes fees, feesAccrued is informational only
+            (BalanceDelta callerDelta, ) = poolManager.modifyLiquidity(poolKey, params, "");
 
             burnedPositions[i] = BurnedPosition({
                 tickLower: positions[i].tickLower,
                 tickUpper: positions[i].tickUpper,
-                amount0Received: uint128(liquidityDelta.amount0() + feesAccrued.amount0()),
-                amount1Received: uint128(liquidityDelta.amount1() + feesAccrued.amount1())
+                amount0Received: uint128(callerDelta.amount0()),
+                amount1Received: uint128(callerDelta.amount1())
             });
         }
     }
@@ -315,20 +316,63 @@ library V4Liquidity {
         feeGrowthInside1DeltaX128 = feeGrowthInside1X128 - feeGrowthInside1LastX128;
     }
 
+    /// @notice Mints liquidity positions into the pool
+    /// @dev Uses a defensive balance check to prevent ERC20InsufficientBalance errors during migration.
+    /// When burning positions from an old hook, the amounts received may not exactly match what's needed
+    /// to mint the same liquidity in the new hook due to:
+    ///   1. Rounding in getLiquidityForAmounts() when converting between liquidity and token amounts
+    ///   2. Price movements between burn and mint operations
+    ///   3. Any accumulated dust from previous operations
+    /// By capping each position's liquidity at what's actually mintable with remaining balances,
+    /// we ensure the migration never reverts due to insufficient tokens.
     function mintPositions(IPoolManager poolManager, PoolKey memory poolKey, LpPosition[] memory positions) internal returns (int128 amount0, int128 amount1) {
-        ModifyLiquidityParams memory params;
         uint256 numPositions = positions.length;
 
+        // Track remaining token balances throughout minting.
+        // These balances decrease as each position consumes tokens.
+        uint256 balance0 = poolKey.currency0.balanceOf(address(this));
+        uint256 balance1 = poolKey.currency1.balanceOf(address(this));
+
+        // Cache sqrt price once for all liquidity calculations
+        (uint160 sqrtPriceX96, , , ) = StateLibrary.getSlot0(poolManager, poolKey.toId());
+
         for (uint256 i; i < numPositions; i++) {
-            params = ModifyLiquidityParams({
+            if (positions[i].liquidity == 0) {
+                continue;
+            }
+
+            // Calculate the maximum liquidity we can mint given our remaining token balances.
+            // This is the key defensive check: even if the requested liquidity would require
+            // more tokens than we have (due to rounding), we cap it at what's actually possible.
+            uint128 maxLiquidity = LiquidityAmounts.getLiquidityForAmounts(
+                sqrtPriceX96,
+                TickMath.getSqrtPriceAtTick(positions[i].tickLower),
+                TickMath.getSqrtPriceAtTick(positions[i].tickUpper),
+                balance0,
+                balance1
+            );
+
+            // Use the lesser of requested liquidity and what we can actually afford
+            uint128 liquidityToMint = positions[i].liquidity < maxLiquidity ? positions[i].liquidity : maxLiquidity;
+
+            if (liquidityToMint == 0) {
+                continue;
+            }
+
+            ModifyLiquidityParams memory params = ModifyLiquidityParams({
                 tickLower: positions[i].tickLower,
                 tickUpper: positions[i].tickUpper,
-                liquidityDelta: SafeCast.toInt256(positions[i].liquidity),
+                liquidityDelta: SafeCast.toInt256(liquidityToMint),
                 salt: 0
             });
 
             (BalanceDelta delta, ) = poolManager.modifyLiquidity(poolKey, params, "");
 
+            // Update remaining balances for next iteration.
+            // delta.amount0/1 are negative when minting (tokens flow out), so adding them decreases our balance.
+            balance0 = uint256(int256(balance0) + int256(delta.amount0()));
+            balance1 = uint256(int256(balance1) + int256(delta.amount1()));
+
             amount0 += delta.amount0();
             amount1 += delta.amount1();
         }

package/src/utils/TrustedMsgSenderProviderLookup.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: ZORA-DELAYED-OSL-v1
+// This software is licensed under the Zora Delayed Open Source License.
+// Under this license, you may use, copy, modify, and distribute this software for
+// non-commercial purposes only. Commercial use and competitive products are prohibited
+// until the "Open Date" (3 years from first public distribution or earlier at Zora's discretion),
+// at which point this software automatically becomes available under the MIT License.
+// Full license terms available at: https://docs.zora.co/coins/license
+pragma solidity ^0.8.23;
+
+import {Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {ContractVersionBase} from "../version/ContractVersionBase.sol";
+import {ITrustedMsgSenderProviderLookup} from "../interfaces/ITrustedMsgSenderProviderLookup.sol";
+
+/// @title TrustedMsgSenderProviderLookup
+/// @notice Contract for ITrustedMsgSenderProviderLookup that manages trusted message senders
+/// @dev This contract allows the owner to add/remove trusted senders and provides lookup functionality
+contract TrustedMsgSenderProviderLookup is ITrustedMsgSenderProviderLookup, ContractVersionBase, Ownable2Step {
+    /// @notice Emitted when a trusted sender is added
+    /// @param sender The address that was added as trusted
+    event TrustedSenderAdded(address indexed sender);
+
+    /// @notice Emitted when a trusted sender is removed
+    /// @param sender The address that was removed from trusted
+    event TrustedSenderRemoved(address indexed sender);
+
+    /// @notice Mapping of addresses to their trusted sender status
+    mapping(address => bool) private trustedSenders;
+
+    /// @notice Constructor that initializes the contract with trusted senders and sets the owner
+    /// @param trustedMessageSenders Array of addresses to mark as trusted senders initially
+    /// @param initialOwner The address that will own this contract
+    constructor(address[] memory trustedMessageSenders, address initialOwner) Ownable(initialOwner) {
+        for (uint256 i = 0; i < trustedMessageSenders.length; i++) {
+            trustedSenders[trustedMessageSenders[i]] = true;
+            emit TrustedSenderAdded(trustedMessageSenders[i]);
+        }
+    }
+
+    /// @notice Checks if an address is a trusted message sender provider
+    /// @param sender The address to check
+    /// @return true if the sender is trusted, false otherwise
+    function isTrustedMsgSenderProvider(address sender) external view override returns (bool) {
+        return trustedSenders[sender];
+    }
+
+    /// @notice Adds multiple trusted senders in a single transaction (only callable by owner)
+    /// @param senders Array of addresses to add as trusted
+    function addTrustedMsgSenderProviders(address[] calldata senders) external onlyOwner {
+        for (uint256 i = 0; i < senders.length; i++) {
+            address sender = senders[i];
+            require(sender != address(0), "Cannot add zero address as trusted sender");
+
+            if (!trustedSenders[sender]) {
+                trustedSenders[sender] = true;
+                emit TrustedSenderAdded(sender);
+            }
+        }
+    }
+
+    /// @notice Removes multiple trusted senders in a single transaction (only callable by owner)
+    /// @param senders Array of addresses to remove from trusted
+    function removeTrustedMsgSenderProviders(address[] calldata senders) external onlyOwner {
+        for (uint256 i = 0; i < senders.length; i++) {
+            address sender = senders[i];
+
+            if (trustedSenders[sender]) {
+                trustedSenders[sender] = false;
+                emit TrustedSenderRemoved(sender);
+            }
+        }
+    }
+}

package/src/version/ContractVersionBase.sol

@@ -9,6 +9,6 @@ import {IVersionedContract} from "@zoralabs/shared-contracts/interfaces/IVersion
 contract ContractVersionBase is IVersionedContract {
     /// @notice The version of the contract
     function contractVersion() external pure override returns (string memory) {
-        return "2.3.1";
+        return "2.4.1";
     }
 }