@zoralabs/coins 0.9.0 → 1.0.1

package/src/hooks/ZoraV4CoinHook.sol

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {BaseHook} from "@uniswap/v4-periphery/src/utils/BaseHook.sol";
+import {Hooks} from "@uniswap/v4-core/src/libraries/Hooks.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {BalanceDelta, BalanceDeltaLibrary} from "@uniswap/v4-core/src/types/BalanceDelta.sol";
+import {SwapParams} from "@uniswap/v4-core/src/types/PoolOperation.sol";
+import {IZoraV4CoinHook} from "../interfaces/IZoraV4CoinHook.sol";
+import {IMsgSender} from "../interfaces/IMsgSender.sol";
+import {IHasSwapPath} from "../interfaces/ICoinV4.sol";
+import {LpPosition} from "../types/LpPosition.sol";
+import {V4Liquidity} from "../libs/V4Liquidity.sol";
+import {CoinRewardsV4} from "../libs/CoinRewardsV4.sol";
+import {ICoinV4} from "../interfaces/ICoinV4.sol";
+import {IDeployedCoinVersionLookup} from "../interfaces/IDeployedCoinVersionLookup.sol";
+import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
+import {CoinCommon} from "../libs/CoinCommon.sol";
+import {PoolConfiguration} from "../types/PoolConfiguration.sol";
+import {CoinDopplerMultiCurve} from "../libs/CoinDopplerMultiCurve.sol";
+import {PoolStateReader} from "../libs/PoolStateReader.sol";
+import {IHasSwapPath} from "../interfaces/ICoinV4.sol";
+import {CoinConfigurationVersions} from "../libs/CoinConfigurationVersions.sol";
+
+/// @title ZoraV4CoinHook
+/// @notice Uniswap V4 hook that automatically handles fee collection and reward distributions on every swap,
+/// paying out all rewards in a backing currency.
+/// @dev This hook executes on afterSwap withdraw fees, swap for a backing currency, and distribute rewards.
+///      On pool initialization, it creates multiple liquidity positions based on the coin's pool configuration.
+///      On every swap, it automatically:
+///      1. Collects accrued LP fees from all positions
+///      2. Swaps collected fees to the backing currency through multi-hop paths
+///      3. Distributes converted fees as rewards
+/// @author oveddan
+contract ZoraV4CoinHook is BaseHook, IZoraV4CoinHook {
+    using BalanceDeltaLibrary for BalanceDelta;
+
+    /// @notice Mapping of trusted message senders - these are addresses that are trusted to provide a
+    /// an original msg.sender
+    mapping(address => bool) internal trustedMessageSender;
+
+    /// @notice Mapping of pool keys to coins.
+    mapping(bytes32 => IZoraV4CoinHook.PoolCoin) internal poolCoins;
+
+    /// @notice The coin version lookup contract - used to determine if an address is a coin and what version it is.
+    IDeployedCoinVersionLookup internal immutable coinVersionLookup;
+
+    /// @notice The constructor for the ZoraV4CoinHook.
+    /// @param poolManager_ The Uniswap V4 pool manager
+    /// @param coinVersionLookup_ The coin version lookup contract - used to determine if an address is a coin and what version it is.
+    /// @param trustedMessageSenders_ The addresses of the trusted message senders - these are addresses that are trusted to provide a
+    constructor(IPoolManager poolManager_, IDeployedCoinVersionLookup coinVersionLookup_, address[] memory trustedMessageSenders_) BaseHook(poolManager_) {
+        if (address(coinVersionLookup_) == address(0)) {
+            revert CoinVersionLookupCannotBeZeroAddress();
+        }
+
+        coinVersionLookup = coinVersionLookup_;
+
+        for (uint256 i = 0; i < trustedMessageSenders_.length; i++) {
+            trustedMessageSender[trustedMessageSenders_[i]] = true;
+        }
+    }
+
+    /// @notice Returns the uniswap v4 hook settings / permissions.
+    /// @dev The permissions currently requested are: afterInitialize and afterSwap.
+    function getHookPermissions() public pure override returns (Hooks.Permissions memory) {
+        return
+            Hooks.Permissions({
+                beforeInitialize: false,
+                afterInitialize: true,
+                beforeAddLiquidity: false,
+                afterAddLiquidity: false,
+                beforeRemoveLiquidity: false,
+                afterRemoveLiquidity: false,
+                beforeSwap: false,
+                afterSwap: true,
+                beforeDonate: false,
+                afterDonate: false,
+                beforeSwapReturnDelta: false,
+                afterSwapReturnDelta: false,
+                afterAddLiquidityReturnDelta: false,
+                afterRemoveLiquidityReturnDelta: false
+            });
+    }
+
+    /// @inheritdoc IZoraV4CoinHook
+    function isTrustedMessageSender(address sender) external view returns (bool) {
+        return trustedMessageSender[sender];
+    }
+
+    /// @inheritdoc IZoraV4CoinHook
+    function getPoolCoinByHash(bytes23 poolKeyHash) external view returns (IZoraV4CoinHook.PoolCoin memory) {
+        return poolCoins[poolKeyHash];
+    }
+
+    /// @inheritdoc IZoraV4CoinHook
+    function getPoolCoin(PoolKey memory key) external view returns (IZoraV4CoinHook.PoolCoin memory) {
+        return poolCoins[CoinCommon.hashPoolKey(key)];
+    }
+
+    /// @notice Internal fn generating the positions for a given pool key.
+    /// @param coin The coin address.
+    /// @param key The pool key for the coin.
+    /// @return positions The contract-created liquidity positions the positions for the coin's pool.
+    function _generatePositions(ICoinV4 coin, PoolKey memory key) internal view returns (LpPosition[] memory positions) {
+        bool isCoinToken0 = Currency.unwrap(key.currency0) == address(coin);
+
+        positions = CoinDopplerMultiCurve.calculatePositions(isCoinToken0, coin.getPoolConfiguration());
+    }
+
+    /// @notice Internal fn called when a pool is initialized.
+    /// @dev This hook is called from BaseHook library from uniswap v4.
+    /// @param sender The address of the sender.
+    /// @param key The pool key.
+    /// @return selector The selector of the afterInitialize hook to confirm the action.
+    function _afterInitialize(address sender, PoolKey calldata key, uint160, int24) internal override returns (bytes4) {
+        address coin = sender;
+        if (!CoinConfigurationVersions.isV4(coinVersionLookup.getVersionForDeployedCoin(coin))) {
+            revert NotACoin(coin);
+        }
+
+        LpPosition[] memory positions = _generatePositions(ICoinV4(coin), key);
+
+        poolCoins[CoinCommon.hashPoolKey(key)] = PoolCoin({coin: coin, positions: positions});
+
+        V4Liquidity.lockAndMint(poolManager, key, positions);
+
+        return BaseHook.afterInitialize.selector;
+    }
+
+    /// @notice Internal fn called when a swap is executed.
+    /// @dev This hook is called from BaseHook library from uniswap v4.
+    /// This hook:
+    /// 1. Collects accrued LP fees from all positions
+    /// 2. Swaps collected fees to the backing currency through multi-hop paths
+    /// 3. Distributes converted fees as rewards
+    /// @param sender The address of the sender.
+    /// @param key The pool key.
+    /// @param params The swap parameters.
+    /// @param delta The balance delta.
+    /// @param hookData The hook data.
+    /// @return selector The selector of the afterSwap hook to confirm the action.
+    function _afterSwap(
+        address sender,
+        PoolKey calldata key,
+        SwapParams calldata params,
+        BalanceDelta delta,
+        bytes calldata hookData
+    ) internal virtual override returns (bytes4, int128) {
+        bytes32 poolKeyHash = CoinCommon.hashPoolKey(key);
+
+        // get the coin address and positions for the pool key; they must have been set in the afterInitialize callback
+        address coin = poolCoins[poolKeyHash].coin;
+        require(coin != address(0), NoCoinForHook(key));
+
+        // get path for swapping the payout to a single currency
+        IHasSwapPath.PayoutSwapPath memory payoutSwapPath = IHasSwapPath(coin).getPayoutSwapPath(coinVersionLookup);
+
+        // Collect accrued LP fees from all positions, swap them to the target payout currency,
+        // and transfer the converted amount to this hook contract for distribution
+        (, , Currency receivedCurrency, uint128 receivedAmount) = CoinRewardsV4.collectFeesAndConvertToPayout(
+            poolManager,
+            key,
+            poolCoins[poolKeyHash].positions,
+            payoutSwapPath
+        );
+
+        // Distribute the collected and converted fees to all reward recipients (creator, referrers, protocol, etc.)
+        CoinRewardsV4.distributeMarketRewards(receivedCurrency, receivedAmount, ICoinV4(coin), CoinRewardsV4.getTradeReferral(hookData));
+
+        {
+            (address swapper, bool isTrustedSwapSenderAddress) = _getOriginalMsgSender(sender);
+            bool isCoinBuy = params.zeroForOne ? Currency.unwrap(key.currency1) == address(coin) : Currency.unwrap(key.currency0) == address(coin);
+            emit Swapped(
+                sender,
+                swapper,
+                isTrustedSwapSenderAddress,
+                key,
+                poolKeyHash,
+                params,
+                delta.amount0(),
+                delta.amount1(),
+                isCoinBuy,
+                hookData,
+                PoolStateReader.getSqrtPriceX96(key, poolManager)
+            );
+        }
+
+        return (BaseHook.afterSwap.selector, 0);
+    }
+
+    /// @notice Internal fn called when the PoolManager is unlocked.  Used to mint initial liquidity positions.
+    function unlockCallback(bytes calldata data) external onlyPoolManager returns (bytes memory) {
+        V4Liquidity.handleMintPositionsCallback(poolManager, data);
+    }
+
+    /// @notice Internal fn to get the original message sender.
+    /// @param sender The address of the sender.
+    /// @return swapper The original message sender.
+    /// @return senderIsTrusted Whether the sender is a trusted message sender.
+    function _getOriginalMsgSender(address sender) internal view returns (address swapper, bool senderIsTrusted) {
+        senderIsTrusted = trustedMessageSender[sender];
+
+        // If getter function reverts, we return a 0 address by default and continue execution.
+        try IMsgSender(sender).msgSender() returns (address _swapper) {
+            swapper = _swapper;
+        } catch {
+            swapper = address(0);
+        }
+    }
+}

package/src/hooks/{BaseCoinDeployHook.sol → deployment/BaseCoinDeployHook.sol}

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import {ICoin} from "../interfaces/ICoin.sol";
-import {IZoraFactory} from "../interfaces/IZoraFactory.sol";
-import {ICoinDeployHook} from "../interfaces/ICoinDeployHook.sol";
+import {ICoin} from "../../interfaces/ICoin.sol";
+import {IZoraFactory} from "../../interfaces/IZoraFactory.sol";
+import {ICoinDeployHook} from "../../interfaces/ICoinDeployHook.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 /// @title Immutable State

package/src/hooks/deployment/BuySupplyWithSwapRouterHook.sol

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {BaseCoinDeployHook} from "./BaseCoinDeployHook.sol";
+import {ICoin} from "../../interfaces/ICoin.sol";
+import {IZoraFactory} from "../../interfaces/IZoraFactory.sol";
+import {ISwapRouter} from "../../interfaces/ISwapRouter.sol";
+import {IWETH} from "../../interfaces/IWETH.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {Coin} from "../../Coin.sol";
+import {ICoinV3} from "../../interfaces/ICoinV3.sol";
+import {ICoinV4} from "../../interfaces/ICoinV4.sol";
+import {CoinConfigurationVersions} from "../../libs/CoinConfigurationVersions.sol";
+import {Currency} 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";
+
+/// @title BuySupplyWithSwapRouter
+/// @notice A hook that buys supply for a coin that is priced in an erc20 token a backing currency, using a Uniswap V3 SwapRouter.
+/// Supports both single-hop and multi-hop swaps using uniswap v3.  Supports buying the coin supply whether the coin is a v3 or v4 coin.
+/// @author @oveddan
+contract BuySupplyWithSwapRouterHook is BaseCoinDeployHook {
+    ISwapRouter immutable swapRouter;
+    IPoolManager immutable poolManager;
+    using BalanceDeltaLibrary for BalanceDelta;
+
+    error Erc20NotReceived();
+    error InvalidSwapRouterCall();
+    error SwapReverted(bytes error);
+    error CoinBalanceNot0(uint256 balance);
+    error CurrencyBalanceNot0(uint256 balance);
+
+    constructor(IZoraFactory _factory, address _swapRouter, address _poolManager) BaseCoinDeployHook(_factory) {
+        swapRouter = ISwapRouter(_swapRouter);
+        poolManager = IPoolManager(_poolManager);
+    }
+
+    /// @notice Hook that buys supply for a coin that is priced in an erc20 token with ETH, using a Uniswap SwapRouter.
+    /// Returns abi encoded (uint256 amountCurrency, uint256 coinsPurchased) - amountCurrency is the amount of currency received from the swap and sent to the coin for the purchase,
+    /// and coinsPurchased is the amount of coins purchased using the amountCurrency that was received from the swap
+    function _afterCoinDeploy(address, ICoin coin, bytes calldata hookData) internal override returns (bytes memory) {
+        address currency = coin.currency();
+
+        (address buyRecipient, bytes memory swapRouterCall) = abi.decode(hookData, (address, bytes));
+
+        uint256 amountCurrency = _handleSwap(currency, swapRouterCall);
+
+        uint256 coinsPurchased = _handleBuy(buyRecipient, coin, amountCurrency);
+
+        return abi.encode(amountCurrency, coinsPurchased);
+    }
+
+    function _handleSwap(address currency_, bytes memory swapRouterCall) internal returns (uint256 amountCurrency) {
+        // call the swap router, with the msg.value
+        _validateSwapRouterCall(swapRouterCall);
+
+        (bool success, bytes memory result) = address(swapRouter).call{value: msg.value}(swapRouterCall);
+
+        require(success, SwapReverted(result));
+
+        amountCurrency = abi.decode(result, (uint256));
+
+        // validate that this contract received the correct amount of currency
+        require(IERC20(currency_).balanceOf(address(this)) == amountCurrency, Erc20NotReceived());
+    }
+
+    function _validateSwapRouterCall(bytes memory swapRouterCall) internal pure {
+        // validate that the swap router call is valid - only exactInput and exactInputSingle are supported
+
+        bytes4 selector = _getSelectorFromCall(swapRouterCall);
+
+        require(selector == ISwapRouter.exactInput.selector || selector == ISwapRouter.exactInputSingle.selector, InvalidSwapRouterCall());
+    }
+
+    function _getSelectorFromCall(bytes memory _call) internal pure returns (bytes4 selector) {
+        assembly {
+            selector := mload(add(_call, 32))
+        }
+    }
+
+    function _handleBuy(address buyRecipient, ICoin coin, uint256 amountCurrency) internal returns (uint256 coinsPurchased) {
+        IERC20(coin.currency()).approve(address(coin), amountCurrency);
+
+        if (CoinConfigurationVersions.isV4(factory.getVersionForDeployedCoin(address(coin)))) {
+            coinsPurchased = _executeV4Buy(buyRecipient, ICoinV4(payable(address(coin))), amountCurrency);
+        } else {
+            coinsPurchased = _executeV3Buy(buyRecipient, ICoinV3(payable(address(coin))), amountCurrency);
+        }
+
+        // make sure that this contract has no balance of the coin remaining
+        uint256 coinBalance = IERC20(address(coin)).balanceOf(address(this));
+        require(coinBalance == 0, CoinBalanceNot0(coinBalance));
+        // make sure that this contract has no balance of the currency remaining
+        uint256 currencyBalance = IERC20(coin.currency()).balanceOf(address(this));
+        require(currencyBalance == 0, CurrencyBalanceNot0(currencyBalance));
+    }
+
+    function _executeV3Buy(address buyRecipient, ICoinV3 coin, uint256 amountCurrency) internal returns (uint256 coinsPurchased) {
+        (, coinsPurchased) = ICoinV3(payable(address(coin))).buy(buyRecipient, amountCurrency, 0, 0, address(0));
+    }
+
+    function _executeV4Buy(address buyRecipient, ICoinV4 coin, uint256 amountCurrency) internal returns (uint256 coinsPurchased) {
+        bytes memory data = abi.encode(buyRecipient, coin, amountCurrency);
+
+        bytes memory result = poolManager.unlock(data);
+
+        coinsPurchased = abi.decode(result, (uint256));
+    }
+
+    error OnlyPoolManager();
+
+    /// @notice Internal fn called when the PoolManager is unlocked.  Used to swap the backing currency for the coin.
+    function unlockCallback(bytes calldata data) external returns (bytes memory) {
+        require(msg.sender == address(poolManager), OnlyPoolManager());
+
+        (address buyRecipient, ICoinV4 coin, uint256 amountCurrency) = abi.decode(data, (address, ICoinV4, uint256));
+
+        bool zeroForOne = coin.currency() == Currency.unwrap(coin.getPoolKey().currency0);
+
+        BalanceDelta delta = poolManager.swap(
+            coin.getPoolKey(),
+            SwapParams(zeroForOne, -(int128(uint128(amountCurrency))), zeroForOne ? TickMath.MIN_SQRT_PRICE + 1 : TickMath.MAX_SQRT_PRICE - 1),
+            ""
+        );
+
+        int128 amountCoin = zeroForOne ? delta.amount1() : delta.amount0();
+
+        // sync the currency balance before transferring to the pool manager
+        poolManager.sync(Currency.wrap(coin.currency()));
+        // transfer the currency to the pool manager for the swap
+        IERC20(coin.currency()).transfer(address(poolManager), uint256(uint128(amountCurrency)));
+        // collect the coin from the pool manager
+        poolManager.take(Currency.wrap(address(coin)), buyRecipient, uint256(uint128(amountCoin)));
+
+        poolManager.settle();
+
+        return abi.encode(uint256(uint128(amountCoin)));
+    }
+}

package/src/interfaces/ICoin.sol

@@ -4,18 +4,34 @@ pragma solidity ^0.8.23;
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IERC7572} from "./IERC7572.sol";
 import {IDopplerErrors} from "./IDopplerErrors.sol";
+import {PoolKey} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {PoolConfiguration} from "../types/PoolConfiguration.sol";
 
-/// @notice The configuration of the pool
-/// @dev This is used to configure the pool's liquidity positions
-struct PoolConfiguration {
+struct PoolConfigurationV4 {
     uint8 version;
-    int24 tickLower;
-    int24 tickUpper;
-    uint16 numPositions;
-    uint256 maxDiscoverySupplyShare;
+    PoolKey poolKey;
+    int24 tick;
 }
 
-interface ICoin is IERC165, IERC7572, IDopplerErrors {
+struct PoolKeyStruct {
+    address currency0;
+    address currency1;
+    uint24 fee;
+    int24 tickSpacing;
+    address hooks;
+}
+
+interface IHasRewardsRecipients {
+    function payoutRecipient() external view returns (address);
+
+    function platformReferrer() external view returns (address);
+
+    function protocolRewardRecipient() external view returns (address);
+
+    function dopplerFeeRecipient() external view returns (address);
+}
+
+interface ICoin is IERC165, IERC7572, IDopplerErrors, IHasRewardsRecipients {
     /// @notice Thrown when an operation is attempted with a zero address
     error AddressZero();
 
@@ -73,6 +89,9 @@ interface ICoin is IERC165, IERC7572, IDopplerErrors {
     /// @notice Thrown when a Doppler pool does not have more than 2 discovery positions
     error DopplerPoolMustHaveMoreThan2DiscoveryPositions();
 
+    /// @notice Thrown when an invalid pool version is specified
+    error InvalidPoolVersion();
+
     /// @notice The rewards accrued from the market's liquidity position
     struct MarketRewards {
         uint256 totalAmountCurrency;
@@ -177,33 +196,6 @@ interface ICoin is IERC165, IERC7572, IDopplerErrors {
     /// @param name The coin name
     event ContractMetadataUpdated(address indexed caller, string newURI, string name);
 
-    /// @notice Executes a buy order
-    /// @param recipient The recipient address of the coins
-    /// @param orderSize The amount of coins to buy
-    /// @param tradeReferrer The address of the trade referrer
-    /// @param sqrtPriceLimitX96 The price limit for Uniswap V3 pool swap
-    function buy(
-        address recipient,
-        uint256 orderSize,
-        uint256 minAmountOut,
-        uint160 sqrtPriceLimitX96,
-        address tradeReferrer
-    ) external payable returns (uint256, uint256);
-
-    /// @notice Executes a sell order
-    /// @param recipient The recipient of the currency
-    /// @param orderSize The amount of coins to sell
-    /// @param minAmountOut The minimum amount of currency to receive
-    /// @param sqrtPriceLimitX96 The price limit for the swap
-    /// @param tradeReferrer The address of the trade referrer
-    function sell(
-        address recipient,
-        uint256 orderSize,
-        uint256 minAmountOut,
-        uint160 sqrtPriceLimitX96,
-        address tradeReferrer
-    ) external returns (uint256, uint256);
-
     /// @notice Enables a user to burn their tokens
     /// @param amount The amount of tokens to burn
     function burn(uint256 amount) external;
@@ -212,11 +204,11 @@ interface ICoin is IERC165, IERC7572, IDopplerErrors {
     /// @return The token URI
     function tokenURI() external view returns (string memory);
 
-    /// @notice Returns the address of the platform referrer
-    /// @return The platform referrer's address
-    function platformReferrer() external view returns (address);
-
     /// @notice Returns the address of the currency
     /// @return The currency's address
     function currency() external view returns (address);
+
+    /// @notice Returns the address of the Airlock
+    /// @return The Airlock's address
+    function airlock() external view returns (address);
 }

package/src/interfaces/ICoinV3.sol

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {ICoin} from "./ICoin.sol";
+import {LpPosition} from "../types/LpPosition.sol";
+import {PoolConfiguration} from "./ICoin.sol";
+
+interface ICoinV3 is ICoin {
+    /// @notice Returns the WETH address
+    function WETH() external view returns (address);
+
+    /// @notice Returns the address of the Uniswap V3 factory
+    function v3Factory() external view returns (address);
+
+    /// @notice Initializes a new coin
+    /// @param payoutRecipient_ The address of the coin creator
+    /// @param tokenURI_ The metadata URI
+    /// @param name_ The coin name
+    /// @param symbol_ The coin symbol
+    /// @param platformReferrer_ The address of the platform referrer
+    /// @param currency_ The address of the currency
+    /// @param poolAddress_ The address of the pool
+    /// @param poolConfiguration_ The configuration of the pool
+    function initialize(
+        address payoutRecipient_,
+        address[] memory owners_,
+        string memory tokenURI_,
+        string memory name_,
+        string memory symbol_,
+        address platformReferrer_,
+        address currency_,
+        address poolAddress_,
+        PoolConfiguration memory poolConfiguration_,
+        LpPosition[] memory positions_
+    ) external;
+
+    /// @notice Executes a buy order
+    /// @param recipient The recipient address of the coins
+    /// @param orderSize The amount of coins to buy
+    /// @param tradeReferrer The address of the trade referrer
+    /// @param sqrtPriceLimitX96 The price limit for Uniswap V3 pool swap
+    function buy(
+        address recipient,
+        uint256 orderSize,
+        uint256 minAmountOut,
+        uint160 sqrtPriceLimitX96,
+        address tradeReferrer
+    ) external payable returns (uint256, uint256);
+
+    /// @notice Executes a sell order
+    /// @param recipient The recipient of the currency
+    /// @param orderSize The amount of coins to sell
+    /// @param minAmountOut The minimum amount of currency to receive
+    /// @param sqrtPriceLimitX96 The price limit for the swap
+    /// @param tradeReferrer The address of the trade referrer
+    function sell(
+        address recipient,
+        uint256 orderSize,
+        uint256 minAmountOut,
+        uint160 sqrtPriceLimitX96,
+        address tradeReferrer
+    ) external returns (uint256, uint256);
+
+    /// @notice Force claim any accrued secondary rewards from the market's liquidity position.
+    /// @dev This function is a fallback, secondary rewards will be claimed automatically on each buy and sell.
+    /// @param pushEthRewards Whether to push the ETH directly to the recipients.
+    function claimSecondaryRewards(bool pushEthRewards) external;
+
+    /// @notice Returns the address of the Uniswap V3 pool
+    function poolAddress() external view returns (address);
+}

package/src/interfaces/ICoinV4.sol

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {ICoin} from "./ICoin.sol";
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {PoolConfiguration} from "../types/PoolConfiguration.sol";
+import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
+import {PathKey} from "@uniswap/v4-periphery/src/libraries/PathKey.sol";
+import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
+import {IDeployedCoinVersionLookup} from "./IDeployedCoinVersionLookup.sol";
+
+/// @notice Returns the pool key for the coin
+interface IHasPoolKey {
+    /// @notice Returns the Uniswap V4 pool key associated with this coin
+    /// @return The PoolKey struct containing pool identification parameters
+    function getPoolKey() external view returns (PoolKey memory);
+}
+
+/// @notice Returns the pool configuration for the coin
+interface IHasSwapPath {
+    /// @notice Struct containing the swap path configuration for converting fees to payout currency
+    /// @param path Array of PathKey structs defining the multi-hop swap route
+    /// @param currencyIn The input currency to start the swap path from
+    struct PayoutSwapPath {
+        PathKey[] path;
+        Currency currencyIn;
+    }
+
+    /// @notice Returns the swap path configuration for converting this coin to its final payout currency
+    /// @dev This enables multi-hop swaps through intermediate currencies to reach the target payout token
+    /// @param coinVersionLookup Contract for looking up deployed coin versions to build recursive paths
+    /// @return PayoutSwapPath struct containing the complete swap route configuration
+    function getPayoutSwapPath(IDeployedCoinVersionLookup coinVersionLookup) external view returns (PayoutSwapPath memory);
+}
+
+interface ICoinV4 is ICoin, IHasPoolKey, IHasSwapPath {
+    /// @notice Returns the pool configuration settings for this coin's Uniswap V4 pool
+    /// @return PoolConfiguration struct containing pool-specific settings and parameters
+    function getPoolConfiguration() external view returns (PoolConfiguration memory);
+
+    /// @notice Returns the hooks contract used by this coin's Uniswap V4 pool
+    /// @return The IHooks contract interface that handles pool lifecycle events
+    function hooks() external view returns (IHooks);
+
+    /// @notice Initializes the coin
+    /// @dev Called by the factory contract when the contract is deployed.
+    /// @param payoutRecipient_ The address of the payout recipient. Can be updated by the owner. Cannot be 0 address.
+    /// @param owners_ The addresses of the owners. All owners have the same full admin access. Cannot be 0 address.
+    /// @param tokenURI_ The URI of the token. Can be updated by the owner.
+    /// @param name_ The name of the token. Cannot be updated.
+    /// @param symbol_ The symbol of the token. Cannot be updated.
+    /// @param platformReferrer_ The address of the platform referrer. Cannot be updated.
+    /// @param currency_ The currency of the coin. Cannot be updated. Can be the zero address for ETH.
+    /// @param poolKey_ The pool key for the coin. Derived in the factory.
+    /// @param sqrtPriceX96 The initial sqrt price for the pool
+    /// @param poolConfiguration_ The configuration for the pool
+    function initialize(
+        address payoutRecipient_,
+        address[] memory owners_,
+        string memory tokenURI_,
+        string memory name_,
+        string memory symbol_,
+        address platformReferrer_,
+        address currency_,
+        PoolKey memory poolKey_,
+        uint160 sqrtPriceX96,
+        PoolConfiguration memory poolConfiguration_
+    ) external;
+}

package/src/interfaces/IDeployedCoinVersionLookup.sol

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+/// @title IDeployedCoinVersionLookup
+/// @notice Interface for querying the version of a deployed coin
+interface IDeployedCoinVersionLookup {
+    /// @notice Gets the version for a deployed coin
+    /// @param coin The address of the coin
+    /// @return version The version of the coin (0 if not found)
+    function getVersionForDeployedCoin(address coin) external view returns (uint8);
+}

package/src/interfaces/IMsgSender.sol

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+/// @notice Interface for getting the correct message sender.
+interface IMsgSender {
+    /// @notice Returns the address of the message sender.
+    /// @return The address of the message sender.
+    function msgSender() external view returns (address);
+}

package/src/interfaces/IPoolConfigEncoding.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+/// @dev contract to enable encoding pool config from the client
+interface IPoolConfigEncoding {
+    function encodeMultiCurvePoolConfig(
+        uint8 version,
+        address currency,
+        int24[] memory tickLower,
+        int24[] memory tickUpper,
+        uint16[] memory numDiscoveryPositions,
+        uint256[] memory maxDiscoverySupplyShare
+    ) external pure returns (bytes memory);
+}

package/src/interfaces/ISwapPathRouter.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.25;
+
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
+
+interface ISwapPathRouter {
+    struct Path {
+        PoolKey key;
+        Currency currencyIn;
+    }
+
+    function getSwapPath(PoolKey memory key, Currency toSwapOut) external view returns (Path[] memory path);
+}