The Ethereum Name Service (ENS) is a distributed, open, and extensible naming system based on the Ethereum blockchain.
ENS’s job is to map human-readable names like ‘alice.eth’ to machine-readable identifiers such as Ethereum addresses, other cryptocurrency addresses, content hashes, and metadata. ENS also supports ‘reverse resolution’, making it possible to associate metadata such as canonical names or interface descriptions with Ethereum addresses.
ENS has similar goals to DNS, the Internet’s Domain Name Service, but has significantly different architecture due to the capabilities and constraints provided by the Ethereum blockchain. Like DNS, ENS operates on a system of dot-separated hierarchical names called domains, with the owner of a domain having full control over subdomains.
Top-level domains, like ‘.eth’ and ‘.test’, are owned by smart contracts called registrars, which specify rules governing the allocation of their subdomains. Anyone may, by following the rules imposed by these registrar contracts, obtain ownership of a domain for their own use. ENS also supports importing in DNS names already owned by the user for use on ENS.
Because of the hierarchal nature of ENS, anyone who owns a domain at any level may configure subdomains - for themselves or others - as desired. For instance, if Alice owns 'alice.eth', she can create 'pay.alice.eth' and configure it as she wishes.
ENS has two principal components: the registry, and resolvers.The ENS registry consists of a single smart contract that maintains a list of all domains and subdomains, and stores three critical pieces of information about each:
The owner of the domainThe resolver for the domainThe caching time-to-live for all records under the domain
The owner of a domain may be either an external account (a user) or a smart contract. A registrar is simply a smart contract that owns a domain and issues subdomains of that domain to users that follow some set of rules defined in the contract.Owners of domains in the ENS registry may:
Set the resolver and TTL for the domainTransfer ownership of the domain to another addressChange the ownership of subdomains
The ENS registry is deliberately straightforward and exists only to map from a name to the resolver responsible for it.Resolvers are responsible for the actual process of translating names into addresses. Any contract that implements the relevant standards may act as a resolver in ENS. General-purpose resolver implementations are offered for users whose requirements are straightforward, such as serving an infrequently changed address for a name.Each record type - cryptocurrency address, IPFS content hash, and so forth - defines a method or methods that a resolver must implement in order to provide records of that kind. New record types may be defined at any time via the EIP standardization process, with no need to make changes to the ENS registry or to existing resolvers in order to support them.Resolving a name in ENS is a two-step process: First, ask the registry what resolver is responsible for the name, and second, ask that resolver for the answer to your query.In the above example, we're trying to find the Ethereum address pointed to by 'foo.eth'. First, we ask the registry which resolver is responsible for 'foo.eth'. Then, we query that resolver for the address of 'foo.eth'.
Controller: The account that may edit the records of a name. The Controller may be changed by the Registrant or Controller.
Label: An individual component of a name, such as 'alice'.
Labelhash: The keccak256 hash of an individual label.
Name: An ENS identifier such as 'alice.eth'. Names may consist of multiple parts, called labels, separated by dots.
Namehash: The algorithm used to process an ENS name and return a cryptographic hash uniquely identifying that name. Namehash takes a name as input and produces a node.
Node: A cryptographic hash uniquely identifying a name.
Owner: The owner of a name is the entity referenced in the ENS registry's owner field. An owner may transfer ownership, set a resolver or TTL, and create or reassign subdomains.
Registrar: A registrar is a contract responsible for allocating subdomains. Registrars can be configured at any level of ENS, and are pointed to by the owner field of the registry.
Registration: A registration is a registrar's record of a user's ownership of a name. This is distinct from the owner field in the Registry; registrations are maintained in the registrar contract and additionally store information on expiry date, fees paid, etc.
Registrant: The owner of a registration. The registrant may transfer the registration, set the Controller, and reclaim ownership of the name in the registry if required.
Registry: The core contract of ENS, the registry maintains a mapping from domain name (at any level - x, y.x, z.y.x etc) to owner, resolver, and time-to-live.
Resolver: A resolver is a contract that maps from name to the resource (e.g., cryptocurrency addresses, content hash, etc). Resolvers are pointed to by the resolver field of the registry.
About the ENS Registry:
Hashes provide a fixed length identifier that can easily be passed around between contracts with fixed overhead and no issues passing around variable-length strings.
A partial list can be seen on our homepage.
Yes. You can create whatever subdomains you wish and assign ownership of them to other people if you desire. You can even set up your own registrar for your domain.
Yes, you can update the addresses and other resources pointed to by your name at any time.
No. We consider ENS to be part of the 'global namespace' inhabited by DNS, and so we do our best not to pollute that namespace. ENS-specific TLDs are restricted to only .eth (on mainnet), or .eth and .test (on Ropsten), plus any special purpose TLDs such as those required to permit reverse lookups.In addition to that, we are deploying support for importing DNS domains from the majority of DNS top-level domains using an integration that relies on DNSSEC. For details on those plans, please read this post.
The root node is presently owned by a multisig contract, with keys held by trustworthy individuals in the Ethereum community. We expect that this will be hands-off, with the root ownership only used to effect administrative changes, such as the introduction of a new TLD, or to recover from an emergency such as a critical vulnerability in a TLD registrar.The keyholders are drawn from respected members of the community, and with the exception of Nick Johnson, founder of ENS, are unaffiliated with ENS. We ask and expect them to exercise their individual judgement acting in the interests of the ENS community, rather than rubber-stamping requests made to them by ENS developers.Since the owner of a node can change ownership of a subnode (unless they have otherwise locked it from their control), the owner of the root can change any node in the ENS tree. This means that the keyholders can replace the contracts that govern issuing and managing domains, giving them ultimate control over the structure of the ENS system and the names registered in it. However, the root key holders have locked control of the .eth registrar contract, which means that even keyholders cannot affect the ownership of .eth domains.The keyholders are still capable of doing the followings:
Over time, we plan to reduce and decentralise human control over the system. Powers still held by the ENS root, such as those to set pricing and renewal conditions for domains, will be decentralised as robust systems become available to permit doing so.
Since the ENS contracts only deal with hashes, they have no direct way to enforce limits on what can be registered; character length restrictions are implemented by allowing users to challenge a short name by providing its preimage to prove it’s too short.This means that you can in theory register both ‘foo.eth’ and ‘FOO.eth’, or even <picture of my cat>.eth. However, resolvers such as browsers and wallets should apply the nameprep algorithm to any names users enter before resolving; as a result, names that are not valid outputs of nameprep will not be resolvable by standard resolvers, making them effectively useless. Dapps that assist users with registering names should prevent users from registering unresolvable names by using nameprep to preprocess names being requested for registration.
It’s not enforced by the ENS contracts, but, as described above, resolvers are expected to use it before resolving names. This means that non-nameprep names will not be resolvable.
ENS complements and extends the usefulness of DNS with decentralised, trustworthy name resolution for web3 resources such as blockchain addresses and distributed content, while Namecoin and Handshake are efforts to replace all or part of DNS with a blockchain-based alternative.
The ENS Manager App and the Twitter bot have built-in lists of common names, drawn from an English dictionary and Alexa’s list of top 1 million Internet domain names. They use these lists to show you when common names are bought or renewed. We do this because if the app didn’t reveal these names, anyone with a little technical skill could find them out anyway, giving them an advantage over those who don’t have the capacity to build their own list and code to check names against it.
Currently, registration costs are set at the following prices:
3 and 4 character names have higher pricing to reflect the small number of these names available.
After your name expires, there is a 90 day grace period in which the owner can't edit the records but can still re-register the name. After the grace period, the name is released for registration by anyone with a temporary premium which decreases over a 21 days period. The released name continues to resolve your ETH address until the new owner overwrites it.
The .eth registrar is structured such that names, once issued, cannot be revoked so long as an active registration is maintaine
The registrar uses two transactions (commit and reveal) to register a name.
It takes less than 5 minutes to register a name, including a 1-minute delay between the first and second transactions to prevent frontrunning.
Make sure you renew your ENS names before they expire! You add registration years to any name at any time, and for any duration you'd like.
You can add registration years to many names at a time on your My Account page in the ENS Manager App.
Anyone can add registration years to any existing name by paying the required fee, at any time. There is no maximum limitation of the renewal duration but there is a minimum renewal period of 28 days.
You can renew your name at any time during the period you own it. Making sure you renew before the name expires will prevent someone else from registering the name. There is also a 'grace period' of 90 days after your name expires. You can renew the name to retain ownership of it during the grace period.
Yearly renewals cost $5/year for names that are 5 characters or longer. 4 character names cost $160/year, and 3 character names cost $640/year. Fees are paid in ETH. The ETH/USD exchange rate is set by the Chainlink ETH/USD oracle.
Rather than being locked and held, as in the original interim registrar, renewal fees in the permanent registrar are spent. You will not get them back.
Funds are sent to the ENS root multisig, for the keyholders to determine how funds get allocated. We're considering multiple options for the long-term use of the funds, such as funding the core ENS team, as well as other teams building on ENS. There are also tax considerations to address.
It's ultimately up to the keyholders to allocate the funds. We hope they will fund ENS ecosystems projects. If available funds exceed the reasonable needs of the ENS ecosystem, we hope other Ethereum projects will receive them.
Simply go to app.ens.domains and click on "My Account".
Yes, .eth names are tradeable as NFTs.
You can do this using our Manager interface here, or using any tool with NFT support.
The cost of doing this is the only limitation in place.
The registrant is the account that owns the .eth name. They can transfer ownership to another account, and they can replace the controller address. The registrant is the owner of the NFT token that represents the name.The controller is the account that controls day-to-day operations with the name: creating subdomains, setting the resolver and records, and so forth.
ENS has documentation for a variety of audiences, including dapp developers and contract developers, as well as reference documentation.
Check out the dapp developer guide, starting with ENS Enabling your Dapp. You'll want to choose one of the many available ENS Libraries to get started working with ENS.
Check out the Contract Developer Guide, starting with Resolving Names On-chain. You can also write your own resolver(to customise the process of looking up names), or your own registrar (to customise the process of registering new names).
Check out the Contract API Reference. We have reference documentation for ENS's core contract, the registry, for resolvers, and for commonly-used registrars such as the Test registrar, reverse registrar, and the .eth registrar.