XDC3 HTTP Provider

Common errors

• TypeError: Web3HttpProvider is not a constructor

  cause 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.
  fix For 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.

  cause 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.
  fix Verify 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

  cause 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.
  fix If 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.

Warnings

• gotcha This 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.
  Fix: Always 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.
• breaking Future 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.
  Fix: For 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.
• gotcha The `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.
  Fix: Ensure 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.

Install

• npm install xdc3-providers-http npm
• yarn add xdc3-providers-http yarn
• pnpm add xdc3-providers-http pnpm

Imports

• Web3HttpProvider
  wrong:

  import { Web3HttpProvider } from 'xdc3-providers-http';

  correct:

  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)
  wrong:

  const { Web3HttpProvider } = require('xdc3-providers-http');

  correct:

  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.

Quickstart

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).