Web3.js limits on custom DNS resolvers and TLS validation

Answer the exact question first

Web3.js 4.x does not expose an API to inject a custom DNS resolver. The only networking hook it offers is the agent option, which is forwarded to the underlying undici request engine. There is no documented or planned extension that would let you supply your own resolver.

Why the limitation exists

The library relies on Node’s built‑in dns module through undici. Exposing a resolver would require changing the request engine’s internal plumbing, which is outside Web3.js’s scope. The current design keeps the provider lightweight and avoids tight coupling with DNS implementation details.

Best practice for TLS control without environment variables

1. Create a custom https.Agent that configures the TLS settings you need.

   const https = require('https');
   const agent = new https.Agent({
     rejectUnauthorized: false, // or true with custom CA
     ca: [fs.readFileSync('ca.pem')],
     // optional: pin the cert by checking the server identity
     checkServerIdentity: (host, cert) => {
       const expected = fs.readFileSync('pin-cert.pem');
       if (cert.raw.toString('hex') !== expected.toString('hex')) {
         return new Error('Certificate pinning failed');
       }
     }
   });
   

2. Pass the agent to the provider via the options object.

   const provider = new Web3.providers.HttpProvider(
     'https://my‑node.example',
     { agent }
   );
   const web3 = new Web3(provider);
   

3. Use web3.eth.getBlockNumber() or any RPC call to confirm the connection.

Implementing certificate pinning provider‑agnostically

Because Web3.js only forwards the agent, you can create a small wrapper provider that injects your pinned‑certificate agent. For example:

class PinnedHttpProvider extends Web3.providers.HttpProvider {
  constructor(url, pinnedCertPath) {
    const agent = new https.Agent({
      ca: [fs.readFileSync(pinnedCertPath)],
      checkServerIdentity: () => undefined // skip default checks
    });
    super(url, { agent });
  }
}

const provider = new PinnedHttpProvider('https://node', 'pin-cert.pem');
const web3 = new Web3(provider);

This wrapper works with any provider that accepts an agent (e.g., HttpProvider, WebsocketProvider if you use ws’s Agent).

What you cannot do yet

• Inject a custom DNS resolver – Web3.js will still use Node’s global dns module.
• Perform automatic retries on DNS failures – the library treats any network error as a generic failure.
• Pin certificates without a custom https.Agent – there is no built‑in pinning API.

When to request an API change

If your project requires DNS failover or custom resolution logic, consider filing an issue on the Web3.js repo or contributing a small patch that extends undici usage. In the meantime, the agent‑based approach is the safest and most maintainable path.

Ask for missing diagnostic detail

To fine‑tune the recommendation, could you share whether you need DNS resolution for IP‑based endpoints or only for hostnames? This affects whether a simple https.Agent is sufficient or if a full proxy solution is required.