status-im/EIPs
2
0
Fork 0
mirror of https://github.com/status-im/EIPs.git synced 2025-02-25 21:25:22 +00:00
Code Issues Projects Releases Wiki Activity

Automatically merged updates to draft EIP(s) 1155

Browse Source 
Hi, I'm a bot! This change was automatically merged because:

 - It only modifies existing Draft or Last Call EIP(s)
 - The PR was approved or written by at least one author of each modified EIP
 - The build is passing
This commit is contained in:
Witek 2019-01-09 12:50:43 -08:00 committed by EIP Automerge Bot
parent 1a0bdc253b
commit edc2525e4a
1 changed files with 110 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
EIPS/eip-1155.md
View File

@ -1,12 +1,13 @@
---
eip: 1155
title: Multi Token Standard
author: Witek Radomski <witek@enjin.com>, Andrew Cooke <andrew@enjin.com>, Philippe Castonguay <ph.castonguay@gmail.com>, James Therien <james@enjin.com>, Eric Binet <eric@enjin.com>
title: ERC-1155 Multi Token Standard
author: Witek Radomski <witek@enjin.com>, Andrew Cooke <andrew@enjin.com>, Philippe Castonguay <pc@horizongames.net>, James Therien <james@enjin.com>, Eric Binet <eric@enjin.com>
type: Standards Track
category: ERC
status: Draft
created: 2018-06-17
discussions-to: https://github.com/ethereum/EIPs/issues/1155
requires: 165
---
## Simple Summary
@ -15,15 +16,15 @@ A standard interface for contracts that manage multiple token types. A single de
## Abstract
This standard outlines a smart contract interface where one can represent any number of Fungible and Non-Fungible tokens in a single contract. Existing standards such as ERC-20 require deployment of separate contracts per token. The ERC-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 ERC-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.
This standard outlines a smart contract interface where one can represent any number of Fungible and Non-Fungible token types in a single contract. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-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 ERC-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` parameter is contained in each function's parameters and indicates a specific token or token type in a transaction.
## Motivation
Tokens standards like ERC-20 and ERC-721 require a separate contract to be deployed for each fungible or NFT token/collection. This places a lot of redundant bytecode on the Ethereum blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address. With the rise of crypto games and platforms like [Enjin Coin](https://enjincoin.io/), game developers may be creating thousands of tokens, and a new type of token standard is needed to support this.
Tokens standards like ERC-20 and ERC-721 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the Ethereum 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, ERC-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 tokens in a single contract.
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
@ -32,7 +33,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
**Smart contracts implementing the ERC-1155 standard MUST implement the `ERC1155` and `ERC165` interfaces.**
```solidity
pragma solidity ^0.4.25;
pragma solidity ^0.5.2;
/**
@title ERC-1155 Multi Token Standard
@ -42,12 +43,22 @@ pragma solidity ^0.4.25;
interface ERC1155 /* is ERC165 */ {
/**
@dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning.
Operator will always be msg.sender.
Either event from address `0x0` signifies a minting operation.
An event to address `0x0` signifies a burning or melting operation.
The total value transferred from address 0x0 minus the total value transferred to 0x0 may be used by clients and exchanges to be added to the "circulating supply" for a given token ID
This MAY emit a 0 value, from `0x0` to `0x0` with `_operator` assuming the role of the token creator to define a token ID with no initial balance at the time of creation.
The total value transferred from address 0x0 minus the total value transferred to 0x0 may be used by clients and exchanges to be added to the "circulating supply" for a given token ID.
To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the TransferSingle event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0.
*/
event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value);
/**
@dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning.
Operator will always be msg.sender.
Either event from address `0x0` signifies a minting operation.
An event to address `0x0` signifies a burning or melting operation.
The total value transferred from address 0x0 minus the total value transferred to 0x0 may be used by clients and exchanges to be added to the "circulating supply" for a given token ID.
To broadcast the existence of multiple token IDs with no initial balance, this SHOULD emit the TransferBatch event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0.
*/
event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values);
/**
@ -57,46 +68,44 @@ interface ERC1155 /* is ERC165 */ {
/**
@dev MUST emit when the URI is updated for a token ID.
URIs are defined in RFC 3986.
The URI MUST point a JSON file that conforms to the "ERC-1155 Metadata JSON Schema".
*/
event URI(string _value, uint256 indexed _id);
/**
@dev MUST emit when the Name is updated for a token ID.
*/
event Name(string _value, uint256 indexed _id);
/**
@notice Transfers value amount of an _id from the _from address to the _to addresses specified. Each parameter array should be the same length, with each index correlating.
@notice Transfers value amount of an _id from the _from address to the _to address specified.
@dev MUST emit TransferSingle event on success.
Caller must be approved to manage the _from account's tokens (see isApprovedForAll).
MUST Throw if `_to` is the zero address.
MUST Throw if `_id` is not a valid token ID.
MUST Throw on any other error.
MUST throw if `_to` is the zero address.
MUST throw if balance of sender for token `_id` is lower than the `_value` sent.
MUST throw on any other error.
When transfer is complete, this function MUST check if `_to` is a smart contract (code size > 0). If so, it MUST call `onERC1155Received` on `_to` and revert if the return value is not `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`.
@param _from Source addresses
@param _to Target addresses
@param _from Source address
@param _to Target address
@param _id ID of the token type
@param _value Transfer amount
@param _data Additional data with no specified format, sent in call to `_to`
*/
function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes _data) external;
function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external;
/**
@notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call).
@dev MUST emit TransferBatch event on success.
Caller must be approved to manage the _from account's tokens (see isApprovedForAll).
MUST Throw if `_to` is the zero address.
MUST Throw if any of the `_ids` is not a valid token ID.
MUST Throw on any other error.
MUST throw if `_to` is the zero address.
MUST throw if length of `_ids` is not the same as length of `_values`.
MUST throw if any of the balance of sender for token `_ids` is lower than the respective `_values` sent.
MUST throw on any other error.
When transfer is complete, this function MUST check if `_to` is a smart contract (code size > 0). If so, it MUST call `onERC1155BatchReceived` on `_to` and revert if the return value is not `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`.
@param _from Source address
@param _to Target address
Transfers and events MUST occur in the array order they were submitted (_ids[0] before _ids[1], etc).
@param _from Source addresses
@param _to Target addresses
@param _ids IDs of each token type
@param _values Transfer amounts per token type
@param _data Additional data with no specified format, sent in call to `_to`
*/
function safeBatchTransferFrom(address _from, address _to, uint256[] _ids, uint256[] _values, bytes _data) external;
function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external;
/**
@notice Get the balance of an account's Tokens.
@ -112,7 +121,7 @@ interface ERC1155 /* is ERC165 */ {
@param _ids ID of the Tokens
@return The _owner's balance of the Token types requested
*/
function balanceOfBatch(address[] _owners, uint256[] _ids) external view returns (uint256[]);
function balanceOfBatch(address[] calldata _owners, uint256[] calldata _ids) external view returns (uint256[] memory);
/**
@notice Enable or disable approval for a third party ("operator") to manage all of the caller's tokens.
@ -138,6 +147,8 @@ interface ERC1155 /* is ERC165 */ {
Smart contracts **MUST** implement this interface to accept transfers.
```solidity
pragma solidity ^0.5.2;
interface ERC1155TokenReceiver {
/**
@notice Handle the receipt of a single ERC1155 token type.
@ -145,14 +156,14 @@ interface ERC1155TokenReceiver {
This function MAY throw to revert and reject the transfer.
Return of other than the magic value MUST result in the transaction being reverted.
Note: The contract address is always the message sender.
@param _operator The address which called `safeTransferFrom` function
@param _operator The address which called the `safeTransferFrom` function
@param _from The address which previously owned the token
@param _id An array containing the ids of the token being transferred
@param _value An array containing the amount of tokens being transferred
@param _id The id of the token being transferred
@param _value The amount of tokens being transferred
@param _data Additional data with no specified format
@return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`
*/
function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes _data) external returns(bytes4);
function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4);
/**
@notice Handle the receipt of multiple ERC1155 token types.
@ -160,28 +171,32 @@ interface ERC1155TokenReceiver {
This function MAY throw to revert and reject the transfer.
Return of other than the magic value WILL result in the transaction being reverted.
Note: The contract address is always the message sender.
@param _operator The address which called `safeTransferFrom` function
@param _operator The address which called the `safeBatchTransferFrom` function
@param _from The address which previously owned the token
@param _ids An array containing ids of each token being transferred
@param _values An array containing amounts of each token being transferred
@param _data Additional data with no specified format
@return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`
*/
function onERC1155BatchReceived(address _operator, address _from, uint256[] _ids, uint256[] _values, bytes _data) external returns(bytes4);
function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4);
}
```
## 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 large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/0x7800000000000001000000000000000000000000000000000000000000000000.json` if the client is referring to token ID `0x7800000000000001000000000000000000000000000000000000000000000000`.
The URI value allows for ID substitution by clients. If the string `%s` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/%s.json` would be replaced with `https://token-cdn-domain/780000000000001e000000000000000000000000000000000000000000000000.json` if the client is referring to token ID `780000000000001e000000000000000000000000000000000000000000000000`.
The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix.
### Metadata Extensions
The following optional extensions can be identified with the (ERC-165 Standard Interface Detection)[https://github.com/ethereum/EIPs/blob/master/EIPS/eip-165.md].
Changes to the URI or Name MUST emit their corresponding events if the change can be expressed with an event. If the optional ERC1155Metadata_URI or ERC1155Metadata_Name extensions are included, the values returned by these functions SHOULD be used to retrieve values for which no event was emitted. The functions MUST return the same value as the event if it was emitted.
Changes to the URI MUST emit the `URI` event if the change can be expressed with an event. If the optional ERC1155Metadata_URI extension is included, the value returned by this function SHOULD be used to retrieve values for which no event was emitted. The function MUST return the same value as the event if it was emitted.
```solidity
pragma solidity ^0.5.2;
/**
Note: The ERC-165 identifier for this interface is 0x0e89341c.
*/
@ -192,24 +207,15 @@ interface ERC1155Metadata_URI {
The URI may point to a JSON file that conforms to the "ERC-1155 Metadata JSON Schema".
@return URI string
*/
function uri(uint256 _id) external view returns (string);
}
/**
Note: The ERC-165 identifier for this interface is 0x00ad800c.
*/
interface ERC1155Metadata_Name {
/**
@notice A human-readable name for a given token
@return Name string
*/
function name(uint256 _id) external view returns (string);
function uri(uint256 _id) external view returns (string memory);
}
```
### ERC-1155 Metadata URI JSON Schema
This JSON schema is loosely based on the "ERC721 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.
This JSON schema is loosely based on the "ERC721 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients. If the string `%s` exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard.
The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix.
```json
{
@ -246,7 +252,7 @@ An example of an ERC-1155 Metadata JSON file follows. The properties array propo
{
"name": "Asset Name",
"description": "Lorem ipsum...",
"image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/{id}.png",
"image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/%s.png",
"properties": {
"simple_property": "example value",
"rich_property": {
@ -269,6 +275,50 @@ An example of an ERC-1155 Metadata JSON file follows. The properties array propo
}
```
## Rationale
<details>
<summary>
Metadata Choices</summary>
The `symbol` function (found in the ERC-20 and ERC-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 ERC-1155 will already utilize JSON Metadata.
</details>
<details>
<summary>
Upgrades</summary>
The requirement to emit `TransferSingle` or `TransferBatch` on balance change implies that a valid implementation of ERC-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 ERC-1538. This will also have the added benefit of providing a stable contract address for users.
</details>
<details>
<summary>
Design decision: Supporting non-batch</summary>
The standard supports `safeTransferFrom` and `onERC1155Received` functions because they are significantly cheaper for single token-type transfers, which is arguably a common use case.
</details>
<details>
<summary>
Design decision: Safe transfers only</summary>
The standard only supports safe-style transfers, making it possible for receiver contracts to depend on `onERC1155Received` or `onERC1155BatchReceived` function to be always called at the end of a transfer.
</details>
<details>
<summary>
Guaranteed log trace</summary>
As the Ethereum ecosystem continues to grow, many dapps are relying on traditional databases and explorer API services to retrieve and categorize data. The ERC-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 ERC-1155 token in the contract.
</details>
## 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.
@ -279,7 +329,9 @@ Batch Operations</summary>
### Batch Transfers
The `safeBatchTransferFrom` function allows for batch transfers of multiple token ids and values. Gas savings improves with the number of token types in the batch transfer, compared to single transfers with multiple transactions.
The `safeBatchTransferFrom` function allows for batch transfers of multiple token ids and values. The design of ERC-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`.
### Batch Balance
@ -293,23 +345,7 @@ Approval</summary>
### Approval
Single-token based approval of specific token values has been dropped in favor of the function `setApprovalForAll` which allows an operator to manage one's entire set of tokens on behalf of the approver. To scope an approval to a specific set or quantity of tokens, we recommend deploying a contract that contains the desired rules, and directing end-users to approve this contract to manage their set of tokens.
</details>
<details>
<summary>
Backwards Compatibility</summary>
### Backwards Compatibility
This standard is compatible with ERC-721 non-fungible tokens. Both interfaces can be inherited without conflict:
```solidity
contract MultiTokens is ERC1155, ERC721 {
...
}
```
The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. Single-token based approval of specific token values is not part of the standard. To scope an approval to a specific set or quantity of tokens, we recommend deploying a contract that contains the desired rules, and directing end-users to approve this contract to manage their set of tokens.
</details>
@ -352,18 +388,21 @@ balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible tok
## References
**Standards**
- ERC-721 Non-Fungible Token Standard. https://raw.githubusercontent.com/ethereum/EIPs/master/EIPS/eip-721.md
- ERC-165 Standard Interface Detection. https://github.com/ethereum/EIPs/blob/master/EIPS/eip-165.md
- JSON Schema. http://json-schema.org/
- RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt
- [ERC-721 Non-Fungible Token Standard](https://raw.githubusercontent.com/ethereum/EIPs/master/EIPS/eip-721.md)
- [ERC-165 Standard Interface Detection](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-165.md)
- [ERC-1538 Transparent Contract Standard](https://github.com/ethereum/EIPs/issues/1538)
- [JSON Schema](http://json-schema.org/)
- [RFC 2119 Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt)
**Implementations**
- [ERC-1155 Reference Implementation](https://github.com/enjin/erc-1155)
- [Horizon Games - Multi-Token Standard](https://github.com/horizon-games/multi-token-standard)
- [Enjin Coin](https://enjincoin.io) ([github](https://github.com/enjin))
**Articles & Discussions**
- [Github - Original Discussion Thread](https://github.com/ethereum/EIPs/issues/1155)
- [ERC-1155 - The Crypto Item Standard](https://blog.enjincoin.io/erc-1155-the-crypto-item-standard-ac9cf1c5a226)
- [Here Be Dragons - Going Beyond ERC-20 and ERC-721 To Reduce Gas Cost by ~80%](https://medium.com/horizongames/going-beyond-erc20-and-erc721-9acebd4ff6ef)
- [Blockonomi - Ethereum ERC-1155 Token Perfect for Online Games, Possibly More](https://blockonomi.com/erc1155-gaming-token/)
- [Beyond Gaming - Exploring the Utility of ERC-1155 Token Standard!](https://blockgeeks.com/erc-1155-token/)