web3-providers-ws

What is web3-providers-ws?

The web3-providers-ws package is a WebSocket provider for the web3.js library, which allows for real-time communication with Ethereum nodes. It is used to connect to an Ethereum node over WebSocket, enabling functionalities such as subscribing to events and receiving updates in real-time.

What are web3-providers-ws's main functionalities?

Connecting to an Ethereum Node

This feature allows you to connect to an Ethereum node using a WebSocket provider. The code sample demonstrates how to create a WebSocket provider and use it to get the current block number.

const Web3 = require('web3');
const Web3WsProvider = require('web3-providers-ws');

const wsProvider = new Web3WsProvider('wss://mainnet.infura.io/ws/v3/YOUR_INFURA_PROJECT_ID');
const web3 = new Web3(wsProvider);

web3.eth.getBlockNumber().then(console.log);

Subscribing to New Blocks

This feature allows you to subscribe to new block headers. The code sample demonstrates how to set up a subscription to receive updates whenever a new block is mined.

const Web3 = require('web3');
const Web3WsProvider = require('web3-providers-ws');

const wsProvider = new Web3WsProvider('wss://mainnet.infura.io/ws/v3/YOUR_INFURA_PROJECT_ID');
const web3 = new Web3(wsProvider);

web3.eth.subscribe('newBlockHeaders', (error, blockHeader) => {
  if (!error) {
    console.log(blockHeader);
  }
});

Subscribing to Pending Transactions

This feature allows you to subscribe to pending transactions. The code sample demonstrates how to set up a subscription to receive updates whenever a new transaction is pending.

const Web3 = require('web3');
const Web3WsProvider = require('web3-providers-ws');

const wsProvider = new Web3WsProvider('wss://mainnet.infura.io/ws/v3/YOUR_INFURA_PROJECT_ID');
const web3 = new Web3(wsProvider);

web3.eth.subscribe('pendingTransactions', (error, transactionHash) => {
  if (!error) {
    console.log(transactionHash);
  }
});

Other packages similar to web3-providers-ws

web3-providers-http

The web3-providers-http package is another provider for the web3.js library, but it uses HTTP instead of WebSocket. It is suitable for applications that do not require real-time updates. Compared to web3-providers-ws, it is less efficient for real-time data but simpler to set up and use.

ethers

The ethers package is a complete and compact library for interacting with the Ethereum blockchain. It includes support for WebSocket providers, similar to web3-providers-ws, but also offers a broader range of functionalities such as contract interaction, wallet management, and utilities for encoding/decoding data. It is often considered more modern and user-friendly compared to web3.js.

README

web3-providers-ws

This is a sub-package of web3.js.

This is a websocket provider for web3.js.

Please read the documentation for more.

Installation

Node.js

npm install web3-providers-ws

In the Browser

Build running the following in the web3.js repository:

npm run-script build-all

Then include dist/web3-providers-ws.js in your html file. This will expose the Web3WsProvider object on the window object.

Usage

// in node.js
var Web3WsProvider = require('web3-providers-ws');

var options = {
    timeout: 30000, // ms

    // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
    headers: {
      authorization: 'Basic username:password'
    },

    clientConfig: {
      // Useful if requests are large
      maxReceivedFrameSize: 100000000,   // bytes - default: 1MiB
      maxReceivedMessageSize: 100000000, // bytes - default: 8MiB

      // Useful to keep a connection alive
      keepalive: true,
      keepaliveInterval: 60000 // ms
    },

    // Enable auto reconnection
    reconnect: {
        auto: true,
        delay: 5000, // ms
        maxAttempts: 5,
        onTimeout: false
    }
};

var ws = new Web3WsProvider('ws://localhost:8546', options);

Additional client config options can be found here.

Types

All the TypeScript typings are placed in the types folder.