Add guide for the breaking changes for Iban and IpcProvider

docs/docs/guides/web3_migration_guide/net_migration_guide.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 sidebar_label: web3.*.net
 ---
 

docs/docs/guides/web3_migration_guide/personal_migration_guide.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 sidebar_label: web3.eth.personal
 ---
 

docs/docs/guides/web3_migration_guide/providers_migration_guide.md

@@ -105,11 +105,12 @@ interface ReconnectOptions {
 }
 ```
 
-In 4.x, the options object is of type `ClientRequestArgs` or of `ClientOptions`. See [here](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_http_d_._http_.clientrequestargs.html) for `ClientRequestArgs` and [here](https://github.com/websockets/ws) for `ClientOptions`.
+In 4.x, the `socketOptions` parameter is of type `ClientRequestArgs` or of `ClientOptions`. See [here](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_http_d_._http_.clientrequestargs.html) for `ClientRequestArgs` and [here](https://github.com/websockets/ws) 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:
+In 4.x the `reconnectOptions` parameter can be given regarding auto-reconnecting, delay and max tries attempts. And here is its type:
 
 ```ts
+// this is the same options interface used for both WebSocketProvider and IpcProvider
 type ReconnectOptions = {
 	autoReconnect: boolean; // default: `true`
 	delay: number; // default: `5000`
@@ -165,7 +166,87 @@ const reconnectOptions: ReconnectOptions = {
 };
 ```
 
-##### Error message for reconnect attempts
+#### 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`](https://github.com/web3/web3.js/blob/1.x/packages/web3-core-helpers/types/index.d.ts#L192). The `WebsocketProviderOptions` interface consists of:
+
+```ts
+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](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_net_d_._net_.socketconstructoropts.html) for full details. And here is its interface:
+
+```ts
+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:
+
+```ts
+// 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:
+
+```ts
+// 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!'`

docs/docs/guides/web3_migration_guide/subscribe_migration_guide.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 sidebar_label: web3.eth.subscribe
 ---
 

docs/docs/guides/web3_migration_guide/web3_eth_iban.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 7
+sidebar_label: web3.eth.iban
+---
+
+# web3.eth.iban Migration Guide
+
+## Breaking Changes
+
+### Iban class
+
+#### The Iban contractor
+
+##### In version 1.x
+
+It used to just accept the passed string without any check.
+
+##### In version 4.x
+
+If the provided string was not of either the length of a direct IBAN (34 or 35), or the length of an indirect IBAN (20), an Error will be thrown. The error will contain the message `'Invalid IBAN was provided'`
+
+#### Calling `toAddress` on an Iban that is not Direct
+
+##### In version 1.x
+
+It used to behave diffidently, if it was called on an instance of IBAN, from if it was called as a static method. However, this used to happen only if the provided address was not a Direct IBAN. More specifically, if the instance method `new Iban(address).toAddress()` was called, it will return an empty string (`''`) for that non Direct IBAN. And if the static method `Iban.toAddress(address)` was called, it used to throw an Error with the message `'IBAN is indirect and can\'t be converted'`, for that non Direct IBAN.
+
+##### In version 4.x
+
+If the provided IBAN was not a Direct one, an error will be thrown which contains the message: `'Iban is indirect and cannot be converted. Must be length of 34 or 35'`. And this behavior is now the same for the instance method `new Iban(address).toAddress()` and the static method `Iban.toAddress(address)`.
+
+#### Calling `fromAddress` on an invalid address
+
+##### In version 1.x
+
+If the provided IBAN was not a valid Ethereum Address, an error used be thrown which contains the message `'Provided address is not a valid address: '+ address`.
+
+##### In version 4.x
+
+If the provided IBAN was not a valid Ethereum Address, an error object will be thrown which contains the message: `'Invalid value given "${address}". Error: 'invalid ethereum address'` and the code `1005`.

docs/docs/guides/web3_migration_guide/web3_utils_migration_guide.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 sidebar_label: web3.utils
 ---
 

docs/docs/guides/web3_providers_guide/index.md

@@ -188,7 +188,56 @@ const reconnectOptions: ReconnectOptions = {
 };
 ```
 
-##### Error message for reconnect attempts
+#### IpcProvider
+
+The IPC provider is used in node.js dapps when running a local node. And it provide the most secure connection.
+
+The `socketOptions` parameter is of type `SocketConstructorOpts`. See [here](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_net_d_._net_.socketconstructoropts.html) for full details. And here is its interface:
+
+```ts
+// for more check: https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_net_d_._net_.socketconstructoropts.html
+interface SocketConstructorOpts {
+	fd?: number | undefined;
+	allowHalfOpen?: boolean | undefined;
+	readable?: boolean | undefined;
+	writable?: boolean | undefined;
+}
+```
+
+And, the `reconnectOptions` parameter can be given regarding auto-reconnecting, delay and max tries attempts. And here its type:
+
+```ts
+// 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:
+
+```ts
+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 message (not wrapped in an Error object) for the max reconnect attempts, will contain the value of the variable `maxAttempts` as follows: