From c96211b12e2b052dfbe3ae3c7b26ad00217de658 Mon Sep 17 00:00:00 2001
From: gomes <17035424+gomesalexandre@users.noreply.github.com>
Date: Mon, 17 Aug 2026 12:45:04 +0200
Subject: [PATCH] docs: clarify isHexChecksumAddress checks shape, not the
 checksum

isHexChecksumAddress's doc said it checks for a "valid hex checksum
address", but it only tests the shape - 0x followed by 40 hex characters,
upper- or lower-case (HEX_CHECKSUM_ADDRESS_REGEX). It never verifies the
ERC-55 checksum, so a non-checksummed (e.g. all-lowercase) address passes.

Correct the JSDoc to describe what it actually validates and point to
getChecksumAddress for computing the checksum. No behavior or name change.

closes #250
---
 src/hex.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/hex.ts b/src/hex.ts
index 7359225cc..427834c1a 100644
--- a/src/hex.ts
+++ b/src/hex.ts
@@ -61,10 +61,17 @@ export function isHexAddress(value: unknown): value is Hex {
 }
 
 /**
- * Check if a string is a valid hex checksum address.
+ * Check if a string has the shape of a hex address, allowing the mixed case
+ * used by ERC-55 checksummed addresses.
+ *
+ * This only validates the shape - "0x" followed by 40 hexadecimal characters,
+ * upper- or lower-case. It does NOT verify the ERC-55 checksum, so a
+ * non-checksummed (for example all-lowercase) address still passes. Use
+ * {@link getChecksumAddress} to compute the checksummed form.
  *
  * @param value - The value to check.
- * @returns Whether the value is a valid hex checksum address.
+ * @returns Whether the value has the shape of a (possibly checksummed) hex
+ * address. The ERC-55 checksum itself is not verified.
  */
 export function isHexChecksumAddress(value: unknown): value is Hex {
   return isString(value) && HEX_CHECKSUM_ADDRESS_REGEX.test(value);