--- eip: 4834 title: Hierarchical Domains description: Extremely generic name resolution author: Gavin John (@Pandapip1) discussions-to: https://ethereum-magicians.org/t/erc-4834-hierarchical-domains-standard/8388 status: Final type: Standards Track category: ERC created: 2022-02-22 --- ## Abstract This is a standard for generic name resolution with arbitrarily complex access control and resolution. It permits a contract that implements this EIP (referred to as a "domain" hereafter) to be addressable with a more human-friendly name, with a similar purpose to [ERC-137](./eip-137.md) (also known as "ENS"). ## Motivation The advantage of this EIP over existing standards is that it provides a minimal interface that supports name resolution, adds standardized access control, and has a simple architecture. ENS, although useful, has a comparatively complex architecture and does not have standard access control. In addition, all domains (including subdomains, TLDs, and even the root itself) are actually implemented as domains, meaning that name resolution is a simple iterative algorithm, not unlike DNS itself. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. ### Contract Interface ```solidity interface IDomain { /// @notice Query if a domain has a subdomain with a given name /// @param name The subdomain to query, in right to left order /// @return `true` if the domain has a subdomain with the given name, `false` otherwise function hasDomain(string[] memory name) external view returns (bool); /// @notice Fetch the subdomain with a given name /// @dev This should revert if `hasDomain(name)` is `false` /// @param name The subdomain to fetch, in right to left order /// @return The subdomain with the given name function getDomain(string[] memory name) external view returns (address); } ``` ### Name Resolution To resolve a name (like `"a.b.c"`), split it by the delimiter (resulting in something like `["a", "b", "c"]`). Set `domain` initially to the root domain, and `path` to be an empty list. Pop off the last element of the array (`"c"`) and add it to the path, then call `domain.hasDomain(path)`. If it's `false`, then the domain resolution fails. Otherwise, set the domain to `domain.getDomain(path)`. Repeat until the list of split segments is empty. There is no limit to the amount of nesting that is possible. For example, `0.1.2.3.4.5.6.7.8.9.a.b.c.d.e.f.g.h.i.j.k.l.m.n.o.p.q.r.s.t.u.v.w.x.y.z` would be valid if the root contains `z`, and `z` contains `y`, and so on. Here is a solidity function that resolves a name: ```solidity function resolve(string[] calldata splitName, IDomain root) public view returns (address) { IDomain current = root; string[] memory path = []; for (uint i = splitName.length - 1; i >= 0; i--) { // Append to back of list path.push(splitName[i]); // Require that the current domain has a domain require(current.hasDomain(path), "Name resolution failed"); // Resolve subdomain current = current.getDomain(path); } return current; } ``` ### Optional Extension: Registerable ```solidity interface IDomainRegisterable is IDomain { //// Events /// @notice Must be emitted when a new subdomain is created (e.g. through `createDomain`) /// @param sender msg.sender for createDomain /// @param name name for createDomain /// @param subdomain subdomain in createDomain event SubdomainCreate(address indexed sender, string name, address subdomain); /// @notice Must be emitted when the resolved address for a domain is changed (e.g. with `setDomain`) /// @param sender msg.sender for setDomain /// @param name name for setDomain /// @param subdomain subdomain in setDomain /// @param oldSubdomain the old subdomain event SubdomainUpdate(address indexed sender, string name, address subdomain, address oldSubdomain); /// @notice Must be emitted when a domain is unmapped (e.g. with `deleteDomain`) /// @param sender msg.sender for deleteDomain /// @param name name for deleteDomain /// @param subdomain the old subdomain event SubdomainDelete(address indexed sender, string name, address subdomain); //// CRUD /// @notice Create a subdomain with a given name /// @dev This should revert if `canCreateDomain(msg.sender, name, pointer)` is `false` or if the domain exists /// @param name The subdomain name to be created /// @param subdomain The subdomain to create function createDomain(string memory name, address subdomain) external payable; /// @notice Update a subdomain with a given name /// @dev This should revert if `canSetDomain(msg.sender, name, pointer)` is `false` of if the domain doesn't exist /// @param name The subdomain name to be updated /// @param subdomain The subdomain to set function setDomain(string memory name, address subdomain) external; /// @notice Delete the subdomain with a given name /// @dev This should revert if the domain doesn't exist or if `canDeleteDomain(msg.sender, name)` is `false` /// @param name The subdomain to delete function deleteDomain(string memory name) external; //// Parent Domain Access Control /// @notice Get if an account can create a subdomain with a given name /// @dev This must return `false` if `hasDomain(name)` is `true`. /// @param updater The account that may or may not be able to create/update a subdomain /// @param name The subdomain name that would be created/updated /// @param subdomain The subdomain that would be set /// @return Whether an account can update or create the subdomain function canCreateDomain(address updater, string memory name, address subdomain) external view returns (bool); /// @notice Get if an account can update or create a subdomain with a given name /// @dev This must return `false` if `hasDomain(name)` is `false`. /// If `getDomain(name)` is also a domain implementing the subdomain access control extension, this should return `false` if `getDomain(name).canMoveSubdomain(msg.sender, this, subdomain)` is `false`. /// @param updater The account that may or may not be able to create/update a subdomain /// @param name The subdomain name that would be created/updated /// @param subdomain The subdomain that would be set /// @return Whether an account can update or create the subdomain function canSetDomain(address updater, string memory name, address subdomain) external view returns (bool); /// @notice Get if an account can delete the subdomain with a given name /// @dev This must return `false` if `hasDomain(name)` is `false`. /// If `getDomain(name)` is a domain implementing the subdomain access control extension, this should return `false` if `getDomain(name).canDeleteSubdomain(msg.sender, this, subdomain)` is `false`. /// @param updater The account that may or may not be able to delete a subdomain /// @param name The subdomain to delete /// @return Whether an account can delete the subdomain function canDeleteDomain(address updater, string memory name) external view returns (bool); } ``` ### Optional Extension: Enumerable ```solidity interface IDomainEnumerable is IDomain { /// @notice Query all subdomains. Must revert if the number of domains is unknown or infinite. /// @return The subdomain with the given index. function subdomainByIndex(uint256 index) external view returns (string memory); /// @notice Get the total number of subdomains. Must revert if the number of domains is unknown or infinite. /// @return The total number of subdomains. function totalSubdomains() external view returns (uint256); } ``` ### Optional Extension: Access Control ```solidity interface IDomainAccessControl is IDomain { /// @notice Get if an account can move the subdomain away from the current domain /// @dev May be called by `canSetDomain` of the parent domain - implement access control here!!! /// @param updater The account that may be moving the subdomain /// @param name The subdomain name /// @param parent The parent domain /// @param newSubdomain The domain that will be set next /// @return Whether an account can update the subdomain function canMoveSubdomain(address updater, string memory name, IDomain parent, address newSubdomain) external view returns (bool); /// @notice Get if an account can unset this domain as a subdomain /// @dev May be called by `canDeleteDomain` of the parent domain - implement access control here!!! /// @param updater The account that may or may not be able to delete a subdomain /// @param name The subdomain to delete /// @param parent The parent domain /// @return Whether an account can delete the subdomain function canDeleteSubdomain(address updater, string memory name, IDomain parent) external view returns (bool); } ``` ## Rationale This EIP's goal, as mentioned in the abstract, is to have a simple interface for resolving names. Here are a few design decisions and why they were made: - Name resolution algorithm - Unlike ENS's resolution algorithm, this EIP's name resolution is fully under the control of the contracts along the resolution path. - This behavior is more intuitive to users. - This behavior allows for greater flexibility - e.g. a contract that changes what it resolves to based on the time of day. - Parent domain access control - A simple "ownable" interface was not used because this specification was designed to be as generic as possible. If an ownable implementation is desired, it can be implemented. - This also gives parent domains the ability to call subdomains' access control methods so that subdomains, too, can choose whatever access control mechanism they desire - Subdomain access control - These methods are included so that subdomains aren't always limited to their parent domain's access control - The root domain can be controlled by a DAO with a non-transferable token with equal shares, a TLD can be controlled by a DAO with a token representing stake, a domain of that TLD can be controlled by a single owner, a subdomain of that domain can be controlled by a single owner linked to an NFT, and so on. - Subdomain access control functions are suggestions: an ownable domain might implement an owner override, so that perhaps subdomains might be recovered if the keys are lost. ## Backwards Compatibility This EIP is general enough to support ENS, but ENS is not general enough to support this EIP. ## Security Considerations ### Malicious canMoveSubdomain (Black Hole) #### Description: Malicious `canMoveSubdomain` Moving a subdomain using `setDomain` is a potentially dangerous operation. Depending on the parent domain's implementation, if a malicious new subdomain unexpectedly returns `false` on `canMoveSubdomain`, that subdomain can effectively lock the ownership of the domain. Alternatively, it might return `true` when it isn't expected (i.e. a backdoor), allowing the contract owner to take over the domain. #### Mitigation: Malicious `canMoveSubdomain` Clients should help by warning if `canMoveSubdomain` or `canDeleteSubdomain` for the new subdomain changes to `false`. It is important to note, however, that since these are functions, it is possible for the value to change depending on whether or not it has already been linked. It is also still possible for it to unexpectedly return true. It is therefore recommended to **always** audit the new subdomain's source code before calling `setDomain`. ### Parent Domain Resolution #### Description: Parent Domain Resolution Parent domains have full control of name resolution for their subdomains. If a particular domain is linked to `a.b.c`, then `b.c` can, depending on its code, set `a.b.c` to any domain, and `c` can set `b.c` itself to any domain. #### Mitigation: Parent Domain Resolution Before acquiring a domain that has been pre-linked, it is recommended to always have the contract **and** all the parents up to the root audited. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).