ENSIP-15 defines the mandatory normalization standard for all ENS names before they are hashed and stored in the registry. This standard replaces the ad-hoc UTS-46 normalization previously used, which introduced inconsistencies across client implementations. The core operational goal is to ensure that any two implementations, given the same user-facing name string, will produce the identical normalized form and therefore the identical namehash. Failure to implement this standard correctly creates a direct vector for homoglyph attacks, where visually identical names resolve to different nodes, and causes interoperability failures between wallets, dapps, and exchanges that rely on consistent name resolution.
Protocols
ENSIP-15 Normalization Implementation Guide
Documents the operational impact of the ENSIP-15 name normalization standard. Provides guidance for client and SDK developers on implementing the normalization algorithm correctly to prevent homoglyph attacks and ensure consistent name hashing across all platforms.
introduction
NORMALIZATION STANDARD
Introduction
Operational guidance for implementing ENSIP-15 name normalization to prevent homoglyph attacks and ensure deterministic name hashing across all platforms.
The standard specifies a multi-stage algorithm: first, the input string is split into labels by the '.' separator; second, each label is processed through a disallowed character check, a Unicode map transformation, a Unicode Normalization Form C (NFC) step, and finally a validation pass against a defined set of whole-label rules. The implementation guide provides the canonical ens-normalize.js library as a reference, but client developers in non-JavaScript environments (such as mobile wallets, hardware signers, or backend services) must port this logic precisely. The most common failure modes involve incorrect handling of zero-width joiners, emoji sequences, or confusable characters that pass NFC but are explicitly disallowed by the ENSIP-15 disallowed character set.
For operators and integrators, the immediate impact is a hard requirement to migrate any name processing pipeline from UTS-46 to an ENSIP-15-compliant implementation. This affects registration flows, address resolution in wallets, deposit address validation on exchanges, and subname management in L2 gateways. Chainscore Labs can assist teams with a formal review of their normalization implementation, including differential testing against the reference library and analysis of edge cases that could lead to silent resolution failures or security gaps in production systems.
ENSIP-15 NORMALIZATION IMPLEMENTATION
Quick Facts
Operational impact and integration requirements for the ENSIP-15 name normalization standard to prevent homoglyph attacks and ensure consistent name hashing.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
Name Hashing | Names must be normalized before hashing to ensure consistent namehash derivation across all platforms. | Wallet developers, SDK maintainers, dapp frontend teams | Verify your namehash derivation pipeline uses an ENSIP-15 compliant library. Inconsistent hashing breaks name resolution. |
Homoglyph Security | Visually confusable characters are detected and disallowed, preventing phishing attacks via lookalike names. | Exchanges, custodians, DeFi frontends | Audit UI rendering of ENS names to ensure normalized forms are displayed. Do not display unnormalized user input. |
Client Libraries | Libraries like @adraffy/ens-normalize.js provide the canonical implementation. Older normalization methods are incompatible. | SDK developers, wallet teams | Migrate from deprecated normalization libraries (e.g., eth-ens-namehash) to the canonical ENSIP-15 implementation immediately. |
Offchain Gateways | CCIP-Read gateways serving wildcard or subname data must normalize names before processing resolution requests. | Gateway operators, L2 protocol teams | Update gateway logic to reject or normalize non-compliant names. Serving data for unnormalized names creates a split-brain resolution state. |
Subgraph Indexing | Indexed name data must use the normalized form as the canonical key to maintain consistency with onchain state. | Data analysts, portfolio trackers, indexer operators | Reprocess historical data to align with ENSIP-15 normalized labels. Queries using unnormalized labels will miss records. |
Smart Contract Input | Contracts accepting ENS names as input (e.g., registrar controllers) should validate normalization on-chain to prevent storage of invalid names. | Protocol developers, registrar operators | Integrate on-chain normalization validation in contracts that store or process user-supplied ENS names to reject non-compliant input at the protocol level. |
User Experience | Users entering names with confusable characters will encounter validation errors. Frontends must provide clear error messaging. | Frontend developers, UX designers | Implement client-side normalization checks with user-friendly error messages explaining why a name was rejected. Do not silently transform user input. |
technical-context
NORMALIZATION ALGORITHM REQUIREMENTS
Technical Mechanism
The operational core of ENSIP-15 is a deterministic algorithm that transforms human-readable names into a canonical byte sequence for hashing, eliminating visual ambiguity that enables homoglyph attacks.
ENSIP-15 mandates a specific normalization process applied to a name before it is hashed and stored in the ENS registry. The algorithm first applies Unicode Normalization Form KC (NFKC) to decompose and recompose characters into a compatible form, collapsing visually similar sequences. It then applies a context-aware validation pass that strips disallowed characters, enforces rules on combining marks, and handles edge cases like emoji sequences and zero-width joiners. The output is a canonical UTF-8 byte string that is hashed with keccak256 to produce the namehash stored onchain. Any deviation in this process—whether in a wallet, dapp, or offchain gateway—produces a different namehash, causing the name to resolve to a different node or fail to resolve entirely.
The primary risk addressed by this standard is the homoglyph attack, where an attacker registers a name that is visually indistinguishable from a legitimate one but has a different underlying byte representation. For example, replacing the ASCII 'a' (U+0061) with the Cyrillic 'а' (U+0430) produces a string that looks identical in many fonts but hashes to a completely different ENS node. ENSIP-15's validation rules explicitly ban such confusable characters and entire scripts that are sources of ambiguity. For integrators, the critical operational requirement is that normalization must be applied identically at two points: when a user registers a name and when any resolver looks it up. Inconsistent normalization between a dapp's frontend and a wallet's resolution library is a direct cause of interoperability failures.
Implementing this algorithm correctly requires using a library that has been verified against the ENSIP-15 test vectors, such as the @adraffy/ens-normalize JavaScript package or equivalent implementations in other languages. Developers must not rely on general-purpose Unicode libraries or naive NFKC alone, as the ENSIP-15 ruleset includes custom filtering logic beyond standard normalization. For teams operating CCIP-Read gateways, the gateway must normalize names in its resolution path using the exact same algorithm as client libraries, or it will return null for valid names. Chainscore Labs can audit an integration's normalization pipeline to verify byte-level consistency with the canonical implementation, preventing the silent resolution failures and phishing vulnerabilities that arise from subtle implementation errors.
ENSIP-15 NORMALIZATION IMPACT
Affected Actors
Wallet Integration Risk
Wallet teams face the most direct user-impact risk from incorrect ENSIP-15 implementation. If a wallet's normalization logic differs from the canonical standard, users will see inconsistent name representations and may be tricked into sending funds to visually similar but incorrectly hashed names.
Action Items:
- Audit your name input sanitization pipeline against the ENSIP-15 algorithm.
- Verify that
namehashoutputs match the reference implementation for edge cases involving zero-width characters and mixed-script labels. - Implement client-side warnings when a user attempts to interact with a name containing confusable characters.
- Test resolution flows with known homoglyph attack vectors to ensure your UI displays the normalized, not the raw, label.
Failure to align creates a phishing vector where an attacker can register a confusable name that your wallet resolves to a different address than other compliant wallets.
implementation-impact
ENSIP-15 NORMALIZATION
Implementation Impact Areas
Operational areas affected by the adoption of the ENSIP-15 name normalization standard. Teams must update their software to prevent homoglyph attacks and ensure consistent name hashing across all platforms.
02
Interoperability and Resolution Consistency
Inconsistent normalization creates a critical interoperability failure. If a dapp resolves a name using ENSIP-15 but a user's wallet uses an older standard, the wallet will fail to find the resolver or display incorrect records. This can lead to users sending funds to the wrong address or interacting with a different name than intended. All interfaces in the resolution supply chain must upgrade in lockstep to prevent a fragmented user experience.
03
Phishing and Homoglyph Attack Surface
The primary security goal of ENSIP-15 is to eliminate homoglyph attacks where visually identical characters from different scripts are used to create deceptive names. Implementation directly reduces this attack surface. However, a partial rollout is more dangerous than no rollout, as it creates a false sense of security. Security teams must audit that normalization is applied universally across their frontend, backend, and smart contract interactions.
04
Offchain Gateway and CCIP-Read Processing
CCIP-Read gateways that serve wildcard records or manage subname registries must apply ENSIP-15 normalization to incoming name queries before performing a lookup. If a gateway normalizes a name differently than the requesting client, the gateway's response will be for an incorrect namehash, causing a silent failure. Gateway operators must update their server-side processing logic and deploy the new code in coordination with client-side library updates.
05
Subgraph and Indexer Data Integrity
Indexers like the ENS subgraph that process registration and transfer events must re-evaluate how they store and query names. If an indexer normalizes names before storing them, a protocol change will create a mismatch with historical data. Teams must implement a migration strategy to re-normalize stored names or clearly version their datasets to prevent data corruption and incorrect ownership displays in analytics dashboards.
06
Exchange and Custodian Deposit Flows
Centralized exchanges and custodians that accept ENS names for deposits must update their resolution pipeline. An outdated normalization library can cause a deposit to be routed to an incorrect blockchain address. This presents a direct risk of fund loss. Operations teams must verify their internal address resolution services are using an ENSIP-15 compliant library and conduct integration tests against the latest ENSJS release before deploying to production.
ENSIP-15 NORMALIZATION IMPLEMENTATION RISKS
Risk Matrix
Operational risks introduced by incorrect or inconsistent implementation of the ENSIP-15 name normalization standard across clients, wallets, and services.
| Risk | Failure mode | Severity | Mitigation |
|---|---|---|---|
Homoglyph phishing | Two visually identical names (e.g., using Cyrillic 'а' vs ASCII 'a') resolve to different nodes, enabling impersonation attacks. | Critical | Implement the exact ENSIP-15 algorithm. Use the official Solidity and JavaScript reference libraries without modification. |
Interoperability failure | Wallet A normalizes a name differently than Dapp B, causing one to show a valid name while the other rejects it or resolves a different address. | High | All integrators must use the same normalization library version. Conduct cross-client testing between major wallets, exchanges, and dapps before release. |
Silent fund loss | An exchange or custodian uses a non-standard normalizer. A user deposits to a normalized name, but the exchange resolves a different node hash, sending funds to an attacker-controlled address. | Critical | Exchanges must verify their normalization logic against the canonical ENSIP-15 test vectors. Implement integration tests that compare node hashes with the official ENS resolver. |
Invalid name rejection | A valid ENS name registered before ENSIP-15 adoption is incorrectly rejected by a strict normalizer, preventing legitimate users from managing or sending to their names. | Medium | Ensure backward compatibility by treating names that fail normalization as valid labels but preventing new registrations. Use the |
CCIP-Read gateway mismatch | An offchain gateway serving L2 names normalizes requests differently than the client, causing the gateway to return 'not found' for a name that the client believes is valid. | High | Gateway operators must verify their normalization logic matches the client library version used by major wallets. Add normalization versioning to gateway response metadata. |
Indexer data corruption | A subgraph or indexer normalizes names before hashing, creating a divergent dataset where some names are indexed under incorrect node hashes, breaking portfolio and analytics tools. | Medium | Data teams must use the same normalization library as the protocol. Re-index historical data after any normalization library upgrade to ensure consistency. |
Smart contract logic error | A DeFi protocol or NFT marketplace implements onchain normalization for ENS names but uses a gas-optimized algorithm that deviates from the standard, locking user assets. | High | Do not implement custom onchain normalizers. Use the canonical, audited Solidity library. Fuzz test against the official JavaScript implementation's output. |
Governance dispute | The ENS DAO proposes a change to the normalization standard, creating a fork risk where some clients adopt the new rules while others remain on the old standard. | Medium | Monitor ENS DAO governance for normalization-related proposals. Plan a coordinated upgrade window with other major ecosystem players to prevent fragmentation. |
ENSIP-15 NORMALIZATION READINESS
Implementation Checklist
A step-by-step operational checklist for client, SDK, and application developers to safely implement the ENSIP-15 name normalization standard. Inconsistent normalization creates interoperability failures, silent resolution mismatches, and homoglyph phishing risks across wallets, exchanges, and dapps.
Confirm that your project uses a canonical ENSIP-15 implementation library such as @adraffy/ens-normalize rather than a custom or outdated normalization routine. Check the exact version pin against the latest audited release.
- Why it matters: Using different normalization libraries or versions leads to hash mismatches. A name that normalizes to one hash in your system may resolve to a different hash on-chain, causing failed lookups or fund loss.
- Readiness signal: All dependencies in
package.jsonor equivalent manifest match the version range recommended in the official ENSIP-15 specification and pass the standard test vectors.
resource-links
CANONICAL REFERENCES
Source Resources
Primary resources for teams implementing ENSIP-15 name normalization in wallets, SDKs, exchanges, registrars, indexers, and ENS-aware applications.
Chains We Build On
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
IMPLEMENTATION FAQ
Frequently Asked Questions
Common operational questions from teams implementing ENSIP-15 normalization in clients, wallets, and SDKs.
Inconsistent normalization across clients creates a direct interoperability failure. If Wallet A normalizes a name differently than Wallet B, they will compute different namehashes. This means a user can register a name in one wallet that appears to resolve correctly, but when they try to interact with it from another platform, the namehash won't match and the name will appear unregistered. This also opens a vector for homoglyph attacks where visually identical names resolve to different addresses depending on the client implementation. The canonical normalization algorithm in ENSIP-15 is the only way to ensure all platforms derive the same namehash for the same human-readable input.
Trusted by Industry Leaders
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
L
Lee Erswell
CEO, Telos Foundation
how to get started
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
01
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
02
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
03
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
04
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Explore More Solutions
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Book a Call
Start a build
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.