Events Subscription

Subscribing to smart contracts events

import { Web3 } from 'web3';

// set a provider - MUST be a WebSocket(WSS) provider
const web3 = new Web3('wss://ethereum-rpc.publicnode.com');

async function subscribe() {
	// create a new contract object, providing the ABI and address
	const contract = new web3.eth.Contract(abi, address);

	// subscribe to the smart contract event
	const subscription = contract.events.EventName();

	// new value every time the event is emitted
	subscription.on('data', console.log);
}

// function to unsubscribe from a subscription
async function unsubscribe(subscription) {
	await subscription.unsubscribe();
}

subscribe();
unsubscribe(subscription);

Subscribing to node events

A standard Ethereum node like Geth supports subscribing to specific events. Additionally, there are some Ethereum nodes that provide additional custom subscriptions. As you can find in this guide, web3.js enables you to subscribe to the standard events out of the box. And it also provides you with the capability to subscribe to custom subscriptions as you can find in the Custom Subscriptions guide.

:::important If you are the developer who provides custom subscriptions to users. We encourage you to develop a web3.js Plugin after you go through the Custom Subscription section below. You can find how to develop a plugin at web3.js Plugin Developer Guide :::

on("data") - Fires on each incoming log with the log object as argument.

subscription.on('data', data => console.log(data));

on("changed") - Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".

subscription.on('changed', changed => console.log(changed));

on("error") - Fires when an error in the subscription occurs.

subscription.on('error', error => console.log(error));

on("connected") - Fires once after the subscription successfully connected. Returns the subscription id.

subscription.on('connected', connected => console.log(connected));

Logs

logs: implemented in the class LogsSubscription

import { Web3 } from 'web3';

const web3 = new Web3('wss://ethereum-rpc.publicnode.com');

async function subscribe() {
	//create subscription
	const subscription = await web3.eth.subscribe('logs');

	//print logs of the latest mined block
	subscription.on('data', data => console.log(data));
}

// function to unsubscribe from a subscription
async function unsubscribe(subscription) {
	await subscription.unsubscribe();
}

subscribe();
unsubscribe(subscription);

Pending Transactions

newPendingTransactions: implemented in the class NewPendingTransactionsSubscription.
pendingTransactions: same as newPendingTransactions.

import { Web3 } from 'web3';

const web3 = new Web3('wss://ethereum-rpc.publicnode.com');

async function subscribe() {
	//create subscription
	const subscription = await web3.eth.subscribe('pendingTransactions'); //or ("newPendingTransactions")

	//print tx hashs of pending transactions
	subscription.on('data', data => console.log(data));
}

// function to unsubscribe from a subscription
async function unsubscribe(subscription) {
	await subscription.unsubscribe();
}

subscribe();
unsubscribe(subscription);

Block headers

newBlockHeaders: implemented in the class NewHeadsSubscription.
newHeads same as newBlockHeaders.

import { Web3 } from 'web3';

const web3 = new Web3('wss://ethereum-rpc.publicnode.com');

async function subscribe() {
	//create subscription
	const subscription = await web3.eth.subscribe('newBlockHeaders'); //or ("newHeads")

	//print block header everytime a block is mined
	subscription.on('data', data => console.log(data));
}

// function to unsubscribe from a subscription
async function unsubscribe(subscription) {
	await subscription.unsubscribe();
}

subscribe();
unsubscribe(subscription);

Syncing

syncing: implemented in the class SyncingSubscription

import { Web3 } from 'web3';

const web3 = new Web3('wss://ethereum-rpc.publicnode.com');

async function subscribe() {
	//create subscription
	const subscription = await web3.eth.subscribe('syncing');

	//this will return `true` when the node is syncing
	//when it’s finished syncing will return `false`, for the `changed` event.
	subscription.on('data', data => console.log(data));
}

// function to unsubscribe from a subscription
async function unsubscribe(subscription) {
	await subscription.unsubscribe();
}

subscribe();
unsubscribe(subscription);