Blurt Nodes Checker

A sophisticated, 0-dependency, and Isomorphic utility to monitor, score, and rank RPC nodes on the Blurt Blockchain. Designed for production performance on Node.js and Modern Frontend Frameworks (React, Angular, Vue, Vite).

Features

• Dependency Zero: Entirely powered by standard APIs (fetch, AbortController). Zero bloating.
• Isomorphic Support: Runs natively in Node.js >= 18 and all modern browsers. Fully Tree-Shakable.
• Micro-Subject Architecture: Safely drop rxjs and Node EventEmitter without breaking the .subscribe() api flow.
• Two-Phase Consensus Detection: Calculates Median Head Block across the cluster and validates block_ids backward in time to guarantee extremely robust fork detection with minimized false positives.
• Dynamic Scoring Matrix: Ranks nodes (0-100 score) using historic latency averages, network fault degradations, success reliability, and stale-block penalties.

Installation

npm install @beblurt/blurt-nodes-checker

Getting Started

import { BlurtNodesChecker, createDefaultTests } from "@beblurt/blurt-nodes-checker";

const rpcList = [
  'https://rpc.blurt.blog',
  'https://blurt-rpc.saboin.com',
  'https://rpc.beblurt.com',
  'https://blurtrpc.dagobert.uk',
  'https://rpc.drakernoise.com'
];

// 1. Initialize Checker
const checker = new BlurtNodesChecker(rpcList, {
  interval: 15,          // Check every 15 seconds
  timeout: 4000,         // Wait max 4 seconds before aborting calls
  maxRetries: 2,         // Exponential backoff network retries
  retryDelay: 500,       // Time between retries (ms)
  staleThreshold: 50,    // Node is "stale" if lagging 50 blocks behind consensus median
  tests: createDefaultTests("beblurt") // Inject dynamic queries
});

// 2. Subscribe to matrix updates
checker.message.subscribe((nodes) => {
  console.log("Cluster Top Node:", nodes[0].url, "Score:", nodes[0].score);
  
  nodes.forEach(node => {
    switch(node.status) {
      case "online":
        console.log(`✅ ${node.url} - Perfectly healthy (${node.score}/100)`);
        break;
      case "stale":
        console.log(`⚠️ ${node.url} - Syncing slowly (${node.lag} blocks behind).`);
        break;
      case "forked":
        console.log(`🚨 ${node.url} - Network Forked / Mismatched Block Identity!`);
        break;
      case "degraded":
        console.log(`🧰 ${node.url} - Missing Critical Plugins!`);
        break;
      case "error":
        console.log(`❌ ${node.url} - Unreachable!`);
        break;
    }
  });
});

// 3. Begin monitoring
checker.start();

Returned Node Properties

The checker.message.subscribe() emits an array of node objects perfectly structured for frontend or load balancer architectures. Each node object contains:

• url: The RPC endpoint URL string.
• status: String union (online | unknown | degraded | error | stale | forked | outdated).
• score: Number (0-100) combining latency, reliability, version and test suite performances.
• block_number & block_id: The current blockchain parameters of the node.
• version & chain_id: The running component version strings.
• lag: Number of blocks this node is currently lagging behind the Median Cluster Consensus.
• latency_avg: Exponentially smoothed average physical latency in ms.
• reliability: Historical percentage (0-100) of correctly handled sub-tests.
• test_result: Array of custom objects mapping exactly what individual RPC sub-tests succeeded or failed.
• error: Populated globally if the node was completely unable to connect, resolving cross-chain discrepancies, or timing out.

Interactive Browser Dashboard

To view the absolute power of this tool without any Node.js backend dependencies, an incredibly detailed Glassmorphic dashboard is bundled!

Navigate to examples/browser/index.html within this repo (and serve it via any basic HTTP tool like npx serve .) to experience a live, flickering-free analytical dashboard dynamically coloring lag limits and modal validations directly over the Web.

👉 View the Live Demo on GitLab Pages

Terminal CLI Dashboard (Node.js)

For server-side and PM2/System Administrator users, there is a beautifully styled, zero-dependency ANSI Terminal Monitor script! Run the following in your terminal to spawn an ASCII-colored real-time tracking matrix measuring network latency, forks, and drops directly in standard output:

node examples/node/index.js

The 0-100 Scoring Math

Our clustering matrix is scored on a normalized 0-100 spectrum allowing standard load balancers to automatically select the absolute healthiest node in real-time.

| Category | Description | Base Impact | | -------- | ----------- | ----------- | | Health | Basic Ok/Error response ratio | 40 points | Tests | Weight-scaled test completions | 30 points | Latency| Averaged responsiveness | 30 points | Lag | Mild penalty for lagging blocks | - (0.5 * blocks lagged) | | Degraded| Node fails a critical: true test | - 30 points | | Stale | Node has lag beyond staleThreshold | - 50 points | | Forked | Node is confirmed on a false timeline | Score Plummets to 0 |

Injecting Custom Checks

Instead of standard queries, pass custom JSON-RPC instructions straight to the constructor! Nodes will evaluate tests and reward points based on matching validations and weights.

const checker = new BlurtNodesChecker(myRpcList, {
  tests: [
    {
      name: "Get Global Properties",
      method: "condenser_api.get_dynamic_global_properties",
      params: [],
      weight: 10,
      critical: true, // If this fails, the node status changes to DEGRADED
      validator: (result) => result && result.head_block_number !== undefined
    }
  ]
})

Contributing

Pull requests for new features, bug fixes, and suggestions are welcome!

Author

@beblurt (https://beblurt.com/@beblurt)

License

Copyright (C) 2022 IMT ASE Co., LTD

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.