Domains Data guide

Overview

Even though adding basic functionalities such as a single name lookup is just adding a few lines of code, analysing overall stats or integrating with historical info can be challenging due to the following reasons.

• The data is stored in storage efficient way to save gas costs, which requires decoding

• Some of the contracts can be extensible by end users leading to inconsistent interface

• Some names (.tomi, wrapped names) expire without emitting events

• Smart contract structures have changed over time

• Some names are not available on the chain (eg: CCIP-read integrated names such as cb.id)

In this section, I will go through the overall structure of Domains contracts and events to help you guide through the Domains data space.

Target audience

The target audience of this article is developers and data analysts who are interested in labelling Domains names into the Ethereum transaction data such as NFT owners, Defi users, and Domains name trading history. It assumes that you have a basic understanding of how Ethereum smart contracts work (such as function calls and events). Some tools also require query language knowledge such as GraphQL and SQL.

How to access Domains data

Just like many other Ethereum-based projects, Domains consists of a set of smart contracts. You can use tools of your choice to interact directly with Domains smart contracts (which we will explain in depth). If you want extra data about a single name, please refer to the Domains library section which explains how to interact with Domains via popular libraries such as ethers.js.

Extracting multiple entities tends to be slow and time-consuming because you have to make a function call to extract each record. If you are interested in extracting more than dozens of name records or want to access event-related information. There are currently two popular services, The Graph, Dune Analytics and Google Big Query.

The Graph

• Mainnet

• Goerli

• RInkeby

The Graph is a decentralized indexing service that allows developers to turn smart contract events (and function calls) into GraphQL schema called subgraph. The Domains team maintains the subgraph that encapsulates multiple events data into a single entity such as Domain, Account, Registration and Resolver.

The following sample query lists all names

account{
  domains {
    labelName
    labelhash
    name
  }
}

It is suitable to extract information such as the list of subdomains a name created, a list of names the address registered, and text keys (eg: Twitter, email, avatar). You can also use it to extract analytics information such as registered names though you need to traverse the data multiple times.

You can see the list of subgraphs used in the https://tdns.network/ (all query names ending with _SUBGRAPH)

Dune Analytics

• Domains Dashboard

Dune is a popular social network to analyse and share blockchain data. Users (called Data wizards) can write SQL to analyse on-chain data. Others can fork (copy) SQL code, make modifications, and share the insight with visual charts. Unlike TheGraph, Dune has decoded many popular smart contract events and function calls including Domains and therefore no need to create its schema. The downside is that the available tables are less structured than the GraphQL subgraph and you will need more domain knowledge about the underlying smart contract events and function call structures.

The following example counts monthly .tomi name registrations.

SELECT date_trunc('month', evt_block_time), COUNT(*)
FROM (
SELECT * FROM tomidomainnameservice."TOMIRegistrarController_1_evt_NameRegistered"
WHERE evt_block_time > (current_date - interval '1' year)
UNION 
SELECT * FROM tomidomainnameservice."TOMIRegistrarController_2_evt_NameRegistered"
WHERE evt_block_time > (current_date - interval '1' year)
UNION 
SELECT * FROM tomidomainnameservice."TOMIRegistrarController_3_evt_NameRegistered"
WHERE evt_block_time > (current_date - interval '1' year)
) AS r GROUP BY 1

Google BigQuery

BigQuery is a data analytics platform similar to Dune Analytics without any “social” features. The query tends to run quicker than dune but it charges per query hence it could cost a lot. Google BigQuery allows you to export the query result into csv/google spreadsheet as well as to their “Data Studio” visualization platform.

The biggest advantage of BigQuery is to allow you to import javascript libraries as a user-defined function. This is particularly helpful if you want to make use of popular javascript libraries such as ethers.js

An example query: comparing normalised labels

CREATE TEMP FUNCTION ens_normalize(arg1 STRING)
RETURNS STRING
LANGUAGE js
  OPTIONS (
    library=['gs://jsassets/ens-normalize.js'])
AS r"""
  try{
    return ens_normalize(arg1)
  }catch(e){
    return null;
  }
""";
WITH Example AS
 (SELECT '50' as label UNION ALL
  SELECT '⁕⁕⁕⁕⁕' UNION ALL --* legacy error, new ok *--
  SELECT '🚀‍‍‍‍‍‍‍‍‍‍🚀‍‍‍‍‍‍‍‍‍‍🚀‍‍‍‍‍‍‍‍‍‍') --* legacy ok , new error *--
SELECT label, ens_normalize(label) FROM Example

Contract structures

The full detail of each smart contract is covered in the contract api reference section. This section lists function names and events which are often used to access the data. To find out the deployed addresses, please refer to “Domains Deployments” section.

DomainsRegistry/DomainsRegistryWithFallback

• "Transfer(node, owner)"

• "NewOwner(node, label, owner)"

• "NewResolver(node,resolver)"

The contract contains the name owner (aka “controller”) and resolver contract addresses that hold the actual record (such as Ethereum address, IPFS content hash) . The name is stored in namehash format so that it can store an infinite length of the name. The name owner has the privilege to change the resolver contract and can create subdomains under the name you own.

NewOwner event is logged when the owner of a node assigns a new owner to a sub node. Transfer event is logged when the owner of a node transfers ownership to a new account. NewResolver event is logged when the resolver for a node changes.

NOTE: The current Domains registry contract is DomainsRegistryWithFallback that was deployed in 2022 Feb to resolve the bug found in the original Registry. Even though the majority of names have transferred to the new contract, there are some names (mostly names owned by smart contract) that couldn’t be migrated. If you want to extract all names existing, you have to query both registries and remove the duplicates.

Resolver

• AddressChanged(node,coinType,address)

• ContenthashChanged(node, name)

• NameChanged(node, value)

• TextChanged(node, key, key, value)

The majority of the contracts use a default resolver which is set at the time of registration. However, the default resolver has changed a few times to add new functionalities (eg: coin type). To find out all the resolver addresses, you have to get the resolver address through DomainsRegistry. NewResolver event (note: Users in the past have put their own Ethereum address by mistake hence there are 100s of addresses that are set as new resolver which don’t contain any record).

BaseRegistrar

• NameRegistered(id, owner, expires)

• NameRenewed(id, expires)

• Transfer(from,to,tokenId)

BaseRegistrar is the owner of .tomi and is a ERC721 NFT contract. id is the hash of the label (eg: for “matoken.eth”, the keccak256 of “matoken” becomes the id. For more information, read “Domains as NFT section”).

tomiRegistrarController

• NameRegistered(name, label, owner, baseCost, premium, expires)

• NameRenewed(name, label, cost, expires)

The EthRegistrarController contract contains the actual registration logic. The contract is upgradable via DAO vote and has been changed a few times in the past. The Registered/Renewed events contain the registration logic as well as domain names in plain text. The Graph uses this information to decode .tomi id and lablehash into human readable names.

NameWrapper

• NameWrapped(node, name, owner, fuses, expiry)

• NameUnwrapped(node, owner)

• FusesSet(node, fuses)

• TransferSingle(operator, from, to, ids, value)

• TransferBatch(operator, from, to, ids, value)

NameWrapper is the new feature that turns any subdomains into NFT (with extra access control to prevent parent domain owners from reverting the NFT ownership). TransferSingle and TransferBatch are ERC1155 defined events.

FAQ

Listing all primary names

• SmartContract = reverse-records smart contract allows you to resolve primary names for multiple addresses.

• TheGraph = subgraph currently does not index primary name info.

• Dune = If you simply want to count the number, you can count the number of names registered under addr.reverse node. To query all names, use “Domains.node_names” abstraction.

Listing all registered names

• JS & SmartContract = There is no function to list all registered names.

• TheGraph = Querying Domains object will give you the list of names.

• Dune = Query DomainsRegistry_evt_NewOwner and DomainsRegistryWithFallback_evt_NewOwner tables

If you want to exclude released names, you need to join the registration table and exclude where the expiration date is less than the current date - 90 days (90 days is the grace period where the name is expired but no one can register).

Listing all records (Ethereum address/contenthash/text record)

• JS & SmartContract = There is no function to list all registered names.

• Dune = Query PublicResolver_call_* Example query or use “domains.resolver_records” abstraction.

• TheGraph = Querying `Domains.resolver` object will give you all the records.

Example

{
  domains {
    name
      resolver{
      contentHash
      texts
      addr {
        id
      }
      coinTypes
    }
  }

NOTE: texts and coinTypes only return the keys so you still have to call smart contracts to get the value.

Listing Offchain names

The offchain names cannot be tracked because they do not exist on the chain.

Why are some subdomain names not decoded?

Domains names are stored as a hash on-chain so we have to decode the name using a list of possible names, and it shows in the hashed format if we don't have it on our list. You can still access and manage the name if you search for the name directly in the search bar.

How do I find sub categories such as 10k club, 100k club, emoji, etc?

Domains Protocol itself does not have any mechanism to categorise names. You can either search with certain categories using regular expressions or may refer to third-party sites.