Most functions in this library are async functions and therefore return promises which can be awaited or chained with .then.
-
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
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
})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.
options (object): {
customProvider (object): Provider object from web3 (optional)
ensAddress (String): Address of the ENS registry (optional)
}
import { setupENS } from '@ensdomains/ui'
window.addEventListener('load', async () => {
const { ens, registrar } = await setupENS()
})name (String): An ENS name (e.g: vitalik.eth)
owner (address): Ethereum address of the owner on the registry
const name = 'vitalik.eth'
const owner = await ens.getOwner(name)
// 0x123...name (String): An ENS name (e.g: vitalik.eth)
owner (address): Ethereum address of the resolver contract
import ens from 'ens'
const owner = await ens.getResolver('vitalik.eth')
// 0x123...name (String): An ENS name (e.g: vitalik.eth)
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.
import ens from 'ens'
const ttl = await ens.getTTL('resolver.eth')
// 12345labelHash (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)
owner (address): Ethereum address of the resolver contract
import ens from 'ens'
const owner = await ens.getOwnerWithLabelHash(labelHash, nodeHash)
// 0x123...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)
resolver (address): Ethereum address of the resolver contract
const resolver = await ens.getResolverWithLabelHash(labelHash, nodeHash)
// 0x123...This function will call the resolver to get the address, if it cannot find a resolver, it will return 0x000... as a fallback
name (String): An ENS name (e.g: vitalik.eth)
address (address): An Ethereum address that was set on the resolver
const addr = await ens.getAddress('vitalik.eth')
// 0x123...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
name (String): An ENS name (e.g: vitalik.eth) key (String): CoinType (e.g: ETH, EOS, ETC, specified in address-encoder)
address (address): A blockchain address that was set on the resolver
const addr = await ens.getAddress('vitalik.eth', 'ETC')
// 0x123...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.
name (String): An ENS name (e.g: vitalik.eth)
contentHash (String): A content hash String for IPFS or swarm
const content = await ens.getContent('vitalik.eth')
// ipfs://Qsxz...This function gets the reverse record of an address.
name (String): ENS name key (String): Any keys. Standard values for key
value (String): A value
const name = await ens.getText('vitalik.eth', 'url')
// https://vitalik.ca/This function gets the reverse record of an address.
address (String): An Ethereum address
name (String): An ENS name
const name = await ens.getName('0x123abc...')
// vitalik.ethThis function gets the reverse record of an address.
name (String): An ENS name
addresses (Array): An ENS name
const name = await ens.getSubdomains('vitalik.eth')
// ['0x123','0x123']name (String): An ENS name newOwner (String): An Ethereum address or contract
transaction (object): Transaction Response Object
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 minedCan only be called by the controller of the parent name.
name (String): An ENS name newOwner (String): An Ethereum address or contract
transaction (object): Transaction Response Object
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 minedSets the record for a subnode. Can only be called by the controller of the parent name.
name (String): An ENS name newOwner (String): An Ethereum address or contract resolver (Address): Resolver
transaction (object): Transaction Response Object
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 minedCan only be called by the controller of the name.
name (String): An ENS name resolver (String): An ENS resolver contract
transaction (object): Transaction Response Object
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 minedCan only be called by the controller of the name.
name (String): An ENS name address (String): An Ethereum address
transaction (object): Transaction Response Object
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 minedCan only be called by the controller of the name.
name (String): An ENS name key (String): CoinType (e.g: ETH, EOS, ETC, specified in address-encoder) address (String): An Ethereum address
transaction (object): Transaction Response Object
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 minedCan only be called by the controller of the name.
This function has been deprecated in favour of setContenthash which uses EIP1577
name (String): An ENS name content (String): A content hash
transaction (object): Transaction Response Object
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 minedCan only be called by the controller of the name.
name (String): An ENS name contenthash (String): A content hash defined by EIP1577
transaction (object): Transaction Response Object
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 minedSets 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.
name (String): An ENS name key (String): key value (String): Value
transaction (object): Transaction Response Object
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 minedCan 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.
name (String): An ENS name (sub.vitalik.eth)
transaction (object): Transaction Response Object
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 minedCan 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...
label (String): ENS Label e.g: sub (sub.vitalik.eth) name (String): An ENS name
transaction (object): Transaction Response Object
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 minedThis 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.
name (String): An ENS name
transaction (object): Transaction Response Object
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 minedThis 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
name (String): An ENS name
transaction (object): Transaction Response Object
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 minedThis is a helper function to get all the details for a particular domain.
name (String): An ENS name
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
}
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..."
}
*/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.
name (String): An ENS name
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
}
const subdomains = await ens.getSubdomains('vitalik.eth')
console.log(subdomains)
/*
[{
name: "vitalik.eth",
label: "vitalik",
labelhash: "0x123456abc...",
owner: "0x123abcdef...",
decrypted: true
}, ...]
*/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",
}