@pioneer-platform/nodes

Single source of truth for blockchain node configurations across the Pioneer ecosystem.

Overview

This package provides centralized node configurations for:

• ✅ 17+ Blockbook node configurations (UTXO & EVM chains)
• ✅ 1,200+ validated Web3 RPC nodes (70+ EVM networks)
• ✅ Unchained API configurations (9 networks)
• ✅ Runtime config loading with API key injection
• ✅ TypeScript type definitions
• ✅ Node validation tooling

Installation

pnpm add @pioneer-platform/nodes

Usage

Static Import (Compile-Time)

import { getBlockbooks } from '@pioneer-platform/nodes';

const configs = getBlockbooks();
// Returns array of blockbook node configs

Runtime Import (Dynamic Loading)

Use this for services that need runtime API key injection:

import { getBlockbookConfigs } from '@pioneer-platform/nodes/runtime';

const configs = getBlockbookConfigs({
  apiKey: process.env.NOW_NODES_API,
  injectApiKeys: true  // Replaces {API_KEY} placeholder
});

TypeScript Types

import type { BlockbookNodeConfig, NodeType } from '@pioneer-platform/nodes';

function processNode(config: BlockbookNodeConfig) {
  console.log(`${config.symbol} (${config.networkId})`);
  console.log(`Service: ${config.service}`);
  console.log(`WebSocket: ${config.websocket}`);
}

Node Configuration Format

Blockbook Nodes

{
  symbol: "BTC",                      // Chain ticker
  blockchain: "bitcoin",              // Full blockchain name
  networkId: "bip122:...",           // CAIP-2 network identifier
  caip: "bip122:.../slip44:0",       // CAIP-19 asset identifier
  type: "blockbook",                  // Node type
  service: "https://.../{ API_KEY}",   // REST API endpoint
  websocket: "wss://.../{ API_KEY}",   // WebSocket URL
  expectedBlockTime: 600              // Block time (seconds)
}

Supported Chains

UTXO Chains (12): BTC, LTC, DOGE, BCH, DASH, ZEC, DGB, GRS, DCR, BTG, KMD, BASE

EVM Chains (5): ETH, BSC, MATIC, AVAX, ARB

Additional chains available via web3.ts (70+ EVM networks)

Migration Guide

For Pioneer Watchtower

Before (file-based JSON loading):

const configPath = path.join(__dirname, '../blockbook_nodes.json');
const chainConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

After (package-based loading):

import { getBlockbookConfigs } from '@pioneer-platform/nodes/runtime';

const chainConfig = {
  blockbooks: getBlockbookConfigs({
    apiKey: NOW_NODES_API,
    injectApiKeys: true
  })
};

Node Validation

Validate node health and connectivity:

pnpm run validate-nodes           # Default: 5s timeout, 20 parallel
pnpm run validate-nodes:verbose   # With detailed logs
pnpm run validate-nodes:fast      # 3s timeout, 30 parallel

Contributing

To add a new node:

1. Add config to src/seeds.ts (blockbooks array)
2. Follow existing format with CAIP-2 networkId
3. Include websocket URL if available
4. Add expectedBlockTime for timeout calculations
5. Build: pnpm run build
6. Test: pnpm test
7. Validate: pnpm run validate-nodes

WebSocket URL Patterns

UTXO chains: Include /websocket suffix

wss://btc.nownodes.io/wss/{API_KEY}/websocket

EVM -blockbook endpoints: Include /websocket suffix

wss://eth-blockbook.nownodes.io/wss/{API_KEY}/websocket

EVM specific endpoints (AVAX, ARB): NO /websocket suffix

wss://avax-blockbook.nownodes.io/wss/{API_KEY}

Architecture

@pioneer-platform/nodes
├── src/
│   ├── index.ts        - Main exports
│   ├── runtime.ts      - Runtime config loading with API key injection
│   ├── types.ts        - TypeScript type definitions
│   ├── seeds.ts        - Blockbook & Unchained node configs
│   ├── web3.ts         - Web3/EVM RPC nodes (auto-generated)
│   └── validate-nodes.ts - Node validation tooling
└── lib/                - Compiled JavaScript output

Package Exports

{
  ".": "./lib/index.js",
  "./runtime": "./lib/runtime.js"
}

License

See project root for license information.