Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Initial ENS Registrar Specification #162
Some of the parameters and mechanisms in this document are outdated with respect to the version deployed on the main net. The following version was last updated 2017-03-13, and mostly describe the first version of the regirstrar deployed to the main net on 2017-03-14. It is kept here for posterity. An updated version can be seen here. Please also refer to ReadTheDocs or natspec comments in the deployed code.
This ERC describes the implementation of a registrar contract to govern the allocation of names in the Ethereum Name Service (ENS). For background, refer to EIP 137.
A well designed and governed registrar is essential to the success of the ENS described in EIP 137, but is described separately in this document as it is external to the core ENS protocol.
In order to maximize utility and adoption of a new namespace, the registrar should mitigate speculation and "name squatting", however the best approach for mitigation is unclear. Thus an "initial" registrar is proposed, which implements a simple approach to name allocation. During the initial period, the available namespace will be significantly restricted to the
This Initial Registrar contract will be replaced with a permanent registrar contract. The Permanent Registrar will increase the available namespace, and incorporate lessons learned from the performance of the Initial Registrar. This upgrade is expected to take place within approximately 2 years of initial deployment.
The following factors should be considered in order to optimize for adoption of the ENS, and good governance of the Initial Registrar's namespace.
Upgradability: The Initial Registrar should be safely upgradeable, so that knowledge gained during its deployment can be used to replace it with an improved and permanent registrar.
Effective allocation: Newly released namespaces often create a land grab situation, resulting in many potentially valuable names being purchased but unused, with the hope of re-selling at a profit. This reduces the availability of the most useful names, in turn decreasing the utility of the name service to end users.
Achieving an effective allocation may or may not require human intervention for dispute resolution and other forms of curation. The Initial Registrar should not aim to create to most effective possible allocation, but instead limit the cost of misallocation in the long term.
Security: The registrar will hold a balance of ether without an explicit limit. It must be designed securely.
Simplicity: The ENS specification itself emphasizes a separation of concerns, allowing the most essential element, the registry to be as simple as possible. The interim registrar in turn should be as simple as possible while still meeting its other design goals.
Adoption: Successful standards become more successful due to network effects. The registrar should consider what strategies will encourage the adoption of the ENS in general, and the namespace it controls in particular.
The Initial Registrar is expected to be in service for approximately two years, prior to upgrading. This should be sufficient time to learn, observe, and design an updated system.
During the initial two year period, the available name space will be restricted to the
This restriction is not implemented by the registrar, but rather by the owner of the ENS root node who should not assign any nodes other than
The Initial Registrar will also prohibit registration of names shorter than the
Name format for hash registration
Names submitted to the initial registrar must be hashed using Ethereum's sha3 function. Note that the hashes submitted to the registrar are the hash of the subdomain label being registered, not the namehash as defined in EIP 137.
For example, in order to register
The registrar will allocate the available names through a Vickrey auction:
The timeline of the auction will be implemented as follows:
The Initial Registrar contract does not hold a balance itself. All ether sent to the Registrar will be held in separate deed contracts. Deeds are initially associated with a bidder and their sealed bid. After an auction is completed and a hash is registered, the deed for the winning bid is held in exchange for ownership of the hash.
After 1 year of registration, the owner of a hash may choose to relinquish ownership and have the value of the deed returned to them. A deed for an owned hash may also be transferred to another account by its owner.
Deeds for non-winning bid can be closed by various methods, at which time any ether held will either be returned to the bidder, burnt, or sent to someone else as a reward for actions which help the registrar.
The following table outlines what portion of the balance held in a deed contract will be returned upon closure, and to whom. The remaining balance will be burnt.
Deployment and Upgrade process
The Initial Registrar requires the ENS's address as a contructor, and should be deployed after the ENS. The multisig account owning the root node in the ENS should then set the Initial Registrar's address as owner of the
The Initial Registrar is expected to be replaced by a Permanent Registrar approximately 2 years after deployment. The following process should be used for the upgrade:
In order to limit dependence on the Initial Registrar, new auctions will stop after 4 years, and all ether held in deeds after 8 years will become unreachable.
After the registration date has passed, this function can be called to finalize the auction, which then calls the ENS function
Starting with a temporary registrar
Anticipating and designing for all the potential issues of name allocation names is unlikely to succeed. This approach chooses not to be concerned with getting it perfect, but allows us to observe and learn with training wheels on, and implement improvements before expanding the available namespace to shorter names or another TLD.
Valid names >= 7 characters
Preserving the shortest, and often most valuable, domain names for the upgraded registrar provides the opportunity to implement processes for dispute resolution (assuming they are found to be necessary).
Restricting TLD to
Thanks for writing this up @maurelian!
Another important thing that I would like to stress out:
Auctioning should not be considered as buying a perpetual right to the domain, and a big part of the reason we want it to be temporary is so that the community can come up with a fair process for the renewal for the name. The main rationale behind this decision is that names are a limited resource with unknown future usefulnnes and we want to reduce, as much as possible, the incentives for a one time land grab. There are some interesting options being considered for exactly how to do that, but the main idea is that once you own a name there should be a rational incentive for users to release them back to the open market, specially if they are not doing any useful work with it. I won't go into details as it would derail the purpose of this particular EIP.
Also, notice that there's no party benefiting in any way from this auctions. The purpose of auctioning isn't a scheme to raise funds to anyone, but to create opportunity costs of holding names.
Good points. We should also emphasise that it's expected that any permanent registrar would provide a migration path for the vast majority of domain holders, but that there's no ironclad guarantee that every single domain bought on the temporary registrar will be able to migrate - one possible example being blatant phishing domains. There's also no guarantees that the pricing scheme of the eventual registrar will relate to the interim registrar's pricing.
I know it's not a short read, so questions are very welcome in the gitter chat room: https://gitter.im/ethereum/go-ethereum/name-registry
I also just put up a simple Truffle project to make it easy to deploy and interact with the registrar locally: https://github.com/maurelian/ens-registry-truffle
@rabbit Thanks for the question. By concern, do you mean that people might submit a false report?
In, re: unicode, wouldn't international characters make the seven-character minimum irrelevant? I can't find an example system for name-prep, but it appears that it will produce a much longer ASCII form of what may be only two Chinese characters. (Or even one?)
On that matter, I'm not sure what limiting system could be used such that it will make sense to users seeking to register international names.
It sounds like you're thinking of punycode. The name service doesn't use punycode; international domain names are represented directly as unicode, so a 2 character Chinese name will only be 2 characters long.
I mentioned this on Gitter, but it may also be of interest to anyone reading this.
My company builds out web based applications on good domain names. As an economist, and a software engineer I wrote the following as an interest piece.
It may provide some useful context re allocation.
referenced this issue
Dec 5, 2016
unfortunately from the ENS side, due to hashing, there wouldn't be a way to avoid that. limitations on all sides, apparently browser behaviors differ too. TIL.
for reference: https://en.wikipedia.org/wiki/Nameprep
RE unicode vs punycode, resolvers should not do unicode encoding (which leads to names like xn--foobar.com, for instance), but rather look up the unicode name directly.
Use of nameprep is discussed in #137. We don't go into browser prohibitions on names there, but should doubtlessly write up a guide; my suggestion is to suggest resolves adopt the same system as mozilla.
@rabbit @jarradh My opinion is that the ENS should be as flexible as possible in registering names but which names are accepted and how they are displayed should be left up to each client. So you could register
Contextual clues that firefox uses are actually a smart solution: I can see mist only accepting Unicode characters and characters from the user's system: i.e., only accept chinese characters if the user is using Mist in chinese, (or has visited that site before). The client can be smarter than the ENS contract
I agree, we need to come to an agreement on how to normalise, unicode characters like U+202E (right to left override) seem especially problematic. While other browsers have tackled this problem, they can rely on rendering punycode, where it doesn't seem so fitting in our case. The more I look at this problem the stickier it seems to get.
No, punycode is an entirely separate step from normalisation; normalisation is accomplished using nameprep. Nameprep is specified in #137 as the canonical way to normalise names on ENS.
In addition, user agents should prohibit names containing code points <0x80 other than
Update: The official and most recent standard to follow is UTS #46, which specifies normalisation rules and prohibited characters. Implementations should use UTS 46 with
I've updated #137's section on names accordingly.
Realise it's too late for this round, but thoughts for a later round of ENS auctions: as a compliment to being able to hide the upper bound of a bid through sending more than the bid value, one should be able to hide the lower bound of a bid through revealing multiple submissions to have contained the same "bid ID" and owner address, thus co-funding a single bid in blinded parts. Example: I want to bid 100 ETH so I make ten submissions with 10 ETH attached to each, but with all having the same blinded ID, owner address, and bid value (of 100 ETH), just different salts. When all 3 are revealed the attached amounts are counted as co-funding the single 100 ETH bid whose ID, owner address, and value they share. IDs which are insufficiently funded by the end of an auction, or where amounts and owners do not match across all submissions of the same ID, are invalid. This would, of course, require adding an ID field to the sealed bid format and significantly reworking the contracts that implement the auction. Note that we can't just use the owner address as the ID because owner addresses are sometimes public and this would permit scattershot invalidation of any bids made by that owner.
@maurelian With the ENS registrar deployment imminent in the mainnet the following may be misleading:
I was informed that on mainnet the auction/reveal phases will last 5 days and 48 hours.
Can you edit the EIP?
Is there proper handling of case sensitivity?
Also, performing the SHA3 of just the name doesn't seem sufficient to guard the secrecy. Assuming 7char are the most desired, I only need to generate ~8 Billion strings to know which 7 char [a-z] domains are being bid on. The best approach would be to include a salt when calculating the hash.
@chejazi the case senitivity issue is addressed in Nick's Jan 12 comments above.
There is a salt in the bid hashes: https://github.com/ethereum/ens/blob/master/contracts/HashRegistrarSimplified.sol#L320
Some of the parameters and mechanisms in this document are outdated with respect to the version deployed on the main net. Until this notice is removed or updated, please refer to ReadTheDocs or natspec comments in the deployed code.
And I commit to revising this in the next 24 hours.
added a commit
May 11, 2017
All information there should be accurate to the main net deployment.
I also plan to add another table similar to the refund schedule, listing the various timelines and other constants used in the contract.