Hosting your NFT on IPFS

If you don't know it yet, having an NFT does not mean that the NFT's file is uploaded as-is on the blockchain. Rather, an NFT corresponds to a blockchain block that contains a certain token. This token stores a "pointer" or link, called tokenURI, which contains the online address to a metadata file, which itself references the media file using another URI.

Because of the peer-to-peer nature of the blockchain, you cannot just host your NFT file and its metadata file on any web hosting service. Your tokenURI needs to stay permanent (or "immutable") and portable across apps and marketplaces, for as long as can be, possibly forever.

This is where IPFS enters the scene.

About IPFS

IPFS, for InterPlanetary File System, is a decentralised file network which servers the purpose of hosting and sharing data across distributed networks. NFT platforms can fetch data from IPFS instead of relying on a single server, and the IPFS protocol makes it "feel" like all hosted files are local.

Do I need to learn about IPFS right now?

It depends on your chosen method to mint your NFT:

• Using vanilla code (such as viem or ethers): Yes, you need a valid tokenURI (e.g., ipfs://.../metadata.json) beforehand.

• Through a dashboard such as thirdweb: No. Uploading to IPFS is built in. You can still paste an existing ipfs://... if you have one in the NFT parameters.

• Using most Web3 SDKs (such as Rarible's Multichain SDK): Yes, they will expect a URI. Some tools might help with uploads, but not most.

The IPFS website has an extensive page on NFT Storing best practices.

Details of NFT upload

When uploading your NFT, you need to perform two uploads to the Content Identifier (CID) that IPFS generates for you:

• The content itself, for which IPFS returns an IPFS URL for the hosted file.

• The metadata file, which references the CID of the media file, and must contain the IPFS URL for the file.

Both are to be uploaded on IPFS under the same CID.

Ideally, your toolset takes this in charge so that you don't have to do it all manually.

For information purpose, here is what a minimal metadata.json file would look like:

{ 
    "name": "Stadium Pass #25456456", 
    "description": "PSG supporter entry ticket", 
    "image": "ipfs:///filename.png",           // for static images only!
    // "animation_url": "ipfs:///filename.mp4" // for video and audio files.
    "attributes": [
    { 
        "trait_type": "Tier", 
        "value": "Gold" 
    }] 
}

To learn more about NFT metadata structure (for instance, why you should use image for images and animation_url for videos), we advise you to read this document from OpenSea:

Metadata StandardsOpenSea Developer Documentation

Note: You are not supposed to write the metadata file from scratch! Your toolset should be able to generate it for you.

You can either run your own IPFS node, or pay for an IPFS-host, such as Pinata, which offers a free pricing plan that might be enough for your needs.

Follow Pinata's quick-start guide in order to obtain your API credentials (consisting of an API key, an API secret, and a JWT token) and your Dedicated Gateway domain (for instance, blue-genetic-quail-122.mypinata.cloud).

As this documentation is not meant to describe everything about IPFS, we advise you to dive into the topic through online searches. You can start with this Pinata explainer:

How does IPFS work with NFTs? - Pinata DocsPinata Docs

... or this blogpost from thirdweb:

What Is IPFS and How Does it Store NFT Metadata?thirdweb