Normalising Wallet Addresses Without Losing Identity
Normalise wallet addresses for comparison while preserving display checksums, network context and the different encoding rules of non-EVM chains.
Overview
When translating these concepts into an integration, keep the scope described by the normalized transactions api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Address normalisation is chain-specific. A rule suitable for EVM hexadecimal addresses can corrupt an identifier on another network. Store a canonical comparison form alongside the original or preferred display form.
Choose the network before the normaliser
For EVM address comparison, validate the byte length and hexadecimal encoding before applying a consistent comparison representation. Mixed-case checksum display can provide an additional user-facing check. Other networks can use case-sensitive encodings. Never lower-case every address string in a multi-chain database merely because that worked for one EVM integration.
Worked example: duplicate EVM displays
Two valid display forms refer to the same 20-byte EVM address on the same chain. The application groups them under one canonical identity while keeping the checksummed display. The same bytes on another chain remain a different network-scoped account. A cache keyed only by the lower-cased string would incorrectly merge those network views.
Test validation separately from ownership
Reject malformed lengths and unsupported encodings. Test leading zeros, whitespace and a mixed-case checksum error. A syntactically valid address does not prove that the user controls it or that a destination is safe. Keep address parsing, ownership verification and counterparty labels as distinct operations with separate evidence.
A practical acceptance test
Test two valid EVM display forms, a malformed address and a case-sensitive identifier from another network. Only the equivalent EVM identities should merge under the EVM parser. Keep the same bytes on different chains separate. This fixture catches a global lower-case normaliser that accidentally changes non-EVM identities or merges cross-chain cache entries.
Questions about the topic
Frequently asked questions
Can every chain address be lower-cased?
No. Some address encodings are case-sensitive.
Does a checksum prove ownership?
No. It helps validate representation, not control of the account.
Standards & technical documentation
