Handshake Address Naming


Handshake Address Naming Spec

Handshake address names enable human-readable wallet addresses for every cryptocurrency without compromising privacy.

The problem of difficult-to-read wallet addresses is well-known in the crypto community. Many attempts have been made to solve this problem but none have truly taken off. We’ll analyze the most well-known naming solution, ENS, to illustrate why this has been the case:

ENS primarily supports Ethereum addresses — it doesn’t support other blockchain addresses which inhibits it from becoming a universal naming system.
ENS names compromise privacy. Even if you switch the address that a name points to, anyone can track all the addresses associated with a name because the address history is stored on the blockchain. This severely limits the possible use cases of ENS names; you must be comfortable with all your transaction history being public and thus trivial to de-anonymize.
In order to use ENS, you must download the ethereum blockchain, which can take hours to sync and require tens of gigabytes of storage even in fast mode.

Handshake address names solve these problems. It is the first naming solution that can be used for any blockchain, preserve privacy, and resolve addresses using virtually zero resources.

Blockchain Agnostic. Handshake supports different blockchain addresses directly in the protocol. You can store different addresses as a key:value pair where the key is the blockchain (e.g. bitcoin) and the value is the address (e.g. 0x32Be343B94f860...). Clients can query a Handshake name for its blockchain addresses just like clients can query a Handshake name for its DNS records.

Private. By using private resolution (outlined below), name owners can receive crypto using their name without exposing their transaction history to senders and the rest of the world. You can use a human-readable name like namebase/ and get the same privacy guarantee as using a bitcoin address like 0x32Be343B94f860....

Lightweight. Handshake address names can be resolved with the lightweight Handshake Simple Payment Verification (SPV) resolver. The SPV resolver allows you to resolve Handshake names trustlessly while using only 10mb of memory and virtually no CPU. This drastically increases the number of places that Handshake address names can be used (e.g. IoT devices that have low resources).


Handshake address names support two modes of resolution. Basic resolution, which does not preserve privacy but is simplest to implement, and private resolution, which requires an address server (either a third-party service or managed by the name owner).

Basic Resolution

Basic resolution is supported by default because you can easily associate a wallet address with a name using the key:value storage provide by Handshake. This is simplest to implement but does not preserve privacy and compromises anonymity. This resolution method may be desirable for ENS names which already have their transaction history broadcast to the public.

Private resolution

Private resolution requires that clients request addresses from an address server which returns a new address for each request. This prevents adversaries from using Handshake’s public transaction history to link addresses together. Additionally, the server must ensure that receiving a new address from the server does not reveal any information about past addresses.

First, name owners generate a large number of wallet addresses and organize them into a Merkle tree. Next, they upload the full Merkle tree to the address server and save the Merkle root to their name on the Handshake blockchain.Clients can then request addresses and Merkle proofs from the address server to confidently obtain addresses associated with a Handshake name.


  1. Name owner generates a large number of addresses (e.g. 1000)
  2. Name owner computes a Merkle tree where the leaf nodes are their addresses concatenated with a nonce.
  3. Name owner stores the Merkle root on the Handshake blockchain by setting a DNS TXT record to the merkle root.1
  4. Name owner also stores the IP address of the server in that DNS TXT record. 2
  5. Name owner uploads their address Merkle tree to the address server, which verifies that the Merkle root matches the one on the Handshake blockchain…


When a person/dApp/device wants to send crypto to a Handshake name using private resolution:

  1. Use the SPV resolver to get the Merkle root and the address server’s IP.
  2. Query the address server for a wallet address, nonce, and Merkel proof.
  3. Verify that the address concatenated with the nonce are in the Handshake name’s Merkle tree.
  4. Send crypto to the address.

Updating the server with new addresses

Name owners will need to update the server with new addresses once the previous addresses have been used up. Name owners can query the server to check when they need to upload new addresses.

  1. Name owner queries the server with a proof of name-ownership to check how many unused addresses remain.
  2. Below a specified threshold (e.g. 100 addresses), the name owner can upload new addresses by following the setup steps.


While a third-party server technically has access to all the generated addresses, it is still more private than using basic resolution. If a name owner wants to maximize privacy, they can run their own server instead of using a third-party server. This is trivial to set up by using services like Glitch.com. In either case, a server just needs to support three functions in order to resolve Handshake addresses.

  1. Allow name owners who generate valid proofs of ownership to upload addresses.
  2. Keep track of which addresses have been used in order to return a new address each time.3
  3. Allow name owners who generate valid proofs of ownership to check how many unused addresses remain.


Wallets should automate the steps involved for both name owners and clients. We (Namebase) would like to work with the open-source community to provide a reference implementation for the server, along with a library that wallets can use to implement Handshake address names.

By implementing Handshake address names, it is possible to provide human-readable wallet addresses for every cryptocurrency without compromising privacy. This will bring much-needed usability improvements to the crypto ecosystem without sacrificing the values upon which it is built.

1 This step can be done in the same transaction as the next step to optimize fees.

2 Instead of using an IP address, you can use a Handshake name since Handshake supports DNS records. The Handshake name can even be the same name as the wallet name!

3 A simple list and index can be used.