Introduction

Led by an anonymous group of eight senior crypto veterans, tomi offers a DAO-governed Web3 infrastructure that serves as a surveillance-free alternative to the World Wide Web. tomi is committed to advancing privacy and anonymity and will continue to develop new technologies to achieve those goals.

Domains is a distributed, open, and extensible naming system based on the Ethereum blockchain.

Domain's Job is to map human-readable names like ‘xyz.tomi’ to machine-readable identifiers such as Ethereum addresses, other cryptocurrency addresses, content hashes, and metadata. Domains also support ‘reverse resolution’, making it possible to associate metadata such as canonical names or interface descriptions with Ethereum addresses.

Domains have similar goals to DNS, the Internet’s Domain Name Service, but have significantly different architectures due to the capabilities and constraints provided by the Ethereum blockchain. Like DNS, Domains operate on a system of dot-separated hierarchical names called domains, with the domain owner having full control over subdomains.

Top-level domains, like ‘.tomi’ and ‘.com’, 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. Domains also support importing in DNS names already owned by the user for use on Domains.

Because of the hierarchical nature of Domains, anyone who owns a domain at any level may configure subdomains - for themselves or others - as desired. For instance, if it owns 'xyz.tomi', it can create 'my.xyz.tomi' and configure it as they wish.

You can try Domains out for yourself now by using the Domains Manager App or any of the many Domains-enabled applications on our homepage.

Domains Architecture

Domains have two principal components: the registry, and resolvers.

The Domains 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 domain

• The resolver for the domain

• The 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 Domains registry may:

• Set the resolver and TTL for the domain

• Transfer ownership of the domain to another address

• Change the ownership of subdomains

The Domains 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 Domains. 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 standardisation process, with no need to make changes to the Domains registry or to existing resolvers in order to support them.

Resolving a name in Domains 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 'xyz.tomi'. First, we ask the registry which resolver is responsible for 'xyz.tomi'. Then, we query that resolver for the address of 'xyz.tomi'.

Namehash

Resource constraints in smart contracts make interacting directly with human-readable names inefficient, so Domains work purely with fixed-length 256-bit cryptographic hashes. To derive the hash from a name while still preserving its hierarchical properties, a process called Namehash is used. For example, the namehash of 'xyz.tomi' is 0x787192fc5378cc32aa956ddfdedbf26b24e8d78e40109add0eea2c1a012c3dec; this is the representation of names that is used exclusively inside Domains.

Namehash is a recursive process that can generate a unique hash for any valid domain name. Starting with the namehash of any domain - for example, 'xyz.tomi' - it's possible to derive the namehash of any subdomain - for example 'my.xyz.tomi' - without having to know or handle the original human-readable name. It is this property that makes it possible for Domains to provide a hierarchical system, without having to deal with human-readable text strings internally.

Before being hashed with namehash, names are first normalised, using a process called UTS-46 normalisation. This ensures that upper- and lower-case names are treated equivalently, and that invalid characters are prohibited. Anything that hashes and resolves a name must first normalise it, to ensure that all users get a consistent view of Domains.

For details on how namehash and normalisation works, see the developer documentation on name processing.

Getting Started

Domains has documentation for a variety of audiences, including DApp developers and contract developers, as well as reference documentation.

I'm a DApp developer and want to add Domains support to my DApp

Check out the DApp developer guide, starting with Domains Enabling your Dapp You'll want to choose one of the many available Domains Libraries to get started working with Domains.

I'm a contract developer and want to interact with Domains from my contract code

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).

I want reference documentation for the Domains' smart contracts

Check out the Contract API Reference. We have reference documentation for tDN's core contract, the registry, for resolvers, and commonly-used registrars such as the Test registrar, reverse registrar, and the .tomi and.com registrar.