Reusable functions and components for the ENS apps

Most functions in this library are async functions and therefore return promises which can be awaited or chained with .then.

npm publish --access public

Contents

• Registry and Resolvers

  • setupENS()
  • getOwner()
  • getResolver()
  • getTTL()
  • getOwnerWithLabelhash()
  • getResolverWithLabelhash()
  • getAddress()
  • getAddr()
  • getContent()
  • getText()
  • getName()
  • getSubdomains()
  • setSubnodeOwner()
  • setSubnodeRecord()
  • setResolver()
  • setAddress()
  • setAddr()
  • setContent() DEPRECATED
  • setContenthash()
  • setText()
  • checkSubdomain()
  • createSubdomain()
  • deleteSubdomain()
  • claimAndSetReverseRecord()
  • setReverseRecord
  • getDomainDetails
  • getSubdomains

• Transaction Response

Setup

Setup for the library is done by calling the setupENS function. It can be optionally provided with a customProvider and an ENS address. Generally you won't need this unless you are running ganache.

It will return an object with the registrar and ens object. The ens object will deal with name resolution, reverse records and dealing with the registry. The registrar object has functions to interact the permanent registrar, legacy auction registrar and test registrar (just on test net)

import { setupENS } from '@ensdomains/ui'

window.addEventListener('load', async () => {
  const { registrar, ens } = await setupENS()
  const owner = await ens.getOwner('resolver.eth')
  // will instantiate with window.web3/window.ethereum if found, read-only if not.
  // Once setup has finished you can now call functions off the library
})

API

async function setupENS(options): void

setupENS must be called before anything other function in this library. We recommend calling it in a window.load event to make sure that your web3 object has loaded. You can provide a custom provider yourself, but by default it will look for window.web3 or window.ethereum if you do not give it a provider. We use the custom provider when we need to run automated tests with ganache. You can also it pass it the registry address, but by default it will derive the network you are on and instantiate ENS using that network's registry. You only need to provider it with an ens address if you are on a private network.

Arguments

options (object): {
  customProvider (object): Provider object from web3 (optional)
  ensAddress (String): Address of the ENS registry (optional)
}

Example

import { setupENS } from '@ensdomains/ui'

window.addEventListener('load', async () => {
  const { ens, registrar } = await setupENS()
})

async function getOwner(name): Address

Arguments

name (String): An ENS name (e.g: vitalik.eth)

Returns

owner (address): Ethereum address of the owner on the registry

Example

const name = 'vitalik.eth'
const owner = await ens.getOwner(name)
// 0x123...

async function getResolver(name): Address

Arguments

name (String): An ENS name (e.g: vitalik.eth)

Returns

owner (address): Ethereum address of the resolver contract

Example

import ens from 'ens'
const owner = await ens.getResolver('vitalik.eth')
// 0x123...

async function getTTL(name): Number

Arguments

name (String): An ENS name (e.g: vitalik.eth)

Returns

ttl (number): Returns the caching time-to-live of the name specified by node. Systems that wish to cache information about a name, including ownership, resolver address, and records, should respect this value. If TTL is zero, new data should be fetched on each query.

Example

import ens from 'ens'
const ttl = await ens.getTTL('resolver.eth')
// 12345

async function getOwnerWithLabelHash(labelHash, nodeHash): Address

Arguments

labelHash (String): Sha3 hash of the label e.g vitalik (vitalik.eth) nodeHash (String): Namehash of the rest of the name (minus the label) e.g eth (vitalik.eth)

Returns

owner (address): Ethereum address of the resolver contract

Example

import ens from 'ens'
const owner = await ens.getOwnerWithLabelHash(labelHash, nodeHash)
// 0x123...

async function getResolverWithLabelHash(labelHash, nodeHash): Address

Arguments

labelHash (String): Hash of the label e.g vitalik (vitalik.eth) nodeHash (String): Hash of the rest of the name (minus the library) e.g eth (vitalik.eth)

Returns

resolver (address): Ethereum address of the resolver contract

Example

const resolver = await ens.getResolverWithLabelHash(labelHash, nodeHash)
// 0x123...

async function getAddress(name): Address

This function will call the resolver to get the address, if it cannot find a resolver, it will return 0x000... as a fallback

Arguments

name (String): An ENS name (e.g: vitalik.eth)

Returns

address (address): An Ethereum address that was set on the resolver

Example

const addr = await ens.getAddress('vitalik.eth')
// 0x123...

async function getAddr(name, key): Address

This function will call the resolver to get the address based on name and coin type of various blockchains, if it cannot find a resolver, it will return 0x000... as a fallback

Arguments

name (String): An ENS name (e.g: vitalik.eth) key (String): CoinType (e.g: ETH, EOS, ETC, specified in address-encoder)

Returns

address (address): A blockchain address that was set on the resolver

Example

const addr = await ens.getAddress('vitalik.eth', 'ETC')
// 0x123...

async function getContent(name): Contenthash

This function will call the resolver to get the contentHash, if it cannot find a resolver, it will return 0x000... as a fallback. Otherwise it will return a contenthash in text format, as defined by EIP1577.

Arguments

name (String): An ENS name (e.g: vitalik.eth)

Returns

contentHash (String): A content hash String for IPFS or swarm

Example

const content = await ens.getContent('vitalik.eth')
// ipfs://Qsxz...

async function getText(name, key): Value

This function gets the reverse record of an address.

Arguments

name (String): ENS name key (String): Any keys. Standard values for key

Returns

value (String): A value

Example

const name = await ens.getText('vitalik.eth', 'url')
// https://vitalik.ca/

async function getName(address): Name

This function gets the reverse record of an address.

Arguments

address (String): An Ethereum address

Returns

name (String): An ENS name

Example

const name = await ens.getName('0x123abc...')
// vitalik.eth

async function getSubdomains(): [Address]

This function gets the reverse record of an address.

Arguments

name (String): An ENS name

Returns

addresses (Array): An ENS name

Example

const name = await ens.getSubdomains('vitalik.eth')
// ['0x123','0x123']

async function setOwner(name, newOwner): TransactionResponse

Arguments

name (String): An ENS name newOwner (String): An Ethereum address or contract

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setOwner('vitalik.eth', '0x123abc...')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setSubnodeOwner(name, newOwner): TransactionResponse

Can only be called by the controller of the parent name.

Arguments

name (String): An ENS name newOwner (String): An Ethereum address or contract

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setSubnodeOwner('sub.vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setSubnodeRecord(name, newOwner, resolver): TransactionResponse

Sets the record for a subnode. Can only be called by the controller of the parent name.

Arguments

name (String): An ENS name newOwner (String): An Ethereum address or contract resolver (Address): Resolver

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setSubnodeRecord(
  'subnode.resolver.eth',
  '0x134',
  '0x123'
)

console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setResolver(name, resolver): TransactionResponse

Can only be called by the controller of the name.

Arguments

name (String): An ENS name resolver (String): An ENS resolver contract

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setResolver('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setAddress(name, address): TransactionResponse

Can only be called by the controller of the name.

Arguments

name (String): An ENS name address (String): An Ethereum address

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setAddress('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setAddr(name, key, address): TransactionResponse

Can only be called by the controller of the name.

Arguments

name (String): An ENS name key (String): CoinType (e.g: ETH, EOS, ETC, specified in address-encoder) address (String): An Ethereum address

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setAddr(
  'vitalik.eth',
  'ETH',
  '0x0000000000000000000000000000000000012345'
)

console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setContent(name, content): TransactionResponse (DEPRECATED)

Can only be called by the controller of the name.

This function has been deprecated in favour of setContenthash which uses EIP1577

Arguments

name (String): An ENS name content (String): A content hash

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setContent('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setContenthash(name, content): TransactionResponse

Can only be called by the controller of the name.

Arguments

name (String): An ENS name contenthash (String): A content hash defined by EIP1577

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setContent('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setText(name, key, value): TransactionResponse

Sets text metadata for node with the unique key key to value, overwriting anything previously stored for node and key. To clear a text field, set it to the empty string.

Arguments

name (String): An ENS name key (String): key value (String): Value

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setText('vitalik.eth', 'url', 'vitalik.ca')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function createSubdomain(name): TransactionResponse

Can only be called by the controller of the name. This is a simplified version of setSubnodeOwner which it uses underneath to create a subdomain. It will automatically set the owner to the parent's names owner. If you call this function on an existing subdomain, it will change its owner to the current parent owner.

Arguments

name (String): An ENS name (sub.vitalik.eth)

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.createSubdomain('sub', 'vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function deleteSubdomain(label, name): TransactionResponse

Can only be called by the controller of the name. This function will set the controller to 0x000... and if it has a resolver, it will set the resolver 0x000..., which will be a second transaction. Alternatively you can manually call setSubnodeOwner and set the controller to 0x000...

Arguments

label (String): ENS Label e.g: sub (sub.vitalik.eth) name (String): An ENS name

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.deleteSubdomain('sub', 'vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function claimAndSetReverseRecordName(name): TransactionResponse

This function will claim your Ethereum address on the reverse registrar, setup the reverse resolver and setup your name on the resolver all in one transaction. It can also be used to change your reverse record name to something else.

Arguments

name (String): An ENS name

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.claimAndSetReverseRecordName('vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function setReverseRecordName(name): TransactionResponse

This function will set your reverse record name given that a resolver is already present on your ethereum address reverse name e.g. 123456abcdef.addr.reverse. This can be useful if you don't want to use claimAndSetReverseRecordName to setup the default reverse registrar

Arguments

name (String): An ENS name

Returns

transaction (object): Transaction Response Object

Example

const tx = await ens.setReverseRecordName('vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined

async function getDomainDetails(name): DomainDetails

This is a helper function to get all the details for a particular domain.

Arguments

name (String): An ENS name

Returns

DomainDetails (object): {
  name (String): ENS name
  label (String): label of the name
  labelhash (String): labelhash of the name
  owner (String): Address of the controller of the ENS name
  resolver (String): ENS resolver contract
  addr (String): Address the ENS name resolves to
  content (String): Contenthash the ENS name resolves to
}

Example

const domainDetails = await ens.getDomainDetails('vitalik.eth')
console.log(domainDetails)
/* 
  {
    name: "vitalik.eth",
    label: "vitalik",
    labelhash: "0x123456abc...",
    owner: "0x123abcdef...",
    resolver: "0x1234abdef...",
    addr: "0xabcdef1234...",
    content: "bzz://Qra123..."
  }
*/

async function getSubdomains(name): Array<Subdomain>

This is a helper function to get all the subdomains for a name. Internally it will search for events for the NewOwner and filter out duplicates.

Arguments

name (String): An ENS name

Returns

Subdomains (Array<Subdomain>): {
  name (String): ENS name
  label (String): label of the name
  labelhash: labelhash of the name
  owner (String): Address of the controller of the ENS name
  decrypted (boolean): Whether the label is known or not
}

Example

const subdomains = await ens.getSubdomains('vitalik.eth')
console.log(subdomains)
/* 
  [{
    name: "vitalik.eth",
    label: "vitalik",
    labelhash: "0x123456abc...",
    owner: "0x123abcdef...",
    decrypted: true
  }, ...]
*/

Transaction Response

The transaction response object gets returned by the promise of all state modifying functions of the library. The most important properties is the wait function which can be called by the initial response, before the transaction has been mined. You can await this promise and it will give you the transaction receipt. The transaction receipt, is the same as the transaction response object, except is has a blockHash, blockNumber and timestamp of the block the transaction has been included in.

{
    // Only available for unmined transactions
    wait: function(){}, //this function is to wait for the transaction to be mined
    // Only available for mined transactions
    blockHash: "0x7f20ef60e9f91896b7ebb0962a18b8defb5e9074e62e1b6cde992648fe78794b",
    blockNumber: 3346463,
    timestamp: 1489440489,

    // Exactly one of these will be present (send vs. deploy contract)
    // They will always be a properly formatted checksum address
    creates: null,
    to: "0xc149Be1bcDFa69a94384b46A1F91350E5f81c1AB",

    // The transaction hash
    hash: "0xf517872f3c466c2e1520e35ad943d833fdca5a6739cfea9e686c4c1b3ab1022e",

    // See above "Transaction Requests" for details
    data: "0x",
    from: "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
    gasLimit: utils.bigNumberify("90000"),
    gasPrice: utils.bigNumberify("21488430592"),
    nonce: 0,
    value: utils.parseEther(1.0017071732629267),

    // The chain ID; 0 indicates replay-attack vulnerable
    // (eg. 1 = Homestead mainnet, 3 = Ropsten testnet)
    chainId: 1,

    // The signature of the transaction (TestRPC may fail to include these)
    r: "0x5b13ef45ce3faf69d1f40f9d15b0070cc9e2c92f3df79ad46d5b3226d7f3d1e8",
    s: "0x535236e497c59e3fba93b78e124305c7c9b20db0f8531b015066725e4bb31de6",
    v: 37,

    // The raw transaction (TestRPC may be missing this)
    raw: "0xf87083154262850500cf6e0083015f9094c149be1bcdfa69a94384b46a1f913" +
           "50e5f81c1ab880de6c75de74c236c8025a05b13ef45ce3faf69d1f40f9d15b0" +
           "070cc9e2c92f3df79ad46d5b3226d7f3d1e8a0535236e497c59e3fba93b78e1" +
           "24305c7c9b20db0f8531b015066725e4bb31de6",
}