ERC-6220: 利用可装备部件的可组合NFT

/// @title EIP-6220 利用可装备部件的可组合NFT
/// @dev 参见 https://eips.ethereum.org/EIPS/eip-6220
/// @dev 注意：此接口的ERC-165标识符为 0x28bc9ae4。

pragma solidity ^0.8.16;

import "./IERC5773.sol";

interface IERC6220 is IERC5773 /*, ERC165 */ {
    /**
     * @notice 用于存储`Equippable`组件的核心结构。
     * @return assetId 装备子项的资产的ID
     * @return childAssetId 用作装备的资产的ID
     * @return childId 已装备的代币的ID
     * @return childEquippableAddress 子资产所属的集合的地址
     */
    struct Equipment {
        uint64 assetId;
        uint64 childAssetId;
        uint256 childId;
        address childEquippableAddress;
    }

    /**
     * @notice 用于提供一个用于输入装备数据的结构。
     * @dev 仅用于输入，不用于存储数据。
     * @return tokenId 我们正在管理的代币的ID
     * @return childIndex 代币的活动子项列表中的子项索引
     * @return assetId 我们正在装备到的资产的ID
     * @return slotPartId 我们用于装备的插槽部件的ID
     * @return childAssetId 我们正在装备的资产的ID
     */
    struct IntakeEquip {
        uint256 tokenId;
        uint256 childIndex;
        uint64 assetId;
        uint64 slotPartId;
        uint64 childAssetId;
    }

    /**
     * @notice 用于通知侦听器，子项的资产已装备到其某个父资产中。
     * @param tokenId 装备了资产的代币的ID
     * @param assetId 与我们正在装备到的代币相关联的资产的ID
     * @param slotPartId 我们用于装备的插槽的ID
     * @param childId 正在装备到插槽中的子代币的ID
     * @param childAddress 子代币集合的地址
     * @param childAssetId 与我们正在装备的代币相关联的资产的ID
     */
    event ChildAssetEquipped(
        uint256 indexed tokenId,
        uint64 indexed assetId,
        uint64 indexed slotPartId,
        uint256 childId,
        address childAddress,
        uint64 childAssetId
    );

    /**
     * @notice 用于通知侦听器，子项的资产已从其某个父资产中解除装备。
     * @param tokenId 解除了资产装备的代币的ID
     * @param assetId 与我们正在解除装备的代币相关联的资产的ID
     * @param slotPartId 我们正在解除装备的插槽的ID
     * @param childId 正在解除装备的代币的ID
     * @param childAddress 正在解除装备的代币所属的集合的地址
     * @param childAssetId 与我们正在解除装备的代币相关联的资产的ID
     */
    event ChildAssetUnequipped(
        uint256 indexed tokenId,
        uint64 indexed assetId,
        uint64 indexed slotPartId,
        uint256 childId,
        address childAddress,
        uint64 childAssetId
    );

    /**
     * @notice 用于通知侦听器，属于`equippableGroupId`的资产已被标记为可装备到给定的插槽和父项中
     * @param equippableGroupId 被标记为可装备到与`parentAddress`集合的`slotPartId`相关联的插槽中的可装备组的ID
     * @param slotPartId 目录的插槽部件的ID，属于与`equippableGroupId`相关联的可装备组的部件可以装备到该目录中
     * @param parentAddress 集合的地址，属于`equippableGroupId`的部件可以装备到该集合中
     */
    event ValidParentEquippableGroupIdSet(
        uint64 indexed equippableGroupId,
        uint64 indexed slotPartId,
        address parentAddress
    );

    /**
     * @notice 用于将子项装备到代币中。
     * @dev `IntakeEquip`结构包含以下数据：
     *  [
     *      tokenId,
     *      childIndex,
     *      assetId,
     *      slotPartId,
     *      childAssetId
     *  ]
     * @param data 指定装备数据的`IntakeEquip`结构
     */
    function equip(
        IntakeEquip memory data
    ) external;

    /**
     * @notice 用于从父代币中解除装备子项。
     * @dev 只能由代币的所有者或已被当前所有者授予权限以管理给定代币的帐户调用。
     * @param tokenId 从中解除装备子项的父代的ID
     * @param assetId 包含子项已装备到的`Slot`的父代的资产的ID
     * @param slotPartId 从中解除装备子项的`Slot`的ID
     */
    function unequip(
        uint256 tokenId,
        uint64 assetId,
        uint64 slotPartId
    ) external;

    /**
     * @notice 用于检查代币是否装备了给定的子项。
     * @dev 用于防止传输已装备的子项。
     * @param tokenId 我们要查询的父代币的ID
     * @param childAddress 子代币智能合约的地址
     * @param childId 子代币的ID
     * @return bool 指示子代币是否已装备到给定代币中的布尔值
     */
    function isChildEquipped(
        uint256 tokenId,
        address childAddress,
        uint256 childId
    ) external view returns (bool);

    /**
     * @notice 用于验证代币是否可以装备到给定父代的插槽中。
     * @param parent 父代币智能合约的地址
     * @param tokenId 我们要装备的代币的ID
     * @param assetId 与我们要装备的代币相关联的资产的ID
     * @param slotId 我们要将代币装备到的插槽的ID
     * @return bool 指示具有给定资产的代币是否可以装备到所需插槽中的布尔值
     */
    function canTokenBeEquippedWithAssetIntoSlot(
        address parent,
        uint256 tokenId,
        uint64 assetId,
        uint64 slotId
    ) external view returns (bool);

    /**
     * @notice 用于获取装备到所需代币的指定插槽中的Equipment对象。
     * @dev `Equipment`结构包含以下数据：
     *  [
     *      assetId,
     *      childAssetId,
     *      childId,
     *      childEquippableAddress
     *  ]
     * @param tokenId 我们要检索其装备的对象的代币的ID
     * @param targetCatalogAddress 与代币的`Slot`部件相关联的`Catalog`的地址
     * @param slotPartId 我们正在检查已装备对象的`Slot`部件的ID
     * @return struct 包含有关已装备对象的数据的`Equipment`结构
     */
    function getEquipment(
        uint256 tokenId,
        address targetCatalogAddress,
        uint64 slotPartId
    ) external view returns (Equipment memory);

    /**
     * @notice 用于获取与给定`assetId`相关联的资产和可装备数据。
     * @param tokenId 要检索资产的代币的ID
     * @param assetId 我们要检索的资产的ID
     * @return metadataURI 资产的元数据URI
     * @return equippableGroupId 此资产所属的可装备组的ID
     * @return catalogAddress 部件所属的目录的地址
     * @return partIds 资产中包含的部件的ID数组
     */
    function getAssetAndEquippableData(uint256 tokenId, uint64 assetId)
        external
        view
        returns (
            string memory metadataURI,
            uint64 equippableGroupId,
            address catalogAddress,
            uint64[] calldata partIds
        );
}

/**
 * @title ICatalog
 * @notice 可装备模块的目录接口。
 * @dev 注意：此接口的ERC-165标识符为 0xd912401f。
 */

pragma solidity ^0.8.16;

interface ICatalog /* is IERC165 */ {
    /**
     * @notice 用于宣布添加新部件的事件。
     * @dev 在添加新部件时发出。
     * @param partId 添加的部件的ID
     * @param itemType 用于指定部件是`None`、`Slot`还是`Fixed`的枚举值
     * @param zIndex 一个指定部件的z值的uint。用于指定应在哪个深度渲染部件
     * @param equippableAddresses 可以装备此部件的地址数组
     * @param metadataURI 部件的元数据URI
     */
    event AddedPart(
        uint64 indexed partId,
        ItemType indexed itemType,
        uint8 zIndex,
        address[] equippableAddresses,
        string metadataURI
    );

    /**
     * @notice 用于宣布向部件添加新的可装备项的事件。
     * @dev 当新的地址被标记为`partId`的可装备项时发出。
     * @param partId 添加了新的可装备地址的部件的ID
     * @param equippableAddresses 可以装备此部件的新地址数组
     */
    event AddedEquippables(
        uint64 indexed partId,
        address[] equippableAddresses
    );

    /**
     * @notice 用于宣布覆盖部件的可装备地址的事件。
     * @dev 当标记为`partId`的可装备项的现有地址列表被新的地址列表覆盖时发出。
     * @param partId 其可装备地址列表被覆盖的部件的ID
     * @param equippableAddresses 可以装备此部件的新的完整地址列表
     */
    event SetEquippables(uint64 indexed partId, address[] equippableAddresses);

    /**
     * @notice 用于宣布任何地址都可以装备给定的部件的事件。
     * @dev 当给定的部件被标记为任何地址都可以装备时发出。
     * @param partId 被标记为任何地址都可以装备的部件的ID
     */
    event SetEquippableToAll(uint64 indexed partId);

    /**
     * @notice 用于定义项目的类型。可能的值为`None`、`Slot`或`Fixed`。
     * @dev 用于固定和插槽部件。
     */
    enum ItemType {
        None,
        Slot,
        Fixed
    }

    /**
     * @notice 定义它的标准RMRK目录项的完整结构。
     * @dev 每个目录项至少需要3个存储槽，相当于柏林硬分叉（2021年4月14日）时约60,000个gas，但考虑到IPFS URI的标准长度，5-7个存储槽更现实。这将导致每250个资产消耗25,000,000到35,000,000个gas--以太坊主网的最大区块大小在高峰使用时为30M。
     * @return itemType 部件的项目类型
     * @return z 部件的z值，定义了在展示完整的NFT时应如何渲染它
     * @return equippable 允许在此部件中装备的地址数组
     * @return metadataURI 部件的元数据URI
     */
    struct Part {
        ItemType itemType; //1字节
        uint8 z; //1字节
        address[] equippable; //n 可以装备到此插槽中的集合
        string metadataURI; //n 字节 32+
    }

    /**
     * @notice 用于添加新的`Part`的结构。
     * @dev 使用指定的ID添加部件，因此您必须确保您使用的是未使用的`partId`，否则将恢复添加部件的操作。
     * @dev 完整的`IntakeStruct`如下所示：
     *  [
     *          partID,
     *      [
     *          itemType,
     *          z,
     *          [
     *               permittedCollectionAddress0,
     *               permittedCollectionAddress1,
     *               permittedCollectionAddress2
     *           ],
     *           metadataURI
     *       ]
     *   ]
     * @return partId 要分配给`Part`的ID
     * @return part 要添加的`Part`
     */
    struct IntakeStruct {
        uint64 partId;
        Part part;
    }

    /**
     * @notice 用于返回与目录关联的元数据URI。
     * @return string 基本元数据URI
     */
    function getMetadataURI() external view returns (string memory);

    /**
     * @notice 用于返回与目录关联的`itemType`
     * @return string 与目录关联的`itemType`
     */
    function getType() external view returns (string memory);

    /**
     * @notice 用于检查是否允许给定的地址装备所需的`Part`。
     * @dev 如果集合可以装备具有`partId`的资产，则返回true。
     * @param partId 我们要检查的部件的ID
     * @param targetAddress 我们要检查是否可以将部件装备到其中的地址
     * @return bool 指示是否可以将`targetAddress`装备到具有`partId`的`Part`中的状态
     */
    function checkIsEquippable(uint64 partId, address targetAddress)
        external
        view
        returns (bool);

    /**
     * @notice 用于检查所有地址是否都可以装备该部件。
     * @dev 如果该部件可以装备给所有人，则返回true。
     * @param partId 我们要检查的部件的ID
     * @return bool 指示是否可以由任何地址装备具有`partId`的部件的状态
     */
    function checkIsEquippableToAll(uint64 partId) external view returns (bool);

    /**
     * @notice 用于检索ID为`partId`的`Part`
     * @param partId 我们要检索的部件的ID
     * @return struct 与给定的`partId`关联的`Part`结构
     */
    function getPart(uint64 partId) external view returns (Part memory);

    /**
     * @notice 用于同时检索多个部件。
     * @param partIds 我们要检索的部件ID数组
     * @return struct 与给定的`partIds`关联的`Part`结构数组
     */
    function getParts(uint64[] calldata partIds)
        external
        view
        returns (Part[] memory);
}