web3.providers Migration Guide

There are multiple ways to set the provider.

Setting a provider

web3.setProvider(myProvider);
web3.eth.setProvider(myProvider);
web3.Contract.setProvider(myProvider);
contractInstance.setProvider(myProvider);

The key rule for setting provider is as follows:

1. Any provider set on the higher level will be applied to all lower levels. e.g. Any provider set using web3.setProvider will also be applied to web3.eth object.
2. For contracts web3.Contract.setProvider can be used to set provider for all instances of contracts created by web3.eth.Contract.

tip

A provider can be either type string or SupportedProviders.

Examples

Local Geth Node

const Web3 = require('web3');
const web3 = new Web3('http://localhost:8545');
// or
const web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));

// change provider
web3.setProvider('ws://localhost:8546');
// or
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));

// Using the IPC provider in node.js
const net = require('net');
const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path
// or
const web3 = new Web3(
    new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net),
); // mac os path
// on windows the path is: "\\\\.\\pipe\\geth.ipc"
// on linux the path is: "/users/myuser/.ethereum/geth.ipc"

Remote Node Provider

// Using a remote node provider, like Alchemy (https://www.alchemyapi.io/supernode), is simple.
const Web3 = require('web3');
const web3 = new Web3('https://eth-mainnet.alchemyapi.io/v2/your-api-key');

Injected providers

The Injected provider should be in compliance with EIP1193.

The web3.js 4.x Provider specifications are defined in web3 base provider for Injected Providers.

const Web3 = require('web3');
// Using an EIP1193 provider like MetaMask can be injected

if (window.ethereum) {
    // Check if ethereum object exists
    await window.ethereum.request();
    window.web3 = new Web3(window.ethereum); // inject provider
}

Provider Options

There are differences in the objects that could be passed in the Provider constructors.

HttpProvider

In 1.x, options passed in the constructor should be of type HttpProviderOptions. The HttpProviderOptions interface consists of:

export interface HttpProviderOptions {
    keepAlive?: boolean;
    timeout?: number;
    headers?: HttpHeader[];
    withCredentials?: boolean;
    agent?: HttpAgent;
}

export interface HttpAgent {
    http?: http.Agent;
    https?: https.Agent;
    baseUrl?: string;
}

export interface HttpHeader {
    name: string;
    value: string;
}

In 4.x, the options is of type HttpProviderOptions, which is an object with a providerOptions key and value a RequestInit object. Regarding RequestInit see microsoft's github.

For example:

// in 1.x
let httpOptions = {
    keepAlive: true,
    withCredentials: false,
    timeout: 20000, // ms
    headers: [
        {
            name: 'Access-Control-Allow-Origin',
            value: '*'
        },
    ],
    agent: {
        http: http.Agent(...),
        baseUrl: ''
    }
};

// in 4.x
let httpOptions = {
    providerOptions: {
        body: undefined,
        cache: 'force-cache',
        credentials: 'same-origin',
        headers: {
            'Content-Type': 'application/json',
        },
        integrity: 'foo',
        keepalive: true,
        method: 'GET',
        mode: 'same-origin',
        redirect: 'error',
        referrer: 'foo',
        referrerPolicy: 'same-origin',
        signal: undefined,
        window: undefined,
    } as RequestInit,
};

WebsocketProvider

In 1.x, options passed in the constructor should be of type WebsocketProviderOptions. The WebsocketProviderOptions interface consists of:

export interface WebsocketProviderOptions {
    host?: string;
    timeout?: number;
    reconnectDelay?: number;
    headers?: any;
    protocol?: string;
    clientConfig?: object;
    requestOptions?: any;
    origin?: string;
    reconnect?: ReconnectOptions;
}

export interface ReconnectOptions {
    auto?: boolean;
    delay?: number;
    maxAttempts?: number;
    onTimeout?: boolean;
}

In 4.x, the options object is of type ClientRequestArgs or of ClientOptions. See Regarding RequestInit see here for ClientRequestArgs and here for ClientOptions.

In 4.x a second option parameter can be given regarding reconnecting.

The interface:

export type ReconnectOptions = {
    autoReconnect: boolean;
    delay: number;
    maxAttempts: number;
};

For example:

// in 1.x
var options = {
    timeout: 30000, // ms

    // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
    headers: {
        authorization: 'Basic username:password',
    },

    clientConfig: {
        // Useful if requests are large
        maxReceivedFrameSize: 100000000, // bytes - default: 1MiB
        maxReceivedMessageSize: 100000000, // bytes - default: 8MiB

        // Useful to keep a connection alive
        keepalive: true,
        keepaliveInterval: 60000, // ms
    },

    // Enable auto reconnection
    reconnect: {
        auto: true,
        delay: 5000, // ms
        maxAttempts: 5,
        onTimeout: false,
    },
};
// in 4.x
let clientOptions: ClientOptions = {
    // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
    headers: {
        authorization: 'Basic username:password',
    },
    maxPayload: 100000000,
};

const reconnectOptions: ReconnectOptions = {
    autoReconnect: true,
    delay: 5000,
    maxAttempts: 5,
};