Massa Node Crawler

Overview

This repository contains a node script designed to crawl the Massa blockchain network and count the number of running nodes. The Massa blockchain is a decentralized and community-driven blockchain that relies on a network of nodes to operate effectively. This crawler helps in providing insights into the network's health by counting the number of active nodes.

Installation

Before you begin, ensure that you have Node.js and npm installed on your machine. You can download them from https://nodejs.org/.

1. Clone the Repository:

   git clone https://github.com/peterjah/massa-crawler

2. Navigate to the Project Directory:

   cd massa-crawler

3. Install Dependencies:

   npm install

Usage

To run the Massa blockchain node crawler, follow these steps:

1. Run the Crawler:

   Execute the following command to start the crawler:

   npm run start

   This will initiate the crawler, and it will begin counting the number of running nodes on the Massa blockchain network.

2. View Results:

   Once the crawler completes its operation, the results will be displayed in the console.

   Number of known nodeIds in the network: 276
   Number of routables nodes: 125
   Number of unreachable: 151
   Versions: { 'MAIN.5.0': 125 }
   
   Probing bootstrap port 31245 on 161 addresses...
   Bootstrap candidates (one per nodeId): 122
   Wrote 122 bootstrap candidates to nodes.json

   The crawler also writes nodes.json, holding one candidate bootstrap peer per nodeId. Addresses are normalized (IPv4-mapped IPv6 collapsed to IPv4, non-routable addresses dropped) and de-duplicated, preferring IPv4 so the list works on hosts without IPv6:

   {
     "crawledAt": "2026-08-25T09:12:33.000Z",
     "bootstrap": [
       {
         "nodeId": "N12WHcnumb2A7dtgZVbLJXeYTearE2dg7oJP4jjywwCmrC5Bm94",
         "ip": "141.94.218.103",
         "version": "MAIN.5.0"
       }
     ]
   }

   Note: a peer lands in bootstrap when its bootstrap port (31245) accepts a TCP connection. That proves the port is bound, not that the node will serve you — enable_bootstrap_server, bootstrap_whitelist and the per-node connection limit are only visible through a real bootstrap handshake. Treat the file as a candidate list.

Configuration

All settings are optional environment variables:

Variable	Default	Description
MASSA_ENDPOINT	https://mainnet.massa.net/api/v2	Entry point the crawl starts from
API_TIMEOUT	2000	Per-node JSON-RPC timeout, in ms
PROBE_TIMEOUT	3000	Bootstrap port connect timeout, in ms
PROBE_CONCURRENCY	100	Parallel bootstrap port probes
OUTPUT_FILE	nodes.json	Where results are written

Contributing

If you would like to contribute to this project, feel free to open issues, create pull requests, or suggest improvements. Your feedback and contributions are highly appreciated.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.