-
Notifications
You must be signed in to change notification settings - Fork 188
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Multi Token Standard #404
Comments
The technical details are mainly whether to modify the methods in the
In TRC721, we change |
TVM has always supported 1155, only needs ecosystem app support, such as Tronscan, wallet, etc. |
After discussions within the community, we introduced the
|
Close this issue as there has been no new discussion for more than 6 months. |
Simple Summary
A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens or other configurations (e.g. semi-fungible tokens).
Abstract
This TIP is compatible with EIP-1155.
This standard outlines a smart contract interface that can represent any number of fungible and non-fungible token types. Existing standards such as TRC-20 require deployment of separate contracts per token type. The TRC-721 standard's token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the TRC-1155 Multi Token Standard allows for each token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes.
The
_id
argument contained in each function's argument set indicates a specific token or token type in a transaction.Motivation
Tokens standards like TRC-20 and TRC-721 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the TRON blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address. With the rise of blockchain games and platforms like Enjin Coin, game developers may be creating thousands of token types, and a new type of token standard is needed to support them. However, TRC-1155 is not specific to games and many other applications can benefit from this flexibility.
New functionality is possible with this design such as transferring multiple token types at once, saving on transaction costs. Trading (escrow / atomic swaps) of multiple tokens can be built on top of this standard and it removes the need to "approve" individual token contracts separately. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract.
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 the TRC-1155 standard MUST implement all of the functions in the
TRC1155
interface.Smart contracts implementing the TRC-1155 standard MUST implement the TRC-165
supportsInterface
function and MUST return the constant valuetrue
if0xd9b67a26
is passed through theinterfaceID
argument.TRC-1155 Token Receiver
In order to provide compatibility with
EIP-1155
, we decided to follow the definition ofERC1155TokenReceiver
defined inEIP-1155
without any modifications.Smart contracts MUST implement all of the functions in the
TRC1155TokenReceiver
interface to accept transfers. See "Safe Transfer Rules" for further detail.Smart contracts MUST implement the TRC-165
supportsInterface
function and signify support for theTRC1155TokenReceiver
interface to accept transfers. See "TRC1155TokenReceiver TRC-165 rules" for further detail.Safe Transfer Rules
To be more explicit about how the standard
safeTransferFrom
andsafeBatchTransferFrom
functions MUST operate with respect to theTRC1155TokenReceiver
hook functions, a list of scenarios and rules follows.Scenarios
Scenario#1 : The recipient is not a contract.
onERC1155Received
andonERC1155BatchReceived
MUST NOT be called on an EOA (Externally Owned Account).Scenario#2 : The transaction is not a mint/transfer of a token.
onERC1155Received
andonERC1155BatchReceived
MUST NOT be called outside of a mint or transfer process.Scenario#3 : The receiver does not implement the necessary
TRC1155TokenReceiver
interface function(s).Scenario#4 : The receiver implements the necessary
TRC1155TokenReceiver
interface function(s) but returns an unknown value.Scenario#5 : The receiver implements the necessary
TRC1155TokenReceiver
interface function(s) but throws an error.Scenario#6 : The receiver implements the
TRC1155TokenReceiver
interface and is the recipient of one and only one balance change (e.g.safeTransferFrom
called).TRC1155TokenReceiver
hook is called on a recipient contract.TRC1155TokenReceiver
hook is called on the recipient contract.onERC1155Received
oronERC1155BatchReceived
MUST be called on the recipient contract.onERC1155Received
hook SHOULD be called on the recipient contract and its rules followed.onERC1155BatchReceived
hook MAY be called on the recipient contract and its rules followed.Scenario#7 : The receiver implements the
TRC1155TokenReceiver
interface and is the recipient of more than one balance change (e.g.safeBatchTransferFrom
called).TRC1155TokenReceiver
hook MUST be updated before theTRC1155TokenReceiver
hook is called on the recipient contract.TRC1155TokenReceiver
hook is called on the recipient contract.onERC1155Received
oronERC1155BatchReceived
MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for.onERC1155BatchReceived
hook SHOULD be called on the recipient contract and its rules followed.onERC1155Received
hook MAY be called on the recipient contract and its rules followed.Scenario#8 : You are the creator of a contract that implements the
TRC1155TokenReceiver
interface and you forward the token(s) onto another address in one or both ofonERC1155Received
andonERC1155BatchReceived
.safeTransferFrom
orsafeBatchTransferFrom
in a new context._data
argument MAY be re-purposed for the new context.Scenario#9 : You are transferring tokens via a non-standard API call i.e. an implementation specific API and NOT
safeTransferFrom
orsafeBatchTransferFrom
.TransferSingle
andTransferBatch
events alone.TRC1155TokenReceiver
hooks still need to be called on it and the return values respected the same as if a standard transfer function had been called.safeTransferFrom
orsafeBatchTransferFrom
functions MUST revert if a receiving contract does not implement theTRC1155TokenReceiver
interface, a non-standard function MAY proceed with the transfer.Rules
safeTransferFrom rules:
_from
account (see "Approval" section)._to
is the zero address._id
is lower than the_value
sent to the recipient.TransferSingle
event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section)._to
is a smart contract (e.g. code size > 0). If so, it MUST callonERC1155Received
on_to
and act appropriately (see "onERC1155Received rules" section)._data
argument provided by the sender for the transfer MUST be passed with its contents unaltered to theonERC1155Received
hook function via its_data
argument.safeBatchTransferFrom rules:
_from
account (see "Approval" section)._to
is the zero address._ids
is not the same as length of_values
._ids
is lower than the respective amount(s) in_values
sent to the recipient.TransferSingle
orTransferBatch
event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section)._to
is a smart contract (e.g. code size > 0). If so, it MUST callonERC1155Received
oronERC1155BatchReceived
on_to
and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section)._data
argument provided by the sender for the transfer MUST be passed with its contents unaltered to theTRC1155TokenReceiver
hook function(s) via their_data
argument.TransferSingle and TransferBatch event rules:
TransferSingle
SHOULD be used to indicate a single balance transfer has occurred between a_from
and_to
pair.TransferBatch
is designed for this to reduce gas consumption._operator
argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender)._from
argument MUST be the address of the holder whose balance is decreased._to
argument MUST be the address of the recipient whose balance is increased._id
argument MUST be the token type being transferred._value
argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by._from
argument MUST be set to0x0
(i.e. zero address). See "Minting/creating and burning/destroying rules"._to
argument MUST be set to0x0
(i.e. zero address). See "Minting/creating and burning/destroying rules".TransferBatch
SHOULD be used to indicate multiple balance transfers have occurred between a_from
and_to
pair.TransferSingle
is designed for this to reduce gas consumption._operator
argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender)._from
argument MUST be the address of the holder whose balance is decreased for each entry pair in_ids
and_values
._to
argument MUST be the address of the recipient whose balance is increased for each entry pair in_ids
and_values
._ids
array argument MUST contain the ids of the tokens being transferred._values
array argument MUST contain the number of token to be transferred for each corresponding entry in_ids
._ids
and_values
MUST have the same length._from
argument MUST be set to0x0
(i.e. zero address). See "Minting/creating and burning/destroying rules"._to
argument MUST be set to0x0
(i.e. zero address). See "Minting/creating and burning/destroying rules".0x0
minus the total value transferred to0x0
observed via theTransferSingle
andTransferBatch
events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID.TransferSingle
event from0x0
to0x0
, with the token creator as_operator
, and a_value
of 0.TransferSingle
andTransferBatch
events MUST be emitted to reflect all the balance changes that have occurred before any call(s) toonERC1155Received
oronERC1155BatchReceived
.onERC1155Received rules:
_operator
argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender)._from
argument MUST be the address of the holder whose balance is decreased._from
MUST be 0x0 for a mint._id
argument MUST be the token type being transferred._value
argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by._data
argument MUST contain the information provided by the sender for the transfer with its contents unaltered._data
argument sent via thesafeTransferFrom
orsafeBatchTransferFrom
call for this transfer.bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))
bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))
the transfer MUST be completed or MUST revert if any other conditions are not met for success.bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))
the transaction MUST be reverted.onERC1155Received
(and/oronERC1155BatchReceived
) MAY be called multiple times in a single transaction and the following requirements must be met:onERC1155Received
andonERC1155BatchReceived
describes all balance changes that occurred during the transaction in the order submitted.onERC1155Received
hook function if the transfer operation is transferring the token to itself.onERC1155BatchReceived rules:
_operator
argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender)._from
argument MUST be the address of the holder whose balance is decreased._from
MUST be 0x0 for a mint._ids
argument MUST be the list of tokens being transferred._values
argument MUST be the list of number of tokens (matching the list and order of tokens specified in_ids
) the holder balance is decreased by and match what the recipient balance is increased by._data
argument MUST contain the information provided by the sender for the transfer with its contents unaltered._data
argument sent via thesafeBatchTransferFrom
call for this transfer.bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))
bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))
the transfer MUST be completed or MUST revert if any other conditions are not met for success.bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))
the transaction MUST be reverted.onERC1155BatchReceived
(and/oronERC1155Received
) MAY be called multiple times in a single transaction and the following requirements must be met:onERC1155Received
andonERC1155BatchReceived
describes all balance changes that occurred during the transaction in the order submitted.onERC1155BatchReceived
hook function if the transfer operation is transferring the token(s) to itself.TRC1155TokenReceiver TRC-165 rules:
supportsInterface
function SHOULD be as follows:true
if0x01ffc9a7
is passed through theinterfaceID
argument. This signifies TRC-165 support.true
if0x4e2312e0
is passed through theinterfaceID
argument. This signifies TRC-1155TRC1155TokenReceiver
support.Implementation specific transfer API rules:
safeTransferFrom
orsafeBatchTransferFrom
(as appropriate) rules MUST still be followed if the receiver implements theTRC1155TokenReceiver
interface. If it does not the non-standard implementation SHOULD revert but MAY proceed.function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);
.myTransferFrom
updates the balances for_from
and_to
addresses for all_ids
and_values
.myTransferFrom
emitsTransferBatch
with the details of what was transferred from address_from
to address_to
.myTransferFrom
checks if_to
is a contract address and determines that it is so (if not, then the transfer can be considered successful).myTransferFrom
callsonERC1155BatchReceived
on_to
and it reverts or returns an unknown value (if it had returnedbytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))
the transfer can be considered successful).myTransferFrom
SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by theonERC1155BatchReceived
function.myTransferFrom
wishes to continue it MUST callsupportsInterface(0x4e2312e0)
on_to
and if it returns the constant valuetrue
the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed.supportsInterface(0x4e2312e0)
at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario.supportsInterface(0x4e2312e0)
on_to
reverts or returns a value other than the constant valuetrue
themyTransferFrom
function MAY consider this transfer successful.safeTransferFrom
andsafeBatchTransferFrom
):TRC1155TokenReceiver
hook function(s) have to be called on it.TRC1155TokenReceiver
hook MUST be updated (and emitted) before theTRC1155TokenReceiver
hook is called.TRC1155TokenReceiver
hook functions that are called MUST be respected if they are implemented.TRC1155TokenReceiver
hook functions.safeTransferFrom
andsafeBatchTransferFrom
MUST revert in that case (unless it is a hybrid standards implementation see "Backwards Compatibility").Minting/creating and burning/destroying rules:
TransferSingle
event from0x0
to0x0
, with the token creator as_operator
, and a_value
of 0._from
argument MUST be set to0x0
(i.e. zero address) to flag the transfer as a mint to contract observers._to
argument MUST be set to0x0
(i.e. zero address) to flag the transfer as a burn to contract observers.0x0
(that is impl specific), only the_to
argument in the event MUST be set to0x0
as above.0x0
minus the total value transferred to0x0
observed via theTransferSingle
andTransferBatch
events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID.safeTransferFrom
orsafeBatchTransferFrom
. If so the "Implementation specific transfer API rules" section would be appropriate.TRC1155TokenReceiver
hook function(s) if the mint operation is transferring the token(s) to itself. In all other cases theTRC1155TokenReceiver
rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid).A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation):
Metadata
The URI value allows for ID substitution by clients. If the string
{id}
exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for a large number of tokens to use the same on-chain string by defining a URI once, for that large number of tokens.[0-9a-f]
with no 0x prefix.Example of such a URI:
https://token-cdn-domain/{id}.json
would be replaced withhttps://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json
if the client is referring to token ID 314592/0x4CCE0.We strongly recommend that you use
BTFS
to identify the url of a token.Metadata Extensions
The optional
TRC1155Metadata_URI
extension can be identified with the TRC-165 Standard Interface Detection.If the optional
TRC1155Metadata_URI
extension is included:supportsInterface
function MUST return the constant valuetrue
if0x0e89341c
is passed through theinterfaceID
argument.URI
event if the change can be expressed with an event (i.e. it isn't dynamic/programmatic).URI
event during a mint operation but it is NOT mandatory. An observer MAY fetch the metadata uri at mint time from theuri
function if it was not emitted.uri
function SHOULD be used to retrieve values if no event was emitted.uri
function MUST return the same value as the latest event for an_id
if it was emitted.uri
function MUST NOT be used to check for the existence of a token as it is possible for an implementation to return a valid string even if the token does not exist.TRC-1155 Metadata URI JSON Schema
This JSON schema is loosely based on the "TRC721 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients. If the string
{id}
exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard.[0-9a-f]
with no 0x prefix.An example of an TRC-1155 Metadata JSON file follows. The properties array proposes some SUGGESTED formatting for token-specific display properties and metadata.
Localization
Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a
localization
attribute, its content MAY be used to provide localized values for fields that need it. Thelocalization
attribute should be a sub-object with three attributes:uri
,default
andlocales
. If the string{locale}
exists in any URI, it MUST be replaced with the chosen locale by all client software.JSON Schema
Localized Sample
Base URI:
es.json:
fr.json:
Approval
The function
setApprovalForAll
allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as TRC-1761 Scoped Approval Interface is suggested.The counterpart
isApprovedForAll
provides introspection into any status set bysetApprovalForAll
.An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call
setApprovalForAll
to approve themselves as an operator before they can operate on them.Rationale
Metadata Choices
The
symbol
function (found in the TRC-20 and TRC-721 standards) was not included as we do not believe this is a globally useful piece of data to identify a generic virtual item / asset and are also prone to collisions. Short-hand symbols are used in tickers and currency trading, but they aren't as useful outside of that space.The
name
function (for human-readable asset names, on-chain) was removed from the standard to allow the Metadata JSON to be the definitive asset name and reduce duplication of data. This also allows localization for names, which would otherwise be prohibitively expensive if each language string was stored on-chain, not to mention bloating the standard interface. While this decision may add a small burden on implementers to host a JSON file containing metadata, we believe any serious implementation of TRC-1155 will already utilize JSON Metadata.Upgrades
The requirement to emit
TransferSingle
orTransferBatch
on balance change implies that a valid implementation of TRC-1155 redeploying to a new contract address MUST emit events from the new contract address to replicate the deprecated contract final state. It is valid to only emit a minimal number of events to reflect only the final balance and omit all the transactions that led to that state. The event emit requirement is to ensure that the current state of the contract can always be traced only through events. To alleviate the need to emit events when changing contract address, consider using the proxy pattern, such as described in TIP-2535. This will also have the added benefit of providing a stable contract address for users.Design decision: Supporting non-batch
The standard supports
safeTransferFrom
andonERC1155Received
functions because they are significantly cheaper for single token-type transfers, which is arguably a common use case.Design decision: Safe transfers only
The standard only supports safe-style transfers, making it possible for receiver contracts to depend on
onERC1155Received
oronERC1155BatchReceived
function to be always called at the end of a transfer.Guaranteed log trace
As the Ethereum ecosystem continues to grow, many dapps are relying on traditional databases and explorer API services to retrieve and categorize data. The TRC-1155 standard guarantees that event logs emitted by the smart contract will provide enough data to create an accurate record of all current token balances. A database or explorer may listen to events and be able to provide indexed and categorized searches of every TRC-1155 token in the contract.
Approval
The function
setApprovalForAll
allows an operator to manage one's entire set of tokens on behalf of the approver. It enables frictionless interaction with exchange and trade contracts.Restricting approval to a certain set of token IDs, quantities or other rules MAY be done with an additional interface or an external contract. The rationale is to keep the TRC-1155 standard as generic as possible for all use-cases without imposing a specific approval scheme on implementations that may not need it. Standard token approval interfaces can be used, such as the suggested TRC-1761 Scoped Approval Interface which is compatible with TRC-1155.
Backwards Compatibility
There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically TRC-721 at time of writing.
To cater for this scenario, there is some leeway with the revert logic should a contract not implement the
TRC1155TokenReceiver
as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessaryTRC1155TokenReceiver
interface function(s)".Hence in a hybrid TRC-1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to
onERC1155Received
oronERC1155BatchReceived
are made.Order of operation MUST therefore be:
supportsInterface(0x4e2312e0)
on the recipient contract, providing at least 10,000 gas.true
the implementation proceeds as a regular TRC-1155 implementation, with the call(s) to theonERC1155Received
oronERC1155BatchReceived
hooks and rules associated.true
the implementation can assume the recipient contract is not anERC1155TokenReceiver
and follow its other standard's rules for transfers.Note that a pure implementation of a single standard is recommended rather than a hybrid solution, but an example of a hybrid TRC-1155/TRC-721 contract is linked in the references section under implementations.
An important consideration is that even if the tokens are sent with another standard's rules the TRC-1155 transfer events MUST still be emitted. This is so the balances can still be determined via events alone as per TRC-1155 standard rules.
Usage
This standard can be used to represent multiple token types for an entire domain. Both fungible and non-fungible tokens can be stored in the same smart-contract.
Batch Transfers
The
safeBatchTransferFrom
function allows for batch transfers of multiple token IDs and values. The design of TRC-1155 makes batch transfers possible without the need for a wrapper contract, as with existing token standards. This reduces gas costs when more than one token type is included in a batch transfer, as compared to single transfers with multiple transactions.Another advantage of standardized batch transfers is the ability for a smart contract to respond to the batch transfer in a single operation using
onERC1155BatchReceived
.It is RECOMMENDED that clients and wallets sort the token IDs and associated values (in ascending order) when posting a batch transfer, as some TRC-1155 implementations offer significant gas cost savings when IDs are sorted. See Horizon Games - Multi-Token Standard "packed balance" implementation for an example of this.
Batch Balance
The
balanceOfBatch
function allows clients to retrieve balances of multiple owners and token IDs with a single call.Enumerating from events
In order to keep storage requirements light for contracts implementing TRC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block.
TRC-1155 contracts must therefore carefully emit
TransferSingle
orTransferBatch
events in any instance where tokens are created, minted, transferred or destroyed.Non-Fungible Tokens
The following strategies are examples of how you MAY mix fungible and non-fungible tokens together in the same contract. The standard does NOT mandate how an implementation must do this.
Split ID bits
The top 128 bits of the uint256
_id
parameter in any TRC-1155 function MAY represent the base token ID, while the bottom 128 bits MAY represent the index of the non-fungible to make it unique.Non-fungible tokens can be interacted with using an index based accessor into the contract/token data set. Therefore to access a particular token set within a mixed data contract and a particular non-fungible within that set,
_id
could be passed as<uint128: base token id><uint128: index of non-fungible>
.To identify a non-fungible set/category as a whole (or a fungible) you COULD just pass in the base id via the
_id
argument as<uint128: base token id><uint128: zero>
. If your implementation uses this technique this naturally means the index of a non-fungible SHOULD be 1-based.Inside the contract code the two pieces of data needed to access the individual non-fungible can be extracted with uint128(~0) and the same mask shifted by 128.
Note that 128 is an arbitrary number, an implementation MAY choose how they would like this split to occur as suitable for their use case. An observer of the contract would simply see events showing balance transfers and mints happening and MAY track the balances using that information alone.
For an observer to be able to determine type (non-fungible or fungible) from an ID alone they would have to know the split ID bits format on a implementation by implementation basis.
The ERC-1155 Reference Implementation is an example of the split ID bits strategy.
Natural Non-Fungible tokens
Another simple way to represent non-fungibles is to allow a maximum value of 1 for each non-fungible token. This would naturally mirror the real world, where unique items have a quantity of 1 and fungible items have a quantity greater than 1.
References
Standards
Implementations
Articles & Discussions
The text was updated successfully, but these errors were encountered: