Closed Will42W closed 2 years ago
This is the new discussion thread for EIP-3525.
The new version of EIP-3525 proposal has significant changes from the last version of committed document, so we suggest discussing the new version in this new thread, the old issue(https://github.com/ethereum/EIPs/issues/3641) is closed, only as a reference for the document history.
The main changes of this version is as follows:
Discussion links should be created at Ethereum Magicians. Please create a thread there and update the EIP to point at it.
Hi, thanks for Micah, I had posted the discussion at Ethereum Magicians, seems it needs some approve to appear, should I post the PR without the discussion URL or just wait for the thread in Ethereum Magicians to be approved?
New to Ethereum Magicians, thanks a lot.
Discussion links should be created at Ethereum Magicians. Please create a thread there and update the EIP to point at it.
What exactly do you need approval to do? Are you unable to create a thread or something?
Are you unable to create a thread or something?
Yes, the discussion thread I created on Ethereum Magicians for EIP-3525 is pending to be reviewed by staff members, because it's the first time I create topics on Ethereum Magicians and it seems to have some approval procedures for users' first topic. So do I have to wait for the thread to be approved and then I can quote the thread in the PR of ERC-3525, or I can first submit the new modifications in a PR and later change the discussion-to URL to Ethereum Magicians after the thread is approved?
Thanks a lot.
You can iterate on it in the meantime. I have reached out to see why there is such a long delay on getting approved.
It looks like it is live now. I didn't approve it, so not sure if another person approved it.
Could you kindly explain why behind the following decision for transferFrom function:
This function MUST create a new ERC3525 token with the same slot for `_to` to receive
* the transferred value.
The why must be associated with real-life use cases that can leverage such a property of creating new token IDs upon transfer of such a token from one address to another. In my view, the alternative is transfer of ownership instead of creating a new token ID every time transfer happens between two accounts or addresses. Yeah it's how 1155 works, which seems to me pretty sufficient. After all tokens with the same slot can be merged or transferred and why bother to create a new ID out of transfer? What happens to the originator token ID that is left with zero value? It looks to me a new token ID simply binds an address or account with a token, which is really unnecessary at all.
What's more, from engineering or programming point of view, it doesn't have to mimic the real-life implementations in the code. E.g. you don't have to create a new token ID simply to differentiate two tokens having the same slot ID, unless there's specific on-chain reason to leverage such a trait.
eip: 3525 title: Semi-Fungible Token Standard author: Will Wang (@will-edge), Mike Meng myan@solv.finance, Ethan Y. Tsai yee.tsai@gmail.com, Ryan Chow ryanchow@solv.finance, Zhongxin Wu wuzhongxin@solv.finance, AlvisDu alvis@solv.finance discussions-to: https://github.com/ethereum/EIPs/issues/5183 status: Draft type: Standards Track category: ERC created: 2020-12-01 requires: 165, 721
Table of Contents
Simple Summary
This is a standard for semi-fungible tokens. The set of smart contract interfaces described in this document defines an ERC-721 extension/compatible token standard. This standard introduces an <ID, SLOT, VALUE> triple scalar model that represents the semi-fungible structure of a token. It also introduces new transfer models as well as approval models that reflect the semi-fungible nature of the tokens.
Abstract
ERC-3525 is an ERC-721 compatible token standard, where each ERC-3525 token, like an ER-721 token, contains an ID property to identify itself as a universally unique entity, so that the tokens can be transferred between addresses and approved to be operated in ERC-721 compatible way.
ERC-3525 tokens also contain an 'value' property, representing the quantitative nature of the token. The meaning of the 'value' property is quite like that of the 'balance' property of an ERC-20 token. Each ERC-3525 token has a 'slot' attribute, ensuring that the value of two ERC-3525 tokens with the same slot be treated as fungible, adding fungibility to the value property of the tokens.
ERC-3525 introduces new token transfer models for semi-fungibility, including value transfer between two tokens of the same slot and value transfer from a token to an address.
Motivation
Tokenization is one of the most important trends by which to use and control digital assets in crypto. Traditionally, there are two approaches to do so: fungible and non-fungible tokens. Fungible tokens are generally powered by ERC-20 standard, where every unit of an asset is identical to each other. ERC-20 is a flexible and efficient way to manipulate fungible tokens. Non-fungible tokens are predominantly ERC-721 tokens, powered by a standard capable of distinguishing digital assets from one another based on identity.
However, both have significant drawbacks. For example, ERC-20 requires that users create a separate ERC-20 contract for each individual data structure or combination of customizable properties, resulting in an unrealistic amount of ERC-20 contracts that need to be created in practice. On the other hand, ERC-721 tokens provide no quantitative feature, hence significantly undercutting their computability, liquidity, and manageability. For example, if we are to create financial instruments such as bonds, insurance policy, vesting plans using ERC-721, no standard interfaces are available for us to control the value in them, making it impossible, for example, to transfer a portion of the equity in the contract represented by the token.
A more intuitive and straightforward way to solve the problem is to create a semi-fungible token that has the quantitative features of ERC-20 and qualitative attributes of ERC-721. The backwards-compatibility of such semi-fungible tokens would help utilize existing infrastructures already in use and lead to faster adoption.
For further design motivations, please view papers and documents below:
Articles & Discussions
Specification
The keywords "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.
Related Standards
Every ERC-3525 compliant contract must implement the ERC3525, ERC721 and ERC165 interfaces
The slot's enumeration extension is OPTIONAL for ERC-3525 smart contracts. This allows your contract to publish its full list of SLOT and make them discoverable.
The slot level approval is OPTIONAL for ERC-3525 smart contracts. This allows any contract that wants to support approval for slots, which allows an operator to manage one's tokens with the same slot.
ERC-3525 Token Receiver
Smart contracts MUST implement all of the functions in the IERC3525Receiver interface to accept transfers. See "Safe Transfer Rules" for further detail.
Token Manipulation
Scenarios
Transfer:
Besides ERC-721 compatible token transfer methods, ERC-3525 introduces two new transfer models: value transfer from ID to ID, and value transfer from ID to address.
The first one allows value transfers from one token (specified by
_fromTokenId
) to another token (specified by_toTokenId
) with the same slot, as a result, the_value
will be subtracted from the value of the source token and added to the value of the destination token;The second one allows value transfers from one token (specified by
_fromTokenId
) to an address (specified by_to
), the value is actually transferred to a token owned by the address, and the id of the destination token should be returned. Further explanation can be found in the 'design decision' section for this method.Rules
approving rules:
For being compatible with ERC-721, ERC-3525 provides four kinds of approving functions indicating different levels of approvals, which can be described as full level approval, slot level approval, token ID level approval as well as value level approval.
setApprovalForAll
, inherited from ERC721, SHOULD indicate the full level of approval, which means that the authorized operators are capable of managing all the tokens, including their values, owned by the owner.setApprovalForSlot
(optional) SHOULD indicate the slot level of approval, which means that the authorized operators are capable of managing all the tokens with the specified slot, including their values, owned by the owner.approve
function, inherited from ERC721, SHOULD indicate that the authorized operator is capable of managing only the specified token ID, including its value, owned by the owner.approve
function, overloaded with a_value
parameter, SHOULD indicate that the authorized operator is capable of managing the specified maximum value of the specified token owned by the owner.transferFrom rules:
The
transferFrom(uint256 _fromTokenId, uint256 _toTokenId, uint256 _value)
function, SHOULD indicate value transfers from one token to another token, in accordance with the rules below:msg.sender
is the owner of_fromTokenId
, an authorized operator or an operator who has been approved the whole token or at least_value
of it._fromTokenId
or_toTokenId
is zero token id or does not exist._fromTokenId
and_toTokenId
do not match._value
exceeds the value of_fromTokenId
or its allowance to the operator.TransferValue
event.The
transferFrom(uint256 _fromTokenId, address _to, uint256 _value)
function, which transfers value from one token ID to an address, SHOULD follow the rule below:msg.sender
is the owner of_fromTokenId
, an authorized operator or an operator who has been approved the whole token or at least_value
of it._fromTokenId
is zero token id or does not exist._to
is zero address._value
exceeds the value of_fromTokenId
or its allowance to the operator.Transfer
andTransferValue
events.safeTransferFrom rules:
safeTransferFrom
SHOULD be used to implement the same function astransferFrom
, with an extra step to check if the recipient is capable of receiving ERC-3525 tokens by implementing theonERC3525Received
interface.transferFrom
._to
is a smart contract (code size > 0). If so,safeTransferFrom
MUST callonERC3525Received
on_to
and MUST revert if the return value does not matchbytes4(keccak256("onERC3525Received(address,uint256,uint256,uint256,bytes)"))
Metadata
Metadata Extensions
ERC-3525 metadata extensions are compatible ERC-721 metadata extensions.
The optional ERC3525Metadata extension can be identified with the ERC-165 Standard Interface Detection.
ERC-3525 Metadata URI JSON Schema
This is the "ERC-3525 Metadata JSON Schema for contractURI()" referenced above.
This is the "ERC-3525 Metadata JSON Schema for slotURI(uint)" referenced above.
This is the "ERC-3525 Metadata JSON Schema for tokenURI(uint)" referenced above.
Approval
ERC-3525 introduces a new approval model, where users can approve operators for transferring value from a token with certain ID:
function approve(address to, uint256 tokenId, uint256 value);
Rationale
Metadata generation
The ERC-3525 token standard is designed to represent semi-fungible assets, which are most suited for financial instruments rather than collectibles or in-game items. For maximum transparency and safety of digital assets, the implementation should generate metadata directly from contract code rather than giving out a server URL.
Design decision: Value transfer from token to address
The ‘value’ of an ERC-3525 token is a property of the token and is not linked to an address, so to transfer the value to an address would be actually transferring it to a token owned by that address, not the address itself.
From the implementation perspective, the process of transferring values from token to address is as follows: (1) create a new token, (2) transfer the value to the new token from the 'source token', and (3) transfer the new token to the recipient’s address. So that this method is not fully independent from the ID-to-ID transfer method, and can be viewed as syntactic sugar that wraps the three-step process above.
In a special case, if the destination address owns one or more tokens with the same slot value as the source token, this method will have an alternative implemention as follows: (1) find one token owned by the address with the same slot value of the source token, (2) trnasfer the value to the found token. Both implementation should be treated as compliant with this standard.
The purpose of maintaining this function is to maximize the compatibility with most wallet apps, since for most of the token standards, the destination of token transfer are addresses. This syntactic wrapping will help wallet apps easily implement the value transfer function from an ERC-3525 token to any address.
Design decision: Keep unsafe transfer
There are mainly two reasons we keep the unsafe transfer interfaces:
onERC3525Received
function so that it can be called whenever a token is transferred usingsafeTransferFrom
. However, in this situation, an approved contract with customized transfer functions like deposit etc. SHOULD never callsafeTransferFrom
since it will result in confusion that whetheronERC3525Received
is called by itself or other dapps that call the safeTransferFrom function.Approval
For maximal semantic compatibility with ERC-721 and simplification of the approval model, we decided to make the relationship between two levels of approval like that:
Approval of an id does not lead to the ability to partially transfer values from this id by the approved operator; Approval of total values in a token does not lead to the ability to transfer the token entity by the approved operator; setApprovalForAll will lead to the ability to transfer any tokens from the owner and to partially transfer values from any token. setApprovalForAll will lead to the ability to approve any tokens of the owner to third parties, as well as the ability to approve partial transfer of values of any token to a third party.
Backwards Compatibility
As mentioned in the beginning, ERC-3525 is an extension interface of ERC-721, and therefore 100% compatible with the latter.
Implementations
Copyright
Copyright and related rights waived via CC0.