The peaq network exposes a JSON-RPC interface over WebSockets that allows clients to subscribe to various chain events. In this guide, we focus on the chain_subscribeNewHeads method. It is designed to notify you whenever a new block header is produced on the blockchain. When you call this method, the node returns a subscription ID. Subsequently, as new blocks are finalized or produced, the node pushes notifications to your client containing block header information (such as the parent hash, block number, state root, extrinsics root, and digest logs).

Key points:

  • chain_subscribeNewHeads is a stable and well-supported JSON-RPC method for header subscriptions.
  • Once subscribed, the node sends notifications (commonly using the method "chain_newHead" or sometimes "subscription") that include the block header data.
  • The subscription is maintained over the lifetime of the WebSocket connection. To clean up, you should unsubscribe using chain_unsubscribeNewHeads before closing the connection.

​
Prerequisites

Before proceeding, the following Prerequisites are made:

  1. WebSocket Endpoint:
    • You have access to a peaq node via a WebSocket endpoint. The script expects this endpoint to be available via an environment variable (e.g., PEAQ_WS_URL). If not provided, it falls back to a default endpoint (e.g., wss://peaq.api.onfinality.io/public-ws).
  2. JSON‑RPC Support:
    • The node supports the standard JSON-RPC methods, including chain_subscribeNewHeads and chain_unsubscribeNewHeads. This guide assumes you are using the stable methods (rather than unstable alternatives that may not work reliably).
  3. Raw WebSocket Library (ws):
    • To avoid any interference from additional wrappers (such as those found in some Web3 libraries), the example uses the ws package. This ensures that you receive the exact JSON-RPC messages directly from the node.
  4. Chain Activity:
    • The network is producing new blocks. If no new blocks are produced after you subscribe, you may not see any notifications immediately.

​
Instructions

​
1. Setting Up the Environment

  • Install Dependencies: Ensure you install the necessary Node.js packages:
npm install ws dotenv
  • Set ESM Module: Add the following to your package.json to alllow for ESM modules.
"type": "module",
  • Environment Variables: Create a .env file in your project directory (if not already present) and set the WebSocket endpoint URL:
PEAQ_WS_URL=wss://peaq.api.onfinality.io/public-ws

​
2. Understanding the Subscription Flow

  • Initiating the Connection: The script establishes a direct WebSocket connection to the peaq node. Once connected, it sends a JSON-RPC payload to subscribe to new block headers using the chain_subscribeNewHeads method.

  • Subscription Request: The JSON‑RPC request payload includes:

    • "jsonrpc": "2.0": The protocol version.
    • "method": "chain_subscribeNewHeads": The method to subscribe to block headers.
    • "params": []: No additional parameters are required.
    • "id": 1: A unique identifier for the request.

  • Handling the Response: The node responds with a JSON-RPC message that includes a subscription ID. This ID is saved locally and used to filter incoming notifications.

  • Receiving Notifications: After a successful subscription, the node pushes notifications (using either "chain_newHead" or the generic "subscription" method) that include a params object. The script checks if the incoming message’s subscription field matches the stored subscription ID and then parses out the block header details.

  • Graceful Shutdown: When the client (or user) sends an interrupt (SIGINT, usually via Ctrl+C), the script sends an unsubscribe request using chain_unsubscribeNewHeads with the subscription ID. This cleanly ends the subscription and then closes the WebSocket connection.

​
3. Running the Boilerplate

// chain_subscribeNewHeads.js

import dotenv from 'dotenv';
dotenv.config();

import WebSocket from 'ws';

const WS_URL = process.env.PEAQ_WS_URL || 'wss://peaq.api.onfinality.io/public-ws';
const ws = new WebSocket(WS_URL);

let subscriptionId = null;
const SUBSCRIBE_REQUEST_ID = 1;
const UNSUBSCRIBE_REQUEST_ID = 2;

ws.on('open', () => {
  console.log("WebSocket connected");

  // Send a subscription request using the stable method "chain_subscribeNewHeads"
  const subscribePayload = {
    jsonrpc: "2.0",
    method: "chain_subscribeNewHeads",
    params: [],
    id: SUBSCRIBE_REQUEST_ID,
  };

  console.log("Sending subscription payload:", JSON.stringify(subscribePayload));
  ws.send(JSON.stringify(subscribePayload));
});

ws.on('message', (message) => {
  try {
    const data = JSON.parse(message);
    console.log("Received message:", JSON.stringify(data, null, 2));

    // Handle the subscription response (id: 1)
    if (data.id === SUBSCRIBE_REQUEST_ID && data.result) {
      subscriptionId = data.result;
      console.log("Subscribed to new heads with ID:", subscriptionId);
    }
    // Handle incoming notifications for new block headers
    // Some nodes may return notifications under the method "chain_newHead" or the generic "subscription"
    else if ((data.method === 'chain_newHead' || data.method === 'subscription') &&
             data.params &&
             data.params.subscription === subscriptionId) {
      console.log("New Block Header received:");
      console.log(data.params.result);
    }
  } catch (e) {
    console.error("Error parsing message:", message);
  }
});

ws.on('error', (error) => {
  console.error("WebSocket error:", error);
});

ws.on('close', () => {
  console.log("WebSocket connection closed");
});

// Graceful shutdown: send an unsubscribe request and close the socket
process.on('SIGINT', () => {
  console.log("\nGracefully shutting down...");
  if (subscriptionId) {
    const unsubscribePayload = {
      jsonrpc: "2.0",
      method: "chain_unsubscribeNewHeads",
      params: [subscriptionId],
      id: UNSUBSCRIBE_REQUEST_ID,
    };
    console.log("Sending unsubscribe payload:", JSON.stringify(unsubscribePayload));
    ws.send(JSON.stringify(unsubscribePayload), () => {
      ws.close();
      process.exit();
    });
  } else {
    ws.close();
    process.exit();
  }
});

console.log("Listening for new block headers on the peaq network (chain_subscribeNewHeads) using ws...");
  • Start the Script: Run the script using Node.js:
node chain_subscribeNewHeads.js

  • You should see logs indicating that the WebSocket connection is established and that the subscription request has been sent. If new blocks are produced, you will see the raw notifications logged (including block header details).

  • Interpreting Logs:

    • A log entry like Subscribed to new heads with ID: <subscriptionId> confirms the subscription was successful.
    • When a new block header is received, the script prints the details under the message New Block Header received:.
    • If no notifications are received, double-check that the chain is active and that the node is emitting new block headers.

  • Shutdown: Press Ctrl+C to trigger the graceful shutdown. The script will send an unsubscribe request before closing the connection.

​
Summary

This guide walked you through the process of listening and parsing chain events (block headers) on the peaq network using the chain_subscribeNewHeads JSON-RPC method.

Using this approach, you can reliably monitor new block headers on the peaq network and integrate these events into your blockchain applications or debugging workflows.