status-im
/
EIPs
mirror of https://github.com/status-im/EIPs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Automatically merged updates to draft EIP(s) 1155 

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 2018-11-01 22:54:01 -07:00 committed by EIP Automerge Bot
parent 8b19b7e2db
commit ab2c2125af
1 changed files with 125 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

195
EIPS/eip-1155.md
View File

@ -1,7 +1,7 @@
---
eip: 1155
title: Multi Token Standard
author: Witek Radomski <witek@enjin.com>, Andrew Cooke <andrew@enjin.com>
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>
type: Standards Track
category: ERC
status: Draft
@ -15,7 +15,7 @@ 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 assets 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. Instead, the ERC-1155 Multi Token Standard allows for each Token ID to represent a new configurable token type, which may have its own totalSupply value and other such attributes.
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.
The `_id` parameter is contained in each function's parameters and indicates a specific token or token type in a transaction.
@ -42,7 +42,7 @@ contract MultiTokens is ERC1155, ERC721 {
# Specification
```solidity
pragma solidity ^0.4.24;
pragma solidity ^0.4.25;
/**
@title ERC-1155 Multi Token Standard
@ -50,14 +50,12 @@ pragma solidity ^0.4.24;
*/
interface ERC1155 {
/**
@dev MUST emit when tokens are transferred, including zero value transfers
@dev MUST emit when tokens are transferred, including zero value transfers as well as minting or burning.
A `Transfer` event from address `0x0` signifies a minting 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
A `Transfer` event to address `0x0` signifies a burning or melting operation.
This MUST emit a zero value, from `0x0` to the creator's address if a token has no initial balance but is being defined/created.
*/
event Transfer(address _spender, address indexed _from, address indexed _to, uint256 indexed _id, uint256 _value);
/**
@dev MUST emit on any successful call to approve(address _spender, uint256 _id, uint256 _currentValue, uint256 _value)
*/
event Approval(address indexed _owner, address indexed _spender, uint256 indexed _id, uint256 _oldValue, uint256 _value);
/**
@dev MUST emit on any successful call to setApprovalForAll(address _operator, bool _approved)
@ -65,7 +63,8 @@ interface ERC1155 {
event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
/**
@dev Emits when the URI is updated for a token ID
@dev Emits when the URI is updated for a token ID.
The URI may point to a JSON file that conforms to the "ERC-1155 Metadata JSON Schema".
*/
event URI(uint256 indexed _id, string _value);
@ -102,17 +101,6 @@ interface ERC1155 {
*/
function safeBatchTransferFrom(address _from, address _to, uint256[] _ids, uint256[] _values, bytes _data) external;
/**
@notice Allow other accounts/contracts to spend tokens on behalf of msg.sender
@dev MUST emit Approval event on success.
To minimize the risk of the approve/transferFrom attack vector (see https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/), this function will throw if the current approved allowance does not equal the expected _currentValue, unless _value is 0.
@param _spender Address to approve
@param _id ID of the Token
@param _currentValue Expected current value of approved allowance.
@param _value Allowance amount
*/
function approve(address _spender, uint256 _id, uint256 _currentValue, uint256 _value) external;
/**
@notice Get the balance of an account's Tokens
@param _id ID of the Token
@ -122,16 +110,7 @@ interface ERC1155 {
function balanceOf(uint256 _id, address _owner) external view returns (uint256);
/**
@notice Queries the spending limit approved for an account
@param _id ID of the Token
@param _owner The owner allowing the spending
@param _spender The address allowed to spend.
@return The _spender's allowed spending balance of the Token requested
*/
function allowance(uint256 _id, address _owner, address _spender) external view returns (uint256);
/**
@notice Enable or disable approval for a third party ("operator") to manage all of `msg.sender`'s assets.
@notice Enable or disable approval for a third party ("operator") to manage all of `msg.sender`'s tokens.
@dev MUST emit the ApprovalForAll event on success.
@param _operator Address to add to the set of authorized operators
@param _approved True if the operator is approved, false to revoke approval
@ -149,6 +128,14 @@ interface ERC1155 {
```
</details>
## Enumerating from events
In order to keep storage requirements light for contracts implementing ERC-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 Transfer and URI event, starting from the block the smart contract was deployed until the latest block.
ERC-1155 contracts must therefore carefully emit Transfer events in any instance where tokens are created, minted, or destroyed.
## Optional 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].
<details>
@ -167,8 +154,48 @@ interface ERC1155Multicast {
@param _to Transfer destination addresses
@param _ids Types of Tokens
@param _values Transfer amounts
@param _data Additional data with no specified format, sent in call to each `_to[]` address
*/
function multicastTransferFrom(address[] _from, address[] _to, uint256[] _ids, uint256[] _values) external;
function safeMulticastTransferFrom(address[] _from, address[] _to, uint256[] _ids, uint256[] _values, bytes[] _data) external;
}
```
</details>
<details>
<summary>
Single Approval</summary>
### Single Approval
With the `ERC1155Approval` extension, an account may allow specific quantities of tokens to be spent on its behalf using the `safeTransferFrom`, `safeBatchTransferFrom`, or `safeMulticastTransferFrom` functions.
```solidity
interface ERC1155Approval {
/**
@dev MUST emit on any successful call to approve(address _spender, uint256 _id, uint256 _currentValue, uint256 _value)
*/
event Approval(address indexed _owner, address indexed _spender, uint256 indexed _id, uint256 _oldValue, uint256 _value);
/**
@notice Allow other accounts/contracts to spend tokens on behalf of msg.sender
@dev MUST emit Approval event on success.
To minimize the risk of the approve/transferFrom attack vector (see https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/), this function will throw if the current approved allowance does not equal the expected _currentValue, unless _value is 0.
@param _spender Address to approve
@param _id ID of the Token
@param _currentValue Expected current value of approved allowance.
@param _value Allowance amount
*/
function approve(address _spender, uint256 _id, uint256 _currentValue, uint256 _value) external;
/**
@notice Queries the spending limit approved for an account
@param _id ID of the Token
@param _owner The owner allowing the spending
@param _spender The address allowed to spend.
@return The _spender's allowed spending balance of the Token requested
*/
function allowance(uint256 _id, address _owner, address _spender) external view returns (uint256);
}
```
@ -184,7 +211,7 @@ interface ERC1155Operators {
/**
@notice Enable or disable approval for a third party ("operator") to manage
all of `msg.sender`'s assets for a particular Token types.
all of `msg.sender`'s Tokens for particular ids.
@dev Emits the OperatorApproval event
@param _operator Address to add to the set of authorized operators
@param _ids The IDs of the Tokens
@ -207,25 +234,75 @@ interface ERC1155Operators {
<details>
<summary>
Metadata / Views</summary>
Metadata</summary>
```solidity
interface ERC1155MetadataURI {
interface ERC1155Metadata {
/**
@notice A distinct Uniform Resource Identifier (URI) for a given asset
@notice A distinct Uniform Resource Identifier (URI) for a given token
@dev URIs are defined in RFC 3986
@return URI string
*/
function uri(uint256 _id) external view returns (string);
}
```
interface ERC1155MetadataName {
/**
@notice Returns a human readable string that identifies a Token, similar to ERC20
@param _id ID of the Token
@return The name of the Token type
*/
function name(uint256 _id) external view returns (string);
## ERC-1155 Metadata JSON Schema
Tokens may either emit URI events or expose the uri() function to indicate that they have metadata available.
This JSON schema is loosely based on the "ERC721 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients.
```json
{
"title": "Token Metadata",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Identifies the asset to which this token represents",
},
"description": {
"type": "string",
"description": "Describes the asset to which this token represents",
},
"image": {
"type": "string",
"description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive.",
},
"properties": {
"type": "object",
"description": "Arbitrary properties. Values may be strings, numbers, object or arrays.",
},
}
}
```
An example of an ERC-1155 Metadata JSON file follows. The properties array proposes some SUGGESTED formatting for token-specific display properties and metadata.
```json
{
"name": "Asset Name",
"description": "Lorem ipsum...",
"image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/{id}.png",
"properties": {
"simple_property": "example value",
"rich_property": {
"name": "Name",
"value": "123",
"display_value": "123 Example Value",
"class": "emphasis",
"css": {
"color": "#ffffff",
"font-weight": "bold",
"text-decoration": "underline"
}
},
"array_property": {
"name": "Name",
"value": [1,2,3,4],
"class": "emphasis"
}
}
}
```
@ -259,7 +336,11 @@ interface ERC1155TokenReceiver {
<summary>
Non-Fungible Tokens</summary>
### Discussion
### Usage Intention
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.
#### Non-Fungible Example
An example strategy to mix Fungible and Non-Fungible tokens together in the same contract would be to pass the base token ID in the top 128 bits of the uint256 `_id` parameter and then use the bottom 128 bits for any extra data you wish to pass to the contract.
@ -271,32 +352,6 @@ Inside the contract code the two pieces of data needed to access the individual
```solidity
interface ERC1155NonFungible {
/**
@notice Find the owner of an NFT
@dev NFTs assigned to zero address are considered invalid, and queries about them do throw
@param _id The identifier for an NFT
@return The address of the owner of the NFT
*/
function ownerOf(uint256 _id) external view returns (address);
/**
@notice Enumerate valid NFs
@dev Throws if `_index` >= `totalSupply()`.
@param _index A counter less than `totalSupply()`
@return The token identifier for the `_index`th NFT (sort order not specified)
*/
function nonFungibleByIndex(uint256 _id, uint128 _index) external view returns (uint256);
/**
@notice Enumerate NFTs assigned to an owner
@dev Throws if `_index` >= `balanceOf(_owner)` or if
`_owner` is the zero address, representing invalid NFTs
@param _owner An address where we are interested in NFTs owned by them
@param _index A counter less than `balanceOf(_owner)`
@return The token identifier for the `_index`th NFT assigned to `_owner` (sort order not specified)
*/
function nonFungibleOfOwnerByIndex(uint256 _id, address _owner, uint128 _index) external view returns (uint256);
/**
@notice Is this token non fungible?
@dev If this returns true, the token is non-fungible.