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

• :gear: NodeJS (LTS/Fermium)
• :toolbox: 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 [email protected]
• yarn add [email protected]

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

• :writing_hand: 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 |