ERC-721 introduced a tokenURI function for non-fungible tokens to handle miscellaneous metadata such as:
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.
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:
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.
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;
}
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);
}
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[];
}
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-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);
}
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;
}
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.
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.
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.
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 and related rights waived via CC0.