Using the Web3.js Plugin

This is a web3.js ^4.0.0 plugin for interacting with Chainlink Data Feeds. This plugin allows you to use Data Feeds natively inside web3.js with a single line of code.

Objective

This tutorial shows you how to use a Price Feed in a project that already uses web3.js. The plugin simplifies the process so you don't have to handle all of the details manually.

Before you begin

Install NodeJS
Install Yarn

Steps to implement

Integrate the plugin with your existing project

Use the following steps to integrate the @chainsafe/web3.js-chainlink-plugin with your existing project.

Clone your current project repository or create a new web3.js project.
From your current project directory, install the @chainsafe/web3.js-chainlink-plugin.
```
yarn add @chainsafe/web3.js-chainlink-plugin
```
Install web3version ^4.0.0 or later in your project. To verify you have the correct web3 version installed, look at the versions listed in your project's package.json under the dependencies section for "web3": "4.1.1" or a similar version.
```
yarn add web3@4.1.1
```

Register the plugin with a web3.js instance

After importing ChainlinkPlugin from @chainsafe/web3-plugin-chainlink and Web3 from web3, register an instance of ChainlinkPlugin with an instance of Web3 like the following example:

import { ChainlinkPlugin } from "@chainsafe/web3-plugin-chainlink"
import { Web3 } from "web3"

const web3 = new Web3("YOUR_PROVIDER_URL")
const chainlinkPlugin = new ChainlinkPlugin()

web3.registerPlugin(chainlinkPlugin)

Run the tests

Run yarn to install dependencies. If you receive the following warning, 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.

Run the following tests:

yarn test:unit: Runs the mocked tests that do not make a network request using the Jest framework
End-to-end tests: Runs Webpack bundled tests that make a network request to the RPC provider https://rpc.ankr.com/eth and returns an actual response from MainnetPriceFeeds.LinkEth smart contract using the Cypress 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
Black box tests: Uses a published version of the plugin from Verdaccio to run tests that make a network request to the RPC provider https://rpc.ankr.com/eth and returns an actual response from MainnetPriceFeeds.LinkEth smart contract using the Jest framework
- Note that the black box tests are setup to run within Github actions environment, but can be ran locally. The black_box_test_helpers.sh script can be used to:
  - start: Start Verdaccio using a Docker container
  - stop: Kill the Docker container
  - startBackgroundAndPublish: Starts a headless Docker container and publishes the plugin package
  - runTests: cds into the test/black_box directory, installs the black box package dependencies, and runs yarn test which will use Jest to run the tests
- In addition to the black_box_test_helpers.sh script, the black box tests can be ran using the following package.json scripts:
  - yarn pre-black-box: Calls startBackgroundAndPublish from the black_box_test_helpers.sh script
  - yarn test:black-box: Calls yarn pre-black-box and runTests from the from the black_box_test_helpers.sh script
  - yarn post-black-box: Calls stop from the black_box_test_helpers.sh script

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

Using Price Feed Addresses

Included in this plugin are two enums that contain the Ethereum contract addresses for specific token pairs:

If you cannot find your desired price feed within these enums, check the Price Feed Addresses page to make sure its supported. If it is, open an issue or a pull request for the missing price feed so that it can be added to the appropriate enum.

Add the getPrice function to your code.

async getPrice(
		priceFeedAddress: MainnetPriceFeeds | GoerliPriceFeeds | Address,
		aggregatorInterfaceAbi: ContractAbi = defaultAggregatorInterfaceAbi,
	): {
        roundId: bigint,
        answer: bigint,
        startedAt: bigint,
        updatedAt: bigint,
        answeredInRound: bigint
    }

The defaultAggregatorInterfaceAbi can be found in the GitHub repository.

The getPrice method, accepts MainnetPriceFeeds | GoerliPriceFeeds | Address for its first parameter, and an optional second parameter for specifying the Chainlink Aggregator Interface ABI of the Ethereum smart contract you'd like to interact with (the parameter is defaulted to defaultAggregatorInterfaceAbi).

Under the hood, this method is calling the latestRoundData for the specified price feed. For more information, see the Data Feeds API Reference.

Your complete code should look similar to the following example:

import { ChainlinkPlugin, MainnetPriceFeeds } from "@chainsafe/web3-plugin-chainlink"
import { Web3 } from "web3"

const web3 = new Web3("YOUR_PROVIDER_URL")
const chainlinkPlugin = new ChainlinkPlugin()

web3.registerPlugin(chainlinkPlugin)

web3.chainlink.getPrice(MainnetPriceFeeds.LinkEth).then(console.log)
// {
//     roundId: 73786976294838212867n,
//     answer: 4185000000000000n,
//     startedAt: 1674178043n,
//     updatedAt: 1674178043n,
//     answeredInRound: 73786976294838212867n
// }