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
Installation
yarn add web3-ipfs-storage-plugin
Using this plugin
4.x
of web3
Installing Version 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 useweb3
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
- Clone the repo
- Run
yarn
to install dependencies- If you receive the following warning, please remove the file
package-lock.json
and make sure to runyarn
to install dependencies instead ofnpm i
:
- If you receive the following warning, please remove the file
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.
- 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 fromRegistry 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
-
- End-to-end tests: Runs Webpack bundled tests that make a network request to the RPC provider
Useful links
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 |