web3-core-subscriptions

What is web3-core-subscriptions?

The web3-core-subscriptions package is part of the Web3.js library, which is used to interact with the Ethereum blockchain. This specific package provides functionality for subscribing to various events and data streams from the Ethereum network, such as new blocks, pending transactions, and logs.

What are web3-core-subscriptions's main functionalities?

Subscribe to New Blocks

This feature allows you to subscribe to new block headers on the Ethereum blockchain. The provided code sample demonstrates how to set up a subscription to new block headers using Web3.js and how to handle the incoming data.

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

const subscription = web3.eth.subscribe('newBlockHeaders', (error, result) => {
  if (!error) {
    console.log(result);
    return;
  }
  console.error(error);
});

// To unsubscribe
subscription.unsubscribe((error, success) => {
  if (success) {
    console.log('Successfully unsubscribed!');
  }
});

Subscribe to Pending Transactions

This feature allows you to subscribe to pending transactions on the Ethereum network. The code sample shows how to set up a subscription to pending transactions and handle the incoming transaction hashes.

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

const subscription = web3.eth.subscribe('pendingTransactions', (error, result) => {
  if (!error) {
    console.log(result);
    return;
  }
  console.error(error);
});

// To unsubscribe
subscription.unsubscribe((error, success) => {
  if (success) {
    console.log('Successfully unsubscribed!');
  }
});

Subscribe to Logs

This feature allows you to subscribe to logs (events) from smart contracts on the Ethereum blockchain. The code sample demonstrates how to set up a subscription to logs with specific options such as contract address and topics.

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

const options = {
  address: '0x123456...', // Address of the contract
  topics: ['0x123456...'] // Topics to subscribe to
};

const subscription = web3.eth.subscribe('logs', options, (error, result) => {
  if (!error) {
    console.log(result);
    return;
  }
  console.error(error);
});

// To unsubscribe
subscription.unsubscribe((error, success) => {
  if (success) {
    console.log('Successfully unsubscribed!');
  }
});

Other packages similar to web3-core-subscriptions

ethers

The ethers.js library is a complete and compact library for interacting with the Ethereum blockchain and its ecosystem. It provides similar subscription functionalities through its Provider API, allowing users to listen for new blocks, pending transactions, and logs. Compared to web3-core-subscriptions, ethers.js is known for its smaller size and ease of use.

ethjs

Ethjs is a highly modular and lightweight library for interacting with the Ethereum blockchain. It offers similar subscription capabilities through its EthFilter API, allowing users to subscribe to new blocks, pending transactions, and logs. Ethjs is designed to be minimalistic and efficient, making it a good alternative to web3-core-subscriptions for developers looking for a more lightweight solution.

web3-providers-ws

The web3-providers-ws package is another part of the Web3.js library that specifically deals with WebSocket providers. It can be used in conjunction with web3-core-subscriptions to set up WebSocket connections and manage subscriptions. While it does not provide subscription functionalities on its own, it is an essential component for enabling WebSocket-based subscriptions in Web3.js.

README

web3-core-subscriptions

This is a sub package of web3.js

The subscriptions package used within some web3.js packages. Please read the documentation for more.

Installation

Node.js

npm install web3-core-subscriptions

In the Browser

Build running the following in the web3.js repository:

npm run-script build-all

Then include dist/web3-core-subscriptions.js in your html file. This will expose the Web3Subscriptions object on the window object.

Usage

// in node.js
var Web3Subscriptions = require('web3-core-subscriptions');

var sub = new Web3Subscriptions({
    name: 'subscribe',
    type: 'eth',
    subscriptions: {
        'newBlockHeaders': {
            subscriptionName: 'newHeads',
            params: 0,
            outputFormatter: formatters.outputBlockFormatter
        },
        'pendingTransactions': {
            params: 0
        }
    }
});
sub.attachToObject(myCoolLib);

myCoolLib.subscribe('newBlockHeaders', function(){ ... });