ERC-7160: ERC-721 Multi-Metadata Extension

Multiple metadata URIs per token, with the option to pin a primary URI.

Metadata

Status: FinalStandards Track: ERCCreated: 2023-06-09

Authors

0xG (@0xGh), Marco Peyfuss (@mpeyfuss)

Requires

EIP-165, EIP-721

Links

GitHub page Discussion on Ethereum Magicians

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.