How to integrate ENS in your app

ENS

In previous article I explained how ENS works. Today I’m going to explain how you can integrate and use ENS in your applications.

Why we need ENS in our app?

1. To resolve name (whoisens.eth) to wallet address (0x5b8…2c). Example could be sending money, paying for goods, etc…
2. To resolve name to IPFS or Swarm. That’s used to point to website or any other kind of document/file.

Resolving name to wallet address

Assume you have a service where users paid for some goods or it’s some kind of wallet. When user enter a name (ENS name), your app resolves it to an address where it’s pointed. As was mentioned above, it could be whoisens.eth which resolves to address 0x5b8…2c. Actually it could be any kind of address, wallet address, smart contract address, just any hash… But, if we have an app working with money transfer, it’ll assume that name pointed to wallet address.

It’s useful, as you shouldn’t enter long address and check it twice, but could be sure you send money to particular person/organization just by looking into entered name.

Similar, user can enter address (0x…….) and application will resolve it to a name. Also useful, as user will be more confident about where money will be sent. But please note, address could be resolve into a name if reverse record is set.

Resolving name to IPFS/Swarm (Content hash)

The same name could be resolved to IPFS/Swarm address (it will be different address). It’s similar to DNS, if you’re familiar with it, where we have A record for the main purpose, and other records, e.g. TXT for other purpose. Here, resolving name to wallet address it’s like A record, and resolving it to IPFS/Swarm address — it’s TXT or other record.

Why we need IPFS/Swarm? It’s actually our content. It could be any kind of file, image, document. Usually it’s website. But that website deployed into Ethereum network, so it’s immutable and decentralized. Cool, ha?

Quick recap

So far, we have Ethereum name, e.g. whoisens.eth which can be resolved into “wallet address” and “website URL”. Thus, we can use the same name to send money and if application supports render/handling IPFS/Swarm, we can see website under that address (or use other services that can show us that content)

Lets integrate it!

Lets look into a few options how you can achieve it, based on your preferences.

1. Use Web3.js or other third-parties libraries
2. Make JSON-RCP call directly to Ethereum network
3. Use REST API

Use Web3.js or other third-parties libraries

First option is very commonly used. All you need it’s any kind of provider and Web3.js or other library. Provider will act as a window to Ethereum network, and library will act as an API, making all required calls and getting info for you.

const networkURL = 'https://mainnet.infura.io/v3/xxxxxx'; // <-- provider URL
const web3 = new Web3(Web3.givenProvider || networkURL);
const address = await web3.eth.ens.getAddress('whoisens.eth');
const content = await web3.eth.ens.getContenthash('whoisens.eth');

Using Web3.js to get info

Output from Web3.js

That code will try to find already used provider (e.g. Metamask) by checking Web3.givenProvider or use the default external one. And after, resolve name into address.

NOTE: contenthash in Web3.js will return byte32, e.g. 0xe301017012200943d91817565faecf319074638f0da4870e4d7c012bed22229d8250a5991b95, thus you have to decode that value by yourself. You can use https://github.com/pldespaigne/content-hash for that.

NOTE: There isn’t reverse resolve (address to name) for Web3.js for now, so you have to use other third-party libraries for that, if you need such functionality.

Pros:

• Very easy to use

Cons:

• Depending on external library
• Contenthash doesn’t returned as decoded value (for Web3.js at least)
• No reverse resolve (for Web3.js at least)

Make JSON-RCP call directly to Ethereum network

Actually, it’s not so simple to resolve name to address or to content hash (IPFS/Swarm). For more info please see ENS (Ethereum Name Service): How it works?. To make such resolve, you have to make it in a few steps, but here provided part of code which makes RPC call directly to network, so you have an idea how it looks like:

const r = await fetch(networkURL, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        jsonrpc: '2.0',
        id,
        method: 'eth_call',
        params: [{
            to,
            data
        }, 'latest']
    })
});
const result = await r.json();

to and data should be formed in particular way, please see https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_call and https://solidity.readthedocs.io/en/latest/abi-spec.html#examples for more info.

If you are interested to know how it works form the inside, you can checkout source code of whoisens-lib which does all resolving directly without third-party libraries making JSON-RPC calls.

That’s the most complicated approach here, but with no dependencies at all :)

I would not recommend that approach. But, if you don’t use Web3.js or any other third-party libraries that could do it for you, and don’t want additional heavy dependencies in your project, you can use whoisens-lib or see other options below.

Pros:

• no third-party dependencies

Cons:

• Too complicated

Use REST API

Of course, that REST API should be provided by someone. It’s not available in Ethereum. WhoisENS service provides such API for free, so you can use it.

const networkURL = 'https://api.whoisens.org';
let r = await fetch(`${networkURL}/resolve/address/${name}`));
const address = (await r.json()).result;
r = await fetch(`${networkURL}/resolve/contenthash/${name}`));
const contenthash = (await r.json()).result;

Using WhoisENS REST API

Part of output from WhoisENS REST API

API returns a lot of useful info, even more than you need :) BTW, name resolving endpoint works in both way, you can resolve name to address and in address to name using the same endpoint. It’s very handy, as you shouldn’t check it by yourself and use different methods. Also content hash returns already decoded value.

Please check with documentation how to use WhoisENS REST API.

Pros:

• No third-party dependencies
• Returned info is verbose
• Endpoint works in both way
• Contenthash returned already decoded

Cons:

• REST API should always be up and running, and if the service down or fail — your application will not work. As an option — you can deploy your own instance to be more confident and have more control.

Conclusion

As you can see, there’re few ways how you can integrate ENS into your application. Each has it’s own pros and cons.

If you’re already use Web3.js — you can stick with it. But you have to decode yourself contenthash and use some other library for reverse resolve.

If you don’t use Web3.js or other similar libraries, or need verbose info, you can use whoisens-lib, which was created for such kind of job.

If you don’t want any library dependency, you can use some REST API. WhoisENS provides such REST API (or you can deploy your own instance). In that case, you can resolve name directly in your browser without any dependencies at all.

PLEASE NOTE: WhoisENS service, whoisens-lib and WhoisENS REST API doesn’t work with old ENS (names registered via auction). These names should be migrated to new ENS registrar by May 4, 2020.

Please share with your own experience resolving ENS, connecting to nodes, using gateways, libs, REST API. Issues you faced and how you resolve them.

Happy coding!