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.
• Sliding Window Elasticity: Score reliability evaluates a real-time sliding memory window (e.g. last 60 checks) instead of absolute history, dynamically forgiving repaired nodes over time.
• 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
  historySize: 60,       // Size of the sliding memory window for reliability calculations
  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 "experimental":
        console.log(`🧪 ${node.url} - Healthy but running an Alpha/Beta build.`);
        break;
      case "throttled":
        console.log(`⏳ ${node.url} - HTTP 429 Rate Limit Exceeded.`);
        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 | experimental | unknown | degraded | error | stale | forked | outdated | throttled).
• 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.

Detecting Node Capabilities (e.g., Nexus API)

Since v2 no longer pollutes the Node object with arbitrary boolean flags (like node.nexus), you can safely verify if a server supports a specific API module by looking at its test_result:

// Get all tests related to the Nexus module
const nexusTests = node.test_result?.filter(t => t.name.startsWith("Nexus | ")) || [];

// Verify that the module was actually tested AND that 100% of its sub-tests passed
const isNexusSupported = nexusTests.length > 0 && nexusTests.every(t => t.success);

Allowing users to opt-in to Experimental Nodes (Frontend Example)

By default, bleeding edge nodes (alpha/beta) are tagged natively as experimental. If these nodes fail critical queries, they still correctly fallback to degraded or error just like online nodes do. This means you can easily create an opt-in toggle in your UI (React/Angular) for power-users wanting to test the latest features:

// Example: A dynamic getter in your Frontend Service
export const getActiveNodes = (allowExperimental: boolean = false): string[] => {
  const allowedStatuses = ["online"];
  
  if (allowExperimental) {
    allowedStatuses.push("experimental"); // Include Alpha/Beta safely
  }

  // Filter checker nodes against allowed statuses and return URLs
  return myChecker.nodes
    .filter(node => allowedStatuses.includes(node.status))
    .sort((a, b) => b.score - a.score)
    .map(node => node.url);
}

Full vs Light Testing (Customizing Tests)

In v1, you passed flags like { full: true, nexus: true } to the constructor. In v2, you have absolute programmatic control over what gets tested. Simply filter the array returned by createDefaultTests() before injecting it.

Additionally, createDefaultTests() accepts an account name and a permlink string as arguments to run the tests directly against your own specific content!

// Create the suite testing a specific account and post (Optional)
let myTests = createDefaultTests("beblurt", "your-custom-post-permlink");

// Example: Remove thick/heavy Condenser queries for a "Light" test run
if (!wantsFullTest) {
  myTests = myTests.filter(t => !t.name.startsWith("Condenser | "));
}

// Example: Remove ALL Nexus queries entirely if you don't use them
if (!wantsNexusTest) {
  myTests = myTests.filter(t => !t.name.startsWith("Nexus | "));
}

const checker = new BlurtNodesChecker(endpoints, {
  interval: 300,
  tests: myTests // Inject your perfectly curated suite
});

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/.