web3.providers Migration Guide

For full description about the providers, their priorities and their types, you can check web3.js Providers Guide.

Provider Options Changes

There are differences in the objects that could be passed in the Provider constructors between version 1.x and 4.x. Below, you will find the difference for every Provider object type.

HttpProvider

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

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

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

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:

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

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

In 4.x, the socketOptions parameter is of type ClientRequestArgs or of ClientOptions. See here for ClientRequestArgs and here for ClientOptions.

In 4.x the reconnectOptions parameter can be given regarding auto-reconnecting, delay and max tries attempts. And here is its type:

// this is the same options interface used for both WebSocketProvider and IpcProvider
type ReconnectOptions = {
    autoReconnect: boolean; // default: `true`
    delay: number; // default: `5000`
    maxAttempts: number; // default: `5`
};

Options examples

Below is an example for the passed options for each version:

// 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,
};

IpcProvider

The IPC provider is used in node.js dapps when running a local node. And it provide the most secure connection.

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 socketOptions parameter is of type SocketConstructorOpts. See here for full details. And here is its interface:

interface SocketConstructorOpts {
    fd?: number | undefined;
    allowHalfOpen?: boolean | undefined;
    readable?: boolean | undefined;
    writable?: boolean | undefined;
    signal?: AbortSignal;
}

In 4.x the reconnectOptions parameter can be given regarding auto-reconnecting, delay and max tries attempts. And here its type:

// this is the same options interface used for both WebSocketProvider and IpcProvider
export type ReconnectOptions = {
    autoReconnect: boolean;
    delay: number;
    maxAttempts: number;
};

Options examples

Below is an example for the passed options for each version:

// in 1.x
var net = require('net');

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"

// in 4.x
let clientOptions: SocketConstructorOpts = {
    allowHalfOpen: false;
    readable: true;
    writable: true;
};

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

Error message for reconnect attempts

note

This section applies for both IpcProvider and WebSocketProvider.

The error in, version 1.x, was an Error object that contains the message: 'Maximum number of reconnect attempts reached!'

However, the error, in version 4.x, is just an error message (not wrapped in an Error object). And the error message will contain the value of the variable maxAttempts as follows:

`Max connection attempts exceeded (${maxAttempts})`

And here is how to catch the error, in version 4.x, if max attempts reached when there is auto reconnecting:

provider.on('error', errorMessage => {
    if (errorMessage.startsWith('Max connection attempts exceeded')) {
        // the `errorMessage` will be `Max connection attempts exceeded (${maxAttempts})`
        // the `maxAttempts` is equal to the provided value by the user, or the default value `5`.
    }
});