ERC-7529 Linking DNS domains and contracts (Contract Discovery and eTLD+1 Association)

Draft · Names & metadata · created 2023-09-30

A standard that lets a web domain's DNS TXT record and a smart contract point to each other, so that anyone can verify directly on the web whether a given contract truly belongs to that domain's owner.

Why it is needed

Even when a company issues digital assets such as tokens or NFTs, users have no reliable way to confirm whether the contract their wallet is currently interacting with truly belongs to that company. This makes it possible to impersonate a genuine company with a fake contract, and there has also been no way to search from a well-known company domain to find that company's contract. Previously, web apps could not read DNS records directly and had to go through an intermediary, which could tamper with the responses. With the introduction of DNS over HTTPS (DoH) under RFC 8484, web apps can now query DNS records directly in a tamper-resistant way, and this standard defines a simple method, built on top of that, for using a TXT record as a pointer to a contract address.

What to implement

In depth

Why eTLD+1 is used as the basis

A TLD is the top-level domain that comes after the final dot in a URL, like .com. However, different organizations can also register domains at non-top levels, such as .ac.uk, so such a registrable level is called an eTLD (effective top-level domain). An eTLD+1 is formed by appending one more name segment immediately after the eTLD, and it is guaranteed that all domains under the same eTLD+1 belong to the same organization. For example, the eTLD of myexample.com is .com, and the eTLD of sussex.ac.uk is .ac.uk. For this reason, this standard uses eTLD+1 as the unit for linking a contract to a single business or organization.

TXT record schema

The owner of an eTLD+1 must create a TXT record pointing to the contract(s) to be linked. HOST takes the form ERC-7529.<chain_id>._domaincontracts, where <chain_id> is the decimal representation of the target network's chain ID (1 for Ethereum mainnet, 11155111 for Sepolia). VALUE lists the contract addresses separated by commas. Since an EVM address string is 42 characters long, most DNS providers can fit dozens of addresses in a single record, and placing multiple TXT records at the same host allows all of them to be retrieved in a single DoH query. It is recommended to use the ERC-1191 checksum format for addresses, so that clients can validate the address and the target network before making an RPC call.

The contract-side interface

The contract only needs to add a single member variable called domains. This is a mapping whose key is the keccak256 hash of the linked eTLD+1 domain string and whose value is a boolean. It is written to via the external functions addDomain and removeDomain, and read via checkDomain. checkDomain takes an eTLD+1 string and returns true if it is linked, false otherwise. AddDomain and RemoveDomain events can optionally be emitted when a domain is added or removed; these are useful for a client to discover the full list of linked domains via events when it doesn't already know which domains are linked. Implementing this ERC is itself optional for any contract.

Client-side verification procedure

When a client finds a compatible TXT record at an eTLD+1, it must call checkDomain via RPC on each listed contract address, passing that eTLD+1 string, and confirm that it returns true. Conversely, when examining a contract that implements this ERC, the client must scan the AddDomain and RemoveDomain events to compute the currently linked domains, then fetch those domains' TXT records to verify the link. In doing so, it must confirm that the contract address appears in the VALUE of that eTLD+1's TXT record. In other words, whether starting from DNS or from the contract, both records must agree for verification to pass.

Security model: cross-checking two independent records

The HOST name convention is modeled on the naming convention of DKIM, the email signing standard, prefixing ERC-7529 to avoid name collisions with other TXT records. Verification cross-checks that two independent sources of information, DNS and the blockchain, agree with each other. If addDomain and removeDomain are properly authenticated, the value in domains can only be written by the contract's controller, and the address in the TXT record can only be entered by the eTLD+1 owner. For the two values to match, the same organization must control both resources, so once the link is verified, the contract can be considered to belong to the domain owner.

Reference implementation and access control

In the reference implementation, checkDomain computes a hash with keccak256(abi.encodePacked(domain)) and looks it up in the domains mapping. addDomain writes true to the same hash key and emits an AddDomain event, while removeDomain checks with require that a link exists, then sets it to false and emits a RemoveDomain event. Both write functions must have proper account authentication attached so that only authorized users can change domains. The reference implementation uses the onlyRole modifier from OpenZeppelin's access control abstract class to allow calls only from accounts with DEFAULT_ADMIN_ROLE.

Proposal status

This ERC was created on September 30, 2023 and is currently in Draft status. Since it is a draft that has not yet been finalized, the details of the specification may change. It references ERC-1191 as a prerequisite.

Things to watch out for

Original ERC · ← ERCs