ERC-5773: 上下文相关的多资产代币

/// @title ERC-5773 上下文相关的多资产代币
/// @dev 请参阅 https://eips.ethereum.org/EIPS/eip-5773
/// @dev 注意：此接口的 ERC-165 标识符为 0x06b4329a。

pragma solidity ^0.8.16;

interface IERC5773 /* is ERC165 */ {
    /**
     * @notice 用于通知监听器在 `assetId` 处初始化了一个资产对象。
     * @param assetId 已初始化的资产的 ID
     */
    event AssetSet(uint64 assetId);

    /**
     * @notice 用于通知监听器 `assetId` 处的资产对象已添加到代币的待处理资产数组中。
     * @param tokenIds 接收到新待处理资产的代币的 ID 数组
     * @param assetId 已添加到代币的待处理资产数组的资产的 ID
     * @param replacesId 将被替换的资产的 ID
     */
    event AssetAddedToTokens(
        uint256[] tokenIds,
        uint64 indexed assetId,
        uint64 indexed replacesId
    );

    /**
     * @notice 用于通知监听器 `assetId` 处的资产对象已被代币接受，并从代币的待处理资产数组迁移到代币的活动资产数组。
     * @param tokenId 接受了新资产的代币的 ID
     * @param assetId 已接受的资产的 ID
     * @param replacesId 已替换的资产的 ID
     */
    event AssetAccepted(
        uint256 indexed tokenId,
        uint64 indexed assetId,
        uint64 indexed replacesId
    );

    /**
     * @notice 用于通知监听器 `assetId` 处的资产对象已从代币中拒绝，并从代币的待处理资产数组中删除。
     * @param tokenId 拒绝了资产的代币的 ID
     * @param assetId 已拒绝的资产的 ID
     */
    event AssetRejected(uint256 indexed tokenId, uint64 indexed assetId);

    /**
     * @notice 用于通知监听器代币的优先级数组已重新排序。
     * @param tokenId 更新了资产优先级数组的代币的 ID
     */
    event AssetPrioritySet(uint256 indexed tokenId);

    /**
     * @notice 用于通知监听器所有者已授予用户管理给定代币的资产的权限。
     * @dev 转移时必须清除批准
     * @param owner 已授予所有代币资产批准的帐户的地址
     * @param approved 已被授予管理代币资产的批准的帐户的地址
     * @param tokenId 授予批准的代币的 ID
     */
    event ApprovalForAssets(
        address indexed owner,
        address indexed approved,
        uint256 indexed tokenId
    );

    /**
     * @notice 用于通知监听器所有者已授予用户管理其所有代币的资产的权限。
     * @param owner 已授予管理其所有代币上所有资产的批准的帐户的地址
     * @param operator 已被授予管理所有代币的代币资产的批准的帐户的地址
     * @param approved 一个布尔值，表示是否已授予 (`true`) 或撤销 (`false`) 权限
     */
    event ApprovalForAllForAssets(
        address indexed owner,
        address indexed operator,
        bool approved
    );

    /**
     * @notice 接受给定代币的待处理数组中的资产。
     * @dev 将资产从代币的待处理资产数组迁移到代币的活动资产数组。
     * @dev 活动资产不能被任何人删除，但可以被新资产替换。
     * @dev 要求：
     *
     *  - 调用者必须拥有代币或被批准管理代币的资产
     *  - `tokenId` 必须存在。
     *  - `index` 必须在待处理资产数组长度的范围内。
     * @dev 发出 {AssetAccepted} 事件。
     * @param tokenId 要接受待处理资产的代币的 ID
     * @param index 要接受的待处理数组中资产的索引
     * @param assetId 预期在索引中的资产的 ID
     */
    function acceptAsset(
        uint256 tokenId,
        uint256 index,
        uint64 assetId
    ) external;

    /**
     * @notice 从给定代币的待处理数组中拒绝资产。
     * @dev 从代币的待处理资产数组中删除资产。
     * @dev 要求：
     *
     *  - 调用者必须拥有代币或被批准管理代币的资产
     *  - `tokenId` 必须存在。
     *  - `index` 必须在待处理资产数组长度的范围内。
     * @dev 发出 {AssetRejected} 事件。
     * @param tokenId 资产被拒绝的代币的 ID
     * @param index 要拒绝的待处理数组中资产的索引
     * @param assetId 预期在索引中的资产的 ID
     */
    function rejectAsset(
        uint256 tokenId,
        uint256 index,
        uint64 assetId
    ) external;

    /**
     * @notice 拒绝来自给定代币的待处理数组的所有资产。
     * @dev 有效地删除待处理数组。
     * @dev 要求：
     *
     *  - 调用者必须拥有代币或被批准管理代币的资产
     *  - `tokenId` 必须存在。
     * @dev 发出 assetId = 0 的 {AssetRejected} 事件。
     * @param tokenId 要清除其待处理数组的代币的 ID
     * @param maxRejections 防止拒绝在此操作之前到达的资产。
     */
    function rejectAllAssets(uint256 tokenId, uint256 maxRejections) external;

    /**
     * @notice 为给定代币设置新的优先级数组。
     * @dev 优先级数组是一个非顺序的 `uint16` 列表，其中最低的值被认为是最高优先级。
     * @dev 优先级的值 `0` 是一种特殊情况，等同于未初始化。
     * @dev 要求：
     *
     *  - 调用者必须拥有代币或被批准管理代币的资产
     *  - `tokenId` 必须存在。
     *  - `priorities` 的长度必须等于活动资产数组的长度。
     * @dev 发出 {AssetPrioritySet} 事件。
     * @param tokenId 要设置优先级的代币的 ID
     * @param priorities 活动资产的优先级数组。优先级数组中项目的顺序与活动数组中项目的顺序匹配
     */
    function setPriority(uint256 tokenId, uint64[] calldata priorities)
        external;

    /**
     * @notice 用于检索给定代币的活动资产的 ID。
     * @dev 资产数据通过引用存储，为了访问与 ID 对应的数据，调用 `getAssetMetadata(tokenId, assetId)`。
     * @dev 你可以安全地获得 1 万
     * @param tokenId 要检索活动资产的 ID 的代币的 ID
     * @return uint64[] 给定代币的活动资产 ID 的数组
     */
    function getActiveAssets(uint256 tokenId)
        external
        view
        returns (uint64[] memory);

    /**
     * @notice 用于检索给定代币的待处理资产的 ID。
     * @dev 资产数据通过引用存储，为了访问与 ID 对应的数据，调用 `getAssetMetadata(tokenId, assetId)`。
     * @param tokenId 要检索待处理资产的 ID 的代币的 ID
     * @return uint64[] 给定代币的待处理资产 ID 的数组
     */
    function getPendingAssets(uint256 tokenId)
        external
        view
        returns (uint64[] memory);

    /**
     * @notice 用于检索给定代币的活动资产的优先级。
     * @dev 资产优先级是一个非顺序的 uint16 值数组，数组大小等于活动资产优先级。
     * @param tokenId 要检索活动资产的优先级的代币的 ID
     * @return uint16[] 给定代币的活动资产的优先级数组
     */
    function getActiveAssetPriorities(uint256 tokenId)
        external
        view
        returns (uint64[] memory);

    /**
     * @notice 用于检索如果接受来自代币的待处理数组的给定资产将被替换的资产。
     * @dev 资产数据通过引用存储，为了访问与 ID 对应的数据，调用 `getAssetMetadata(tokenId, assetId)`。
     * @param tokenId 要检查的代币的 ID
     * @param newAssetId 将被接受的待处理资产的 ID
     * @return uint64 将被替换的资产的 ID
     */
    function getAssetReplacements(uint256 tokenId, uint64 newAssetId)
        external
        view
        returns (uint64);

    /**
     * @notice 用于获取指定代币的具有给定索引的活动资产的资产元数据。
     * @dev 可以覆盖以实现枚举、回退或其他自定义逻辑。
     * @param tokenId 从中检索资产元数据的代币的 ID
     * @param assetId 资产 ID，必须在活动资产数组中
     * @return string 属于代币的活动资产数组中指定索引的资产的元数据
     */
    function getAssetMetadata(uint256 tokenId, uint64 assetId)
        external
        view
        returns (string memory);

    /**
     * @notice 用于授予用户管理代币资产的权限。
     * @dev 这与转移批准不同，因为当批准方接受或拒绝资产或设置资产优先级时，不会清除批准。此批准在代币转移时清除。
     * @dev 一次只能批准一个帐户，因此批准 `0x0` 地址会清除之前的批准。
     * @dev 要求：
     *
     *  - 调用者必须拥有代币或是一个批准的 operator。
     *  - `tokenId` 必须存在。
     * @dev 发出 {ApprovalForAssets} 事件。
     * @param to 要授予批准的帐户的地址
     * @param tokenId 授予管理资产批准的代币的 ID
     */
    function approveForAssets(address to, uint256 tokenId) external;

    /**
     * @notice 用于检索被批准管理给定代币的资产的帐户的地址。
     * @dev 要求：
     *
     *  - `tokenId` 必须存在。
     * @param tokenId 要检索批准地址的代币的 ID
     * @return address 被批准管理指定代币的资产的帐户的地址
     */
    function getApprovedForAssets(uint256 tokenId)
        external
        view
        returns (address);

    /**
     * @notice 用于为调用者添加或删除资产的 operator。
     * @dev Operators 可以为调用者拥有的任何代币调用 {acceptAsset}、{rejectAsset}、{rejectAllAssets} 或 {setPriority}。
     * @dev 要求：
     *
     *  - `operator` 不能是调用者。
     * @dev 发出 {ApprovalForAllForAssets} 事件。
     * @param operator 要向其授予或撤销 operator 角色的帐户的地址
     * @param approved 指示是授予 (`true`) 还是撤销 (`false`) operator 角色的布尔值
     */
    function setApprovalForAllForAssets(address operator, bool approved)
        external;

    /**
     * @notice 用于检查地址是否已被给定地址授予 operator 角色。
     * @dev 请参阅 {setApprovalForAllForAssets}。
     * @param owner 我们正在检查是否已授予 operator 角色的帐户的地址
     * @param operator 我们正在检查是否具有 operator 角色的帐户的地址
     * @return bool 指示我们正在检查的帐户是否已被授予 operator 角色的布尔值
     */
    function isApprovedForAllForAssets(address owner, address operator)
        external
        view
        returns (bool);
}