--- eip: 5625 title: NFT Metadata JSON Schema dStorage Extension description: Add a dStorage property to non-fungible tokens (NFTs) metadata JSON schema to provide decentralized storage information of NFT assets author: Gavin Fu (@gavfu) discussions-to: https://ethereum-magicians.org/t/eip-5625-nft-metadata-json-schema-dstorage-extension/10754 status: Review type: Standards Track category: ERC created: 2022-09-08 requires: 721, 1155 --- ## Abstract This EIP extends the NFT metadata JSON schema defined in [EIP-721](./eip-721.md) and [EIP-1155](./eip-1155.md), adding a `dStorage` key that provides information about how the NFT data is stored. ## Motivation As highly valuable crypto properties, NFT assets intrinsically demand guaranteed storage to assure their **immutability**, **reliability**, and **durability**. NFT ownership is tracked by [EIP-721](./eip-721.md) or [EIP-1155](./eip-1155.md) smart contracts, hence persisted in blockchain, which is not a problem. But how about the mime-type assets that NFT tokens represent? Ideally, they should also be stored in some reliable and verifiable decentralized storage system that is designed to store larger amounts of data than the blockchain itself. As an effort to promote **decentralized storage** adoption in NFT world, we propose to add additional **dStorage** information into NFT metadata JSON schema. As a refresher, let's review existing NFT metadata JSON schema standards. [EIP-721](./eip-721.md) defines a standard contract method `tokenURI` to return a given NFT's metadata JSON file, conforming to the *[EIP-721](./eip-721.md) Metadata JSON Schema*, which defines three properties: `name`, `description` and `image`. Similarly, [EIP-1155](./eip-1155.md) also defines a standard contract method `uri` to return NFT metadata JSON files conforming to the *[EIP-1155](./eip-1155.md) Metadata JSON Schema*, which defines properties like `name`, `decimals`, `description`, `image`, `properties`, `localization`, etc. Besides, as the world's largest NFT marketplace nowadays, OpenSea defines their own *Metadata Standards*, including a few more properties like `image_data`, `external_url`, `attributes`, `background_color`, `animation_url`, `youtube_url`, etc. This standard is de facto respected and followed by other NFT marketplaces like LooksRare. None of these standards conveys storage information about the mime-type asset that the NFT token represents. This proposal is an effort to fill the missing part. ## 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. In addition to the existing properties, the Metadata JSON file returned by [EIP-721](./eip-721.md) and [EIP-1155](./eip-1155.md) smart contracts (via `tokenURI` and `uri` methods, respectively), should OPTIONALLY contains one more `dStorage` property. For [EIP-721](./eip-721.md) smart contracts, the Metadata JSON file schema is: ```json { "title": "Asset Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this NFT represents" }, "description": { "type": "string", "description": "Describes the asset to which this NFT represents" }, "image": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." }, "dStorage": { "type": "object", "required": ["platform", "description", "persistence_mechanism", "challenge_mechanism", "consensus", "dstorage_note"], "properties": { "platform": { "type": "string", "description": "dStorage platform name like Swarm, Arweave, Filecoin, Crust, etc" }, "description": { "type": "string", "description": "A brief description of the dStorage platform" }, "persistence_mechanism": { "type": "string", "description": "Persistence mechanism or incentive structure of the dStorage platform, like 'blockchain-based', 'contract-based', etc" }, "challenge_mechanism": { "type": "string", "description": "Challenge mechanism of the dStorage platform, like Arweave's proof-of-access, etc" }, "consensus": { "type": "string", "description": "Consensus mechanism of the dStorage platform, like PoW, PoS, etc" }, "dstorage_note": { "type": "string", "description": "A note to prove the storage of the NFT asset on the dStorage platform, like a Filecoin deal id, a Crust place_storage_order transaction hash, etc" } } } } } ``` For [EIP-1155](./eip-1155.md) smart contracts, the Metadata JSON file schema is: ```json { "title": "Token Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this token represents", }, "decimals": { "type": "integer", "description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation." }, "description": { "type": "string", "description": "Describes the asset to which this token represents" }, "image": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." }, "properties": { "type": "object", "description": "Arbitrary properties. Values may be strings, numbers, object or arrays.", }, "localization": { "type": "object", "required": ["uri", "default", "locales"], "properties": { "uri": { "type": "string", "description": "The URI pattern to fetch localized data from. This URI should contain the substring `{locale}` which will be replaced with the appropriate locale value before sending the request." }, "default": { "type": "string", "description": "The locale of the default data within the base JSON" }, "locales": { "type": "array", "description": "The list of locales for which data is available. These locales should conform to those defined in the Unicode Common Locale Data Repository (http://cldr.unicode.org/)." } } }, "dStorage": { "type": "object", "required": ["platform", "description", "persistence_mechanism", "challenge_mechanism", "consensus", "dstorage_note"], "properties": { "platform": { "type": "string", "description": "dStorage platform name like Swarm, Arweave, Filecoin, Crust, etc" }, "description": { "type": "string", "description": "A brief description of the dStorage platform" }, "persistence_mechanism": { "type": "string", "description": "Persistence mechanism or incentive structure of the dStorage platform, like 'blockchain-based', 'contract-based', etc" }, "challenge_mechanism": { "type": "string", "description": "Challenge mechanism of the dStorage platform, like Arweave's proof-of-access, etc" }, "consensus": { "type": "string", "description": "Consensus mechanism of the dStorage platform, like PoW, PoS, etc" }, "dstorage_note": { "type": "string", "description": "A note to prove the storage of the NFT asset on the dStorage platform, like a Filecoin deal id, a Crust place_storage_order transaction hash, etc" } } } } } ``` ## Rationale ### Choice between Interface and JSON Schema Extension An extension of the EIP-721 or EIP-1155 contract interfaces would unnecessarily require additional code to implement, and would not be available for use by NFT projects that already have their NFT smart contracts finalized and deployed. An optional JSON schema extension is noninvasive, and more easily adopted. # Backwards Compatibility This EIP is backward compatible with [EIP-721](./eip-721.md) and [EIP-1155](./eip-1155.md). ## Security Considerations Needs discussion. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).