2
0
mirror of https://github.com/status-im/EIPs.git synced 2025-02-13 15:26:50 +00:00
Witek ab2c2125af 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
2018-11-02 05:54:01 +00:00

17 KiB

eip title author type category status created discussions-to
1155 Multi Token Standard 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> Standards Track ERC Draft 2018-06-17 https://github.com/ethereum/EIPs/issues/1155

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 (for example, semi-fungible tokens).

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.

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, 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.

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:

contract MultiTokens is ERC1155, ERC721 {
    ...
}

Specification

pragma solidity ^0.4.25;

/**
    @title ERC-1155 Multi Token Standard
    @dev Note: the ERC-165 identifier for this interface is 0xf23a6e61.
 */
interface ERC1155 {
    /**
        @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 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.
        The URI may point to a JSON file that conforms to the "ERC-1155 Metadata JSON Schema".
    */
    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 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
        @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)
        @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 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 Token type requested
     */
    function balanceOf(uint256 _id, address _owner) external view returns (uint256);
    
    /**
        @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
    */
    function setApprovalForAll(address _operator, bool _approved) external;
    
    /** 
        @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);
}

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].

Multicast Transfers

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.

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
        @param _data    Additional data with no specified format, sent in call to each `_to[]` address
    */
    function safeMulticastTransferFrom(address[] _from, address[] _to, uint256[] _ids, uint256[] _values, bytes[] _data) external;
}
Single Approval

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.

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);
}
Token ID Approval
interface ERC1155Operators {
    event OperatorApproval(address indexed _owner, address indexed _operator, uint256 indexed _id, bool _approved);

    /**
        @notice Enable or disable approval for a third party ("operator") to manage
        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
        @param _approved  True if the operators is approved, false to revoke approval
    */
    function setApproval(address _operator, uint256[] _ids, bool _approved) external;
    
    /**
        @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);
}
Metadata
interface ERC1155Metadata {
    /**
        @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);
}

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.

{
    "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.

{
	"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"
		}
	}
}

ERC-1155 Token Receiver

Smart contracts MUST implement this interface to accept safe transfers.

interface ERC1155TokenReceiver {
    /**
        @notice Handle the receipt of an ERC1155 type
        @dev The smart contract calls this function on the recipient
        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 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)"))`
    */
    function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes _data) external returns(bytes4);
}
Non-Fungible Tokens

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.

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

interface ERC1155NonFungible {
    /**
        @notice Is this token non fungible?
        @dev If this returns true, the token is non-fungible.
        @param _id  The identifier for a potential non-fungible.
        @return     True if the token is non-fungible
    */
    function isNonFungible(uint256 _id) external view returns (bool);
}

Example of split ID bits

uint256 baseToken = 12345 << 128;
uint128 index = 50;

balanceOf(baseToken, msg.sender); // Get balance of the base token
balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible token index

Implementation

Copyright and related rights waived via CC0.