Documentation

Configuring

Configuration Options

The JSONRpcProvider is initialized with a JSONRpcProviderConfig object that encapsulates all connection and performance settings in a single configuration structure. Only the url and network fields are required — all other options have sensible defaults and can be overridden as needed for your environment.

typescript
Constructor Signature
constructor(config: JSONRpcProviderConfig)

JSONRpcProviderConfig Interface

typescript
JSONRpcProviderConfig Interface
interface JSONRpcProviderConfig {
    readonly url: string;
    readonly network: Network;
    readonly timeout?: number;
    readonly fetcherConfigurations?: Agent.Options;
    readonly useThreadedParsing?: boolean;
    readonly useThreadedHttp?: boolean;
}

Parameter Reference

Property Type Default Description
url string required RPC endpoint URL.
network Network required Bitcoin network (mainnet/testnet/opnetTestnet/regtest).
timeout number 20000 Request timeout in milliseconds.
fetcherConfigurations Agent.Options see below HTTP agent configuration.
useThreadedParsing boolean true Parse responses in a worker thread.
useThreadedHttp boolean true Perform entire HTTP request in a worker thread.

Fetcher Configuration

The provider utilizes HTTP requests with built-in connection pooling to optimize network performance. Connection pooling maintains a set of reusable connections, eliminating the overhead of establishing new connections for each request. These HTTP configuration parameters are specified through an Agent.Options object.

Agent.Options Reference

Property Type Default Description
keepAliveTimeout number 30000 Socket keep-alive duration in ms. How long sockets stay open without activity.
keepAliveTimeoutThreshold number 30000 Keep-alive threshold in ms. Threshold before closing keep-alive sockets.
connections number 128 Maximum concurrent connections per server.
pipelining number 2 Maximum requests to pipeline per connection.

Configurations

Default

typescript
Default Configuration
const provider = new JSONRpcProvider({
    url: url, 
    network: network, 
    timeout: 20000, 
    fetcherConfigurations: {
        keepAliveTimeout: 30_000,     // Socket keep-alive
        keepAliveTimeoutThreshold: 30_000,
        connections: 128,             // Max connections
        pipelining: 2,                // Pipelined requests
    }
});

High-Performance

typescript
High-Performance Configuration
const provider = new JSONRpcProvider({
    url: url,
    network: network,
    timeout: 30000,  // Longer timeout
    fetcherConfigurations: {
        keepAliveTimeout: 60_000,    // Longer keep-alive
        keepAliveTimeoutThreshold: 60_000,
        connections: 256,            // More connections
        pipelining: 10,              // More pipelining
    }
});

Production Recommended

typescript
Production Recommended Configuration
// Production configuration
const provider = new JSONRpcProvider({
    url: 'https://mainnet.opnet.org',
    network: networks.bitcoin,
    timeout: 60_000,  // Longer timeout for mainnet
    fetcherConfigurations:{
        connections: 256,
        pipelining: 4,
    },
    useThreadedParsing: true,   // Threaded parsing
    useThreadedHttp: true    // Threaded HTTP
});

Threaded Parsing

For large responses, the provider can parse JSON in a worker thread to prevent blocking the main thread. This option is configured by passing the useThreadedParsing parameter to the constructor(). Threaded parsing is disabled by default when no value is specified.

Recommended use cases for threaded parsing:

  • Processing large block data.
  • Fetching multiple transactions simultaneously.
  • Production environments.

Scenarios where threaded parsing should be disabled:

  • Debugging.
  • Handling small responses.
  • Environments without worker support.
typescript
Specifying Threaded Parsing
// Enable threaded parsing
const provider = new JSONRpcProvider({
    url: url,
    network: network,
    timeout: 20_000,
    fetcherConfigurations: undefined,
    useThreadedParsing: true
});

// Disable for small responses or debugging
const provider = new JSONRpcProvider({
    url: url,
    network: network,
    timeout: 20_000,
    fetcherConfigurations: undefined,
    useThreadedParsing: false
});

Threaded HTTP

Beyond threaded parsing, the provider can offload the entire HTTP request (network I/O + JSON parsing) to a worker thread, completely freeing the main thread. This option is configured by passing the useThreadedHttp parameter to the constructor(). Threaded HTTP is disabled by default when no value is specified.

Threaded HTTP Overview Main Thread Worker Thread OP_NET Node fetch request HTTP POST Worker: JSON response (dashed) --> JSON response JSON.parse() Main: Parsed result (dashed) --> Parsed result Main Thread Worker Thread OP_NET Node

Recommended use cases for threaded HTTP:

  • High-frequency RPC calls.
  • Real-time applications where main thread responsiveness is critical.
  • Browser environments to prevent UI blocking.
  • Production environments.

Scenarios where threaded HTTP should be disabled:

  • Debugging network issues.
  • Service worker contexts (automatic fallback provided).
  • When fine-grained control over HTTP requests is required.
typescript
Specifying Threaded HTTP
// Enable threaded HTTP
const provider = new JSONRpcProvider({
    url: url,
    network: network,
    tiemout: 20_000,
    fetcherConfigurations: undefined,
    useThreadedParsing: true,
    useThreadedHttp: true
});

// Disable threaded HTTP (uses main thread for HTTP, optional threaded parsing)
const provider = new JSONRpcProvider({
    url: url,
    network: network,
    tiemout: 20_000,
    fetcherConfigurations: undefined,
    useThreadedParsing: true,
    useThreadedHttp: false
});

Complete Configuration Example

typescript
Complete Configuration Example
import { JSONRpcProvider } from 'opnet';
import { networks } from '@btc-vision/bitcoin';

const provider = new JSONRpcProvider({
    url: 'https://regtest.opnet.org',// RPC URL
    network: networks.regtest,       // Network
    timeout: 30_000,                 // 30s timeout
    fetcherConfigurations: {
        keepAliveTimeout: 60_000,    // 60s keep-alive
        connections: 256,            // More connections
        pipelining: 4,               // More pipelining
    },
    useThreadedParsing: true,        // Use threaded parsing
    useThreadedHttp: true            // Use threaded HTTP
});

async function main() {
    // Use the provider
    const block = await provider.getBlockNumber();
    console.log('Current block:', block);

    // Always close when done
    await provider.close();
}

main();
On this page