Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some minor grammar and wording changes just before final. #2113

Merged
merged 86 commits into from
Jun 12, 2019
Merged
Changes from all commits
Commits
Show all changes
86 commits
Select commit Hold shift + click to select a range
49fbbde
EDT-3069 Adding more clarity in transfer rules and other things, alte…
AC0DEM0NK3Y May 3, 2019
5a0fba2
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 3, 2019
73a3365
EDT-3069 id substitution example was not lowercase.
AC0DEM0NK3Y May 4, 2019
0557c37
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 4, 2019
ed9f0d1
EDT-3069 Updated the "Safe Transfer Rules" section to match feedback …
AC0DEM0NK3Y May 7, 2019
e331f58
EDT-3069 Some formatting changes to make it easier to digest/
AC0DEM0NK3Y May 7, 2019
3e2a176
EDT-3069 More formatting.
AC0DEM0NK3Y May 7, 2019
c9db596
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 7, 2019
3ba6d4f
EDT-3069 Move impl specific functions rules to the rules section.
AC0DEM0NK3Y May 7, 2019
b3f5675
EDT-3069 Better wording on impl specific api rules.
AC0DEM0NK3Y May 7, 2019
774c0ae
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 7, 2019
f745443
EDT-3069 Added in rules for TransferSingle and TransferBatch events s…
AC0DEM0NK3Y May 7, 2019
1f3a415
EDT-3069 EOA explanation.
AC0DEM0NK3Y May 8, 2019
54a4fa1
EDT-3069 Updated text after feedback.
AC0DEM0NK3Y May 9, 2019
2f16e0f
EDT-3069 Another update.
AC0DEM0NK3Y May 9, 2019
cdc350b
EDT- Minor wording changes, be consistent in how we name ERC numbers …
AC0DEM0NK3Y May 9, 2019
5083d1e
EDT-3069 Remove confusion on hook return vals and args.
AC0DEM0NK3Y May 9, 2019
5869a76
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 9, 2019
cbc7264
EDT-3069 Drop the "DRAFT" text from linked standards, so when we go f…
AC0DEM0NK3Y May 9, 2019
d5446f9
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 9, 2019
c62f69b
EDT-3069 Added safe and batch transferFrom rules to also be explicit …
AC0DEM0NK3Y May 9, 2019
dd6b5d7
EDT-3069 Another small change to match the rules.
AC0DEM0NK3Y May 9, 2019
4f36207
Changes to wording to clarify transfer rules.
JamesTherien May 10, 2019
b6f8829
Clarification for the _data parameter
JamesTherien May 10, 2019
67a42bc
Clarify rules of breaking down into multiple onReceived callbacks
JamesTherien May 10, 2019
8f0c356
Merge pull request #1 from JamesTherien/master
AC0DEM0NK3Y May 10, 2019
48cce31
EDT-3069 Alter the rejection logic back to normal for regular 115 ope…
AC0DEM0NK3Y May 10, 2019
f11b5c2
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 10, 2019
cd86485
EDT-3069 Small inconsistency and remove the ==<hex value> part from r…
AC0DEM0NK3Y May 11, 2019
206594c
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 11, 2019
d7b07bd
EDT-3069 Add in ERC-165 interface identifier info for the ERC1155Toke…
AC0DEM0NK3Y May 11, 2019
97fa9de
EDT-3069 Very minor change to text, remove odd grammar.
AC0DEM0NK3Y May 13, 2019
4f0378e
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 13, 2019
15a67ab
EDT-3069 Consistency change on the isERC1155TokenReceiver gas require…
AC0DEM0NK3Y May 13, 2019
65052c6
EDT-3069 Added wighawag as an author, alter isERC1155Receiver interfa…
AC0DEM0NK3Y May 18, 2019
8cb2756
EDT-3069 Minor grammar and consistency changes on use of "for example…
AC0DEM0NK3Y May 18, 2019
a560f91
EDT-3069 Change the recommended isERC1155TokenReceiver function to us…
AC0DEM0NK3Y May 18, 2019
2eedafb
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 18, 2019
cc3e971
EDT-3069 Small alteration to text by request.
AC0DEM0NK3Y May 21, 2019
c2a0f11
EDT-3069 Minor text consistency change.
AC0DEM0NK3Y May 22, 2019
4eaf2c7
EDT-3069 Fixed typo.
AC0DEM0NK3Y May 22, 2019
fb0e643
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 22, 2019
cc3a9d9
EDT-3069 Spelling.
AC0DEM0NK3Y May 22, 2019
caa8d27
EDT-3069 Minor formatting change.
AC0DEM0NK3Y May 22, 2019
d8b0d2f
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 22, 2019
8c96bfb
EDT-3069 Some small changes to wording for clarity.
AC0DEM0NK3Y May 24, 2019
282e0d0
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 24, 2019
50d401c
Revert magic_values to original byte4
PhABC May 24, 2019
d054f84
EDT-3069 Adding in scenario for non-standard api call and allow it to…
AC0DEM0NK3Y May 24, 2019
8d50450
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 25, 2019
eb36a93
Merge pull request #2 from PhABC/patch-7
AC0DEM0NK3Y May 25, 2019
ca3278b
EDT-3069 Minor consistency change.
AC0DEM0NK3Y May 25, 2019
cfae695
EDT-3069 Updated return value to latest after merge.
AC0DEM0NK3Y May 25, 2019
c21e799
EDT-3069 Consistency on calling "1155" "ERC-1155".
AC0DEM0NK3Y May 25, 2019
6dd5dc6
EDT-3069 Minor wording change.
AC0DEM0NK3Y May 25, 2019
343457a
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 25, 2019
91815a0
EDT-3069 More wording changes for clarification.
AC0DEM0NK3Y May 25, 2019
a3c61ba
EDT-3069 Small grammar change and capitalized API.
AC0DEM0NK3Y May 25, 2019
4ff6c62
EDT-3069 Change a MAY to SHOULD as a non-standard impl really should …
AC0DEM0NK3Y May 25, 2019
2a62512
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 25, 2019
4da1425
EDT-3069 Minor changes for grammar and consistency.
AC0DEM0NK3Y May 26, 2019
4aa3ac9
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 27, 2019
7a61926
EDT-3069 Slightly strong wording using SHOULD instead of a MAY in the…
AC0DEM0NK3Y May 27, 2019
a301bc6
EDT-3069 Solidity 0.5.9 is latest version (ref impl tested on this ve…
AC0DEM0NK3Y May 28, 2019
a9b6921
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 28, 2019
0ec4c57
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y May 28, 2019
16ad5b1
EDT-3069 Some alteration to the standard as requested along with a se…
AC0DEM0NK3Y Jun 1, 2019
eb1207b
EDT-3069 Minor grammar fix.
AC0DEM0NK3Y Jun 3, 2019
219d72a
EDT-3069 Add in mention that mint/burn is a custom transfer so follow…
AC0DEM0NK3Y Jun 4, 2019
e57d757
EDT-3069 Add in recommendation for wallets etc. to sort their batch t…
AC0DEM0NK3Y Jun 4, 2019
7800e85
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 4, 2019
8390de7
EDT-3069 More minor grammar and formatting fixes.
AC0DEM0NK3Y Jun 4, 2019
93cc841
DT-3069 Consistent use of MUST in uri event and function.
AC0DEM0NK3Y Jun 5, 2019
34df030
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 5, 2019
4f21e38
EDT-3069 Replace isERCTokenReceiver with usage of ERC165 supportsInte…
AC0DEM0NK3Y Jun 6, 2019
9de300a
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 7, 2019
463d6b2
URI event clarification
AC0DEM0NK3Y Jun 7, 2019
0a255c5
EDT-3069 Altered Metadata Extension rules to be clear about the ERC-1…
AC0DEM0NK3Y Jun 7, 2019
cb3cbfc
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 7, 2019
93a2c71
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 7, 2019
4ef4687
DT-3069 Some minor changes for github formatting.
AC0DEM0NK3Y Jun 7, 2019
7286293
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 7, 2019
dee01f7
EDT-3069 Very minor clarification.
AC0DEM0NK3Y Jun 11, 2019
b3d9945
EDT-3069 consistent use of "non-fungible" rather than mixing in "Non-…
AC0DEM0NK3Y Jun 12, 2019
92bcc27
Merge branch 'master' of https://github.com/ethereum/EIPs
AC0DEM0NK3Y Jun 12, 2019
9a29771
EDT-3069 Minor grammar alterations.
AC0DEM0NK3Y Jun 12, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions EIPS/eip-1155.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,19 @@ 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).
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.
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.
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.
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

Expand Down Expand Up @@ -115,7 +115,7 @@ interface ERC1155 /* is ERC165 */ {
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.
@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
Expand All @@ -125,7 +125,7 @@ interface ERC1155 /* is ERC165 */ {
/**
@notice Get the balance of multiple account/token pairs
@param _owners The addresses of the token holders
@param _ids ID of the Tokens
@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);
Expand All @@ -140,7 +140,7 @@ interface ERC1155 /* is ERC165 */ {

/**
@notice Queries the approval status of an operator for a given owner.
@param _owner The owner of the Tokens
@param _owner The owner of the tokens
@param _operator Address of authorized operator
@return True if the operator is approved, false if not
*/
Expand Down Expand Up @@ -207,7 +207,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran

**_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 tokens 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.
- 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.
Expand Down Expand Up @@ -242,9 +242,9 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran
- 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 function had been called.
- i.e. an external viewer should still be able to query a balance via a function and it 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 function had been called.
* 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".

Expand Down Expand Up @@ -377,7 +377,7 @@ To be more explicit about how the standard `safeTransferFrom` and `safeBatchTran
* 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/create 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 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):
Expand Down Expand Up @@ -407,7 +407,7 @@ An important consideration is that even if the tokens are sent with another stan

### 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 large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens.
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.
Expand Down Expand Up @@ -594,7 +594,7 @@ fr.json:
### 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](https://eips.ethereum.org/EIPS/eip-1761) is suggested.
The counterpart `isApprovedForAll` provides introspection into status set by `setApprovalForAll`.
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.

Expand Down Expand Up @@ -630,7 +630,7 @@ Restricting approval to a certain set of token IDs, quantities or other rules MA

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

Expand All @@ -648,13 +648,13 @@ The `balanceOfBatch` function allows clients to retrieve balances of multiple ow

In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block.

ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBatch` events in any instance where tokens are created, minted, or destroyed.
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 strategy is an example of how to mix fungible and non-fungible tokens together in the same contract. The top 128 bits of the uint256 `_id` parameter in any ERC-1155 function could represent the base token ID, while the bottom 128 bits might be used for any extra data passed to the contract.

Non-Fungible tokens can be interacted with using an index based accessor into the contract/token data set. Therefore to access a particular token set within a mixed data contract and particular NFT within that set, `_id` could be passed as `<uint128: base token id><uint128: index of NFT>`.
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.

Expand All @@ -665,7 +665,7 @@ 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
balanceOf(baseToken + index, msg.sender); // Get balance of the non-fungible token index
```

## References
Expand Down