tokenURI Interoperability

Abstract

ERC-721 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, and extends ERC-721 and ERC-1155 to enable interoperability between all three types of token URI.

Motivation

See the note about the metadata extension in ERC-721. 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:

/**
 * 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 an 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 an ERC-1155 token.
     **/
    erc1155?: boolean | undefined;
}

ERC-20 Extension

ERC-20 Interface Extension

Compliant contracts MUST implement the following Solidity interface:

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:

/**
 * Asset Metadata
 */
interface ERC20TokenMetadata {
    /**
     * Interoperability, 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:

interface ERC721TokenMetadataInterop extends ERC721TokenMetadata {
    /**
     * Interoperability, to avoid confusion between different token URIs
     **/
    interop: InteroperabilityMetadata;
}

ERC-1155 Extension

ERC-1155 Interface Extension

ERC-1155-compliant contracts using the metadata extension SHOULD implement the following Solidity interface:

pragma solidity ^0.8.0;

/// @title  ERC-1155 Metadata URI Interoperability Extension
interface ERC1155TokenMetadataInterop /* is ERC1155 */ {
    /// @notice         Gets an ERC-1046-compliant ERC-1155 token URI
    /// @param  tokenId The token ID to get the URI of
    /// @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(tokenId)` function, if present.
    function tokenURI(uint256 tokenId) 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:

interface ERC1155TokenMetadataInterop extends ERC1155TokenMetadata {
    /**
     * Interoperability, to avoid confusion between different token URIs
     **/
    interop: InteroperabilityMetadata;
}

Miscellaneous Recommendations

To save gas, it is RECOMMENDED for compliant contracts not to implement the name(), symbol(), or decimals() functions, and instead to only include them in the metadata URI. Additionally, for ERC-20 tokens, 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, 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.