ERC: Multi Token Standard

[coinfork]

---
eip: 1155
title: ERC-1155 Multi Token Standard
author: Witek Radomski <[email protected]>, Andrew Cooke <[email protected]>, Philippe Castonguay <[email protected]>, James Therien <[email protected]>, Eric Binet <[email protected]>, Ronan Sandford <[email protected]>
type: Standards Track
category: ERC
status: Final
created: 2018-06-17
discussions-to: https://github.com/ethereum/EIPs/issues/1155
requires: 165
---

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 (e.g. semi-fungible tokens).

Abstract

This standard outlines a smart contract interface that can represent any number of fungible and non-fungible token types. 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 argument contained in each function's argument set 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 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 token types in a single contract.

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 all of the functions in the ERC1155 interface.

Smart contracts implementing the ERC-1155 standard MUST implement the ERC-165 supportsInterface function and MUST return the constant value true if 0xd9b67a26 is passed through the interfaceID argument.

pragma solidity ^0.5.9;

/**
    @title ERC-1155 Multi Token Standard
    @dev See https://eips.ethereum.org/EIPS/eip-1155
    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 (see "Safe Transfer Rules" section of the standard).
        The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
        The `_from` argument MUST be the address of the holder whose balance is decreased.
        The `_to` argument MUST be the address of the recipient whose balance is increased.
        The `_id` argument MUST be the token type being transferred.
        The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.
        When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).
        When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address).        
    */
    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 (see "Safe Transfer Rules" section of the standard).      
        The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
        The `_from` argument MUST be the address of the holder whose balance is decreased.
        The `_to` argument MUST be the address of the recipient whose balance is increased.
        The `_ids` argument MUST be the list of tokens being transferred.
        The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by.
        When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).
        When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address).                
    */
    event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values);

    /**
        @dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absence of an event assumes disabled).        
    */
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);

    /**
        @dev MUST emit when the URI is updated for a token ID.
        URIs are defined in RFC 3986.
        The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema".
    */
    event URI(string _value, uint256 indexed _id);

    /**
        @notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call).
        @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
        MUST revert if `_to` is the zero address.
        MUST revert if balance of holder for token `_id` is lower than the `_value` sent.
        MUST revert on any other error.
        MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard).
        After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).        
        @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, MUST be sent unaltered in call to `onERC1155Received` on `_to`
    */
    function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external;

    /**
        @notice Transfers `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with safety call).
        @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard).
        MUST revert if `_to` is the zero address.
        MUST revert if length of `_ids` is not the same as length of `_values`.
        MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient.
        MUST revert on any other error.        
        MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard).
        Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc).
        After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard).                      
        @param _from    Source address
        @param _to      Target address
        @param _ids     IDs of each token type (order and length must match _values array)
        @param _values  Transfer amounts per token type (order and length must match _ids array)
        @param _data    Additional data with no specified format, MUST be sent unaltered in call to the `ERC1155TokenReceiver` hook(s) on `_to`
    */
    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.
        @param _owner  The address of the token holder
        @param _id     ID of the token
        @return        The _owner's balance of the token type requested
     */
    function balanceOf(address _owner, uint256 _id) external view returns (uint256);

    /**
        @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 (i.e. balance for each (owner, id) pair)
     */
    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.
        @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 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);
}

ERC-1155 Token Receiver

Smart contracts MUST implement all of the functions in the ERC1155TokenReceiver interface to accept transfers. See "Safe Transfer Rules" for further detail.

Smart contracts MUST implement the ERC-165 supportsInterface function and signify support for the ERC1155TokenReceiver interface to accept transfers. See "ERC1155TokenReceiver ERC-165 rules" for further detail.

pragma solidity ^0.5.9;

/**
    Note: The ERC-165 identifier for this interface is 0x4e2312e0.
*/
interface ERC1155TokenReceiver {
    /**
        @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 MUST return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` (i.e. 0xf23a6e61) if it accepts the transfer.
        This function MUST revert if it rejects the transfer.
        Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller.
        @param _operator  The address which initiated the transfer (i.e. msg.sender)
        @param _from      The address which previously owned the token
        @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 calldata _data) external returns(bytes4);

    /**
        @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 MUST return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` (i.e. 0xbc197c81) if it accepts the transfer(s).
        This function MUST revert if it rejects the transfer(s).
        Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller.
        @param _operator  The address which initiated the batch transfer (i.e. msg.sender)
        @param _from      The address which previously owned the token
        @param _ids       An array containing ids of each token being transferred (order and length must match _values array)
        @param _values    An array containing amounts of each token being transferred (order and length must match _ids array)
        @param _data      Additional data with no specified format
        @return           `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`
    */
    function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4);       
}

Safe Transfer Rules

To be more explicit about how the standard safeTransferFrom and safeBatchTransferFrom functions MUST operate with respect to the ERC1155TokenReceiver hook functions, a list of scenarios and rules follows.

Scenarios

Scenario#1 : The recipient is not a contract.

• onERC1155Received and onERC1155BatchReceived MUST NOT be called on an EOA (Externally Owned Account).

Scenario#2 : The transaction is not a mint/transfer of a token.

• onERC1155Received and onERC1155BatchReceived MUST NOT be called outside of a mint or transfer process.

Scenario#3 : The receiver does not implement the necessary ERC1155TokenReceiver interface function(s).

• The transfer MUST be reverted with the one caveat below.
  • If the token(s) being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Compatibility with other standards" section.

Scenario#4 : The receiver implements the necessary ERC1155TokenReceiver interface function(s) but returns an unknown value.

• The transfer MUST be reverted.

Scenario#5 : The receiver implements the necessary ERC1155TokenReceiver interface function(s) but throws an error.

• The transfer MUST be reverted.

Scenario#6 : The receiver implements the ERC1155TokenReceiver interface and is the recipient of one and only one balance change (e.g. safeTransferFrom called).

• The balances for the transfer MUST have been updated before the ERC1155TokenReceiver hook is called on a recipient contract.
• The transfer event MUST have been emitted to reflect the balance changes before the ERC1155TokenReceiver hook is called on the recipient contract.
• One of onERC1155Received or onERC1155BatchReceived MUST be called on the recipient contract.
• The onERC1155Received hook SHOULD be called on the recipient contract and its rules followed.
  • See "onERC1155Received rules" for further rules that MUST be followed.
• The onERC1155BatchReceived hook MAY be called on the recipient contract and its rules followed.
  • See "onERC1155BatchReceived rules" for further rules that MUST be followed.

Scenario#7 : The receiver implements the ERC1155TokenReceiver interface and is the recipient of more than one balance change (e.g. safeBatchTransferFrom called).

• All balance transfers that are referenced in a call to an ERC1155TokenReceiver hook MUST be updated before the ERC1155TokenReceiver hook is called on the recipient contract.
• All transfer events MUST have been emitted to reflect current balance changes before an ERC1155TokenReceiver hook is called on the recipient contract.
• onERC1155Received or onERC1155BatchReceived MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for.
  • The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules".
• The onERC1155BatchReceived hook SHOULD be called on the recipient contract and its rules followed.
  • See "onERC1155BatchReceived rules" for further rules that MUST be followed.
• The onERC1155Received hook MAY be called on the recipient contract and its rules followed.
  • See "onERC1155Received rules" for further rules that MUST be followed.

Scenario#8 : You are the creator of a contract that implements the ERC1155TokenReceiver interface and you forward the token(s) onto another address in one or both of onERC1155Received and onERC1155BatchReceived.

• Forwarding should be considered acceptance and then initiating a new safeTransferFrom or safeBatchTransferFrom in a new context.
  • The prescribed keccak256 acceptance value magic for the receiver hook being called MUST be returned after forwarding is successful.
• The _data argument MAY be re-purposed for the new context.
• If forwarding fails the transaction MAY be reverted.
  • If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so.

Scenario#9 : You are transferring tokens via a non-standard API call i.e. an implementation specific API and NOT safeTransferFrom or safeBatchTransferFrom.

• In this scenario all balance updates and events output rules are the same as if a standard transfer function had been called.
  • i.e. an external viewer MUST still be able to query the balance via a standard function and it MUST be identical to the balance as determined by TransferSingle and TransferBatch events alone.
• If the receiver is a contract the ERC1155TokenReceiver hooks still need to be called on it and the return values respected the same as if a standard transfer function had been called.
  • However while the safeTransferFrom or safeBatchTransferFrom functions MUST revert if a receiving contract does not implement the ERC1155TokenReceiver interface, a non-standard function MAY proceed with the transfer.
  • See "Implementation specific transfer API rules".

Rules

safeTransferFrom rules:

• Caller must be approved to manage the tokens being transferred out of the _from account (see "Approval" section).
• MUST revert if _to is the zero address.
• MUST revert if balance of holder for token _id is lower than the _value sent to the recipient.
• MUST revert on any other error.
• MUST emit the TransferSingle event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section).
• After the above conditions are met, this function MUST check if _to is a smart contract (e.g. code size > 0). If so, it MUST call onERC1155Received on _to and act appropriately (see "onERC1155Received rules" section).
  • The _data argument provided by the sender for the transfer MUST be passed with its contents unaltered to the onERC1155Received hook function via its _data argument.

safeBatchTransferFrom rules:

• Caller must be approved to manage all the tokens being transferred out of the _from account (see "Approval" section).
• MUST revert if _to is the zero address.
• MUST revert if length of _ids is not the same as length of _values.
• MUST revert if any of the balance(s) of the holder(s) for token(s) in _ids is lower than the respective amount(s) in _values sent to the recipient.
• MUST revert on any other error.
• MUST emit TransferSingle or TransferBatch event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section).
• The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc).
• After the above conditions are met, this function MUST check if _to is a smart contract (e.g. code size > 0). If so, it MUST call onERC1155Received or onERC1155BatchReceived on _to and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section).
  • The _data argument provided by the sender for the transfer MUST be passed with its contents unaltered to the ERC1155TokenReceiver hook function(s) via their _data argument.

TransferSingle and TransferBatch event rules:

• TransferSingle SHOULD be used to indicate a single balance transfer has occurred between a _from and _to pair.
  • It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that TransferBatch is designed for this to reduce gas consumption.
  • The _operator argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
  • The _from argument MUST be the address of the holder whose balance is decreased.
  • The _to argument MUST be the address of the recipient whose balance is increased.
  • The _id argument MUST be the token type being transferred.
  • The _value argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.
  • When minting/creating tokens, the _from argument MUST be set to 0x0 (i.e. zero address). See "Minting/creating and burning/destroying rules".
  • When burning/destroying tokens, the _to argument MUST be set to 0x0 (i.e. zero address). See "Minting/creating and burning/destroying rules".
• TransferBatch SHOULD be used to indicate multiple balance transfers have occurred between a _from and _to pair.
  • It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that TransferSingle is designed for this to reduce gas consumption.
  • The _operator argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).
  • The _from argument MUST be the address of the holder whose balance is decreased for each entry pair in _ids and _values.
  • The _to argument MUST be the address of the recipient whose balance is increased for each entry pair in _ids and _values.
  • The _ids array argument MUST contain the ids of the tokens being transferred.
  • The _values array argument MUST contain the number of token to be transferred for each corresponding entry in _ids.
  • _ids and _values MUST have the same length.
  • When minting/creating tokens, the _from argument MUST be set to 0x0 (i.e. zero address). See "Minting/creating and burning/destroying rules".
  • When burning/destroying tokens, the _to argument MUST be set to 0x0 (i.e. zero address). See "Minting/creating and burning/destroying rules".
• The total value transferred from address 0x0 minus the total value transferred to 0x0 observed via the TransferSingle and TransferBatch events MAY be used by clients and exchanges to determine 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.
• All TransferSingle and TransferBatch events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to onERC1155Received or onERC1155BatchReceived.
  • To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract.

onERC1155Received rules:

• The _operator argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).

• The _from argument MUST be the address of the holder whose balance is decreased.
  • _from MUST be 0x0 for a mint.
• The _id argument MUST be the token type being transferred.
• The _value argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.
• The _data argument MUST contain the information provided by the sender for the transfer with its contents unaltered.
  • i.e. it MUST pass on the unaltered _data argument sent via the safeTransferFrom or safeBatchTransferFrom call for this transfer.
• The recipient contract MAY accept an increase of its balance by returning the acceptance magic value bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))
  • If the return value is bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) the transfer MUST be completed or MUST revert if any other conditions are not met for success.
• The recipient contract MAY reject an increase of its balance by calling revert.
  • If the recipient contract throws/reverts the transaction MUST be reverted.
• If the return value is anything other than bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) the transaction MUST be reverted.
• onERC1155Received (and/or onERC1155BatchReceived) MAY be called multiple times in a single transaction and the following requirements must be met:
  • All callbacks represent mutually exclusive balance changes.
  • The set of all calls to onERC1155Received and onERC1155BatchReceived describes all balance changes that occurred during the transaction in the order submitted.
• A contract MAY skip calling the onERC1155Received hook function if the transfer operation is transferring the token to itself.

onERC1155BatchReceived rules:

• The _operator argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).

• The _from argument MUST be the address of the holder whose balance is decreased.
  • _from MUST be 0x0 for a mint.
• The _ids argument MUST be the list of tokens being transferred.
• The _values argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by.
• The _data argument MUST contain the information provided by the sender for the transfer with its contents unaltered.
  • i.e. it MUST pass on the unaltered _data argument sent via the safeBatchTransferFrom call for this transfer.
• The recipient contract MAY accept an increase of its balance by returning the acceptance magic value bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))
  • If the return value is bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) the transfer MUST be completed or MUST revert if any other conditions are not met for success.
• The recipient contract MAY reject an increase of its balance by calling revert.
  • If the recipient contract throws/reverts the transaction MUST be reverted.
• If the return value is anything other than bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) the transaction MUST be reverted.
• onERC1155BatchReceived (and/or onERC1155Received) MAY be called multiple times in a single transaction and the following requirements must be met:
  • All callbacks represent mutually exclusive balance changes.
  • The set of all calls to onERC1155Received and onERC1155BatchReceived describes all balance changes that occurred during the transaction in the order submitted.
• A contract MAY skip calling the onERC1155BatchReceived hook function if the transfer operation is transferring the token(s) to itself.

ERC1155TokenReceiver ERC-165 rules:

• The implementation of the ERC-165 supportsInterface function SHOULD be as follows:

  function supportsInterface(bytes4 interfaceID) external view returns (bool) {
      return  interfaceID == 0x01ffc9a7 ||    // ERC-165 support (i.e. `bytes4(keccak256('supportsInterface(bytes4)'))`).
              interfaceID == 0x4e2312e0;      // ERC-1155 `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`).
  }

• The implementation MAY differ from the above but:
  • It MUST return the constant value true if 0x01ffc9a7 is passed through the interfaceID argument. This signifies ERC-165 support.
  • It MUST return the constant value true if 0x4e2312e0 is passed through the interfaceID argument. This signifies ERC-1155 ERC1155TokenReceiver support.
  • It MUST NOT consume more than 10,000 gas.
    • This keeps it below the ERC-165 requirement of 30,000 gas, reduces the gas reserve needs and minimises possible side-effects of gas exhaustion during the call.

Implementation specific transfer API rules:

• If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the safeTransferFrom or safeBatchTransferFrom (as appropriate) rules MUST still be followed if the receiver implements the ERC1155TokenReceiver interface. If it does not the non-standard implementation SHOULD revert but MAY proceed.
• An example:
  1. An approved user calls a function such as function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);.
  2. myTransferFrom updates the balances for _from and _to addresses for all _ids and _values.
  3. myTransferFrom emits TransferBatch with the details of what was transferred from address _from to address _to.
  4. myTransferFrom checks if _to is a contract address and determines that it is so (if not, then the transfer can be considered successful).
  5. myTransferFrom calls onERC1155BatchReceived on _to and it reverts or returns an unknown value (if it had returned bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)")) the transfer can be considered successful).
  6. At this point myTransferFrom SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the onERC1155BatchReceived function.
  7. If however myTransferFrom wishes to continue it MUST call supportsInterface(0x4e2312e0) on _to and if it returns the constant value true the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed.
     • NOTE: You could have called supportsInterface(0x4e2312e0) at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario.
  8. If the above call to supportsInterface(0x4e2312e0) on _to reverts or returns a value other than the constant value true the myTransferFrom function MAY consider this transfer successful.
     • NOTE: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens.
• The above example is not exhaustive but illustrates the major points (and shows that most are shared with safeTransferFrom and safeBatchTransferFrom):
  • Balances that are updated MUST have equivalent transfer events emitted.
  • A receiver address has to be checked if it is a contract and if so relevant ERC1155TokenReceiver hook function(s) have to be called on it.
  • Balances (and events associated) that are referenced in a call to an ERC1155TokenReceiver hook MUST be updated (and emitted) before the ERC1155TokenReceiver hook is called.
  • The return values of the ERC1155TokenReceiver hook functions that are called MUST be respected if they are implemented.
  • Only non-standard transfer functions MAY allow tokens to be sent to a recipient contract that does NOT implement the necessary ERC1155TokenReceiver hook functions. safeTransferFrom and safeBatchTransferFrom MUST revert in that case (unless it is a hybrid standards implementation see "Compatibility with other standards").

Minting/creating and burning/destroying rules:

• A mint/create operation is essentially a specialized transfer and MUST follow these rules:
  • 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.
  • The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the mint(s) (i.e. singles or batches) however the _from argument MUST be set to 0x0 (i.e. zero address) to flag the transfer as a mint to contract observers.
    • NOTE: This includes tokens that are given an initial balance in the contract. The balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too.
• A burn/destroy operation is essentially a specialized transfer and MUST follow these rules:
  • The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the _to argument MUST be set to 0x0 (i.e. zero address) to flag the transfer as a burn to contract observers.
  • When burning/destroying you do not have to actually transfer to 0x0 (that is impl specific), only the _to argument in the event MUST be set to 0x0 as above.
• The total value transferred from address 0x0 minus the total value transferred to 0x0 observed via the TransferSingle and TransferBatch events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID.
• As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with custom transfer functions rather than safeTransferFrom or safeBatchTransferFrom. If so the "Implementation specific transfer API rules" section would be appropriate.
  • Even in a non-safe API and/or hybrid standards case the above event rules MUST still be adhered to when minting/creating or burning/destroying.
• A contract MAY skip calling the ERC1155TokenReceiver hook function(s) if the mint operation is transferring the token(s) to itself. In all other cases the ERC1155TokenReceiver rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid).

A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation):

bytes4 constant public ERC1155_ERC165 = 0xd9b67a26; // ERC-165 identifier for the main token standard.
bytes4 constant public ERC1155_ERC165_TOKENRECEIVER = 0x4e2312e0; // ERC-165 identifier for the `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`).
bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // Return value from `onERC1155Received` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`).
bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xbc197c81; // Return value from `onERC1155BatchReceived` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`).

Compatibility with other standards

There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing.
To cater for this scenario, there is some leeway with the revert logic should a contract not implement the ERC1155TokenReceiver as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary ERC1155TokenReceiver interface function(s)".

Hence in a hybrid ERC-1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to onERC1155Received or onERC1155BatchReceived are made.
Order of operation MUST therefore be:

1. The implementation MUST call the function supportsInterface(0x4e2312e0) on the recipient contract, providing at least 10,000 gas.
2. If the function call succeeds and the return value is the constant value true the implementation proceeds as a regular ERC-1155 implementation, with the call(s) to the onERC1155Received or onERC1155BatchReceived hooks and rules associated.
3. If the function call fails or the return value is NOT the constant value true the implementation can assume the recipient contract is not an ERC1155TokenReceiver and follow its other standard's rules for transfers.

Note that a pure implementation of a single standard is recommended rather than a hybrid solution, but an example of a hybrid ERC-1155/ERC-721 contract is linked in the references section under implementations.

An important consideration is that even if the tokens are sent with another standard's rules the ERC-1155 transfer events MUST still be emitted. This is so the balances can still be determined via events alone as per ERC-1155 standard rules.

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 a large number of tokens to use the same on-chain string by defining a URI once, for that large number of tokens.

• The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: [0-9a-f] with no 0x prefix.
• The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary.

Example of such a URI: https://token-cdn-domain/{id}.json would be replaced with https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json if the client is referring to token ID 314592/0x4CCE0.

Metadata Extensions

The optional ERC1155Metadata_URI extension can be identified with the (ERC-165 Standard Interface Detection)[https://eips.ethereum.org/EIPS/eip-165].

If the optional ERC1155Metadata_URI extension is included:

• The ERC-165 supportsInterface function MUST return the constant value true if 0x0e89341c is passed through the interfaceID argument.
• Changes to the URI MUST emit the URI event if the change can be expressed with an event (i.e. it isn't dynamic/programmatic).
  • An implementation MAY emit the URI event during a mint operation but it is NOT mandatory. An observer MAY fetch the metadata uri at mint time from the uri function if it was not emitted.
• The uri function SHOULD be used to retrieve values if no event was emitted.
• The uri function MUST return the same value as the latest event for an _id if it was emitted.
• The uri function MUST NOT be used to check for the existence of a token as it is possible for an implementation to return a valid string even if the token does not exist.

pragma solidity ^0.5.9;

/**
    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.
        The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema".        
        @return URI 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.

• The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: [0-9a-f] with no 0x prefix.
• The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary.

{
    "title": "Token Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this token represents",
        },
        "decimals": {
            "type": "integer",
            "description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation.",
        },
        "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"
		}
	}
}

Localization

Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a localization attribute, its content MAY be used to provide localized values for fields that need it. The localization attribute should be a sub-object with three attributes: uri, default and locales. If the string {locale} exists in any URI, it MUST be replaced with the chosen locale by all client software.

JSON Schema

{
    "title": "Token Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this token represents",
        },
        "decimals": {
            "type": "integer",
            "description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation.",
        },
        "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.",
        },
        "localization": {
            "type": "object",
            "required": ["uri", "default", "locales"],
            "properties": {
                "uri": {
                    "type": "string",
                    "description": "The URI pattern to fetch localized data from. This URI should contain the substring `{locale}` which will be replaced with the appropriate locale value before sending the request."
                },
                "default": {
                    "type": "string",
                    "description": "The locale of the default data within the base JSON"
                },
                "locales": {
                    "type": "array",
                    "description": "The list of locales for which data is available. These locales should conform to those defined in the Unicode Common Locale Data Repository (http://cldr.unicode.org/)."
                }
            }
        },
    }
}

Localized Sample

Base URI:

{
  "name": "Advertising Space",
  "description": "Each token represents a unique Ad space in the city.",
  "localization": {
    "uri": "ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/{locale}.json",
    "default": "en",
    "locales": ["en", "es", "fr"]
  }
}

es.json:

{
  "name": "Espacio Publicitario",
  "description": "Cada token representa un espacio publicitario único en la ciudad."
}

fr.json:

{
  "name": "Espace Publicitaire",
  "description": "Chaque jeton représente un espace publicitaire unique dans la ville."
}

Approval

The function setApprovalForAll allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as ERC-1761 Scoped Approval Interface is suggested.
The counterpart isApprovedForAll provides introspection into any status set by setApprovalForAll.

An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call setApprovalForAll to approve themselves as an operator before they can operate on them.

Rationale

Metadata Choices

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.

Upgrades

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.

Design decision: Supporting non-batch

The standard supports safeTransferFrom and onERC1155Received functions because they are significantly cheaper for single token-type transfers, which is arguably a common use case.

Design decision: Safe transfers only

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.

Guaranteed log trace

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.

Approval

The function setApprovalForAll allows an operator to manage one's entire set of tokens on behalf of the approver. It enables frictionless interaction with exchange and trade contracts.

Restricting approval to a certain set of token IDs, quantities or other rules MAY be done with an additional interface or an external contract. The rationale is to keep the ERC-1155 standard as generic as possible for all use-cases without imposing a specific approval scheme on implementations that may not need it. Standard token approval interfaces can be used, such as the suggested ERC-1761 Scoped Approval Interface which is compatible with ERC-1155.

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.

Batch Transfers

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.

It is RECOMMENDED that clients and wallets sort the token IDs and associated values (in ascending order) when posting a batch transfer, as some ERC-1155 implementations offer significant gas cost savings when IDs are sorted. See Horizon Games - Multi-Token Standard "packed balance" implementation for an example of this.

Batch Balance

The balanceOfBatch function allows clients to retrieve balances of multiple owners and token IDs with a single call.

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, transferred or destroyed.

Non-Fungible Tokens

The following strategies are examples of how you MAY mix fungible and non-fungible tokens together in the same contract. The standard does NOT mandate how an implementation must do this.

Split ID bits

The top 128 bits of the uint256 _id parameter in any ERC-1155 function MAY represent the base token ID, while the bottom 128 bits MAY represent the index of the non-fungible to make it unique.

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 a particular non-fungible within that set, _id could be passed as <uint128: base token id><uint128: index of non-fungible>.

To identify a non-fungible set/category as a whole (or a fungible) you COULD just pass in the base id via the _id argument as <uint128: base token id><uint128: zero>. If your implementation uses this technique this naturally means the index of a non-fungible SHOULD be 1-based.

Inside the contract code the two pieces of data needed to access the individual non-fungible can be extracted with uint128(~0) and the same mask shifted by 128.

uint256 baseTokenNFT = 12345 << 128;
uint128 indexNFT = 50;

uint256 baseTokenFT = 54321 << 128;

balanceOf(baseTokenNFT, msg.sender); // Get balance of the base token for non-fungible set 12345 (this MAY be used to get balance of the user for all of this token set if the implementation wishes as a convenience).
balanceOf(baseTokenNFT + indexNFT, msg.sender); // Get balance of the token at index 50 for non-fungible set 12345 (should be 1 if user owns the individual non-fungible token or 0 if they do not).
balanceOf(baseTokenFT, msg.sender); // Get balance of the fungible base token 54321.

Note that 128 is an arbitrary number, an implementation MAY choose how they would like this split to occur as suitable for their use case. An observer of the contract would simply see events showing balance transfers and mints happening and MAY track the balances using that information alone.
For an observer to be able to determine type (non-fungible or fungible) from an ID alone they would have to know the split ID bits format on a implementation by implementation basis.

The ERC-1155 Reference Implementation is an example of the split ID bits strategy.

Natural Non-Fungible tokens

Another simple way to represent non-fungibles is to allow a maximum value of 1 for each non-fungible token. This would naturally mirror the real world, where unique items have a quantity of 1 and fungible items have a quantity greater than 1.

References

Standards

• ERC-721 Non-Fungible Token Standard
• ERC-165 Standard Interface Detection
• ERC-1538 Transparent Contract Standard
• JSON Schema
• RFC 2119 Key words for use in RFCs to Indicate Requirement Levels

Implementations

• ERC-1155 Reference Implementation
• Horizon Games - Multi-Token Standard
• Enjin Coin (GitHub)
• The Sandbox - Dual ERC-1155/721 Contract

Articles & Discussions

• Github - Original Discussion Thread
• ERC-1155 - The Crypto Item Standard
• Here Be Dragons - Going Beyond ERC-20 and ERC-721 To Reduce Gas Cost by ~80%
• Blockonomi - Ethereum ERC-1155 Token Perfect for Online Games, Possibly More
• Beyond Gaming - Exploring the Utility of ERC-1155 Token Standard!
• ERC-1155: A new standard for The Sandbox

Copyright

Copyright and related rights waived via CC0.

[AC0DEM0NK3Y]

Suggestion: Add in some detail of how to encode extra information into the _itemId to facilitate the mixing of different item/token standards.

An example strategy to mix Fungible and Non-Fungible items together in the same contract for example may 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.

In the ERC-721 case individual NFTs are 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>".

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.

[coinfork]

Added the split bits strategy to the description, thanks :)

[AC0DEM0NK3Y]

Transfer made using this standard, 2 FTs (10k + 500) and 100 NFTs (100):

https://ropsten.etherscan.io/tx/0xfc924192fb068a6326bc28a2f5762be3a4b1fb6a1ef801bf6bf02c06af929d53

FT "ENJ" ID: 0x54e8b965cee12ac713ee58508b0d07300000000000000000000000000000000
FT "Gold" ID: 0x3bf7ded270a4ab1d5e170cc79deb931800000000000000000000000000000000
NFT "Lots of NFTs" ID: 0x4362b8ce48bee741861f523a3b91803c00000000000000000000000000000000

10000, 500 and 100*1 sent in one transaction costing 5480196 gas (~$2.42 at time of tx).

Note, this was done in an advanced solution with a lot more features than a basic impl. Basic/ref impl and gas as compared to current standards in basic form will be added soon.

[highruned]

Hyperbridge is interested in potentially supporting this standard in our upcoming marketplace. We'd like to see where other organizations stand on this as it's an obvious problem, and if the proposed solution works for you. @coinfork I don't see source code, so I'm going to take to take it that it's currently proprietary. Is there any examples in the wild as of yet?

[coinfork]

Hey @ericmuyser thanks for your interest! We currently have a deployed contract on Ropsten (please see AC0DEM0NK3Y's post above) that is specifically tailored to our gaming use-case. We'll consider adding a reference implementation to the standard.

[powether]

I hope you didn't announce this like "Biggest innovation in the manking". 5480196 gas is unacceptably high.

[AC0DEM0NK3Y]

"I hope you didn't announce this like "Biggest innovation in the manking". 5480196 gas is unacceptably high."

I think you need to look at the gas cost relative to the alternatives and how this differs from them. If you average this down (even without the fungible transfers that went with it) the above transfer cost ~55K per NFT sent, which compared to many other ERC721 implementations for eg. (seeing numbers 250K+ each) this offers significant savings. A simple ETH transfer costs 21K and ERC20 tokens look to cost anywhere from 35k to 130k each tx after some quick explorer checks in the top 100. So I would say the above cost is quite reasonable.

On top of that there is also the reduction of number of contracts necessary to be deployed to the network, the transaction numbers being reduced (in this case 102 : 1) and also the possible features this would bring that wouldn't be possible with separate contracts and incompatible NFT & FT standards.

[shrugs]

I don't have strong opinions yet, but did y'all explore the option of composing ERC721 and 20/721 to get similar functionality? As in, creating a AllItems contract that is 721 but fully controlled by whatever governance mechanism you'd prefer. Then, owners can create a new item set like createNonFungible(...) to deploy a 721 contract and add that new contract address as one of the tokens tracked by the contract (owned by the AllItems contract itself). Similar for fungible assets. Then clients can get the set of all items via iterating the 721 interface, ERC165 detect fungibility or non-fungibility, and either 1) directly interface with those sub-contracts to manage their items or 2) you could provide similar multi-send features by proxying transfer requests through the AllItems contract that's either an approved operator of the sub-contract or is just an all-seeing authority (deferring the access-control logic to the AllItems contract to verify who owns what before transferring).

Anyway, it might be a little roundabout, but it does avoid the creation of a new standard by extending and composing existing ones, which is neat.

[AC0DEM0NK3Y]

Hi @shrugs while not getting too far into the implementation details of a system that uses this standard, in the above example where two different fungible types and one non-fungible set were operated on what a user/creator could do is call a "deployERCAdapter" function on the particular type if they so wish which will deploy an adapter contract that is either fully ERC721 or ERC20 compatible depending on the base type. This means the individual set is now backwards compatible with those standards and can therefore be used in any current system that supports them.
So we get the best of both worlds, full compatibility with ERC20 and ERC721 (as an option) but also the ability to mix these two standards together by operating at the 1155 "main level" and so can transfer/operate on these together and on multiple of the types, in the same transaction.

Extending ERC721 rather than making a new standard that can mix different fungibility (and then supporting ERC721 with backwards compatibility) wouldn't have quite worked as ERC721 mandatory standard has certain functions that only make it suitable for a single data set in a single contract such as "balanceOf(address _owner)" and "isApprovedForAll(address _owner, address _operator)" for example.

[shrugs]

@AC0DEM0NK3Y the ERC adaptor is interesting, yeah.

The fungible/non-fungible tokens would not be tracked in a single 721; their contract addresses would be.

AllItems (ERC721, tracking contract addresses)
  |__ Sword contract (ERC20)
  |
  |__ Legendary Armor contract (ERC721)

so each individual contract still fulfills 721 and 20 to the best of their ability, and you add additional features like multi-send and factory methods to the AllItems parent contract.

[AC0DEM0NK3Y]

That is a way to track perhaps, but is much less user/network friendly. If I want to send you an NFT A and and NFT B and do that through your tracking contract I'd have to call approve on contract A and B separately to give the tracking contract the allowance, then call the tracking contract to do the transfer.
That is 3 individual transactions (4 if your tracking contract doesn't support arrays for transfer API).

By allowing things to be mixed together and stored in a single contract I can transfer A and B to you in a single tx.

A and B contract also have to be deployed. It's more data on the chain than is needed and that is not sustainable and/or limiting imho.
If you consider use cases like a videogames that have lots of different types of NFTs and how many games there are in the market now and will be in the future, having to deploy an ERC20/ERC721 contract to support those types every time is not good for the ETH network as a whole going forward and that is just one use case.

[shrugs]

I mentioned that above as well, perhaps I wasn't clear enough; you can implement multi-send functionality by making the AllItems contract a designated operator (or a super user of sorts) for transferring tokens/items and then implement access control at the AllItems layer, allowing you to skip approvals and send multiple items with a single transaction exactly as you do in 1155. Nothing has changed here.

I agree that composability does come with gas costs, and these should be measured. You can also separate logic and data using proxy patterns and cut down on duplicate logic deployments. (and before someone references the parity wallet, this is very much the same approach that 1155 uses by consolidating the logic and data into a single contract; it's still a single point of failure if there is a show-stopping bug).

[AC0DEM0NK3Y]

It sounds like it could work, but it doesn't fix the wastage/management issue. Deploying a contract for every NFT is not future proof imho.

Your pattern seems like it would work with 1155 though. The register function that you are proposing could be something someone implements and then this returns an ID to match the contract address when calling the function. The call to transfer A and B in that case would might be to call:

uint aID = 1155.register(ContractOfA);
uint aIndex = 12345; // NFT index I want to send from contract A
uint bID = 1155.register(ContractOfB);
uint bIndex = 888; // NFT index I want to send from contract B
ContractOfA.makeSuperUser(1155);
ContractOfB.makeSuperUser(1155);
1155.transfer([aID, aIndex, bID, bIndex], [yourAddr,yourAddr],[1,1]);

This now needs an extension to ERC721 to append "makeSuperUser" function.

[shrugs]

((an aside: using an existing standard is the definition of futureproof))

superuser would need to be added, yes. you could also get away with operator functionality that already exists; simply default to setting the approved operator of every token to the AllItems contract. users could revoke, but 1) why would they and 2) to restore previous behavior, they can simply re-approve the operator. compatible with both 20 and 721.

The data/logic separation via proxy is a well-known pattern and does indeed work. The only unknown is the gas implications, which could be measured. Having your sub-items be compatible with 20/721 by default is a very powerful effect. We've only just started the whole NFT thing, and fracturing into another standard instead of leveraging existing ones isn't really a strong move, imo. Existing indexers (Toshi, Trust Wallet, etc) would need to have extra logic to monitor this standard as well. And deploying ERC adaptors for every token just gets you back to the point I'm making; it should just be compatible with the existing standard by default.

Anyway, give it a think and see if it solves the problem you're interested in solving. I'm very familiar with the space and the problems you're facing, specifically around gaming, and have thought about this at length as well. A next step would be profiling the gas costs of a composable approach, which I may mind time to do within the next week or two, but can't guarantee.

[AC0DEM0NK3Y]

an aside: using an existing standard is the definition of futureproof

I would call that backwards compatible but hey :)

The data/logic separation via proxy is a well-known pattern and does indeed work.

Yes, we do this or sorts in our implementation. Storage contract holds all the data, then the rest is an API over the top of it. Many reasons to do this.
So in the above test, consider that a test of gas costs perhaps.

Thanks for the discussion @shrugs looking forward to more.

[PhABC]

Hello!

Happy to see other people working on something like this. I personally recommend the following changes ;

1. Remove transfer(...). It's a special case of transferFrom() and is less explicit, which isn't great.

2. Add safeTransferFrom(...) instead of passing data in second 128 bits. Explicit > implicit should be favored in standards imo.

3. Change arguments order of transferFrom(uint256[] _itemId, address[] _from, address[] _to, uint256[] _value)nt ordering from transferFrom(uint256[] _itemId, address[] _from, address[] _to, uint256[] _value) to transferFrom(address[] _from, address[] _to, uint256[] _itemId, uint256[] _value) which seems more consistent with current standards.

4. Change the current approval logic to something like setApprovalForAll() or setOperator() instead of using specific approvals. Approvals are almost exclusively used to give access to your tokens to a trusted/vetted contract. I have yet to see an example of a specific approval value. Even with erc-721, I have yet to see a use case where giving approval to a single ID is useful.

When it comes to transfer() and transferFrom(), is the reason for "not" throwing and return a bool instead to prevent a single transfer from breaking the entire transfer? What does it mean to return false? That at least one of them was unsuccessful? All of them? Not sure I understand the logic here and would love some extra info.

[amittmahajan]

Thanks for putting this together!

A few folks (@petejkim (Cipher/Toshi), @lsankar4033 (PepeDapp), @pkieltyka (Horizon Games), and myself (Rare Bits/Fan Bits)) were actually bouncing around a Semi Fungible Token standard that may make sense to combine efforts on given the similarities. I've put it below for posterity. That being said, a couple ideological things that may be worth considering:

1. ERC721 was just approved after a lot of deliberation and it seems like maintaining this as an evolution/superset of ERC721/ERC20 in terms of nomenclature / API compatibility will help with adoption / building to consensus quickly. We took the approach of starting with the ERC721 spec and then evolving from there to ensure we captured all of the hard work and thought that went into that standard.

2. This is bigger than games and the ecosystem for NFTs is already spreading well beyond virtual items. Switching from Items to Tokens doesn't make a whole lot of sense given the existing ecosystem that exists around these standards already.

3. We all agreed that having indexing/metadata functions are required versus optional makes life a lot easier for wallet providers and other indexers trying to display the data and interoperate with these contracts.

pragma solidity ^0.4.20;

/// The goal of this spec is to handle a now-common case of having different
/// token types with fungibility within each type.

/// Many DApps are either using ERC721 with multiple-tokens of the same type or deploying 
/// multiple ERC20 contracts to create fungible tokens within a set non-fungible token types.
/// An example would be a trading card game with different types but where 
/// each card of a given type is indistinguishable from the other. Or an art 
/// token where each print of an art piece is indistinguishable from any other print.

/// This is a *VERY* draft spec that is modified from the (near) final
/// ERC721-spec. We should evolve it as necessary from here.

/// @title ERC->>>TBD<<< Semi-Fungible Token Standard
/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-TBD.md
///  Note: the ERC-165 identifier for this interface is >>>TBD<<<
interface ERCTBD /* is ERC165 */ {
    /// @dev This emits when ownership of any SFT changes by any mechanism.
    ///  This event emits when SFTs are created (from == 0) and destroyed
    ///  (to == 0). Exception: during contract creation, any number of SFTs
    ///  may be created and assigned without emitting Transfer. At the time of
    ///  any transfer, the approved address for that SFT (if any) is reset to none.
    event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenType, uint256 indexed _value);

    /// @dev This emits when the approved address for an SFT is changed or
    ///  reaffirmed. The zero address indicates there is no approved address.
    ///  When a Transfer event emits, this also indicates that the approved
    ///  address for that SFT (if any) is reset to none.
    event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenType, uint256 indexed _value);

    /// @dev This emits when an operator is enabled or disabled for an owner.
    ///  The operator can manage all SFTs of the owner.
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);

    /// @notice Returns the total token supply.
    /// @dev Throws if '_tokenType' is not a valid SFT
    /// @param _tokenType The type of SFT to get the totalSupply of. Must be less than the return value of totalTokenTypes
    /// @return The total supply of the given SFT
    function totalSupply(uint256 _tokenType) external view returns (uint256 totalSupply);

    /// @notice Count all SFTs of a given type owned by _owner
    /// @dev Throws if '_tokenType' is not a valid SFT or if _owner is set to the zero-address
    /// @param _owner An address for whom to query the balance
    /// @param _tokenType The type of SFT to get the balance of. Must be less than the return value of totalTokenTypes
    function balanceOf(address _owner, uint256 _tokenType) external view returns (uint256 balance);
    
    /// @notice Return all token types for a given _owner
    /// @param _owner An address for whom to return token types for
    function tokenTypesOf(address _owner) external view returns (uint256[] tokenTypes);

    /// @notice Returns the total number of token types for this contract
    /// @dev Can possibly be zero
    /// @return The total number of token types
    function totalTokenTypes() external view returns (uint256 totalTokenTypes);

    /// @notice Returns the total number of distinct owners who own _tokenType
    /// @dev Can possibly be zero
    /// @return The total number of distinct owners owning _tokenType
    function totalOwners(uint256 _tokenType) external view returns (uint256 totalOwners);

    /// @notice Returns the owner of _tokenType specified by _ownerIndex
    /// @param _ownerIndex Unique identifier of an owner of _tokenType
    /// @return The address of the ownner of _tokenType specified by _ownerIndex
    function ownerOf(uint256 _tokenType, uint256 _ownerIndex) external view returns (address owner);

    /// @notice Transfers the ownership of some SFTs from one address to another address
    /// @dev Throws unless 'msg.sender' is the current owner, an authorized
    ///  operator, or the approved address for the SFTs. Throws if '_from' is
    ///  not the current owner. Throws if '_to' is the zero address. Throws if
    ///  '_tokenType' is not a valid SFT type. When transfer is complete, this function
    ///  checks if '_to' is a smart contract (code size > 0). If so, it calls
    ///  'onERCTBDReceived' on '_to' and throws if the return value is not
    ///  'bytes4(keccak256("onERCTBDReceived(address,address,uint256,bytes)"))'.
    /// @param _from The current owner of the SFTs
    /// @param _to The new owner
    /// @param _tokenType The SFT type to transfer. Must be less than the return value of totalTokenTypes
    /// @param _value Amount of SFT to transfer
    /// @param data Additional data with no specified format, sent in call to '_to'
    function safeTransferFrom(address _from, address _to, uint256 _tokenType, uint256 _value, bytes data) external payable;

    /// @notice Transfers the ownership of some SFTs from one address to another address
    /// @dev This works identically to the other function with an extra data parameter,
    ///  except this function just sets data to "".
    /// @param _from The current owner of the SFTs
    /// @param _to The new owner
    /// @param _tokenType The SFT type to transfer. Must be less than the return value of totalTokenTypes
    /// @param _value Amount of SFT to transfer
    function safeTransferFrom(address _from, address _to, uint256 _tokenType, uint256 _value) external payable;

    /// @notice Transfer ownership of some SFT -- THE CALLER IS RESPONSIBLE
    ///  TO CONFIRM THAT '_to' IS CAPABLE OF RECEIVING SFTS OR ELSE
    ///  THEY MAY BE PERMANENTLY LOST
    /// @dev Throws unless 'msg.sender' is the current owner, an authorized
    ///  operator, or the approved address for this SFT. Throws if '_from' is
    ///  not the current owner. Throws if '_to' is the zero address. Throws if
    ///  '_tokenType' is not a valid SFT.
    /// @param _from The current owner of the SFT
    /// @param _to The new owner
    /// @param _tokenType The SFT type to transfer. Must be less than the return value of totalTokenTypes
    function transferFrom(address _from, address _to, uint256 _tokenType, uint256 _value) external payable;

    /// @notice Change or reaffirm the approved address for some SFTs
    /// @dev The zero address indicates there is no approved address.
    ///  Throws unless 'msg.sender' is the current owner of the SFTs, or an authorized
    ///  operator of the current owner.
    /// @param _approved The new approved SFT controller
    /// @param _tokenType The SFT type to approve. Must be less than the return value of totalTokenTypes
    /// @param _value The amount of SFT able to be withdrawn
    function approve(address _approved, uint256 _tokenType, uint256 _value) external payable;

    /// @notice Enable or disable approval for a third party ("operator") to manage
    ///  all of msg.sender's assets
    /// @dev Emits the ApprovalForAll event. The contract MUST allow
    ///  multiple operators per owner.
    /// @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 Get the amount of allowance a spender has for a given owner and SFT type
    /// @param _owner The address that owns the SFTs
    /// @param _spender The address that is operating on behalf of the owner
    /// @param _tokenType The type of SFT to find the approved address for. Must be less than the return value of totalTokenTypes
    /// @return The amount able to be spent by the spender for a given owner and type
    function allowance(address _owner, address _spender, uint256 _tokenType) external view returns (uint256);

    /// @notice Query if an address is an authorized operator for another address
    /// @param _owner The address that owns the SFTs
    /// @param _operator The address that acts on behalf of the owner
    /// @return True if '_operator' is an approved operator for '_owner', false otherwise
    function isApprovedForAll(address _owner, address _operator) external view returns (bool);

    /// @notice A descriptive name for a collection of SFTs in this contract
    function name() external view returns (string _name);

    /// @notice An abbreviated name for SFTs of a given type
    function symbol(uint256 _tokenType) external view returns (string _symbol);

    /// @notice A distinct Uniform Resource Identifier (URI) for a given asset.
    /// @dev Throws if '_tokenType' is not a valid SFT. URIs are defined in RFC
    ///  3986. The URI may point to a JSON file that conforms to the "ERC721
    ///  Metadata JSON Schema".
    function tokenURI(uint256 _tokenType) external view returns (string);    
}

interface ERC165 {
    /// @notice Query if a contract implements an interface
    /// @param interfaceID The interface identifier, as specified in ERC-165
    /// @dev Interface identification is specified in ERC-165. This function
    ///  uses less than 30,000 gas.
    /// @return 'true' if the contract implements 'interfaceID' and
    ///  'interfaceID' is not 0xffffffff, 'false' otherwise
    function supportsInterface(bytes4 interfaceID) external view returns (bool);
}

[PhABC]

@amittmahajan Could you explain what ownerOf and totalOwners are referring to? It's not clear to me what the intentions are with these functions.

[amittmahajan]

@PhABC totalOwners is referring to the number of unique addresses that hold a given tokenType. ownerOf is one element of that "owners" array of a given tokenType. it allows you to enumerate every owner of a given tokenType.

[AC0DEM0NK3Y]

Thanks for adding that @amittmahajan and we'll discuss it internally. What first springs to mind however is that your proposal standard does not allow for approving/transferring etc. on multiple things in one shot as they do not take array arguments.

Also the functions such as @PhABC is talking about like totalOwners sound immediately to me like they would need more storage and so gas costs to maintain. I would advocate for as little as possible on chain storage and this sort of "metadata" instead recorded off-chain.
You could find the owners/track balance via transfer log events for eg. and store that info elsewhere. It isn't necessary for the users to have that info stored and the developers can get this info from a local node.
The less we bloat ETH while providing great features for the users the better imho.

[PhABC]

@amittmahajan Ah I see. How do you keep track of all the owners? I can understand iterating over all token types an user owns if the totsl number of token types is somewhat low, but I can't really see a way to iterate over the owners unless you keep a big array of owners for each token types. Any insights?

[dwking2000]

Good to see this proposal.

Our use case is for ERC-20 tokens. We want to 'color' tokens by community while allowing them to be fungible on exchanges as a 'clear' token. Within communities transfer of colored tokens will be allowed in the community color only, but outside of communities the rest of the world will see the tokens as a single ERC-20 type token. This looks like a similar solution I came up with to solve this.

A standard will encourage the creation of tools and potentially wallets will that can deal with this paradigm. My question: is this EIP just for NFTs or is it intended to be used for ERC-20 tokens as well?

[amittmahajan]

@PhABC @AC0DEM0NK3Y re: totalOwners, ownerOf. not married to including these because we've built out the infra already to support it but I included it with the intent of spurring the discussion if there was a more clever way to implement it / see what the community demand for such a feature would be.

re: multiple token transfer, i think it's a good idea and has a lot of use cases. That being said, I wouldn't be surprised if that function is mostly called with a single type. Perhaps it makes sense to implement that as a new function (multiTransfer) to reduce complexity for the most basic use case of transfer. If I were to vote right now, i'd say stick with the current version (one func transfer that takes multiple types) but wanted to raise the topic of two funcs to be diligent.

[PhABC]

@amittmahajan batch transfer is critical for these types of tokens, imo, it's really what makes such an interface interesting. I personally vote for batchTransferFrom(..) to follow naming conventions. I do agree that some applications might favor single type transfer while others might utilize the batch transfer functionality more often.Convince me :).

I personally would not include totalOwners & ownerOf as they add significant gas cost and their on-chain utility seems limited.

[AC0DEM0NK3Y]

We originally had a transfer (single) and multiTransfer (array) in the standard but after testing gas differences and usability we decided it better to just use the array version and name it transfer for simplicity.

If you pass in MEW for eg. as well as other methods, the difference in array vs non-array method is almost identical (it is identical in MEW) and the gas difference is negligible and the power of the feature is huge for gas savings and for functionaility.

[PhABC]

With my implementation, it costs around 400k gas to send 100 token types, but single transfer is about 2k gas more expensive using the batchTransferFrom function compared to the transferFrom().

[lsankar4033]

@AC0DEM0NK3Y one downside of a single transfer method (vs. separate transfer and multiTransfer methods) is that there's an additional burden on 3rd parties integrating with all standards, as they have to remember that transfer has different argument lists (address vs. address[]) for ERC721/20/1155.

I think the simplicity cost of having two methods is worth the integration win of cleaner unification with existing standards.

[AC0DEM0NK3Y]

@lsankar4033 We'll talk/test about that internally and come back on it.

My first thought is that transfer has to change even in singular form to include the token/item type:

function transfer(address _to, uint256 _value)

vs

function transfer(uint256 _itemId, address _to, uint256 _value)
or
function transfer(uint256[] _itemId, address[] _to, uint256[] _value)

so if it has to change signature anyway, why not go for the most powerful version if it is just as easy to call, almost as cheap and provides the opportunity for much more functionality?

[playmint-jbr]

Do I really HAVE to emit the URI event for every single token if the URI changes? Wouldn't that mean that if I change some metadata and re-pin on IPFS resulting in a different IPFS hash, that I'll have to emit an event for every token - prohibitively expensive gas if I have thousands of NFTs already minted from a contract?

[Nielsbishere]

@playmint-jbr Yes as far as I know. It would've been nice to have batch uri update function in the standard.

[playmint-jbr]

Agreed, an event which takes a range of token ids or some such would do. I would say this is a significant problem with this standard.

[boringcrypto]

I've been implementing this EIP and a few issues have come up:

• Contracts can't query the name and decimals info. This is only exposed through the URI, which cannot be retrieved or parsed by solidity. I'm creating ERC1155 tokens that "wrap" other ERC1155 tokens, but the URI for these can't have much usable info because it's only available to clients.

• I'm generating the URI on-chain and this is quite expensive, but normally only called from a client (not another contract). However, according to the spec the URI event contains the actual URI. I will instead emit an empty string to keep things useable. The wording should probably change to SHOULD or CAN, not MUST as this makes this standard impossible to implement in certain cases. And clients can simply query the URI after they've been notified of an update. Things would be even better if the URI event only had the tokenId parameter.

[githubusertrial]

How does one take a snapshot of Each Holder wallet and the corresponding tokens in that wallet under 1155 contract? And can the snapshot be taken on regular basis say daily at specific time?

[ThienLK1]

In this standard i see api to query metadata(uri) and the event to change it.
But i can not found a api to change uri, or init it(maybe in mint process?, if yes, i dont see the param to set uri yet....)?
So how can i implement this?

[ericbinet]

So how can i implement this?

The standard doesn't impose an API on how to set the URIs. Some contracts have static URIs that will never change. If your tokens have mutable URIs, then create any necessary methods to update them.

It could be setURI(...) or setBaseURI(...) [to change only a substring of the URIs] or setURIs(...) [to change the URIs of multiple tokens].

Make sure to secure those.

[RnbWd]

this contract should have decimals on it

[bglmmz]

Up to now (05/22/2022)， is there any exchange, swap, dex, wallet to support EIP-1155 including its Fungible Token and Non-Fungible Token?

[MicahZoltu]

Closing this for housekeeping purposes. Feel free to continue using this issue for discussion about EIP-1155 though.