Skip to main content

How do ENSv1 names work?

How ENSv1 names are structured: the Registry, Resolvers and the .eth Registrar, and how a lookup finds a record.

ENSv1 names are built on three kinds of smart contract. The Registry records who controls each name and where its records live, Resolvers store the records, and Registrars issue names. Every lookup is the same two steps: ask the Registry which Resolver a name uses, then ask that Resolver for the record.

You don't need any of this to register, manage or use a name. It's here for anyone who wants to know what happens underneath.

The ENS Registry

The Registry is a single smart contract that lists every ENSv1 name. For each name it stores two things: the Manager, the account that controls the name, and the Resolver, the contract that holds its records.

The Registry table, with Node, Controller and Resolver columns

The Registry holds more than .eth names. DNS names (like domain.com) and subnames (like sub.name.eth) have entries too.

The Manager can change the Resolver, create or update subnames, or hand the role to another account.

Resolvers

A Resolver is a smart contract that stores a name's records. A record can be an ETH address, another cryptocurrency address such as Bitcoin, or text like an email address or social handles.

The Registry pointing names to a default and a custom Resolver

If a name has no Resolver set in the Registry, it has no records and does not resolve.

How a lookup works

To find the ETH address for name.eth:

  1. Ask the Registry which Resolver name.eth uses.

  2. Ask that Resolver for the ETH address record, and it returns the address.

A sequence diagram of the two lookup calls

The .eth Registrar

A Registrar is a smart contract that controls a top-level name and issues subnames under it. Each Registrar sets its own rules, such as pricing and character limits.

The .eth Registrar owns the 'eth' name and issues names like name.eth. Registering one mints an NFT to the Owner, which is why it is often called the NFT contract for ENS names.

The .eth Registrar issuing names and minting their NFTs

The Owner holds the NFT and has final control of the name. Under ENSv1, ownership and management are separate roles, but registering a name sets the Owner as Manager too. You can set a different Manager later, and the Owner can always take the role back.

Names of three or more characters can be registered, and pricing depends on name length. Every .eth name has an expiry date. Renewing before it expires adds time to that date and keeps the name yours.

Upgrading to ENSv2 is optional and isn't available on Ethereum Mainnet yet. An ENSv1 name keeps working as it is, and you can stay on ENSv1. When you do upgrade, the name keeps its records. See Upgrade your name to ENSv2.

Some names are also wrapped with the Name Wrapper, ENSv1 technology that changes how ownership and permissions work. See What is the Name Wrapper?.

Did this answer your question?