ERC-1046: tokenURI Interoperability

Extends ERC-20 with an ERC-721-like tokenURI, and extends ERC-721 and ERC-1155 with interoperability

Metadata

Status: FinalStandards Track: ERCCreated: 2018-04-13

Authors

Tommy Nicholas (@tomasienrbc), Matt Russo (@mateosu), John Zettler (@JohnZettler), Matt Condon (@shrugs), Gavin John (@Pandapip1)

Requires

EIP-20, EIP-721, EIP-1155

Links

GitHub page Discussion on Ethereum Magicians

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:

ERC-20 Extension

ERC-20 Interface Extension

Compliant contracts MUST implement the following Solidity interface:

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:

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:

ERC-1155 Extension

ERC-1155 Interface Extension

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

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:

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.