From ddb40fe23064339d8f5972b1be70752b46e682d7 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Thu, 26 Oct 2023 14:07:43 -0700 Subject: [PATCH 01/15] moved from EIPs to ERCs --- ERCS/erc-7529.md | 157 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 ERCS/erc-7529.md diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md new file mode 100644 index 0000000000..7d42efd13b --- /dev/null +++ b/ERCS/erc-7529.md @@ -0,0 +1,157 @@ +--- +eip: 7529 +title: Contract Discovery and eTLD+1 Association +description: A simple method for leveraging TXT Records to discover, verify and associate a smart contract with the owner of a DNS domain. +author: Todd Chapman (@tthebc01), Charlie Sibbach , Sean Sing (@seansing) +discussions-to: https://ethereum-magicians.org/t/add-eip-dns-over-https-for-contract-discovery-and-etld-1-association/15996 +status: Draft +type: Standards Track +category: ERC +created: 2023-09-30 +requires: 1191 +--- + +## Abstract + +The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) has enabled tamper-resistant client-side queries of DNS records directly from the browser context. [ERC-7529](./eip-7529.md) describes a simple standard leveraging DoH to fetch TXT records which are used for discovering and verifying the association of a smart contract with a common DNS domain. + +## 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 browser resources) 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 queries of DNS records straight from the browser context and thus leverage a simple TXT record as a pointer to an on-chain smart contract. + +A TXT pointer coupled with an appropriate smart contract interface (described in this ERC) 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 a 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. + +### Contract Pointers in TXT Records + +The owner of a 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](https://www.rfc-editor.org/rfc/rfc1035#section-3.3.14) 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 retrived in a single DoH query. + +The TXT record MUST adhere to the following schema: + +- `HOST`: ERC-7529.`chain_id`._domaincontracts +- `VALUE`: \
,\
,... + +This `HOST` naming scheme is designed to mimic the [DKIM](https://www.rfc-editor.org/rfc/rfc6376) 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. The value of `chain_id` is simply the integer associated with the target network (i.e. `1` for Ethereum mainnet or `42` for Polygon). So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. + +It is RECOMMENDED that EVM address strings adhere to [ERC-1191](./eip-1191.md) so that the browser client can checksum the validity of the address and its target network before making an RPC call. + +A user can check the propagation of their TXT record from the browser console with `fetch`: + +``` +await fetch("https://cloudflare-dns.com/dns-query?name=ERC-7529.1._domaincontracts.example.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 contract. This member variable can be written to with the external functions `addDomain` and `removeDomain`. + +```solidity +{ + 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 address is contained in a TXT record's `VALUE` field of the eTLD+1 pointed to by the contract's `domains` array. + +## Rationale + +According to Cloudflare, the two most common use cases of TXT records today are email spam prevention (via [SPF](https://www.rfc-editor.org/rfc/rfc7208), DKIM, and [DMARC](https://www.rfc-editor.org/rfc/rfc7489) TXT records) and domain ownership verification. The use case considered here for on-chain smart contract discovery and verification is essentially analogous. Now that DoH is supported by most major DNS providers, it is easy to leverage TXT records directly in wallets, dApps, and other web applications without relying on a proprietary vendor API to provide DNS information and thus gain the same benefits afforded to email and domain verification with digital assets and on-chain logic. + +The client working with the smart contract is protected by cross-checking that two independent sources of information agree with each other. 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 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): + +```solidity +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("Consent : 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, "Consent : 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](../LICENSE.md). From 1d45d204abd92c475f30985b6098db17bc9ea026 Mon Sep 17 00:00:00 2001 From: Todd Chapman <6946868+TtheBC01@users.noreply.github.com> Date: Thu, 26 Oct 2023 18:18:42 -0700 Subject: [PATCH 02/15] Update erc-7529.md change eip- to erc- --- ERCS/erc-7529.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 7d42efd13b..4e1fea0cc9 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -13,7 +13,7 @@ requires: 1191 ## Abstract -The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) has enabled tamper-resistant client-side queries of DNS records directly from the browser context. [ERC-7529](./eip-7529.md) describes a simple standard leveraging DoH to fetch TXT records which are used for discovering and verifying the association of a smart contract with a common DNS domain. +The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) has enabled tamper-resistant client-side queries of DNS records directly from the browser context. [ERC-7529](./erc-7529.md) describes a simple standard leveraging DoH to fetch TXT records which are used for discovering and verifying the association of a smart contract with a common DNS domain. ## Motivation @@ -46,7 +46,7 @@ The TXT record MUST adhere to the following schema: This `HOST` naming scheme is designed to mimic the [DKIM](https://www.rfc-editor.org/rfc/rfc6376) 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. The value of `chain_id` is simply the integer associated with the target network (i.e. `1` for Ethereum mainnet or `42` for Polygon). So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. -It is RECOMMENDED that EVM address strings adhere to [ERC-1191](./eip-1191.md) so that the browser client can checksum the validity of the address and its target network before making an RPC call. +It is RECOMMENDED that EVM address strings adhere to [ERC-1191](./erc-1191.md) so that the browser client can checksum the validity of the address and its target network before making an RPC call. A user can check the propagation of their TXT record from the browser console with `fetch`: From 46a21b6b081b227375bf29444e5b171a367c572c Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Mon, 20 Nov 2023 09:16:44 -0800 Subject: [PATCH 03/15] addressed comments from @SamWilsn --- ERCS/erc-7529.md | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 4e1fea0cc9..c70e8c0324 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -13,11 +13,13 @@ requires: 1191 ## Abstract -The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) has enabled tamper-resistant client-side queries of DNS records directly from the browser context. [ERC-7529](./erc-7529.md) describes a simple standard leveraging DoH to fetch TXT records which are used for discovering and verifying the association of a smart contract with a common DNS domain. +The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) has enabled tamper-resistant client-side queries of DNS records directly from a web application. [ERC-7529](./erc-7529.md) 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 simple 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 browser resources) 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 queries of DNS records straight from the browser context and thus leverage a simple TXT record as a pointer to an on-chain smart contract. +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 browser resources) 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](https://www.rfc-editor.org/rfc/rfc7208), [DKIM](https://www.rfc-editor.org/rfc/rfc6376), and [DMARC](https://www.rfc-editor.org/rfc/rfc7489) 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 ERC) 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 a 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. @@ -33,25 +35,32 @@ A user visits nftmarketplace.io to buy a limited release NFT from theirfavoriteb 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. -### Contract Pointers in TXT Records +#### 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 organization 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 organization can be issued their own domain names under both `.com` and `.ac.uk`. -The owner of a 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. +Therefor, 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 ERC-7529 for associating a smart contract with a single business or organization entity. + + +### Contract Pointers in TXT Records -[TXT records](https://www.rfc-editor.org/rfc/rfc1035#section-3.3.14) 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 retrived in a single DoH query. +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. -The TXT record MUST adhere to the following schema: +[TXT records](https://www.rfc-editor.org/rfc/rfc1035#section-3.3.14) 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. -- `HOST`: ERC-7529.`chain_id`._domaincontracts -- `VALUE`: \
,\
,... +A TXT record pointing to an organization's smart contracts MUST adhere to the following schema: -This `HOST` naming scheme is designed to mimic the [DKIM](https://www.rfc-editor.org/rfc/rfc6376) 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. The value of `chain_id` is simply the integer associated with the target network (i.e. `1` for Ethereum mainnet or `42` for Polygon). So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. +- `HOST`: ERC-7529.<`chain_id`>._domaincontracts +- `VALUE`: \<`address 1`\>,\<`address 2`\>,... It is RECOMMENDED that EVM address strings adhere to [ERC-1191](./erc-1191.md) so that the browser client can checksum the validity of the address and its target network before making an RPC call. -A user can check the propagation of their TXT record from the browser console with `fetch`: +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://cloudflare-dns.com/dns-query?name=ERC-7529.1._domaincontracts.example.com&type=TXT", { +await fetch("https://example-doh-provider.com/dns-query?name=ERC-7529.1._domaincontracts.myexample.com&type=TXT", { headers: { Accept: "application/dns-json" } @@ -62,7 +71,7 @@ await fetch("https://cloudflare-dns.com/dns-query?name=ERC-7529.1._domaincontrac 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 contract. This member variable can be written to with the external functions `addDomain` and `removeDomain`. +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`. ```solidity { @@ -80,13 +89,13 @@ The user client MUST verify that the eTLD+1 of the TXT record matches an entry i 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 address is contained in a TXT record's `VALUE` field of the eTLD+1 pointed to by the contract's `domains` array. +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 -According to Cloudflare, the two most common use cases of TXT records today are email spam prevention (via [SPF](https://www.rfc-editor.org/rfc/rfc7208), DKIM, and [DMARC](https://www.rfc-editor.org/rfc/rfc7489) TXT records) and domain ownership verification. The use case considered here for on-chain smart contract discovery and verification is essentially analogous. Now that DoH is supported by most major DNS providers, it is easy to leverage TXT records directly in wallets, dApps, and other web applications without relying on a proprietary vendor API to provide DNS information and thus gain the same benefits afforded to email and domain verification with digital assets and on-chain logic. +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 integer associated with the target blockchain network (i.e. `1` for Ethereum mainnet or `42` for Polygon) that the smart contracts are deployed to. So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. -The client working with the smart contract is protected by cross-checking that two independent sources of information agree with each other. 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 domain. For these two values to align the same organization must control both resources. +A user client working with smart contracts implementing ERC-7529 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 From 140bdc3f3ada97aaf66eb57eb6d17613eb39f9fa Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Fri, 8 Dec 2023 10:24:28 -0800 Subject: [PATCH 04/15] minor edits --- ERCS/erc-7529.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index c70e8c0324..b4a124ed93 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -1,7 +1,7 @@ --- eip: 7529 title: Contract Discovery and eTLD+1 Association -description: A simple method for leveraging TXT Records to discover, verify and associate a smart contract with the owner of a DNS domain. +description: Leveraging TXT Records to discover, verify and associate a smart contract with the owner of a DNS domain. author: Todd Chapman (@tthebc01), Charlie Sibbach , Sean Sing (@seansing) discussions-to: https://ethereum-magicians.org/t/add-eip-dns-over-https-for-contract-discovery-and-etld-1-association/15996 status: Draft @@ -13,7 +13,7 @@ requires: 1191 ## Abstract -The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) has enabled tamper-resistant client-side queries of DNS records directly from a web application. [ERC-7529](./erc-7529.md) 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 simple technique to mitigate smart contract authorship spoofing and enhance the discoverability of smart contracts through standard web search mechanisms. +The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) 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 simple technique to mitigate smart contract authorship spoofing and enhance the discoverability of smart contracts through standard web search mechanisms. ## Motivation @@ -21,7 +21,7 @@ As mainstream businesses begin to adopt public blockchain and digital asset tech According to Cloudflare, the two most common use cases of TXT records today are email spam prevention (via [SPF](https://www.rfc-editor.org/rfc/rfc7208), [DKIM](https://www.rfc-editor.org/rfc/rfc6376), and [DMARC](https://www.rfc-editor.org/rfc/rfc7489) 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 ERC) 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 a 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. +A TXT pointer coupled with an appropriate smart contract interface (described in this ERC) 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**: @@ -41,7 +41,7 @@ The term TLD stands for *top-level domain* and is always the part of a domain na However, this is not the case in general since many DNS registrars allow organization 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 organization can be issued their own domain names under both `.com` and `.ac.uk`. -Therefor, 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 ERC-7529 for associating a smart contract with a single business or organization entity. +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 ERC-7529 for associating a smart contract with a single business or organization entity. ### Contract Pointers in TXT Records @@ -55,7 +55,7 @@ A TXT record pointing to an organization's smart contracts MUST adhere to the fo - `HOST`: ERC-7529.<`chain_id`>._domaincontracts - `VALUE`: \<`address 1`\>,\<`address 2`\>,... -It is RECOMMENDED that EVM address strings adhere to [ERC-1191](./erc-1191.md) so that the browser client can checksum the validity of the address and its target network before making an RPC call. +It is RECOMMENDED that EVM address strings adhere to [ERC-1191](./eip-1191.md) 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: From 096fc97d3d7ac3cbbf34c2ea7c637d63c213de7a Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Mon, 11 Dec 2023 17:16:38 -0800 Subject: [PATCH 05/15] edit direct references to erc-7529 --- ERCS/erc-7529.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index b4a124ed93..93d8f16352 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -41,7 +41,7 @@ The term TLD stands for *top-level domain* and is always the part of a domain na However, this is not the case in general since many DNS registrars allow organization 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 organization 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 ERC-7529 for associating a smart contract with a single business or organization entity. +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 @@ -95,7 +95,7 @@ Alternatively, if a client is inspecting a contract that implements this ERC, th 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 integer associated with the target blockchain network (i.e. `1` for Ethereum mainnet or `42` for Polygon) that the smart contracts are deployed to. So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. -A user client working with smart contracts implementing ERC-7529 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. +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 From b644cfc7499ba614208709f8a343327c6abce265 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Mon, 11 Dec 2023 17:19:11 -0800 Subject: [PATCH 06/15] spelling --- ERCS/erc-7529.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 93d8f16352..32bd409c9a 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -39,7 +39,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S 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 organization 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 organization can be issued their own domain names under both `.com` and `.ac.uk`. +However, this is not the case in general since many DNS registrars allow organization 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. From dd26a3a616b4624d5f99d5a7f1799f7990382d6a Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Sat, 16 Dec 2023 12:28:02 -0800 Subject: [PATCH 07/15] tweak TXT record formatting --- ERCS/erc-7529.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 32bd409c9a..f0eb88dd2c 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -13,15 +13,15 @@ requires: 1191 ## Abstract -The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) 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 simple technique to mitigate smart contract authorship spoofing and enhance the discoverability of smart contracts through standard web search mechanisms. +The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) 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 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 browser resources) 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. +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](https://www.rfc-editor.org/rfc/rfc7208), [DKIM](https://www.rfc-editor.org/rfc/rfc6376), and [DMARC](https://www.rfc-editor.org/rfc/rfc7489) 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 ERC) 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. +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**: @@ -39,7 +39,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S 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 organization 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`. +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. @@ -52,14 +52,14 @@ The owner of an eTLD+1 domain name MUST create a TXT record in their DNS setting A TXT record pointing to an organization's smart contracts MUST adhere to the following schema: -- `HOST`: ERC-7529.<`chain_id`>._domaincontracts +- `HOST`: `ERC-7529.._domaincontracts` (where `` 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](./eip-1191.md) 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: -``` +```javascript await fetch("https://example-doh-provider.com/dns-query?name=ERC-7529.1._domaincontracts.myexample.com&type=TXT", { headers: { Accept: "application/dns-json" @@ -93,7 +93,7 @@ Alternatively, if a client is inspecting a contract that implements this ERC, th ## 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 integer associated with the target blockchain network (i.e. `1` for Ethereum mainnet or `42` for Polygon) that the smart contracts are deployed to. So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. +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 `` is simply the integer associated with the target blockchain network (i.e. `1` for Ethereum mainnet or `42` for Polygon) where the smart contracts are deployed. So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._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. @@ -117,7 +117,7 @@ function addDomain( keccak256(abi.encodePacked((domainsArr[i]))) == keccak256(abi.encodePacked((domain))) ) { - revert("Consent : Domain already added"); + revert("Domain already added"); } unchecked { ++i; @@ -149,7 +149,7 @@ function removeDomain( ++i; } } - require(flag > 0, "Consent : Domain is not in the list"); + require(flag > 0, "Domain is not in the list"); } ``` From ec2994e7dcb6eecd95873d642feaf514e07e6c2a Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Sat, 16 Dec 2023 12:32:31 -0800 Subject: [PATCH 08/15] replaced polygon example with sepolia --- ERCS/erc-7529.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index f0eb88dd2c..b184ea2920 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -93,7 +93,7 @@ Alternatively, if a client is inspecting a contract that implements this ERC, th ## 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 `` is simply the integer associated with the target blockchain network (i.e. `1` for Ethereum mainnet or `42` for Polygon) where the smart contracts are deployed. So, a typical `HOST` might be: `ERC-7529.1._domainContracts`, `ERC-7529.42._domaincontracts`, etc. +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 `` 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. From edd8068517d79ffaf3655d3b11ea5f533fbcc47a Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Sat, 16 Dec 2023 12:36:17 -0800 Subject: [PATCH 09/15] grammar --- ERCS/erc-7529.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index b184ea2920..8de5746834 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -13,7 +13,7 @@ requires: 1191 ## Abstract -The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) 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 straightforward technique to mitigate smart contract authorship spoofing and enhance the discoverability of smart contracts through standard web search mechanisms. +The introduction of DNS over HTTPS (DoH) in [RFC 8484](https://www.rfc-editor.org/rfc/rfc8484) 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 From 56a11c27f08577ed7761ba745e520f63ee79b735 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Sat, 16 Dec 2023 12:40:23 -0800 Subject: [PATCH 10/15] swapped quotes for back tiks --- ERCS/erc-7529.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 8de5746834..0eac94ebe7 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -93,7 +93,7 @@ Alternatively, if a client is inspecting a contract that implements this ERC, th ## 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 `` 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. +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 `` 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. From 316935a8bf136dacd214ac3c8144a1c5de8429e9 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Tue, 19 Mar 2024 22:21:27 -0700 Subject: [PATCH 11/15] update with suggestions from EIP day at ETHDenver --- ERCS/erc-7529.md | 86 +++++++++++++++++++++++------------------------- 1 file changed, 42 insertions(+), 44 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 0eac94ebe7..d78cc40a10 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -29,7 +29,7 @@ A user visits merchant.com who accepts payments via paymentprocessor.com. The bu **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. +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 @@ -71,25 +71,48 @@ await fetch("https://example-doh-provider.com/dns-query?name=ERC-7529.1._domainc 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`. +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 `getDomain` 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. ```solidity { - public string[] domains; // a string list of eTLD+1 domains associated with this contract + /// @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; - function addDomain(string memory domain) external; // an authenticated method to add an eTLD+1 + /// @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 getDomain(string calldata domain) external view returns (bool); - function removeDomain(string memory domain) external; // an authenticated method to remove an eTLD+1 + /// @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 -The user client MUST verify that the eTLD+1 of the TXT record matches an entry in the `domains` list of the smart contract. +The user client MUST verify that the eTLD+1 of the TXT record returns `true` when passed as an argument to the `getDomain` function 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. +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 `getDomain` function. -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. +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 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 @@ -106,50 +129,25 @@ No backward compatibility issues found. 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): ```solidity +function getDomain( + string calldata domain + ) external view returns (bool) { + return domains[keccak256(abi.encodePacked(domain))]; + } + 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); + domains[keccak256(abi.encodePacked(domain))] = true; + emit AddDomain(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"); + require(domains[keccak256(abi.encodePacked(domain))] == true, "ERC7521: eTLD+1 currently not associated with this contract"); + domains[keccak256(abi.encodePacked(domain))] = false; + emit RemoveDomain(domain); } ``` From 1e5b64fdbe0d19d4c025d742b79c4904a4ae5f87 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Tue, 19 Mar 2024 22:25:11 -0700 Subject: [PATCH 12/15] additional tweaks --- ERCS/erc-7529.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index d78cc40a10..7bd234e1e2 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -126,7 +126,7 @@ 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): +The implementation of `addDomain` and `removeDomain` is a trivial exercise, but candidate implementations are given here for completeness: ```solidity function getDomain( @@ -151,7 +151,7 @@ function removeDomain( } ``` -**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. +**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 From 025c7eba728be53a9c5abf8ae517674a67482a91 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Tue, 19 Mar 2024 22:26:35 -0700 Subject: [PATCH 13/15] more tweaks --- ERCS/erc-7529.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index 7bd234e1e2..c29537120f 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -126,7 +126,7 @@ 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: +The implementation of `getDomain`, `addDomain` and `removeDomain` is a trivial exercise, but candidate implementations are given here for completeness: ```solidity function getDomain( From ffd1a890727b52b7a9df9367f6c406ee446717ed Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Tue, 19 Mar 2024 22:33:25 -0700 Subject: [PATCH 14/15] more tweaks --- ERCS/erc-7529.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index c29537120f..c80c014d41 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -106,13 +106,11 @@ determining all domains associated with a contract when they are not known ahead ### Client-side Verification -The user client MUST verify that the eTLD+1 of the TXT record returns `true` when passed as an argument to the `getDomain` function of the smart contract. - 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 `getDomain` 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 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. +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 From 04f471b8983e22aadc94a11da8de79b7ea65e5c1 Mon Sep 17 00:00:00 2001 From: TtheBC01 Date: Tue, 19 Mar 2024 22:34:30 -0700 Subject: [PATCH 15/15] typo --- ERCS/erc-7529.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7529.md b/ERCS/erc-7529.md index c80c014d41..4fc7c4a371 100644 --- a/ERCS/erc-7529.md +++ b/ERCS/erc-7529.md @@ -143,7 +143,7 @@ function addDomain( function removeDomain( string memory domain ) external onlyRole(DEFAULT_ADMIN_ROLE) { - require(domains[keccak256(abi.encodePacked(domain))] == true, "ERC7521: eTLD+1 currently not associated with this contract"); + 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); }