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 websocket provider sub-package for web3.js.

Please read the documentation for more.

Installation

Node.js

npm install web3-providers-ws

Usage

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

const 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
    }
};

const 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.

Changelog

[1.2.10]

Added

• Add support for EIP-1193 provider request method (#3625)

Changed

• Upgrade minified bundle build process (from gulp to webpack) (#3618)
• CI improvements: add dependency caching, netlify browser test preview (#3598, #3602)
• Remove references to genesis block in 1.x documentation (#3594)
• Disallow setting toBlock when subscribing to contract events (#3207)

Fixed

• Extend _txInputFormatter with hex prefix check (#3317)
• Extract revert reason string for geth >= 1.9.15 (#3520)
• Fix Incorrect param encoding of BN object in arrayed inputs (#3592)
• Remove mis-encoded whitespace characters from web3-utils files (#3601)
• Fix incompatibilities with webpack Buffer polyfill for wallet.encrypt/decrypt (#3580)
• Fix misformatted fromBlock value when re-subscribing to events over WS (#3596)
• Support Function type log parameter decoding (#2826)
• Add undefined callback check to websocket provider response queue (#3574)
• Fix WS clientConfig type (#3563)