mirror of https://github.com/status-im/EIPs.git
Automatically merged updates to draft EIP(s) 1155
Hi, I'm a bot! This change was automatically merged because: - It only modifies existing Draft or Last Call EIP(s) - The PR was approved or written by at least one author of each modified EIP - The build is passing
This commit is contained in:
Witek
EIP Automerge Bot
parent
7ff054d956
commit
f27695249c
262
EIPS/eip-1155.md
262
EIPS/eip-1155.md
|
|
@ -16,7 +16,7 @@ A standard interface for contracts that manage multiple token types. A single de
|
|||
|
||||
## Abstract
|
||||
|
||||
This standard outlines a smart contract interface where one can represent any number of Fungible and Non-Fungible token types in a single contract. 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` parameter is contained in each function's parameters and indicates a specific token or token type in a transaction.
|
||||
|
||||
|
|
@ -184,7 +184,7 @@ interface ERC1155TokenReceiver {
|
|||
|
||||
## Metadata
|
||||
|
||||
The URI value allows for ID substitution by clients. If the string `%s` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/%s.json` would be replaced with `https://token-cdn-domain/780000000000001e000000000000000000000000000000000000000000000000.json` if the client is referring to token ID `780000000000001e000000000000000000000000000000000000000000000000`.
|
||||
The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for large number of tokens to use the same on-chain string by defining a URI once, for a large collection of tokens. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/780000000000001e000000000000000000000000000000000000000000000000.json` if the client is referring to token ID `780000000000001e000000000000000000000000000000000000000000000000`.
|
||||
|
||||
The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix.
|
||||
|
||||
|
|
@ -213,7 +213,7 @@ interface ERC1155Metadata_URI {
|
|||
|
||||
### 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 `%s` exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard.
|
||||
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.
|
||||
|
||||
|
|
@ -252,7 +252,7 @@ An example of an ERC-1155 Metadata JSON file follows. The properties array propo
|
|||
{
|
||||
"name": "Asset Name",
|
||||
"description": "Lorem ipsum...",
|
||||
"image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/%s.png",
|
||||
"image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/{id}.png",
|
||||
"properties": {
|
||||
"simple_property": "example value",
|
||||
"rich_property": {
|
||||
|
|
@ -275,6 +275,226 @@ An example of an ERC-1155 Metadata JSON file follows. The properties array propo
|
|||
}
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Localization</summary>
|
||||
|
||||
#### Localization
|
||||
|
||||
Metadata localization should be standardized to increase presentation uniformity accross 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{
|
||||
"name": "Espacio Publicitario",
|
||||
"description": "Cada token representa un espacio publicitario único en la ciudad."
|
||||
}
|
||||
```
|
||||
|
||||
fr.json:
|
||||
```json
|
||||
{
|
||||
"name": "Espace Publicitaire",
|
||||
"description": "Chaque jeton représente un espace publicitaire unique dans la ville."
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Approval
|
||||
|
||||
The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval on a subset of tokens, standardized scoped approval is available as an extension. More complex approval schemes will require the use of an external contract enforcing custom rules.
|
||||
|
||||
### Scoped Approval Extension
|
||||
|
||||
This extension enables restrictions on approval's reach using a standardized method. When considering a smart contract
|
||||
managing tokens from multiple different domains, it makes sense to limit approvals to those domains. Scoped approval is a
|
||||
generalization of this idea. ERC-1155 implementors can define scopes as needed.
|
||||
|
||||
<details>
|
||||
<summary>Interface</summary>
|
||||
|
||||
```solidity
|
||||
pragma solidity ^0.5.2;
|
||||
|
||||
/**
|
||||
Note: The ERC-165 identifier for this interface is 0x30168307.
|
||||
*/
|
||||
interface ERC1155ScopedApproval {
|
||||
/**
|
||||
@dev MUST emit when approval changes for scope.
|
||||
*/
|
||||
event ApprovalForScope(address indexed _owner, address indexed _operator, bytes32 indexed _scope, bool _approved);
|
||||
|
||||
/**
|
||||
@dev MUST emit when the token IDs are added to the scope.
|
||||
By default, IDs are in no scope.
|
||||
The range is inclusive: _idStart, _idEnd, and all IDs in between have been added to the scope.
|
||||
_idStart must be lower than or equal to _idEnd.
|
||||
*/
|
||||
event AddIdsToScope(uint256 indexed _idStart, uint256 indexed _idEnd, bytes32 indexed _scope);
|
||||
|
||||
/**
|
||||
@dev MUST emit when the token IDs are removed from the scope.
|
||||
The range is inclusive: _idStart, _idEnd, and all IDs in between have been removed from the scope.
|
||||
_idStart must be lower than or equal to _idEnd.
|
||||
*/
|
||||
event RemoveIdsFromScope(uint256 indexed _idStart, uint256 indexed _idEnd, bytes32 indexed _scope);
|
||||
|
||||
/** @dev MUST emit when a scope URI is set or changes.
|
||||
URIs are defined in RFC 3986.
|
||||
The URI MUST point a JSON file that conforms to the "Scope Metadata JSON Schema".
|
||||
*/
|
||||
event ScopeURI(string _value, bytes32 indexed _scope);
|
||||
|
||||
/**
|
||||
@notice Returns the number of scopes that contain _id.
|
||||
@param _id The token ID
|
||||
@return The number of scopes containing the ID
|
||||
*/
|
||||
function scopeCountForId(uint256 _id) public view returns (uint32);
|
||||
|
||||
/**
|
||||
@notice Returns a scope that contains _id.
|
||||
@param _id The token ID
|
||||
@param _scopeIndex The scope index to query (valid values are 0 to scopeCountForId(_id)-1)
|
||||
@return The Nth scope containing the ID
|
||||
*/
|
||||
function scopeForId(uint256 _id, uint32 _scopeIndex) public view returns (bytes32);
|
||||
|
||||
/**
|
||||
@notice Returns a URI that can be queried to get scope metadata. This URI should return a JSON document containing, at least the scope name and description. Although supplying a URI for every scope is recommended, returning an empty string "" is accepted for scopes without a URI.
|
||||
@param _scope The queried scope
|
||||
@return The URI describing this scope.
|
||||
*/
|
||||
function scopeUri(bytes32 _scope) public view returns (string memory);
|
||||
|
||||
/**
|
||||
@notice Enable or disable approval for a third party ("operator") to manage the caller's tokens in the specified scope.
|
||||
@dev MUST emit the ApprovalForScope event on success.
|
||||
@param _operator Address to add to the set of authorized operators
|
||||
@param _scope Approval scope (can be identified by calling scopeForId)
|
||||
@param _approved True if the operator is approved, false to revoke approval
|
||||
*/
|
||||
function setApprovalForScope(address _operator, bytes32 _scope, bool _approved) external;
|
||||
|
||||
/**
|
||||
@notice Queries the approval status of an operator for a given owner, within the specified scope.
|
||||
@param _owner The owner of the Tokens
|
||||
@param _operator Address of authorized operator
|
||||
@param _scope Scope to test for approval (can be identified by calling scopeForId)
|
||||
@return True if the operator is approved, false otherwise
|
||||
*/
|
||||
function isApprovedForScope(address _owner, address _operator, bytes32 _scope) public view returns (bool);
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Scope Metadata JSON Schema</summary>
|
||||
|
||||
This shema is similar to the token metadata schema and also allows localization. `{id}` and `{locale}` should be replaced with the proper values.
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Scope Metadata",
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Identifies the scope in a human-readable way.",
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Describes the scope to allow users to make informed approval decisions.",
|
||||
},
|
||||
"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/)."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
## Rationale
|
||||
|
||||
<details>
|
||||
|
|
@ -319,6 +539,28 @@ As the Ethereum ecosystem continues to grow, many dapps are relying on tradition
|
|||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
Approval</summary>
|
||||
|
||||
### 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. However, it may be desired to restrict approval in
|
||||
some applications. Restricted approval can prevent losses in cases where users do not audit the contracts they're
|
||||
approving. No standard API is supplied to manage scopes as this is implementation specific. Some implementations may
|
||||
opt to offer a fixed number of scopes, or assign a specific set of scopes to certain types. Other implementations may
|
||||
open up scope configuration to its users and offer methods to create scopes and assign IDs to them.
|
||||
|
||||
Sample use cases for scopes:
|
||||
|
||||
* A company may represent it's fleet of vehicles on the blockchain and it could create a scope for each regional office.
|
||||
* Game developers could share an ERC-1155 contract where each developer manages tokens under a specified scope.
|
||||
* Tokens of different value magnitude could be split in separate scopes. 0.01Ξ tokens would be kept separate from
|
||||
10,000.00Ξ tokens.
|
||||
|
||||
</details>
|
||||
|
||||
## 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.
|
||||
|
|
@ -339,16 +581,6 @@ The `balanceOfBatch` function allows clients to retrieve balances of multiple ow
|
|||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
Approval</summary>
|
||||
|
||||
### Approval
|
||||
|
||||
The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. Single-token based approval of specific token values is not part of the standard. To scope an approval to a specific set or quantity of tokens, we recommend deploying a contract that contains the desired rules, and directing end-users to approve this contract to manage their set of tokens.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
Enumeration</summary>
|
||||
|
|
@ -407,4 +639,4 @@ balanceOf(baseToken + index, msg.sender); // Get balance of the Non-Fungible tok
|
|||
- [Beyond Gaming - Exploring the Utility of ERC-1155 Token Standard!](https://blockgeeks.com/erc-1155-token/)
|
||||
|
||||
## Copyright
|
||||
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|
||||
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|
||||
Loading…
Reference in New Issue