How to store NFTs on Arweave

When creating an NFT, three distinct components are involved:

Smart contract: Tracks NFT ownership
NFT metadata: Structured data that describes the NFT
NFT assets: Actual JPGs, GIFs, video and audio files

alt_text

The Arweave blockchain is designed for permanently storing data of any size, which makes it the ideal choice for storing NFT metadata and assets. This guide covers why Arweave is the best choice for your NFTs and how to use Irys when uploading to Arweave.

The disappearing NFT problem

If NFT metadata and assets are stored on providers that lack the same permanence guarantees of Arweave, like IPFS or cloud providers, it can lead to the NFT disappearing. The NFT will still “exist” in a user’s wallet, but the visual assets will disappear. This famously happened with FTX. They stored their NFT assets on cloud service providers, and then when they went bankrupt and stopped paying their bills, the NFTs disappeared.

Permanent data

Unlike IPFS and cloud storage providers, data on Arweave is permanent because it is:

Fault-tolerant: The data is stored by miners across the world. As of 2023, there are 800 complete replicas stored in every corner of the globe. No number of failed drives or natural disasters can destroy this data.
Tamperproof: When you upload data, it is given an address formed by hashing it. Any change to the data would change the hash, which makes it impossible to alter the data without altering its address.
Paid-for: You pay a one-time fee when uploading data to Arweave and a portion of that payment is reserved to incentivize miners to store your data in perpetuity. This is an important distinction from other Web3 storage providers as it helps guarantee your uploads will be available forever.

What is Irys?

Irys is a provenance layer built on Arweave that offers a streamlined developer experience. Irys allows you to pay for your upload with most popular tokens, and also provides a Devnet you can use while building. With Irys’ Devnet, you pay for your upload using free tokens available from faucets (like Solana, ETH Sepoli, or MATIC Mumbai) and uploads are kept for approximately 60 days.

Irys also provides additional guarantees for your upload, we ensure your transaction is finalized on Arweave (even if Arweave forks, your data is still guaranteed to be uploaded) and that it will be seeded to multiple miners.

In addition to improving the developer experience while working on Arweave, Irys also provides a signed receipt for every upload that includes a millisecond-accurate timestamp. This receipt establishes the provenance of the upload and is used by content creators to prove they created the work at a given time.

Using the Irys CLI to upload NFT assets

The easiest way to upload your assets to Arweave using Irys is with the Irys CLI. You can upload either a single or multiple files with a single command. You’ll need first to install a wallet like Metamask or Phantom, fund it, and export your private key.

Install the Irys CLI

Start by installing the Irys CLI globally using the -g flag. Depending on your setup, you may or may not need to use sudo.

npm i -g @irys/sdk

npm i -g @irys/sdk

Uploading images

When uploading entire NFT collections, it’s common practice to upload the entire folder all at once using the Irys CLI command “upload-dir”. All files will be uploaded in a single interaction, and you can reference them using their original names.

If you prefer, you can also upload the images individually using the CLI command “upload”.

Imagine a folder named “MyNFTs” with the following files inside:

nft1.png
nft2.png
nft3.png

To upload the folder, navigate to the “MyNFTs” parent directory and execute the following to upload to our Devnet while replacing the value after -w with the private key of your wallet. The examples below show how to use MATIC to pay for uploads, if you’re using a different token, make sure to change the value of the -t parameter.

irys upload-dir ./MyNFTs \
  -h https://devnet.irys.xyz \
  -t matic \
  -w 601676dd5er…20ff54a120201cb6a \
  --provider-url https://rpc-mumbai.maticvigil.com

Or this version to upload to Iry’s Node 1, which ensures your upload is stored permanently on Arweave:

irys upload-dir ./MyNFTs \
  -h https://node1.irys.xyz \
  -t matic \
  -w 601676dd5er…20ff54a120201cb6a \

Upon successful upload, you’ll get a reply similar to this.

https://gateway.irys.xyz/GA_Z1U8Fe3HlPKCP5zVznD7vZ9rkEtaXISGv5sTYVXo

The permanent URLs for your files can be formed by taking the above value and prepending it to the original file name, as below. Your file names will be similar to the examples below, however, each manifest ID is unique. Note down your unique file names, we’ll use them when creating your metadata.

https://gateway.irys.xyz/GA_Z1U8Fe3HlPKCP5zVznD7vZ9rkEtaXISGv5sTYVXo/nft1.png
https://gateway.irys.xyz/GA_Z1U8Fe3HlPKCP5zVznD7vZ9rkEtaXISGv5sTYVXo/nft2.png
https://gateway.irys.xyz/GA_Z1U8Fe3HlPKCP5zVznD7vZ9rkEtaXISGv5sTYVXo/nft3.png

Creating metadata

Next, you’ll create metadata for each image. A basic metadata example is below, create one for each NFT while replacing the value of the “image” field with the URL generated in the previous step.

{
  "name": "Collection name",
  "description": "Collection description",
  "image": "https://gateway.irys.xyz/GA_Z1U8Fe3HlPKCP5zVznD7vZ9rkEtaXISGv5sTYVXo/nft1.png",
  "external_link": "https://mycollection.co"
}

Finally, upload the metadata using the Irys CLI and then use the URLs to the metadata files when minting your NFTs.

Online demo

Irys also has an interactive online demo, the Provenance Toolkit, which you can use to upload files to our Devnet. Fund a wallet with Mumbai Matic and use our Uploader component, or use our Gassless Uploader component, which does not require a wallet to be installed. All uploads through this demo are kept for approximately 60 days. Irys’ Provenance Toolkit is fully open-source; developers can clone the repository and use the UI components when building their own projects.

For one-click minting of images as compressed NFTs on Solana, you can use our open-source Solana NFT Minter Component.