@openscan/network-connectors

TypeScript library providing unified, type-safe RPC client interfaces for multiple blockchain networks with configurable request execution strategies.

Features

Multi-Network Support: Unified API for 10+ blockchain networks including EVM chains (Ethereum, Optimism, Arbitrum, Polygon, BNB, Base, Avalanche, Aztec), Bitcoin, Zcash and Solana
Bitcoin Support: Full Bitcoin Core v28+ RPC support with ~115 methods using CAIP-2/BIP122 chain identifiers
Zcash Support: Full Zebra (zebrad) RPC support with ~40 methods, including the shielded pool and address-index RPCs
Strategy Pattern: Pluggable request execution strategies (Fallback for reliability, Parallel for consistency detection, Race for minimum latency)
Type Safety: Strong TypeScript typing with network-specific type definitions
Dual Transport: HTTP and WebSocket support with automatic transport detection from URL scheme
WebSocket Features: Persistent connections, request multiplexing, auto-reconnect with exponential backoff
Zero Dependencies: Pure Node.js implementation with no external runtime dependencies
ES Modules: Native ESM support for modern JavaScript environments
Factory Pattern: Type-safe client instantiation based on chain IDs (numeric for EVM, CAIP-2 for Bitcoin)
Inconsistency Detection: Parallel strategy detects RPC provider data divergence, comparing responses in full rather than only their top-level fields
Resource Lifecycle: close() method for clean shutdown of WebSocket connections

Installation

npm install @openscan/network-connectors

Supported Networks

EVM Networks

Network	Chain ID	Client Class	Special Features
Ethereum	1	`EthereumClient`	Full eth_, web3_, net_, debug_, trace_, txpool_
Optimism	10	`OptimismClient`	Ethereum + optimism_, opp2p_, admin_* methods
BNB Smart Chain	56	`BNBClient`	Extended Ethereum methods + BSC-specific features
BNB Testnet	97	`BNBClient`	Factory maps to `BNBClient`; `BNBTestnetClient` also exported for direct use
Polygon	137	`PolygonClient`	Ethereum + Polygon Bor validator methods
Base	8453	`BaseClient`	Optimism-compatible (reuses Optimism types)
Arbitrum One	42161	`ArbitrumClient`	Ethereum + arbtrace_* (Arbitrum traces)
Avalanche C-Chain	43114	`AvalancheClient`	Ethereum + avax cross-chain, admin, extended debug
Aztec	677868	`AztecClient`	Custom node_/nodeAdmin_ methods (non-EVM)
Hardhat	31337	`HardhatClient`	Ethereum + hardhat_/evm_ state manipulation methods
Sepolia Testnet	11155111	`SepoliaClient`	Ethereum-compatible testnet

Bitcoin Networks

Bitcoin uses CAIP-2/BIP122 chain identifiers instead of numeric chain IDs.

Network	Chain ID (CAIP-2)	Client Class	Special Features
Bitcoin Mainnet	`bip122:000000000019d6689c085ae165831e93`	`BitcoinClient`	Full Bitcoin Core v28+ RPC (~115 methods)
Bitcoin Testnet3	`bip122:000000000933ea01ad0ee984209779ba`	`BitcoinClient`	Bitcoin testnet3 network
Bitcoin Testnet4	`bip122:00000000da84f2bafbbc53dee25a72ae`	`BitcoinClient`	Bitcoin testnet4 (BIP94)
Bitcoin Signet	`bip122:00000008819873e925422c1ff0f99f7c`	`BitcoinClient`	Bitcoin signet (BIP325)

Bitcoin Chain ID Constants

For convenience, use the exported constants instead of raw chain ID strings:

import {
  BITCOIN_MAINNET,
  BITCOIN_TESTNET3,
  BITCOIN_TESTNET4,
  BITCOIN_SIGNET
} from "@openscan/network-connectors";

// BITCOIN_MAINNET = "bip122:000000000019d6689c085ae165831e93"

Bitcoin Method Categories (~115 methods)

Category	Methods	Description
Blockchain	~15	`getBlockchainInfo`, `getBlock`, `getBlockHash`, `getBlockHeader`, `getBlockStats`, `getChainTips`, `getDifficulty`, etc.
Mempool	~10	`getMempoolInfo`, `getRawMempool`, `getMempoolEntry`, `testMempoolAccept`, `submitPackage`, etc.
Raw Transactions	~7	`getRawTransaction`, `decodeRawTransaction`, `decodeScript`, `sendRawTransaction`, `createRawTransaction`, etc.
PSBT	~8	`createPsbt`, `decodePsbt`, `analyzePsbt`, `combinePsbt`, `finalizePsbt`, `joinPsbts`, etc.
Network	~13	`getNetworkInfo`, `getPeerInfo`, `getConnectionCount`, `getNetTotals`, `ping`, `addNode`, etc.
Fee Estimation	~1	`estimateSmartFee` with economical/conservative modes
Utility	~7	`validateAddress`, `getDescriptorInfo`, `deriveAddresses`, `createMultisig`, `verifyMessage`, etc.
Mining	~9	`getMiningInfo`, `getNetworkHashPs`, `getBlockTemplate`, `submitBlock`, `generateToAddress`, etc.
Wallet	~35	`getWalletInfo`, `getBalances`, `listWallets`, `sendToAddress`, `listUnspent`, `importDescriptors`, etc.
Control	~6	`getMemoryInfo`, `getRpcInfo`, `help`, `uptime`, `logging`, `stop`

Zcash Networks

Zcash is a Bitcoin fork, so it shares the bip122: CAIP-2 namespace with Bitcoin. Chain IDs are still unique — the reference is the first 32 hex characters of each chain's genesis block hash — and the factory routes on registry membership rather than the namespace prefix.

Network	Chain ID (CAIP-2)	Client Class	Special Features
Zcash Mainnet	`bip122:00040fe8ec8471911baa1db1266ea15d`	`ZcashClient`	Full Zebra RPC (~40 methods) incl. shielded pools
Zcash Testnet	`bip122:05a60a92d99d85997cce3b87616c089f`	`ZcashClient`	Zcash testnet

Node implementation: zcashd reached its automatic end-of-support halt on 2026-07-18 and no longer runs. ZcashClient therefore models the RPC surface of Zebra (zebrad), the current Zcash node. Wallet RPCs (z_sendmany, z_getbalance, …) live in the separate Zallet daemon and are not covered here.

Transport: Zebra's RPC server is HTTP-only, so Zcash has no WebSocket transport or subscription support.

Zcash Chain ID Constants

import { ZCASH_MAINNET, ZCASH_TESTNET } from "@openscan/network-connectors";

// ZCASH_MAINNET = "bip122:00040fe8ec8471911baa1db1266ea15d"

Zcash Method Categories (~40 methods)

Category	Methods	Description
Chain & Blocks	8	`getBlockchainInfo`, `getBlockCount`, `getBestBlockHash`, `getBestBlockHeightAndHash`, `getBlockHash`, `getBlock`, `getBlockHeader`, `getDifficulty`
Transactions	3	`getRawTransaction`, `sendRawTransaction`, `getTxOut`
Mempool	2	`getMempoolInfo`, `getRawMempool`
Address Index	3	`getAddressBalance`, `getAddressTxIds`, `getAddressUtxos`
Shielded	4	`zGetTreestate`, `zGetSubtreesByIndex`, `zValidateAddress`, `zListUnifiedReceivers`
Mining	9	`getBlockTemplate`, `submitBlock`, `getMiningInfo`, `getNetworkSolPs`, `getBlockSubsidy`, `getStandardFee`, `generate`, `generateToAddress`, `getNetworkHashPs`
Node & Network	8	`getInfo`, `getDeprecationInfo`, `getNetworkInfo`, `getPeerInfo`, `ping`, `addNode`, `stop`, `validateAddress`
Chain Manipulation	2	`invalidateBlock`, `reconsiderBlock`

Note some parameter conventions differ from Bitcoin: getBlock, getBlockHeader and zGetTreestate take a block hash or a height as a decimal string (getBlock("3444000", 1)); getRawTransaction takes a numeric verbosity (0 or 1) rather than a boolean; and the address-index methods take a single object argument (getAddressBalance({ addresses: ["t1..."] })).

Because Zebra's RPC server is HTTP-only, ZcashClient rejects ws:///wss:// endpoints at construction rather than letting them hang until the transport times out.

Authenticated RPC Endpoints

Endpoints that require an API key header can be configured as objects instead of plain URL strings. Headers are scoped per endpoint, so a credential is never sent to the other providers in the same list:

const client = ClientFactory.createClient(ZCASH_MAINNET, {
  type: "fallback",
  rpcUrls: [
    { url: "https://zcash-mainnet.gateway.tatum.io", headers: { "x-api-key": process.env.TATUM_API_KEY! } },
    "https://zcash-mainnet-zebrad.gateway.tatum.io", // plain strings still work
  ],
});

Headers apply to HTTP transports only. Supplying them for a ws:///wss:// endpoint throws, rather than silently producing an unauthenticated connection that fails later:

createTransport({ url: "wss://example.com", headers: { "x-api-key": "..." } });
// Error: Headers are not supported for WebSocket endpoints (wss://example.com).

Reading endpoints back

client.getRpcUrls();      // string[] — endpoint objects normalized to their URL,
                          // so configured headers are never exposed
client.getRpcEndpoints(); // (string | RpcEndpoint)[] — the entries as configured

Both return copies, and the client copies the rpcUrls array it was given, so a client cannot be reconfigured after construction by mutating either array. getRpcEndpoints() is a shallow copy: endpoint objects are shared, so treat their headers as read-only.

Project Structure

@openscan/network-connectors/
├── src/
│   ├── strategies/              # Request execution strategies (Fallback, Parallel, Race)
│   ├── networks/                # Network-specific clients organized by chain ID
│   ├── factory/                 # Client instantiation and chain ID mapping
│   ├── NetworkClient.ts         # Base network client (concrete class)
│   ├── JsonRpcTransport.ts      # Transport interface and auto-detect factory
│   ├── RpcClient.ts             # HTTP JSON-RPC transport
│   ├── WebSocketRpcClient.ts    # WebSocket JSON-RPC transport
│   ├── RpcClientTypes.ts        # JSON-RPC request/response type definitions
│   └── index.ts                 # Main export file
├── tests/                       # Comprehensive test suite
│   ├── http/                    # HTTP transport tests (strategies, networks, factory)
│   ├── ws/                      # WebSocket transport tests (strategies, networks)
│   ├── transport/               # Transport layer tests (auto-detection)
│   └── helpers/                 # Test utilities (validators, env config)
├── scripts/
│   └── publish-and-tag.sh       # Automated release workflow
├── .github/workflows/
│   └── npm-publish.yml          # CI/CD automation
├── dist/                        # Compiled JavaScript output (gitignored)
├── biome.json                   # Linting and formatting configuration
├── tsconfig.json                # TypeScript configuration
└── package.json                 # Project metadata and dependencies

Directory Purposes

src/strategies/: Implements the Strategy pattern for RPC request execution
- FallbackStrategy: Sequential execution with early exit on success
- ParallelStrategy: Concurrent execution with inconsistency detection
- RaceStrategy: Concurrent execution returning first successful response
- StrategyFactory: Creates appropriate strategy based on configuration
src/networks/: Network-specific client implementations (one directory per chain ID)
- Each client extends NetworkClient base class
- Provides network-specific RPC methods and type definitions
- Organized by chain ID for clarity
src/factory/: Client instantiation logic
- ClientRegistry: Maps chain IDs to client classes with type safety
- Factory methods for creating clients
tests/: Comprehensive test coverage
- Uses Node.js native test framework with tsx
- Split by transport: http/ for HTTP tests, ws/ for WebSocket tests
- transport/ for transport layer auto-detection tests
- helpers/ for shared validators and env config
scripts/: Automation scripts
- Release workflow (build, publish, tag)

Architecture Overview

Strategy Pattern

The library uses the Strategy Pattern to provide flexible RPC request execution:

FallbackStrategy: Tries RPC providers sequentially until one succeeds
- Minimal overhead (stops at first success)
- Returns metadata tracking all attempted providers and response times
- Best for reliability when providers are generally consistent
ParallelStrategy: Executes all RPC providers concurrently
- Tracks response times and errors for all providers
- Detects data inconsistencies by hashing each canonicalized response, so divergence in nested fields is caught too
- Treats object key order as insignificant and array order as significant
- Returns comprehensive metadata for debugging
- Best for detecting provider divergence
RaceStrategy: Executes all RPC providers concurrently, returns first success
- Uses Promise.any to return as soon as any provider succeeds
- Minimizes latency by using the fastest responding provider
- Only fails if ALL providers fail
- Includes metadata with winning response and errors
- Best for latency-sensitive operations

Strategies can be configured at client creation or switched dynamically using updateStrategy(). All three strategies support both HTTP and WebSocket transports interchangeably.

Transport Layer

The library supports both HTTP and WebSocket transports through a unified JsonRpcTransport interface:

RpcClient (HTTP): Stateless, one request per fetch call
WebSocketRpcClient: Persistent connection with request multiplexing, auto-reconnect with exponential backoff, configurable timeouts
createTransport(): Factory function that auto-detects transport from URL scheme (http:///https:// → HTTP, ws:///wss:// → WebSocket)

HTTP and WebSocket endpoints can be mixed in the same strategy configuration. Call close() on the client when done to clean up WebSocket connections.

Factory Pattern

The ClientFactory provides type-safe client instantiation based on chain IDs:

import { ClientFactory, BITCOIN_MAINNET } from "@openscan/network-connectors";

const config = {
  type: "fallback" as const,
  rpcUrls: ["https://rpc.example.com"]
};

// EVM client (numeric chain ID)
const ethClient = ClientFactory.createClient(1, config);
// ethClient is typed as EthereumClient

// Bitcoin client (CAIP-2 chain ID)
const btcClient = ClientFactory.createClient(BITCOIN_MAINNET, config);
// btcClient is typed as BitcoinClient

// Type-safe client with network-specific methods
const arbClient = ClientFactory.createTypedClient(42161, config);
// arbClient has Arbitrum-specific methods like arbtraceBlock()

Type-Safe Network Clients

Each network has a dedicated client class extending NetworkClient:

Fully typed with network-specific type definitions
Network-specific RPC methods (e.g., Arbitrum traces, Optimism rollup methods)
Inherits base Ethereum methods for compatible networks
Strong TypeScript inference for return types

Available Commands

Development Workflow

Command	Description
`npm install`	Install project dependencies
`npm run build`	Compile TypeScript to JavaScript (output: `dist/`)
`npm run typecheck`	Type check `src` and `tests` without code emission
`npm run test`	Run the full test suite (HTTP + WebSocket)
`npm run test:http`	Run HTTP and transport tests
`npm run test:wss`	Run WebSocket tests only
`npm run format`	Check code formatting (Biome)
`npm run format:fix`	Auto-fix formatting issues
`npm run lint`	Check linting rules (Biome)
`npm run lint:fix`	Auto-fix linting issues
`npm run check`	Combined format + lint check

CI/CD Automation

Two GitHub Actions workflows:

ci.yml — runs on pull requests and pushes to main:

quality (blocking): npm run check → npm run typecheck → npm run build
test (non-blocking): npm run test:http. Tests hit live public RPC endpoints, so a red run can mean a provider is down rather than a defect

npm-publish.yml — publishes to npm on every push to main:

Trigger: Push to main branch
Environment: ubuntu-latest, Node.js 24
Steps: Checkout → Setup Node.js → Install dependencies → Build → Publish
Authentication: Uses OIDC authentication for npm publishing

Development Setup

Prerequisites

Node.js: Version 24 or higher
npm: Comes with Node.js

Installation Steps

Clone the repository:

git clone https://github.com/openscan-explorer/network-connectors.git
cd network-connectors

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Run tests to verify setup:
```
npm run test
```

Code Quality Checks

Before committing, ensure your code passes all quality checks:

npm run check      # Check formatting and linting
npm run typecheck  # Check TypeScript types
npm run test       # Run test suite

Or auto-fix issues:

npm run format:fix  # Auto-fix formatting
npm run lint:fix    # Auto-fix linting

Testing

Running Tests

npm run test       # Run all tests (HTTP + WebSocket)
npm run test:http  # Run HTTP and transport tests
npm run test:wss   # Run WebSocket tests only

The project uses Node.js native test framework with tsx for TypeScript execution. No external test frameworks like Jest or Mocha are required.

Tests make real RPC calls against live endpoints — nothing is mocked — so a failure can mean a provider is down or rate-limiting rather than a defect.

Test credentials

Everything runs without configuration; tests needing a credential skip instead of failing. To run more of the suite, copy .env.example to .env and fill in what you have:

Variable	Unlocks
`ALCHEMY_API_KEY`	Adds an Alchemy endpoint to the EVM test URL lists
`TATUM_API_KEY`	Lifts Tatum's 5 req/min anonymous cap, enabling the live Zcash tests
`ZCASH_RPC_URL`	A self-hosted `zebrad`, enabling the shielded (`z_*`), address-index and node-admin tests that no hosted free endpoint exposes

Values left in the <placeholder> form are treated as unset, so copying .env.example verbatim behaves exactly like having no .env.

A local Hardhat node on 127.0.0.1:8545 is needed for the chain-31337 tests; without one they fail rather than skip.

Test Structure

Tests are split by transport type to validate both HTTP and WebSocket:

tests/http/strategies/: Strategy tests over HTTP transport
tests/http/networks/: Network client tests over HTTP transport
tests/http/factory/: ClientFactory tests
tests/ws/strategies/: Strategy tests over WebSocket transport
tests/ws/networks/: Network client tests over WebSocket (organized by chain ID subdirectories)
tests/transport/: Transport layer tests (auto-detection, interface compliance)
tests/helpers/: Shared test utilities
- validators.ts: Validators for hex strings, addresses, blocks, transactions, receipts, logs, strategy metadata
- env.ts: Test URL configuration with optional Alchemy API key support

Testing Rules

Real RPC calls only: All network client tests must call live RPC endpoints. Never mock RPC calls.
Type validation: Tests must validate that response data matches the expected TypeScript type definitions. Each test is tagged:
- [strong]: Validates response shape, field types, and format (e.g., hex strings, required fields)
- [weak]: Cannot fully validate response types (e.g., admin/debug methods unsupported on public nodes). Only checks that a result is returned.

Contributing

Adding a New Network

To add support for a new blockchain network:

Create network directory:

mkdir -p src/networks/<CHAIN_ID>   # EVM chains use the numeric chain ID
mkdir -p src/networks/<name>       # non-EVM chains use a lowercase name (bitcoin, zcash, solana)

Define network-specific types (if needed):
- Create types file for network-specific data structures
- Extend base Ethereum types if applicable
- For non-EVM chains, declare the CAIP-2 chain ID constants and the <Name>ChainId union here — the registry imports them from the types file
Create client class:
- Extend NetworkClient base class
- Implement network-specific RPC methods
- Use this.execute<T>(method, params) for all RPC calls
- Add JSDoc comments for all public methods
Update factory in src/factory/ClientRegistry.ts:
- EVM chains: add the chain ID to SupportedChainId, update the ChainIdToClient mapping, add an entry to CHAIN_REGISTRY, and add a createClient() overload
- CAIP-2 chains (Bitcoin, Zcash, Solana): add a Supported<Name>ChainId alias, extend SupportedNetwork, add a branch to NetworkToClient (not ChainIdToClient), add a <NAME>_REGISTRY, add an is<Name>Network() guard that tests registry membership (never a namespace prefix — Bitcoin and Zcash share bip122:), then add the createClient() overload and a dispatch branch
- createTypedClient() needs no change; it delegates and casts through NetworkToClient
Export from index:
- Add exports to src/index.ts: a banner comment, a value export for the client, a value export for the chain ID constants, then one export type {} block
Add tests:
- Create HTTP test file in tests/http/networks/
- Create a WebSocket test directory and file in tests/ws/networks/<CHAIN_ID>/, if the network has a WebSocket RPC — Bitcoin and Zcash do not, so they have HTTP tests only
- Add factory cases to tests/http/factory/ClientFactory.test.ts
- Test client instantiation, methods, and type safety
Update documentation:
- Add network to supported networks table in README.md and CLAUDE.md
- Document any special features or methods

Adding New RPC Methods

To add new RPC methods to an existing network:

Add method to client class:

async methodName(param1: Type1, param2?: Type2): Promise<StrategyResult<ReturnType>> {
  const params: any[] = [param1];
  if (param2 !== undefined) params.push(param2);
  return this.execute<ReturnType>("rpc_methodName", params);
}

Define return type (if needed):
- Add type definition to appropriate types file
- Use existing types where possible

Add JSDoc comment:

/**
 * Brief description of what this method does
 * @param param1 Description of parameter
 * @param param2 Optional parameter description
 * @returns Promise with strategy result containing return type
 */

Add test coverage:
- Test success case
- Test error handling
- Test parameter validation

Code Style Guidelines

This project uses Biome for linting and formatting:

Line Width: 100 characters
Indentation: 2 spaces
Quotes: Double quotes
Semicolons: Required
Trailing Commas: ES5 (no trailing commas in function parameters)

Run formatters before committing:

npm run format:fix  # Auto-fix formatting
npm run lint:fix    # Auto-fix linting issues

Pull Request Process

Fork the repository

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes:
- Follow code style guidelines
- Add tests for new functionality
- Update documentation if needed

Run quality checks:

npm run check
npm run typecheck
npm run test

Commit your changes:

git commit -m "feat: description of your changes"

Push to your fork:

git push origin feature/your-feature-name

Open a pull request against the main branch

Release Process

Manual Release

Ensure you're on the main branch with a clean working directory
Confirm package.json carries a version not yet on npm — the PR being released bumps it (see Version Management)
Run the release script:
```
npm run release
```
The script will automatically:
- Validate environment
- Run all quality checks
- Build the project
- Publish to npm
- Create and push git tag

Automated Release

Every push to the main branch triggers automatic npm publication via GitHub Actions:

Merge your PR — including its version bump — to main
GitHub Actions automatically builds and publishes
Check Actions tab for workflow status

The publish step only runs when the version in package.json is not already on npm. A merge without a version bump publishes nothing, yet the workflow still reports success.

Version Management

Version is managed in package.json
Every PR that adds functionality or resolves an issue must bump the version, in that same PR
Follow Semantic Versioning — when a PR mixes kinds of change, the highest level wins:
- MAJOR: Breaking changes to the public API
- MINOR: New features (backwards compatible)
- PATCH: Bug fixes (backwards compatible)
Bump with npm version <major|minor|patch> --no-git-tag-version, which updates package.json and package-lock.json together, and commit it on its own with the bare version as the subject (e.g. 1.8.1)
PRs that change no shipped code — docs, tests, CI, tooling — need no bump

Configuration Files

TypeScript Configuration (tsconfig.json)

Target: ES5 (broad compatibility)
Module: ESNext (native ES modules)
Output: dist/ directory
Type Declarations: Generated in dist/types/
Strict Mode: Enabled for maximum type safety

Biome Configuration (biome.json)

Formatter: 100 char line width, 2-space indent
Linter: Recommended rules with custom overrides
File Patterns: src/**/*.ts, tests/**/*.ts
Special Rules: Relaxed explicit any checks in test files

Package Configuration (package.json)

Type: "module" (ES modules)
Main Entry: dist/index.js
Type Definitions: dist/index.d.ts
Exports: Dual support for require/import
Files: Only dist/ directory published to npm

Project Metadata

Repository: https://github.com/openscan-explorer/network-connectors
Issues: https://github.com/openscan-explorer/network-connectors/issues
Package: @openscan/network-connectors on npm
License: MIT

Additional Resources

CLAUDE.md: Comprehensive AI assistant context file with detailed codebase documentation
TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/intro.html
Biome Documentation: https://biomejs.dev/
Node.js Test Framework: https://nodejs.org/api/test.html

Support

For questions, issues, or contributions:

Check existing issues: GitHub Issues
Open a new issue: Provide detailed description, steps to reproduce, and environment info
Contribute: Follow the contribution guidelines above

License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with TypeScript, tested with Node.js, formatted with Biome.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Latest commit

History

Folders and files

Repository files navigation