How to claim your DNS domain on ENS

4 min readNov 11, 2017

At DevCon3, I announced forthcoming support for claiming DNS domains on the Ethereum Name Service (ENS). This will make it possible to import nearly any internet domain name into ENS, and interact with it just as you would a .eth domain. Soon, you will be able to tell people “you can pay me ether at myname.com”.

Right now, this is only deployed for one internet TLD — .xyz — on the Ethereum Ropsten test network. Support on the Ethereum mainnet, and on more internet TLDs, is coming soon. Once everything is in place, we expect to be able to support the vast majority of internet TLDs — about 96% of them.

Since this is a brand new feature, the process right now is manual and a bit involved. Claiming your ENS domain is a four step process:

Set up DNSSEC signing for your domain.
Add a TXT record specifying your Ethereum address to your DNS domain.
Prove the contents of this TXT record to the DNSSEC oracle.
Call the DNS Registrar for .xyz to claim ownership of your domain in ENS.

We’ll walk through these in order.

1 — Setting up DNSSEC signing

Depending on your DNS provider, this may be really easy, or quite involved.

If your DNS provider already supports DNSSEC-signed domains, great! Follow their instructions for setting up DNSSEC.

If they don’t, you’ll need to migrate to someone who does. I recommend either EasyDNS or Google Cloud DNS. EasyDNS’s setup guide for DNSSEC is here, while Google’s is here.

Whatever provider you need, make sure you select RSA signatures and SHA256 hashing.

Once you’ve set DNSSEC up, your DNS provider will give you some data — DS or RRSIG records . You will need to provide these records to your registrar. Doing this lets them insert the relevant ‘glue’ to make sure everything works end-to-end.

When you’ve finished this step, use Verisign’s DNSSEC debugger to verify everything is working before going further.

2 — Adding a TXT record

The DNS Registrar on ENS looks for a TXT record with a specific name and format in order to verify what Ethereum address should be given ownership of the domain.

To claim ownership of mydomain.xyz, create a TXT record in your DNS zone, _ens.mydomain.xyz, with text data of the form a=0x1234..., where 0x1234... is the Ethereum address you want to give control of the ENS record to.

3 — Interacting with the DNSSEC oracle

Next, you need to prove to the DNSSEC oracle the contents of the TXT record you set up. For that, you can use this dnsprove tool I wrote. It takes care of all the hard work for you.

First, download the tool into a golang workspace and compile it.

Then, run dnsprove --address=0xd7296b6044ffd0565062345c2eaa4017024b2d22 --keyfile=/path/to/keyfile TXT _ens.mydomain.xyz.

For the command to work, you will need to have a running Ethereum node on localhost:8545 — or, you can specify a custom location with --rpc=http://host:port.

Here, the address is the address of the DNSSEC oracle on Ropsten The keyfile is the path to a JSON keystore file for the account you want to use to send transactions.

Before you ask, yes, it is ironic that this command does not yet support ENS names for specifying the DNSSEC oracle address.

DNSSEC will perform a series of DNS queries to establish a chain of trust. DNSSEC will then check with the oracle to see which steps have not yet been proven or are out-of-date.

dnsprove will then prompt you for permission to send transactions verifying the remaining records. Once you grant your permission, the transactions are sent, and Ethereum is now officially cognizant of your DNS records!

3 — Claiming your domain in ENS

Finally, you can claim your domain in ENS. From a geth console, execute the following:

var registrar = web3.eth.contract([{"constant":true,"inputs":[],"name":"ens","outputs":[{"name":"","type":"address"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":true,"inputs":[],"name":"rootDomain","outputs":[{"name":"","type":"bytes"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":true,"inputs":[],"name":"oracle","outputs":[{"name":"","type":"address"}],"payable":false,"stateMutability":"view","type":"function"},{"constant":false,"inputs":[{"name":"name","type":"bytes"}],"name":"claim","outputs":[],"payable":false,"stateMutability":"nonpayable","type":"function"},{"constant":true,"inputs":[],"name":"rootNode","outputs":[{"name":"","type":"bytes32"}],"payable":false,"stateMutability":"view","type":"function"},{"inputs":[{"name":"_dnssec","type":"address"},{"name":"_ens","type":"address"},{"name":"_rootDomain","type":"bytes"},{"name":"_rootNode","type":"bytes32"}],"payable":false,"stateMutability":"nonpayable","type":"constructor"}]).at("0xf8d18b3c5de9892681998076bebcba32e62e0835");function encodeName(buf, off, name) {
  if(name == ".") {
    buf.writeUInt8(0, off++);
    return off;
  }for(var part of name.split(".")) {
    buf.writeUInt8(part.length, off++);
    buf.write(part, off)
    off += part.length;
  }
  return off;
}function hexEncodeName(name) {
  if(!name.endsWith(".")) name = name + ".";
  var buf = new Buffer(name.length + 1);
  var off = encodeName(buf, 0, name);
  return "0x" + buf.toString("hex", 0, off);
}registrar.claim(hexEncodeName('myname.xyz'), {from: myaddress})

Run this, and once the transaction is mined, you’re done!

The ENS record corresponding to myname.xyz is now owned by your account, and you can configure it just like any other name — perhaps by using manager.ens.domains.

Next Steps

Clearly, this is currently quite a manual, and fairly involved process, but this is set to improve. Better libraries, improvements to the command line tool, and even dedicated claiming dapps will make this all a lot more straightforward for end users; we’re even optimistic that registrars or DNS service providers may add support for doing this with a single click.

Do you want to help improve the process? We’re going to be looking for (paid and volunteer) help with this over coming months. Hit us up in our gitter channel if you’re keen to help!