ERC-3525: 半同质化代币

pragma solidity ^0.8.0;

/**
 * @title ERC-3525 Semi-Fungible Token Standard, optional extension for slot enumeration
 * @dev Interfaces for any contract that wants to support enumeration of slots as well as tokens 
 *  with the same slot.
 *  用于任何想要支持枚举 slot 以及具有相同 slot 的代币的合约的接口。
 * Note: the ERC-165 identifier for this interface is 0x3b741b9e.
 */
interface IERC3525SlotEnumerable is IERC3525 /* , IERC721Enumerable */ {

    /**
     * @notice Get the total amount of slots stored by the contract.
     *  获取合约存储的 slot 总数。
     * @return The total amount of slots
     */
    function slotCount() external view returns (uint256);

    /**
     * @notice Get the slot at the specified index of all slots stored by the contract.
     *  获取合约存储的所有 slot 中指定索引处的 slot。
     * @param _index The index in the slot list
     * @return The slot at `index` of all slots.
     */
    function slotByIndex(uint256 _index) external view returns (uint256);

    /**
     * @notice Get the total amount of tokens with the same slot.
     *  获取具有相同 slot 的代币总数。
     * @param _slot The slot to query token supply for
     * @return The total amount of tokens with the specified `_slot`
     */
    function tokenSupplyInSlot(uint256 _slot) external view returns (uint256);

    /**
     * @notice Get the token at the specified index of all tokens with the same slot.
     *  获取具有相同 slot 的所有代币中指定索引处的代币。
     * @param _slot The slot to query tokens with
     * @param _index The index in the token list of the slot
     * @return The token ID at `_index` of all tokens with `_slot`
     */
    function tokenInSlotByIndex(uint256 _slot, uint256 _index) external view returns (uint256);
}

pragma solidity ^0.8.0;

/**
 * @title ERC-3525 Semi-Fungible Token Standard, optional extension for approval of slot level
 * @dev Interfaces for any contract that wants to support approval of slot level, which allows an
 *  operator to manage one's tokens with the same slot.
 *  用于任何想要支持 slot 级别授权的合约的接口，该授权允许 operator 管理一个人具有相同 slot 的代币。
 *  See https://eips.ethereum.org/EIPS/eip-3525
 * Note: the ERC-165 identifier for this interface is 0xb688be58.
 */
interface IERC3525SlotApprovable is IERC3525 {
    /**
     * @dev MUST emit when an operator is approved or disapproved to manage all of `_owner`'s
     *  tokens with the same slot.
     *  当批准或不批准 operator 管理所有 `_owner` 的具有相同 slot 的代币时，必须发出此事件。
     * @param _owner The address whose tokens are approved
     * @param _slot The slot to approve, all of `_owner`'s tokens with this slot are approved
     * @param _operator The operator being approved or disapproved
     * @param _approved Identify if `_operator` is approved or disapproved
     */
    event ApprovalForSlot(address indexed _owner, uint256 indexed _slot, address indexed _operator, bool _approved);

    /**
     * @notice Approve or disapprove an operator to manage all of `_owner`'s tokens with the
     *  specified slot.
     *  批准或不批准 operator 管理所有 `_owner` 的具有指定 slot 的代币。
     * @dev Caller SHOULD be `_owner` or an operator who has been authorized through
     *  `setApprovalForAll`.
     *  调用者应该是 `_owner` 或已通过 `setApprovalForAll` 授权的 operator。
     *  MUST emit ApprovalSlot event.
     *  必须发出 ApprovalSlot 事件。
     * @param _owner The address that owns the ERC-3525 tokens
     * @param _slot The slot of tokens being queried approval of
     * @param _operator The address for whom to query approval
     * @param _approved Identify if `_operator` would be approved or disapproved
     */
    function setApprovalForSlot(
        address _owner,
        uint256 _slot,
        address _operator,
        bool _approved
    ) external payable;

    /**
     * @notice Query if `_operator` is authorized to manage all of `_owner`'s tokens with the
     *  specified slot.
     *  查询 `_operator` 是否被授权管理所有 `_owner` 的具有指定 slot 的代币。
     * @param _owner The address that owns the ERC-3525 tokens
     * @param _slot The slot of tokens being queried approval of
     * @param _operator The address for whom to query approval
     * @return True if `_operator` is authorized to manage all of `_owner`'s tokens with `_slot`,
     *  false otherwise.
     *  如果 `_operator` 被授权管理所有 `_owner` 的具有 `_slot` 的代币，则为 True，否则为 False。
     */
    function isApprovedForSlot(
        address _owner,
        uint256 _slot,
        address _operator
    ) external view returns (bool);
}

pragma solidity ^0.8.0;

/**
 * @title ERC-3525 Semi-Fungible Token Standard
 * Note: the ERC-165 identifier for this interface is 0xd5358140.
 */
interface IERC3525 /* is IERC165, IERC721 */ {
    /**
     * @dev MUST emit when value of a token is transferred to another token with the same slot,
     *  including zero value transfers (_value == 0) as well as transfers when tokens are created
     *  (`_fromTokenId` == 0) or destroyed (`_toTokenId` == 0).
     *  当一个代币的 value 被转移到另一个具有相同 slot 的代币时，必须发出此事件
     *  包括零 value 转移 (_value == 0) 以及创建代币时 (`_fromTokenId` == 0) 或销毁代币时 (`_toTokenId` == 0) 的转移。
     * @param _fromTokenId The token id to transfer value from
     * @param _toTokenId The token id to transfer value to
     * @param _value The transferred value
     */
    event TransferValue(uint256 indexed _fromTokenId, uint256 indexed _toTokenId, uint256 _value);

    /**
     * @dev MUST emit when the approval value of a token is set or changed.
     *  当一个代币的授权 value 被设置或更改时，必须发出此事件。
     * @param _tokenId The token to approve
     * @param _operator The operator to approve for
     * @param _value The maximum value that `_operator` is allowed to manage
     */
    event ApprovalValue(uint256 indexed _tokenId, address indexed _operator, uint256 _value);
    
    /**
     * @dev MUST emit when the slot of a token is set or changed.
     *  当一个代币的 slot 被设置或更改时，必须发出此事件。
     * @param _tokenId The token of which slot is set or changed
     * @param _oldSlot The previous slot of the token
     * @param _newSlot The updated slot of the token
     */ 
    event SlotChanged(uint256 indexed _tokenId, uint256 indexed _oldSlot, uint256 indexed _newSlot);

    /**
     * @notice Get the number of decimals the token uses for value - e.g. 6, means the user
     *  representation of the value of a token can be calculated by dividing it by 1,000,000.
     *  获取代币用于 value 的小数位数 - 例如，6 表示可以通过将代币 value 除以 1,000,000 来计算代币 value 的用户表示形式。
     *  Considering the compatibility with third-party wallets, this function is defined as
     *  `valueDecimals()` instead of `decimals()` to avoid conflict with ERC-20 tokens.
     *  考虑到与第三方钱包的兼容性，此函数定义为 `valueDecimals()` 而不是 `decimals()`，以避免与 ERC-20 代币冲突。
     * @return The number of decimals for value
     */
    function valueDecimals() external view returns (uint8);

    /**
     * @notice Get the value of a token.
     *  获取代币的 value。
     * @param _tokenId The token for which to query the balance
     * @return The value of `_tokenId`
     */
    function balanceOf(uint256 _tokenId) external view returns (uint256);

    /**
     * @notice Get the slot of a token.
     *  获取代币的 slot。
     * @param _tokenId The identifier for a token
     * @return The slot of the token
     */
    function slotOf(uint256 _tokenId) external view returns (uint256);

    /**
     * @notice Allow an operator to manage the value of a token, up to the `_value`.
     *  允许 operator 管理代币的 value，最高可达 `_value`。
     * @dev MUST revert unless caller is the current owner, an authorized operator, or the approved
     *  address for `_tokenId`.
     *  除非调用者是当前所有者、授权的 operator 或 `_tokenId` 的授权地址，否则必须回退。
     *  MUST emit the ApprovalValue event.
     *  必须发出 ApprovalValue 事件。
     * @param _tokenId The token to approve
     * @param _operator The operator to be approved
     * @param _value The maximum value of `_toTokenId` that `_operator` is allowed to manage
     */
    function approve(
        uint256 _tokenId,
        address _operator,
        uint256 _value
    ) external payable;

    /**
     * @notice Get the maximum value of a token that an operator is allowed to manage.
     *  获取 operator 允许管理的一个代币的最大 value。
     * @param _tokenId The token for which to query the allowance
     * @param _operator The address of an operator
     * @return The current approval value of `_tokenId` that `_operator` is allowed to manage
     */
    function allowance(uint256 _tokenId, address _operator) external view returns (uint256);

    /**
     * @notice Transfer value from a specified token to another specified token with the same slot.
     *  将 value 从指定的代币转移到另一个具有相同 slot 的指定代币。
     * @dev Caller MUST be the current owner, an authorized operator or an operator who has been
     *  approved the whole `_fromTokenId` or part of it.
     *  调用者必须是 `_fromTokenId` 的当前所有者、授权的 operator 或已被授权全部 `_fromTokenId` 或其中一部分的 operator。
     *  MUST revert if `_fromTokenId` or `_toTokenId` is zero token id or does not exist.
     *  如果 `_fromTokenId` 或 `_toTokenId` 为零代币 id 或不存在，则必须回退。
     *  MUST revert if slots of `_fromTokenId` and `_toTokenId` do not match.
     *  如果 `_fromTokenId` 和 `_toTokenId` 的 slot 不匹配，则必须回退。
     *  MUST revert if `_value` exceeds the balance of `_fromTokenId` or its allowance to the
     *  operator.
     *  如果 `_value` 超过 `_fromTokenId` 的余额或其对 operator 的授权，则必须回退。
     *  MUST emit `TransferValue` event.
     *  必须发出 `TransferValue` 事件。
     * @param _fromTokenId The token to transfer value from
     * @param _toTokenId The token to transfer value to
     * @param _value The transferred value
     */
    function transferFrom(
        uint256 _fromTokenId,
        uint256 _toTokenId,
        uint256 _value
    ) external payable;


    /**
     * @notice Transfer value from a specified token to an address. The caller should confirm that
     *  `_to` is capable of receiving ERC-3525 tokens.
     *  将 value 从指定的代币转移到一个地址。调用者应确认 `_to` 能够接收 ERC-3525 代币。
     * @dev This function MUST create a new ERC-3525 token with the same slot for `_to`, 
     *  or find an existing token with the same slot owned by `_to`, to receive the transferred value.
     *  此函数必须为 `_to` 创建一个具有相同 slot 的新 ERC-3525 代币，或者找到一个 `_to` 拥有的具有相同 slot 的现有代币，以接收转移的 value。
     *  MUST revert if `_fromTokenId` is zero token id or does not exist.
     *  如果 `_fromTokenId` 为零代币 id 或不存在，则必须回退。
     *  MUST revert if `_to` is zero address.
     *  如果 `_to` 为零地址，则必须回退。
     *  MUST revert if `_value` exceeds the balance of `_fromTokenId` or its allowance to the
     *  operator.
     *  如果 `_value` 超过 `_fromTokenId` 的余额或其对 operator 的授权，则必须回退。
     *  MUST emit `Transfer` and `TransferValue` events.
     *  必须发出 `Transfer` 和 `TransferValue` 事件。
     * @param _fromTokenId The token to transfer value from
     * @param _to The address to transfer value to
     * @param _value The transferred value
     * @return ID of the token which receives the transferred value
     */
    function transferFrom(
        uint256 _fromTokenId,
        address _to,
        uint256 _value
    ) external payable returns (uint256);
}

pragma solidity ^0.8.0;

/**
 * @title ERC-3525 Semi-Fungible Token Standard, optional extension for slot enumeration
 * @dev Interfaces for any contract that wants to support enumeration of slots as well as tokens 
 *  with the same slot.
 *  用于任何想要支持枚举 slot 以及具有相同 slot 的代币的合约的接口。
 * Note: the ERC-165 identifier for this interface is 0x3b741b9e.
 */
interface IERC3525SlotEnumerable is IERC3525 /* , IERC721Enumerable */ {

    /**
     * @notice Get the total amount of slots stored by the contract.
     *  获取合约存储的 slot 总数。
     * @return The total amount of slots
     */
    function slotCount() external view returns (uint256);

    /**
     * @notice Get the slot at the specified index of all slots stored by the contract.
     *  获取合约存储的所有 slot 中指定索引处的 slot。
     * @param _index The index in the slot list
     * @return The slot at `index` of all slots.
     */
    function slotByIndex(uint256 _index) external view returns (uint256);

    /**
     * @notice Get the total amount of tokens with the same slot.
     *  获取具有相同 slot 的代币总数。
     * @param _slot The slot to query token supply for
     * @return The total amount of tokens with the specified `_slot`
     */
    function tokenSupplyInSlot(uint256 _slot) external view returns (uint256);

    /**
     * @notice Get the token at the specified index of all tokens with the same slot.
     *  获取具有相同 slot 的所有代币中指定索引处的代币。
     * @param _slot The slot to query tokens with
     * @param _index The index in the token list of the slot
     * @return The token ID at `_index` of all tokens with `_slot`
     */
    function tokenInSlotByIndex(uint256 _slot, uint256 _index) external view returns (uint256);
}

pragma solidity ^0.8.0;

/**
 * @title ERC-3525 Semi-Fungible Token Standard, optional extension for approval of slot level
 * @dev Interfaces for any contract that wants to support approval of slot level, which allows an
 *  operator to manage one's tokens with the same slot.
 *  用于任何想要支持 slot 级别授权的合约的接口，该授权允许 operator 管理一个人具有相同 slot 的代币。
 *  See https://eips.ethereum.org/EIPS/eip-3525
 * Note: the ERC-165 identifier for this interface is 0xb688be58.
 */
interface IERC3525SlotApprovable is IERC3525 {
    /**
     * @dev MUST emit when an operator is approved or disapproved to manage all of `_owner`'s
     *  tokens with the same slot.
     *  当批准或不批准 operator 管理所有 `_owner` 的具有相同 slot 的代币时，必须发出此事件。
     * @param _owner The address whose tokens are approved
     * @param _slot The slot to approve, all of `_owner`'s tokens with this slot are approved
     * @param _operator The operator being approved or disapproved
     * @param _approved Identify if `_operator` is approved or disapproved
     */
    event ApprovalForSlot(address indexed _owner, uint256 indexed _slot, address indexed _operator, bool _approved);

    /**
     * @notice Approve or disapprove an operator to manage all of `_owner`'s tokens with the
     *  specified slot.
     *  批准或不批准 operator 管理所有 `_owner` 的具有指定 slot 的代币。
     * @dev Caller SHOULD be `_owner` or an operator who has been authorized through
     *  `setApprovalForAll`.
     *  调用者应该是 `_owner` 或已通过 `setApprovalForAll` 授权的 operator。
     *  MUST emit ApprovalSlot event.
     *  必须发出 ApprovalSlot 事件。
     * @param _owner The address that owns the ERC-3525 tokens
     * @param _slot The slot of tokens being queried approval of
     * @param _operator The address for whom to query approval
     * @param _approved Identify if `_operator` would be approved or disapproved
     */
    function setApprovalForSlot(
        address _owner,
        uint256 _slot,
        address _operator,
        bool _approved
    ) external payable;

    /**
     * @notice Query if `_operator` is authorized to manage all of `_owner`'s tokens with the
     *  specified slot.
     *  查询 `_operator` 是否被授权管理所有 `_owner` 的具有指定 slot 的代币。
     * @param _owner The address that owns the ERC-3525 tokens
     * @param _slot The slot of tokens being queried approval of
     * @param _operator The address for whom to query approval
     * @return True if `_operator` is authorized to manage all of `_owner`'s tokens with `_slot`,
     *  false otherwise.
     *  如果 `_operator` 被授权管理所有 `_owner` 的具有 `_slot` 的代币，则为 True，否则为 False。
     */
    function isApprovedForSlot(
        address _owner,
        uint256 _slot,
        address _operator
    ) external view returns (bool);
}

 pragma solidity ^0.8.0;

/**
 * @title ERC-3525 token receiver interface
 * @dev Interface for a smart contract that wants to be informed by ERC-3525 contracts when receiving values from ANY addresses or ERC-3525 tokens.
 *  用于智能合约的接口，该智能合约希望在接收到来自任何地址或 ERC-3525 代币的 value 时得到 ERC-3525 合约的通知。
 * Note: the ERC-165 identifier for this interface is 0x009ce20b.
 */
interface IERC3525Receiver {
    /**
     * @notice Handle the receipt of an ERC-3525 token value.
     *  处理接收 ERC-3525 代币的 value。
     * @dev An ERC-3525 smart contract MUST check whether this function is implemented by the recipient contract, if the
     *  recipient contract implements this function, the ERC-3525 contract MUST call this function after a 
     *  value transfer (i.e. `transferFrom(uint256,uint256,uint256,bytes)`).
     *  ERC-3525 智能合约必须检查接收者合约是否实现了此函数，如果接收者合约实现了此函数，则 ERC-3525 合约必须在 value 转移后调用此函数（即 `transferFrom(uint256,uint256,uint256,bytes)`）。
     *  MUST return 0x009ce20b (i.e. `bytes4(keccak256('onERC3525Received(address,uint256,uint256,
     *  uint256,bytes)'))`) if the transfer is accepted.
     *  如果转移被接受，必须返回 0x009ce20b（即 `bytes4(keccak256('onERC3525Received(address,uint256,uint256,uint256,bytes)'))`）。
     *  MUST revert or return any value other than 0x009ce20b if the transfer is rejected.
     *  如果转移被拒绝，必须回退或返回除 0x009ce20b 之外的任何 value。
     * @param _operator The address which triggered the transfer
     * @param _fromTokenId The token id to transfer value from
     * @param _toTokenId The token id to transfer value to
     * @param _value The transferred value
     * @param _data Additional data with no specified format
     * @return `bytes4(keccak256('onERC3525Received(address,uint256,uint256,uint256,bytes)'))` 
     *  unless the transfer is rejected.
     *  除非转移被拒绝，否则返回 `bytes4(keccak256('onERC3525Received(address,uint256,uint256,uint256,bytes)'))`。
     */
    function onERC3525Received(address _operator, uint256 _fromTokenId, uint256 _toTokenId, uint256 _value, bytes calldata _data) external returns (bytes4);

}

function transferFrom(uint256 _fromTokenId, uint256 _toTokenId, uint256 _value) external payable;
	
function transferFrom(uint256 _fromTokenId, address _to, uint256 _value) external payable returns (uint256 toTokenId_);

pragma solidity ^0.8.0;

/**
 * @title ERC-3525 Semi-Fungible Token Standard, optional extension for metadata
 * @dev Interfaces for any contract that wants to support query of the Uniform Resource Identifier
 *  (URI) for the ERC-3525 contract as well as a specified slot. 
 *  用于任何想要支持查询 ERC-3525 合约以及指定 slot 的统一资源标识符 (URI) 的合约的接口。
 *  Because of the higher reliability of data stored in smart contracts compared to data stored in 
 *  centralized systems, it is recommended that metadata, including `contractURI`, `slotURI` and 
 *  `tokenURI`, be directly returned in JSON format, instead of being returned with a url pointing 
 *  to any resource stored in a centralized system. 
 *  由于与存储在集中式系统中的数据相比，存储在智能合约中的数据具有更高的可靠性，因此建议以 JSON 格式直接返回元数据，包括 `contractURI`、`slotURI` 和 `tokenURI`，而不是返回指向存储在集中式系统中的任何资源的 URL。
 *  See https://eips.ethereum.org/EIPS/eip-3525
 * Note: the ERC-165 identifier for this interface is 0xe1600902.
 */
interface IERC3525Metadata is
    IERC3525 /* , IERC721Metadata */
{
    /**
     * @notice Returns the Uniform Resource Identifier (URI) for the current ERC-3525 contract.
     *  返回当前 ERC-3525 合约的统一资源标识符 (URI)。
     * @dev This function SHOULD return the URI for this contract in JSON format, starting with
     *  header `data:application/json;`.
     *  此函数应该以 JSON 格式返回此合约的 URI，以 `data:application/json;` 标头开头。
     *  See https://eips.ethereum.org/EIPS/eip-3525 for the JSON schema for contract URI.
     * @return The JSON formatted URI of the current ERC-3525 contract
     */
    function contractURI() external view returns (string memory);

    /**
     * @notice Returns the Uniform Resource Identifier (URI) for the specified slot.
     *  返回指定 slot 的统一资源标识符 (URI)。
     * @dev This function SHOULD return the URI for `_slot` in JSON format, starting with header
     *  `data:application/json;`.
     *  此函数应该以 JSON 格式返回 `_slot` 的 URI，以 `data:application/json;` 标头开头。
     *  See https://eips.ethereum.org/EIPS/eip-3525 for the JSON schema for slot URI.
     * @return The JSON formatted URI of `_slot`
     */
    function slotURI(uint256 _slot) external view returns (string memory);
}