@pioneer-platform/nodes 8.30.1 → 8.30.3

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
 
-> @pioneer-platform/nodes@8.30.1 build /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/modules/pioneer/pioneer-nodes
+> @pioneer-platform/nodes@8.30.3 build /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/modules/pioneer/pioneer-nodes
 > tsc -p .
 

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @pioneer-platform/nodes
 
+## 8.30.3
+
+### Patch Changes
+
+- chore: chore: - Services (discovery-service, watchtower)
+- Updated dependencies
+  - @pioneer-platform/pioneer-caip@9.19.3
+
+## 8.30.2
+
+### Patch Changes
+
+- fa09397: chore: - Services (discovery-service, watchtower)
+- Updated dependencies [fa09397]
+  - @pioneer-platform/pioneer-caip@9.19.2
+
 ## 8.30.1
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,170 @@
+# @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.

package/lib/index.d.ts

@@ -1,3 +1,6 @@
+export { getBlockbookConfigs, RuntimeOptions } from './runtime';
+export type { BaseNodeConfig, BlockbookNodeConfig, ApiOnlyNodeConfig, UnchainedNodeConfig, Web3NodeConfig, AnyNodeConfig } from './types';
+export { NodeType } from './types';
 export declare const init: (type: string, config: any, isTestnet: boolean) => Promise<boolean>;
 export declare const getWeb3Nodes: () => {
     networkId: string;
@@ -26,22 +29,6 @@ export declare const getBlockbooks: () => ({
     type: string;
     service: string;
     websocket?: undefined;
-} | {
-    symbol: string;
-    blockchain: string;
-    caip: string;
-    type: string;
-    service: string;
-    websocket: string;
-    networkId?: undefined;
-} | {
-    symbol: string;
-    blockchain: string;
-    caip: string;
-    type: string;
-    service: string;
-    networkId?: undefined;
-    websocket?: undefined;
 })[];
 export declare const getUnchaineds: () => {
     networkId: any;

package/lib/index.js

@@ -51,13 +51,18 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
     }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getUnchaineds = exports.getBlockbooks = exports.getNode = exports.getNodes = exports.getWeb3Nodes = exports.init = void 0;
+exports.getUnchaineds = exports.getBlockbooks = exports.getNode = exports.getNodes = exports.getWeb3Nodes = exports.init = exports.NodeType = exports.getBlockbookConfigs = void 0;
 var TAG = " | Pioneer Nodes | ";
 var log = require('@pioneer-platform/loggerdog')();
 var _a = require("@pioneer-platform/pioneer-caip"), shortListNameToCaip = _a.shortListNameToCaip, shortListSymbolToCaip = _a.shortListSymbolToCaip, evmCaips = _a.evmCaips;
 var seeds_1 = require("./seeds");
 var web3_1 = require("./web3");
 var NODES = web3_1.web3Seeds;
+// Export runtime config functions
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "getBlockbookConfigs", { enumerable: true, get: function () { return runtime_1.getBlockbookConfigs; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "NodeType", { enumerable: true, get: function () { return types_1.NodeType; } });
 var init = function (type, config, isTestnet) {
     return init_nodes(type, config, isTestnet);
 };

package/lib/runtime.d.ts

@@ -0,0 +1,44 @@
+export interface RuntimeOptions {
+    apiKey?: string;
+    injectApiKeys?: boolean;
+}
+/**
+ * Get blockbook node configurations with optional runtime API key injection.
+ *
+ * This function replaces file-based JSON loading patterns and allows services
+ * to load configs directly from the @pioneer-platform/nodes package with
+ * dynamic API key injection at runtime.
+ *
+ * @param options - Configuration options
+ * @param options.apiKey - API key to inject (replaces {API_KEY} placeholder)
+ * @param options.injectApiKeys - Whether to perform API key injection
+ * @returns Array of blockbook node configurations
+ *
+ * @example
+ * // Load configs without API key injection
+ * const configs = getBlockbookConfigs();
+ *
+ * @example
+ * // Load configs with API key injection
+ * const configs = getBlockbookConfigs({
+ *   apiKey: process.env.NOW_NODES_API,
+ *   injectApiKeys: true
+ * });
+ */
+export declare function getBlockbookConfigs(options?: RuntimeOptions): ({
+    symbol: string;
+    blockchain: string;
+    caip: string;
+    networkId: string;
+    type: string;
+    service: string;
+    websocket: string;
+} | {
+    symbol: string;
+    blockchain: string;
+    caip: string;
+    networkId: string;
+    type: string;
+    service: string;
+    websocket?: undefined;
+})[];

package/lib/runtime.js

@@ -0,0 +1,66 @@
+"use strict";
+/*
+    Runtime Config Loader
+
+    Provides runtime API for dynamic blockchain node configuration loading.
+    Used by services like watchtower to replace file-based JSON loading.
+*/
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBlockbookConfigs = getBlockbookConfigs;
+var seeds_1 = require("./seeds");
+/**
+ * Get blockbook node configurations with optional runtime API key injection.
+ *
+ * This function replaces file-based JSON loading patterns and allows services
+ * to load configs directly from the @pioneer-platform/nodes package with
+ * dynamic API key injection at runtime.
+ *
+ * @param options - Configuration options
+ * @param options.apiKey - API key to inject (replaces {API_KEY} placeholder)
+ * @param options.injectApiKeys - Whether to perform API key injection
+ * @returns Array of blockbook node configurations
+ *
+ * @example
+ * // Load configs without API key injection
+ * const configs = getBlockbookConfigs();
+ *
+ * @example
+ * // Load configs with API key injection
+ * const configs = getBlockbookConfigs({
+ *   apiKey: process.env.NOW_NODES_API,
+ *   injectApiKeys: true
+ * });
+ */
+function getBlockbookConfigs(options) {
+    if (options === void 0) { options = {}; }
+    // Clone configs to avoid mutating the source
+    var configs = __spreadArray([], seeds_1.blockbooks, true);
+    // Inject API keys if requested
+    if (options.injectApiKeys && options.apiKey) {
+        configs = configs.map(function (config) {
+            var _a;
+            return (__assign(__assign({}, config), { service: config.service.replace('{API_KEY}', options.apiKey), websocket: (_a = config.websocket) === null || _a === void 0 ? void 0 : _a.replace('{API_KEY}', options.apiKey) }));
+        });
+    }
+    return configs;
+}

package/lib/seeds.d.ts

@@ -49,22 +49,6 @@ export declare const blockbooks: ({
     type: string;
     service: string;
     websocket?: undefined;
-} | {
-    symbol: string;
-    blockchain: string;
-    caip: string;
-    type: string;
-    service: string;
-    websocket: string;
-    networkId?: undefined;
-} | {
-    symbol: string;
-    blockchain: string;
-    caip: string;
-    type: string;
-    service: string;
-    networkId?: undefined;
-    websocket?: undefined;
 })[];
 interface NodeEntry {
     key: string;

package/lib/seeds.js

@@ -119,24 +119,27 @@ exports.blockbooks = [
         symbol: "DOGE",
         blockchain: "dogecoin",
         caip: "bip122:00000000001a91e3dace36e2be3bf030/slip44:3",
+        networkId: "bip122:00000000001a91e3dace36e2be3bf030",
         type: "blockbook",
-        service: "https://dogebook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6",
+        service: "https://dogebook.nownodes.io/{API_KEY}",
         websocket: "wss://doge.nownodes.io/wss/{API_KEY}/websocket"
     },
     {
         symbol: "LTC",
         blockchain: "litecoin",
         caip: "bip122:12a765e31ffd4059bada1e25190f6e98/slip44:2",
+        networkId: "bip122:12a765e31ffd4059bada1e25190f6e98",
         type: "blockbook",
-        service: "https://ltcbook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6",
+        service: "https://ltcbook.nownodes.io/{API_KEY}",
         websocket: "wss://ltc.nownodes.io/wss/{API_KEY}/websocket"
     },
     {
         symbol: "BCH",
         blockchain: "bitcoincash",
         caip: "bip122:000000000000000000651ef99cb9fcbe/slip44:145",
+        networkId: "bip122:000000000000000000651ef99cb9fcbe",
         type: "blockbook",
-        service: "https://bchbook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6",
+        service: "https://bchbook.nownodes.io/{API_KEY}",
         websocket: "wss://bch.nownodes.io/wss/{API_KEY}/websocket"
     },
     // ============================================================================
@@ -163,8 +166,9 @@ exports.blockbooks = [
         symbol: "GRS",
         blockchain: "Groestlcoin",
         caip: "bip122:00000ac5927c594d49cc0bdb81759d0d/slip44:17",
+        networkId: "bip122:00000ac5927c594d49cc0bdb81759d0d",
         type: "blockbook",
-        service: "https://grsbook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6"
+        service: "https://grsbook.nownodes.io/{API_KEY}"
     },
     {
         symbol: "DCR",
@@ -172,28 +176,31 @@ exports.blockbooks = [
         caip: "bip122:00000ac5927c594d49cc0bdb81759d0d/slip44:42",
         networkId: "bip122:00000ac5927c594d49cc0bdb81759d0d",
         type: "blockbook",
-        service: "https://dcr-blockbook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6"
+        service: "https://dcr-blockbook.nownodes.io/{API_KEY}"
     },
     {
         symbol: "BTG",
         blockchain: "bitcoin gold",
         caip: "bip122:00069578d7a76f82b2c7117c1334c7ef/slip44:1",
+        networkId: "bip122:00069578d7a76f82b2c7117c1334c7ef",
         type: "blockbook",
-        service: "https://btg.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6"
+        service: "https://btg.nownodes.io/{API_KEY}"
     },
     {
         symbol: "KMD",
         blockchain: "Komodo",
         caip: "bip122:027e3758c3a65b12aa1046462b486d0a/slip44:1",
+        networkId: "bip122:027e3758c3a65b12aa1046462b486d0a",
         type: "blockbook",
-        service: "https://kmdbook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6"
+        service: "https://kmdbook.nownodes.io/{API_KEY}"
     },
     {
         symbol: "ZEC",
         blockchain: "zcash",
         caip: "bip122:00040fe8ec8471911baa1db1266ea15d/slip44:133",
+        networkId: "bip122:00040fe8ec8471911baa1db1266ea15d",
         type: "blockbook",
-        service: "https://zecbook.nownodes.io/cf522543-87e2-4dd6-b645-2fbfd0bc61f6"
+        service: "https://zecbook.nownodes.io/{API_KEY}"
     },
     // ============================================================================
     // EVM CHAINS - NowNodes Blockbook
@@ -207,6 +214,42 @@ exports.blockbooks = [
         service: "https://eth-blockbook.nownodes.io/{API_KEY}",
         websocket: "wss://eth-blockbook.nownodes.io/wss/{API_KEY}/websocket"
     },
+    {
+        symbol: "BSC",
+        blockchain: "binancesmartchain",
+        caip: "eip155:56/slip44:60",
+        networkId: "eip155:56",
+        type: "blockbook",
+        service: "https://bsc-blockbook.nownodes.io/{API_KEY}",
+        websocket: "wss://bsc-blockbook.nownodes.io/wss/{API_KEY}/websocket"
+    },
+    {
+        symbol: "MATIC",
+        blockchain: "polygon",
+        caip: "eip155:137/slip44:60",
+        networkId: "eip155:137",
+        type: "blockbook",
+        service: "https://maticbook.nownodes.io/{API_KEY}",
+        websocket: "wss://maticbook.nownodes.io/wss/{API_KEY}/websocket"
+    },
+    {
+        symbol: "AVAX",
+        blockchain: "avalanche",
+        caip: "eip155:43114/slip44:60",
+        networkId: "eip155:43114",
+        type: "blockbook",
+        service: "https://avax-blockbook.nownodes.io/{API_KEY}",
+        websocket: "wss://avax-blockbook.nownodes.io/wss/{API_KEY}"
+    },
+    {
+        symbol: "ARB",
+        blockchain: "arbitrum",
+        caip: "eip155:42161/slip44:60",
+        networkId: "eip155:42161",
+        type: "blockbook",
+        service: "https://arb-blockbook.nownodes.io/{API_KEY}",
+        websocket: "wss://arb-blockbook.nownodes.io/wss/{API_KEY}"
+    },
     // ============================================================================
     // ZELCORE NODES REMOVED - All returning HTTP 403 Forbidden
     // ============================================================================

package/lib/types.d.ts

@@ -0,0 +1,66 @@
+export declare enum NodeType {
+    BLOCKBOOK = "blockbook",
+    API_ONLY = "api-only",
+    UNCHAINED = "unchained",
+    WEB3 = "web3"
+}
+/**
+ * Base configuration shared by all node types
+ */
+export interface BaseNodeConfig {
+    symbol: string;
+    blockchain: string;
+    networkId: string;
+    type: string | NodeType;
+}
+/**
+ * Blockbook node configuration for UTXO and EVM chains
+ *
+ * Blockbook nodes provide REST APIs and WebSocket connections
+ * for blockchain data and transaction monitoring.
+ */
+export interface BlockbookNodeConfig extends BaseNodeConfig {
+    type: 'blockbook' | NodeType.BLOCKBOOK;
+    service: string;
+    websocket?: string;
+    expectedBlockTime?: number;
+    caip?: string;
+}
+/**
+ * API-only node configuration for chains without blockbook support
+ *
+ * Used for chains that only need basic metadata without
+ * full REST or WebSocket endpoints.
+ */
+export interface ApiOnlyNodeConfig extends BaseNodeConfig {
+    type: 'api-only' | NodeType.API_ONLY;
+    expectedBlockTime?: number;
+}
+/**
+ * Unchained API node configuration
+ *
+ * ShapeShift's Unchained APIs provide standardized blockchain access.
+ */
+export interface UnchainedNodeConfig extends BaseNodeConfig {
+    type: 'unchained' | NodeType.UNCHAINED;
+    networkId: string;
+    caip: string;
+    swagger?: string;
+    service?: string;
+    wss?: string;
+}
+/**
+ * Web3 RPC node configuration
+ *
+ * Used for EVM chains with standard Web3/Ethereum RPC interfaces.
+ */
+export interface Web3NodeConfig extends BaseNodeConfig {
+    type: 'web3' | NodeType.WEB3;
+    url: string;
+    networkId: string;
+    chainId?: number;
+}
+/**
+ * Union type for all node configurations
+ */
+export type AnyNodeConfig = BlockbookNodeConfig | ApiOnlyNodeConfig | UnchainedNodeConfig | Web3NodeConfig;

package/lib/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/*
+    Pioneer Nodes Type Definitions
+
+    TypeScript interfaces for blockchain node configurations.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeType = void 0;
+var NodeType;
+(function (NodeType) {
+    NodeType["BLOCKBOOK"] = "blockbook";
+    NodeType["API_ONLY"] = "api-only";
+    NodeType["UNCHAINED"] = "unchained";
+    NodeType["WEB3"] = "web3";
+})(NodeType || (exports.NodeType = NodeType = {}));

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@pioneer-platform/nodes",
-  "version": "8.30.1",
+  "version": "8.30.3",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    },
+    "./runtime": {
+      "require": "./lib/runtime.js",
+      "types": "./lib/runtime.d.ts"
+    }
+  },
   "dependencies": {
     "dotenv": "^8.2.0",
     "ethers": "5.7.2",
     "@pioneer-platform/loggerdog": "8.11.0",
-    "@pioneer-platform/pioneer-caip": "9.19.1"
+    "@pioneer-platform/pioneer-caip": "9.19.3"
   },
   "devDependencies": {
     "@types/jest": "^25.2.3",
@@ -25,6 +35,7 @@
     "npm": "pnpm i",
     "npm-update": "pnpm update",
     "test": "pnpm run build && node __tests__/test-module.js",
+    "test:runtime": "pnpm run build && node __tests__/runtime.test.js",
     "test-cli-export": "pnpm run build && node __tests__/reference-test-cli-export.js",
     "lint": "prettier --write '**/**/*.ts'",
     "start": "nodemon --watch 'src/**/*.ts' --exec ts-node __tests__node",