ens-normalize.js

0-dependency Ethereum Name Service (ENS) Name Normalizer.

npm i @adraffy/ens-normalize ✓

* 🏛️ Follows ENSIP-15: ENS Name Normalization Standard
* Unicode: 17.0.0 • CLDR: 47
* Other implementations:
* Python — namehash/ens-normalize-python
* Rust — sevenzing/ens-normalize-rs
* Zig — evmts/z-ens-normalize
* C# — adraffy/ENSNormalize.cs
* Java — adraffy/ENSNormalize.java
* Swift – adraffy/ENSNormalize.swift
* Go — adraffy/go-ens-normalize
* Swift – adraffy/ENSNormalize.swift
* Prior implementation:
* Javascript — ensdomains/eth-ens-namehash
* Breakdown Reports from ENSIP-1
* ✅️ Passes 100% ENSIP-15 Validation Tests
* ✅️ Passes 100% Unicode Normalization Tests
* Minified File Sizes:
* 29KB — native NFC via nf-native.js using String.normalize() ⚠️
* 38KB Default — custom NFC via nf.js
44KB Everything!* — custom NFC + sub-libraries: parts.js, utils.js
* Included Apps:
* Resolver Demo ⭐
* Supported Emoji
* Character Viewer
* Confused Explainer
* Related Projects:
* Recent .eth Registrations • Renews • Expirations
* Label Database • Labelhash⁻¹ • Brute-force
* Emoji Frequency Explorer
* adraffy/punycode.js • Punycode Coder
* adraffy/keccak.js • Keccak Hasher
* adraffy/emoji.js • Emoji Parser
* More links at bottom of Resolver Demo

``js
import {ens_normalize} from '@adraffy/ens-normalize'; // or require()
// browser: https://cdn.jsdelivr.net/npm/@adraffy/ens-normalize@latest/dist/index.min.mjs (or .cjs)

// ALL errors thrown by this library are safe to print
// - characters are shown as {HEX} if should_escape()
// - potentially different bidi directions inside "quotes"
// - 200E is used near "quotes" to prevent spillover
// - an "error type" can be extracted by slicing up to the first (:)
// - labels are middle-truncated with ellipsis (…) at 63 cps

// string -> string
// throws on invalid names
// output ready for namehash
let normalized = ens_normalize('RaFFY🚴‍♂️.eTh');
// => "raffy🚴‍♂.eth"

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

Format names with fully-qualified emoji:
`js
// works like ens_normalize()
// output ready for display
let pretty = ens_beautify('1⃣2⃣.eth');
// => "1️⃣2️⃣.eth"

// note: normalization is unchanged:
// ens_normalize(ens_beautify(x)) == ens_normalize(x)
`

Normalize name fragments for substring search:
`js
// these fragments fail ens_normalize()
// but will normalize fine as fragments
let frag1 = ens_normalize_fragment('AB--'); // expected error: label ext
let frag2 = ens_normalize_fragment('\u{303}'); // expected error: leading cm
let frag3 = ens_normalize_fragment('οо'); // expected error: mixture
`

Input-based tokenization:
`js
// string -> Token[]
// never throws
let tokens = ens_tokenize('_R💩\u{FE0F}a\u{FE0F}\u{304}\u{AD}./');
// [
// { type: 'valid', cps: [ 95 ] }, // valid (as-is)
// {
// type: 'mapped',
// cp: 82, // input
// cps: [ 114 ] // output
// },
// {
// type: 'emoji',
// input: Emoji(2) [ 128169, 65039 ], // input
// emoji: [ 128169, 65039 ], // fully-qualified
// cps: Emoji(1) [ 128169 ] // output (normalized)
// },
// {
// type: 'nfc',
// input: [ 97, 772 ], // input (before nfc)
// cps: [ 257 ], // output (after nfc)
// tokens0: [ // tokens (before nfc)
// { type: 'valid', cps: [ 97 ] },
// { type: 'ignored', cp: 65039 },
// { type: 'valid', cps: [ 772 ] }
// ],
// tokens: [ // tokens (after nfc)
// { type: 'valid', cps: [ 257 ] }
// ]
// },
// { type: 'ignored', cp: 173 },
// { type: 'stop', cp: 46 },
// { type: 'disallowed', cp: 47 }
// ]

// note: if name is normalizable, then:
// ens_normalize(ens_tokenize(name).map(token => {
// convert valid/mapped/nfc/stop to string
// }).join('')) == ens_normalize(name)
`

Output-based tokenization:
`js
// string -> Label[]
// never throws
let labels = ens_split('💩Raffy.eth_');
// [
// {
// input: [ 128169, 82, 97, 102, 102, 121 ],
// offset: 0, // index of codepoint, not substring index!
// // (corresponding length can be inferred from input)
// tokens: [
// Emoji(2) [ 128169, 65039 ], // emoji
// [ 114, 97, 102, 102, 121 ] // nfc-text
// ],
// output: [ 128169, 114, 97, 102, 102, 121 ],
// emoji: true,
// type: 'Latin'
// },
// {
// input: [ 101, 116, 104, 95 ],
// offset: 7,
// tokens: [ [ 101, 116, 104, 95 ] ],
// output: [ 101, 116, 104, 95 ],
// error: Error('underscore allowed only at start')
// }
// ]
`

Generate a sorted array of (beautified) supported emoji codepoints:
`js
// () -> number[][]
let emojis = ens_emoji();
// [
// [ 2764 ],
// [ 128169, 65039 ],
// [ 128105, 127997, 8205, 9877, 65039 ],
// ...
// ]
`

Determine if a character shouldn't be printed directly:
`js
// number -> bool
should_escape(0x202E); // eg. RIGHT-TO-LEFT OVERRIDE => true
`

Determine if a character is a combining mark:
`js
// number -> bool
is_combining_mark(0x20E3); // eg. COMBINING ENCLOSING KEYCAP => true
`

Format codepoints as print-safe string:
`js
// number[] -> string
safe_str_from_cps([0x300, 0, 32, 97]); // "◌̀{00} a"
safe_str_from_cps(Array(100).fill(97), 4); // "aa…aa" => middle-truncated
`

Build

* git clone this repo, then npm install
* Follow instructions in /derive/ to generate data files
* npm run derive
* spec.json
* nf.json
* nf-tests.json
* npm run make — compress data files from /derive/output/
* include-ens.js
* include-nf.js
* include-versions.js
* Follow instructions in /validate/ to generate validation tests
* npm run validate
* tests.json
* npm run test — perform validation tests
* npm run build — create /dist/
* npm run rebuild — run all the commands above
* npm run order — create optimal group ordering and rebuild again

Security

* Build and compare against include-versions.js
* spec_hash — SHA-256 of spec.json bytes
* ens_hash_base64 — SHA-256 of include-ens.js base64 literal
* nf_hash_base64` — SHA-256 of include-nf.js base64 literal