Namehashing

Namehashing is an algorithm that converts a domain name in a classical format (like www.example.crypto) to ERC-721 token ID. All .crypto contracts accept a domain name as a method argument in the form of an ERC-721 token. Namehashing is defined as a part of the EIP-137 standard. See the standard for a text description of the algorithm.

To verify an implementation of the namehash algorithm, use the following reference table:

Generating a Domain Namehash

You can generate the namehash of a domain using any of the Resolution Libraries, Resolution CLI, or Resolution Service. You can also use online tools to calculate the namehash of the domain.

const {default: Resolution} = require('@unstoppabledomains/resolution');
// obtain a key by following this document https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/#api-key
const resolution = new Resolution({ apiKey: "<api_key>" });
let namehash = resolution.namehash("brad.crypto", "UNS");

import com.unstoppabledomains.resolution.Resolution;
// obtain a key by following this document https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/#api-key. See https://github.com/unstoppabledomains/resolution-java for more initialization options
DomainResolution resolution = new Resolution("<api_key>");
String namehash = resolution.getNamehash("brad.crypto", "UNS");

import UnstoppableDomainsResolution

// obtain a key by following this document https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/#api-key. See https://github.com/unstoppabledomains/resolution-swift for more initialization options
guard let resolution = try? Resolution(apiKey: "<api_key>") else {
  print ("Init of Resolution instance failed...")
  return
}

let namehash = try resolution.namehash(domain: "brad.crypto")

package main

import (
    "fmt"
    "github.com/unstoppabledomains/resolution-go/v3"
)

func main() {
    // obtain a key by following this document https://docs.unstoppabledomains.com/domain-distribution-and-management/quickstart/retrieve-an-api-key/#api-key. See https://github.com/unstoppabledomains/resolution-go for more initialization options
    uns, _ := resolution.NewUnsBuilder().SetUdClient("<api_key>").Build()
    namehash, _ := uns.Namehash("brad.crypto")
    fmt.Println("The namehash for brad.crypto is", namehash)
}

$ resolution namehash -d brad.crypto
"0x756e4e998dbffd803c21d23b06cd855cdc7a4b57706c95964a37e24b47c10fc9"

Reverse Lookup

Fundamentally, namehashing is a one-way operation. It recursively hashes the labels using the SHA-256 hash function. If one possesses a precomputed table of all hashes and corresponding domains reverse lookups are possible. This table can be reconstructed using the events on the CNS and UNS Registry NewURI event.

JSON RPC

The UNS and CNS metadata APIs track all domain names with their corresponding namehash. That makes it possible to obtain an original domain name from token metadata which can be retrieved from the token metadata URI.

The token metadata URI can be retrieved via ETH RPC call to ProxyReader#tokenURI. This works for CNS and UNS.

Now, the domain name along with other metadata can be retrieved by performing a simple GET request using the token metadata URI.

For example:

// Get a proxy reader contract instance using web3 or ethers
let proxyReaderContractInstance = new Contract(address, abi);

// call the tokenURI method
let tokenUri = await proxyReaderContractInstance.tokenURI("0x756e4e998dbffd803c21d23b06cd855cdc7a4b57706c95964a37e24b47c10fc9");

// GET data from URI
let metadataResponse = await fetch(tokenUri);
// Parse it as json
let metadata = await metadataResponse.json();

// Retrieve the domain name from metadata
console.log(metadata.name);

NewURI Events

When a domain is created its name and token ID are logged using a NewURI event. This event can be looked up in order to reverse the namehash of a domain. This approach also works for CNS and UNS.

For an implementation example, see the unhash function of the resolution library.

Note that regardless of the way a namehash is reversed, it should always be forward-validated by hashing the retrieved domain name. In order to ensure the integrity of the retrieved domain name.

Public API

Unstoppable Domains maintains a public-facing API which can be used to obtain the information of a domain using its namehash. To learn more, visit the Get Metadata for a Domain documentation.