CNS Architecture Overview

This page covers the following topics:

• Smart Contract Architecture — An overview of the core smart contracts that make up CNS. This section explains how domains are minted and managed, what domain information is stored, and how members can interact with those domains through a blockchain.
• Domain Hierarchy and Ownership — All things subdomains. How they can be structured, created, and managed.
• Delegating Domain Management — Explains the role of the transaction processor and meta transactions in minting domains and allowing members to delegate transaction costs.

Unstoppable Domains are built on CNS — the Crypto Name Service. CNS is a set of smart contracts on the Ethereum blockchain that govern how domains are created and used. Although it serves a similar purpose as a traditional DNS system, CNS has architectural differences that change the interaction model significantly. For example, CNS domains are owned irrevocably. They do not need to be renewed and cannot be reclaimed by Unstoppable Domains. Once minted, members have complete control of their domains.

Every CNS domain is issued as an ERC-721 token. Building on this standard makes it easier for developers to integrate with Unstoppable Domains and it lets members manage their domain ownership from any compatible wallet, exchange, or marketplace.

Smart Contract Architecture

The two central components of CNS are its Registry and Resolver smart contracts. Registry is a map (or dictionary) from domain names to an owner address and a Resolver address. And Resolver is a map from domain names to the records associated with that domain (cryptocurrency addresses, etc.).

There is only one Registry smart contract deployed in the Ethereum Mainnet, but there are many versions of Resolver smart contracts. In theory, every domain could use a different Resolver contract but in practice the majority of domains are managed by the same Resolver smart contract instance (like Resolver 1 in the example above).

Each ERC-721 token can be identified by a unique number, its tokenId. To make domains identifiable, we use a process called Namehashing.

For instance, example.crypto's namehash: 0xd584c5509c6788ad9d9491be8ba8b4422d05caf62674a98fbf8a9988eeadfb7e

Visualization

This flow describes how the CNS Registry and Resolvers interact.

Registry

Registry is the most essential smart contract in CNS. This is the contract that defines ownership rules, how domains are minted, provides ERC-721 token metadata, and stores a metadata-enriched list of all domains.

Registry stores:

• Owner address
• Approved operator address
• Resolver address
• Domain name

Registry's smart contract includes a set of methods for minting new domains, creating new subdomains, and managing ownership.

Accounts that are allowed to mint second-level domains (e.g.: alice.crypto) are called whitelisted minters. Whitelisted minters are only permitted to mint new domains. They can't control domain ownership (e.g. approve or transfer a domain to another owner) and they can't change domain records. Whitelisted minters are operated by Unstoppable Domains.

Registry's smart contract was designed without an admin. This means that no entity can manage or transfer a member's domains without their permission — even Unstoppable Domains.

Domain owners can:

• Transfer domain ownership
• Set a new resolver
• Mint a new subdomain
• Burn a domain

Domain owners can set one Approved address per domain and many Operator addresses. These roles can manage a domain on a member's behalf. For more details, see Managing domain ownership.

Resolver

Resolver is a smart contract that is used for resolving domains and storing domain records. This is where domain owners store their data, such as cryptocurrency addresses, chat IDs, and IPFS hashes for decentralized websites.

Under the surface, Resolver is effectively a map of domain namehashes to key-value dictionaries of records. This structure allows members to store arbitrary records, even those that aren't specified by the Records reference.

In practice, Resolver's data structure is slightly more complicated. If you're interested in the implementation details, see Resolver.sol.

Resolver allows domain owners, approved addresses, and operators to edit records of their owned domains. Resolver also provides an interface for getting standardized records, making it easier to access general information about domains.

ProxyReader

ProxyReader is a smart contract that our resolution libraries use to resolve domains. Normally, it would take at least two queries to the Ethereum blockchain to resolve a domain:

1. Call Registry to learn a domain's Resolver address
2. Call Resolver to read records themselves

ProxyReader consolidates these operations into a single call.

For more information on how the resolution process works read Resolving domain records.

Domain Hierarchy and Ownership

Domain ownership can take many forms in CNS.

A domain can be owned by both an external address (one that is accessed with a private key) or an internal address (i.e.: a smart contract). Managing domains with smart contracts opens up many new ways to structure ownership. For example, domain management could be governed by a multi-signature wallet or it could be equally shared among a group of administrators. These are two simple examples but there are many more possibilities.

Subdomains are subject to the same set of rules as second-level domains in CNS. Subdomains can be transferred or burned by both a direct owner and a domain zone owner (i.e. parent domain owner). Only a direct domain owner can set a Resolver address and manage domain records.

Such an ownership model might not be suitable for every member. One may want to mint subdomains that are irrevocable and can be transferred only by a direct owner – this and other models are possible if a domain zone is owned by a smart contract. For more details on alternative ownership models, see the section below.

Alternative Ownership Models

Using Solidity smart contracts allows many new ways to manage subdomains. One of these ways is to use the DomainZoneController smart contract, which is supported by the Unstoppable Domains team.

DomainZoneController implements a model of ownership where subdomains can be managed only by their owners. Minting subdomains can be performed using whitelisted accounts which can be added or removed by the smart contract administrators.

In addition to minting subdomains, DomainZoneController provides functionality to set a Resolver address and manage the records of a domain zone itself. These actions can only be performed by whitelisted accounts.

Delegating Domain Management

CNS allows members to delegate transaction execution to accounts that aren't domain owners.

Registry and Resolver smart contracts implement methods that use Meta Transactions. One use-case for meta transactions is delegating (gas-using) blockchain calls to other accounts. This allows domain owners to keep their domains and funds on separate accounts or even have someone else pay their transaction fees.

Unstoppable Domains uses this delegation feature to operate an internal transaction processor. Our transaction processor makes it possible for members to mint and manage their domains without having to worry about their wallet's balance. Under the hood, the transaction processor is a queue-based job processor that sends transactions from Unstoppable Domains-owned accounts.

On behalf of our members, our transaction processor generally handles:

• Minting domains
• Managing domains (transferring, setting Resolver address, modifying records)

Minting domains happens when a member mints a domain from the Unstoppable Domains website. This action doesn't require a domain owner's signature, since the minting of second-level domains is controlled by Unstoppable Domains.

Managing domains, in contrast, can only be performed with a domain owner's permission. Each delegated transaction that modifies the owner address, the Resolver address, or the domain records requires a domain owner's signature.

CNS transaction delegation does not depend on Unstoppable Domains' transaction processor. As long as the domain owner provides a valid signature, write operations can be performed by any Ethereum account.

To learn more about the technical details of delegating transactions in CNS, read our Delegating Meta Transactions page.