subscribe ("newBlockHeaders") | Avalanche

​

Parameters

• string — a keyword identifying the type of event to subscribe to, newBlockHeaders in this case.
• function — (optional) a callback function that will be called every time a new event of the specified type is received. This function takes two parameters: error and result. The error parameter contains any error that occurred while subscribing to the event, and the result parameter contains the data for the event that was received.

​

Response

• object— a block object with the following fields:
  • number — the block number of the requested block, encoded as hexadecimal. null if the block is pending.
  • hash — the block hash of the requested block. null if the block pending.
  • parenthash — hash of the previous block used to generate the current block. Also known as the ‘parent block’.
  • nonce — the hash used to demonstrate proof-of-work. null if the block pending. It returns 0x0000000000000000 when the consensus is proof-of-stake.
  • sha3uncles — the hash of the list of uncles included in the block. It is used to identify the block uniquely and to verify the integrity of the block’s data.
  • logsbloom — the bloom filter for the logs of the block, a data structure that allows for efficient membership testing of elements in a set, in this case, the logs included in the block. null if pending.
  • transactionsroot — the root of the transaction trie of the block. The transactionsRoot field allows Avalanche nodes to verify the integrity of the transactions in a block.
  • stateroot — the root of the final state trie of the block. The stateroot field is included in the block header and is used to verify the integrity of the state at the time the block was processed
  • receiptsroot — the root of the receipts trie of the block. A 32-byte hash of the root node of the receipts trie of all transactions in the block. It is used to verify the integrity of the receipts data for all transactions in the block.
  • miner — the address of the miner receiving the reward.
  • difficulty — a measure of how hard it is to find a valid block for the Avalanche blockchain. It is a number that increases as more miners join the network and more blocks are added to the chain, encoded as hexadecimal.
  • totaldifficulty — the cumulative sum of the difficulty of all blocks that have been mined in the Avalanche network since the inception of the network. It measures the overall security and integrity of the Avalanche network.
  • extradata — extra data included in a block by the miner who mined it. It often includes messages or other information related to the block.
  • size — the size of this block in bytes as an integer value, encoded as hexadecimal.
  • gaslimit — the maximum gas allowed in this block, encoded as hexadecimal.
  • gasused — the total used gas by all transactions in this block, encoded as hexadecimal.
  • timestamp — the Unix timestamp for when the block was collated.
  • transactions — an array of transaction objects. See eth_getTransactionByHash for the exact shape.
  • uncles — an array of uncle hashes.

​

subscribe("newBlockHeaders") code example

• provider.on("block", listener) — activates for each new block header received.
• provider.on("error", listener) — activates if an error is detected during the subscription.
• provider.off("block", listener) — removes the listener and stops the subscription.
• provider.destroy() — closes the WebSocket connection.

const { ethers } = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);

async function subscribeToNewBlocks() {
    try {
        // Subscribe to the 'block' event for new block headers
        provider.on("block", handleNewBlock);

        // React to any provider errors during the subscription
        provider.on("error", handleError);

        console.log("New subscription to block headers");
    } catch (error) {
        console.error(`Error subscribing to new blocks: ${error}`);
    }
}

/* Fallback functions to react to the different events */

// Event listener that fetches and logs the received block header data
async function handleNewBlock(blockNumber) {
    const blockHeader = await provider.getBlock(blockNumber);
    console.log(blockHeader);
}

// Event listener that logs any errors that occur
function handleError(error) {
    console.error(`Error receiving new blocks: ${error}`);
}

subscribeToNewBlocks();

​

Use case

const { ethers } = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);

let blockCount = 0;

async function subscribeToNewBlocks() {
    try {
        // Subscribe to the 'block' event for new block headers
        provider.on("block", handleNewBlock);

        // React to any provider errors during the subscription
        provider.on("error", handleError);

        console.log("New subscription to block headers");
    } catch (error) {
        console.error(`Error subscribing to new blocks: ${error}`);
    }
}

function unsubscribeFromNewBlocks() {
    // Remove the listener and close the WebSocket connection
    provider.off("block", handleNewBlock);
    provider.destroy();
    console.log("Successfully unsubscribed!");
    return process.exit(1);
}

/* Fallback functions to react to the different events */

// Event listener that extracts block number and base fee per gas from the received block header data
async function handleNewBlock(blockNumber) {

    const blockHeader = await provider.getBlock(blockNumber);
    const baseFeePerGas = blockHeader.baseFeePerGas;
    const baseFeeGwei = ethers.formatUnits(baseFeePerGas, "gwei");

    blockCount++;
    console.log(`Block number: ${blockNumber} \n Base Fee per Gas: ${baseFeeGwei} Gwei \n`);
    if (blockCount === 100) {
        unsubscribeFromNewBlocks();
    }
}

// Event listener that logs any errors that occur
function handleError(error) {
    console.error(`Error receiving new blocks: ${error}`);
}

subscribeToNewBlocks();