Skip to content

Commit 8c4d854

Browse files
spacesailor24spacesailor24
authored
Merge pull request #16 from ChainSafe/wyatt/update-readme
Update `README.md`
2 parents b688d4a + cbcd765 commit 8c4d854

File tree

2 files changed

+89
-39
lines changed

2 files changed

+89
-39
lines changed

‎README.md

Lines changed: 87 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -4,48 +4,81 @@
44
![Node Version](https://img.shields.io/badge/node-14.x-green)
55
[![NPM Package][npm-image]][npm-url]
66

7-
This is a Chainlink plugin implementation for version `4.x` of [web3.js](https://github.com/web3/web3.js).
7+
This is a [web3.js](https://github.com/web3/web3.js) `4.x` plugin for interacting with Chainlink Ethereum contracts.
88

99
## Prerequisites
1010

1111
- :gear: [NodeJS](https://nodejs.org/) (LTS/Fermium)
12-
- :toolbox: [Yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/package/npm)
12+
- :toolbox: [Yarn](https://yarnpkg.com/)
1313

1414
## Installation
1515

16-
You can install the package either using [npm](https://www.npmjs.com/package/web3) or using [Yarn](https://yarnpkg.com/package/web3)
16+
```bash
17+
yarn add @chainsafe/web3.js-chainlink-plugin
18+
```
1719

18-
### Using npm
20+
## Using this plugin
1921

20-
```bash
21-
npm install @chainsafe/web3.js-chainlink-plugin
22+
### Registering the Plugin with a web3.js Instance
23+
24+
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:
25+
26+
```typescript
27+
import { ChainlinkPlugin } from '@chainsafe/web3.js-chainlink-plugin';
28+
import Web3 from 'web3';
29+
30+
const web3 = new Web3('YOUR_PROVIDER_URL');
31+
const chainlinkPlugin = new ChainlinkPlugin();
32+
33+
web3.registerPlugin(chainlinkPlugin);
2234
```
2335

24-
### Using Yarn
36+
More information about registering web3.js plugins can be found [here](https://docs.web3js.org/docs/guides/web3_plugin_guide/plugin_users#registering-the-plugin).
2537

26-
```bash
27-
yarn add @chainsafe/web3.js-chainlink-plugin
38+
### Plugin Methods
39+
40+
#### Price Feed Addresses
41+
42+
Included in this plugin are two enums that contain the Ethereum contract addresses for specific token pairs: [MainnetPriceFeeds](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/b688d4aede593e4faf2668e565caf4882c88abc9/src/types.ts#L11) and [GoerliPriceFeeds](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/b688d4aede593e4faf2668e565caf4882c88abc9/src/types.ts#L250). If you cannot find your desired price feed within these enums, please check [here](https://docs.chain.link/docs/data-feeds/price-feeds/addresses) 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.
43+
44+
#### `getPrice`
45+
46+
```typescript
47+
async getPrice(
48+
priceFeedAddress: MainnetPriceFeeds | GoerliPriceFeeds | Address,
49+
aggregatorInterfaceAbi: ContractAbi = defaultAggregatorInterfaceAbi,
50+
): {
51+
roundId: bigint,
52+
answer: bigint,
53+
startedAt: bigint,
54+
updatedAt: bigint,
55+
answeredInRound: bigint
56+
}
2857
```
2958

30-
## Using this plugin
59+
`defaultAggregatorInterfaceAbi` can be found [here](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/src/aggregator_v3_interface_abi.ts).
3160

32-
You can use this plugin to get the price of token-pairs from a Chainlink smart contract.
61+
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](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/src/aggregator_v3_interface_abi.ts)).
3362

34-
Following is a code snippet for getting the Price of the pair `Link/Eth` from the Ethereum mainnet.
35-
However, if you are connected to another Ethereum network other than the mainnet, or you would like to get the price of another pair, replace `MainnetPriceFeeds.LinkEth`, in the code below, with the address of the intended Chainlink smart contract that is deployed on the network that you are connected to, and you may check https://docs.chain.link/docs/data-feeds/price-feeds/addresses/ for the most updated mainnet and testnet addresses.
63+
Under the hood, this method is calling the `latestRoundData` for the specified price feed, more information about it can be found [here](https://docs.chain.link/data-feeds/price-feeds/api-reference#latestrounddata).
3664

3765
```typescript
3866
import { ChainlinkPlugin, MainnetPriceFeeds } from '@chainsafe/web3.js-chainlink-plugin';
39-
4067
import Web3 from 'web3';
4168

42-
const web3 = new Web3('YOUR_ETHEREUM_NODE'); // Use a node connected to mainnet, if you will keep using `MainnetPriceFeeds.LinkEth` below.
43-
69+
const web3 = new Web3('YOUR_PROVIDER_URL');
4470
const chainlinkPlugin = new ChainlinkPlugin();
4571

4672
web3.registerPlugin(chainlinkPlugin);
4773

4874
web3.chainlink.getPrice(MainnetPriceFeeds.LinkEth).then(console.log);
75+
// {
76+
// roundId: 73786976294838212867n,
77+
// answer: 4185000000000000n,
78+
// startedAt: 1674178043n,
79+
// updatedAt: 1674178043n,
80+
// answeredInRound: 73786976294838212867n
81+
// }
4982
```
5083

5184
## Found an issue or have a question or suggestion
@@ -55,32 +88,51 @@ web3.chainlink.getPrice(MainnetPriceFeeds.LinkEth).then(console.log);
5588

5689
## Run the tests
5790

58-
You may like to run the tests and examine their code to see how to use the plugin. And this would be also useful if you are a plugin writer.
59-
60-
First clone the repo locally. And then:
61-
62-
- Run `yarn` or `npm i`
63-
- Installs dependencies and builds the plugin
64-
- Run `yarn test` or `npm test`
65-
- Runs the [unit test](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/test/unit/plugin.test.ts) that instantiates an instance of `Web3`, configures it with a provider, then registers the [ChainlinkPlugin](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/src/index.ts) on the `Web3` instance
66-
- `ChainlinkPlugin` takes an `AggregatorV3InterfaceABI` as the first argument, and the deployed contract address as the second
91+
1. Clone the repo
92+
2. Run `yarn` to install dependencies
93+
3. Run the tests:
94+
- `yarn test:unit`: Runs the mocked tests that do not make a network request using the [Jest](https://jestjs.io/) framework
95+
- 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](https://www.cypress.io/) framework
96+
- `yarn test:e2e:chrome`: Runs the tests using Chrome
97+
- `yarn test:e2e:electron`: Runs the tests using Electron
98+
- `yarn test:e2e:firefox`: Runs the tests using Firefox
99+
- Black box tests: Uses a published version of the plugin from [Verdaccio](https://verdaccio.org/) 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](https://jestjs.io/) framework
100+
- NOTE The black box tests are setup to run within Github actions environment, but can be ran locally. The [black_box_test_helpers.sh](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/scripts/black_box_test_helpers.sh) script can be used to:
101+
- `start`: Start Verdaccio using a Docker container
102+
- `stop`: Kill the Docker container
103+
- `startBackgroundAndPublish`: Starts a headless Docker container and publishes the plugin package
104+
- `runTests`: `cd`s into the `test/black_box` directory, installs the black box package dependencies, and runs `yarn test` which will use Jest to run the tests
105+
- In addition to the `black_box_test_helpers.sh` script, the black box tests can be ran using the following `package.json` scripts:
106+
1. `yarn pre-black-box`: Calls `startBackgroundAndPublish` from the `black_box_test_helpers.sh` script
107+
2. `yarn test:black-box`: Calls `yarn pre-black-box` and `runTests` from the from the `black_box_test_helpers.sh` script
108+
3. `yarn post-black-box`: Calls `stop` from the `black_box_test_helpers.sh` script
67109

68110
## Useful links
69111

70112
- [web3.js Documentation](https://docs.web3js.org/)
71-
- [Chainlink Documentation](https://docs.chain.link/docs) especially gettnig the price from the latest round: [latestRoundData](https://docs.chain.link/docs/data-feeds/price-feeds/api-reference/#latestrounddata)
113+
- [Chainlink Documentation](https://docs.chain.link/docs)
72114

73115
## Package.json Scripts
74116

75-
| Script | Description |
76-
| --------- | -------------------------------------------------- |
77-
| build | Uses `tsc` to build package and dependent packages |
78-
| clean | Uses `rimraf` to remove `dist/` |
79-
| format | Uses `prettier` to format the code |
80-
| lint | Uses `eslint` to lint package |
81-
| lint:fix | Uses `eslint` to check and fix any warnings |
82-
| test | Uses `jest` to run unit tests |
83-
| test:unit | Uses `jest` to run tests under `/test/unit` |
117+
| Script | Description |
118+
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
119+
| build | Uses `tsc` to build package and dependent packages |
120+
| build:web | Uses `webpack` to build a browser ready build of the plugin in `dist` directory |
121+
| clean | Uses `rimraf` to remove `lib/` and `dist/` |
122+
| format | Uses `prettier` to format the code |
123+
| lint | Uses `eslint` to lint package |
124+
| lint:fix | Uses `eslint` to check and fix any warnings |
125+
| post-black-box | Uses `stop` from `black_box_test_helpers.sh` to kill running Verdaccio Docker container |
126+
| pre-black-box | Uses `startBackgroundAndPublish` from `black_box_test_helpers.sh` to start a Verdaccio Docker container and publish the plugin package to it |
127+
| prebuild | Calls `yarn clean` |
128+
| prepare | Installs [husky](https://github.com/typicode/husky) |
129+
| test | Uses `jest` to run unit tests |
130+
| test:black-box | Calls `yarn pre-black-box` and `runTests` from `black_box_test_helpers.sh` to run black box tests |
131+
| test:coverage | Uses `jest` to report test coverage |
132+
| test:e2e:chrome | Users `cypress` to run `e2e` test in a Chrome environment |
133+
| test:e2e:firefox | Users `cypress` to run `e2e` test in a Firefox environment |
134+
| test:e2e:electron | Users `cypress` to run `e2e` test in a Electron environment |
135+
| test:unit | Uses `jest` to run tests under `/test/unit` |
84136

85137
[npm-image]: https://img.shields.io/npm/v/web3-core-method.svg
86138
[npm-url]: https://npmjs.org/packages/web3

‎package.json

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,17 @@
1515
],
1616
"scripts": {
1717
"build": "tsc --build",
18-
"build:check": "node -e \"require('./lib')\"",
1918
"build:web": "npx webpack",
20-
"clean": "rimraf lib",
19+
"clean": "rimraf lib && rimraf dist",
2120
"format": "prettier --write '**/*'",
2221
"lint": "eslint --ext .js,.ts .",
2322
"lint:fix": "eslint --fix --ext .js,.ts .",
2423
"post-black-box": "./scripts/black_box_test_helpers.sh stop",
2524
"pre-black-box": "./scripts/black_box_test_helpers.sh startBackgroundAndPublish",
26-
"prebuild": "rimraf lib",
25+
"prebuild": "yarn clean",
2726
"prepare": "husky install",
2827
"test": "jest --config=./test/unit/jest.config.js",
2928
"test:black-box": "yarn pre-black-box && ./scripts/black_box_test_helpers.sh runTests",
30-
"test:ci": "jest --coverage=true --coverage-reporters=json --verbose",
3129
"test:coverage": "jest --config=./test/unit/jest.config.js --coverage=true --coverage-reporters=text",
3230
"test:e2e:chrome": "npx cypress run --headless --browser chrome",
3331
"test:e2e:firefox": "npx cypress run --headless --browser firefox",

0 commit comments

Comments
 (0)