Merge 4b4335e into 8788879

Author: lightclient

EIPS/eip-1046.md

@@ -1,221 +1 @@
----
-eip: 1046
-title: tokenURI Interoperability
-description: Extends ERC-20 with an ERC-721-like tokenURI, and extends ERC-721 and ERC-1155 with interoperability
-author: Tommy Nicholas (@tomasienrbc), Matt Russo (@mateosu), John Zettler (@JohnZettler), Matt Condon (@shrugs), Gavin John (@Pandapip1)
-discussions-to: https://ethereum-magicians.org/t/eip-1046-erc-20-metadata-extension/13036
-status: Final
-type: Standards Track
-category: ERC
-created: 2018-04-13
-requires: 20, 721, 1155
----
-
-## Abstract
-
-[ERC-721](./eip-721.md) introduced a `tokenURI` function for non-fungible tokens to handle miscellaneous metadata such as:
-
-- thumbnail image
-- title
-- description
-- special asset properties
-- etc.
-
-This ERC adds a `tokenURI` function to [ERC-20](./eip-20.md), and extends [ERC-721](./eip-721.md) and [ERC-1155](./eip-1155.md) to enable interoperability between all three types of token URI.
-
-## Motivation
-
-See the note about the metadata extension in [ERC-721](./eip-721.md#rationale). The same arguments apply to ERC-20.
-
-Being able to use similar mechanisms to extract metadata for ERC-20, ERC-721, ERC-1155, and future standards is useful for determining:
-
-- What type of token a contract is (if any);
-- How to display a token to a user, either in an asset listing page or on a dedicated token page; and
-- Determining the capabilities of the token
-
-## Specification
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
-
-### Interoperability Metadata
-
-The following TypeScript interface is used in later sections:
-
-```typescript
-/**
- * Interoperability metadata.
- * This can be extended by other proposals.
- * 
- * All fields MUST be optional.
- * **Not every field has to be a boolean.** Any optional JSON-serializable object can be used by extensions.
- */
-interface InteroperabilityMetadata {
-    /**
-     * This MUST be true if this is ERC-1046 Token Metadata, otherwise, this MUST be omitted.
-     * Setting this to true indicates to wallets that the address should be treated as an ERC-20 token.
-     **/
-    erc1046?: boolean | undefined;
-
-    /**
-     * This MUST be true if this is ERC-721 Token Metadata, otherwise, this MUST be omitted.
-     * Setting this to true indicates to wallets that the address should be treated as a ERC-721 token.
-     **/
-    erc721?: boolean | undefined;
-
-    /**
-     * This MUST be true if this is ERC-1155 Token Metadata, otherwise, this MUST be omitted.
-     * Setting this to true indicates to wallets that the address should be treated as a ERC-1155 token.
-     **/
-    erc1155?: boolean | undefined;
-}
-```
-
-### ERC-20 Extension
-
-#### ERC-20 Interface Extension
-
-Compliant contracts MUST implement the following Solidity interface:
-
-```solidity
-pragma solidity ^0.8.0;
-
-/// @title  ERC-20 Metadata Extension
-interface ERC20TokenMetadata /* is ERC20 */ {
-    /// @notice     Gets an ERC-721-like token URI
-    /// @dev        The resolved data MUST be in JSON format and support ERC-1046's ERC-20 Token Metadata Schema
-    function tokenURI() external view returns (string);
-}
-```
-
-#### ERC-20 Token Metadata Schema
-
-The resolved JSON of the `tokenURI` described in the ERC-20 Interface Extension section MUST conform to the following TypeScript interface:
-
-```typescript
-/**
- * Asset Metadata
- */
-interface ERC20TokenMetadata {
-    /**
-     * Interoperabiliy, to differentiate between different types of tokens and their corresponding URIs.
-     **/
-    interop: InteroperabilityMetadata;
-    
-    /**
-     * The name of the ERC-20 token. 
-     * If the `name()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value.
-     */
-    name?: string;
-    
-    /**
-     * The symbol of the ERC-20 token. 
-     * If the `symbol()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value.
-     */
-    symbol?: string;
-    
-    /**
-     * The decimals of the ERC-20 token. 
-     * If the `decimals()` function is present in the ERC-20 token, these MUST be the same value.
-     * Defaults to 18 if neither this parameter nor the ERC-20 `decimals()` function are present.
-     */
-    decimals?: number;
-    
-    /**
-     * Provides a short one-paragraph description of the ERC-20 token, without any markup or newlines.
-     */
-    description?: string;
-    
-    /**
-     * A URI pointing to a resource with mime type `image/*` that represents this token.
-     * If the image is a bitmap, it SHOULD have a width between 320 and 1080 pixels
-     * The image SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.
-     */
-    image?: string;
-    
-    /**
-     * One or more URIs each pointing to a resource with mime type `image/*` that represents this token.
-     * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels
-     * Images SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.
-     */
-    images?: string[];
-    
-    /**
-     * One or more URIs each pointing to a resource with mime type `image/*` that represent an icon for this token.
-     * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels, and MUST have a height equal to its width
-     * Images MUST have an aspect ratio of 1:1, and use a transparent background
-     */
-    icons?: string[];
-}
-```
-
-### ERC-721 Extension
-
-#### Extension to the ERC-721 Metadata Schema
-
-Contracts that implement ERC-721 and use its token metadata URI SHOULD to use the following TypeScript extension to the metadata URI:
-
-```typescript
-interface ERC721TokenMetadataInterop extends ERC721TokenMetadata {
-    /**
-     * Interoperabiliy, to avoid confusion between different token URIs
-     **/
-    interop: InteroperabilityMetadata;
-}
-```
-
-### ERC-1155 Extension
-
-#### ERC-1155 Interface Extension
-
-[ERC-1155](./eip-1155.md)-compliant contracts using the metadata extension SHOULD implement the following Solidity interface:
-
-```solidity
-pragma solidity ^0.8.0;
-
-/// @title  ERC-1155 Metadata URI Interoperability Extension
-interface ERC1155TokenMetadataInterop /* is ERC1155Metadata */ {
-    /// @notice     Gets an ERC-1046-compliant ERC-1155 token URI
-    /// @dev        The resolved data MUST be in JSON format and support ERC-1046's Extension to the ERC-1155 Token Metadata Schema
-    ///             This MUST be the same uri as the `uri()` function
-    function tokenURI() external view returns (string);
-}
-```
-
-#### Extension to the ERC-1155 Metadata Schema
-
-Contracts that implement ERC-1155 and use its token metadata URI are RECOMMENDED to use the following extension to the metadata URI. Contracts that implement the interface described in the ERC-1155 Interface Extension section MUST use the following TypeScript extension:
-
-```typescript
-interface ERC1155TokenMetadataInterop extends ERC1155TokenMetadata {
-    /**
-     * Interoperabiliy, to avoid confusion between different token URIs
-     **/
-    interop: InteroperabilityMetadata;
-}
-```
-
-### Miscellaneous Recommendations
-
-To save gas, it is RECOMMENDED for compliant contracts not to implement the optional `name()`, `symbol()`, or `decimals()` functions, and instead to only include them in the metadata URI. Additionally, if the decimals is `18`, then it is NOT RECOMMENDED to include the `decimals` field in the metadata.
-
-## Rationale
-
-This ERC makes adding metadata to ERC-20 tokens more straightforward for developers, with minimal to no disruption to the overall ecosystem. Using the same parameter name makes it easier to reuse code.
-
-Additionally, the recommendations not to use ERC-20's `name`, `symbol`, and `decimals` functions save gas.
-
-Built-in interoperability is useful as otherwise it might not be easy to differentiate the type of the token. Interoperability could be done using [ERC-165](./eip-165.md), but static calls are time-inefficient for wallets and websites, and is generally inflexible. Instead, including interoperability data in the token URI increases flexibility while also giving a performance increase.
-
-## Backwards Compatibility
-
-This EIP is fully backwards compatible as its implementation simply extends the functionality of ERC-20 tokens and is optional. Additionally, it makes backward compatible recommendations for ERC-721 and ERC-1155 tokens.
-
-## Security Considerations
-
-### Server-Side Request Forgery (SSRF)
-
-Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database.
-
-## Copyright
-
-Copyright and related rights waived via [CC0](../LICENSE.md).
+This file was moved to https://github.com/ethereum/ercs/blob/master/ercs/erc-1046.md