Adding getting started with ens guide for dapp devs #15
Conversation
There was a problem hiding this comment.
Thanks for your contribution
This bulk of the PR looks more like a tutorial.
we are considering adding the tutorial section somewhere in the docs
but we don't have it yet.
Either way, it would be good if you could split this PR in 2 parts, 2 different pages
-
the first introductory section on what is ENS (that you might want to consider as proposed additions/corrections to the already existent introduction https://docs.ens.domains/, rather than a duplication of the page)
-
and a second page dedicated to the tutorial
if you need to put explainers about what ENS is and how it works in certain parts, please consider quoting and linking to existing material in the documentation.
In the tutorial page, please add under the title of the tutorial
a
#### tutorial contributed by [nanspro](https://github.com/nanspro)
and correct with the credit name and contact link of your preference
thanks
| ### Meaning of ENS | ||
|
|
||
| The Ethereum Name Service (ENS) is a useful tool for dapp developers. ENS is like DNS (Domain Name System), in that it maps a memorable shortcut to an address. Using ENS we can map the friendly name ethereum.eth to the rather unfriendly 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359. Subsequently, we can use the friendly name in-place of the address, making it easier to remember, and reducing the chance of errors.<br/> | ||
| An ENS name has a root name ethereum.eth which can contain sub-names like wallet.ethereum.eth. Whoever successfully bid for the root name in a Vickrey auction owns it.<br/> |
There was a problem hiding this comment.
An ENS name has a root name ethereum.eth which can contain sub-names like wallet.ethereum.eth.
This is not exactly right: the root name is not "ethereum.eth", just ".eth"
So I'd propose to change with something like this
an ENS name can be a subdomain of the root .eth domain, like example.eth or any subdomain of a subdomain, like sub.example.eth, or wallet.username.example.eth
Whoever successfully bid for the root name in a Vickrey auction owns it.
This also is no longer the case, the Vickrey auction was the mechanism to get a name in the first version, before the permanent registrar that was launched on mainnet on 2019-05-04
| An ENS name has a root name ethereum.eth which can contain sub-names like wallet.ethereum.eth. Whoever successfully bid for the root name in a Vickrey auction owns it.<br/> | |
| an ENS name can be a subdomain of the root .eth domain, like `example.eth` | |
| or any subdomain of a subdomain, like `sub.example.eth`, or `wallet.username.example.eth`<br/> |
| ENS doesn't just map to addresses. ENS is highly extensible and supports many types of mappings. It is possible to map the same friendly name to multiple endpoints at the same time. <br/> | ||
| ENS gets rid of the necessity of copying or typing lengthy hexadecimal addresses. With ENS, you’ll be able to send funds to the domain name instead of the long address, engage with your smart contract at mycontract.eth, and check out swarm-hosted sites at swarmsite.eth. <br/> | ||
|
|
||
| ENS is a completely decentralized system. Creating new domains under the “.eth” top-level domain is possible by an auction process that takes place on the Ethereum blockchain, and anyone can procure a domain for themselves by taking part. |
There was a problem hiding this comment.
again the auction has been discontinued and there are these 2 ways to get ENS Names
- get ENS Names under the .eth Top level domain through the permanent registrar
- get subdomains of ENS Names through different dApps that offer it (Status, Gitcoin, Argent, Tenzorum, Zinc, Aragon, etc)
and in the future these other ways will also be added
- get subdomains of certain ENS Names directly through the ENS Subdomain Registrar
- register ENS Names under the .xyz or .luxe TLDs
- register ENS Names, between 3 and 6 characters, that will be allocated through a 45 day long Vickrey Auction between Q2 and Q3 2019.
|
|
||
|
|
||
| #### ENS Subdomains | ||
| They can also give more of an organizational feel to users, where the domain represents the organization and the subdomain resembles the structure of email addresses. A novel use case currently being implemented by Tenzorum Project is to use your subdomain as a username/login to Ethereum ĐApps. <br/> |
There was a problem hiding this comment.
Subdomains have all the properties of simple ENS Names / domains
you can use them in the same way.
The expression give more of an organizational feel to users seem a bit arbitrary and suggests only one possible use, of the many, for subdomains.
it would be more appropriate to be more descriptive:
- explain first what subdomains are (maybe aggregating texts from other parts)
- only after give some example of possible uses, (using the conditional because there are many different uses), like
where the main ENS domain could represent the organization and the subdomain would resembles the different users email addresses
A novel use case currently being implemented by Tenzorum Project is to use your subdomain as a username/login to Ethereum ĐApps.
there are many dApps offering this already, as mentioned before, and there should be a mention also to Alex Van De Sande Universal Logins
|
|
||
| #### ENS Subdomains | ||
| They can also give more of an organizational feel to users, where the domain represents the organization and the subdomain resembles the structure of email addresses. A novel use case currently being implemented by Tenzorum Project is to use your subdomain as a username/login to Ethereum ĐApps. <br/> | ||
| Subdomains map names to addresses exactly the same way as domains do, but you don’t need to go through an auction process to create one. Luckily, there is no minimum length limit on ENS subdomains, either. To register a subdomain, you have to be the owner of the domain as a prerequisite. |
There was a problem hiding this comment.
To register a subdomain, you have to be the owner of the domain as a prerequisite.
You can also register subdomains of other ENS Names that you don't own
but that their owners have allowed others to create subdomains of, for free in some cases, and at a periodic/annual cost in other cases.
These subdomains will soon be registerable through the ENS Subdomain Registrar
| They can also give more of an organizational feel to users, where the domain represents the organization and the subdomain resembles the structure of email addresses. A novel use case currently being implemented by Tenzorum Project is to use your subdomain as a username/login to Ethereum ĐApps. <br/> | ||
| Subdomains map names to addresses exactly the same way as domains do, but you don’t need to go through an auction process to create one. Luckily, there is no minimum length limit on ENS subdomains, either. To register a subdomain, you have to be the owner of the domain as a prerequisite. | ||
|
|
||
| **Prerequisites**<br/> |
There was a problem hiding this comment.
From "Prerequisites" on it looks to me more like a tutorial.
We are considering adding the tutorial section somewhere in the docs
but we don't know yet.
it would be good if you could split this PR in 2 parts, 2 pages
-
the first introductory section on what is ENS (that you might want to consider as proposed additions/corrections to the already existent introduction https://docs.ens.domains/, rather than a duplication of the page)
-
and a second page dedicated to the tutorial
if you need to put explainers about what ENS is and how it works in certain parts, please also consider quoting and linking to existing material in the documentation
|
Hey @lyricalpolymath are you with the ENS team? Thanks for the comments, I was the bounty staker for this task. The original brief was for a tutorial, hence the tutorial style submission. I'll take a look through the comments you submitted, and I am just about to start an overall language and grammar sweep anyway. |
|
Nice work @ChrisChinchilla ! Please replace UTF-8 quotes |
|
@industral done!! |
|
Reviewing and testing this now. Watch this space. |
|
@nanspro this required quite a lot of editing (that you can find in this PR - nanspro#1), and the first half was mostly from the existing blog post, I'm uncertain how useful the 2nd half is, as it's not full examples, but code snippets. It's a good start, but not quite a getting started guide yet. @Arachnid are you able to offer any opinions on if this at least as start to what you were looking for? And we can figure out what's needed to get it finished up. |
|
Apologies for this @ChrisChinchilla , me and @owans will update this PR and also do a proper check on other 3 PR's to make them better |
|
OK, this is now good for me and I'll pay the bounty out. I can work with the ENS team to do the final polish and get it merged. |
|
This is out of date |
Fixes #10