How do ENS names work?

An ENS name works through three contracts on Ethereum: a registry that records who controls each name, a registrar that rents out names ending in the protocol's eth suffix by the year, and a resolver that stores what the name points to, such as a payment address. You hold the name as a token in your own wallet, you keep it for as long as the yearly fee is paid, and anyone can look up its records without asking permission.

The Ethereum Name Service, ENS for short, describes itself in its documentation as a distributed, open and extensible naming system based on the Ethereum blockchain. This article takes its mechanisms one by one, from registration to resale, with the fee levels read in the protocol's own documentation at the time of writing. Fees are set by the protocol's governance and can change, so read the current figure before you budget.

What do the registry, the registrar and the resolver each do?

The ENS registry lists every name with its owner, its resolver and a time-to-live value; a registrar decides who may obtain a name under a given suffix; and a resolver answers the question of what the name points to. The three are separate contracts, and keeping them apart is the reason a name can change hands without its records moving, or change records without changing hands.

The registry is the starting point of every lookup. According to the ENS documentation, it stores three things per name: the owner, which is the address that controls the name; the resolver, which is the contract that answers lookups; and the time-to-live. The address recorded there can set a different resolver, hand the entry to another address, create names one level below, and approve an operator to act on its behalf.

A registrar is the contract that owns a suffix and sets the rules for handing out names under it. For names ending in the eth suffix, the work is divided in two: a base registrar that keeps ownership and transfers, and a controller that handles registration and renewal pricing. The documentation gives the reason for the division: it keeps the part that holds ownership small and stable, so that the pricing logic can be replaced without touching who owns what.

How is an ENS name registered, and why does it take two transactions?

An ENS name under the eth suffix is registered in two transactions, a commitment and then the registration itself, so that nobody watching pending transactions can see which name you want and register it ahead of you. The first transaction publishes only a hash; the name is revealed in the second.

The controller checks the age of the commitment before it accepts the registration. The ENS documentation states that the commitment must be at least one minute old and no more than 24 hours old. Leave the second transaction too long and the commitment lapses, in which case you start again with a new one.

Each of the two transactions also costs network gas, which is paid to the network and not to the protocol.

What does an ENS name cost per year?

At the time of writing, the ENS documentation prices a name under the eth suffix at $5 a year for five characters or more, $160 a year for four characters and $640 a year for three characters. The fee is set in US dollars and paid in ETH, converted at a price fed to the contract at the moment of the transaction.

The length scale is steep: a three-character name costs 128 times a name of five characters or more, and a four-character name 32 times. The protocol's support documentation explains the reasoning: shorter names are scarcer, and the fee exists to discourage registering names only to sit on them and to fund the continued development of the protocol through its decentralised organisation. The documentation states that registration funds are forwarded to the ENS treasury.

Because the fee is a dollar figure paid in a volatile asset, the amount of ETH due can move between the time your wallet prepares the transaction and the time it confirms. The documentation recommends sending slightly more than the quoted price, and the protocol's own manager application adds 10% to its estimate; the excess comes back in the same transaction. On a five-year registration of a four-character name, priced at $800, that means sending the equivalent of $880 and receiving the equivalent of $80 back if the ETH price has not moved.

The fee buys time, not title: the name is rented from the protocol, and the token in your wallet represents the right to it until the expiry date.

What does renewing an ENS name cost over several years?

Renewing an ENS name costs the yearly fee for its length multiplied by the number of years, so at the fee levels in the ENS documentation at the time of writing a name of five letters or more costs $25 over five years, a four-letter name $800 and a three-letter name $3,200. Gas is added once per renewal transaction, whatever the number of years bought.

The table below is a worked example at those three fee levels, with no change of fee over the period, which is an assumption and not a promise: the fee can be changed by governance.

For anyone holding several names, the short ones drive the budget. Take a worked example of a 16-name portfolio: twelve names of five letters or more, three four-letter names and one three-letter name.

The whole portfolio renews for $1,180 a year, or $5,900 over five years. The single three-letter name is 54% of that bill and the twelve longest names together are 5%. A holder deciding which names to keep is therefore deciding almost entirely about the short ones.

One feature of renewal surprises newcomers: according to the ENS documentation, any account can renew a name, not only its owner, and for any duration. Paying a renewal gives the payer no right over the name.

What happens when an ENS name expires?

When an ENS name under the eth suffix expires, it enters a 90-day grace period in which it can still be renewed at the normal fee, and after that it is released to the public with a temporary premium that falls to zero over 21 days. The durations are those stated in the ENS documentation at the time of writing.

During the grace period nobody else can register the name. Renewing it costs the ordinary yearly fee, with no penalty. For a wrapped name, a state covered further down, the documentation is specific: the owner keeps ownership during the grace period but cannot unwrap or update the name until it is renewed.

On the day the grace period ends, the name becomes available to anyone, with an extra charge on top of the yearly fee. The protocol calls it the temporary premium and runs it as a descending-price sale: the premium starts at about $100 million, a level meant to be out of anyone's reach, and decreases exponentially, quickly on the first day and more slowly as it approaches zero on day 21. Whoever registers first pays the premium of that moment plus the yearly fee. The premium is paid once; later renewals are at the ordinary fee.

For the former holder, after the grace period, getting the name back means bidding against everyone else. Counting from the expiry date, the name is protected until day 90 and carries a premium until day 111.

What is the difference between the owner and the manager of an ENS name?

The owner of an ENS name holds the token and has the last word, and the manager is the address allowed to change the resolver and edit the records. The two roles exist separately on unwrapped names under the eth suffix, and they can be given to two different addresses.

The protocol's support documentation calls the owner the ultimate owner of the name: the owner can transfer the name and can replace the manager at any time. The manager, formerly called the controller, runs the name day to day: it can change the resolver and add or edit records.

The separation is useful. A company can keep ownership in a wallet that several signers must approve, stored offline, and give the manager role to an operational wallet that updates addresses and records. The risk is the mirror image: a manager you forgot about can still repoint the name, including its payment address, until the owner replaces it.

A wrapped name has no separate manager. The documentation states that once a name is wrapped, a single account is both owner and manager.

What records can an ENS name hold, and how is a name resolved?

An ENS name can hold addresses for Ethereum and for many other networks, free-form text records and a content record, all stored in its resolver, and resolving the name takes two steps: ask the registry which resolver serves the name, then ask that resolver for the record wanted. The ENS documentation states that resolution always starts from the Ethereum main network, whichever network the answer concerns.

Address records are stored per network. Each network has a numeric identifier, and a name can carry one address for each, so the same name can point to an Ethereum address, an address on a second-layer network and an address on an unrelated chain. A wallet that resolves a name for a payment asks for the address of the network it is about to use; if that record was never set, a careful wallet declines to guess.

Text records are pairs of a key and a value. The protocol's standards define a common set, among them an avatar image, a description, a website and handles on social and code-hosting platforms, and any application can define its own keys, with a prefix recommended to avoid collisions. Everything in a resolver is public. Do not put in a record what you would not publish.

What are reverse resolution and a primary name?

Reverse resolution goes from an address to a name, and a primary name is the name an address has chosen to be shown as. The ENS documentation defines a primary name as a two-way link: the address declares the name, and the name's own address record points back to that address.

Both halves are needed because the two records are set by different parties. The address record of a name is set by the name's manager. The reverse record is set by the holder of the address, through a contract the protocol calls the reverse registrar. Anyone could set a reverse record claiming a name they do not control, so the documentation instructs applications to always follow a reverse lookup with a forward lookup, and to show the raw address if the two do not match.

Owning a name therefore does not make it appear next to your address in applications; you have to set it as primary from the address concerned. The same name can be owned by one wallet and be the primary name of another, provided the name's address record points to that other wallet.

How do ENS subnames work?

A subname is a name one level below another, created by the owner of the parent name, and it resolves exactly like any other name with its own owner, resolver and records. The ENS registry gives the address that controls a name the power to create names beneath it, at any depth.

No yearly protocol fee is collected for a subname: the fee by length is charged by the registrar controller for names directly under the eth suffix, and a subname is created by a registry operation that costs network gas only. A business can register one name and issue a subname per department, per client or per payment purpose.

The point to understand is who is in charge. On an unwrapped parent, a subname is held at the parent owner's discretion: the parent can replace its owner or take it back. That is acceptable inside one company and not acceptable for a subname sold to a stranger. The name wrapper, next, was built to give subname holders guarantees the parent cannot withdraw.

What does wrapping an ENS name change?

Wrapping an ENS name hands it to a contract called the Name Wrapper, which issues an ERC-1155 token in its place and lets permissions be removed for good, on the name itself and on its subnames. According to the ENS documentation, any name under the eth suffix, any subname and any imported DNS name can be wrapped, where previously only names directly under the eth suffix were tokens, under the ERC-721 standard.

Three things change for the holder. The owner and manager roles merge into one account. The name becomes a token under a different standard, which matters to marketplaces and to contracts that accept only one of the two. And the name gains a set of switches the documentation calls fuses. A fuse can be burned and never restored while the name's expiry lasts. Owner-controlled fuses give up a permission: one of them, for instance, prevents the wrapped token from being transferred. Parent-controlled fuses are burned by the parent on a subname and grant its holder something, such as the ability to extend the subname's own expiry.

The documentation describes the resulting states. A wrapped subname can still be replaced by its parent. An emancipated name can no longer be replaced or have further fuses burned by its parent; a name directly under the eth suffix reaches this state automatically when wrapped. A locked name can no longer be unwrapped. Every wrapped name carries an expiry, and a subname's expiry cannot exceed its parent's. For a name directly under the eth suffix, the wrapper's expiry is the end of the registrar's grace period. When an emancipated or locked name reaches its expiry, its owner loses it.

Before you buy a wrapped name, read which fuses are burned. A name whose transfer permission has been given up cannot be delivered to you at all, and a parent name with emancipated subnames comes with holders you cannot remove before their expiry.

Can a DNS name be imported into ENS?

Yes: a name from the traditional domain name system can be brought into ENS by its registrant, provided the name is secured with DNSSEC and carries a text record naming the Ethereum address or resolver to use. The ENS documentation covers the process through a dedicated DNS registrar, and notes that DNSSEC builds its chain of trust from a root key signed by ICANN.

Two methods exist. In the onchain method, the registrant enables DNSSEC, publishes a text record containing an Ethereum address, and submits the signed proof to the registrar contract. The documentation states that there is no ENS protocol fee, and that submitting the proof can require up to a few million units of gas, which makes it an expensive transaction on a busy day. In the gasless method, the registrant publishes a text record naming a resolver, and the proof is fetched and verified each time the name is looked up, so nothing is stored on Ethereum and the registrant pays no gas.

An imported name behaves differently from a name under the eth suffix on the points that matter commercially. No yearly fee is paid to the ENS protocol, but the name remains registered in the traditional system: it is renewed with its domain registrar, under that registry's rules, and control in ENS follows whoever controls the DNS records and can publish a new proof. A buyer of such a name is buying a traditional domain first, with its ENS presence as a consequence.

What transfers when an ENS name is sold?

When an ENS name is sold, what transfers is the token, and with it the owner role and the remaining registration time; the records, the manager role on an unwrapped name and the seller's primary name setting do not update by themselves. The protocol's support documentation says it in one sentence: sending a name to another address will not update the records, or make it the primary name for the new address.

The second and third rows are the ones that cost money when missed. Until the buyer changes the address record, a payment sent to the name still arrives at the seller's address. Until the buyer takes the manager role on an unwrapped name, the previous manager can still edit the records. The first two actions after a purchase are therefore to take the manager role and to rewrite the records.

On the payment itself, the name is a token and the price is usually paid in ETH or a stablecoin, so both legs can be exchanged in a single transaction through a marketplace contract, or handled by an escrow service or a broker when the amount or the parties call for one. Either way, read the name's state before the price is paid, not after.

What should you check before buying or relying on an ENS name?

Before buying an ENS name or sending money to one, check five things that the contracts show publicly: the expiry date, whether the name is wrapped and which permissions are gone, who the owner and manager are, what the address record says for the network you will use, and which subnames exist.

• Expiry. Read the date and count the 90-day grace period. A name sold with a few weeks left is not a problem if you renew at once, since anyone can pay a renewal.
• Wrapped or not. The token standard differs, and a wrapped name can carry burned fuses. Confirm the token can be transferred and, if you intend to unwrap it, that it still can be.
• Owner and manager. On an unwrapped name, see whether a third address is manager, and plan to replace it.
• Records. If you are paying someone through their name, resolve it yourself for the right network and compare the address with one confirmed through a second channel. If you are buying, expect every record to be the seller's.
• Subnames. A parent name with subnames issued to third parties carries commitments. On a wrapped parent, emancipated subnames stay with their holders until they expire.