Add guide for the breaking changes for Iban and IpcProvider (#5899)

* add guide for `IpcProvider`

* add migration guid for Iban

* rearrange sidebar_position for iban guide

* update and correct providers guides and give more samples

* set the type for reconnectOptions at SocketProvider constructor

* improve SocketProvider, WebSocketProvider and IpcProvider constructor types

* few edits at providers guides

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 to control: 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,6 +166,130 @@ const reconnectOptions: ReconnectOptions = {
 };
 ```
 
+And here is a sample instantiation for the `WebSocketProvider`:
+
+```ts
+const provider = new WebSocketProvider(
+	`ws://localhost:8545`,
+	{
+		headers: {
+			// to provide the API key if the Node requires the key to be inside the `headers` for example:
+			'x-api-key': '<Api key>',
+		},
+	},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
+
+The second and the third parameters are both optional. And you can for example, the second parameter could be an empty object or undefined, like in the following example:
+
+```ts
+const provider = new WebSocketProvider(
+	`ws://localhost:8545`,
+	{},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
+
+#### 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, it used to accept the path and an instance of net.Server as in the following example:
+
+```ts
+import * as net from 'net';
+
+const ipcProvider = new IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', new net.Server());
+```
+
+In 4.x, it accepts a second parameter called `socketOptions`. And, its type is `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 third parameter is called `reconnectOptions` that is of the type `ReconnectOptions`. It can be given to control: auto-reconnecting, delay and max tries attempts. And here 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`
+	maxAttempts: number; // default: `5`
+};
+```
+
+##### 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,
+};
+```
+
+And here is a sample instantiation for the `IpcProvider`:
+
+```ts
+const provider = new IpcProvider(
+	`path.ipc`,
+	{
+		writable: false,
+	},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
+
+The second and the third parameters are both optional. And, for example, the second parameter could be an empty object or undefined.
+
+```ts
+const provider = new IpcProvider(
+	`path.ipc`,
+	{},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
+
 #### Error message for reconnect attempts
 
 :::note
@@ -187,4 +312,4 @@ provider.on('error', error => {
 		// the `maxAttempts` is equal to the provided value by the user, or the default value `5`.
 	}
 });
-```
+```

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 differently, 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/events_listening.md

@@ -46,7 +46,7 @@ web3.provider.on('chainChanged',()=>{
 })
 
 // it is possible to catch errors that could happen in the underlying connection Socket with the `error` event
-// and it is also used to catch the error when max connection attempts exceeded
+// and it is also used to catch the error when max reconnection attempts exceeded
 //  as in section: /docs/guides/web3_providers_guide/#error-message
 web3.provider.on('error',()=>{
   // ...

docs/docs/guides/web3_providers_guide/index.md

@@ -142,31 +142,53 @@ const httpOptions = {
 
 #### WebSocketProvider
 
+Use WebSocketProvider to connect to a Node using a WebSocket connection, i.e. over the `ws` or `wss` protocol.
+
 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`.
 
 The second option parameter can be given regarding reconnecting. And here is its type:
 
 ```ts
+// this is the same options interface used for both WebSocketProvider and IpcProvider
 type ReconnectOptions = {
-	autoReconnect: boolean;
-	delay: number;
-	maxAttempts: number;
+	autoReconnect: boolean; // default: `true`
+	delay: number; // default: `5000`
+	maxAttempts: number; // default: `5`
 };
 ```
 
-:::info
-Here is how to catch the error if max attempts reached when the auto reconnecting:
+And here is a sample instantiation for the `WebSocketProvider`:
 
 ```ts
-provider.on('error', errorMessage => {
-	if (errorMessage.startsWith('Maximum number of reconnect attempts reached!')) {
-		// the `errorMessage` will be `Maximum number of reconnect attempts reached! (${maxAttempts})`
-		// the `maxAttempts` is equal to the provided value by the user or the default `5`.
-	}
-});
+const provider = new WebSocketProvider(
+	`ws://localhost:8545`,
+	{
+		headers: {
+			// to provide the API key if the Node requires the key to be inside the `headers` for example:
+			'x-api-key': '<Api key>',
+		},
+	},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
 ```
 
-:::
+The second and the third parameters are both optional. And, for example, the second parameter could be an empty object or undefined, like in the following example:
+
+```ts
+const provider = new WebSocketProvider(
+	`ws://localhost:8545`,
+	{},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
 
 ##### Options example
 
@@ -188,9 +210,84 @@ const reconnectOptions: ReconnectOptions = {
 };
 ```
 
+### IpcProvider
+
+The IPC Provider could be used in node.js dapps when running a local node. And it provide the most secure connection.
+
+It accepts a second parameter called `socketOptions`. And, its type is `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 third parameter is called `reconnectOptions` that is of the type `ReconnectOptions`. It can be given to control: auto-reconnecting, delay and max tries attempts. And here 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`
+	maxAttempts: number; // default: `5`
+};
+```
+
+##### 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,
+};
+```
+
+And here is a sample instantiation for the `IpcProvider`:
+
+```ts
+const provider = new IpcProvider(
+	`path.ipc`,
+	{
+		writable: false,
+	},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
+
+The second and the third parameters are both optional. And, for example, the second parameter could be an empty object or undefined.
+
+```ts
+const provider = new IpcProvider(
+	`path.ipc`,
+	{},
+	{
+		delay: 500,
+		autoReconnect: true,
+		maxAttempts: 10,
+	},
+);
+```
+
 #### Error message for reconnect attempts
 
-:::note
+:::info
 This section applies for both `IpcProvider` and `WebSocketProvider`.
 :::
 
@@ -207,4 +304,4 @@ provider.on('error', error => {
 		// the `maxAttempts` is equal to the provided value by the user, or the default value `5`.
 	}
 });
-```
+```

packages/web3-eth/test/unit/utils/parse_transaction_error.test.ts

@@ -84,6 +84,6 @@ describe('parseTransactionError', () => {
 			},
 		]);
 
-		expect(() => parseTransactionError(error)).toThrowError(error);
+		expect(() => parseTransactionError(error)).toThrow(error);
 	});
 });