ERC-7160: ERC-721 Multi-Metadata Extension
Multiple metadata URIs per token, with the option to pin a primary URI.
Abstract
This EIP proposes an extension to the ERC-721 standard to support multiple metadata URIs per token. It introduces a new interface, IERC721MultiMetadata
, which provides methods for accessing the metadata URIs associated with a token, including a pinned URI index and a list of all metadata URIs. The extension is designed to be backward compatible with existing ERC721Metadata
implementations.
Motivation
The current ERC-721 standard allows for a single metadata URI per token with the ERC721Metadata
implementation. However, there are use cases where multiple metadata URIs are desirable. Some example use cases are listed below:
- A token represents a collection of (cycling) assets with individual metadata
- An on-chain history of revisions to token metadata
- Appending metadata with different aspect ratios so that it can be displayed properly on all screens
- Dynamic and evolving metadata
- Collaborative and multi-artist tokens
This extension enables such use cases by introducing the concept of multi-metadata support.
The primary reason for having a multi-metadata standard in addition to the existing ERC721Metadata
standard is that dapps and marketplaces don't have a mechanism to infer and display all the token URIs. Giving a standard way for marketplaces to offer collectors a way to pin/unpin one of the metadata choices also enables quick and easy adoption of this functionality.
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The multi-metadata extension is OPTIONAL for ERC-721 contracts and it is RECOMMENDED to be used in conjunction with the ERC-4906 standard if implemented.
The TokenUriPinned
event MUST be emitted when pinning a token uri with the pinTokenUri
function.
The TokenUriUnpinned
event MUST be emitted when unpinning a token uri with the unpinTokenUri
function.
The tokenURI
function defined in the ERC-721 Metadata extension MUST return the pinned URI when a token has a pinned uri.
The tokenURI
function defined in the ERC-721 Metadata extension MUST return a default uri when a token has an unpinned uri.
The supportsInterface
method MUST return true
when called with 0x06e1bc5b
.
Implementing functionality to add or remove uris to a token MUST be implemented separately from this standard. It is RECOMMENDED that one of the event defined in ERC-4906 are emitted whenever uris are added or removed.
See the Implementation section for an example.
Rationale
Similar terminology to ERC-721 was used in order to keep fetching metadata familiar. The concept of pinning and unpinning metadata is introduced as it is clear that NFT owners might want to choose which piece of metadata to display. At first, we considered leaving the pinning and unpinning actions up to each developer, but realized that a standard interface for pinning and unpinning allows for dApps to easily implement universal support for multi-metadata tokens.
We first considered whether the tokenURIs
function should return just a string array, but added the extra information so that you could get all info desired in one call instead of potentially three calls. The pinned URI should be used as the primary URI for the token, while the list of metadata URIs can be used to access individual assets' metadata within the token. dApps could present these as a gallery or media carousels.
The TokenUriPinned
and TokenUriUnpinned
events included in this specification can be used by dApps to index what metadata to show. This can eliminate on-chain calls and event driven architecture can be used instead.
The reason why this standard recommends the use of ERC-4906 when adding or removing uris from a token is that there is already wide dApp support for this event and it already is what is needed - an alert to dApps that metadata for a token has been updated. We did not want to potentially cause dApp issues with duplicate events. A third party listening to this event could then call the tokenURIs
function to get the updated metadata.
Backwards Compatibility
This extension is designed to be backward compatible with existing ERC-721 contracts. The implementation of the tokenURI
method must either return the pinned token uri (if pinned) or some default uri (if unpinned).
Reference Implementation
An open-source reference implementation of the IERC721MultiMetadata
interface can be provided, demonstrating how to extend an existing ERC-721 contract to support multi-metadata functionality. This reference implementation can serve as a guide for developers looking to implement the extension in their own contracts.
Security Considerations
Care should be taken when specifying access controls for state changing events, such as those that allow uris to be added to tokens
and those specified in this standard: the pinTokenUri
and unpinTokenUri
functions. This is up to the developers to specify
as each application may have different requirements to allow for pinning and unpinning.
Copyright
Copyright and related rights waived via CC0.