Skip to main content

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.
 subcription.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".
 subcription.on("changed", (changed) => console.log(changed));
  • on("error") - Fires when an error in the subscription occurs.
 subcription.on("error", (error) => console.log(error));
  • on("connected") - Fires once after the subscription successfully connected. Returns the subscription id.
 subcription.on("connected", (connected) => console.log(connected));

Logs​

import { Web3 } from "web3";

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

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

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

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

subscribe();
unsubscribe(subscription);

Pending Transactions​

import { Web3 } from "web3";

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

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

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

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

subscribe();
unsubscribe(subscription);

Block headers​

import { Web3 } from "web3";

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

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

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

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

subscribe();
unsubscribe(subscription);

Syncing​

import { Web3 } from "web3";

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

async function subscribe() {
  //create subcription
  const subcription = 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.
  subcription.on("data", (data) => console.log(data));
}

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

subscribe();
unsubscribe(subscription);