Primer on IPFS Storage - Leveraging IPFS.

Automating a lot of tasks for working with IPFS is not easy - especially with Metadata, Nested uploads, Batch uploads and more. Hence, that was the reason for creating IpfsStorage, to leverage IPFS completely for storage and retrieval of data with anything from no to less effort.

The IpfsStorage supports uploading Metadata and Images, both in batches and single uploads. It also supports retrieval of Metadata and Images at the same time.

Once of the useful use-cases, where IpfsStorage makes it even more fun to work with is the automatic handling of literally any file type possible. For metadata, It handles nested files and auto-uploads and generates the JSON metadata compatible everywhere.

For an example, the metadata

{
  "name": "Awesome file!",
  "description": "This is an amazing file!",
  "image": fs.readFileSync("./image.jpg"),
}

When uploaded to IPFS using the IPFS Storage, the final metadata that's uploaded is,

{
  "name": "Awesome file!",
  "description": "This is an amazing file!",
  "image": "ipfs://<CID>"
}

And, this is completely handled internally for you.

Getting started with IPFS Storage#

Getting started with IPFS storage is pretty easy. It just requires you to import, and create an object with the IPFS gateway URL to be used for replacing IPFS URIs (ipfs://<CID>) with the gateway URL (<GATEWAY_URL>/<CID>).

Here's the code for getting started:

import { IpfsStorage } from '@0xsaturn/sdk';

const storage = new IpfsStorage('https://ipfs.io/ipfs');

Pretty easy, right?

Uploading files using IpfsStorage#

IpfsStorage supports both batch and single uploads, along with support for both File type in frontend, and Buffer or other types in Node.js runtime.

How to upload a single file using the IPFS storage in Node.js:

import fs from 'fs';

const uri = await storage.upload(fs.readFileSync('./image.jpg'));

console.log(`Uploaded file with URI: ${uri}`);

Here's how to upload a batch of files using the IPFS storage in Node.js:

import fs from 'fs';

const uris = await storage.uploadBatch([
  fs.readFileSync('./images/1.jpg'),
  fs.readFileSync('./images/2.jpg'),
  fs.readFileSync('./images/3.jpg')
]);

console.log(`Uploaded batch with URIs: ${uris}`);

Uploading metadata using IPFS Storage#

Before we get to the code, Let's understand what happens behind the scenes when uploading metadata.

When we pass in a JSON, usually the JSON needs to be in a valid format (In this case, Files should be present as IPFS URIs - ipfs://<CID>).

But, what if the user passes in a File buffer/object directly onto the Metadata? It would break, since it's not valid.

To handle this, 4 steps are performed behind the scenes:

• Filter out all the string objects (Assuming they are IPFS URIs).
• Recursively iterate over the JSON/JavaScript object and store the files to be uploaded in an array.
• Upload all the files collected.
• Recursively iterate over the JSON/JavaScript object and replace the files with the IPFS URIs.

Let's now upload the Metadata for a NFT using the IPFS storage!

import fs from 'fs';

const metadata = {
  name: 'Awesome NFT',
  description: 'IPFS Storage is awesome!',
  image: fs.readFileSync('./image.jpg')
};

const uri = await storage.uploadMetadata(metadata);

console.log(`Uploaded metadata with URI: ${uri}`);

And, also a batch of Metadata, for the same!

import fs from 'fs';

const metadatas = [
  {
    name: 'Awesome NFT',
    description: 'IPFS Storage is awesome!',
    image: fs.readFileSync('./images/1.jpg')
  },
  {
    name: 'Awesome NFT #2',
    description: 'My epic NFT',
    image: fs.readFileSync('./images/2.jpg')
  }
];

const uris = await storage.uploadMetadataBatch(metadatas);

console.log(`Uploaded metadata with URIs: ${uris}`);

Retrieving data using IPFS Storage#

It's just as easy to retrieve data, as it is to upload it.

Just pass in the URI to get function, then stringify and parse the data using JSON.

const rawData = await storage.get('ipfs://<CID>');

const data = JSON.parse(JSON.stringify(rawData));

console.log(`Retrieved data: ${data}`);

And, it gives you the uploaded data back ✨.