@towns-protocol/contracts 0.0.302

package/src/router/ISwapRouter.sol

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+interface ISwapRouterBase {
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          STRUCTS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Parameters for an exact input swap
+    /// @param tokenIn The input token
+    /// @param tokenOut The output token
+    /// @param amountIn The amount of input tokens to swap
+    /// @param minAmountOut The minimum amount of output tokens to receive
+    /// @param recipient The address to receive the output tokens
+    struct ExactInputParams {
+        address tokenIn;
+        address tokenOut;
+        uint256 amountIn;
+        uint256 minAmountOut;
+        address recipient;
+    }
+
+    /// @notice Parameters for Permit2 signature transfer with witness
+    /// @dev Token and amount are derived from ExactInputParams
+    /// @param owner The owner of the tokens (who signed the permit)
+    /// @param nonce The permit nonce
+    /// @param deadline The permit deadline
+    /// @param signature The permit signature
+    struct Permit2Params {
+        address owner;
+        uint256 nonce;
+        uint256 deadline;
+        bytes signature;
+    }
+
+    /// @notice Parameters for external router interaction
+    /// @param router The address of the router to use
+    /// @param approveTarget The address to approve token transfers
+    /// @param swapData The calldata to execute on the router
+    struct RouterParams {
+        address router;
+        address approveTarget;
+        bytes swapData;
+    }
+
+    /// @notice Fee configuration for permit-based swaps
+    /// @param recipient The address that should receive the fee
+    /// @param feeBps The expected fee in basis points
+    struct FeeConfig {
+        address recipient;
+        uint16 feeBps;
+    }
+
+    struct SwapWitness {
+        ExactInputParams exactInputParams;
+        RouterParams routerParams;
+        FeeConfig feeConfig;
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           ERRORS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Error thrown when an invalid router is specified
+    error SwapRouter__InvalidRouter();
+
+    /// @notice Error thrown when an invalid amount is provided
+    error SwapRouter__InvalidAmount();
+
+    /// @notice Error thrown when the output amount is less than the minimum expected
+    error SwapRouter__InsufficientOutput();
+
+    /// @notice Error thrown when ETH is sent but not expected (tokenIn is not the native token)
+    error SwapRouter__UnexpectedETH();
+
+    /// @notice Error thrown when an invalid BPS value is provided
+    error SwapRouter__InvalidBps();
+
+    /// @notice Error thrown when native token is used with permit (not supported)
+    error SwapRouter__NativeTokenNotSupportedWithPermit();
+
+    /// @notice Error thrown when recipient is not specified (address(0))
+    error SwapRouter__RecipientRequired();
+
+    /// @notice Error thrown when tokenIn and tokenOut are the same
+    error SwapRouter__SameToken();
+
+    /// @notice Error thrown when the poster fee in permit doesn't match the actual configured fee
+    error SwapRouter__PosterFeeMismatch();
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                           EVENTS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Emitted when the SwapRouter is initialized
+    /// @param spaceFactory The address of the space factory
+    event SwapRouterInitialized(address spaceFactory);
+
+    /// @notice Emitted when a swap is successfully executed
+    /// @param router The address of the router used
+    /// @param caller The address that initiated the swap
+    /// @param tokenIn The input token
+    /// @param tokenOut The output token
+    /// @param amountIn The amount of input tokens sold
+    /// @param amountOut The amount of output tokens received
+    /// @param recipient The address that received the output tokens
+    event Swap(
+        address indexed router,
+        address indexed caller,
+        address tokenIn,
+        address tokenOut,
+        uint256 amountIn,
+        uint256 amountOut,
+        address recipient
+    );
+
+    /// @notice Emitted when fees are distributed after a swap
+    /// @param token The token in which fees are paid
+    /// @param protocol The address receiving the protocol fee
+    /// @param poster The address receiving the poster fee (if any)
+    /// @param protocolAmount The amount of tokens sent as protocol fee
+    /// @param posterAmount The amount of tokens sent to the poster
+    event FeeDistribution(
+        address indexed token,
+        address indexed protocol,
+        address indexed poster,
+        uint256 protocolAmount,
+        uint256 posterAmount
+    );
+}
+
+interface ISwapRouter is ISwapRouterBase {
+    /// @notice Executes a swap through a whitelisted router
+    /// @param params The parameters for the swap
+    /// tokenIn The token being sold
+    /// tokenOut The token being bought
+    /// amountIn The amount of tokenIn to swap
+    /// minAmountOut The minimum amount of tokenOut to receive
+    /// recipient The address to receive the output tokens
+    /// @param routerParams The router parameters for the swap
+    /// router The address of the router to use
+    /// approveTarget The address to approve the token transfer
+    /// swapData The calldata to execute on the router
+    /// @param poster The address that posted this swap opportunity
+    /// @return amountOut The amount of tokenOut received
+    /// @return protocolFee The amount of protocol fee collected
+    function executeSwap(
+        ExactInputParams calldata params,
+        RouterParams calldata routerParams,
+        address poster
+    ) external payable returns (uint256 amountOut, uint256 protocolFee);
+
+    /// @notice Executes a swap using Permit2 with witness data binding permit to swap intent
+    /// @dev Uses Uniswap's Permit2 protocol with witness binding for enhanced security.
+    /// Integration flow:
+    /// 1. User approves tokens to Permit2 contract (0x000000000022D473030F116dDEE9F6B43aC78BA3)
+    /// 2. Frontend generates permit signature using getPermit2MessageHash()
+    /// 3. Frontend calls this function with signed permit
+    /// @param params The exact input swap parameters that will be bound to the permit signature
+    /// @param routerParams The router interaction parameters that will be bound to the permit signature
+    /// @param permit The Permit2 data containing owner, nonce, deadline, and signature
+    /// @param posterFee The fee configuration including poster address and expected poster fee rate (included in witness)
+    /// @return amountOut The amount of output tokens received after fees
+    /// @return protocolFee The amount of protocol fee collected
+    function executeSwapWithPermit(
+        ExactInputParams calldata params,
+        RouterParams calldata routerParams,
+        FeeConfig calldata posterFee,
+        Permit2Params calldata permit
+    ) external payable returns (uint256 amountOut, uint256 protocolFee);
+
+    /// @notice Calculate fees for ETH input swaps before execution
+    /// @dev This function helps integrators determine the actual amount that will be sent to external
+    /// routers after protocol and poster fees are deducted. Integration flow:
+    /// 1. Call this function to get `amountInAfterFees`
+    /// 2. Use `amountInAfterFees` to get quotes from aggregator
+    /// 3. Construct RouterParams with the aggregator quote
+    /// 4. Call executeSwap with original amountIn and the prepared RouterParams
+    /// @param amountIn The original ETH amount before fees
+    /// @param caller The address that will call executeSwap (to calculate correct fees based on space status)
+    /// @param poster The address that posted this swap opportunity
+    /// @return amountInAfterFees The ETH amount that will be sent to external router after fees
+    /// @return protocolFee The amount collected as protocol fee
+    /// @return posterFee The amount collected as poster fee
+    function getETHInputFees(
+        uint256 amountIn,
+        address caller,
+        address poster
+    ) external view returns (uint256 amountInAfterFees, uint256 protocolFee, uint256 posterFee);
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                        PERMIT2 UTILS                       */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Get the next available Permit2 nonce for a user from Permit2's bitmap system
+    /// @dev Permit2 uses a bitmap system where each bit represents a nonce state (0=available, 1=used).
+    /// Nonces are organized in 256-nonce "words" (uint256 bitmaps). This function efficiently searches
+    /// through words starting from the one containing startNonce, using bit manipulation to find the
+    /// first available nonce. The search continues across word boundaries until an available nonce is
+    /// found or the maximum word position is reached.
+    /// @param owner The address to check nonce availability for
+    /// @param startNonce The nonce to start searching from (inclusive - will return this exact nonce if available)
+    /// @return nonce The next available nonce at or after startNonce, or type(uint256).max if no nonces are available (stop flag)
+    function getPermit2Nonce(
+        address owner,
+        uint256 startNonce
+    ) external view returns (uint256 nonce);
+
+    /// @notice Generate the EIP-712 message hash for Permit2 signature
+    /// @dev Generates the exact hash that needs to be signed for permit-based swaps
+    /// @param params Swap parameters that will be bound to permit signature
+    /// @param routerParams Router parameters that will be bound to permit signature
+    /// @param posterFee Fee configuration including poster address and expected poster fee rate (included in witness)
+    /// @param amount Token amount to permit (should be >= params.amountIn)
+    /// @param nonce Permit nonce (use getPermit2Nonce to find available nonce)
+    /// @param deadline Permit deadline (unix timestamp)
+    /// @return messageHash The EIP-712 message hash ready for signing
+    function getPermit2MessageHash(
+        ExactInputParams calldata params,
+        RouterParams calldata routerParams,
+        FeeConfig calldata posterFee,
+        uint256 amount,
+        uint256 nonce,
+        uint256 deadline
+    ) external view returns (bytes32 messageHash);
+}

package/src/router/Permit2Hash.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+import {PermitHash} from "@uniswap/permit2/src/libraries/PermitHash.sol";
+import {ISwapRouterBase} from "./ISwapRouter.sol";
+
+library Permit2Hash {
+    /// @notice EIP-712 type hash for ExactInputParams struct
+    bytes32 internal constant EXACT_INPUT_PARAMS_TYPE_HASH =
+        keccak256(
+            "ExactInputParams(address tokenIn,address tokenOut,uint256 amountIn,uint256 minAmountOut,address recipient)"
+        );
+
+    /// @notice EIP-712 type hash for RouterParams struct
+    bytes32 internal constant ROUTER_PARAMS_TYPE_HASH =
+        keccak256("RouterParams(address router,address approveTarget,bytes swapData)");
+
+    /// @notice EIP-712 type hash for FeeConfig struct
+    bytes32 internal constant FEE_CONFIG_TYPE_HASH =
+        keccak256("FeeConfig(address recipient,uint16 feeBps)");
+
+    /// @notice EIP-712 type string for SwapWitness struct used in permit signatures
+    /// @dev Defines the complete type definition including nested struct types for swap parameters
+    string internal constant WITNESS_TYPE =
+        "SwapWitness(ExactInputParams exactInputParams,RouterParams routerParams,FeeConfig feeConfig)ExactInputParams(address tokenIn,address tokenOut,uint256 amountIn,uint256 minAmountOut,address recipient)FeeConfig(address recipient,uint16 feeBps)RouterParams(address router,address approveTarget,bytes swapData)";
+
+    /// @notice Keccak256 hash of the WITNESS_TYPE string
+    /// @dev Pre-computed hash for gas efficiency in signature verification
+    bytes32 internal constant WITNESS_TYPE_HASH = keccak256(bytes(WITNESS_TYPE));
+
+    /// @notice EIP-712 witness type string for SwapWitness
+    /// @dev This string defines the structure of the witness data that binds permit signatures
+    /// to specific swap parameters, preventing front-running and parameter manipulation attacks
+    string internal constant WITNESS_TYPE_STRING =
+        "SwapWitness witness)ExactInputParams(address tokenIn,address tokenOut,uint256 amountIn,uint256 minAmountOut,address recipient)FeeConfig(address recipient,uint16 feeBps)RouterParams(address router,address approveTarget,bytes swapData)SwapWitness(ExactInputParams exactInputParams,RouterParams routerParams,FeeConfig feeConfig)TokenPermissions(address token,uint256 amount)";
+
+    /// @notice EIP-712 type hash for PermitWitnessTransferFrom with SwapWitness
+    /// @dev Combined type hash for Permit2 witness transfers with swap-specific witness data
+    /// Used to create structured hashes that bind permit signatures to exact swap parameters
+    bytes32 internal constant PERMIT_WITNESS_TRANSFER_FROM_TYPEHASH =
+        keccak256(
+            abi.encodePacked(
+                PermitHash._PERMIT_TRANSFER_FROM_WITNESS_TYPEHASH_STUB,
+                WITNESS_TYPE_STRING
+            )
+        );
+
+    /// @notice Hashes SwapWitness struct according to EIP-712
+    /// @param witness The SwapWitness struct to hash
+    /// @return bytes32 The EIP-712 hashStruct of SwapWitness
+    function hash(ISwapRouterBase.SwapWitness memory witness) internal pure returns (bytes32) {
+        return
+            keccak256(
+                abi.encode(
+                    WITNESS_TYPE_HASH,
+                    hash(witness.exactInputParams),
+                    hash(witness.routerParams),
+                    hash(witness.feeConfig)
+                )
+            );
+    }
+
+    /// @notice Hashes ExactInputParams struct according to EIP-712
+    /// @param params The ExactInputParams struct to hash
+    /// @return bytes32 The EIP-712 hashStruct of ExactInputParams
+    function hash(ISwapRouterBase.ExactInputParams memory params) internal pure returns (bytes32) {
+        return keccak256(abi.encode(EXACT_INPUT_PARAMS_TYPE_HASH, params));
+    }
+
+    /// @notice Hashes RouterParams struct according to EIP-712
+    /// @param params The RouterParams struct to hash
+    /// @return bytes32 The EIP-712 hashStruct of RouterParams
+    function hash(ISwapRouterBase.RouterParams memory params) internal pure returns (bytes32) {
+        // RouterParams contains dynamic bytes, so we must encode fields individually per EIP-712
+        return
+            keccak256(
+                abi.encode(
+                    ROUTER_PARAMS_TYPE_HASH,
+                    params.router,
+                    params.approveTarget,
+                    keccak256(params.swapData) // Dynamic bytes must be hashed
+                )
+            );
+    }
+
+    /// @notice Hashes FeeConfig struct according to EIP-712
+    /// @param feeConfig The FeeConfig struct to hash
+    /// @return bytes32 The EIP-712 hashStruct of FeeConfig
+    function hash(ISwapRouterBase.FeeConfig memory feeConfig) internal pure returns (bytes32) {
+        return keccak256(abi.encode(FEE_CONFIG_TYPE_HASH, feeConfig));
+    }
+}