@towns-protocol/contracts 0.0.302

package/src/spaces/facets/swap/SwapFacet.sol

@@ -0,0 +1,290 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {ITownsPointsBase} from "../../../airdrop/points/ITownsPoints.sol";
+import {IPlatformRequirements} from "../../../factory/facets/platform/requirements/IPlatformRequirements.sol";
+import {ISwapRouter} from "../../../router/ISwapRouter.sol";
+import {ISwapFacet} from "./ISwapFacet.sol";
+
+// libraries
+import {BasisPoints} from "../../../utils/libraries/BasisPoints.sol";
+import {CurrencyTransfer} from "../../../utils/libraries/CurrencyTransfer.sol";
+import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
+import {DependencyLib} from "../DependencyLib.sol";
+import {MembershipStorage} from "../membership/MembershipStorage.sol";
+import {SwapFacetStorage} from "./SwapFacetStorage.sol";
+import {FixedPointMathLib} from "solady/utils/FixedPointMathLib.sol";
+import {SafeTransferLib} from "solady/utils/SafeTransferLib.sol";
+
+// contracts
+import {Entitled} from "../Entitled.sol";
+import {PointsBase} from "../points/PointsBase.sol";
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+import {ReentrancyGuardTransient} from "solady/utils/ReentrancyGuardTransient.sol";
+
+/**
+ * @title SwapFacet
+ * @notice Diamond facet for executing swaps within a space with configurable fees and poster handling
+ * @dev This facet extends SwapRouter functionality with space-specific features:
+ *
+ * Standard Swaps (`executeSwap`):
+ * - Space membership validation required for all callers
+ * - Configurable poster fees (to space treasury or forwarded to poster)
+ * - Smart ETH refund logic accounts for poster fees when poster is space
+ * - Points minting for ETH-involved swaps
+ *
+ * Permit2 Swaps (`executeSwapWithPermit`):
+ * - All standard swap features plus Permit2 security enhancements
+ * - Cryptographic binding prevents fee manipulation attacks
+ *
+ * Space-Specific Features:
+ * - Owner-configurable poster fee rates and forwarding behavior via `setSwapFeeConfig`
+ * - Automatic fee collection to space treasury when poster equals space address
+ * - Smart refund logic preserves space fees during partial ETH swaps
+ * - Integration with space entitlement and membership validation systems
+ * - Diamond pattern integration for upgradeable space functionality
+ */
+contract SwapFacet is ISwapFacet, ReentrancyGuardTransient, Entitled, PointsBase, Facet {
+    using CustomRevert for bytes4;
+    using SafeTransferLib for address;
+
+    /// @notice Maximum fee in basis points (2%)
+    uint16 internal constant MAX_FEE_BPS = 200;
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                       ADMIN FUNCTIONS                      */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @inheritdoc ISwapFacet
+    function setSwapFeeConfig(uint16 posterFeeBps, bool forwardPosterFee) external onlyOwner {
+        // get protocol fee for validation
+        IPlatformRequirements platform = _getPlatformRequirements();
+        (uint16 protocolBps, ) = platform.getSwapFees();
+
+        // ensure total fee is reasonable
+        if (protocolBps + posterFeeBps > MAX_FEE_BPS) {
+            SwapFacet__TotalFeeTooHigh.selector.revertWith();
+        }
+
+        SwapFacetStorage.Layout storage ds = SwapFacetStorage.layout();
+        (ds.posterFeeBps, ds.forwardPosterFee) = (posterFeeBps, forwardPosterFee);
+
+        emit SwapFeeConfigUpdated(posterFeeBps, forwardPosterFee);
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                            SWAP                            */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @inheritdoc ISwapFacet
+    function executeSwap(
+        ExactInputParams calldata params,
+        RouterParams calldata routerParams,
+        address poster
+    ) external payable nonReentrant returns (uint256 amountOut) {
+        address swapRouter = _validateSwapPrerequisites(poster);
+
+        // create mutable copy in memory to modify amountIn for fee-on-transfer tokens
+        ExactInputParams memory paramsMemory = params;
+
+        // handle ERC20 transfers before calling SwapRouter
+        bool isNativeToken = params.tokenIn == CurrencyTransfer.NATIVE_TOKEN;
+
+        // take snapshot of balance BEFORE receiving user tokens for refund calculation
+        uint256 tokenInBalanceBefore;
+        if (!isNativeToken) {
+            // use the actual received amount to handle fee-on-transfer tokens
+            tokenInBalanceBefore = params.tokenIn.balanceOf(address(this));
+            params.tokenIn.safeTransferFrom(msg.sender, address(this), params.amountIn);
+            // update amountIn based on the actual balance after transfer
+            paramsMemory.amountIn = params.tokenIn.balanceOf(address(this)) - tokenInBalanceBefore;
+
+            // approve SwapRouter to spend the tokens
+            params.tokenIn.safeApprove(swapRouter, paramsMemory.amountIn);
+        } else {
+            // for ETH, msg.value is already included in balance, so subtract it
+            tokenInBalanceBefore = address(this).balance - msg.value;
+        }
+
+        // execute swap through the router
+        // forwarding `msg.value` may introduce double-spending if used with `multicall`
+        // which has been handled by Solady Multicallable
+        uint256 protocolFee;
+        (amountOut, protocolFee) = ISwapRouter(swapRouter).executeSwap{value: msg.value}(
+            paramsMemory,
+            routerParams,
+            poster
+        );
+
+        // handle refunds of unconsumed input tokens
+        _handleRefunds(params.tokenIn, tokenInBalanceBefore, poster);
+
+        // reset approval for ERC20 tokens
+        if (!isNativeToken) params.tokenIn.safeApprove(swapRouter, 0);
+
+        _mintPointsAndEmitSwapEvent(params, amountOut, protocolFee, poster, msg.sender);
+    }
+
+    /// @inheritdoc ISwapFacet
+    /// @dev Permit is forwarded directly to SwapRouter which handles all token operations,
+    /// e.g. Permit2 transfers, approvals, refunds
+    function executeSwapWithPermit(
+        ExactInputParams calldata params,
+        RouterParams calldata routerParams,
+        FeeConfig calldata posterFee,
+        Permit2Params calldata permit
+    ) external payable nonReentrant returns (uint256 amountOut) {
+        // Permit2 swaps do not support ETH
+        if (msg.value != 0) SwapFacet__UnexpectedETH.selector.revertWith();
+
+        address swapRouter = _validateSwapPrerequisites(posterFee.recipient);
+
+        // execute swap through the router with permit
+        uint256 protocolFee;
+        (amountOut, protocolFee) = ISwapRouter(swapRouter).executeSwapWithPermit(
+            params,
+            routerParams,
+            posterFee,
+            permit
+        );
+
+        _mintPointsAndEmitSwapEvent(
+            params,
+            amountOut,
+            protocolFee,
+            posterFee.recipient,
+            permit.owner
+        );
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                          GETTERS                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @inheritdoc ISwapFacet
+    function getSwapRouter() public view returns (address) {
+        return DependencyLib.getDependency(MembershipStorage.layout(), DependencyLib.SWAP_ROUTER);
+    }
+
+    /// @inheritdoc ISwapFacet
+    function getSwapFees()
+        public
+        view
+        returns (uint16 protocolBps, uint16 posterBps, bool forwardPosterFee)
+    {
+        SwapFacetStorage.Layout storage ds = SwapFacetStorage.layout();
+
+        // get protocolBps and posterBps from protocol config
+        IPlatformRequirements platform = _getPlatformRequirements();
+        (protocolBps, posterBps) = platform.getSwapFees();
+
+        uint16 spacePosterBps;
+        (spacePosterBps, forwardPosterFee) = (ds.posterFeeBps, ds.forwardPosterFee);
+
+        // if poster fee is forwarded or spacePosterBps is set, use spacePosterBps
+        if (forwardPosterFee || spacePosterBps != 0) posterBps = spacePosterBps;
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                         INTERNAL                            */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    /// @notice Mint points for ETH swaps and emit swap events
+    /// @param params The swap parameters for event emission
+    /// @param amountOut The amount of output tokens received
+    /// @param protocolFee The protocol fee collected for points calculation
+    /// @param poster The swap poster address
+    /// @param payer The address that should receive the points
+    function _mintPointsAndEmitSwapEvent(
+        ExactInputParams calldata params,
+        uint256 amountOut,
+        uint256 protocolFee,
+        address poster,
+        address payer
+    ) internal {
+        // mint points based on the protocol fee if ETH is involved
+        if (
+            params.tokenIn == CurrencyTransfer.NATIVE_TOKEN ||
+            params.tokenOut == CurrencyTransfer.NATIVE_TOKEN
+        ) {
+            address airdropDiamond = _getAirdropDiamond();
+            uint256 points = _getPoints(
+                airdropDiamond,
+                ITownsPointsBase.Action.Swap,
+                abi.encode(protocolFee)
+            );
+            _mintPoints(airdropDiamond, payer, points);
+        }
+
+        emit SwapExecuted(
+            params.recipient,
+            params.tokenIn,
+            params.tokenOut,
+            params.amountIn,
+            amountOut,
+            poster
+        );
+    }
+
+    /// @notice Handles refunds of unconsumed input tokens back to the caller
+    /// @param tokenIn The input token address
+    /// @param tokenInBalanceBefore The balance before receiving tokens from user
+    /// @param poster The poster address for this swap
+    function _handleRefunds(
+        address tokenIn,
+        uint256 tokenInBalanceBefore,
+        address poster
+    ) internal {
+        uint256 currentBalance = _getBalance(tokenIn);
+
+        // calculate base refund amount
+        uint256 refundAmount = FixedPointMathLib.zeroFloorSub(currentBalance, tokenInBalanceBefore);
+
+        // for ETH, subtract poster fee if it was collected to space
+        // this happens when poster is the space itself (regardless of forwardPosterFee setting)
+        if (tokenIn == CurrencyTransfer.NATIVE_TOKEN && poster == address(this)) {
+            // get the poster fee that was collected to space
+            (, uint16 posterBps, ) = getSwapFees();
+            uint256 posterFee = BasisPoints.calculate(msg.value, posterBps);
+
+            // subtract poster fee from refund since it should stay in space
+            refundAmount = FixedPointMathLib.zeroFloorSub(refundAmount, posterFee);
+        }
+
+        CurrencyTransfer.transferCurrency(tokenIn, address(this), msg.sender, refundAmount);
+    }
+
+    /// @notice Validates swap prerequisites (membership, SwapRouter availability, and poster address)
+    /// @param poster The poster address to validate
+    /// @return swapRouter The address of the SwapRouter to use
+    function _validateSwapPrerequisites(address poster) internal view returns (address swapRouter) {
+        _validateMembership(msg.sender);
+
+        swapRouter = getSwapRouter();
+        if (swapRouter == address(0)) SwapFacet__SwapRouterNotSet.selector.revertWith();
+
+        // validate poster address based on fee configuration
+        if (!(_isForwardPosterFee() || poster == address(this))) {
+            SwapFacet__InvalidPosterInput.selector.revertWith();
+        }
+    }
+
+    function _getPlatformRequirements() internal view returns (IPlatformRequirements) {
+        return IPlatformRequirements(MembershipStorage.layout().spaceFactory);
+    }
+
+    /// @notice Gets the balance of a token for this contract
+    /// @param token The token to check
+    /// @return uint256 The balance
+    function _getBalance(address token) internal view returns (uint256) {
+        if (token == CurrencyTransfer.NATIVE_TOKEN) return address(this).balance;
+        return token.balanceOf(address(this));
+    }
+
+    /// @notice Checks if poster fees should be forwarded to the poster
+    /// @return bool True if poster fees are forwarded, false if they go to the space
+    function _isForwardPosterFee() internal view returns (bool) {
+        return SwapFacetStorage.layout().forwardPosterFee;
+    }
+}

package/src/spaces/facets/swap/SwapFacetStorage.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+/// @title SwapFacetStorage
+/// @notice Storage layout for the SwapFacet contract
+library SwapFacetStorage {
+    // keccak256(abi.encode(uint256(keccak256("spaces.facets.swap.storage")) - 1)) &
+    // ~bytes32(uint256(0xff))
+    bytes32 internal constant STORAGE_SLOT =
+        0xf363e6f383c163fac4382e7bd60c54a795a129059b7601463644e52990dfaf00;
+
+    struct Layout {
+        /// @notice Poster fee in basis points (space-specific)
+        uint16 posterFeeBps;
+        /// @notice Whether to forward the poster fee to the poster (default: false, fees go to space)
+        bool forwardPosterFee;
+    }
+
+    function layout() internal pure returns (Layout storage l) {
+        assembly {
+            l.slot := STORAGE_SLOT
+        }
+    }
+}

package/src/spaces/facets/tipping/ITipping.sol

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+
+// contracts
+
+interface ITippingBase {
+    // =============================================================
+    //                           Structs
+    // =============================================================
+
+    struct TipRequest {
+        address receiver;
+        uint256 tokenId;
+        address currency;
+        uint256 amount;
+        bytes32 messageId;
+        bytes32 channelId;
+    }
+
+    // =============================================================
+    //                           Events
+    // =============================================================
+
+    event Tip(
+        uint256 indexed tokenId,
+        address indexed currency,
+        address sender,
+        address receiver,
+        uint256 amount,
+        bytes32 messageId,
+        bytes32 channelId
+    );
+
+    // =============================================================
+    //                           Errors
+    // =============================================================
+
+    error TokenDoesNotExist();
+    error ReceiverIsNotMember();
+    error CannotTipSelf();
+    error AmountIsZero();
+    error CurrencyIsZero();
+}
+
+interface ITipping is ITippingBase {
+    /// @notice Sends a tip to a space member
+    /// @param tipRequest The tip request containing token ID, currency, amount, message ID and
+    /// channel ID
+    /// @dev Requires sender and receiver to be members of the space
+    /// @dev Requires amount > 0 and valid currency address
+    /// @dev Emits Tip event
+    function tip(TipRequest calldata tipRequest) external payable;
+
+    /// @notice Gets the total tips received for a token ID in a specific currency
+    /// @param tokenId The token ID to get tips for
+    /// @param currency The currency address to get tips in
+    /// @return The total amount of tips received in the specified currency
+    function tipsByCurrencyAndTokenId(
+        uint256 tokenId,
+        address currency
+    ) external view returns (uint256);
+
+    /// @notice Gets the list of currencies that have been tipped to the space
+    /// @return An array of currency addresses
+    function tippingCurrencies() external view returns (address[] memory);
+
+    /// @notice Gets the total number of tips received in a specific currency
+    /// @param currency The currency address to get tips for
+    /// @return The total number of tips received in the specified currency
+    function totalTipsByCurrency(address currency) external view returns (uint256);
+
+    /// @notice Gets the total amount of tips received in a specific currency
+    /// @param currency The currency address to get tips for
+    /// @return The total amount of tips received in the specified currency
+    function tipAmountByCurrency(address currency) external view returns (uint256);
+}

package/src/spaces/facets/tipping/TippingBase.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {CurrencyTransfer} from "src/utils/libraries/CurrencyTransfer.sol";
+// contracts
+
+library TippingBase {
+    using EnumerableSet for EnumerableSet.AddressSet;
+
+    // keccak256(abi.encode(uint256(keccak256("spaces.facets.tipping.storage")) - 1)) &
+    // ~bytes32(uint256(0xff))
+    bytes32 internal constant STORAGE_SLOT =
+        0xb6cb334a9eea0cca2581db4520b45ac6f03de8e3927292302206bb82168be300;
+
+    struct TippingStats {
+        uint256 totalTips;
+        uint256 tipAmount;
+    }
+
+    struct Layout {
+        EnumerableSet.AddressSet currencies;
+        mapping(uint256 tokenId => mapping(address currency => uint256 amount)) tipsByCurrencyByTokenId;
+        mapping(address currency => TippingStats) tippingStatsByCurrency;
+    }
+
+    function layout() internal pure returns (Layout storage l) {
+        assembly {
+            l.slot := STORAGE_SLOT
+        }
+    }
+
+    function tip(
+        address sender,
+        address receiver,
+        uint256 tokenId,
+        address currency,
+        uint256 amount
+    ) internal {
+        Layout storage ds = layout();
+
+        ds.currencies.add(currency);
+        ds.tipsByCurrencyByTokenId[tokenId][currency] += amount;
+
+        TippingStats storage stats = ds.tippingStatsByCurrency[currency];
+        stats.tipAmount += amount;
+        stats.totalTips += 1;
+
+        CurrencyTransfer.transferCurrency(currency, sender, receiver, amount);
+    }
+
+    function totalTipsByCurrency(address currency) internal view returns (uint256) {
+        return layout().tippingStatsByCurrency[currency].totalTips;
+    }
+
+    function tipAmountByCurrency(address currency) internal view returns (uint256) {
+        return layout().tippingStatsByCurrency[currency].tipAmount;
+    }
+
+    function tipsByCurrencyByTokenId(
+        uint256 tokenId,
+        address currency
+    ) internal view returns (uint256) {
+        return layout().tipsByCurrencyByTokenId[tokenId][currency];
+    }
+
+    function tippingCurrencies() internal view returns (address[] memory) {
+        return layout().currencies.values();
+    }
+}

package/src/spaces/facets/tipping/TippingFacet.sol

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {ITipping} from "./ITipping.sol";
+import {ITownsPointsBase} from "src/airdrop/points/ITownsPoints.sol";
+import {IPlatformRequirements} from "src/factory/facets/platform/requirements/IPlatformRequirements.sol";
+
+// libraries
+import {TippingBase} from "./TippingBase.sol";
+import {MembershipStorage} from "src/spaces/facets/membership/MembershipStorage.sol";
+import {BasisPoints} from "src/utils/libraries/BasisPoints.sol";
+import {CurrencyTransfer} from "src/utils/libraries/CurrencyTransfer.sol";
+import {CustomRevert} from "src/utils/libraries/CustomRevert.sol";
+
+// contracts
+import {Facet} from "@towns-protocol/diamond/src/facets/Facet.sol";
+import {ReentrancyGuard} from "solady/utils/ReentrancyGuard.sol";
+import {ERC721ABase} from "src/diamond/facets/token/ERC721A/ERC721ABase.sol";
+import {PointsBase} from "../points/PointsBase.sol";
+
+contract TippingFacet is ITipping, ERC721ABase, PointsBase, Facet, ReentrancyGuard {
+    function __Tipping_init() external onlyInitializing {
+        _addInterface(type(ITipping).interfaceId);
+    }
+
+    /// @inheritdoc ITipping
+    function tip(TipRequest calldata tipRequest) external payable nonReentrant {
+        _validateTipRequest(
+            msg.sender,
+            tipRequest.receiver,
+            tipRequest.currency,
+            tipRequest.amount
+        );
+
+        uint256 tipAmount = tipRequest.amount;
+
+        if (tipRequest.currency == CurrencyTransfer.NATIVE_TOKEN) {
+            uint256 protocolFee = _payProtocol(msg.sender, tipRequest.amount);
+            tipAmount = tipRequest.amount - protocolFee;
+
+            address airdropDiamond = _getAirdropDiamond();
+            uint256 points = _getPoints(
+                airdropDiamond,
+                ITownsPointsBase.Action.Tip,
+                abi.encode(protocolFee)
+            );
+            _mintPoints(airdropDiamond, msg.sender, points);
+        }
+
+        TippingBase.tip(
+            msg.sender,
+            tipRequest.receiver,
+            tipRequest.tokenId,
+            tipRequest.currency,
+            tipAmount
+        );
+
+        emit Tip(
+            tipRequest.tokenId,
+            tipRequest.currency,
+            msg.sender,
+            tipRequest.receiver,
+            tipRequest.amount,
+            tipRequest.messageId,
+            tipRequest.channelId
+        );
+    }
+
+    /// @inheritdoc ITipping
+    function tippingCurrencies() external view returns (address[] memory) {
+        return TippingBase.tippingCurrencies();
+    }
+
+    /// @inheritdoc ITipping
+    function tipsByCurrencyAndTokenId(
+        uint256 tokenId,
+        address currency
+    ) external view returns (uint256) {
+        return TippingBase.tipsByCurrencyByTokenId(tokenId, currency);
+    }
+
+    /// @inheritdoc ITipping
+    function totalTipsByCurrency(address currency) external view returns (uint256) {
+        return TippingBase.totalTipsByCurrency(currency);
+    }
+
+    /// @inheritdoc ITipping
+    function tipAmountByCurrency(address currency) external view returns (uint256) {
+        return TippingBase.tipAmountByCurrency(currency);
+    }
+
+    /*´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:*/
+    /*                         Internal                           */
+    /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
+
+    function _validateTipRequest(
+        address sender,
+        address receiver,
+        address currency,
+        uint256 amount
+    ) internal pure {
+        if (currency == address(0)) {
+            CustomRevert.revertWith(CurrencyIsZero.selector);
+        }
+        if (sender == receiver) CustomRevert.revertWith(CannotTipSelf.selector);
+        if (amount == 0) CustomRevert.revertWith(AmountIsZero.selector);
+    }
+
+    function _payProtocol(address sender, uint256 amount) internal returns (uint256 protocolFee) {
+        MembershipStorage.Layout storage ds = MembershipStorage.layout();
+        IPlatformRequirements platform = IPlatformRequirements(ds.spaceFactory);
+
+        protocolFee = BasisPoints.calculate(amount, 50); // 0.5%
+
+        CurrencyTransfer.transferCurrency(
+            CurrencyTransfer.NATIVE_TOKEN,
+            sender,
+            platform.getFeeRecipient(),
+            protocolFee
+        );
+    }
+}

package/src/spaces/facets/treasury/ITreasury.sol

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+
+// contracts
+
+interface ITreasury {
+    /// @notice Withdraw funds from the treasury to a specified account
+    /// @dev Can only be called by the owner of the contract. Will revert if account is zero address
+    /// or if balance is 0
+    /// @param account The address to withdraw funds to
+    function withdraw(address account) external;
+
+    /// @notice Handle the receipt of a single ERC721 token
+    /// @dev Implements the IERC721Receiver interface to safely receive ERC721 tokens
+    /// @param operator The address which called `safeTransferFrom` function
+    /// @param from The address which previously owned the token
+    /// @param tokenId The NFT identifier which is being transferred
+    /// @param data Additional data with no specified format
+    /// @return bytes4 `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`
+    function onERC721Received(
+        address operator,
+        address from,
+        uint256 tokenId,
+        bytes calldata data
+    ) external returns (bytes4);
+
+    /// @notice Handle the receipt of a single ERC1155 token
+    /// @dev Implements the IERC1155Receiver interface to safely receive ERC1155 tokens
+    /// @param operator The address which called the `safeTransferFrom` function
+    /// @param from The address which previously owned the token
+    /// @param id The ID of the token being transferred
+    /// @param value The amount of tokens being transferred
+    /// @param data Additional data with no specified format
+    /// @return bytes4
+    /// `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`
+    function onERC1155Received(
+        address operator,
+        address from,
+        uint256 id,
+        uint256 value,
+        bytes calldata data
+    ) external returns (bytes4);
+
+    /// @notice Handle the receipt of multiple ERC1155 tokens
+    /// @dev Implements the IERC1155Receiver interface to safely receive multiple ERC1155 tokens
+    /// @param operator The address which called the `safeBatchTransferFrom` function
+    /// @param from The address which previously owned the tokens
+    /// @param ids An array containing ids of each token being transferred
+    /// @param values An array containing amounts of each token being transferred
+    /// @param data Additional data with no specified format
+    /// @return bytes4
+    /// `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`
+    function onERC1155BatchReceived(
+        address operator,
+        address from,
+        uint256[] calldata ids,
+        uint256[] calldata values,
+        bytes calldata data
+    ) external returns (bytes4);
+}