web3.js

Ethereum JavaScript API

BlockchainWeb3
web3/web3.jsweb3

README

web3.js


web3.js - Ethereum JavaScript API

[![NPM Package Downloads][npm-image-downloads]][npm-url] [![cdnhits][cdnhits-image]][cdnhits-url] [![Discord][discord-image]][discord-url] [![StackExchange][stackexchange-image]][stackexchange-url] [![NPM Package Version][npm-image-version]][npm-url] [![Build Status][actions-image]][actions-url]  [![Coverage Status][coveralls-image]][coveralls-url] [![Lerna][lerna-image]][lerna-url] [![Netlify Status][netlify-image]][netlify-url] [![GitPOAP Badge][gitpoap-image]][gitpoap-url] [![Twitter][twitter-image]][twitter-url]

[Web3.js 4.x][4x-release] has been released. Checkout 4.x [API documentation and migration guide][4xdoc] for testing, early feedback and contributions.

This is the Ethereum [JavaScript API][docs]
which connects to the Generic JSON-RPC spec.

You need to run a local or remote Ethereum node to use this library.

Please read the [documentation][docs] for more.

Installation


You can install the package either using NPM or using Yarn

Using NPM


  1. ``` sh
  2. npm install web3
  3. ```

Yarn


  1. ``` sh
  2. yarn add web3
  3. ```

In the Browser


Use the prebuilt dist/web3.min.js, or
build using the [web3.js][repo] repository:

  1. ``` sh
  2. npm run build
  3. ```

Then include dist/web3.min.js in your html file.
This will expose Web3 on the window object.

Or via jsDelivr CDN:

  1. ``` html
  2. <script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
  3. ```

UNPKG:

  1. ``` html
  2. <script src="https://unpkg.com/web3@latest/dist/web3.min.js"></script>
  3. ```

Usage


  1. ``` js
  2. // In Node.js
  3. const Web3 = require('web3');
  4. const web3 = new Web3('ws://localhost:8546');
  5. console.log(web3);
  6. // Output
  7. {
  8.     eth: ... ,
  9.     shh: ... ,
  10.     utils: ...,
  11.     ...
  12. }
  13. ```

Additionally you can set a provider using web3.setProvider() (e.g. WebsocketProvider):

  1. ``` js
  2. web3.setProvider('ws://localhost:8546');
  3. // or
  4. web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));
  5. ```

There you go, now you can use it:

  1. ``` js
  2. web3.eth.getAccounts().then(console.log);
  3. ```

Usage with TypeScript


We support types within the repo itself. Please open an issue here if you find any wrong types.

You can use web3.js as follows:

  1. ```typescript
  2. import Web3 from 'web3';
  3. import { BlockHeader, Block } from 'web3-eth' // ex. package types
  4. const web3 = new Web3('ws://localhost:8546');
  5. ```

If you are using the types in a commonjs module, like in a Node app, you just have to enable esModuleInterop and allowSyntheticDefaultImports in your tsconfig for typesystem compatibility:

  1. ``` js
  2. "compilerOptions": {
  3.     "allowSyntheticDefaultImports": true,
  4.     "esModuleInterop": true,
  5.     ....
  6. ```

Troubleshooting and known issues.


Web3 and Create-react-app


If you are using create-react-app version >=5 you may run into issues building. This is because NodeJS polyfills are not included in the latest version of create-react-app.

Solution



- Install react-app-rewired and the missing modules

If you are using yarn:
  1. ``` sh
  2. yarn add --dev react-app-rewired process crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer
  3. ```

If you are using npm:
  1. ``` sh
  2. npm install --save-dev react-app-rewired crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process
  3. ```

- Create config-overrides.js in the root of your project folder with the content:

  1. ``` js
  2. const webpack = require('webpack');

  4. module.exports = function override(config) {
  5.     const fallback = config.resolve.fallback || {};
  6.     Object.assign(fallback, {
  7.         "crypto": require.resolve("crypto-browserify"),
  8.         "stream": require.resolve("stream-browserify"),
  9.         "assert": require.resolve("assert"),
  10.         "http": require.resolve("stream-http"),
  11.         "https": require.resolve("https-browserify"),
  12.         "os": require.resolve("os-browserify"),
  13.         "url": require.resolve("url")
  14.     })
  15.     config.resolve.fallback = fallback;
  16.     config.plugins = (config.plugins || []).concat([
  17.         new webpack.ProvidePlugin({
  18.             process: 'process/browser',
  19.             Buffer: ['buffer', 'Buffer']
  20.         })
  21.     ])
  22.     return config;
  23. }
  24. ```

- Within package.json change the scripts field for start, build and test. Instead of react-scripts replace it with react-app-rewired

before:
  1. ```typescript
  2. "scripts": {
  3.     "start": "react-scripts start",
  4.     "build": "react-scripts build",
  5.     "test": "react-scripts test",
  6.     "eject": "react-scripts eject"
  7. },
  8. ```

after:
  1. ```typescript
  2. "scripts": {
  3.     "start": "react-app-rewired start",
  4.     "build": "react-app-rewired build",
  5.     "test": "react-app-rewired test",
  6.     "eject": "react-scripts eject"
  7. },
  8. ```

The missing Nodejs polyfills should be included now and your app should be functional with web3.
- If you want to hide the warnings created by the console:

In config-overrides.js within the override function, add:

  1. ``` js
  2. config.ignoreWarnings = [/Failed to parse source map/];
  3. ```

Web3 and Angular


New solution


If you are using Angular version >11 and run into an issue building, the old solution below will not work. This is because polyfills are not included in the newest version of Angular.

- Install the required dependencies within your angular project:

  1. ``` sh
  2. npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify
  3. ```

- Within tsconfig.json add the following paths in compilerOptions so Webpack can get the correct dependencies

  1. ```typescript
  2. {
  3.     "compilerOptions": {
  4.         "paths" : {
  5.         "crypto": ["./node_modules/crypto-browserify"],
  6.         "stream": ["./node_modules/stream-browserify"],
  7.         "assert": ["./node_modules/assert"],
  8.         "http": ["./node_modules/stream-http"],
  9.         "https": ["./node_modules/https-browserify"],
  10.         "os": ["./node_modules/os-browserify"],
  11.     }
  12. }
  13. ```

- Add the following lines to polyfills.ts file:

  1. ```typescript
  2. import { Buffer } from 'buffer';

  4. (window as any).global = window;
  5. global.Buffer = Buffer;
  6. global.process = {
  7.     env: { DEBUG: undefined },
  8.     version: '',
  9.     nextTick: require('next-tick')
  10. } as any;
  11. ```

Old solution


If you are using Ionic/Angular at a version >5 you may run into a build error in which modules crypto and stream are undefined

a workaround for this is to go into your node-modules and at /angular-cli-files/models/webpack-configs/browser.js change  the node: false to node: {crypto: true, stream: true} as mentioned here

Another variation of this problem was an issue opned on angular-cli

Documentation


Documentation can be found at [ReadTheDocs][docs].

Building


Requirements


-   Node.js
-   npm

  1. ``` sh
  2. sudo apt-get update
  3. sudo apt-get install nodejs
  4. sudo apt-get install npm
  5. ```

Building (webpack)


Build the web3.js package:

  1. ``` sh
  2. npm run build
  3. ```

Testing (mocha)


  1. ``` sh
  2. npm test
  3. ```

Contributing


Please follow the Contribution Guidelines and Review Guidelines.

This project adheres to the Release Guidelines.

Community


-   [Discord][discord-url]
-   [StackExchange][stackexchange-url]

Similar libraries in other languages


-   Haskell: hs-web3
-   Java: web3j
-   PHP: web3.php
-   Purescript: purescript-web3
-   Python: Web3.py
-   Ruby: ethereum.rb
-   Scala: web3j-scala

[repo]: https://github.com/ethereum/web3.js
[docs]: http://web3js.readthedocs.io/
[npm-image-version]: https://img.shields.io/npm/v/web3.svg
[npm-image-downloads]: https://img.shields.io/npm/dm/web3.svg
[npm-url]: https://npmjs.org/package/web3
[actions-image]: https://github.com/ethereum/web3.js/workflows/Build/badge.svg
[actions-url]: https://github.com/ethereum/web3.js/actions
[coveralls-image]: https://coveralls.io/repos/ethereum/web3.js/badge.svg?branch=1.x
[coveralls-url]: https://coveralls.io/r/ethereum/web3.js?branch=1.x
[waffle-image]: https://badge.waffle.io/ethereum/web3.js.svg?label=ready&title=Ready
[waffle-url]: https://waffle.io/ethereum/web3.js
[discord-image]: https://img.shields.io/discord/593655374469660673?label=Discord&logo=discord&style=flat
[discord-url]:  https://discord.gg/pb3U4zE8ca
[twitter-image]: https://img.shields.io/twitter/follow/web3_js?label=web3_js&style=social
[twitter-url]:  https://twitter.com/web3_js
[lerna-image]: https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg
[lerna-url]: https://lerna.js.org/
[netlify-image]: https://api.netlify.com/api/v1/badges/1fc64933-d170-4939-8bdb-508ecd205519/deploy-status
[netlify-url]: https://app.netlify.com/sites/web3-staging/deploys
[stackexchange-image]: https://img.shields.io/badge/web3js-stackexchange-brightgreen
[stackexchange-url]: https://ethereum.stackexchange.com/questions/tagged/web3js
[gitpoap-image]: https://public-api.gitpoap.io/v1/repo/ChainSafe/web3.js/badge
[gitpoap-url]: https://www.gitpoap.io/gh/ChainSafe/web3.js
[4x-release]: https://github.com/ChainSafe/web3.js/releases/tag/v4.0.0-alpha.0
[4xdoc]: https://docs.web3js.org/
[cdnhits-image]: https://data.jsdelivr.com/v1/package/npm/web3/badge
[cdnhits-url]: https://www.jsdelivr.com/package/npm/web3

Semantic versioning


This project follows semver as closely as possiblefrom version 1.3.0 onwards. Earlier minor version bumps might have included breaking behavior changes.