ERC-7529: Contract Discovery and eTLD+1 Association

Leveraging TXT Records to discover, verify and associate a smart contract with the owner of a DNS domain.

Abstract

The introduction of DNS over HTTPS (DoH) in RFC 8484 has enabled tamper-resistant client-side queries of DNS records directly from a web application. This proposal describes a simple standard leveraging DoH to fetch TXT records (from traditional DNS service providers) which are used for discovering and verifying the association of a smart contract with a common DNS domain. This standard can be used as a straightforward technique to mitigate smart contract authorship spoofing and enhance the discoverability of smart contracts through standard web search mechanisms.

Motivation

As mainstream businesses begin to adopt public blockchain and digital asset technologies more rapidly, there is a growing need for a discovery/search mechanism (compatible with conventional web technologies) of smart contracts associated with a known business domain as well as reasonable assurance that the smart contract does indeed belong to the business owner of the DNS domain. The relatively recent introduction and widespread support of DoH means it is possible to make direct, tamper-resistant queries of DNS records straight from a web application context and thus leverage a simple TXT record as a pointer to an on-chain smart contract. Prior to the introduction of DoH, web (and mobile) applications could not access DNS records directly; instead they would have to relay requests through a trusted, proprietary service provider who could easily manipulate response results.

According to Cloudflare, the two most common use cases of TXT records today are email spam prevention (via SPF, DKIM, and DMARC TXT records) and domain name ownership verification. The use case considered here for on-chain smart contract discovery and verification is essentially analogous.

A TXT pointer coupled with an appropriate smart contract interface (described in this proposal) yields a simple, yet flexible and robust mechanism for the client-side detection and reasonably secure verification of on-chain logic and digital assets associated with the owner of a domain name. For example, a stablecoin issuer might leverage this standard to provide a method for an end user or web-based end user client to ensure that the asset their wallet is interacting with is indeed the contract issued or controlled by the owner or administrator of a well known DNS domain.

Example 1:

A user visits merchant.com who accepts payments via paymentprocessor.com. The business behind paymentprocessor.com has previously released a stable coin for easier cross-border payments which adheres to this ERC. On the checkout page, paymentprocessor.com is mounted as an iframe component. If the user has installed a browser-extension wallet compatible with this standard, then the wallet can detect the domain of the iframe in the context of the checkout page, discover and verify the stable coin’s association with paymentprocessor.com, and automatically prompt to complete the purchase in paymentprocessor.com’s stable coin.

Example 2:

A user visits nftmarketplace.io to buy a limited release NFT from theirfavoritebrand.com. The marketplace app can leverage this ERC to allow the user to search by domain name and also indicate to the user that an NFT of interest is indeed an authentic asset associated with theirfavoritebrand.com.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Definition: eTLD+1

The term TLD stands for top-level domain and is always the part of a domain name which follows the final dot in a URL (e.g. .com or .net). If only domains directly under TLDs where registrable by a single organization, then it would be guaranteed that myexample.com, abc.myexample.com, and def.myexample.com all belonged to the same organization.

However, this is not the case in general since many DNS registrars allow organizations to register domain names below the top level (examples include sussex.ac.uk and aber.ac.uk which are controlled by different institutions). These types of domains are referred to as eTLDs (effective top-level domains) and represent a domain under which domain names can be registered by a single organization. For example, the eTLD of myexample.com is .com and the eTLD of sussex.ac.uk is .ac.uk since individual organizations can be issued their own domain names under both .com and .ac.uk.

Therefore, an eTLD+1 is an eTLD plus this next part on the domain name. Since eTLDs are by definition registerable, all domains with the same eTLD+1 are owned by the same organization, which makes them appropriate to utilize in this proposal for associating a smart contract with a single business or organization entity.

Contract Pointers in TXT Records

The owner of an eTLD+1 domain name MUST create a TXT record in their DNS settings that serves as a pointer to all relevant smart contracts they wish to associate with their domain.

TXT records are not intended (nor permitted by most DNS servers) to store large amounts of data. Every DNS provider has their own vendor-specific character limits. However, an EVM-compatible address string is 42 characters, so most DNS providers will allow for dozens of contract addresses to be stored under a single record. Furthermore, a domain is allowed to have multiple TXT records associated with the same host and the content of all duplicate records can be retrieved in a single DoH query.

A TXT record pointing to an organization’s smart contracts MUST adhere to the following schema:

• HOST: ERC-7529.<chain_id>._domaincontracts (where <chain_id> is replaced by the decimal representation of the chain id)
• VALUE: <address 1>,<address 2>,…

It is RECOMMENDED that EVM address strings adhere to ERC-1191 so that the browser client can checksum the validity of the address and its target network before making an RPC call.

A user’s web application can access TXT records directly from a DNS registrar who supports DoH with fetch. An example query of a DoH server that supports JSON format will look like:

await fetch("https://example-doh-provider.com/dns-query?name=ERC-7529.1._domaincontracts.myexample.com&type=TXT", {
  headers: {
    Accept: "application/dns-json"
  }
})

Smart Contract Association with a Domain

Any smart contract MAY implement this ERC to provide a verification mechanism of smart contract addresses listed in a compatible TXT record.

A smart contract need only store one new member variable, domains, which is an array of all unique eTLD+1 domains associated with the business or organization which deployed (or is closely associated with) the contract. This member variable can be written to with the external functions addDomain and removeDomain.

{
  public string[] domains; // a string list of eTLD+1 domains associated with this contract

  function addDomain(string memory domain) external; // an authenticated method to add an eTLD+1

  function removeDomain(string memory domain) external; // an authenticated method to remove an eTLD+1
}

Client-side Verification

The user client MUST verify that the eTLD+1 of the TXT record matches an entry in the domains list of the smart contract.

When a client detects a compatible TXT record listed on an eTLD+1, it MUST loop through each listed contract address and, via an appropriate RPC provider, collect the domains array from each contract in the list. The client should detect an eTLD+1 entry in the contract’s domains array that exactly matches (DNS domains are not case-sensitive) the eTLD+1 of the TXT record.

Alternatively, if a client is inspecting a contract that implements this ERC, the client SHOULD collect the domains array from the contract and then attempt to fetch TXT records from all listed eTLD+1 domains to ascertain its association or authenticity. The client MUST confirm that the contract’s address is contained in a TXT record’s VALUE field of the eTLD+1 pointed to by the contract’s domains array.

Rationale

In this specification, the TXT record HOST naming scheme is designed to mimic the DKIM naming convention. Additionally, this naming scheme makes it simple to programmatically ascertain if any smart contracts are associated with the domain on a given blockchain network. Prepending with ERC-7529 will prevent naming collisions with other TXT records. The value of <chain_id> is simply the decimal representation of the chain id associated with the target blockchain network (i.e. 1 for Ethereum mainnet or 11155111 for Sepolia) where the smart contracts are deployed. So, a typical HOST might be: ERC-7529.1._domainContracts, ERC-7529.11155111._domaincontracts, etc.

A user client working with smart contracts implementing this proposal is protected by cross-checking that two independent sources of information agree with each other (i.e. DNS and a blockchain network). As long as the addDomain and removeDomain calls on the smart contract are properly authenticated (as shown in the reference implementation), the values in the domains field must have been set by a controller of the contract. The contract addresses in the TXT records can only be set by the owner of the eTLD+1 domain. For these two values to align the same organization must control both resources.

Backwards Compatibility

No backward compatibility issues found.

Reference Implementation

The implementation of addDomain and removeDomain is a trivial exercise, but candidate implementations are given here for completeness (note that these functions are unlikely to be called often, so gas optimizations are possible):

function addDomain(
      string memory domain
  ) external onlyRole(DEFAULT_ADMIN_ROLE) {
      string[] memory domainsArr = domains;

      // check if domain already exists in the array
      for (uint256 i; i < domains.length; ) {
          if (
              keccak256(abi.encodePacked((domainsArr[i]))) ==
              keccak256(abi.encodePacked((domain)))
          ) {
              revert("Domain already added");
          }
          unchecked {
            ++i;
          }
      }
    domains.push(domain);
  }

function removeDomain(
    string memory domain
  ) external onlyRole(DEFAULT_ADMIN_ROLE) {
    string[] memory domainsArr = domains;
    // A check that is incremented if a requested domain exists
    uint8 flag;
    for (uint256 i; i < domains.length; ) {
      if (
        keccak256(abi.encodePacked((domainsArr[i]))) ==
        keccak256(abi.encodePacked((domain)))
      ) {
          // replace the index to delete with the last element
          domains[i] = domains[domains.length - 1];
          // delete the last element of the array
          domains.pop();
          // update to flag to indicate a match was found
          flag++;
          break;
        }
        unchecked {
          ++i;
        }
    }
    require(flag > 0, "Domain is not in the list");
  }

NOTE: It is important that appropriate account authentication be applied to addDomain and removeDomain so that only authorized users may update the domains list. In the given reference implementation the onlyRole modifier is used to restrict call privileges to accounts with the DEFAULT_ADMIN_ROLE which can be added to any contract with the OpenZeppelin access control library.

Security Considerations

Due to the reliance on traditional DNS systems, this ERC is susceptible to attacks on this technology, such as domain hijacking. Additionally, it is the responsibility of the smart contract author to ensure that addDomain and removeDomain are authenticated properly, otherwise an attacker could associate their smart contract with an undesirable domain, which would simply break the ability to verify association with the proper domain.

It is worth noting that for an attacker to falsy verify a contract against a domain would require them to compromise both the DNS settings and the smart contract itself. In this scenario, the attacker has likely also compromised the business’ email domains as well.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Todd Chapman (@tthebc01), Charlie Sibbach <charlie@cwsoftware.com>, Sean Sing (@seansing), "ERC-7529: Contract Discovery and eTLD+1 Association [DRAFT]," Ethereum Improvement Proposals, no. 7529, September 2023. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7529.