ERC-6059: 父级管理的、可嵌套的非同质化代币

/// @title EIP-6059 父级管理的、可嵌套的非同质化代币
/// @dev 请参阅 https://eips.ethereum.org/EIPS/eip-6059
/// @dev 注意：此接口的 ERC-165 标识符为 0x42b0e56f。

pragma solidity ^0.8.16;

interface IERC6059 /* is ERC165 */ {
    /**
     * @notice 核心所有权结构体。
     * @dev `DirectOwner` 结构体用于存储下一个直接所有者的信息，无论是父代币、
     * 一个 `ERC721Receiver` 合约还是一个外部拥有的账户。
     * @dev 如果代币不属于 NFT，则 `tokenId` 必须等于 `0`。
     * @param tokenId 父代币的 ID
     * @param ownerAddress 代币所有者的地址。如果所有者是另一个代币，则地址必须是
     *  父代币的集合智能合约的地址。如果所有者是外部拥有的帐户，则地址
     *  必须是此帐户的地址
     */
    struct DirectOwner {
        uint256 tokenId;
        address ownerAddress;
    }

    /**
     * @notice 用于通知侦听器该代币正在被转移。
     * @dev 当 `tokenId` 代币从 `from` 转移到 `to` 时发出。
     * @param from 前一个直接所有者的地址，如果代币被嵌套，则为智能合约。
     * @param to 新的直接所有者的地址，如果代币正在被嵌套，则为智能合约。
     * @param fromTokenId 前一个父代币的 ID。如果该代币之前未嵌套，则值必须为 `0`
     * @param toTokenId 新的父代币的 ID。如果该代币未被嵌套，则值必须为 `0`
     * @param tokenId 被转移的代币的 ID
     */
    event NestTransfer(
        address indexed from,
        address indexed to,
        uint256 fromTokenId,
        uint256 toTokenId,
        uint256 indexed tokenId
    );

    /**
     * @notice 用于通知侦听器已将新代币添加到给定代币的待处理子代币数组。
     * @dev 当子 NFT 被添加到代币的待处理数组时发出。
     * @param tokenId 接收到新的待处理子代币的代币的 ID
     * @param childIndex 提议的子代币在父代币的待处理子代币数组中的索引
     * @param childAddress 提议的子代币的集合智能合约的地址
     * @param childId 子代币在子代币的集合智能合约中的 ID
     */
    event ChildProposed(
        uint256 indexed tokenId,
        uint256 childIndex,
        address indexed childAddress,
        uint256 indexed childId
    );

    /**
     * @notice 用于通知侦听器新子代币已被父代币接受。
     * @dev 当父代币从其待处理数组中接受一个代币，将其迁移到活动数组时发出。
     * @param tokenId 接受新子代币的代币的 ID
     * @param childIndex 新接受的子代币在父代币的活动子代币数组中的索引
     * @param childAddress 子代币的集合智能合约的地址
     * @param childId 子代币在子代币的集合智能合约中的 ID
     */
    event ChildAccepted(
        uint256 indexed tokenId,
        uint256 childIndex,
        address indexed childAddress,
        uint256 indexed childId
    );

    /**
     * @notice 用于通知侦听器已拒绝给定代币的所有待处理子代币。
     * @dev 当代币从其待处理数组中移除所有子代币时发出。
     * @param tokenId 拒绝所有待处理子代币的代币的 ID
     */
    event AllChildrenRejected(uint256 indexed tokenId);

    /**
     * @notice 用于通知侦听器已将子代币从父代币转移。
     * @dev 当代币将其自身转移子代币时发出，转移所有权。
     * @param tokenId 转移子代币的代币的 ID
     * @param childIndex 被转移的子代币在其所属数组中的索引
     * @param childAddress 子代币的集合智能合约的地址
     * @param childId 子代币在其自己的集合智能合约中的 ID
     * @param fromPending 一个布尔值，表示该代币是否在待处理子代币数组中 (`true`) 或
     *  在活动子代币数组中 (`false`)
     */
    event ChildTransferred(
        uint256 indexed tokenId,
        uint256 childIndex,
        address indexed childAddress,
        uint256 indexed childId,
        bool fromPending
    );

    /**
     * @notice 核心子代币结构体，保存有关子代币的信息。
     * @return tokenId 子代币在子代币的集合智能合约中的 ID
     * @return contractAddress 子代币的智能合约的地址
     */
    struct Child {
        uint256 tokenId;
        address contractAddress;
    }

    /**
     * @notice 用于检索给定代币的*根*所有者。
     * @dev 代币的*根*所有者是层次结构中不是 NFT 的顶层所有者。
     * @dev 如果代币由另一个 NFT 拥有，它必须递归查找父代的根所有者。
     * @param tokenId 为其检索*根*所有者的代币的 ID
     * @return owner 代币的*根*所有者
     */
    function ownerOf(uint256 tokenId) external view returns (address owner);

    /**
     * @notice 用于检索给定代币的直接所有者。
     * @dev 如果直接所有者是另一个代币，则返回的地址必须是父代币的
     *  集合智能合约的地址。
     * @param tokenId 为其检索直接所有者的代币的 ID
     * @return address 给定代币的所有者的地址
     * @return uint256 父代币的 ID。如果所有者不是 NFT，则必须为 `0`
     * @return bool 指示所有者是否为 NFT 的布尔值
     */
    function directOwnerOf(uint256 tokenId)
        external
        view
        returns (
            address,
            uint256,
            bool
        );

    /**
     * @notice 用于销毁给定的代币。
     * @dev 当一个代币被销毁时，它的所有子代币也会被递归销毁。
     * @dev 当指定最大递归销毁时，如果还有更多的子代币要销毁，则执行必须回滚。
     * @dev 将 `maxRecursiveBurn` 值设置为 0 应该只尝试销毁指定的代币，并且如果
     *  存在任何子代币，则必须回滚。
     * @param tokenId 要销毁的代币的 ID
     * @param maxRecursiveBurns 要递归销毁的最大代币数
     * @return uint256 递归销毁的子代币数
     */
    function burn(uint256 tokenId, uint256 maxRecursiveBurns)
        external
        returns (uint256);

    /**
     * @notice 用于将子代币添加到给定的父代币。
     * @dev 这会将子代币添加到给定父代币的待处理子代币数组中。
     * @dev 目标代币不得是被转移的代币或其下游子代币的子代币。
     * @dev 此方法不得直接调用。它只能作为 `IERC6059` 实例的一部分调用，
     `nestTransfer` 或 `transferChild` 到一个 NFT。
     * @dev 要求：
     *
     *  - 子合约上的 `directOwnerOf` 必须解析为被调用的合约。
     *  - 父合约的待处理数组不得已满。
     * @param parentId 接收新子代币的父代币的 ID
     * @param childId 新提议的子代币的 ID
     */
    function addChild(uint256 parentId, uint256 childId) external;

    /**
     * @notice 用于接受给定父代币的待处理子代币。
     * @dev 这会将子代币从父代币的待处理子代币数组移动到活动子代币
     *  数组中。
     * @param parentId 为其接受子代币的父代币的 ID
     * @param childIndex 在给定代币的待处理子代币数组中要接受的子代币的索引
     * @param childAddress 预期位于指定索引处的子代币的集合智能合约的地址
     * @param childId 预期位于指定索引处的子代币的 ID
     */
    function acceptChild(
        uint256 parentId,
        uint256 childIndex,
        address childAddress,
        uint256 childId
    ) external;

    /**
     * @notice 用于拒绝给定父代币的所有待处理子代币。
     * @dev 从 pending 数组映射中移除子代币。
     * @dev 子代币的所有权结构不会更新。
     * @dev 要求：
     *
     * - `parentId` 必须存在
     * @param parentId 要为其拒绝所有待处理代币的父代币的 ID
     * @param maxRejections 预期要拒绝的最大子代币数，用于防止拒绝
     *  刚好在此操作之前到达的子代币。
     */
    function rejectAllChildren(uint256 parentId, uint256 maxRejections) external;

    /**
     * @notice 用于从给定父代币转移子代币。
     * @dev 必须从父代的活动或待处理子代币中移除该子代币。
     * @dev 当转移子代币时，代币的所有者必须设置为 `to`，或者在 `to` 的情况下不更新
     *  是 `0x0` 地址。
     * @param tokenId 要从中转移子代币的父代币的 ID
     * @param to 要将代币转移到的地址
     * @param destinationId 接收此子代币的代币的 ID（如果目的地不是代币，则必须为 0）
     * @param childIndex 我们正在转移的代币的索引，在其所属的数组中（可以是活动数组或
     *  待处理数组）
     * @param childAddress 子代币的集合智能合约的地址
     * @param childId 子代币在其自己的集合智能合约中的 ID
     * @param isPending 一个布尔值，指示被转移的子代币是否在父代币的待处理数组中
     *  (`true`) 或在活动数组中 (`false`)
     * @param data 没有指定格式的附加数据，在调用 `to` 时发送
     */
    function transferChild(
        uint256 tokenId,
        address to,
        uint256 destinationId,
        uint256 childIndex,
        address childAddress,
        uint256 childId,
        bool isPending,
        bytes data
    ) external;

    /**
     * @notice 用于检索给定父代币的活动子代币。
     * @dev 返回父代币存在的 Child 结构体数组。
     * @dev Child 结构体由以下值组成：
     *  [
     *      tokenId,
     *      contractAddress
     *  ]
     * @param parentId 要为其检索活动子代币的父代币的 ID
     * @return struct[] 包含父代币的活动子代币的 Child 结构体数组
     */
    function childrenOf(uint256 parentId)
        external
        view
        returns (Child[] memory);

    /**
     * @notice 用于检索给定父代币的待处理子代币。
     * @dev 返回给定父代币存在的待处理 Child 结构体数组。
     * @dev Child 结构体由以下值组成：
     *  [
     *      tokenId,
     *      contractAddress
     *  ]
     * @param parentId 要为其检索待处理子代币的父代币的 ID
     * @return struct[] 包含父代币的待处理子代币的 Child 结构体数组
     */
    function pendingChildrenOf(uint256 parentId)
        external
        view
        returns (Child[] memory);

    /**
     * @notice 用于检索给定父代币的特定活动子代币。
     * @dev 返回位于父代币的活动子代币数组的 `index` 处的单个 Child 结构体。
     * @dev Child 结构体由以下值组成：
     *  [
     *      tokenId,
     *      contractAddress
     *  ]
     * @param parentId 要为其检索子代币的父代币的 ID
     * @param index 子代币在父代币的活动子代币数组中的索引
     * @return struct 包含有关指定子代币数据的 Child 结构体
     */
    function childOf(uint256 parentId, uint256 index)
        external
        view
        returns (Child memory);

    /**
     * @notice 用于从给定父代币检索特定待处理子代币。
     * @dev 返回位于父代币的活动子代币数组的 `index` 处的单个 Child 结构体。
     * @dev Child 结构体由以下值组成：
     *  [
     *      tokenId,
     *      contractAddress
     *  ]
     * @param parentId 要为其检索待处理子代币的父代币的 ID
     * @param index 子代币在父代币的待处理子代币数组中的索引
     * @return struct 包含有关指定子代币数据的 Child 结构体
     */
    function pendingChildOf(uint256 parentId, uint256 index)
        external
        view
        returns (Child memory);

    /**
     * @notice 用于将代币转移到另一个代币中。
     * @dev 目标代币不得是被转移的代币或其下游子代币的子代币。
     * @param from 要转移的代币的直接所有者的地址
     * @param to 接收代币的代币的集合智能合约的地址
     * @param tokenId 要转移的代币的 ID
     * @param destinationId 接收被转移的代币的代币的 ID
     */
    function nestTransferFrom(
        address from,
        address to,
        uint256 tokenId,
        uint256 destinationId
    ) external;
}

    function transferChild(
        uint256 tokenId,
        address to,
        uint256 destinationId,
        uint256 childIndex,
        address childAddress,
        uint256 childId,
        bool isPending,
        bytes data
    ) external;