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-10-19 19:34:43 -07:00 committed by EIP Automerge Bot
parent 379438bd2e
commit ff95e31eea
1 changed files with 152 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

376
EIPS/eip-1155.md
View File

@ -1,6 +1,6 @@
---
eip: 1155
title: Crypto Item Standard
title: Multi Token Standard
author: Witek Radomski <witek@enjin.com>, Andrew Cooke <andrew@enjin.com>
type: Standards Track
category: ERC
@ -11,285 +11,206 @@ discussions-to: https://github.com/ethereum/EIPs/issues/1155
## Simple Summary
A standard interface for multiple item/token definitions in a single deployed contract.
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 (for example, semi-fungible tokens).
## 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 Crypto Item Standard allows for each Item 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 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.
The `_id` parameter is contained in each function's parameters and indicates a specific item or item type in a transaction.
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 tens of thousands of items, 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 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.
New functionality is possible with this design, such as transferring or approving 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 tokens separately. It is also easy to describe and mix multiple fungible or non-fungible tokens in a single contract.
## Specification
### 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.
### 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
```solidity
pragma solidity ^0.4.24;
/**
@title ERC-1155 Crypto Items Standard
@dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-721.md
Note: the ERC-165 identifier for this interface is 0xf23a6e61.
@title ERC-1155 Multi Token Standard
@dev Note: the ERC-165 identifier for this interface is 0xf23a6e61.
*/
interface IERC1155 {
interface ERC1155 {
/**
@dev MUST trigger on any successful call to approve(address _spender, uint256 _value)
*/
event Approval(address indexed _owner, address indexed _spender, uint256 indexed _id, uint256 _oldValue, uint256 _value);
/**
@dev MUST trigger when tokens are transferred, including zero value transfers
This emits when ownership of any NFT changes by any mechanism.
This event emits when NFTs are created (`from` == 0) and destroyed
(`to` == 0). Exception: during contract creation, any number of NFTs
may be created and assigned without emitting Transfer. At the time of
any transfer, the approved address for that NFT (if any) is reset to none.
@dev MUST emit when tokens are transferred, including zero value transfers
*/
event Transfer(address _spender, address indexed _from, address indexed _to, uint256 indexed _id, uint256 _value);
/**
@dev 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.
Caller must have a sufficient allowance by _from for the _id/_value pair
@param _from source addresses
@param _to target addresses
@param _id ID of the CryptoItem
@param _value transfer amounts
@dev MUST emit on any successful call to approve(address _spender, uint256 _id, uint256 _currentValue, uint256 _value)
*/
function transferFrom(address _from, address _to, uint256 _id, uint256 _value) external;
event Approval(address indexed _owner, address indexed _spender, uint256 indexed _id, uint256 _oldValue, uint256 _value);
/**
@dev 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.
Caller must have a sufficient allowance by _from for the _id/_value pair
@dev MUST emit on any successful call to setApprovalForAll(address _operator, bool _approved)
*/
event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
/**
@dev Emits when the URI is updated for a token ID
*/
event URI(uint256 indexed _id, string _value);
/**
@dev Emits when the Name is updated for a token ID
*/
event Name(uint256 indexed _id, string _value);
/**
@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 Transfer event on success.
Caller must have sufficient allowance by _from for the _id/_value pair, or isApprovedForAll must be true.
Throws if `_to` is the zero address.
Throws if `_id` is not a valid NFT.
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 CryptoItem
@param _id ID of the Token
@param _value transfer amounts
@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;
/**
@dev Allow other accounts/contracts to spend tokens on behalf of msg.sender
Also, 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
@notice Send multiple types of Tokens from a 3rd party in one transfer (with safety call)
@dev MUST emit Transfer event per id 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.
@param _from Source address
@param _to Target address
@param _ids Types of Tokens
@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 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 CryptoItem
@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;
/**
@dev Get the balance of an account's CryptoItems
@param _id ID of the CryptoItem
@notice Get the balance of an account's Tokens
@param _id ID of the Token
@param _owner The address of the token holder
@return The _owner's balance of the CryptoItem type requested
@return The _owner's balance of the Token type requested
*/
function balanceOf(uint256 _id, address _owner) external view returns (uint256);
/**
@dev Queries the spending limit approved for an account
@param _id ID of the CryptoItem
@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 CryptoItem requested
@return The _spender's allowed spending balance of the Token requested
*/
function allowance(uint256 _id, address _owner, address _spender) external view returns (uint256);
}
```
<details>
<summary>
Simple/Extended Transfers</summary>
```solidity
interface IERC1155Extended {
/**
@dev Send a single type of CryptoItem
@param _to Transfer destination address
@param _id ID of the CryptoItem
@param _value Transfer amount
*/
function transfer(address _to, uint256 _id, uint256 _value) external;
/**
@dev Send a single type of CryptoItem (with safety call)
@param _to Transfer destination address
@param _id ID of the CryptoItem
@param _value Transfer amount
@param _data Additional data with no specified format, sent in call to `_to`
*/
function safeTransfer(address _to, uint256 _id, uint256 _value, bytes _data) external;
}
```
</details>
<details>
<summary>
Batch Transfers</summary>
```solidity
interface IERC1155BatchTransfer {
/**
@dev Send multiple types of CryptoItems from a 3rd party in one transfer
For the purpose of transfer fees, each id/value pair is counted as a transfer
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
@param _from Source address
@param _to Target address
@param _ids Types of CryptoItems
@param _values Transfer amounts per item type
*/
function batchTransferFrom(address _from, address _to, uint256[] _ids, uint256[] _values) external;
/**
@dev Send multiple types of CryptoItems from a 3rd party in one transfer (with safety call)
For the purpose of transfer fees, each id/value pair is counted as a transfer
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
@param _from Source address
@param _to Target address
@param _ids Types of CryptoItems
@param _values Transfer amounts per item 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;
/**
@dev Allow other accounts/contracts to spend tokens on behalf of msg.sender
Also, 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 _ids IDs of the CryptoItems
@param _currentValues Expected current values of allowances per item type
@param _values Allowance amounts per item type
*/
function batchApprove(address _spender, uint256[] _ids, uint256[] _currentValues, uint256[] _values) external;
}
```
</details>
<details>
<summary>
Simple/Extended Batch Transfers</summary>
```solidity
interface IERC1155BatchTransferExtended {
/**
@dev Send multiple types of CryptoItems in one transfer
For the purpose of transfer fees, each id/value pair is counted as a transfer
@param _to Transfer destination address
@param _ids IDs of the CryptoItems
@param _values Transfer amounts per item type
*/
function batchTransfer(address _to, uint256[] _ids, uint256[] _values) external;
/**
@dev Send multiple types of CryptoItems in one transfer (with safety call)
For the purpose of transfer fees, each id/value pair is counted as a transfer
@param _to Transfer destination address
@param _ids IDs of the CryptoItems
@param _values Transfer amounts per item type
@param _data Additional data with no specified format, sent in call to `_to`
*/
function safeBatchTransfer(address _to, uint256[] _ids, uint256[] _values, bytes _data) external;
}
```
</details>
<details>
<summary>
Extended Approvals</summary>
```solidity
interface IERC1155Operators {
event OperatorApproval(address indexed _owner, address indexed _operator, uint256 indexed _id, bool _approved);
event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
/**
@notice Enable or disable approval for a third party ("operator") to manage
all of `msg.sender`'s assets for a particular CryptoItem types.
@dev Emits the OperatorApproval event
@param _operator Address to add to the set of authorized operators
@param _ids The IDs of the CryptoItems
@param _approved True if the operators is approved, false to revoke approval
*/
function setApproval(address _operator, uint256[] _ids, bool _approved) external;
/**
@dev Queries the approval status of an operator for a given CryptoItem and owner
@param _owner The owner of the CryptoItems
@param _operator Address of authorized operator
@param _id ID of the CryptoItem
@return True if the operator is approved, false if not
*/
function isApproved(address _owner, address _operator, uint256 _id) external view returns (bool);
/**
@notice Enable or disable approval for a third party ("operator") to manage
all of `msg.sender`'s assets.
@dev Emits the OperatorApproval event
@notice Enable or disable approval for a third party ("operator") to manage all of `msg.sender`'s assets.
@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
*/
function setApprovalForAll(address _operator, bool _approved) external;
/**
@dev Queries the approval status of an operator for a given CryptoItem and owner
@param _owner The owner of the CryptoItems
@notice Queries the approval status of an operator for a given Token and owner
@param _owner The owner of the Tokens
@param _operator Address of authorized operator
@return True if the operator is approved, false if not
*/
function isApprovedForAll(address _owner, address _operator) external view returns (bool isOperator);
}
```
</details>
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>
<summary>
Multicast Transfers</summary>
### Multicast Transfers
The `ERC1155Multicast` extension allows for multicast transfers to and from multiple addresses. It's also possible to create a simple atomic swap using this function by first obtaining approvals from the source and destination parties.
```solidity
interface ERC1155Multicast {
/**
@dev Send multiple types of Tokens in one transfer from multiple sources.
@param _from Source addresses
@param _to Transfer destination addresses
@param _ids Types of Tokens
@param _values Transfer amounts
*/
function multicastTransferFrom(address[] _from, address[] _to, uint256[] _ids, uint256[] _values) external;
}
```
</details>
<details>
<summary>
Views</summary>
Token ID Approval</summary>
```solidity
interface IERC1155Views {
interface ERC1155Operators {
event OperatorApproval(address indexed _owner, address indexed _operator, uint256 indexed _id, bool _approved);
/**
@dev Returns how many of a CryptoItem are deemed or expected to exist in circulation
@param _id ID of the CryptoItem
@return The number of CryptoItems in circulation
*/
function totalSupply(uint256 _id) external view returns (uint256);
@notice Enable or disable approval for a third party ("operator") to manage
all of `msg.sender`'s assets for a particular Token types.
@dev Emits the OperatorApproval event
@param _operator Address to add to the set of authorized operators
@param _ids The IDs of the Tokens
@param _approved True if the operators is approved, false to revoke approval
*/
function setApproval(address _operator, uint256[] _ids, bool _approved) external;
/**
@dev Returns a human readable string that identifies a CryptoItem, similar to ERC20
@param _id ID of the CryptoItem
@return The name of the CryptoItem type
*/
function name(uint256 _id) external view returns (string);
/**
@dev Returns symbol of a CryptoItem, similar to ERC20 and ERC721
@param _id ID of the CryptoItem
@return The symbol of the CryptoItem
*/
function symbol(uint256 _id) external view returns (string);
/**
@dev Returns the number of decimal places for a CryptoItem, similar to ERC20
@param _id ID of the CryptoItem
@return Number of decimals
*/
function decimals(uint256 _id) external view returns (uint8);
@notice Queries the approval status of an operator for a given Token and owner
@param _owner The owner of the Tokens
@param _operator Address of authorized operator
@param _id ID of the Token
@return True if the operator is approved, false if not
*/
function isApproved(address _owner, address _operator, uint256 _id) external view returns (bool);
}
```
</details>
<details>
<summary>
Metadata / Views</summary>
```solidity
interface ERC1155MetadataURI {
/**
@notice A distinct Uniform Resource Identifier (URI) for a given asset
@dev URIs are defined in RFC 3986
@ -297,27 +218,36 @@ interface IERC1155Views {
*/
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);
}
```
</details>
<details>
<summary>
ERC-1155 Token Receiver</summary>
## ERC-1155 Token Receiver
Smart contracts **MUST** implement this interface to accept safe transfers.
```solidity
interface IERC1155TokenReceiver {
interface ERC1155TokenReceiver {
/**
@notice Handle the receipt of an ERC1155 type
@dev The smart contract calls this function on the recipient
after a `safeTransfer`. This function MAY throw to revert and reject the
after a `safeTransferFrom`. 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 _from The address which previously owned the token
@param _id The identifier of the item being transferred
@param _value The amount of the item being transferred
@param _id The identifier of the token being transferred
@param _value The amount of the token being transferred
@param _data Additional data with no specified format
@return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`
*/
@ -325,24 +255,22 @@ interface IERC1155TokenReceiver {
}
```
</details>
<details>
<summary>
Non-Fungible Tokens</summary>
## Non-Fungible Items
### Discussion
An example strategy to mix Fungible and Non-Fungible Items together in the same contract would be to pass the base item ID in the top 128 bits of the uint256 `_itemID` parameter and then use the bottom 128 bits for any extra data you wish to pass to the contract.
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.
Non-Fungible Items can be interacted with using an index based accessor into the contract/item data set. Therefore to access a particular item set within a mixed data contract and particular NFT within that set, `_itemID` could be passed as `<uint128: base item id><uint128: index of NFT>`.
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>`.
Inside the contract code the two pieces of data needed to access the individual NFT can be extracted with uint128(~0) and the same mask shifted by 128.
### Interface
<details>
<summary>
Optional Non Fungible Interface</summary>
```solidity
interface IERC1155NonFungible {
interface ERC1155NonFungible {
/**
@notice Find the owner of an NFT
@dev NFTs assigned to zero address are considered invalid, and queries about them do throw
@ -379,8 +307,6 @@ interface IERC1155NonFungible {
}
```
</details>
### Example of split ID bits
```solidity
@ -391,6 +317,8 @@ balanceOf(baseToken, msg.sender); // Get balance of the base token
balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible token index
```
</details>
## Implementation
- [ERC-1155 Reference Implementation](https://github.com/enjin/erc-1155)