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 webapp 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 a mapping from the keccak256 hash of all eTLD+1 domain strings associated with the business or organization which deployed (or is closely associated with) the contract to a boolean. This member variable can be written to with the external functions addDomain and removeDomain. The domains member variable can be queried by the checkDomain function which takes a string representing an eTLD+1 and returns true if the contract has been associated with the domain and false otherwise.

Lastly, the contract MAY emit events when eTLD+1 domains are added (AddDomain) or removed (RemoveDomain) from the domains map. This can be useful for determining all domains associated with a contract when they are not known ahead of time by the client.

{
  /// @notice Optional event emitted when a domain is added
  /// @param domain eTLD+1 associated with the contract
  event AddDomain(string domain);

  /// @notice Optional event emitted when a domain is removed
  /// @param domain eTLD+1 that is no longer associated with the contract
  event RemoveDomain(string domain);

  /// @dev a mapping from the keccak256 hash of eTLD+1 domains associated with this contract to a boolean
  mapping(bytes32 => bool) domains;

  /// @notice a getter function that takes an eTLD+1 domain string and returns true if associated with the contract
  /// @param domain a string representing an eTLD+1 domain
  function checkDomain(string calldata domain) external view returns (bool); 

  /// @notice an authenticated method to add an eTLD+1 domain
  /// @param domain a string representing an eTLD+1 domain associated with the contract
  function addDomain(string calldata domain) external;

  /// @notice an authenticated method to remove an eTLD+1 domain
  /// @param domain a string representing an eTLD+1 domain that is no longer associated with the contract
  function removeDomain(string calldata domain) external; 
}

Client-side Verification

When a client detects a compatible TXT record listed on an eTLD+1, it SHOULD loop through each listed contract address and, via an appropriate RPC provider, assert that each of the smart contracts returns true when the eTLD+1 string is passed to the checkDomain function.

Alternatively, if a client is inspecting a contract that implements this ERC, the client SHOULD inspect the AddDomain and RemoveDomain events to calculate if one or more eTLD+1 domains are actively associated with the contract. The user client SHOULD attempt to fetch TXT records from all associated eTLD+1 domains to verify its association or authenticity. The client MUST confirm that each contract address is contained in a TXT record’s VALUE field of the eTLD+1 pointed to by the contract’s domains mapping.

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 checkDomain, addDomain and removeDomain is a trivial exercise, but candidate implementations are given here for completeness:

function checkDomain(
      string calldata domain
  ) external view returns (bool) {
    return domains[keccak256(abi.encodePacked(domain))];
  }

function addDomain(
      string memory domain
  ) external onlyRole(DEFAULT_ADMIN_ROLE) {
    domains[keccak256(abi.encodePacked(domain))] = true;
    emit AddDomain(domain);
  }

function removeDomain(
    string memory domain
  ) external onlyRole(DEFAULT_ADMIN_ROLE) {
    require(domains[keccak256(abi.encodePacked(domain))] == true, "ERC7529: eTLD+1 currently not associated with this contract"); 
    domains[keccak256(abi.encodePacked(domain))] = false;
    emit RemoveDomain(domain);
  }

NOTE: Appropriate account authentication MUST be applied to addDomain and removeDomain so that only authorized users may update the domains mapping. 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 abstract class.

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.