diff --git a/EIPS/eip-4635.md b/EIPS/eip-4635.md new file mode 100644 index 00000000000000..b71bf53a3feb8e --- /dev/null +++ b/EIPS/eip-4635.md @@ -0,0 +1,312 @@ +--- +eip: 4635 +title: Semi-fungible token standard +author: Bo Lin (@linvictor88), Danyang Li (@muren102), Frank Shen (@d22shen) +discussions-to: https://ethereum-magicians.org/t/eip-4635-semi-fungible-token-standard/7923 +status: Draft +type: Standards Track +category: ERC +created: 2021-12-16 +requires: 721 +--- + +## Simple Summary +A standard interface for contracts that manage semi-fungible token(s). A single deployed contract usually includes multiple types of fungible tokens and one single transformational non-fungible token. + +## Abstract +This standard outlines a smart contract interface that can represent semi-fungible tokens (SFT). SFTs start out as types of fungible tokens and finally end as non-fungible tokens to provide value. ERC-1155 can manage combination of fungible tokens and non-fungible tokens, however, it's intractable for semi-fungible token representation. So this standard is specially for semi-fungible token use, in which fungible token types are managed like ERC-1155 and non-fungible tokens are totally managed by ERC-721. + +## Motivation +ERC-1155 does the combination of ERC-20 and ERC-721 to allow transferring multiple token types and ids at once. This can greatly save transaction costs and remove the need to "approve" individual token contracts separately. But it's not appropriate for semi-fungible tokens as following reasons: +* ERC-1155 requires the smart contract to ensure the quantity as 1 to represent NFT which is not nature. Meanwhile, the ownership, which is one of the important attribute in NFT, is hard to track with ERC-1155. + +* By checking semi-fungible token scenarios, generally, there are no requirements to have more than one types of NFT in the single smart contract, such as mixing concert tickets and software licenses. Even if there are such requirements, the type can be defined in NFT metadata. + +* NFT usually has different values with fungible token in SFT, which needs separate approvals. + +Meanwhile, none of present ERCs has the transition from fungible token to non-fungible token. It's necessary to define a standard interface specially for SFT. SFT can manage multiple types of fungible tokens and the transition from FTs to NFTs. SFT also defines different approvals for FT and NFT. There are many scenarios which depend on SFT. For example, concert tickets can be fungible tokens which own the same right to watch a show, but it will turn to NFT once it is delivered to the audience with the unique seat number and owner name. + +## Specification +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. + +**Smart contracts implementing this standard MUST implement all the functions in the `IERC4635` interface.** + +**Smart contracts implementing this standard MUST implement the ERC-165 `supportsInterface` function and MUST return the constant value `true` if `type(IERC4635).interfaceId` is passed through the `interfaceID` argument.** + +```solidity +//SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +interface IERC4635 is IERC721 { + /** + @dev This emits when `_value` tokens of semi-fungible token (SFT) type are minted. + The `_operator` argument MUST be the address of an account/contract that is approved to + mint this type of token. + */ + event SemiTypeMinted(address indexed _operator, address indexed _to, uint256 indexed _tokenType, bytes _data, uint256 _value); + + /** + @dev This emits when approval for a second party/operator address to manage `_tokenType` of SFTs + for an owner address is enabled or disabled. + */ + event ApprovalForSemi(address indexed _owner, address indexed _operator, uint256 indexed _tokenType, bool _approved); + + /** + @dev This emits when approval for a second party/operator address to manage all types of SFTs + for an owner address is enabled or disabled. + */ + event ApprovalForAllSemi(address indexed _owner, address indexed _operator, bool _approved); + + /** + @dev This emits when a new NFT is minted from one type of SFT + */ + event SemiMinted(address _operator, address indexed _from, address indexed _to, uint256 indexed _tokenId, uint256 _tokenType); + + /** + @dev Either `SemiTransferSingle` or `SemiTransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). + The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). + The `_from` argument MUST be the address of the holder whose balance is decreased. + The `_to` argument MUST be the address of the recipient whose balance is increased. + The `_tokenType` argument MUST be the token type being transferred. + The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). + */ + event SemiTransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _tokenType, uint256 _value); + + /** + @dev Either `SemiTransferSingle` or `SemiTransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). + The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). + The `_from` argument MUST be the address of the holder whose balance is decreased. + The `_to` argument MUST be the address of the recipient whose balance is increased. + The `_tokenTypes` argument MUST be the list of token types being transferred. + The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _tokenTypes) the holder balance is decreased by and match what the recipient balance is increased by. + When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). + When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). + */ + event SemiTransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _tokenTypes, uint256[] _values); + + /** + @notice Create `_value` tokens of `_tokenType` to `_to`. + @dev Caller MUST be owner or approved to create new SFT type + MUST revert if `_to` is the zero address. + MUST emit `SemiTypeMinted` event to reflect the new sem-fungible token type creation. + @param _to address that `_tokenType` tokens assigned to. + @param _tokenType SFT type + @param _data The metadata for `_tokenType` + @param _value The number of tokens for `_tokenType` + */ + function semiTypeMint(address _to, uint256 _tokenType, uint256 _value, bytes calldata _data) external; + + /** + @notice Enable or disable approval for a third party ("operator") to manage caller's '_tokenType' tokens. + @dev MUST emit `ApprovalForSemi` event on success. + MUST revert if `_tokenType` doesn't exist + @param _operator Address of authorized operators + @param _tokenType SFT type + @param _approved True if the operator is approved, false to revoke approval + */ + function setApprovalForSemi(address _operator, uint256 _tokenType, bool _approved) external; + + /** + @notice Queries the approval status of an operator for a given owner and `_tokenType`. + @param _owner The address of the token holder + @param _operator Address of authorized operator + @param _tokenType SFT type + @return True if the operator is approved, false if not + */ + function isApprovedForSemi(address _owner, address _operator, uint256 _tokenType) external view returns (bool); + + /** + @notice Enable or disable approval for a third party ("operator") to manage caller's all SFT tokens. + @dev MUST emit `SemiApprovalForAll` event on success. + @param _operator Address of authorized operators + @param _approved True if the operator is approved, false to revoke approval + */ + function setApprovalForAllSemi(address _operator, bool _approved) external; + + /** + @notice Queries the approval status of an operator for a given owner. + @param _owner The address of the token holder + @param _operator Address of authorized operator + @return True if the operator is approved, false if not + */ + function isApprovedForAllSemi(address _owner, address _operator) external view returns (bool); + + /** + @notice Mint one SFT type of NFT from the `_from` to the `_to` as ownership of converted NFT with `_tokenId`. + @dev Caller MUST be approved to manage the token being transferred out of the `_from` account. + MUST emit `SemiTransferSingle` event to reflect the SFT converted to NFT information. + MUST emit `SemiMinted` event to reflect the new NFT creation information. + MUST emit `Transfer` event to reflect NFT creation. + MUST revert if `_to` is the zero address. + MUST revert if semiBalance of `_from` is lower than 1. + MUST revert if `_tokenType` is invalid + MUST revert on any other error. + would generate unique tokenId across the contract as the NFT id to caller. + unique tokenId is recorded in `SemiMinted` event. + SFT owner calling this function to mint one SFT type of NFT to `_to`, accordingly, the SFT balance of `_from` is decreased by 1, while NFT balance of `_to` is increased by 1. + @param _from Source address + @param _to Target address + @param _tokenType SFT type + @param _data The metadata for `_tokenType` + */ + function semiMint(address _from, address _to, uint256 _tokenType, bytes calldata _data) external; + + /** + @notice Transfers `_value` amount of a `_tokenType` from the `_from` address to the `_to` address specified (with safety call). + @dev Caller MUST be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). + MUST revert if `_to` is the zero address. + MUST revert if balance of holder for `_tokenType` tokens is lower than the `_value` sent. + MUST revert on any other error. + MUST emit the `SemiTransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard). + After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERCSFTReceived` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + @param _from Source address + @param _to Target address + @param _tokenType SFT type + @param _value Transfer amount + @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERCSFTReceived` on `_to` + */ + function semiSafeTransferFrom(address _from, address _to, uint256 _tokenType, uint256 _value, bytes calldata _data) external; + + /** + @notice Transfers `_values` amount(s) of `_tokenTypes` from the `_from` address to the `_to` address specified (with safety call). + @dev Caller MUST be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). + MUST revert if `_to` is the zero address. + MUST revert if length of `_tokenTypes` is not the same as length of `_values`. + MUST revert if any of the balance(s) of the holder(s) for token(s) in `_tokenTypes` is lower than the respective amount(s) in `_values` sent to the recipient. + MUST revert on any other error. + MUST emit `SemiTransferSingle` or `SemiTransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard). + Balance changes and events MUST follow the ordering of the arrays (_tokenTypes[0]/_values[0] before _tokenTypes[1]/_values[1], etc). + After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call the relevant `ERCSFTTokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). + @param _from Source address + @param _to Target address + @param _tokenTypes SFT types (order and length MUST match _values array) + @param _values Transfer amounts per token type (order and length MUST match _tokenTypes array) + + @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERCSFTReceived` on `_to` + */ + function semiSafeBatchTransferFrom(address _from, address _to, uint256[] calldata _tokenTypes, uint256[] calldata _values, bytes calldata _data) external; + + /** + @notice Get the balance of an account's tokens for `_tokenType`. + @param _owner The address of the token holder + @param _tokenType The token type + @return The _owner's balance of the token type requested + */ + function balanceOfSemi(address _owner, uint256 _tokenType) external view returns (uint256); + + /** + * @dev Total amount of SFTs in with a given `_tokenType`. + */ + function totalSupplyForSemi(uint256 _tokenType) external view returns (uint256); +} +``` + +### IERC4635Receiver Token Receiver + +**Smart contracts MUST implement all the functions in the `IERC4635Receiver` interface to accept transfers. See "Safe Transfer Rules" for further detail.** + +**Smart contracts MUST implement the ERC-165 `supportsInterface` function and signify support for the `IERC4635Receiver` interface to accept transfers. See "IERC4635Receiver ERC-165 rules" for further detail.** +```solidity +pragma solidity ^0.8.0; + +interface IERC4635Receiver { + /** + @notice Handle the receipt of a single ERCSFT token type. + @dev An ERCSFT-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. + This function MUST return `bytes4(keccak256("onERCSFTReceived(address,address,uint256,uint256,bytes)"))` (i.e. 0x198fb191) if it accepts the transfer. + This function MUST revert if it rejects the transfer. + Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. + @param _operator The address which initiated the transfer (i.e. msg.sender) + @param _from The address which previously owned the token + @param _type The type of the token being transferred + @param _value The amount of tokens being transferred + @param _data Additional data with no specified format + @return `bytes4(keccak256("onERCSFTReceived(address,address,uint256,uint256,bytes)"))` + */ + function onERCSFTReceived(address _operator, address _from, uint256 _type, uint256 _value, bytes calldata _data) external returns(bytes4); + + /** + @notice Handle the receipt of multiple ERCSFT token types. + @dev An ERCSFT-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. + This function MUST return `bytes4(keccak256("onERCSFTBatchReceived(address,address,uint256[],uint256[],bytes)"))` (i.e. 0xa3a64bf1) if it accepts the transfer(s). + This function MUST revert if it rejects the transfer(s). + Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. + @param _operator The address which initiated the batch transfer (i.e. msg.sender) + @param _from The address which previously owned the token + @param _types An array containing token types being transferred (order and length must match _values array) + @param _values An array containing amounts of each token being transferred (order and length must match _ids array) + @param _data Additional data with no specified format + @return `bytes4(keccak256("onERCSFTBatchReceived(address,address,uint256[],uint256[],bytes)"))` + */ + function onERCSFTBatchReceived(address _operator, address _from, uint256[] calldata _types, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); +} +``` + +### Safe Transfer Rules +To be more explicit about how the standard `semiSafeTransferFrom` and `semiSafeBatchTransferFrom` functions MUST operate with respect to the `IERC4635Receiver` hook functions, +please refer to "Safe Transfer Rules" in [ERC-1155 Multi Token Standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md). + +In ERC-1155, the `_id` argument contained in each function's argument set indicates a specific token or token type in a transaction. In ERC-SFT, the `_type` argument contained in each function's argument set indicates a semi-fungible token type in a transaction. +So please treat `_id` as token type when you refer to ERC-1155 "Safe Transfer Rules". + +#### IERC4635Receiver ERC-165 rules +* The implementation of the ERC-165 `supportsInterface` function SHOULD be as follows: + ```solidity + function supportsInterface(bytes4 interfaceID) external view returns (bool) { + return interfaceID == 0x01ffc9a7 || // ERC-165 support (i.e. `bytes4(keccak256('supportsInterface(bytes4)'))`). + interfaceID == 0xba29fa60; // ERC-SFT `IERC4635Receiver` support (i.e. `bytes4(keccak256("onERCSFTReceived(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERCSFTBatchReceived(address,address,uint256[],uint256[],bytes)"))`). + } + ``` +* The implementation MAY differ from the above but: + - It MUST return the constant value `true` if `0x01ffc9a7` is passed through the `interfaceID` argument. This signifies ERC-165 support. + - It MUST return the constant value `true` if `0xba29fa60` is passed through the `interfaceID` argument. This signifies ERC-SFT `IERC4635Receiver` support. + +### Metadata +```solidity + +pragma solidity ^0.8.0; + +interface IERC4635Metadata /* is IERC4635 */{ + /** + @notice A descriptive name for a collection of SFTs in this contract + */ + function semiName(uint256 _tokenType) external view returns (string memory); + /** + @notice An abbreviated name for SFTs in this contract + */ + function semiSymbol(uint256 _tokenType) external view returns (string memory); + /** + @notice A distinct Uniform Resource Identifier (URI) for a given asset. + @dev Throws if `_id` is not a valid NFT. URIs are defined in RFC + 3986. The URI may point to a JSON file that conforms to the "ERC721 + Metadata JSON Schema". + */ + function semiURI(uint256 _tokenType) external view returns (string memory); +} +``` + +## Rationale +The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. + +## Backwards Compatibility +All EIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The EIP must explain how the author proposes to deal with these incompatibilities. EIP submissions without a sufficient backwards compatibility treatise may be rejected outright. + +## Test Cases +Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. If the test suite is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/eip-####/`. + +## Reference +**Standards** +- [ERC-721 Non-Fungible Token Standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md) +- [ERC-165 Standard Interface Detection](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-165.md) +- [ERC-1155 Multi Token Standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md) + +**Implementations** +- [ERC-SFT Reference Implementation](https://github.com/linvictor88/ERC-SFT) + +## Security Considerations +All EIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. EIP submissions missing the "Security Considerations" section will be rejected. An EIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers. + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).