Handshake logo

HIP-0005: Name data standard for alternative namespace resolution


This HIP describes how to set the data for a Handshake name so that it can resolved via an external namespace or alternative consensus system. Resolution must be performed by an extension to a Handshake resolver which may not be included by default in full or light clients.


There may be various reasons to resolve a name on an alternative namespace other than a domain name or an name server hosted on an IP address. One example is decentralized subdomains: software could recognize the special records for an HNS name and resolve the user query on an external system, where protocol rules allow for censorship-resistant subdomain registration, relieving those domain owners of parent-zone risk.

Name data standard

External resolution is triggered by setting a special NS record for a Handshake name. The ns value must end in a name that is invalid or otherwise blocked by the Handshake root name server. For example, names that begin with an underscore are normally invalid, and names like .bit and .eth are normally blocked. The invalid “top level domain” of the ns record is referred to as the HIP-5 protocol.

Any additional labels in the ns field are treated as protocol-specific inputs for the external resolver, and are referred to as the HIP-5 data.

This is an example of a Handshake name resource that should trigger external resolution with a compatible plug-in:

  "records": [{
    "type": "NS",
    "ns": "0x36fc69f0983E536D1787cC83f481581f22CCA2A1._eth."

In this example, the protocol is _eth which corresponds to “EIP-137 compatible Ethereum contract.” The data is 0x36fc69f0983E536D1787cC83f481581f22CCA2A1 which corresponds to an “Ethereum contract address.”

External name resolution for Handshake TLDs

To execute this protocol, a Handshake root nameserver must inspect its own responses to all queries. If it detects a compatible NS record in the response to a query, the software extension should resolve the initial query string using the external protocol defined by the NS record. The plug-in is effectively a recursive resolver inside the HNS root zone.

Example dialog between user, their recursive resolver, the HNS root resolver, and the HIP-5 plug-in. Notice how the plugin intercepts the response from the root name server.

? denotes queries, ! denotes responses and A / NS are DNS record types.

HIP-5 Resolver Diagram

For best interoperability with existing DNS software, software extensions implementing this protocol must not send HIP-5 supported NS referrals to DNS clients even if the queried name or type does not exist. Recursive resolvers may interpret such records as delegations, but these pseudo-NS records are not reachable by traditional DNS clients, and it could end up poisoning their cache. Instead, software extensions should act as an authoritative source within the root server, sending NXDOMAIN or NODATA for negative answers as appropriate.

Direct resolution of external namespace

Because the Handshake resolver is running with a protocol extension plug-in, it should also be possible for that same software to resolve alternative namespaces outside of Handshake referrals. This mechanism is not really a feature of HIP-5 but is included here as a recommendation for software implementing this HIP.

Example of direct ENS resolution using HIP-5 extended Handshake resolver. Note how the .eth suffix resolves using the official ENS contract.

$ dig brantly.eth +short

Registered protocols

Ethereum contract address._ethEIP-137 ENS-compatible contract deployed on Ethereum
ENS subdomain.ethOfficial ENS contract deployed on Ethereum


.eth and ._eth: https://github.com/imperviousinc/handover

Mon, 08 Feb 2021
Last commit:
Mon, 13 Mar 2023
  • Mike Carson <https://impervious.com/>
  • Matthew Zipkin <pinheadmz@gmail.com>

Edit on GitHub