Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Web3HttpProvider
✓ import Web3HttpProvider from 'xdc3-providers-http';
✗ import { Web3HttpProvider } from 'xdc3-providers-http';
The `Web3HttpProvider` class is commonly exported as a default export in ESM, aligning with its typical CommonJS usage where `require('xdc3-providers-http')` directly yields the class constructor.
Web3HttpProvider (CJS)
✓ const Web3HttpProvider = require('xdc3-providers-http');
✗ const { Web3HttpProvider } = require('xdc3-providers-http');
In CommonJS, the package typically exports the `Web3HttpProvider` class directly as its `module.exports`, meaning no destructuring is required.
HttpProviderOptions (type)
✓ import type { HttpProviderOptions } from 'xdc3-providers-http';
For TypeScript projects, import the `HttpProviderOptions` interface using a type-only import for specifying configuration objects without incurring runtime overhead.
This quickstart demonstrates how to instantiate and configure `Web3HttpProvider` with custom options (like timeout and headers) and integrate it with the `XDC3` library to fetch the current block number and chain ID from an XDC node, showcasing basic connectivity.
import Web3HttpProvider from 'xdc3-providers-http';
import XDC3 from 'xdc3'; // Ensure 'xdc3' package is also installed
// --- Configuration ---
// It's good practice to get URLs from environment variables
const xdcNodeUrl = process.env.XDC_NODE_URL ?? 'http://localhost:8545';
// --- Provider Options (HttpProviderOptions type) ---
const providerOptions = {
keepAlive: true,
timeout: 30000, // RPC call timeout in milliseconds
headers: [
{ name: 'X-App-Name', value: 'MyXDC3App' },
{ name: 'Authorization', value: `Bearer ${process.env.XDC_AUTH_TOKEN ?? ''}` } // Example for authenticated nodes
],
// For custom HTTP agent configuration in Node.js, e.g., to increase maxSockets:
// agent: { http: new (require('http').Agent)({ maxSockets: 10 }), https: new (require('https').Agent)({ maxSockets: 10 }) },
};
// --- Instantiate the Provider ---
const provider = new Web3HttpProvider(xdcNodeUrl, providerOptions);
// --- Instantiate XDC3 with the provider ---
const xdc3 = new XDC3(provider);
// --- Example Usage: Get the current block number and chain ID ---
async function getCurrentBlockchainInfo() {
try {
const blockNumber = await xdc3.eth.getBlockNumber();
const chainId = await xdc3.eth.getChainId();
console.log(`Successfully connected to XDC node at ${xdcNodeUrl}`);
console.log(`Current block number: ${blockNumber}`);
console.log(`Connected to Chain ID: ${chainId}`);
} catch (error) {
console.error('Failed to connect or retrieve data from XDC node:', error);
if (error instanceof Error) {
console.error(`Error details: ${error.message}`);
}
}
}
getCurrentBlockchainInfo();
// To run this example:
// 1. Install packages: npm install xdc3 xdc3-providers-http
// 2. Ensure an XDC node is accessible at the specified URL (e.g., http://localhost:8545).
// 3. If using TypeScript, you can run directly with 'npx ts-node your-script.ts' (install ts-node).
Debug
Known issues
gotchaThis package is specifically designed for `xdc3`, the XinFin fork of Web3.js. While its API is similar to `web3-providers-http`, it's critical to use `xdc3-providers-http` when building applications with the `xdc3` core library to ensure full compatibility with XinFin-specific network behaviors and features.fixAlways install `xdc3-providers-http` if your project uses the `xdc3` library. Avoid interchanging it with `web3-providers-http` from the mainstream Web3.js library to prevent unexpected issues.
affects: >=1.0.0
breakingFuture major versions of `xdc3-providers-http`, in line with modern JavaScript ecosystem trends, may transition to ESM-only module distribution. This change would break existing CommonJS `require()` statements if the package does not provide dual CommonJS/ESM compatibility.fixFor new projects or when upgrading, prefer using ESM `import` statements. For existing CommonJS projects, monitor release notes for explicit guidance on ESM-only transitions and consider migration strategies or using dynamic `import()` where appropriate.
affects: future major versions (e.g., >=2.0.0)
gotchaThe `engines` field in `package.json` specifies Node.js `>=8.0.0`. While this package might function on older Node.js versions, it is strongly recommended to use a currently supported Node.js LTS version (e.g., Node.js 16 or 18) to benefit from security patches, performance enhancements, and broader compatibility with other modern JavaScript tooling.fixEnsure your development and production environments run on a supported Node.js LTS version. Tools like `nvm` (Node Version Manager) can facilitate easy switching and management of Node.js versions.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Web3HttpProvider is not a constructor
This error typically occurs due to an incorrect import statement, either attempting to destructure a default CommonJS export or using a named import when the module provides a default export in ESM.
fixFor ESM, ensure you use `import Web3HttpProvider from 'xdc3-providers-http';`. For CommonJS, use `const Web3HttpProvider = require('xdc3-providers-http');`. Do not use `{ Web3HttpProvider }` with default exports. Error: CONNECTION ERROR: Couldn't connect to node http://localhost:8545.
The application failed to establish a connection with the specified XDC RPC node. This can be due to the node not running, being inaccessible, or listening on a different address/port.
fixVerify that your XDC node (or a public XDC RPC endpoint) is running and accessible from the machine where your application is executing. Double-check the configured `xdcNodeUrl` for typos and ensure no firewall rules are blocking the connection. Network latency or an overloaded node can also contribute to this.
ERR_REQUIRE_ESM
Attempting to `require()` an ESM-only package within a CommonJS module context. This happens if the package or one of its dependencies has fully transitioned to ESM.
fixIf this package or its dependencies become ESM-only in a future update, you must convert your consuming file to an ESM module (e.g., by changing its extension to `.mjs` or by setting `"type": "module"` in your `package.json` and using `import` statements). Alternatively, consider using dynamic `import()` within your CommonJS module.
Audit
Dependencies
No dependency data recorded yet.