Technical Documentation
Dapp Developer Guide
Contract API Reference
Contract Developer Guide
ENS Migration (February 2020)
Resolving Names
The ENS namespace includes both .eth names (which are native to ENS) and DNS names imported into ENS. Because the DNS suffix namespace expands over time, a hardcoded list of name suffixes for recognizing ENS names will regularly be out of date, leading to your application not recognizing all valid ENS names. To remain future-proof, a correct integration of ENS treats any dot-separated name as a potential ENS name and will attempt a look-up.
Looking up cryptocurrency addresses
Names can have many types of data associated with them; the most common is cryptocurrency addresses. ENS supports storing and resolving the addresses of any arbitrary blockchain.
Resolving a name to an Ethereum address using a library is simple:
ensjs
web3.js
ethjs-ens
ethers.js
go-ens
web3.py
web3j
1
var address = await ens.name('resolver.eth').getAddress();
Copied!
1
var address = ens.getAddress('alice.eth');
Copied!
1
var address = await ens.lookup('alice.eth');
Copied!
1
var address = await provider.resolveName('alice.eth');
Copied!
ethers.js also supports using ENS names anywhere you would use an address, meaning you often do not need to directly call
resolveName. For example, to look up an account's balance, you can do:1
var balance = await provider.getBalance('alice.eth');
Copied!
Or, to instantiate a contract:
1
const abi = [
2
"function getValue() view returns (string value)",
3
"function setValue(string value)"
4
];
5
const contract = new ethers.Contract('contract.alice.eth', abi, provider);
Copied!
1
address, err := ens.Resolve(client, "alice.eth")
Copied!
1
address = ns.address('alice.eth')
Copied!
1
String address = ens.resolve("alice.eth");
Copied!
web3j also supports using ENS names anywhere you would use an address, meaning you often do not need to directly interact with the
EnsResolver object. For example, to instantiate a contract interface, you can do:1
YourSmartContract contract = YourSmartContract.load(
2
"contract.alice.eth", web3j, credentials, GAS_PRICE, GAS_LIMIT);
Copied!
Resolution without a library is a three step process:
- 1.
- 2.Call
resolver()on the ENS registry, passing in the output of step 1. This returns the address of the resolver responsible for the name. - 3.Using the resolver interface, call
addr()on the resolver address returned in step 2, passing in the hashed name calculated in step 1.
Resolution support for the addresses of other blockchains is implemented with an additional overload on
addr(). To resolve a non-Ethereum address, supply both the namehash and the SLIP44 chain ID of the cryptocurrency whose address you want to resolve. For example, to resolve a Bitcoin address, you would call addr(hash, 0). Note that the returned address will be in binary representation, and so will need decoding to a text-format address; for details, see EIP 2304.If you are resolving addr() records, you MUST treat a return value from the resolver of 0x00…00 as that record being unset. Failing to do so could result in users accidentally sending funds to the null address if they have configured a resolver in ENS, but not set the resolver record!
Looking up other resources
ENS supports many types of resources besides Ethereum addresses, including other cryptocurrency addresses, content hashes (hashes for IPFS, Skynet, and Swarm, and Tor .onion addresses), contract interfaces (ABIs), and text-based metadata. The process for looking these up varies from library to library; for specific details see your chosen library's documentation.
Resolving these content types without a library follows the same 3-step process detailed above; simply call the relevant method on the resolver in step 3 instead of
addr().ensjs
web3.js
ethjs-ens
ethers.js
go-ens
web3.py
web3j
1
// Getting contenthash
2
await ens.name('abittooawesome.eth').getContent()
3
// Setting contenthash
4
await ens.name('abittooawesome.eth').setContenthash(contentHash)
5
​
6
// Getting other coins
7
await ens.name('brantly.eth').getAddress('BTC')
8
// Setting other coins
9
await ens.name('superawesome.eth').setAddress('ETC', '0x0000000000000000000000000000000000012345')
10
// Getting text
11
await ens.name('resolver.eth').getText('url')
12
// Setting text
13
await ens.name('superawesome.eth').setText('url', 'http://google.com')
Copied!
1
// Getting contenthash
2
web3.eth.ens.getContenthash('ethereum.eth').then(function (result) {
3
console.log(result);
4
});
5
// Setting contenthash
6
web3.eth.ens.setContenthash('ethereum.eth', hash);
Copied!
1
Not supported.
Copied!
1
const resolver = await provider.getResolver('abittooawesome.eth');
2
const contentHash = await resolver.getContentHash();
3
const btcAddress = await resolver.getAddress(0);
4
const dogeAddress = await resolver.getAddress(3);
5
const email = await resolver.getText("email");
Copied!
1
// Encoding
2
bin, err := ens.StringToContenthash("/ipfs/QmayQq2DWCkY3d4x3xKh4suohuRPEXe2fBqMBam5xtDj3t")
3
// Setting contenthash
4
resolver.SetContenthash(opts, data)
5
// Getting contenthash
6
resolver.Contenthash()
7
// Decoding
8
repr, err := ens.ContenthashToString(bin)
9
​
10
// Getting Multicoin
11
btcAddress, err := resolver.MultiAddress(0)
12
// Setting Multicoin
13
resolver.SetMultiAddress(opts, address)
14
​
15
// Setting text
16
resolver.SetText(opts, name, value)
17
// Getting text
18
resolver.Text(name)
Copied!
1
Not supported.
Copied!
1
Not supported.
Copied!
Encoding and decoding contenthash
contenthash is used to store IPFSand Swarm content hashes, which permit resolving ENS addresses to distributed content (eg, websites) hosted on these distributed networks. content-hash javascript library provides a convenient way to encode/decode these hashes.1
const contentHash = require('content-hash')
2
const encoded = 'e3010170122029f2d17be6139079dc48696d1f582a8530eb9805b561eda517e22a892c7e3f1f'
3
const content = contentHash.decode(encoded)
4
// 'QmRAQB6YaCyidP37UdDnjFY5vQuiBrcqdyoW1CuDgwxkD4'
5
​
6
const onion = 'zqktlwi4fecvo6ri'
7
contentHash.encode('onion', onion);
8
// 'bc037a716b746c776934666563766f367269'
9
​
10
const encoded = 'e40101701b20d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162'
11
​
12
const codec = contentHash.getCodec(encoded) // 'swarm-ns'
13
codec === 'ipfs-ns' // false
Copied!
Note for ipns: For security reasons, the encoding of ipns is only allowed for
libp2p-key codec. Decoding with other formats will show a deprecation warning. Please read here for more detail.Coin type and encoding/decoding
While some libraries allow you to query cryptocurrency addresses via their symbol (e.g.:
BTC), others do not have the built-in support, and you have to call via each coin id (e.g.: 0 for BTC, 16 for `ETH). For Javascript/Typescript, we have @ensdomains/address-encoder library that allows you to convert1
import { formatsByName, formatsByCoinType } from '@ensdomains/address-encoder';
2
​
3
formatsByName['BTC']
4
// {
5
// coinType: 0,
6
// decoder: [Function (anonymous)],
7
// encoder: [Function (anonymous)],
8
// name: 'BTC'
9
// }
Copied!
To save storage space as well as prevent users from setting wrong token address, the library has
encoder and decoder1
const data = formatsByName['BTC'].decoder('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa');
2
console.log(data.toString('hex')); // 76a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1888ac
3
const addr = formatsByCoinType[0].encoder(data);
4
console.log(addr); // 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Copied!
Listing cryptocurrency addresses and text records
For cryptocurrency addresses and text records, you need to know the coin type or key names to get the value. If you want to list down all the cryptocurrency addresses and text records the user has set, you have to either retrieve the information from
Event or query via ENS subgraph.For example
1
{
2
domains(where:{name:"vitalik.eth"}) {
3
id
4
name
5
resolver{
6
texts
7
coinTypes
8
}
9
}
10
}
Copied!
will return the following result
1
{
2
"data": {
3
"domains": [
4
{
5
"id": "0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835",
6
"name": "vitalik.eth",
7
"resolver": {
8
"coinTypes": [
9
60
10
],
11
"texts": [
12
"url"
13
]
14
}
15
}
16
]
17
}
18
}
Copied!
Reverse Resolution
While 'regular' resolution involves mapping from a name to an address, reverse resolution maps from an address back to a name. ENS supports reverse resolution to allow applications to display ENS names in place of hexadecimal addresses.
Reverse resolution is accomplished via the special purpose domain addr.reverse and the resolver function
name(). addr.reverse is owned by a special purpose registrar contract that allocates subdomains to the owner of the matching address - for instance, the address 0x314159265dd8dbb310642f98f50c066173c1259b may claim the name 314159265dd8dbb310642f98f50c066173c1259b.addr.reverse, and configure a resolver and records on it. The resolver in turn supports the name() function, which returns the name associated with that address.ENS does not enforce the accuracy of reverse records - for instance, anyone may claim that the name for their address is 'alice.eth'. To be certain that the claim is accurate, you must always perform a forward resolution for the returned name and check it matches the original address.
Most libraries provide functionality for doing reverse resolution:
ensjs
web3.js
ethjs-ens
ethers.js
go-ens
web3.py
web3j
1
const address = '0x1234...';
2
let ensName = null;
3
({ name: ensName } = await ens.getName(address))
4
// Check to be sure the reverse record is correct. skip check if the name is null
5
if(ensName == null || address != await ens.name(ensName).getAddress()) {
6
ensName = null;
7
}
Copied!
Not supported.
1
var address = '0x1234...';
2
var name = await ens.reverse(address);
3
// Check to be sure the reverse record is correct.
4
if(address != await ens.lookup(name)) {
5
name = null;
6
}
Copied!
1
var address = '0x1234...';
2
var name = await provider.lookupAddress(address);
3
// ethers.js automatically checks that the forward resolution matches.
Copied!
1
name, err := ens.ReverseResolve(client, common.HexToAddress("0x1234...")
Copied!
1
address = '0x1234...'
2
name = ns.reverse(address)
3
# Check to be sure the reverse record is correct.
4
if address != ns.address(name):
5
name = None
Copied!
1
String address = "0x1234...";
2
String name = ens.reverseResolve(address);
3
// Check to be sure the reverse record is correct.
4
if(address != ens.resolve(name)) {
5
name = null;
6
}
Copied!
Reverse resolution without a library follows the same pattern as forward resolution: Get the resolver for
1234....addr.reverse(where 1234... is the address you want to reverse-resolve), and call the name() function on that resolver. Then, perform a forward resolution to verify the record is accurate.If you need to process many addresses (eg: showing reverse record of transaction histories), resolving both reverse and forward resolution for each item may not be practical. We have a seperate smart contract called
ReverseRecords which allows you to lookup multiple names in one function call.1
const namehash = require('eth-ens-namehash');
2
const allnames = await ReverseRecords.getNames(['0x123','0x124'])
3
const validNames = allnames.filter((n) => namehash.normalize(n) === n )
Copied!
Make sure to compare that the returned names match with the normalised names to prevent from homograph attack as well as people simply using capital letters.