Unknown Labels

The Problem: Unknown Labels

When querying indexed ENS names, you may encounter labels represented as Encoded LabelHashes like [428...b0b] instead of human-readable strings.

An Unknown Label is a Label that is known to exist, but where only the LabelHash of the label is known, not the human-readable string. These unknown labels are represented by ENS indexers as encoded labelhashes using the format [{LabelHash}].

Unknown labels are an unfortunate user experience issue in the ENS ecosystem. They can make names difficult to read, understand, and work with in applications.

ENSRainbow serves the goal of minimizing the number of unknown labels that exist, and therefore minimizing the probability that users experience interacting with them.

Format: Encoded LabelHash

When an unknown label is encountered, it is represented as an Encoded LabelHash in the format [{labelhash}], where {labelhash} is the 64-character hexadecimal representation of the labelhash (without the 0x prefix).

Examples:

• vitalik.eth — a normalized name with known labels
• [731f7025b488151de311c24abc1f27f02940bde412246fbdb3dea0d4f0663b22].eth — a name with an unknown label encoded as a labelhash, followed by the known label eth
• [731f7025b488151de311c24abc1f27f02940bde412246fbdb3dea0d4f0663b22].[af2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc].eth — a name with multiple unknown labels, each encoded as a labelhash

Important: Labels formatted as encoded labelhashes need to be carefully interpreted depending on the context as either literal labels or interpreted labels. ENSNode (unlike the ENS Subgraph) guarantees that all labels it returns are interpreted labels so long as ENSNode’s SUBGRAPH_COMPAT is not activated (off by default).

What Causes Unknown Labels?

Unknown labels arise from the fundamental design of the ENS protocol:

The ENS Registry Design

Unknown labels are a consequence of the ENS Registry not emitting the actual label in events when subnames are created. Only the labelhash is emitted.

Understanding the distinction:

• The ENS Registry contract (ENSRegistryWithFallback) stores only the node for each registered name (the node is a 32-byte hash computed via namehash)
• However, indexers don’t generally read what’s stored on-chain—they read the data from events emitted by contracts
• The problem for indexers emerges from what’s emitted in events, not what’s stored

The root cause: All subnames are created by calling the setSubnodeOwner function on the Registry contract. When this happens, the Registry emits a NewOwner event for the newly created subname. However, this event contains a parameter misleadingly named label that is not actually the label string—it’s the labelhash of the new subname’s label:

event NewOwner(bytes32 indexed node, bytes32 indexed label, address owner);
//                                                       ^^^^^ This is actually a labelhash, not a label!

The critical issue: When a subname is added to the Registry, the Registry doesn’t emit the label of the newly created subname—only the labelhash of the new subname’s label. This means:

1. Indexers only receive labelhashes: When indexers listen to NewOwner events, they can only discover the labelhash, not the human-readable label
2. Contracts that wrap the Registry (like ETHRegistrarController or NameWrapper) can emit additional events with the actual label string, making labels discoverable to indexers
3. Direct Registry calls from contracts that don’t wrap the Registry and emit the label separately will result in unknown labels for indexers
4. Historical data from before label emission was standardized may not include label information

Shadow Registries

The unknown label problem also impacts Shadow Registries, which are essentially clones of the “root” ENS Registry deployed on other chains. These are part of projects such as:

• Basenames on Base
• Lineanames on Linea
• Other ENS-compatible naming systems on L2s and alternative chains

Shadow Registries inherit the same architectural design as the original ENS Registry, meaning they also only emit labelhashes (not labels) in their events. This means unknown labels are a challenge across the entire ecosystem of ENS-compatible naming systems, not just on Ethereum mainnet.

When Labels Can Be Made Known

In many cases, the labels that make up a name can be made known through several strategies:

• Contract events: Some contracts (like ETHRegistrarController or NameWrapper) emit the human-readable label in their events
• Rainbow table lookups: The human-readable label for a given labelhash can be determined via customizable and massive rainbow table lookups through ENSRainbow
• Heuristics for addr.reverse: ENSNode uses specialized heuristics that heal 100% of subnames under addr.reverse, which represent reverse ENS records
• Intelligent expansion strategies: ENSNode has implemented strategies to intelligently expand the set of rainbow tables in ENSRainbow over time, ensuring healing coverage improves continuously

ENSNode uses a number of these strategies in combination to heal unknown labels. However, if none of these methods succeed, the label remains unknown and must be represented as an encoded labelhash.

Why Unknown Labels Are Forever a Consideration

Unknown labels are a permanent architectural constraint of the ENS protocol, not a temporary issue that can be fully eliminated. Here’s why:

1. Protocol Design Immutability

The ENS Registry contract is immutable—it cannot be changed or upgraded. The design decision to emit only labelhashes (not labels) in NewOwner events is permanent.

2. Cryptographic One-Way Function

The labelhash function computes a 32-byte hash of a label using keccak256:

import { labelhash } from 'viem';
const labelHash = labelhash("vitalik");
// Returns: 0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc

keccak256 is a cryptographic hash function that is one-way:

• Given a label, you can compute its labelhash: labelhash("vitalik") → 0xaf2c...
• Given a labelhash, you cannot reverse it to get the original label: 0xaf2c... → ???

This means that without external knowledge (rainbow tables, event logs, etc.), a labelhash cannot be converted back to its original label. This one-way property is exactly why rainbow tables—and ENSRainbow—are necessary.

3. Ongoing Subname Creation

New subnames continue to be created on-chain. While many modern contracts emit label information in events, the protocol itself does not guarantee this.

How Unknown Labels Influence Indexing

Unknown labels impact how ENS data is indexed and queried:

Indexing Process

When ENSNode indexes onchain events where a subname is created in the ENS Registry:

1. The labelhash is always known from the onchain event data
2. The label may be unknown if it wasn’t emitted in the event
3. ENSRainbow lookup is attempted: ENSNode attempts to lookup the label for the labelhash through an attached ENSRainbow server
4. Representation decision:
   • If the lookup succeeds: ENSNode represents the subname using its true label
   • If the lookup fails: ENSNode represents the “unknown label” using its labelhash in the format [labelhash]

Label Mutability Over Time

The representation of labels can change over time as ENSRainbow’s healing capabilities improve:

• Time 1: ENSRainbow cannot heal label X → label is represented as [labelhash]
• Time 2: ENSRainbow gains the ability to heal label X → label transitions from unknown to known

This mutability means that:

• Label representations should not be used as immutable identifiers
• The node (computed via namehash) should always be used as the stable identifier for querying
• For deterministic results, pin healing to a specific label set ID + version (see Label Sets & Versioning)

Subgraph-Unindexable Labels

The legacy ENS Subgraph specifies that Unknown Labels and labels containing certain UTF-8 characters are “invalid” or “subgraph-unindexable”. These include:

1. \0 (null byte) - PostgreSQL does not allow storing this character in text fields
2. . (period) - Conflicts with ENS label separator logic
3. [ (left square bracket) - Conflicts with “unknown label” representations
4. ] (right square bracket) - Conflicts with “unknown label” representations

In ENSNode’s default Interpreted Labels mode (SUBGRAPH_COMPAT=false), when a subgraph-unindexable label is encountered, it will be represented as an Encoded LabelHash even if the actual label data is available. This simplifies handling for many edge cases.

How Unknown Labels Influence Apps and User Interfaces

Unknown labels create challenges for applications building on ENS:

Display Challenges

Apps must support the possibility of needing to display names containing unknown labels / encoded labelhashes.

Querying Challenges

Unknown labels create different challenges depending on which API you’re using:

Subgraph-compatible GraphQL APIs (ENS Subgraph & ENSNode’s /subgraph endpoint):

When querying ENSNode’s Subgraph-compatible GraphQL API or the legacy ENS Subgraph:

1. Use nodes, not names: Always use the node (computed via namehash) as the stable identifier, not the name string
2. Normalization awareness: When querying from user input, normalize first; when querying from onchain data, don’t normalize
3. Encoded LabelHash-aware namehash: Use implementations like viem’s namehash that handle encoded labelhashes correctly

ENSNode’s Resolution API:

ENSNode’s Resolution API (accessed via the ENSNodeClient SDK) accepts names directly without requiring you to compute the node (namehash) yourself. However, you must still normalize the name before passing it to the API. The key difference is that you don’t need to manually compute the namehash - you can call methods like resolveRecords(normalizedName, selection) directly with the name string.

The Solution: How ENSRainbow Works

ENSRainbow mitigates the unknown labels problem by providing a healing service that converts labelhashes back to human-readable labels via rainbow table lookups.

What is Healing?

Healing is the act of converting a labelhash back to its original label via a rainbow table lookup. ENSRainbow maintains pre-computed mappings of labelhash → label pairs (called rainbow records) that enable this reverse lookup.

How ENSRainbow Works

ENSRainbow operates as a sidecar service to ENSNode:

1. Rainbow Table Storage: ENSRainbow maintains LevelDB databases containing millions of labelhash-to-label mappings
2. HTTP API: Provides a lightweight HTTP API (GET /v1/heal/{labelhash}) that returns the corresponding label if found (optionally scoped via label_set_id and label_set_version query parameters)
3. Integration with ENSNode: During indexing, ENSNode automatically queries ENSRainbow when it encounters an unknown labelhash
4. Deterministic Healing: Uses label set IDs and versions to ensure deterministic healing across time

Healing Process

When ENSNode encounters an unknown label during indexing:

// 1. ENSNode encounters labelhash: 0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc
// 2. ENSNode queries ENSRainbow: GET /v1/heal/0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc
// 3. ENSRainbow looks up in rainbow table
// 4. If found: Returns { "status": "success", "label": "vitalik" }
// 5. ENSNode stores the name as "vitalik.eth" instead of "[af2c...].eth"

Coverage and Limitations

ENSRainbow significantly improves healing coverage compared to relying solely on services like the ENS Subgraph. However:

• Not all labels can be healed: Some labelhashes may never be recoverable if the label cannot be discovered from any available source (onchain events, offchain APIs, brute-force generation, user submissions, or other data sources)
• Growing coverage: ENSRainbow’s goal is to heal as many ENS names as possible, minimizing the probability that end-users encounter unknown labels
• Multiple label sets: Different label sets (identified by label set ID) can provide different coverage, allowing the ecosystem to contribute additional healing data

Label Sets and Versioning

ENSRainbow uses a label set system to organize rainbow table data:

• Label Set ID: Identifies a collection of rainbow records (e.g., subgraph, discovery-a)
• Label Set Version: Monotonically increasing version numbers that enable incremental updates
• Deterministic Results: Clients can pin to specific versions for reproducible healing results

This system enables:

• Extensibility: New label sets can be created and published by anyone
• Incremental Updates: New versions add mappings without invalidating previous versions
• Deterministic Healing: Applications can rely on consistent results over time

For more details, see Label Sets & Versioning.

Related Documentation

• Glossary - Key terminology including labelhash, heal, and rainbow table
• Label Sets & Versioning - Understanding how ENSRainbow organizes healing data
• Architecture - High-level system architecture and data flow
• API Reference - Complete HTTP API documentation for ENSRainbow
• Terminology Reference - Comprehensive ENSNode terminology including Unknown Label and Encoded LabelHash
• Querying Best Practices - How to handle unknown labels when querying ENSNode