Utils guide (#7008)

* added utils guide

* reorder sidebar

* added args to avoid error when copy/pasting example

docs/docs/guides/advanced/_category_.yml

@@ -2,4 +2,4 @@ label: '🧠 Advanced'
 collapsible: true
 collapsed: true
 link: null
-position: 12
+position: 14

docs/docs/guides/events_subscriptions/_category_.yml

@@ -2,4 +2,4 @@ label: '🔔 Events subscription'
 collapsible: true
 collapsed: true
 link: null
-position: 6
+position: 7

docs/docs/guides/feedback/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 17
 sidebar_label: '🗣️ Feedback'
 ---
 

docs/docs/guides/glossary/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 18
 sidebar_label: '📖 Glossary'
 title: Glossary
 ---

docs/docs/guides/hardhat_tutorial/_category_.yml

@@ -2,4 +2,4 @@ label: '⛑️ Hardhat Tutorial'
 collapsible: true
 collapsed: true
 link: null
-position: 2
+position: 3

docs/docs/guides/migration_from_other_libs/_category_.yml

@@ -2,4 +2,4 @@ label: '🔄 Migration Guides'
 collapsible: true
 collapsed: true
 link: null
-position: 11
+position: 12

docs/docs/guides/smart_contracts/_category_.yml

@@ -2,4 +2,4 @@ label: '📜 Smart Contracts'
 collapsible: true
 collapsed: true
 link: null
-position: 4
+position: 6

docs/docs/guides/wagmi_usage/_category_.yml

@@ -2,4 +2,4 @@ label: '🔄 Wagmi usage'
 collapsible: true
 collapsed: true
 link: null
-position: 11
+position: 13

docs/docs/guides/wallet/_category_.yml

@@ -2,4 +2,4 @@ label: '🔑 Wallet and Accounts '
 collapsible: true
 collapsed: true
 link: null
-position: 3
+position: 5

docs/docs/guides/web3_config/_category_.yml

@@ -2,4 +2,4 @@ label: '⚙️ Web3 config'
 collapsible: true
 collapsed: true
 link: null
-position: 9
+position: 15

docs/docs/guides/web3_eth/_category_.yml

@@ -1,5 +1,5 @@
-label: '📦 Web3Eth module'
+label: '📦 Web3 Eth module'
 collapsible: true
 collapsed: true
 link: null
-position: 7
+position: 8

docs/docs/guides/web3_plugin_guide/_category_.yml

@@ -1,5 +1,5 @@
-label: '🛠️ Web3 Plugin🧩'
+label: '🛠️ Web3 Plugin 🧩'
 collapsible: true
 collapsed: true
 link: null
-position: 13
+position: 2

docs/docs/guides/web3_providers_guide/_category_.yml

@@ -2,4 +2,4 @@ label: '🔌 Providers'
 collapsible: true
 collapsed: true
 link: null
-position: 2
+position: 4

docs/docs/guides/web3_upgrade_guide/_category_.yml

@@ -2,4 +2,4 @@ label: '⬆️ Upgrading'
 collapsible: true
 collapsed: true
 link: null
-position: 10
+position: 11

docs/docs/guides/web3_utils_module/_category_.yml

@@ -0,0 +1,5 @@
+label: '📦 Web3 Utils module'
+collapsible: true
+collapsed: true
+link: null
+position: 10

docs/docs/guides/web3_utils_module/mastering_web3-utils.md

@@ -0,0 +1,241 @@
+# Mastering Utility Functions
+
+## Introduction
+In this guide, you'll learn about the different functions of the web3 utils package, it contains the methods to know how to generate random bytes in different formats, how to perform conversion between Hex values and numbers, hashing functions, addresses, packing padding and in the last part you will see how to compare block numbers.
+
+## Installation
+
+Install only the web3 package
+```bash
+npm i web3-utils
+```
+
+Or you can install the web3 library as well and then access web3.utils
+
+```bash
+npm i web3
+```
+
+## Imports
+
+There are three different ways to import utils package.
+
+### Import the entire web3 library
+
+```js
+// import web3 module
+import { Web3 } from "web3";
+
+// no need to initialize a provider
+Web3.utils.toHex("web3");
+//=> 0x77656233
+
+// initializing  a provider
+const web3 = new Web3("https:// eth.llamarpc.com");
+
+// access the utils package
+web3.utils.toHex("web3");
+//=> 0x77656233
+```
+
+
+### Import utils module
+
+```js 
+// import utils module
+import { utils } from "web3"; 
+
+// access the utils package
+utils.toWei("1", "ether")
+```
+
+### Import specific methods
+
+```js
+// import toWei and toHex functions
+import { toWei, toHex } from"web3-utils";
+
+// usage
+toWei("1", "ether")
+toHex("")
+```    
+
+## Methods example
+
+### Random Hex and Bytes
+
+```js
+// Random bytes in hex format and array format
+
+console.log(web3.utils.randomBytes(32));
+/* => array format
+Uint8Array(32) [
+  251,  70, 124,  65, 203, 180,  92, 234,
+  210, 236,  72, 154,  83, 219, 171, 223,
+  212, 136, 117, 140,  67, 117,  86,  81,
+  234, 245, 148, 186, 175,  83,  98,  78
+]
+*/
+
+console.log(web3.utils.randomHex(32));
+/* => hex string format
+0x594386dc9b2e150979416f9b2a093e01f84a37c4f8db5fc1b0d9b1dc83a12c1f
+*/
+
+```
+:::info
+If you don't give any arguments then both of these functions will have a default value as 32.
+:::
+
+### Conversions - Ethereum Denominations
+
+We've got two different functions to perform conversions between Ethereum denominations.
+
+```js
+console.log(web3.utils.fromWei("1", "ether")); 
+// 0.000000000000000001
+
+console.log(web3.utils.toWei("1", "ether")); 
+// 1_000_000_000_000_000_000
+```
+
+### Conversions to Hex Values
+
+```js
+// most versatile one
+console.log(web3.utils.toHex(10));
+// 0xa
+
+console.log(web3.utils.toHex(true));
+// 0x01
+
+console.log(web3.utils.numberToHex(10));
+// 0xa
+
+console.log(web3.utils.fromDecimal(10));
+// 0xa
+
+const arr = new Uint8Array([1, 2, 3, 4]);
+
+console.log(web3.utils.toHex(arr));
+// 0x7b2230223a312c2231223a322c2232223a332c2233223a347d
+
+console.log(web3.utils.bytesToHex(arr));
+// 0x01020304
+```
+
+### Conversions UTF and ASCII
+
+```js
+console.log(web3.utils.utf8ToHex("😊"));
+// 0xf09f988a
+
+console.log(web3.utils.fromUtf8("😊"));
+// 0xf09f988a
+
+console.log(web3.utils.asciiToHex("😊"));
+// 0xd83dde0a
+
+console.log(web3.utils.toUtf8("0xf09f988a"));
+// 😊
+
+console.log(web3.utils.hexToUtf8("0xf09f988a"));
+// 😊
+
+console.log(web3.utils.hexToString("0xf09f988a"));
+// 😊
+
+// emojis are not ASCII character, that's why it won't work
+console.log(web3.utils.toAscii("0x4869"));
+// Hi
+
+console.log(web3.utils.hexToAscii("0x4869"));
+// Hi
+```
+
+### Conversions - Numbers and Bigint
+
+```js
+console.log(web3.utils.toNumber("0xa"));
+// 10 (number)
+
+console.log(web3.utils.hexToNumber("0xa"));
+// 10 (number)
+
+console.log(web3.utils.toDecimal("0xa"));
+// 10 (number)
+
+console.log(web3.utils.hexToNumberString("0xa"));
+// 10 (string)
+
+console.log(web3.utils.toBigInt("0xa")); 
+// 10n (bigint)
+```
+
+### Hashing Functions
+
+```js
+// both will return undefined if an empty string is passed as an argument
+console.log(web3.utils.sha3("hello web3"));
+// 0x6c171485a0138b7b0a49d72b570e1d9c589d42a79ae57329d90671d1ac702d74
+
+console.log(web3.utils.soliditySha3({ type: "string", value: "hello web3" }));
+// 0x6c171485a0138b7b0a49d72b570e1d9c589d42a79ae57329d90671d1ac702d74
+```
+
+### Addresses
+
+```js
+// isAddress() is deprecated so we can use toCheckSumAddress()
+// to see if the hex string we are passing is a correct ethereum address
+
+// passing an address with all characters lowercase
+console.log(web3.utils.toChecksumAddress("0xa3286628134bad128faeef82f44e99aa64085c94"));
+// 0xA3286628134baD128faeef82F44e99AA64085C94
+
+// passing an wrong address
+console.log(web3.utils.toChecksumAddress("0xa3286628134bad128faeef82f44e99aa64085c9"));
+// InvalidAddressError: Invalid value given "0xa286628134bad128faeef82f44e99aa64085c94". Error: invalid ethereum address.
+```
+
+### Packing and Padding
+
+```js
+// same as abi.encodePacked() in solidity (must be strings)
+// converts everything to hex and packs everything without padding
+console.log(web3.utils.encodePacked("1", "1", "1"));
+// 0x313131
+
+
+// it will convert the number `10` to hex('a') and add 0s until it's 32 characters long
+// the third argument will be the one that will fill/pad the whole hex string, in this case is '0'
+console.log(web3.utils.padRight(10, 32, 0));
+// 0xa0000000000000000000000000000000
+
+console.log(web3.utils.rightPad(10, 32, 0));
+// 0xa0000000000000000000000000000000
+
+console.log(web3.utils.padLeft(10, 32, 0));
+// 0x0000000000000000000000000000000a
+
+console.log(web3.utils.leftPad(10, 32, 0));
+// 0x0000000000000000000000000000000a
+```
+
+### Compare Block Numbers
+
+```js
+// accepts numbers and formats as well
+console.log(web3.utils.compareBlockNumbers("pending", "latest"));
+// 1
+
+console.log(web3.utils.compareBlockNumbers("latest", "pending"));
+// -1
+
+console.log(web3.utils.compareBlockNumbers("latest", "latest"));
+// 0
+
+console.log(web3.utils.compareBlockNumbers(2, 2));
+// 0
+```
+