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-12-12 17:13:00 -08:00 committed by EIP Automerge Bot
parent 68a68d8f6f
commit 947a95e496
1 changed files with 123 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
EIPS/eip-1155.md
View File

@ -25,97 +25,81 @@ Tokens standards like ERC-20 and ERC-721 require a separate contract to be deplo
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.
### 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.
### 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.
### 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 {
...
}
```
# 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 ERC-1155 standard MUST implement the `ERC1155` and `ERC165` interfaces.**
```solidity
pragma solidity ^0.4.25;
/**
@title ERC-1155 Multi Token Standard
@dev Contracts implementing this standard MUST also implement ERC-165
Note: the ERC-165 identifier for this interface is 0xd9b67a26.
@dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md
Note: The ERC-165 identifier for this interface is 0xd9b67a26.
*/
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. This event supports single tokens.
A `TransferSingle` 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 `TransferSingle` event to address `0x0` signifies a burning or melting operation.
This MUST emit a 0 value, from `0x0` to `0x0` with `_operator` assuming the role of the token creator. This can be used to define a token ID with no initial balance at the time of creation.
@dev Either TransferSingle or TransferBatch MUST emit when tokens are transferred, including zero value transfers as well as minting or burning.
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.
*/
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. This event supports multiple _ids and _values.
A `TransferBatch` 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 `TransferBatch` event to address `0x0` signifies a burning or melting operation.
This MUST emit a 0 value, from `0x0` to `0x0` with `_operator` assuming the role of the token creator. This can be used to define a token ID with no initial balance at the time of creation.
*/
event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values);
/**
@dev MUST emit when an approval is updated
@dev MUST emit when an approval is updated.
*/
event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
/**
@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".
@dev MUST emit when the URI is updated for a token ID.
The URI MUST point a JSON file that conforms to the "ERC-1155 Metadata JSON Schema".
*/
event URI(string _value, uint256 indexed _id);
/**
@dev Emits when the Name is updated for a token 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.
@dev MUST emit TransferSingle event on success.
Caller must be approved to manage the _from account's tokens (see isApprovedForAll)
Throws if `_to` is the zero address.
Throws if `_id` is not a valid token ID.
When transfer is complete, this function checks if `_to` is a smart contract (code size > 0). If so, it calls `onERC1155Received` on `_to` and throws if the return value is not `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`.
@param _from source addresses
@param _to target addresses
@param _id ID of the Token
@param _value transfer amounts
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.
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 _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;
/**
@notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call)
@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 have a sufficient allowance by _from for each of the id/value pairs.
Throws on any error rather than return a false flag to minimize user errors.
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.
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
@param _ids Types of Tokens
@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;
/**
@notice Get the balance of an account's Tokens
@notice Get the balance of an account's Tokens.
@param _owner The address of the token holder
@param _id ID of the Token
@return The _owner's balance of the Token type requested
@ -123,7 +107,7 @@ interface ERC1155 /* is ERC165 */ {
function balanceOf(address _owner, uint256 _id) external view returns (uint256);
/**
@notice Get the balance of an account's Tokens, of multiple types
@notice Get the balance of multiple account/token pairs
@param _owners The addresses of the token holders
@param _ids ID of the Tokens
@return The _owner's balance of the Token types requested
@ -131,7 +115,7 @@ interface ERC1155 /* is ERC165 */ {
function balanceOfBatch(address[] _owners, uint256[] _ids) external view returns (uint256[]);
/**
@notice Enable or disable approval for a third party ("operator") to manage all of `msg.sender`'s tokens.
@notice Enable or disable approval for a third party ("operator") to manage all of the caller'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
@ -151,16 +135,16 @@ interface ERC1155 /* is ERC165 */ {
## ERC-1155 Token Receiver
Smart contracts **MUST** implement this interface to accept safe transfers.
Smart contracts **MUST** implement this interface to accept transfers.
```solidity
interface ERC1155TokenReceiver {
/**
@notice Handle the receipt of a single ERC1155 token type
@dev The smart contract calls this function on the recipient after a `safeTransferFrom`.
@notice Handle the receipt of a single ERC1155 token type.
@dev An ERC1155-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 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.
Note: The contract address is always the message sender.
@param _operator The address which called `safeTransferFrom` function
@param _from The address which previously owned the token
@param _id An array containing the ids of the token being transferred
@ -171,11 +155,11 @@ interface ERC1155TokenReceiver {
function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes _data) external returns(bytes4);
/**
@notice Handle the receipt of multiple ERC1155 token types
@dev A ERC1155-compliant smart contract MUST call this function on the token recipient contract at the end of a `safeBatchTransferFrom` after the balance have been updated.
@notice Handle the receipt of multiple ERC1155 token types.
@dev An ERC1155-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 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.
Note: The contract address is always the message sender.
@param _operator The address which called `safeTransferFrom` function
@param _from The address which previously owned the token
@param _ids An array containing ids of each token being transferred
@ -187,15 +171,9 @@ interface ERC1155TokenReceiver {
}
```
## 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 TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block.
ERC-1155 contracts must therefore carefully emit TransferSingle or TransferBatch events in any instance where tokens are created, minted, or destroyed.
## 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. 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`
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`.
### Metadata Extensions
@ -204,15 +182,22 @@ The following optional extensions can be identified with the (ERC-165 Standard I
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.
```solidity
/**
Note: The ERC-165 identifier for this interface is 0x0e89341c.
*/
interface ERC1155Metadata_URI {
/**
@notice A distinct Uniform Resource Identifier (URI) for a given token
@dev URIs are defined in RFC 3986
@notice A distinct Uniform Resource Identifier (URI) for a given token.
@dev URIs are defined in RFC 3986.
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
@ -284,17 +269,69 @@ An example of an ERC-1155 Metadata JSON file follows. The properties array propo
}
```
## 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.
<details>
<summary>
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.
### Batch Balance
The `balanceOfBatch` function allows clients to retrieve balances of multiple owners and token ids with a single call.
</details>
<details>
<summary>
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 {
...
}
```
</details>
<details>
<summary>
Enumeration</summary>
### 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 TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block.
ERC-1155 contracts must therefore carefully emit TransferSingle or TransferBatch events in any instance where tokens are created, minted, or destroyed.
</details>
<details>
<summary>
Non-Fungible Tokens</summary>
### Usage Intention
### Non-Fungible Tokens
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.
The following strategy is an example of how to mix fungible and non-fungible tokens together in the same contract. The top 128 bits of the uint256 `_id` parameter in any ERC-1155 function could represent the base token ID, while the bottom 128 bits might be used for any extra data passed to the contract.
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 particular NFT within that set, `_id` could be passed as `<uint128: base token id><uint128: index of NFT>`.
@ -312,10 +349,23 @@ balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible tok
</details>
## Implementation
## 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
**Implementations**
- [ERC-1155 Reference Implementation](https://github.com/enjin/erc-1155)
- [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)
- [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/)
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).