npm package: @pioneer-platform/nodes
Description: Single source of truth for blockchain node configurations across the Pioneer ecosystem.
Latest version: 8.30.3

# @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

```bash
pnpm add @pioneer-platform/nodes
```

## Usage

### Static Import (Compile-Time)

```typescript
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:**

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

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

### TypeScript Types

```typescript
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

```typescript
{
  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):
```typescript
const configPath = path.join(__dirname, '../blockbook_nodes.json');
const chainConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
```

**After** (package-based loading):
```typescript
import { getBlockbookConfigs } from '@pioneer-platform/nodes/runtime';

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

## Node Validation

Validate node health and connectivity:

```bash
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

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

## License

See project root for license information.