Domain Name Claiming for Handshake

name-claim.md

Handshake Domain Name Claims

The Handshake Network has reserved the Alexa Top 100k domains on chain to make sure that important brands are able to own their name in the system. These names can be claimed using a DNSSEC proof of ownership. This means that the owner of the domain name must place a TXT record at their domain name that includes a controlled address.

For technical instructions, see:

• https://github.com/handshake-org/hsd#claiming-a-name
• https://github.com/handshake-org/hs-names

If you use a DNS provider that does not support DNSSEC, this process will be more challenging and the instructions here will need to be used. Please consider switching to a DNS provider that does allow DNSSEC to help make the internet more secure.

Instructions

Make sure to be using the latest versions of hsd and hs-client. It is also possible to claim a name using Kyokan's Bob Wallet. Skip to Claiming the Domain.

DNS Configuration

• Verify that your name was reserved on Handshake by searching on https://dns.live
  • It is not the current Alexa Top 100k, the list was aggregated in 2018
  • https://github.com/handshake-org/hs-names/blob/master/data/top-1m.csv
• Enable DNSSEC on your DNS hosting provider

Some guides are available here:

• Namecheap
• GoDaddy
• Gandi
• Name.com
• Hover
• Cloudflare

It may take some time before DNSSEC is activated, be sure that your DNS provider has completed enabling DNSSEC before continuing.

Handshake

• Install hsd using the installation instructions on the README. This requires Node.js version 10 along with npm, and node-gyp. Instructions may vary based on operating system, please use the appropriate package manager to install these.

hsd Installation

$ git clone https://github.com/handshake-org/hsd
$ cd hsd
$ npm i

Setup

Now start the node so that its possible to create an address. This will create a directory $HOME/.hsd. It is very important that this directory is secure because the wallet keys are in $HOME/.hsd/wallet.

./bin/hsd

hs-client Installation

In another terminal, install hs-client.

$ git clone https://github.com/handshake-org/hs-client
$ cd hs-client
$ npm i

Note: if you are not using the latest version, you will need to pass --network main to every CLI command from hs-client.

Mnemonic Backup

Be sure to back up your mnemonic using the command:

$ ./bin/hsw-cli master

https://hsd-dev.org/api-docs/#get-master-hd-key

Note: this is very important to back up and will result in loss of control of the domain name on Handshake if it is lost. Be sure to correctly back up the mnemonic phrase in a separate place. It should look like a series of common words. These words can be used to create a new wallet and rediscover the HNS and names that are controlled by that wallet.

Setting a Passphrase

If you would like to set a passphrase for the wallet, use the command:

$ curl  http://127.0.0.1:12039/wallet/primary/passphrase \
    -X POST --data '{"passphrase":"NEWPASSWORDGOESHERE"}'

If you are updating a wallet's passphrase, include the an "old" key in the JSON body that contains the old passphrase.

On Windows the command needs to be formatted like this (escaped double quotes in the json):

curl -X POST -H "Content-Type: application/json" \
    --data "{\"passphrase\":\"NEWPASSWORDGOESHERE\"}" \
    http://127.0.0.1:12039/wallet/primary/passphrase

Claiming the Domain

To connect the local wallet to the domain name, use the command: Users running Bob Wallet will want to pass along their API key by including the --api-key APIKEYHERE flag in the below command.

$ ./bin/hsw-rpc createclaim DOMAINNAME

Copy the .txt field in the output and place in a TXT record at the domain using a DNS service provider. It should look something like "hns-claim:qnPxvMRKAAAAAAAA+4mmSeRmfY/8TOEF+ux4cu9H4M4OYKap5Y4LfMO7YUcAFBUOdex4+uplMqefKrIpsyZnyHPn".

Submitting the Domain Claim

After the TXT record has been propagated, use the command:

$ ./bin/hsw-rpc sendclaim DOMAINNAME

This will broadcast a claim to the network. After some time, the claim will be mined. The claim must mature for a period of 30 days before DNS records can be writted to the authenticated database. An additional claim can be sent to reset the 30 day period. This is useful to prevent names from being stolen, since the community has time to coordinate out of band during those 30 days. After the maturity period, the name will now be under control of the local wallet. To update the records, the sendupdate RPC command is useful.

An example here:

$ ./bin/hsw-rpc sendupdate DOMAINNAME \
    '{"records":[{"type":"GLUE4","ns":"ns1.example.com.","address":"127.0.0.1"}]}'

Credits

• dns.live
• tynes

Suggestion: use https://dnssec-debugger.verisignlabs.com/ to test DNSSEC chain.
https://dnssec-debugger.verisignlabs.com/crypto51.app is an example of a qualified DNSSEC chain for a name that was successfully claimed on Handshake. Note that the keys in the DS records are RSASHA256. Ironically, ICANN.org will not be able to be used to claim icann on Handhsake because .org uses RSASHA1-NSEC3-SHA1 (considered weak and not valid).

See: handshake-org/hsd#399

A new node RPC is being implemented called getdnssecproof here: handshake-org/hsd#261

It will return the Handshake DNSSEC proof for a domain along with verifying it. An error will be thrown if the proof is invalid. This will be helpful for testing out the DNSSEC claim process, along with making the DNSSEC proofs themselves more accessible to application developers.

Alexa's top 100K only? What about brands & entities which don't fall into this category?

@Blooniverse, this isn't really the right place to ask questions or raise issues. But HNS reserved trademark names as well, there was a long application process available before mainnet launched: https://github.com/handshake-org/hs-names

Spotted a typo "The claim must mature for a period of 30 days before DNS records can be writted to the authenticated database."

A couple questions:

1. If you set a passphrase (as detailed in https://gist.github.com/tynes/230f715c9710a089ee190b28585b6596#setting-a-passphrase), where do you need to specify it in the following commands?
2. In the section about broadcasting a claim, is there a way to check that the claim was properly broadcast to the network? I got some json when I issued the command, but not any transaction ID.
3. The claim instructions say, "An additional claim can be sent to reset the 30 day period. This is useful to prevent names from being stolen, since the community has time to coordinate out of band during those 30 days." What does this mean? I should submit a claim and then reset that claim at some point? Or is it that I only need to reset that claim if someone attempts to steal it?
4. Once the claim has matured, how does one get the airdrop for the claim?

@micah:

1. See https://hsd-dev.org/api-docs/?shell--cli#unlock-wallet to decrypt a wallet for a given timespan to perform signautre operations. In this guide, createclaim and sendclaim will not require a wallet signature, but sendupdate will.
2. Claims are actually broadcasted into a special section of the mempool that AFAIK is not displayed on block explorers the way regular transactions are. You may have to wait for it to be confirmed in a block. Claims are integrated into coinbase transactions but your wallet will index it once confirmed. Execute rpc getnames to see the claimed name, it will be in a LOCKED state for ~30 days.
3. The lockout period is explained in this issue but there was a problem with it, disclosed here. Currently hsd does not support the emergency re-claim procedure but it will soon.
4. After the 30 day LOCKED period you can register the name with rpc sendupdate. This registration transaction will include a change output back to your wallet with the value of the claim reward.

If you have any more questions or need better support, join us on telegram: https://t.me/hns_tech