Payment Address Normalization

Overview

Mechanism and important distinctions

Different chains represent addresses differently. Some use base58-style encodings, some use bech32 variants, and EVM-style chains often use hexadecimal addresses with optional mixed-case checksum information. Normalization may safely remove accidental surrounding whitespace for one format while silently corrupting a case-sensitive format for another. Therefore an address parser needs an explicit network context before it transforms user input.

The order matters: select or validate the network, parse according to its specification, check any checksum and only then produce a canonical internal representation. Never use normalization to guess whether a user intended one chain rather than another. Preserve the original string beside the canonical bytes for debugging. An address may be syntactically valid and still be unusable for the desired asset or not belong to the intended merchant.

Consider a pasted string from a QR code that includes a URI prefix, an address and a requested amount. A parser must first interpret the URI scheme and isolate its components; it should not run string substitutions on the whole payload and call the result an address. Validate memos and network selectors separately because removing them can send funds successfully while leaving the merchant unable to attribute the payment.

Related glossary concepts

Crypto Payment Address Screening; Payment Address Checksum; Crypto Payment Address Poisoning

Primary reference

ERC-55: Mixed-case checksum address encoding