ERC-5185: NFT Updatable Metadata Extension
An interface extension for ERC-721/ERC-1155 controlled metadata updates
Abstract
This specification defines a standard way to allow controlled NFTs' metadata updates along predefined formulas. Updates of the original metadata are restricted and defined by a set of recipes and the sequence and results of these recipes are deterministic and fully verifiable with on-chain metadata updates event. The proposal depends on and extends the EIP-721 and EIP-1155.
Motivation
Storing voluminous NFT metadata on-chain is often neither practical nor cost-efficient.
Storing NFT metadata off-chain on distributed file systems like IPFS can answer some needs of verifiable correlation and permanence between an NFT tokenId and its metadata but updates come at the cost of being all or nothing (aka changing the tokenURI). Bespoke solutions can be easily developed for a specific NFT smart contract but a common specification is necessary for NFT marketplaces and third parties tools to understand and verify these metadata updates.
This ERC allows the original JSON metadata to be modified step by step along a set of predefined JSON transformation formulas. Depending on NFT use-cases, the transformation formulas can be more or less restrictive.
As examples, an NFT representing a house could only allow append-only updates to the list of successive owners, and a game using NFT characters could let some attributes change from time to time (e.g. health, experience, level, etc) while some other would be guaranteed to never change (e.g. physicals traits etc).
This standard extension is compatible with NFTs bridged between Ethereum and L2 networks and allows efficient caching solutions.
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 metadata updates extension is OPTIONAL for EIP-721 and EIP-1155 contracts.
The original metadata SHOULD conform to the "ERC-5185 Updatable Metadata JSON Schema" which is a compatible extension of the "ERC-721 Metadata JSON Schema" defined in ERC-721.
"ERC-5185 Updatable Metadata JSON Schema" :
"NFT Metadata Updates JSON Schema" :
Engines
Only one engine is currently defined in this extension proposal.
If the engine in the original metadata is "jsonata@1.8.*", updated metadata is calculated starting from original metadata and applying each update sequentially (all updates which are present in all the URIs emitted by the event MetadataUpdates for which tokenId matches).
For each step, the next metadata is obtained by the javascript calculation (or compatible jsonata implementation in other language) :
With evalString is found with recipeKey in the original metadata recipes list.
If the key is not present in the original metadata list, previousMetadata is kept as the valid updated metadata.
If the evaluation throws any errors, previousMetadata is kept as the valid updated metadata.
If a validation Schema JSON has been defined and the result JSON nextMetadata does not conform, that update is not valid and previousMetadata is kept as the valid updated metadata.
Rationale
There have been numerous interesting uses of EIP-721 and EIP-1155 smart contracts that associate for each token essential and significant metadata. While some projects (e.g. EtherOrcs) have experimented successfully to manage these metadata on-chain, that experimental solution will always be limited by the cost and speed of generating and storing JSON on-chain. Symmetrically, while storing the JSON metadata at URI endpoint controlled by traditional servers permit limitless updates the metadata for each NFT, it is somehow defeating in many uses cases, the whole purpose of using a trustless blockchain to manage NFT: indeed users may want or demand more permanence and immutability from the metadata associated with their NFT.
Most use cases have chosen intermediate solutions like IPFS or arweave to provide some permanence or partial/full immutability of metadata. This is a good solution when an NFT represents a static asset whose characteristics are by nature permanent and immutable (like in the art world) but less so with other use cases like gaming or NFT representing a deed or title. Distinguishable assets in a game often should be allowed to evolve and change over time in a controlled way and titles need to record real life changes.
The advantages of this standard is precisely to allow these types of controlled transformations over time of each NFT metadata by applying sequential transformations starting with the original metadata and using formulas themselves defined in the original metadata.
The original metadata for a given NFT is always defined as the JSON pointed by the result of tokenURI for EIP-721 and function uri for EIP-1155.
The on-chain log trace of updates guarantee that anyone can recalculate and verify independently the current updated metadata starting from the original metadata. The fact that the calculation is deterministic allows easy caching of intermediate transformations and the efficient processing of new updates using these caches.
The number of updates defined by each event is to be determined by the smart contract logic and use case, but it can easily scale to thousands or millions of updates per event. The function(s) that should emit MetadataUpdates and the frequency of these on-chain updates is left at the discretion of this standard implementation.
The proposal is extremely gas efficient, since gas costs are only proportional to the frequency of committing changes. Many changes for many tokens can be batched in one transaction for the cost of only one emit.
Reference Implementation
Transformation engines
We have been experimenting with this generic Metadata update proposal using the JSONata transformation language.
Here is a very simple example of a NFT metadata for an imaginary 'little monster' game :
This updatable metadata can only be updated to increment by one the trait attribute "Level".
An example JSON updates metadata would be :
Security Considerations
A malicious recipe in the original metadata might be constructed as a DDoS vector for third parties marketplaces and tools that calculate NFT updated JSON metadata. They are encouraged to properly encapsulate software in charge of these calculations and put limits for the engine updates processing.
Smart contracts should be careful and conscious of using this extension and still allow the metadata URI to be updated in some contexts (by not having the same URI returned by tokenURI or uri for a given tokenId over time). They need to take into account if previous changes could have been already broadcasted for that NFT by the contract, if these changes are compatible with the new "original metadata" and what semantic they decide to associate by combining these two kinds of "updates".
Backwards Compatibility
The proposal is fully compatible with both EIP-721 and EIP-1155. Third-party applications that don't support this EIP will still be able to use the original metadata for each NFT.
Copyright
Copyright and related rights waived via CC0.