OPRR Flash Depth Activities

Search Extension

Buidler DAO: A deep analysis of the technical design of the Web3 domain system using ENS as an example.

Buidler DAO

2022-12-08 22:00

Read this article in 37 Minutes

AI summary

View the summary

Original Title: "Buidler DAO: A Deep Analysis of the Technical Design of the Web3 Domain Name System Using ENS as an Example"

Original Author: @axtrur, Researcher at Buidler DAO

Web3 Domain Name System, in short, is a blockchain-based distributed and decentralized naming system similar to DNS (Domain Name System) that resolves addresses (wallet addresses or smart contract addresses) into readable names. This article takes ENS as an example to analyze the design of the web3 domain name system from the overall architecture to contract details in depth.

ENS Preconception

Domain Name Hierarchy

Similar to DNS, the ENS domain name hierarchy is also divided into levels.

The root domain name, that is, the "" domain name.

A top-level domain, similar to .com, .cn, has .eth and .reverse in ens (used to record reverse resolution, which will be mentioned later).

Subdomain, which refers to the domain name registered by the user, such as axtrur.eth

Third-level domain names can be created or modified under the second-level domain name after the user registers the second-level domain name, such as app.axtrur.eth.

NameHash Algorithm

Due to the low efficiency of interacting with readable domain names directly through smart contracts, ENS uses a fixed-length 256-bit encrypted hash as the domain name record. Namehash is a recursive algorithm that can derive the value of any subdomain from the NameHash value of any domain name, without knowing the true text string of the original domain name, while also conforming to the multi-level characteristics of domain names.

Namehash("") = "0x0000000000000000000000000000000000000000000000000000000000000000" Namehash("eth") = keccak256(Namehash(""), keccak256("eth")) Namehash("axtrur.eth") = keccak256(Namehash("eth"), keccak256("axtrur")) Namehash("app.axtrur.eth") = keccak256(Namehash("axtrur.eth"), keccak256("app"))

node

In ens, user-registered domain names such as axtrur.eth are recorded on-chain using the namehash algorithm to generate a hash node. In the following text, we will refer to this node as a domain name, such as axtrur. For information on handling ENS names, please refer to https://ensuser.com/docs/contract-api-reference/name-processing.html.

ENS Module Concept

Registry Contract (green section): Responsible for allocating names, including forward registry, reverse registry, and DNS registry.

Parser contract (blue section): responsible for recording the mapping relationship of domain names, including forward and reverse parser contracts. The forward parser contract can also be customized for implementation.

Forward resolution (there is a default public resolver contract on the mainnet): responsible for recording the content bound to the domain name, that is, the resolution of the nameNode (such as axtrur.eth, app.axtrur.eth) to various contents including but not limited to name, addr, txt, contenthash, etc. It can set wallet addresses for various currencies, set IPFS content hashes, and even record third-party accounts such as email as text records.

Reverse resolution (there is a default reverse resolver contract on the mainnet): responsible for recording the domain name bound to the wallet address, that is, the nameNode of the reverse domain name (such as {{wallet address}}.addr.reverse) to the resolution of the domain name.

Root contract: The owner of the root domain, who has management authority over the top-level domain.

Controller contract: The registration entrance contract on the official website (If different gameplay contracts need to be implemented, they are uniformly classified as the controller contract module. The corresponding registrar contract address needs to be set to the registrar to have permission to operate the registrar for domain NFT registration and record reverse resolution.)

Price Oracle: ENS pricing is based on U denomination (USDT), so a USDT oracle is needed to calculate the ETH conversion value of registration fees at a certain point in time. The registration fee on the ENS mainnet is:

Domain names with a length of 5 or more characters: pay $5 annually.

A domain name with 4 characters in length: pay $160 annually.

A domain name with a length of 3 characters: pays $640 annually.

DNSSEC Oracle: DNS Security Extension Oracle Contract, responsible for verifying the ownership and validity of web3 domain names.

ENS Module Analysis

Registration Contract (EnsRegistry.sol)

The registry is the core contract of ENS. The "records" structure inside the registry contract, as shown in the figure above, maintains the owner, resolver, and TTL information corresponding to the domain-level node.

除了注册表信息 records 维护，合约还维护 owner 的委托管理者信息 operators，owner 可以通过添加设置委托管理者地址（可以是用户地址，也可以是合约地址）来共同管理域名信息合约中相关管理设置接口（比如设置解析器，ttl，以及创建和修改子域名），都会通过修饰器`authorised(node)`来限制调用权限；该修饰器将判断该接口的交易请求者是否为当前域名的 owner，或者委托管理者地址，保证了仅有域名的 owner 或委托者才有创建下一级子域名的权限。同时这里部署初始化的时候将`」」`根域名的 node 的 owner 设置为部署者，只有这样，部署者才能将根域名的 owner 设置给 Root 合约根合约。

Translation:

In addition to maintaining registry information records, the contract also maintains information about the owner's delegated managers operators. The owner can add and set the delegated manager address (which can be a user address or a contract address) to jointly manage domain name information. The contract's related management setting interfaces (such as setting resolvers, TTL, and creating and modifying subdomains) will limit the calling permissions through the decorator `authorised(node)`; this decorator will determine whether the transaction requester of the interface is the owner of the current domain name or the delegated manager address, ensuring that only the owner or delegate of the domain name has the permission to create the next level of subdomains. At the same time, when deploying and initializing, the owner of the node of the root domain name `」」` is set to the deployer, so that only the deployer can set the owner of the root domain name to the Root contract root contract.

(Root.sol) The root contract is the owner of the root domain name. As the owner of the root domain name, the root contract has the authority to call the setSubnodeOwner interface of the registry contract to point the owner of the domain name .eth to the basic registrar contract.

Base Registrar Implementation Contract (BaseRegistrarImplementation.sol)

Due to the Root contract pointing the owner of the domain name .eth to the Basic Registrar contract (also known as the Forward Registrar contract), the Basic Registrar has the permission to set up second-level domain names under .eth, allowing users to register domain names through the Basic Registrar contract. At the same time, the Registrar contract inherits the ERC721 protocol standard, which is why ENS domain names can be bought and sold as NFTs on trading markets such as opensea. In addition, the Basic Registrar contract also maintains the expiration time expiries for each domain name. The Registrar sets a 90-day protection period for each domain name. If the domain name expires and is within the protection period, the domain name owner can renew it by calling the renew interface. If it exceeds the protection period, it needs to be re-registered (re-registration will first destroy the NFT and then re-mint it). At the same time, in the ENS design, the Registrar contract (whether it is a Forward Registrar or a Reverse Registrar) basically has a controllers structure, which maintains trusted controller Registrar contracts that can only be called by trusted contracts.

Controller Contract (ETHRegsiterController.sol)

Users submit registration information, including the domain name, to the controller contract on the official website. The controller contract calculates the price of the domain name through an oracle and converts the domain name to a node through namehash before passing it to the basic registrar for domain NFT registration. At the same time, the relevant registration information of the domain name is written into the registration contract to complete the registration. The owner of the domain name can also manage it through the registration contract on the official website. The registration page on the official website is as follows:

The core registration process:

ENS registration adopts a "request-submit" two-stage registration mode. Why is a two-stage submission required? We know that Ethereum nodes prioritize transactions in the transaction pool based on the gas fees paid. Before the registrant submits the transaction constructed with the domain name to be registered, the entire network is publicly transparent. Malicious attackers can listen and parse such transactions waiting to be submitted to the chain, and construct registration transactions for the same domain name to register the controller contract by increasing the gas fee and getting ahead of the original registrant.

To prevent domain name grabbing, ENS adopts a registration model of requesting first and submitting later. In the first phase, domain names are not directly submitted, but instead are called through.

The makeCommitment interface generates a special commitment by hashing the domain name to be applied for, the applying address, and a random value secret, and submits it to the chain through commit.

The commitment recorded during the submission phase records the current timestamp, and the ENS sets the validity period of the commitment to be between 60s and 86400s. When registering in the second phase, the contract will recalculate the commitment and check whether it is consistent with the one submitted in the first phase, and check the validity period of the commitment to ensure that the processing time interval on the chain in the first phase is more than 1 minute, and ensure that the block recording the transaction in the first phase has been confirmed by at least 5 subsequent blocks. (At this time, although the attacker can obtain the domain name value, the risk of being snatched is avoided because only the owner of the first phase needs to be consistent with the owner of the second phase to generate a consistent commitment.)

During the second stage of registration on the official website, the actual logic branch in the code is resolver != address(0), because ENS defaults to setting the registered resolver to the default public forward resolver (which will be discussed later as publicResolver). Why do we need to register the domain name to the contract itself and then transfer it to the user? This is because, as mentioned earlier, only the owner or delegated manager of the registry contract has the permission to set the resolver or update the owner. Therefore, in order to help users set the resolver, it is necessary to register it to the contract itself through the basic registrar (register), set the resolver through the registry contract (setResolver), declare ownership (reclaim), and finally transfer it to the registrant (transferFrom).

Resolver

The resolver contract in ENS is divided into forward resolution and reverse resolution. The resolution record is an important content in ENS. Only by defining the specification can the ecosystem easily become ENS-like web3 domain name system.

Forward resolution (using the default forward resolver contract PublicResolver.sol in ENS or a custom resolver contract.)

Responsible for mapping domain names to corresponding user-set content, including currency addresses, IPFS content hashes, universal text records, etc.

First, Metamask will obtain the resolver address set by the domain node through the registry contract (the default public resolver or a user-defined resolver contract address). Then, it will interact with the resolver address to obtain the currency address of the user's ETH setting (which is set to the registrant by default on the official website and can be freely changed by the registrant), and perform a transfer operation.

Reverse resolution (ENS Default Reverse Resolver contract DefaultReverseResolver.sol)

Responsible for mapping user wallet addresses to corresponding domain names.

Reverse resolution is actually opaque to users, who cannot customize it like they can with forward resolvers. Users can set the domain name they want to bind to their current wallet address using the setName method of the ReverseRegistrar.sol. Reverse records are also maintained in the ENS registry contract, and user-registered reverse records are stored in third-level domain name records in the format: specific user address.addr.reverse.

After setting up reverse resolution, the opensea user interface will display the user's wallet address as a readable ENS domain name, which is the process of reverse resolution, the resolver structure, and the registry information corresponding to the node.

The owner of the root domain is the root domain:

The owner of the second and third level domain names registered by the user is the user themselves, and they can freely set the resolver contract address.

.reserve top-level domain name owner is the multi-signature wallet address of ENS.

.addr.reserve is a subdomain owner of the reverse registrar in the encryption industry. When registering the controller contract of the current main network version of ENS, it is set by default through the reverse registrar (ReverseRegistrar.sol) to set reverse resolution records (such as the specific user address .addr.reverse points to axtrur.eth). Users do not need to provide reverse registration fees other than gas.

Previously, we have completed the design of the ENS domain name contract and its main modules. ENS is worth learning from in terms of module splitting and permission splitting, but there are also some issues with the current ENS on the mainnet.

ENS Issues and Solutions

1. Zero-width problem: This is currently a difficult problem for ENS because zero-width characters were not restricted in the contract design. (For an explanation of the zero-width problem, see https://mirror.xyz/0xc952fE149b640097054CFa53cAf7aC2bfd0162C5/RW6psQ2mnxyzmQx08PUXgLXOZc0kjvfXm8RGRVu8s0Y). For example, when registering a domain name on the official website, if the domain name has already been registered, you can use https://unicode-table.com/en/200B/ to copy a corresponding zero-width string and insert it into the middle of the domain name to register the corresponding domain name.

2. Special characters: The ENS contract does not have any restrictions on special characters such as emoji expressions, resulting in too many redundant and non-standard domain names in the current trading market.

Currently, the ENS official website has filtered special characters and provided necessary warning prompts (however, the contract itself is not restricted, so scientists can still register through the contract).

3. Transfer issue: Currently, ENS has a relatively complicated issue with transferring domain name NFTs. When transferring the NFT, the owner does not transfer synchronously. Therefore, when you buy an ENS domain name NFT in the trading market, you need to use the reclaim interface of the basic registrar contract to declare ownership of the NFT by consuming a certain amount of gas fee. Only then can you see the domain you own on the ENS official website.

4. TokenURI issue: The basic registration contract of ENS does not have a tokenURI that conforms to the ERC721 standard. This may be due to poor initial design considerations. Therefore, the metadata of ENS NFTs on trading markets such as OpenSea is provided by a special API of the centralized metaservice of ENS in the trading market (such as: https://metadata.ens.domains/mainnet/0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85/92165218023603606815515740961699344403389102980529428548045197994533319339809).

5. Reserved Words: This is an area where I think .bit has done a good job. The .bit official will reserve the names of institutions or companies in the web2 world, making it easier to connect between web2 and web3 in the future (https://github.com/dotbitHQ/Documents/blob/main/Reserved_DAS/Reserved_DAS_List.md). This is meaningful for the development of the web3 domain name ecosystem.

6. Basic contracts can be upgraded. ENS currently does not support proxy mode for basic modules to enable contract upgrades. This makes it difficult to upgrade basic modules in the future. One solution is fallback, and another is data migration, but both can only solve part of the problem. There is room for improvement in this aspect for ENS.

How can we solve the above problems?

1. Character issues can be addressed by modifying the logic in the valid function of the controller contract. One implementation approach is to restrict special characters such as spaceid (https://github.com/Space-ID/SpaceIDContract-Audit/blob/main/contracts/bnbregistrar/BNBRegistrarControllerV9.sol#L88), while another approach is to only allow characters that comply with the specifications.

2. Transfer issue: We can override the transferFrom and saveTransferFrom functions in the basic registry to transfer the NFT and call setSubnodeOwner to transfer the owner at the same time.

3. tokenURI issue: This is relatively simple. We just need to inherit the tokenURI standard of ECR721. But how do we dynamically display the domain name in the image? We can use svg on-chain (you can see the TokenURIBuilder.sol contract code modified after the article).

4. Reserved word issue: Reserved words and corresponding wallet addresses can be put on the chain, reserved for the contract itself, and later can be applied to a specific address through the apply interface.

5. Upgradable basic contracts: We can use the proxy pattern (EIP-1967) to modify the basic module contracts. If interested, you can refer to the contract design of Lens Protocol (https://github.com/lens-protocol/core/tree/main/contracts).

DNS Module

ENS's DNS capability is not the web2 domain name system we are talking about, such as .com, which can be used to access your ENS domain name in a browser. ENS's DNS registration is actually based on DNS security extensions, which verify your ownership of the web2 domain name through relevant proofs and verification algorithms, and then make a record of the web2 domain name to wallet address on the chain, allowing us to use web2 domain names for on-chain transfers. For more information, please see (https://ensuser.com/docs/dns-registrar-guide.html).

But why didn't we talk about the ENS DNS module in detail in this article? It's because although ENS has spent most of its energy on implementing DNS, this feature is relatively unpopular in ENS. In fact, this is actually a category of DID aggregation, and similar capabilities are more suitable for implementation in aggregated DIDs, such as NextID from Mask Network and ZKID from Cloak Network. The proof can be done well, and it can be integrated into web2 domains like Twitter's handler.

Deploying your own web3 domain

Finally, we provide a modified version of the ENS domain name contract (https://github.com/axtrur/xens-contracts for modification details and deployment methods, please refer to the readme), which facilitates users to deploy their own web3 domain names and gain a deeper understanding of the design principles of the web3 domain name system. Deployment command for the Goerli test network.

OWNER_KEY={{account private key}} INFURA_ID=c03713652e3c4ef6a3c09ea7dbf58711 npx hardhat deploy --network goerli (INFURA_ID can be replaced with your own infuraid, delete the deployment/goerli folder and deployment/goerli_result.json before executing)

After deploying the test network Goerli, execute the registration script ens.js to register the domain name.

OWNKEY={{account private key}} INFURA=https://goerli.infura.io/v3/c03713652e3c4ef6a3c09ea7dbf58711 node ens.js

You can check the deployed NFTs on the OpenSea testnet by visiting it. For example, you can check the deployed NFTs with the ".buidlerdao" domain suffix on the OpenSea testnet, just like mine.

https://testnets.opensea.io/collection/buildlerdao-name-service

Summary

ENS domain names, as pioneers of web3 domain names, have many design features worth learning from. The .bnb and .nft we see are also built on the basis of the ENS contract. Through this article, we hope that everyone can have a deep understanding of the design of ENS from the overall to the details. Web3 domain names are not just NFTs, they have deeper meanings. At the same time, web domain names are just a small beginning. With the popularization, ecological integration, and exploration of DID by everyone, native readable web3 domain names on the chain will be aggregated, allowing each user to have a unified business card description in the encrypted world and better connect multi-chain ecology and users.

ENS Domain Name System Related EIP Standards

EIP 137 - Registry https://eips.ethereum.org/EIPS/eip-137

EIP 181 - Reverse Registrar https://eips.ethereum.org/EIPS/eip-181

EIP 205 - ABI Parsing (ABI()).

EIP 619 - SECP256k1 Public Key Parsing (pubkey()).

EIP 634 - Text Record Parsing (text()).EIP 1577 - Content hash resolution (contenthash()).

EIP 2304 - Multi-Token Address Resolution (addr()). The new record type can be defined at any time through the EIP standardization process.

Mainnet deployed ENS contract

Registry contract: 0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e

Root contract: 0xab528d626ec275e3fad363ff1393a41f581c5897

Basic forward registry contract: 0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85.Reverse Register Contract: 0x084b1c3c81545d370f3634392de611caabff8148.

Default forward parser contract: 0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41

(Note: The content contains technical terms and industry-specific jargon, which have been left untranslated as per the request.)Default reverse resolver contract: 0xa2c122be93b0074270ebee7f6b7292c7deb45047.Controller contract: 0x283Af0B28c62C092C9727F1Ee09c02CA627EB7F5

ENS Domain Information

Official website: https://app.ens.domains/

github: https://github.com/ensdomainsContract code: https://github.com/ensdomains/ens-contracts/tree/master/contracts

Network deployment version: https://etherscan.io/accounts/label/ens

Document: https://ensuser.com/docs/contract-api-reference/ens-contracts-overview.html

Trading market: https://opensea.io/collection/ens

Other web3 domain system information

.bnb

Official website: https://space.id/

github： https://github.com/Space-ID

Trading market: https://www.element.market/collections/space-id-bnb

.bit