@adraffy/ens-normalize

What is @adraffy/ens-normalize?

@adraffy/ens-normalize is an npm package designed to normalize Ethereum Name Service (ENS) names. It ensures that ENS names are in a consistent format, which is crucial for avoiding ambiguities and ensuring compatibility across different systems.

What are @adraffy/ens-normalize's main functionalities?

Normalization

This feature allows you to normalize an ENS name to ensure it is in a consistent format. The code sample demonstrates how to normalize the ENS name 'example.eth'.

const { normalize } = require('@adraffy/ens-normalize');
const normalized = normalize('example.eth');
console.log(normalized);

Validation

This feature allows you to validate an ENS name to check if it conforms to the expected format. The code sample demonstrates how to validate the ENS name 'example.eth'.

const { validate } = require('@adraffy/ens-normalize');
const isValid = validate('example.eth');
console.log(isValid);

Unicode Handling

This feature allows you to convert Punycode-encoded ENS names to their Unicode equivalents. The code sample demonstrates how to convert the Punycode-encoded ENS name 'xn--exmple-cua.eth' to its Unicode equivalent.

const { toUnicode } = require('@adraffy/ens-normalize');
const unicodeName = toUnicode('xn--exmple-cua.eth');
console.log(unicodeName);

Other packages similar to @adraffy/ens-normalize

eth-ens-namehash

The eth-ens-namehash package is another tool for generating ENS namehashes. It includes some basic normalization features but is primarily focused on the namehashing process. It is less comprehensive in normalization compared to @adraffy/ens-normalize.

punycode

The punycode package provides utilities for converting between Unicode and Punycode, which is useful for handling internationalized domain names (IDNs). While it does not specifically target ENS names, it can be used in conjunction with other packages to handle Unicode normalization.

README

ens-normalize.js

1-file, 1-function, 1-argument, 0-dependancy Compact ES6 Ethereum Name Service (ENS) Name Normalizer.

• Uses Unicode v14.0.0 + UTS-51 + UTS-46 w/IDNA2008
• Handles ContextJ/ContextO
• Handles CheckBidi
• Passes 100% IDNATestV2 (Using uts46 Payload)
• Handles Emoji ZWJ Sequences
• Passes 100% Emoji Sequences (Using uts51 Payload)
• Passes 100% NormalizationTests
• Handles Punycode, adapted from mathiasbynens/punycode.js

---

• Demo: Resolver
• Demo: Display Name
• Generated Report vs eth-ens-namehash Latest version • Prior (IDNA2003)

import {ens_normalize} from '@adraffy/ens-normalize';
// browser: 
// 'https://unpkg.com/@adraffy/ens-normalize@latest/dist/ens-normalize.min.js'
// alternatives:
// - ens-normalize-xbidi.min.js (no CheckBidi)
// - ens-normalize-xnfc.min.js (use default String.normalize)
// see: /dist/ for more

// Primary API: string -> string
let normalized = ens_normalize('🚴‍♂️.eth'); // throws 
// ready for namehash

// errors:
// - not a string
// - contains disallowed character
// - punycode error
// - label has double-hyphen
// - label starts/ends with hyphen
// - label starts with combining mark
// - character out of context
// - bidi error

// note: does not enforce .eth TLD 3-character minimum

Instead of exposing an IDNA-like API (is_valid(), get_mapped(), etc.), this library converts names to tokens for use in providing a better UX for end-users. Also, see: parts.js submodule below.

// Secondary API: string -> [{tokens,...}]
// turn a name into a list of tokens
let tokens = ens_tokenize('R💩\uFE0Fa\xAD./'); // never throws
// [
//   {m: [0x72], u:[0x52]},              // mapped u:"R" -> m:"r"
//   {e: [0x1F4A9], u:[0x1F4A9,0xFE0F]}, // emoji: u:"💩" -> e:"💩"
//   {v: [0x61]},                        // valid: "a"
//   {i: 0xAD},                          // ignored: \xAD
//   {},                                 // stop: "."
//   {d: 0x2F}                           // disallowed: "/"
// ]

Independent submodules:

// Unicode Normalized Forms
// see: build/nf.js (algo)
// see: build/lib-nf.js (api)
// see: https://adraffy.github.io/ens-normalize.js/test/report-nf.html
import {nfc, nfd} from 'dist/nf.min.js';
// {nfc,nfd}(string): string

// CheckBidi 
// see: build/bidi.js (algo)
// see: build/lib-bidi.js (api)
// see: https://www.rfc-editor.org/rfc/rfc5893.html#section-2
import {check_bidi, is_bidi_domain_name} from 'dist/bidi.min.js';
// is_bidi_domain_name(string): bool
// check_bidi(string) throws

// Parts -- generate HTML from parsed tokens
// see: build/lib-parts.js (api)
// see: https://adraffy.github.io/ens-normalize.js/test/report-emoji.html
import {dom_from_tokens, use_default_style} from 'dist/parts.min.js';
// use_default_style(); installs a stylesheet
// DOMNode.append(dom_from_tokens(ens_tokenize('raffy.eth')));

Building

• Clone to access build/. The actual source is in build/lib-normalize.js. You can run this file directly.
• Run node build/unicode.js download to download data from unicode.org.
• Run node build/unicode.js parse to parse those files into JSON files.
• Run node build/build-tables.js all to build compressed rule payloads.
• Run npm run test-source to test build/lib-normalize.js.
• Run npm run build or node build/build.js all to inject the compressed tables into the source template and create the readable and minified dist/ files.
• Run npm run test-build to test dist/ens-normalize.js.