From df594c9d189e837afe4ea36edad362c15462cf65 Mon Sep 17 00:00:00 2001
From: Muhammad Altabba <24407834+Muhammad-Altabba@users.noreply.github.com>
Date: Fri, 5 Jan 2024 10:55:10 +0100
Subject: [PATCH] add section at migration guide for toHex (#6683)

---
 .../1.x/web3_utils_migration_guide.md          | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/docs/guides/web3_upgrade_guide/1.x/web3_utils_migration_guide.md b/docs/docs/guides/web3_upgrade_guide/1.x/web3_utils_migration_guide.md
index 1b7410aa197..04886c52351 100644
--- a/docs/docs/guides/web3_upgrade_guide/1.x/web3_utils_migration_guide.md
+++ b/docs/docs/guides/web3_upgrade_guide/1.x/web3_utils_migration_guide.md
@@ -29,6 +29,24 @@ web3.utils.toWei('0.1');
 web3.utils.toWei('0.1', 'ether');
 ```
 
+## Conversion to Hex
+
+The `toHex` behave exactly the same in both v1.x and 4.x, except for a string that contains only numbers. In 1.x if a number was provided inside a string like `123` it used to be treated as a number. While in 4.x it will be treated as a string, except if it was prefixed with `0x`. For more clarity, check below: 
+
+```ts
+// 1.x
+new Web3().utils.toHex(0x1) // returns  0x1
+new Web3().utils.toHex('0x1') // returns  0x1
+new Web3().utils.toHex(1) // returns  0x1
+new Web3().utils.toHex('1') // returns  0x1
+
+// 4.x
+new Web3().utils.toHex(0x1) // returns  0x1
+new Web3().utils.toHex('0x1') // returns  0x1
+new Web3().utils.toHex(1) // returns  0x1
+new Web3().utils.toHex('1') // returns  0x31
+```
+
 ## Validation functions
 
 Validation functions has been moved to the new package `web3-validator`. Actually, you can still import them from `web3-util`. But they are marked as "deprecated" and you are encouraged to import them from `web3-validator`.