docs: clarify isHexChecksumAddress checks shape, not the checksum

[gomesalexandre]

closes MetaMask/core#10207

what

isHexChecksumAddress's doc claims 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 = /^0x[0-9a-fA-F]{40}$/u). It never keccak-hashes to verify the ERC-55 checksum, so a non-checksummed (for example all-lowercase) address passes:

isHexChecksumAddress('0x' + 'a'.repeat(40)) // => true, but not a valid ERC-55 checksum

This matches how the function is actually used - in getChecksumAddress, to assert the input address has a valid (mixed-case-allowing) shape before computing the checksum.

how

Corrects the JSDoc to describe what the function actually validates (shape, allowing the mixed case of a checksummed address) and notes it does not verify the ERC-55 checksum, pointing to getChecksumAddress for that. No behavior or name change - a rename/behavior change would be breaking and per the issue thread wants a broader look at how the function is used, so this is scoped to the documentation accuracy the issue calls out.

references

Addresses the "and documented" half of MetaMask/core#10207.

---

Note

Low Risk
JSDoc-only change with no behavior, types, or exports modified.

Overview
Documentation-only fix for isHexChecksumAddress in hex.ts: the JSDoc no longer says it checks a “valid hex checksum address.”

It now states the function only checks address shape (0x plus 40 hex digits, with mixed case allowed for ERC-55-style strings) and explicitly that it does not verify the ERC-55 checksum—e.g. an all-lowercase address can still pass. Readers are directed to getChecksumAddress for producing the checksummed form; actual checksum validation remains isValidChecksumAddress. No runtime or API changes.

^{Reviewed by Cursor Bugbot for commit c4f11f8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cryptodev-2s]

This library has now been migrated into the core monorepo. This PR has been locked and this repo will be archived shortly. Going forward, releases of this library will only include changes made in the core repo.

• Please push this branch to core and open a new PR there.
• Optionally, add a link pointing to the discussion in this PR to provide context.

Tracked in MetaMask/core#10207.