Web3.js IPFS Storage Plugin

This is a web3.js 4.x plugin for storing files in IPFS and storing the CID in the Ethereum Network.

Prerequisites

• ⚙️ NodeJS (LTS/Fermium)
• 🧰 Yarn

Installation

yarn add web3-ipfs-storage-plugin

Using this plugin

Installing Version 4.x of web3

When adding the web3 package to your project, make sure to use version 4.x:

• npm i -S web3@4.0.3
• yarn add web3@4.0.3

NOTE
If 4.x was already released, you are good to just use web3 without appending anything to it.

To verify you have the correct web3 version installed, after adding the package to your project (the above commands), look at the versions listed in your project's package.json under the dependencies section, it should contain version 4.x similar to:

"dependencies": {
	"web3": "4.0.3"
}

Registering the Plugin with a web3.js Instance

After importing IPFSStoragePlugin from web3-ipfs-storage-plugin and Web3 from web3, register an instance of IPFSStoragePlugin with an instance of Web3 like so:

import { IPFSStoragePlugin } from 'web3-ipfs-storage-plugin';
import { Web3 } from 'web3';

const web3 = new Web3('YOUR_PROVIDER_URL');
const IPFSStoragePlugin = new IPFSStoragePlugin();

web3.registerPlugin(IPFSStoragePlugin);

More information about registering web3.js plugins can be found here.

Plugin Methods

uploadLocalFileToIPFS

  public async uploadLocalFileToIPFS(
    localFilePath: string,
  ): Promise<TransactionReceipt>

The uploadLocalFileToIPFS method in IPFSStoragePlugin Uploads a file from the local file system to IPFS, and stores the returned CID in a smart contract registry. @param localFilePath - The file URL object pointing to the local file to upload. @returns A TransactionReceipt object that contains details of the transaction used to store the CID in the registry.

Under the hood, this method is calling the store for the specified registry contract, more information about it can be found here.

import { IPFSStoragePlugin } from 'web3-ipfs-storage-plugin';
import { Web3 } from 'web3';

const web3 = new Web3('YOUR_PROVIDER_URL');
const IPFSStoragePlugin = new IPFSStoragePlugin();

web3.registerPlugin(IPFSStoragePlugin);

web3.IPFSStoragePlugin.uploadLocalFileToIPFS(file)

listCIDsForAddress

  public async listCIDsForAddress(
    ethereumAddress: string,
    startBlock: number,
  ): Promise<void>

The listCIDsForAddress method in IPFSStoragePlugin Retrieves a console log with a list of CIDs in(Content Identifiers) stored by a specific Ethereum address from a smart contract registry.

Under the hood, It filters the CIDStored events emitted by the contract for the given address and starting from the specified block number up to the latest block.

import { IPFSStoragePlugin } from 'web3-ipfs-storage-plugin';
import { Web3 } from 'web3';

const web3 = new Web3('YOUR_PROVIDER_URL');
const IPFSStoragePlugin = new IPFSStoragePlugin();

web3.registerPlugin(IPFSStoragePlugin);

web3.IPFSStoragePlugin.listCIDsForAddress(signerAddress, startBlock)

Found an issue or have a question or suggestion

• ✍️ If you found an issue or have a question or suggestion submit an issue or join us on Discord

Run the tests

1. Clone the repo
2. Run yarn to install dependencies
   • If you receive the following warning, please remove the file package-lock.json and make sure to run yarn to install dependencies instead of npm i:

warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.

3. Run the tests:
   • End-to-end tests: Runs Webpack bundled tests that make a network request to the RPC provider https://endpoints.omniatech.io/v1/eth/sepolia/public and returns an actual response from Registry Contract smart contract using the Jest framework
     • yarn test:e2e:chrome: Runs the tests using Chrome
     • yarn test:e2e:electron: Runs the tests using Electron
     • yarn test:e2e:firefox: Runs the tests using Firefox

Useful links

• web3.js Documentation

Package.json Scripts

Script	Description
build	Uses tsc to build package and dependent packages
build:web	Uses webpack to build a browser ready build of the plugin in dist directory
clean	Uses rimraf to remove lib/ and dist/
format	Uses prettier to format the code
lint	Uses eslint to lint package
lint:fix	Uses eslint to check and fix any warnings
prebuild	Calls yarn clean
prepare	Installs husky
test:e2e:chrome	Users cypress to run e2e test in a Chrome environment
test:e2e:firefox	Users cypress to run e2e test in a Firefox environment
test:e2e:electron	Users cypress to run e2e test in a Electron environment