diff --git a/docs/docs/guides/advanced/_category_.yml b/docs/docs/guides/advanced/_category_.yml index 2abe6bbdc6a..dab551977cf 100644 --- a/docs/docs/guides/advanced/_category_.yml +++ b/docs/docs/guides/advanced/_category_.yml @@ -2,4 +2,4 @@ label: '🧠 Advanced' collapsible: true collapsed: true link: null -position: 12 \ No newline at end of file +position: 14 \ No newline at end of file diff --git a/docs/docs/guides/events_subscriptions/_category_.yml b/docs/docs/guides/events_subscriptions/_category_.yml index 528836749db..2f13d5222b4 100644 --- a/docs/docs/guides/events_subscriptions/_category_.yml +++ b/docs/docs/guides/events_subscriptions/_category_.yml @@ -2,4 +2,4 @@ label: 'πŸ”” Events subscription' collapsible: true collapsed: true link: null -position: 6 \ No newline at end of file +position: 7 \ No newline at end of file diff --git a/docs/docs/guides/feedback/index.md b/docs/docs/guides/feedback/index.md index f096d471236..228003d5a6e 100644 --- a/docs/docs/guides/feedback/index.md +++ b/docs/docs/guides/feedback/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 17 sidebar_label: 'πŸ—£οΈ Feedback' --- diff --git a/docs/docs/guides/glossary/index.md b/docs/docs/guides/glossary/index.md index e8962c28966..39294de39ed 100644 --- a/docs/docs/guides/glossary/index.md +++ b/docs/docs/guides/glossary/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 18 sidebar_label: 'πŸ“– Glossary' title: Glossary --- diff --git a/docs/docs/guides/hardhat_tutorial/_category_.yml b/docs/docs/guides/hardhat_tutorial/_category_.yml index dfd158abb00..191ad0faa29 100644 --- a/docs/docs/guides/hardhat_tutorial/_category_.yml +++ b/docs/docs/guides/hardhat_tutorial/_category_.yml @@ -2,4 +2,4 @@ label: '⛑️ Hardhat Tutorial' collapsible: true collapsed: true link: null -position: 2 +position: 3 diff --git a/docs/docs/guides/migration_from_other_libs/_category_.yml b/docs/docs/guides/migration_from_other_libs/_category_.yml index dc10487c990..665581166bc 100644 --- a/docs/docs/guides/migration_from_other_libs/_category_.yml +++ b/docs/docs/guides/migration_from_other_libs/_category_.yml @@ -2,4 +2,4 @@ label: 'πŸ”„ Migration Guides' collapsible: true collapsed: true link: null -position: 11 \ No newline at end of file +position: 12 \ No newline at end of file diff --git a/docs/docs/guides/smart_contracts/_category_.yml b/docs/docs/guides/smart_contracts/_category_.yml index 6bf6e7694db..fcbba9574a5 100644 --- a/docs/docs/guides/smart_contracts/_category_.yml +++ b/docs/docs/guides/smart_contracts/_category_.yml @@ -2,4 +2,4 @@ label: 'πŸ“œ Smart Contracts' collapsible: true collapsed: true link: null -position: 4 \ No newline at end of file +position: 6 \ No newline at end of file diff --git a/docs/docs/guides/wagmi_usage/_category_.yml b/docs/docs/guides/wagmi_usage/_category_.yml index a314e00849b..90b55da4312 100644 --- a/docs/docs/guides/wagmi_usage/_category_.yml +++ b/docs/docs/guides/wagmi_usage/_category_.yml @@ -2,4 +2,4 @@ label: 'πŸ”„ Wagmi usage' collapsible: true collapsed: true link: null -position: 11 +position: 13 diff --git a/docs/docs/guides/wallet/_category_.yml b/docs/docs/guides/wallet/_category_.yml index d96e556347b..6b079975e01 100644 --- a/docs/docs/guides/wallet/_category_.yml +++ b/docs/docs/guides/wallet/_category_.yml @@ -2,4 +2,4 @@ label: 'πŸ”‘ Wallet and Accounts ' collapsible: true collapsed: true link: null -position: 3 \ No newline at end of file +position: 5 \ No newline at end of file diff --git a/docs/docs/guides/web3_config/_category_.yml b/docs/docs/guides/web3_config/_category_.yml index 4c1d5ddbd90..dbe4222696b 100644 --- a/docs/docs/guides/web3_config/_category_.yml +++ b/docs/docs/guides/web3_config/_category_.yml @@ -2,4 +2,4 @@ label: 'βš™οΈ Web3 config' collapsible: true collapsed: true link: null -position: 9 \ No newline at end of file +position: 15 \ No newline at end of file diff --git a/docs/docs/guides/web3_eth/_category_.yml b/docs/docs/guides/web3_eth/_category_.yml index f7e09e00d19..197604038d5 100644 --- a/docs/docs/guides/web3_eth/_category_.yml +++ b/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 \ No newline at end of file +position: 8 \ No newline at end of file diff --git a/docs/docs/guides/web3_plugin_guide/_category_.yml b/docs/docs/guides/web3_plugin_guide/_category_.yml index daec6ebe046..42237f7ea38 100644 --- a/docs/docs/guides/web3_plugin_guide/_category_.yml +++ b/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 \ No newline at end of file +position: 2 \ No newline at end of file diff --git a/docs/docs/guides/web3_providers_guide/_category_.yml b/docs/docs/guides/web3_providers_guide/_category_.yml index 3b85fe4849e..f426dbedf9a 100644 --- a/docs/docs/guides/web3_providers_guide/_category_.yml +++ b/docs/docs/guides/web3_providers_guide/_category_.yml @@ -2,4 +2,4 @@ label: 'πŸ”Œ Providers' collapsible: true collapsed: true link: null -position: 2 \ No newline at end of file +position: 4 \ No newline at end of file diff --git a/docs/docs/guides/web3_upgrade_guide/_category_.yml b/docs/docs/guides/web3_upgrade_guide/_category_.yml index e3022cfe8fd..aeab3125b26 100644 --- a/docs/docs/guides/web3_upgrade_guide/_category_.yml +++ b/docs/docs/guides/web3_upgrade_guide/_category_.yml @@ -2,4 +2,4 @@ label: '⬆️ Upgrading' collapsible: true collapsed: true link: null -position: 10 \ No newline at end of file +position: 11 \ No newline at end of file diff --git a/docs/docs/guides/web3_utils_module/_category_.yml b/docs/docs/guides/web3_utils_module/_category_.yml new file mode 100644 index 00000000000..95a9529cfce --- /dev/null +++ b/docs/docs/guides/web3_utils_module/_category_.yml @@ -0,0 +1,5 @@ +label: 'πŸ“¦ Web3 Utils module' +collapsible: true +collapsed: true +link: null +position: 10 \ No newline at end of file diff --git a/docs/docs/guides/web3_utils_module/mastering_web3-utils.md b/docs/docs/guides/web3_utils_module/mastering_web3-utils.md new file mode 100644 index 00000000000..7bad9e3b396 --- /dev/null +++ b/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 +``` +