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 options object is of type ClientRequestArgs
or of ClientOptions
. See here for ClientRequestArgs
and here for ClientOptions
.
In 4.x a second option parameter can be given regarding auto-reconnecting, delay and max tries attempts. And here is its type:
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,
};
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!'
And, the error in version 4.x, is the same, but will also contain the value of the variable maxAttempts
as follows:
`Maximum number of reconnect attempts reached! (${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', error => {
if (error.message.startsWith('Maximum number of reconnect attempts reached!')) {
// the `error.message` will be `Maximum number of reconnect attempts reached! (${maxAttempts})`
// the `maxAttempts` is equal to the provided value by the user, or the default value `5`.
}
});