ERC-7589: 半同质化代币角色

/// @title ERC-7589 半同质化代币角色
/// @dev 见 https://eips.ethereum.org/EIPS/eip-7589
/// 注意：此接口的 ERC-165 标识符是 0xc4c8a71d。
interface IERC7589 /* is IERC165 */ {

    /** 事件 **/

    /// @notice 当代币被提交（存入或冻结）时发出。
    /// @param _grantor SFT 的所有者。
    /// @param _commitmentId 创建的承诺的标识符。
    /// @param _tokenAddress 代币地址。
    /// @param _tokenId 代币标识符。
    /// @param _tokenAmount 代币数量。
    event TokensCommitted(
        address indexed _grantor,
        uint256 indexed _commitmentId,
        address indexed _tokenAddress,
        uint256 _tokenId,
        uint256 _tokenAmount
    );

    /// @notice 当角色被授予时发出。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色的接收者。
    /// @param _expirationDate 角色的到期日期。
    /// @param _revocable 该角色是否可撤销。
    /// @param _data 关于角色的任何其他数据。
    event RoleGranted(
        uint256 indexed _commitmentId,
        bytes32 indexed _role,
        address indexed _grantee,
        uint64 _expirationDate,
        bool _revocable,
        bytes _data
    );

    /// @notice 当角色被撤销时发出。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色撤销的接收者。
    event RoleRevoked(uint256 indexed _commitmentId, bytes32 indexed _role, address indexed _grantee);

    /// @notice 当用户从承诺中释放代币时发出。
    /// @param _commitmentId 承诺标识符。
    event TokensReleased(uint256 indexed _commitmentId);

    /// @notice 当用户被批准代表另一个用户管理角色时发出。
    /// @param _tokenAddress 代币地址。
    /// @param _operator 被批准授予和撤销角色的用户。
    /// @param _isApproved 批准状态。
    event RoleApprovalForAll(address indexed _tokenAddress, address indexed _operator, bool _isApproved);

    /** 外部函数 **/

    /// @notice 提交代币（在合约上存入或冻结余额）。
    /// @param _grantor SFT 的所有者。
    /// @param _tokenAddress 代币地址。
    /// @param _tokenId 代币标识符。
    /// @param _tokenAmount 代币数量。
    /// @return commitmentId_ 创建的承诺的唯一标识符。
    function commitTokens(
        address _grantor,
        address _tokenAddress,
        uint256 _tokenId,
        uint256 _tokenAmount
    ) external returns (uint256 commitmentId_);

    /// @notice 将角色授予 `_grantee`。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色的接收者。
    /// @param _expirationDate 角色的到期日期。
    /// @param _revocable 该角色是否可撤销。
    /// @param _data 关于角色的任何其他数据。
    function grantRole(
        uint256 _commitmentId,
        bytes32 _role,
        address _grantee,
        uint64 _expirationDate,
        bool _revocable,
        bytes calldata _data
    ) external;

    /// @notice 撤销角色。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色撤销的接收者。
    function revokeRole(uint256 _commitmentId, bytes32 _role, address _grantee) external;

    /// @notice 将代币释放回授予者。
    /// @param _commitmentId 承诺标识符。
    function releaseTokens(uint256 _commitmentId) external;

    /// @notice 批准操作员代表另一个用户授予和撤销角色。
    /// @param _tokenAddress 代币地址。
    /// @param _operator 被批准授予和撤销角色的用户。
    /// @param _approved 批准状态。
    function setRoleApprovalForAll(address _tokenAddress, address _operator, bool _approved) external;

    /** 视图函数 **/

    /// @notice 返回 承诺的所有者（授予者）。
    /// @param _commitmentId 承诺标识符。
    /// @return grantor_ 承诺所有者。
    function grantorOf(uint256 _commitmentId) external view returns (address grantor_);

    /// @notice 返回已提交的代币的地址。
    /// @param _commitmentId 承诺标识符。
    /// @return tokenAddress_ 代币地址。
    function tokenAddressOf(uint256 _commitmentId) external view returns (address tokenAddress_);

    /// @notice 返回已提交的代币的标识符。
    /// @param _commitmentId 承诺标识符。
    /// @return tokenId_ 代币标识符。
    function tokenIdOf(uint256 _commitmentId) external view returns (uint256 tokenId_);

    /// @notice 返回已提交的代币数量。
    /// @param _commitmentId 承诺标识符。
    /// @return tokenAmount_ 代币数量。
    function tokenAmountOf(uint256 _commitmentId) external view returns (uint256 tokenAmount_);

    /// @notice 返回角色分配的自定义数据。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色的接收者。
    /// @return data_ 自定义数据。
    function roleData(
        uint256 _commitmentId,
        bytes32 _role,
        address _grantee
    ) external view returns (bytes memory data_);

    /// @notice 返回角色分配的到期日期。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色的接收者。
    /// @return expirationDate_ 到期日期。
    function roleExpirationDate(
        uint256 _commitmentId,
        bytes32 _role,
        address _grantee
    ) external view returns (uint64 expirationDate_);

    /// @notice 返回角色分配的到期日期。
    /// @param _commitmentId 承诺标识符。
    /// @param _role 角色标识符。
    /// @param _grantee 角色的接收者。
    /// @return revocable_ 该角色是否可撤销。
    function isRoleRevocable(
        uint256 _commitmentId,
        bytes32 _role,
        address _grantee
    ) external view returns (bool revocable_);

    /// @notice 检查授予者是否批准了所有 SFT 的操作员。
    /// @param _tokenAddress 代币地址。
    /// @param _grantor 批准操作员的用户。
    /// @param _operator 可以授予和撤销角色的用户。
    /// @return isApproved_ 操作员是否被批准。
    function isRoleApprovedForAll(
        address _tokenAddress,
        address _grantor,
        address _operator
    ) external view returns (bool isApproved_);
}

/// @title ERC-7589 半同质化代币角色，可选的单笔交易扩展
/// @dev 见 https://eips.ethereum.org/EIPS/eip-7589
/// 注意：此接口的 ERC-165 标识符是 0x5c3d7d74。
interface ICommitTokensAndGrantRoleExtension /* is IERC7589 */ {
    /// @notice 在单笔交易中提交代币并授予角色。
    /// @param _grantor SFT 的所有者。
    /// @param _tokenAddress 代币地址。
    /// @param _tokenId 代币标识符。
    /// @param _tokenAmount 代币数量。
    /// @param _role 角色标识符。
    /// @param _grantee 角色的接收者。
    /// @param _expirationDate 角色的到期日期。
    /// @param _revocable 该角色是否可撤销。
    /// @param _data 关于角色的任何其他数据。
    /// @return commitmentId_ 创建的承诺的标识符。
    function commitTokensAndGrantRole(
        address _grantor,
        address _tokenAddress,
        uint256 _tokenId,
        uint256 _tokenAmount,
        bytes32 _role,
        address _grantee,
        uint64 _expirationDate,
        bool _revocable,
        bytes calldata _data
    ) external returns (uint256 commitmentId_);
}

/// @title ERC-7589 半同质化代币角色，可选的角色余额扩展
/// @dev 见 https://eips.ethereum.org/EIPS/eip-7589
/// 注意：此接口的 ERC-165 标识符是 0x2f35b73f。
interface IRoleBalanceOfExtension /* is IERC7589 */ {
    /// @notice 返回授予被授予者给定角色的所有 tokenAmounts 的总和。
    /// @param _role 角色标识符。
    /// @param _tokenAddress 代币地址。
    /// @param _tokenId 代币标识符。
    /// @param _grantee 返回余额的用户。
    /// @return balance_ 被授予者给定角色的余额。
    function roleBalanceOf(
        bytes32 _role,
        address _tokenAddress,
        uint256 _tokenId,
        address _grantee
    ) external returns (uint256 balance_);
}