@chainsafe/web3.js-chainlink-plugin v0.1.0-alpha.0

Web3.js Chainlink Plugin

This is a web3.js 4.x plugin for interacting with Chainlink Ethereum contracts.

Prerequisites

• :gear: NodeJS (LTS/Fermium)
• :toolbox: Yarn

Installation

yarn add @chainsafe/web3.js-chainlink-plugin

Using this plugin

Registering the Plugin with a web3.js Instance

After importing ChainlinkPlugin from @chainsafe/web3.js-chainlink-plugin and Web3 from web3, register an instance of ChainlinkPlugin with an instance of Web3 like so:

import { ChainlinkPlugin } from '@chainsafe/web3.js-chainlink-plugin';
import Web3 from 'web3';

const web3 = new Web3('YOUR_PROVIDER_URL');
const chainlinkPlugin = new ChainlinkPlugin();

web3.registerPlugin(chainlinkPlugin);

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

Plugin Methods

Price Feed Addresses

Included in this plugin are two enums that contain the Ethereum contract addresses for specific token pairs: MainnetPriceFeeds and GoerliPriceFeeds. If you cannot find your desired price feed within these enums, please check here to make sure it's supported, and if it is, please open an issue or a pull request for the missing price feed so that it can be added to the appropriate enum.

getPrice

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

defaultAggregatorInterfaceAbi can be found here.

The getPrice method, accepts MainnetPriceFeeds | GoerliPriceFeeds | Address for it's 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, more information about it can be found here.

import { ChainlinkPlugin, MainnetPriceFeeds } from '@chainsafe/web3.js-chainlink-plugin';
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
// }

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
3. Run the 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 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:
       1. yarn pre-black-box: Calls startBackgroundAndPublish from the black_box_test_helpers.sh script
       2. yarn test:black-box: Calls yarn pre-black-box and runTests from the from the black_box_test_helpers.sh script
       3. yarn post-black-box: Calls stop from the black_box_test_helpers.sh script

Useful links

• web3.js Documentation
• Chainlink Documentation

Package.json Scripts