How to use IPFS to store and host NFTs (Tutorial)

One of the core values ​​of NFT is that it can be preserved for a long time and prevent tampering. Unfortunately, many current consumer-oriented NFTs do not have these properties due to fundamental design flaws. It is common to see some NFTs claiming to "live forever on the blockchain", but in reality, due to cost and blockchain storage capacity limitations, only ownership records and metadata associated with the NFT are stored.

Oftentimes, these links are fragile (https://www.vice.com/en/article/pkdj79/peoples-expensive-nfts-keep-vanishing-this-is-why), using HTTP to direct users to a specific location rather than the asset itself. This means that the content the link points to may become invalid or change in the future, resulting in the loss of the original asset (leaving only a worthless record of ownership).

IPFS can solve this problem, and NFTs using IPFS will have an advantage. But only by complying with existing specifications can data be better preserved and accessed permanently. With the rapid popularity of NFTs, now is a good time to review the best practices for storing and linking NFT data on IPFS. In this article, we will explore two recent hot topics: content addressing and data integrity. On the IPFS documentation website, there is a new section Best Practices for Storing NFT Data Using IPFS (https://docs.ipfs.io/how-to/best-practices-for-nft-data/) to help you learn more details.

Content Addressing

IPFS content identifiers (https://docs.ipfs.io/guides/concepts/cid/) (CID) are extremely powerful and flexible in accurately identifying content, no matter where or how it is stored. To maximize these benefits, developers should follow the following recommendations and conventions when linking IPFS data.

Link Overview

This is not a comprehensive explanation of CIDs (there is already excellent material on this (https://docs.ipfs.io/how-to/address-ipfs-on-web/#dweb-addressing-in-brief)). However, this article aims to give readers a few insights:

CID

CID is self-describing and is a unique identifier for any content.

Example: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

CID should be used in your application code and other contexts that explicitly use IPFS.

We recommend converting CIDs to IPFS URIs on disk, especially in metadata or blockchain records that are written and never change. Adding ipfs:// URIs to CIDs adds context, making it easier for users and automated tools to find the linked content.

IPFS URI

Uniform Resource Identifiers (URIs) are used to specify specific content in a protocol. The protocol is determined by the URI format (attached to the URI as a prefix, plus ://). The URI format for IPFS is ipfs. Sometimes the URI can have a path appended to the end.

example:

ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

ipfs://bafybeigvafaks2bvivtv46n2z7uxszpvl25jhvzc6dbhnjjgjkbeia5jta/nft.mp4

An IPFS URI is a standard IPFS link to a file or directory. When linking to IPFS data from a smart contract, the IPFS URI indicates that the data should be obtained through the IPFS system.

IPFS URIs should also be used when linking to images and other media resources on IPFS in the structured metadata of an NFT.

HTTP Gateway URL

HTTP gateways (https://docs.ipfs.io/how-to/address-ipfs-on-web/#http-gateways) help with compatibility with older browsers that cannot natively resolve IPFS URIs. Such links should only be used in the application's interface and should not be stored in the blockchain or NFT's metadata.

Example: https://dweb.link/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

It should be noted that HTTP gateways centralize content distribution, are a possible vector for man-in-the-middle attacks, and bring potential single points of failure - if the gateway operator goes offline or loses connection, the link will fail. Browsers with built-in IPFS support (through the IPFS Companion (https://docs.ipfs.io/install/ipfs-companion/) browser extension, or native support, such as Brave (https://brave.com/ipfs-support/)) can avoid these problems because they can automatically extract CIDs from such links and load data from IPFS according to user settings.

Addressing in different scenarios

In different scenarios, developers should use appropriate link settings according to the specific situation.

On-chain

The IPFS URI should be used for the resources and metadata corresponding to an NFT on the NFT smart contract.

Example: ipfs://bafybeibnsoufr2renqzsh347nrx54wcubt5lgkeivez63xvivplfwhtpym/metadata.json

We recommend generating an IPFS URI before generating an NFT, and storing the URI in full on-chain. This is the simplest approach for smart contract interfaces that pass in a URI. And the ipfs:// URI format lets the application know that the data is on IPFS.

Metadata

In the metadata of an NFT, the IPFS URI should be used, which is the most unambiguous and long-term reliable way to link to an IPFS resource in text.

Here is an example of an IPFS URI linking to an NFT media asset: ipfs://bafybeigvafaks2bvivtv46n2z7uxszpvl25jhvzc6dbhnjjgjkbeia5jta/nft.mp4.

Developers can use a public HTTP gateway (https://docs.ipfs.io/how-to/address-ipfs-on-web/#http-gateways) to gain compatibility.

At the same time, other ways of linking to content (such as URLs that are not IPFS HTTP gateways) should be avoided. Ordinary HTTP links can only serve as temporary mirrors of content at best, because the content of the link can be easily changed. On the blockchain, data is permanently stored and cannot be tampered with, so using HTTP on the chain is fragile and has the risk of failure.

In contrast, IPFS URIs are permanent and can be safely used as canonical links to data. By using IPFS URIs as "source of truth" links, applications can more easily use a variety of different storage solutions, or switch to different gateways in the future, just by generating a new gateway link. This is more flexible than "hard-coding" a specific gateway link into the permanent record of the blockchain.

application

In user-facing applications, developers should link to IPFS content in the following two ways.

1. IPFS URI

2. HTTP gateway URL

Until more browsers support IPFS URIs natively. Note that both links are easily generated from either the raw CID or the IPFS URI.

Here is an HTTP gateway URL pointing to the public dweb.link:

https://dweb.link/ipfs/bafybeigvafaks2bvivtv46n2z7uxszpvl25jhvzc6dbhnjjgjkbeia5jta/nft.mp4

You can also use the CID as a subdomain instead of putting it in the URL path:

https://bafybeigvafaks2bvivtv46n2z7uxszpvl25jhvzc6dbhnjjgjkbeia5jta.ipfs.dweb.link/nft.mp4

Both examples correspond to this standard IPFS URI: ipfs://bafybeigvafaks2bvivtv46n2z7uxszpvl25jhvzc6dbhnjjgjkbeia5jta/nft.mp4.

Data Integrity

An important point about NFT assets is their integrity - including the asset itself and all related data. IPFS uses CID to protect the integrity of NFT data, ensuring that it has not been tampered with since the link was created.

Developers should follow the following suggestions to maximize the effectiveness of IPFS's built-in data verification features.

Linking asset metadata

Metadata is an integral part of the value of NFT. Therefore, to preserve the value of assets, metadata should also be stored when storing assets on IPFS, and both should be accessible.

The preferred method to achieve this goal is as follows:

1. Create two new directories (one for assets and one for metadata)

2. Add assets to its catalog

3. Add the asset directory to IPFS and record its CID

4. Create metadata in the corresponding directory and create an IPFS URI using the CID from step 3. The URI should contain the directory’s CID and the asset file name

5. Add the metadata directory to IPFS and record its CID.

6. Use the CID from step 5 to create an IPFS URI for the metadata, store the URI on-chain, and add the ownership record

This process allows developers to include file names in links (making it easier for users to interact with them) while ensuring that metadata and assets can be used independently.

Here is an example of JSON metadata that contains an IPFS URI linking to an image file:

The image is accessible using the IPFS URI ipfs://bafybeidfjqmasnpu6z7gvn7l6wthdcyzxh5uystkky3xvutddbapchbopi/no-time-to-explain.jpeg`. In the UI, your application can create a gateway URL to facilitate users to obtain the image using HTTP, such as https://dweb.link/ipfs/bafybeidfjqmasnpu6z7gvn7l6wthdcyzxh5uystkky3xvutddbapchbopi/no-time-to-explain.jpeg.

Once the metadata is created and stored as a JSON file on IPFS, its CID can be used to create a URI such as ipfs://bafybeibnsoufr2renqzsh347nrx54wcubt5lgkeivez63xvivplfwhtpym/metadata.json. This URI can be stored in a smart contract.

A practical example of the whole process can be found on the IPFS documentation website How to Issue NFTs on IPFS (https://docs.ipfs.io/how-to/mint-nfts-with-ipfs/#a-short-introduction-to-nfts). The document uses javascript to demonstrate the whole process in detail.

High Availability

One of the main reasons for using a decentralized network like IPFS to serve content is to protect against link failures (https://en.wikipedia.org/wiki/Link_rot). This is achieved by having other nodes in the network jointly operate a data mirror service. However, developers who have high requirements for data availability should not rely on the altruism of other nodes. To ensure that the linked content is available, developers should pin (https://docs.ipfs.io/concepts/persistence/) the CID of the content on their own storage nodes and store and distribute the content with nodes willing to help. If desired, developers can also use a pinning service (https://docs.ipfs.io/how-to/work-with-pinning-services/) to operate it on their behalf.