Introduction
The ENS Name Wrapper
Example - Step By Step
Example - Parent Locks Subname All-In-One
Example - Multiple Subnames in Various States
Name Wrapper Fuses
Name Wrapper Expiry
Approved Operators
DNS Domains and Fuses
Use-Cases
1.) I want to give subnames out to all of my DAO members / NFT holders!
2.) I want to sell / rent out subnames!
3.) Other cool things you can do
Issue subdomains as tickets to an event
Lock the resolved records for a name
Recap
Other Links
Before we dive into the Name Wrapper, let’s briefly recap some basic ENS concepts that will give some helpful context.
The Registry is the core contract at the heart of ENS resolution. All ENS lookups start by querying the registry. The registry is not just for .eth second-level names (like name.eth), but for all ENS names (subnames like sub.name.eth, and also DNS names like domain.xyz). The owner of the name in the registry is also referred to as the Controller or Manager of the name.
The .eth Registrar is specific to .eth second-level name registrations. This is essentially a subdomain registrar for the TLD (top-level domain) .eth. When you register a .eth name, the registrar issues you an ERC-721 NFT.
The owner of that NFT is also referred to as the Registrant or Owner of that name. It can be used to reclaim ownership over the name in the core registry as well (in other words, the Registrant can overwrite the Controller).
As you can see, without the Name Wrapper, only .eth second-level names are NFTs currently. Subnames and DNS domains do not have NFTs associated with them by default, unless a custom contract is created for that purpose.
Woah don’t worry, I’ll explain all of this soon enough.
The Name Wrapper wraps an ENS name into a new ERC-1155 NFT. Any ENS name can be wrapped, whether it’s a .eth name or DNS domain or even any subname!
There is a Use-Cases section later on in this article too.
You can take your name.eth…
And turn it into a wrapped ERC-1155 NFT!
Let’s take our sub1.name.eth subname from up above, and wrap it!
Now the subname is a wrapped ERC-1155 NFT too!
Those lines you see represent so-called “permission fuses” for your wrapped ENS name, which I’ll explain in a bit.
How does this affect the core registry though?
When you wrap a name, you are setting the Controller to the Name Wrapper contract. In return, the Name Wrapper issues an ERC-1155 NFT and transfers it to you.
For .eth second-level names, you transfer the Registrant / NFT (in the .eth registrar) to the Name Wrapper contract when you wrap. The Name Wrapper will automatically reclaim the Controller in the core registry too.
Before, there was no NFT at all (for subnames and DNS names at least):
After you wrap a name, technically the Controller in the registry is now the Name Wrapper contract. That means that you cannot interact directly with the ENS registry for that name, because you are not the Controller.
However, the Name Wrapper contract provides all the necessary methods so that you can still interact with the registry. You can transfer ownership, set the resolver/TTL, and even create subnames just as you would normally. On top of that, any subnames you create will be automatically wrapped by default as well!
We’re almost ready to see some visual examples! But first, let’s get some terminology out of the way…
In addition to all the functionality that the name gains from being a fully-fledged ERC-1155 NFT, the Name Wrapper provides a number of ENS-specific features as well.
It does this with a “fuse” system. Each “fuse” represents some kind of permission for the name. When you burn a fuse, you are usually revoking some kind of permission. In the ENS Manager UI, this is available in the “Permissions” section of the name.
For example, by default when you wrap a name, you can transfer that NFT around freely, just as you can with other NFTs. However, if the “Cannot Transfer” fuse is burned, then the NFT becomes non-transferrable. In the ENS Manager UI, you would do this by revoking the “Can send this name” permission.
As the name implies, once you burn a fuse, you cannot undo that action, until the expiry at least.
The expiry is how long the fuses are active for. The expiry on a name is set by the parent owner. For .eth second-level names, the expiry is set to the same expiry from the .eth registrar. When the expiry is reached, all fuses reset. In addition, if your name is Emancipated or Locked, then you lose ownership of the name when it expires. There is a section later that goes into greater detail about the expiry.
There are also special fuses that determine the relationship between “parent” and “child” names, or alter the state of the wrapped name. A name can be in one of these possible states:
The name has not even been registered/created yet, or it has expired.
The name exists and has not expired (in the case of .eth second-level names). The Name Wrapper contract does not have ownership over the name. You own the name in the registry and/or .eth registrar.
The Name Wrapper contract has ownership of the name (in the registry/registrar). You are issued an ERC-1155 NFT in return, which proves that you are the actual owner. You can unwrap the name at any time, which burns the ERC-1155 NFT, and returns ownership in the registry/registrar back to you. If your name is a subname like sub.name.eth, then the owner of name.eth can technically replace the subname and transfer it to a different owner. In addition, the parent owner can burn parent-controlled fuses on your name.
The owner of the parent name is no longer able to replace this name, or burn any additional fuses on it. All .eth second-level names (like name.eth) are automatically put into the Emancipated state when they are wrapped. The name can still be unwrapped and rewrapped by the owner.
The name can no longer be unwrapped. The owner can now burn owner-controlled fuses on the name. Fuses for subnames of this name can now be burned as well.
Let’s dive into an example to learn more about fuses.
Say you have name.eth and sub1.name.eth, both wrapped. You have already locked name.eth, but no fuses have been burned on the subname yet.
The subname is Wrapped but not yet Emancipated, so the parent still has full control. Check out the diagram below, see that anchor there in the top-left of the subname? This means that the parent owner can still control the subname. It can burn Parent-Controlled Fuses, or it can even completely replace the subname if it wanted to.
The owner of the subname can still unwrap/rewrap, transfer, set the resolver/TTL, and even create new subnames of its own. However the owner cannot burn any fuses on the subname or any sub-subnames yet.
I’ll keep the name.eth node stripped down so it’s hopefully not as confusing, since we’re focusing on the sub1.name.eth subname right now. See the diagram below:
While in this state, the parent owner can burn Parent-Controlled Fuses while continuing to have full control over the subname.
There are 3 total predefined Parent-Controlled Fuses, and then there are 13 undefined fuses that you can use however you wish. One way to think of these fuses are as "perks" for the owner of the subname.
For example, if you are using ENS subnames to issue tickets to an event, you could use these Parent-Controlled Fuses to unlock perks, like the ability to redeem some swag or get into a special event (maybe it even automatically integrates with one of those smart door locks when the person taps an access card!).
I’ll show one of the Parent-Controlled Fuses being burned in the diagram below. In this case, it’s the CAN_EXTEND_EXPIRY fuse, which allows the subname owner to extend their own expiry (there is a section later going over all the fuses and what they do).
To Emancipate a name, burn the special "Parent Cannot Control" fuse.
After burning, no more fuses will be able to be burned by the parent.
The owner of the parent name will also no longer be able to replace the subname.
Remember that anchor in the top-left of the diagram? Burning the PCC fuse will blow that away! Without that anchor, the child drifts away from the parent and severs all the remaining fuses. So the parent owner will no longer have any control over this child!
In addition, see that other fuse going down below PCC? It will also blow away a section of wall, giving the subname owner access to its own “matchbox”! The subname owner will now be able to burn fuses on their own.
I’ve circled these places in green in the diagram below:
The subname sub1.name.eth is now Emancipated.
The parent can no longer burn any fuses, or replace the subname (up until the expiry).
The subname is not yet Locked though, so the owner of the subname can still unwrap the name if they want! If the name is unwrapped and then rewrapped, everything will still be in the same Emancipated state with the same fuses burned.
Because the name is not yet Locked, the owner of the subname cannot burn any other fuses (besides “Cannot Unwrap”). The owner cannot burn any fuses on any of its own subnames yet either.
See that section below that is now green? Now that the parent has burned PCC, the owner has access to its own “matchbox”, and can start playing with fire!
You might also notice that the fuse for “Cannot Unwrap” is accessible from within this same section…
To Lock a name, burn the special "Cannot Unwrap" fuse.
This can only be burned if PCC (Parent Cannot Control) has first been burned by the parent.
In other words, it can only be burned if the name is already Emancipated.
See that bundle of dynamite with “CU” next to it? That’s gonna blow when you burn the Cannot Unwrap fuse. If you follow the other fuses attached to it, you’ll see that it’ll also blow up a few other things, which I’ll go over next.
I’ve circled in green the areas that will be affected in the diagram below:
The subname sub1.name.eth is now Locked. This means that the name can no longer be unwrapped.
Look at the diagram below, Simba. Everything the green light touches is our kingdom.
Now that the name is Locked, the owner can burn other Owner-Controlled Fuses. The owner can also burn fuses for any subnames of its own.
There are 7 total predefined Owner-Controlled Fuses, and then there are 9 undefined fuses that you can use however you wish.
For example, you can burn "Cannot Transfer" and "Cannot Set Resolver".
Now the name cannot be transferred/sold, and the resolver contract can no longer be overwritten, up until the expiry.
If you burn the special "Cannot Burn Fuses" fuse, then no more fuses can be burned on the name.
The parent owner may burn this fuse on a subname to ensure that some permissions remain "locked open".
The owner of the name could also choose to burn it. For example, if the name uses a subdomain registrar, the owner could leave “Cannot Create Subname” unburnt, and then burn the "Cannot Burn Fuses" fuse to guarantee that new subnames can always be registered.
See the remaining bundle of dynamite with “CBF” next to it? Once that blows, all of the other Owner-Controlled Fuses will be rendered inaccessible. I’ve circled it in green below:
The "Cannot Burn Fuses" fuse has now been burned.
The fuses for the name are now completely frozen until its expiry. Any previously burned fuses will remain in that burned state, but no other fuses can be burned on this name now.
However, the owner can still burn fuses of any subnames, assuming that it has not yet emancipated them.
Okay, so I simplified a few things earlier to make it easier to follow.
Usually there won't be so many steps. The parent can burn multiple fuses at once, and take the name all the way to the Locked state in one fell swoop.
For example, say you want to emancipate and lock a subdomain, and burn a Parent-Controlled fuse, and burn some Owner-Controller fuses too?
To do that, you will burn "Parent Cannot Control" and "Cannot Unwrap", and all the other fuses you want, all in one transaction.
Remember, once PCC is burned, no further fuses can be burned by the parent.
Also, if you want to burn any Owner-Controlled Fuses, you must also burn CU (Cannot Unwrap). You may have noticed that purple “CU Lock” on the diagram. That indicates that in order to burn any of those fuses, you must also burn CU.
In addition, the CU fuse can only be burned if PCC is already burned, or burned at the same time. Similarly there is that purple “PCC Lock” on the diagram. That indicates that in order to burn CU, you must also burn PCC.
I know this is a lot to take in, but as an example, I've highlighted some fuses in green below:
After burning those fuses, the subname is now Locked.
In addition, the “Can Extend Expiry” fuse was burned, and the "Cannot Transfer" fuse was also burned.
The owner of the subname still has the ability to burn other fuses and create new subnames of its own in this case. The parent could have decided to restrict things even further by burning other fuses, like "Cannot Create Subname" or "Cannot Burn Fuses".
But now that the parent has burned PCC, it has relinquished control over this subname, and it can no longer burn anything else.
So we just saw how you can take an existing wrapped subname, and Emancipate / Lock it, with fuses burned, all in one step.
Just so you know, the same can also be done when you create an entirely new subname!
If your name is wrapped, and you create a new subname under it, that subname will also be wrapped by default. And at the same time, in the same transaction, you can also pass in your desired list of fuses to burn (and the expiry).
So you do not have to create a subname and then separately burn fuses. You can do everything in one transaction.
Now let’s zoom out a bit, and I’ll even fill in the name.eth wrapper this time.
Remember that .eth second-level names are automatically put into the Emancipated state when they are wrapped. They are not automatically Locked though. When you register/wrap a .eth second-level name, you can pass in any owner-controlled fuses you want to burn to start with, so you can go directly to the Locked state if you wish.
As you can see, each subname does not have to be in the same state. Some can be Locked, some Emancipated, and some merely Wrapped. It’s entirely up to the owner of the parent name and how much power or freedom they want to give to child names.
This will depend on the use-case. Using subnames for a temporary ticketing system is going to have different constraints than a permanent subdomain registrar, for example.
As previously mentioned, a "fuse" is a permission or perk that can be granted/revoked on a name. As the name implies, once the fuse is "burned", it cannot be unburned. Fuses will only reset when the expiry is reached.
There are parent-controlled and owner-controlled fuses:
PARENT_CANNOT_CONTROL:
Allows a parent owner to Emancipate a child name. After this is burned, the parent will no longer be able to burn any further fuses, and will no longer be able to replace/delete the child name. This fuse must be burned in order for any owner-controlled fuses to be burned on the name.
IS_DOT_ETH:
This fuse cannot be burned by users of the Name Wrapper, it is only set internally when a .eth 2LD is wrapped.
CAN_EXTEND_EXPIRY:
The owner of the child name will be able to extend their own expiry. Normally, only the parent owner can extend the expiry of a child name.
Custom Fuses:
There are 13 other parent-controlled fuses that are not reserved, and can be used in any custom way you want!
CANNOT_UNWRAP:
The name will now be Locked, and can no longer be unwrapped. This fuse must be burned in order for any other owner-controlled fuses to be burned on the name.
CANNOT_BURN_FUSES:
No further fuses can be burned on the name.
CANNOT_TRANSFER:
The name (wrapped NFT) can no longer be transferred.
CANNOT_SET_RESOLVER:
The resolver contract for the name can no longer be updated.
CANNOT_SET_TTL:
The TTL for the name can no longer be updated.
CANNOT_CREATE_SUBDOMAIN:
New subdomains can no longer be created.
CANNOT_APPROVE:
The approved subname renewal manager for the name can no longer be updated. See the Approved Operators section below for more information.
Custom Fuses:
There are 9 other owner-controlled fuses that are not reserved, and can be used in any custom way you want!
For unwrapped names, only .eth second-level names (like name.eth) have the concept of an expiration date (set in the .eth Registrar). The Name Wrapper has the concept of an expiry as well, which can apply to .eth subnames too. This expiry determines how long any burned fuses are active for, and may also determine whether the name itself has expired. In order to use fuses, a name must also have an expiry set.
When the Name Wrapper is used:
The expiry for .eth second-level names will automatically be set to the expiry from the .eth Registrar (plus the grace period).
It’s possible the wrapped expiry can get “out of sync” if you renew via the old registrar controller contract. In this case, you can re-sync the wrapped expiry by calling the renew method on the wrapper contract.
Other .eth subnames can have their own separate expiry, and at maximum it can be set to the expiry of the parent node.
The expiry does not apply to any DNS names, since they currently cannot use fuses.
You may choose to not burn any fuses on a subname and leave it in the Wrapped state if you wish. In that case, the expiry has no practical effect and can just be left as 0. However if you wish to burn any fuses (or emancipate/lock a subname, which requires fuses to be burned), then you must also set an expiry.
The expiry applies to all fuses that may have been previously burned, both parent-controlled and owner-controlled. When the expiry has been reached, all fuses will be reset.
By default, the expiry for a name can only be set by the parent, and can only be increased, not decreased. The maximum value for the expiry of a name is the expiry of its parent name.
For example, say a name expires in 5 years. The owner of the name can then set the expiry of its subnames to a maximum of 5 years as well. But the parent could also choose to set the expiry to something less. Let’s say the parent sets the expiry of one of its subnames to 2 years. Then in turn, the owner of the subname can set the expiry of its own subnames up to a maximum of 2 years, but it could also set it to something less, like 1 year.
The parent can set a different expiry for different subnames too, just as it can burn different fuses for different subnames.
When a wrapped .eth second-level name (like name.eth) is renewed, that new expiry is automatically set in the Name Wrapper as well as in the .eth Registrar. However, the expiry for any other .eth names (like sub.name.eth) will not be automatically extended when the parent expiry is extended.
The parent can extend the expiry for an existing subname at any time, even if the subname has been emancipated.
The parent can also choose to approve a separate contract to allow the expiry for subnames to be extended by the subname owner or other accounts. That is basically how .eth second-level names work: Since the eth node is locked in the registrar contract and has the Name Wrapper (which exposes a renew method) approved as a controller, .eth second-level names can be directly renewed by their owners. The parent can further lock this approved contract in by burning the CANNOT_APPROVE fuse.
There is also a special parent-controlled fuse called CAN_EXTEND_EXPIRY. If the parent burns this fuse on a subname, then the owner of that subname (or any approved controller) can also extend the expiry.
So, if you are running a subname registrar and you want to enable “unruggable renewals”, you can use one of the above options (or both).
For .eth second-level names, the end of the name’s grace period (from the .eth Registrar) is used for the expiry inside of the Name Wrapper. So if the name’s expiration date in the Registrar is January 1st, then the expiry in the Name Wrapper will reflect that date plus the grace period (currently 90 days, so approximately April 1st, depending on the year).
When the name’s expiration date (from the .eth Registrar) has been reached, and the name is now in the grace period, all Name Wrapper operations on the name will be restricted. The owner will not yet lose ownership of the name, but they will also not be able to unwrap or update the name until it has been renewed.
When a name is merely Wrapped but not Emancipated or Locked, parent-controlled fuses can still be burned. This means that the parent can burn a custom fuse for a limited amount of time. When the expiry is reached, all fuses will be reset, but the name will otherwise be unaffected. Also, as a reminder, the parent must first be in the Locked state before it can burn fuses on any subnames.
When a name is Emancipated or Locked, the expiry has an important additional effect. In this scenario, when the expiry has been reached, the name itself will expire, and the owner loses ownership of the name. The Name Wrapper contract will return the null address (0x000…) as the owner for any expired name. This means:
The name will not be able to be transferred.
The NFT for the name may disappear from websites/dapps/wallets as the owner is now the null address.
The resolver/TTL will not be able to be updated.
New subnames will not be able to be created.
Existing subnames will not be able to be altered.
Depending on the resolver contract, the name may continue to resolve to any records that were set before the name expired.
Depending on the resolver contract, records for the name may no longer be updatable.
When a subname expires, the parent regains the power to completely replace the subname, with a new expiry, a new set of fuses, and even a new owner. That “new set of fuses” is up to the parent. They could choose to completely reset all fuses, or they could choose to use the same set of fuses that were previously set before the subname expired. So if the parent wanted to simply “reactivate” the subname in the same state it was before, it could recreate the subname with the same owner and same set of fuses, but with a new expiry.
Your wrapped name is an ERC-1155 NFT that supports the setApprovalForAll method. When you approve an address using this method, it will have full control over all wrapped ENS names that you own.
This method is typically used by NFT marketplace contracts.
The Name Wrapper also supports the ERC-721 approve method. This method is used to approve a single “Subname Renewal Manager” for a specific name.
The “Renewal Manager” does not have full control over your wrapped name, it can only set / extend the expiry on subnames.
Further, if you burn the CANNOT_APPROVE fuse on your name, then the approved renewal manager can no longer be changed. You can use this to “lock in” that contract, so that you can guarantee to all subname owners that renewals/extensions can always be done.
This approved renewal manager will be reset if the wrapped NFT is burned or re-minted, which happens if you unwrap the name, or if an expired name gets re-registered. It will also be reset if the wrapped NFT is transferred, unless the CANNOT_APPROVE fuse is burned.
You can use these operator approval methods to setup a separate contract that can take certain actions on your behalf. One example is setting up a “subname registrar” to allow users to register/renew subnames.
That subname registrar contract would act on your behalf and allow users to register subnames. To allow this, you would call setApprovalForAll to give that contract full control over your name (and thus the ability to create subnames).
Then, to enable “unruggable renewals”, you could call approve on that same contract (or a separate one specific to renewals if you wish) and burn CANNOT_APPROVE to lock in subname renewals for that contract.
If you need to later on, you would still be able to revoke with setApprovalForAll. So the contract would lose full control over your name (and the ability to create new subnames), but it would still be able to perpetually renew/extend existing subnames.
And you can do all of this without needing to send your wrapped NFT to that contract.
As previously explained, in order to burn fuses on a name, the parent name must be Locked. The reason is, if the parent name was not locked, then the owner of the parent name could simply get around the constraints of the Name Wrapper by unwrapping the name, and replacing/revoking subnames against the core ENS Registry.
This is why I’ve said in this guide that currently, only .eth names support fuses, because only the eth node is on-chain native and completely locked beyond anyone’s control.
This is not to say that DNS names “can’t ever” use fuses. Technically speaking, the owner of a DNS TLD has the ability to burn fuses on that TLD in the Name Wrapper, and set it to the “Locked” state. And then from there, all subnames under that DNS TLD will be able to use fuses. The DNS TLD owner would need to:
Request the Controller of that TLD from the ENS DAO
Wrap the TLD node in the Name Wrapper
Burn the PARENT_CANNOT_CONTROL and CANNOT_UNWRAP fuses on the wrapped TLD to lock it
However, this still does not have all the immutable guarantees that .eth names do. This is because for DNS names, the “source of truth” always lies not in the Ethereum network, but in the DNS network, and the DNS root zone governed by ICANN stakeholders.
So even if the DNS TLD owner “Locks” that TLD in the ENS Name Wrapper, if that TLD were to ever change ownership on the DNS side, then (per the ENS DAO constitution) the new owner would be able to override control of that TLD on the ENS side, unwrap it, and replace/revoke all 2LDs.
This is just something to keep in mind for wrapped DNS domains.
However, even if wrapped DNS domains do not support fuses, you can still use them as ERC-1155 NFTs. They will still have their own NFT metadata and show up in your wallet, with whatever avatar you have set, etc. They just won’t have all the extra functionality that comes with the fuse/permission system.
Say you own the wrapped name mycoolnft.eth, representing a popular NFT project you created. You want to distribute subnames like 6529.mycoolnft.eth to all holders.
One option is to just bulk create the subnames and drop the wrapped NFTs into their wallets. This might be good at least as an initial drop, because then the holders don’t need to interact with any contract or spend any gas, you’re doing that for them!
To create the subnames, you’d use the setSubnodeOwner or setSubnodeRecord methods.
You must also decide:
Do you want to be able to revoke subnames? Or do you want them to be completely outside your control?
One thing to consider is whether you want the current holder of your NFT to always be able to claim/reclaim the corresponding ENS subname. If so, then you will not want to Emancipate those subnames (in other words, do not burn PARENT_CANNOT_CONTROL). If the subname is Emancipated, then the NFT holder could sell/transfer the NFT but keep the subname (up until the expiry).
To make it easy for anyone to claim/reclaim a subname after your initial drop, you can set up a contract for this.
The claim method of your contract could:
Call ownerOf or balanceOf on your NFT contract to get or verify the current owner of the NFT
Call ownerOf or balanceOf on the ENS Name Wrapper contract to get or verify the current owner of the wrapped subname
If both owner addresses are the same, just return, nothing to do
Call setSubnodeOwner or setSubnodeRecord on the ENS Name Wrapper:
owner: The current owner of the NFT
fuses: What fuses you want to burn (if any) on that subname. If you burn any fuses, you must also set an expiry.
expiry: When the subname will expire.
Then, to give that contract access to create subnames on your behalf, you would call setApprovalForAll on the Name Wrapper to approve your contract as an operator.
Now, even if the NFT gets sold / transferred, the new owner will be able to claim their mycoolnft.eth subname at any time.
In addition, if you expand your NFT collection in the future and there are new owners, then those new owners would be able to claim their subnames as well.
If you are creating a new NFT contract, you could even bake this functionality directly into the NFT contract too, instead of needing a separate contract! By doing this, you wouldn’t need a separate claim method either, your NFT contract would just automatically transfer the wrapped ENS subname whenever the NFT itself gets transferred!
If you decide to not Emancipate the subnames that you issue, you will still be able to burn any Parent-Controlled Fuses. There are 13 unreserved parent-controlled fuses that you can use however you wish!
For example, perhaps you want to grant on-chain “perks” or “roles” to certain holders. You would call setChildFuses on the Name Wrapper and pass in the fuses you want to burn, and the expiry.
This means that those “perks” or “roles” can also be time-boxed if you want. Maybe a perk expires in 1 week or something, up to you.
There is also the reserved CAN_EXTEND_EXPIRY parent-controlled fuse. If you burn this, then the subname owner will be able to extend their own expiry whenever they want.
Say you own the wrapped name verypopularname.eth. Obviously you can just manually create wrapped subnames like my.verypopularname.eth and then sell them on an NFT marketplace. But that sure doesn’t scale well.
To accomplish this, you will want to create a subname registrar. This is a contract that will handle all the registration / renewal for you, and then users will be able to interact with that contract in order to register their own subnames.
In fact, this is exactly how .eth 2LDs are registered. The owner of the eth TLD (the NFT contract) delegates registration / renewal to the ETHRegistrarController contract. It is acting as a subname registrar for the name eth.
Your contract would expose a register method that anyone can call. Under the hood it will use the setSubnodeOwner or setSubnodeRecord methods to create subnames, passing in the fuses and expiry you want to set.
First, note that if you want to burn any fuses on subnames, then your name must be Locked (meaning CANNOT_UNWRAP is burned).
Assuming that you want your subnames to be “unruggable”, such that you cannot replace / revoke them, then you will want to burn PARENT_CANNOT_CONTROL on the subnames. This will place them in the Emancipated state upon registration.
If you want to sell “forever” subnames, where users register once and can then keep them for as long as they wish, then you can consider burning the CAN_EXTEND_EXPIRY fuse. This will allow the subname owner to extend their own expiry whenever they want. The max expiry is the expiry of the parent name, but the .eth Registrar allows anyone to renew/extend a .eth 2LD as well.
If you just want to rent subnames, then do not burn CAN_EXTEND_EXPIRY. Instead, you could include a renew method on your contract that users can call for another fee.
If you want to enable “unruggable renewals” for your registrar, to guarantee that users will always be able to renew, then you can call approve on the Name Wrapper and approve your registrar contract as the “subname renewal manager” for your name. Then, burn the CANNOT_APPROVE fuse on your name, to guarantee that you can never revoke that contract for subname renewals. See the Approved Operators section above for more info.
If you want to impose other restrictions on your registered subnames, then you can burn the CANNOT_UNWRAP fuse to Lock the subname, and also burn whatever other fuses you want.
For example, if you want to prevent owners of your subnames (like my.verypopularname.eth from creating their own subnames (like buy.my.verypopularname.eth), then you would burn CANNOT_UNWRAP and CANNOT_CREATE_SUBDOMAIN.
To recap on fuses…
Sell permanent names:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL
Sell permanent names, but prevent them from creating their own subnames:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_CREATE_SUBDOMAIN
Rent out names:
PARENT_CANNOT_CONTROL
Rent out names, but prevent them from transferring or reselling them:
PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_TRANSFER
And so on, it’s up to you. You can also burn whatever custom parent-controlled or owner-controlled fuses you want to.
Yes! It’s your registrar contract, so you can impose whatever rules and fees you want.
For example, the .eth Registrar imposes a 3-character minimum on all names, as well as a custom fee structure and a temporary premium auction upon expiration.
By default there is no character limit on subnames, but your contract could have its own rules and fee structure or whatever you want. For example, you can:
Allow or disallow specific addresses from registering / renewing
Only allow registration based on some custom criteria like holding a specific NFT
Custom length restrictions like only 3+ characters or < 100 characters
Only allow names with characters [a-z0-9] and nothing else
Use a custom fee structure based on:
The length of the name
The specific characters that are in the name, like emojis
A pre-curated list of “good” names like people’s first names
And whatever other rules you want.
If writing and deploying your own contract seems daunting, then don’t worry, the ENS Labs devs are working on some basic subname registrar contracts that anybody will be able to use.
I’m sure that the ENS community will create all kinds of other registrar contracts and tools you can use too!
Maybe you have mycoolevent.eth and you want to issue tickets like 1.ticket.2023.mycoolevent.eth.
If you want, you can choose to not Emancipate those subnames, but still burn some custom parent-controlled fuses. Those fuses might:
Indicate what “tier” their event ticket is
Maybe they can upgrade their ticket to a higher tier, which would burn some additional fuses
Allow them access to the express line or some VIP room
Maybe even automatically via some smart door
When you burn those fuses, perhaps you also set the expiry to the day after the event ends.
Or, maybe you want your attendees to be able to keep their subnames as a souvenir or proof-of-attendance!
If so, then instead of letting the names expire at the end of the event, you could extend the expiry and burn some additional fuses to allow the attendees to keep them forever! In that case you might want to burn these fuses:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL
If you want those tickets to be non-transferrable (soulbound to the address that attended), then burn these fuses:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_TRANSFER
By default, newly registered names will use the Public Resolver, which just allows the current manager/controller of the name to update any records.
However, in some cases perhaps you want to make sure that a name resolves to specific records and never changes. You can accomplish this with the CANNOT_SET_RESOLVER fuse.
Say you own mycoolcontract.eth representing a smart contract. You can use ENS subnames to refer to specific versions of that contract, like 1.mycoolcontract.eth. And perhaps you want those versioned subnames to always point to:
The ETH address of that immutable contract
The ABI for that contract
The contenthash for some versioned documentation page
etc.
One way to do this is just to make sure the name is Locked, all the records are set correctly, and then transfer the owner to some burn address so it can never be updated again.
But of course this isn't ideal, because maybe there are some records that you do want to update in the future. Or maybe you still want to keep ownership of that subname for other reasons.
Instead of essentially burning the name, you could create a custom resolver that locks in certain records forever. Then:
Set the resolver of that name to your custom contract
Set the records however you want and lock them into the resolver
Burn these fuses on the name:
PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_SET_RESOLVER
Now you can still keep ownership and even some limited management power over the name, while still guaranteeing that the ETH address, ABI, and whatever other records are completely immutable, as long as the expiry is set appropriately.
The Name Wrapper takes control of your ENS name, and issues you an ERC-1155 NFT in return.
For .eth names, fuses can be used to apply perks or restrictions on subnames.
DNS names can be wrapped, but currently cannot use fuses. (See the DNS Domains and Fuses section for additional nuance.)
All .eth second-level names (like name.eth) are automatically placed into the Emancipated state when wrapped.
Emancipated means that the parent no longer has control over the child name. It can no longer burn any fuses or replace the subname, up until the expiry.
A name is Emancipated when the parent burns the “Parent Cannot Control” (PCC) fuse. The parent must first be in the Locked state to be able to do this.
Locked means that the name cannot be unwrapped. This provides assurance to subnames that the parent owner cannot unwrap and then, for example, start replacing subnames directly against the registry.
An Emancipated name is Locked when the “Cannot Unwrap” (CU) fuse is burned.
Think of the special PCC / CU fuses recursively:
To burn owner-controlled or subname fuses, CU must be burned.
To burn CU, PCC must be burned.
Only the parent can burn PCC on the child name, and only if CU is first burned on the parent
To burn CU on the parent, PCC must be burned on the parent
Only the grandparent can burn PCC on the parent name, and only if CU is first burned on the grandparent
And so on…
Follow that chain up until you hit a .eth second-level name like name.eth, since .eth second-level names will have PCC automatically burned when wrapping. The parent eth node is already in the Locked state.
A parent name can burn all the fuses it needs to on a child name in one transaction. This can be done when the subname is created, or on an existing subname that has not yet been Emancipated.
Finally, in order to use fuses, an expiry must also be set on the name. When the expiry is reached, all fuses are reset on the name. If the name is Emancipated or Locked, then in addition, when the expiry is reached, you lose ownership of the name.
The actual contracts as well as technical documentation are here:
The core contracts of the ENS protocol . Contribute to ensdomains/ens-contracts development by creating an account on GitHub.
We also have a section on the Name Wrapper in the support docs with much of this same information: Developer Basics - Name Wrapper Overview
As well as a how-to section for the new ENS Manager App: Support Docs - Name Wrapper How-Tos
There is also a useful third-party integration guide here: NameWrapper third party support guide
Also see all of our other technical docs at https://docs.ens.domains.
Introduction
The ENS Name Wrapper
Example - Step By Step
Example - Parent Locks Subname All-In-One
Example - Multiple Subnames in Various States
Name Wrapper Fuses
Name Wrapper Expiry
Approved Operators
DNS Domains and Fuses
Use-Cases
1.) I want to give subnames out to all of my DAO members / NFT holders!
2.) I want to sell / rent out subnames!
3.) Other cool things you can do
Issue subdomains as tickets to an event
Lock the resolved records for a name
Recap
Other Links
Before we dive into the Name Wrapper, let’s briefly recap some basic ENS concepts that will give some helpful context.
The Registry is the core contract at the heart of ENS resolution. All ENS lookups start by querying the registry. The registry is not just for .eth second-level names (like name.eth), but for all ENS names (subnames like sub.name.eth, and also DNS names like domain.xyz). The owner of the name in the registry is also referred to as the Controller or Manager of the name.
The .eth Registrar is specific to .eth second-level name registrations. This is essentially a subdomain registrar for the TLD (top-level domain) .eth. When you register a .eth name, the registrar issues you an ERC-721 NFT.
The owner of that NFT is also referred to as the Registrant or Owner of that name. It can be used to reclaim ownership over the name in the core registry as well (in other words, the Registrant can overwrite the Controller).
As you can see, without the Name Wrapper, only .eth second-level names are NFTs currently. Subnames and DNS domains do not have NFTs associated with them by default, unless a custom contract is created for that purpose.
Woah don’t worry, I’ll explain all of this soon enough.
The Name Wrapper wraps an ENS name into a new ERC-1155 NFT. Any ENS name can be wrapped, whether it’s a .eth name or DNS domain or even any subname!
There is a Use-Cases section later on in this article too.
You can take your name.eth…
And turn it into a wrapped ERC-1155 NFT!
Let’s take our sub1.name.eth subname from up above, and wrap it!
Now the subname is a wrapped ERC-1155 NFT too!
Those lines you see represent so-called “permission fuses” for your wrapped ENS name, which I’ll explain in a bit.
How does this affect the core registry though?
When you wrap a name, you are setting the Controller to the Name Wrapper contract. In return, the Name Wrapper issues an ERC-1155 NFT and transfers it to you.
For .eth second-level names, you transfer the Registrant / NFT (in the .eth registrar) to the Name Wrapper contract when you wrap. The Name Wrapper will automatically reclaim the Controller in the core registry too.
Before, there was no NFT at all (for subnames and DNS names at least):
After you wrap a name, technically the Controller in the registry is now the Name Wrapper contract. That means that you cannot interact directly with the ENS registry for that name, because you are not the Controller.
However, the Name Wrapper contract provides all the necessary methods so that you can still interact with the registry. You can transfer ownership, set the resolver/TTL, and even create subnames just as you would normally. On top of that, any subnames you create will be automatically wrapped by default as well!
We’re almost ready to see some visual examples! But first, let’s get some terminology out of the way…
In addition to all the functionality that the name gains from being a fully-fledged ERC-1155 NFT, the Name Wrapper provides a number of ENS-specific features as well.
It does this with a “fuse” system. Each “fuse” represents some kind of permission for the name. When you burn a fuse, you are usually revoking some kind of permission. In the ENS Manager UI, this is available in the “Permissions” section of the name.
For example, by default when you wrap a name, you can transfer that NFT around freely, just as you can with other NFTs. However, if the “Cannot Transfer” fuse is burned, then the NFT becomes non-transferrable. In the ENS Manager UI, you would do this by revoking the “Can send this name” permission.
As the name implies, once you burn a fuse, you cannot undo that action, until the expiry at least.
The expiry is how long the fuses are active for. The expiry on a name is set by the parent owner. For .eth second-level names, the expiry is set to the same expiry from the .eth registrar. When the expiry is reached, all fuses reset. In addition, if your name is Emancipated or Locked, then you lose ownership of the name when it expires. There is a section later that goes into greater detail about the expiry.
There are also special fuses that determine the relationship between “parent” and “child” names, or alter the state of the wrapped name. A name can be in one of these possible states:
The name has not even been registered/created yet, or it has expired.
The name exists and has not expired (in the case of .eth second-level names). The Name Wrapper contract does not have ownership over the name. You own the name in the registry and/or .eth registrar.
The Name Wrapper contract has ownership of the name (in the registry/registrar). You are issued an ERC-1155 NFT in return, which proves that you are the actual owner. You can unwrap the name at any time, which burns the ERC-1155 NFT, and returns ownership in the registry/registrar back to you. If your name is a subname like sub.name.eth, then the owner of name.eth can technically replace the subname and transfer it to a different owner. In addition, the parent owner can burn parent-controlled fuses on your name.
The owner of the parent name is no longer able to replace this name, or burn any additional fuses on it. All .eth second-level names (like name.eth) are automatically put into the Emancipated state when they are wrapped. The name can still be unwrapped and rewrapped by the owner.
The name can no longer be unwrapped. The owner can now burn owner-controlled fuses on the name. Fuses for subnames of this name can now be burned as well.
Let’s dive into an example to learn more about fuses.
Say you have name.eth and sub1.name.eth, both wrapped. You have already locked name.eth, but no fuses have been burned on the subname yet.
The subname is Wrapped but not yet Emancipated, so the parent still has full control. Check out the diagram below, see that anchor there in the top-left of the subname? This means that the parent owner can still control the subname. It can burn Parent-Controlled Fuses, or it can even completely replace the subname if it wanted to.
The owner of the subname can still unwrap/rewrap, transfer, set the resolver/TTL, and even create new subnames of its own. However the owner cannot burn any fuses on the subname or any sub-subnames yet.
I’ll keep the name.eth node stripped down so it’s hopefully not as confusing, since we’re focusing on the sub1.name.eth subname right now. See the diagram below:
While in this state, the parent owner can burn Parent-Controlled Fuses while continuing to have full control over the subname.
There are 3 total predefined Parent-Controlled Fuses, and then there are 13 undefined fuses that you can use however you wish. One way to think of these fuses are as "perks" for the owner of the subname.
For example, if you are using ENS subnames to issue tickets to an event, you could use these Parent-Controlled Fuses to unlock perks, like the ability to redeem some swag or get into a special event (maybe it even automatically integrates with one of those smart door locks when the person taps an access card!).
I’ll show one of the Parent-Controlled Fuses being burned in the diagram below. In this case, it’s the CAN_EXTEND_EXPIRY fuse, which allows the subname owner to extend their own expiry (there is a section later going over all the fuses and what they do).
To Emancipate a name, burn the special "Parent Cannot Control" fuse.
After burning, no more fuses will be able to be burned by the parent.
The owner of the parent name will also no longer be able to replace the subname.
Remember that anchor in the top-left of the diagram? Burning the PCC fuse will blow that away! Without that anchor, the child drifts away from the parent and severs all the remaining fuses. So the parent owner will no longer have any control over this child!
In addition, see that other fuse going down below PCC? It will also blow away a section of wall, giving the subname owner access to its own “matchbox”! The subname owner will now be able to burn fuses on their own.
I’ve circled these places in green in the diagram below:
The subname sub1.name.eth is now Emancipated.
The parent can no longer burn any fuses, or replace the subname (up until the expiry).
The subname is not yet Locked though, so the owner of the subname can still unwrap the name if they want! If the name is unwrapped and then rewrapped, everything will still be in the same Emancipated state with the same fuses burned.
Because the name is not yet Locked, the owner of the subname cannot burn any other fuses (besides “Cannot Unwrap”). The owner cannot burn any fuses on any of its own subnames yet either.
See that section below that is now green? Now that the parent has burned PCC, the owner has access to its own “matchbox”, and can start playing with fire!
You might also notice that the fuse for “Cannot Unwrap” is accessible from within this same section…
To Lock a name, burn the special "Cannot Unwrap" fuse.
This can only be burned if PCC (Parent Cannot Control) has first been burned by the parent.
In other words, it can only be burned if the name is already Emancipated.
See that bundle of dynamite with “CU” next to it? That’s gonna blow when you burn the Cannot Unwrap fuse. If you follow the other fuses attached to it, you’ll see that it’ll also blow up a few other things, which I’ll go over next.
I’ve circled in green the areas that will be affected in the diagram below:
The subname sub1.name.eth is now Locked. This means that the name can no longer be unwrapped.
Look at the diagram below, Simba. Everything the green light touches is our kingdom.
Now that the name is Locked, the owner can burn other Owner-Controlled Fuses. The owner can also burn fuses for any subnames of its own.
There are 7 total predefined Owner-Controlled Fuses, and then there are 9 undefined fuses that you can use however you wish.
For example, you can burn "Cannot Transfer" and "Cannot Set Resolver".
Now the name cannot be transferred/sold, and the resolver contract can no longer be overwritten, up until the expiry.
If you burn the special "Cannot Burn Fuses" fuse, then no more fuses can be burned on the name.
The parent owner may burn this fuse on a subname to ensure that some permissions remain "locked open".
The owner of the name could also choose to burn it. For example, if the name uses a subdomain registrar, the owner could leave “Cannot Create Subname” unburnt, and then burn the "Cannot Burn Fuses" fuse to guarantee that new subnames can always be registered.
See the remaining bundle of dynamite with “CBF” next to it? Once that blows, all of the other Owner-Controlled Fuses will be rendered inaccessible. I’ve circled it in green below:
The "Cannot Burn Fuses" fuse has now been burned.
The fuses for the name are now completely frozen until its expiry. Any previously burned fuses will remain in that burned state, but no other fuses can be burned on this name now.
However, the owner can still burn fuses of any subnames, assuming that it has not yet emancipated them.
Okay, so I simplified a few things earlier to make it easier to follow.
Usually there won't be so many steps. The parent can burn multiple fuses at once, and take the name all the way to the Locked state in one fell swoop.
For example, say you want to emancipate and lock a subdomain, and burn a Parent-Controlled fuse, and burn some Owner-Controller fuses too?
To do that, you will burn "Parent Cannot Control" and "Cannot Unwrap", and all the other fuses you want, all in one transaction.
Remember, once PCC is burned, no further fuses can be burned by the parent.
Also, if you want to burn any Owner-Controlled Fuses, you must also burn CU (Cannot Unwrap). You may have noticed that purple “CU Lock” on the diagram. That indicates that in order to burn any of those fuses, you must also burn CU.
In addition, the CU fuse can only be burned if PCC is already burned, or burned at the same time. Similarly there is that purple “PCC Lock” on the diagram. That indicates that in order to burn CU, you must also burn PCC.
I know this is a lot to take in, but as an example, I've highlighted some fuses in green below:
After burning those fuses, the subname is now Locked.
In addition, the “Can Extend Expiry” fuse was burned, and the "Cannot Transfer" fuse was also burned.
The owner of the subname still has the ability to burn other fuses and create new subnames of its own in this case. The parent could have decided to restrict things even further by burning other fuses, like "Cannot Create Subname" or "Cannot Burn Fuses".
But now that the parent has burned PCC, it has relinquished control over this subname, and it can no longer burn anything else.
So we just saw how you can take an existing wrapped subname, and Emancipate / Lock it, with fuses burned, all in one step.
Just so you know, the same can also be done when you create an entirely new subname!
If your name is wrapped, and you create a new subname under it, that subname will also be wrapped by default. And at the same time, in the same transaction, you can also pass in your desired list of fuses to burn (and the expiry).
So you do not have to create a subname and then separately burn fuses. You can do everything in one transaction.
Now let’s zoom out a bit, and I’ll even fill in the name.eth wrapper this time.
Remember that .eth second-level names are automatically put into the Emancipated state when they are wrapped. They are not automatically Locked though. When you register/wrap a .eth second-level name, you can pass in any owner-controlled fuses you want to burn to start with, so you can go directly to the Locked state if you wish.
As you can see, each subname does not have to be in the same state. Some can be Locked, some Emancipated, and some merely Wrapped. It’s entirely up to the owner of the parent name and how much power or freedom they want to give to child names.
This will depend on the use-case. Using subnames for a temporary ticketing system is going to have different constraints than a permanent subdomain registrar, for example.
As previously mentioned, a "fuse" is a permission or perk that can be granted/revoked on a name. As the name implies, once the fuse is "burned", it cannot be unburned. Fuses will only reset when the expiry is reached.
There are parent-controlled and owner-controlled fuses:
PARENT_CANNOT_CONTROL:
Allows a parent owner to Emancipate a child name. After this is burned, the parent will no longer be able to burn any further fuses, and will no longer be able to replace/delete the child name. This fuse must be burned in order for any owner-controlled fuses to be burned on the name.
IS_DOT_ETH:
This fuse cannot be burned by users of the Name Wrapper, it is only set internally when a .eth 2LD is wrapped.
CAN_EXTEND_EXPIRY:
The owner of the child name will be able to extend their own expiry. Normally, only the parent owner can extend the expiry of a child name.
Custom Fuses:
There are 13 other parent-controlled fuses that are not reserved, and can be used in any custom way you want!
CANNOT_UNWRAP:
The name will now be Locked, and can no longer be unwrapped. This fuse must be burned in order for any other owner-controlled fuses to be burned on the name.
CANNOT_BURN_FUSES:
No further fuses can be burned on the name.
CANNOT_TRANSFER:
The name (wrapped NFT) can no longer be transferred.
CANNOT_SET_RESOLVER:
The resolver contract for the name can no longer be updated.
CANNOT_SET_TTL:
The TTL for the name can no longer be updated.
CANNOT_CREATE_SUBDOMAIN:
New subdomains can no longer be created.
CANNOT_APPROVE:
The approved subname renewal manager for the name can no longer be updated. See the Approved Operators section below for more information.
Custom Fuses:
There are 9 other owner-controlled fuses that are not reserved, and can be used in any custom way you want!
For unwrapped names, only .eth second-level names (like name.eth) have the concept of an expiration date (set in the .eth Registrar). The Name Wrapper has the concept of an expiry as well, which can apply to .eth subnames too. This expiry determines how long any burned fuses are active for, and may also determine whether the name itself has expired. In order to use fuses, a name must also have an expiry set.
When the Name Wrapper is used:
The expiry for .eth second-level names will automatically be set to the expiry from the .eth Registrar (plus the grace period).
It’s possible the wrapped expiry can get “out of sync” if you renew via the old registrar controller contract. In this case, you can re-sync the wrapped expiry by calling the renew method on the wrapper contract.
Other .eth subnames can have their own separate expiry, and at maximum it can be set to the expiry of the parent node.
The expiry does not apply to any DNS names, since they currently cannot use fuses.
You may choose to not burn any fuses on a subname and leave it in the Wrapped state if you wish. In that case, the expiry has no practical effect and can just be left as 0. However if you wish to burn any fuses (or emancipate/lock a subname, which requires fuses to be burned), then you must also set an expiry.
The expiry applies to all fuses that may have been previously burned, both parent-controlled and owner-controlled. When the expiry has been reached, all fuses will be reset.
By default, the expiry for a name can only be set by the parent, and can only be increased, not decreased. The maximum value for the expiry of a name is the expiry of its parent name.
For example, say a name expires in 5 years. The owner of the name can then set the expiry of its subnames to a maximum of 5 years as well. But the parent could also choose to set the expiry to something less. Let’s say the parent sets the expiry of one of its subnames to 2 years. Then in turn, the owner of the subname can set the expiry of its own subnames up to a maximum of 2 years, but it could also set it to something less, like 1 year.
The parent can set a different expiry for different subnames too, just as it can burn different fuses for different subnames.
When a wrapped .eth second-level name (like name.eth) is renewed, that new expiry is automatically set in the Name Wrapper as well as in the .eth Registrar. However, the expiry for any other .eth names (like sub.name.eth) will not be automatically extended when the parent expiry is extended.
The parent can extend the expiry for an existing subname at any time, even if the subname has been emancipated.
The parent can also choose to approve a separate contract to allow the expiry for subnames to be extended by the subname owner or other accounts. That is basically how .eth second-level names work: Since the eth node is locked in the registrar contract and has the Name Wrapper (which exposes a renew method) approved as a controller, .eth second-level names can be directly renewed by their owners. The parent can further lock this approved contract in by burning the CANNOT_APPROVE fuse.
There is also a special parent-controlled fuse called CAN_EXTEND_EXPIRY. If the parent burns this fuse on a subname, then the owner of that subname (or any approved controller) can also extend the expiry.
So, if you are running a subname registrar and you want to enable “unruggable renewals”, you can use one of the above options (or both).
For .eth second-level names, the end of the name’s grace period (from the .eth Registrar) is used for the expiry inside of the Name Wrapper. So if the name’s expiration date in the Registrar is January 1st, then the expiry in the Name Wrapper will reflect that date plus the grace period (currently 90 days, so approximately April 1st, depending on the year).
When the name’s expiration date (from the .eth Registrar) has been reached, and the name is now in the grace period, all Name Wrapper operations on the name will be restricted. The owner will not yet lose ownership of the name, but they will also not be able to unwrap or update the name until it has been renewed.
When a name is merely Wrapped but not Emancipated or Locked, parent-controlled fuses can still be burned. This means that the parent can burn a custom fuse for a limited amount of time. When the expiry is reached, all fuses will be reset, but the name will otherwise be unaffected. Also, as a reminder, the parent must first be in the Locked state before it can burn fuses on any subnames.
When a name is Emancipated or Locked, the expiry has an important additional effect. In this scenario, when the expiry has been reached, the name itself will expire, and the owner loses ownership of the name. The Name Wrapper contract will return the null address (0x000…) as the owner for any expired name. This means:
The name will not be able to be transferred.
The NFT for the name may disappear from websites/dapps/wallets as the owner is now the null address.
The resolver/TTL will not be able to be updated.
New subnames will not be able to be created.
Existing subnames will not be able to be altered.
Depending on the resolver contract, the name may continue to resolve to any records that were set before the name expired.
Depending on the resolver contract, records for the name may no longer be updatable.
When a subname expires, the parent regains the power to completely replace the subname, with a new expiry, a new set of fuses, and even a new owner. That “new set of fuses” is up to the parent. They could choose to completely reset all fuses, or they could choose to use the same set of fuses that were previously set before the subname expired. So if the parent wanted to simply “reactivate” the subname in the same state it was before, it could recreate the subname with the same owner and same set of fuses, but with a new expiry.
Your wrapped name is an ERC-1155 NFT that supports the setApprovalForAll method. When you approve an address using this method, it will have full control over all wrapped ENS names that you own.
This method is typically used by NFT marketplace contracts.
The Name Wrapper also supports the ERC-721 approve method. This method is used to approve a single “Subname Renewal Manager” for a specific name.
The “Renewal Manager” does not have full control over your wrapped name, it can only set / extend the expiry on subnames.
Further, if you burn the CANNOT_APPROVE fuse on your name, then the approved renewal manager can no longer be changed. You can use this to “lock in” that contract, so that you can guarantee to all subname owners that renewals/extensions can always be done.
This approved renewal manager will be reset if the wrapped NFT is burned or re-minted, which happens if you unwrap the name, or if an expired name gets re-registered. It will also be reset if the wrapped NFT is transferred, unless the CANNOT_APPROVE fuse is burned.
You can use these operator approval methods to setup a separate contract that can take certain actions on your behalf. One example is setting up a “subname registrar” to allow users to register/renew subnames.
That subname registrar contract would act on your behalf and allow users to register subnames. To allow this, you would call setApprovalForAll to give that contract full control over your name (and thus the ability to create subnames).
Then, to enable “unruggable renewals”, you could call approve on that same contract (or a separate one specific to renewals if you wish) and burn CANNOT_APPROVE to lock in subname renewals for that contract.
If you need to later on, you would still be able to revoke with setApprovalForAll. So the contract would lose full control over your name (and the ability to create new subnames), but it would still be able to perpetually renew/extend existing subnames.
And you can do all of this without needing to send your wrapped NFT to that contract.
As previously explained, in order to burn fuses on a name, the parent name must be Locked. The reason is, if the parent name was not locked, then the owner of the parent name could simply get around the constraints of the Name Wrapper by unwrapping the name, and replacing/revoking subnames against the core ENS Registry.
This is why I’ve said in this guide that currently, only .eth names support fuses, because only the eth node is on-chain native and completely locked beyond anyone’s control.
This is not to say that DNS names “can’t ever” use fuses. Technically speaking, the owner of a DNS TLD has the ability to burn fuses on that TLD in the Name Wrapper, and set it to the “Locked” state. And then from there, all subnames under that DNS TLD will be able to use fuses. The DNS TLD owner would need to:
Request the Controller of that TLD from the ENS DAO
Wrap the TLD node in the Name Wrapper
Burn the PARENT_CANNOT_CONTROL and CANNOT_UNWRAP fuses on the wrapped TLD to lock it
However, this still does not have all the immutable guarantees that .eth names do. This is because for DNS names, the “source of truth” always lies not in the Ethereum network, but in the DNS network, and the DNS root zone governed by ICANN stakeholders.
So even if the DNS TLD owner “Locks” that TLD in the ENS Name Wrapper, if that TLD were to ever change ownership on the DNS side, then (per the ENS DAO constitution) the new owner would be able to override control of that TLD on the ENS side, unwrap it, and replace/revoke all 2LDs.
This is just something to keep in mind for wrapped DNS domains.
However, even if wrapped DNS domains do not support fuses, you can still use them as ERC-1155 NFTs. They will still have their own NFT metadata and show up in your wallet, with whatever avatar you have set, etc. They just won’t have all the extra functionality that comes with the fuse/permission system.
Say you own the wrapped name mycoolnft.eth, representing a popular NFT project you created. You want to distribute subnames like 6529.mycoolnft.eth to all holders.
One option is to just bulk create the subnames and drop the wrapped NFTs into their wallets. This might be good at least as an initial drop, because then the holders don’t need to interact with any contract or spend any gas, you’re doing that for them!
To create the subnames, you’d use the setSubnodeOwner or setSubnodeRecord methods.
You must also decide:
Do you want to be able to revoke subnames? Or do you want them to be completely outside your control?
One thing to consider is whether you want the current holder of your NFT to always be able to claim/reclaim the corresponding ENS subname. If so, then you will not want to Emancipate those subnames (in other words, do not burn PARENT_CANNOT_CONTROL). If the subname is Emancipated, then the NFT holder could sell/transfer the NFT but keep the subname (up until the expiry).
To make it easy for anyone to claim/reclaim a subname after your initial drop, you can set up a contract for this.
The claim method of your contract could:
Call ownerOf or balanceOf on your NFT contract to get or verify the current owner of the NFT
Call ownerOf or balanceOf on the ENS Name Wrapper contract to get or verify the current owner of the wrapped subname
If both owner addresses are the same, just return, nothing to do
Call setSubnodeOwner or setSubnodeRecord on the ENS Name Wrapper:
owner: The current owner of the NFT
fuses: What fuses you want to burn (if any) on that subname. If you burn any fuses, you must also set an expiry.
expiry: When the subname will expire.
Then, to give that contract access to create subnames on your behalf, you would call setApprovalForAll on the Name Wrapper to approve your contract as an operator.
Now, even if the NFT gets sold / transferred, the new owner will be able to claim their mycoolnft.eth subname at any time.
In addition, if you expand your NFT collection in the future and there are new owners, then those new owners would be able to claim their subnames as well.
If you are creating a new NFT contract, you could even bake this functionality directly into the NFT contract too, instead of needing a separate contract! By doing this, you wouldn’t need a separate claim method either, your NFT contract would just automatically transfer the wrapped ENS subname whenever the NFT itself gets transferred!
If you decide to not Emancipate the subnames that you issue, you will still be able to burn any Parent-Controlled Fuses. There are 13 unreserved parent-controlled fuses that you can use however you wish!
For example, perhaps you want to grant on-chain “perks” or “roles” to certain holders. You would call setChildFuses on the Name Wrapper and pass in the fuses you want to burn, and the expiry.
This means that those “perks” or “roles” can also be time-boxed if you want. Maybe a perk expires in 1 week or something, up to you.
There is also the reserved CAN_EXTEND_EXPIRY parent-controlled fuse. If you burn this, then the subname owner will be able to extend their own expiry whenever they want.
Say you own the wrapped name verypopularname.eth. Obviously you can just manually create wrapped subnames like my.verypopularname.eth and then sell them on an NFT marketplace. But that sure doesn’t scale well.
To accomplish this, you will want to create a subname registrar. This is a contract that will handle all the registration / renewal for you, and then users will be able to interact with that contract in order to register their own subnames.
In fact, this is exactly how .eth 2LDs are registered. The owner of the eth TLD (the NFT contract) delegates registration / renewal to the ETHRegistrarController contract. It is acting as a subname registrar for the name eth.
Your contract would expose a register method that anyone can call. Under the hood it will use the setSubnodeOwner or setSubnodeRecord methods to create subnames, passing in the fuses and expiry you want to set.
First, note that if you want to burn any fuses on subnames, then your name must be Locked (meaning CANNOT_UNWRAP is burned).
Assuming that you want your subnames to be “unruggable”, such that you cannot replace / revoke them, then you will want to burn PARENT_CANNOT_CONTROL on the subnames. This will place them in the Emancipated state upon registration.
If you want to sell “forever” subnames, where users register once and can then keep them for as long as they wish, then you can consider burning the CAN_EXTEND_EXPIRY fuse. This will allow the subname owner to extend their own expiry whenever they want. The max expiry is the expiry of the parent name, but the .eth Registrar allows anyone to renew/extend a .eth 2LD as well.
If you just want to rent subnames, then do not burn CAN_EXTEND_EXPIRY. Instead, you could include a renew method on your contract that users can call for another fee.
If you want to enable “unruggable renewals” for your registrar, to guarantee that users will always be able to renew, then you can call approve on the Name Wrapper and approve your registrar contract as the “subname renewal manager” for your name. Then, burn the CANNOT_APPROVE fuse on your name, to guarantee that you can never revoke that contract for subname renewals. See the Approved Operators section above for more info.
If you want to impose other restrictions on your registered subnames, then you can burn the CANNOT_UNWRAP fuse to Lock the subname, and also burn whatever other fuses you want.
For example, if you want to prevent owners of your subnames (like my.verypopularname.eth from creating their own subnames (like buy.my.verypopularname.eth), then you would burn CANNOT_UNWRAP and CANNOT_CREATE_SUBDOMAIN.
To recap on fuses…
Sell permanent names:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL
Sell permanent names, but prevent them from creating their own subnames:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_CREATE_SUBDOMAIN
Rent out names:
PARENT_CANNOT_CONTROL
Rent out names, but prevent them from transferring or reselling them:
PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_TRANSFER
And so on, it’s up to you. You can also burn whatever custom parent-controlled or owner-controlled fuses you want to.
Yes! It’s your registrar contract, so you can impose whatever rules and fees you want.
For example, the .eth Registrar imposes a 3-character minimum on all names, as well as a custom fee structure and a temporary premium auction upon expiration.
By default there is no character limit on subnames, but your contract could have its own rules and fee structure or whatever you want. For example, you can:
Allow or disallow specific addresses from registering / renewing
Only allow registration based on some custom criteria like holding a specific NFT
Custom length restrictions like only 3+ characters or < 100 characters
Only allow names with characters [a-z0-9] and nothing else
Use a custom fee structure based on:
The length of the name
The specific characters that are in the name, like emojis
A pre-curated list of “good” names like people’s first names
And whatever other rules you want.
If writing and deploying your own contract seems daunting, then don’t worry, the ENS Labs devs are working on some basic subname registrar contracts that anybody will be able to use.
I’m sure that the ENS community will create all kinds of other registrar contracts and tools you can use too!
Maybe you have mycoolevent.eth and you want to issue tickets like 1.ticket.2023.mycoolevent.eth.
If you want, you can choose to not Emancipate those subnames, but still burn some custom parent-controlled fuses. Those fuses might:
Indicate what “tier” their event ticket is
Maybe they can upgrade their ticket to a higher tier, which would burn some additional fuses
Allow them access to the express line or some VIP room
Maybe even automatically via some smart door
When you burn those fuses, perhaps you also set the expiry to the day after the event ends.
Or, maybe you want your attendees to be able to keep their subnames as a souvenir or proof-of-attendance!
If so, then instead of letting the names expire at the end of the event, you could extend the expiry and burn some additional fuses to allow the attendees to keep them forever! In that case you might want to burn these fuses:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL
If you want those tickets to be non-transferrable (soulbound to the address that attended), then burn these fuses:
CAN_EXTEND_EXPIRY | PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_TRANSFER
By default, newly registered names will use the Public Resolver, which just allows the current manager/controller of the name to update any records.
However, in some cases perhaps you want to make sure that a name resolves to specific records and never changes. You can accomplish this with the CANNOT_SET_RESOLVER fuse.
Say you own mycoolcontract.eth representing a smart contract. You can use ENS subnames to refer to specific versions of that contract, like 1.mycoolcontract.eth. And perhaps you want those versioned subnames to always point to:
The ETH address of that immutable contract
The ABI for that contract
The contenthash for some versioned documentation page
etc.
One way to do this is just to make sure the name is Locked, all the records are set correctly, and then transfer the owner to some burn address so it can never be updated again.
But of course this isn't ideal, because maybe there are some records that you do want to update in the future. Or maybe you still want to keep ownership of that subname for other reasons.
Instead of essentially burning the name, you could create a custom resolver that locks in certain records forever. Then:
Set the resolver of that name to your custom contract
Set the records however you want and lock them into the resolver
Burn these fuses on the name:
PARENT_CANNOT_CONTROL | CANNOT_UNWRAP | CANNOT_SET_RESOLVER
Now you can still keep ownership and even some limited management power over the name, while still guaranteeing that the ETH address, ABI, and whatever other records are completely immutable, as long as the expiry is set appropriately.
The Name Wrapper takes control of your ENS name, and issues you an ERC-1155 NFT in return.
For .eth names, fuses can be used to apply perks or restrictions on subnames.
DNS names can be wrapped, but currently cannot use fuses. (See the DNS Domains and Fuses section for additional nuance.)
All .eth second-level names (like name.eth) are automatically placed into the Emancipated state when wrapped.
Emancipated means that the parent no longer has control over the child name. It can no longer burn any fuses or replace the subname, up until the expiry.
A name is Emancipated when the parent burns the “Parent Cannot Control” (PCC) fuse. The parent must first be in the Locked state to be able to do this.
Locked means that the name cannot be unwrapped. This provides assurance to subnames that the parent owner cannot unwrap and then, for example, start replacing subnames directly against the registry.
An Emancipated name is Locked when the “Cannot Unwrap” (CU) fuse is burned.
Think of the special PCC / CU fuses recursively:
To burn owner-controlled or subname fuses, CU must be burned.
To burn CU, PCC must be burned.
Only the parent can burn PCC on the child name, and only if CU is first burned on the parent
To burn CU on the parent, PCC must be burned on the parent
Only the grandparent can burn PCC on the parent name, and only if CU is first burned on the grandparent
And so on…
Follow that chain up until you hit a .eth second-level name like name.eth, since .eth second-level names will have PCC automatically burned when wrapping. The parent eth node is already in the Locked state.
A parent name can burn all the fuses it needs to on a child name in one transaction. This can be done when the subname is created, or on an existing subname that has not yet been Emancipated.
Finally, in order to use fuses, an expiry must also be set on the name. When the expiry is reached, all fuses are reset on the name. If the name is Emancipated or Locked, then in addition, when the expiry is reached, you lose ownership of the name.
The actual contracts as well as technical documentation are here:
The core contracts of the ENS protocol . Contribute to ensdomains/ens-contracts development by creating an account on GitHub.
We also have a section on the Name Wrapper in the support docs with much of this same information: Developer Basics - Name Wrapper Overview
As well as a how-to section for the new ENS Manager App: Support Docs - Name Wrapper How-Tos
There is also a useful third-party integration guide here: NameWrapper third party support guide
Also see all of our other technical docs at https://docs.ens.domains.
ENS$ENS Token Allocation (Claiming Opens Nov 8)
Since we announced that ENS would be launching a DAO and $ENS token to govern key components of the ENS protocol, we’ve had a lot of inquiries as to how the DAO will be structured and what the token airdrop to community members will look like. Here’s an overview of what we have planned.ENS Token and DAO OverviewThe core components of ENS are decentralized and self-running (e.g., no one can take away another person’s .ETH name), but there are a few things that require some human discretion. Du...
ENS$ENS Now Available for Claiming
We’re pleased to announce the launch of $ENS, the governance token of ENS. Here’s what you need to know.ENS Token & Claim SiteThe claim site is now open: claim.ens.domains. The ENS token contract is token.ensdao.eth: 0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72 Double check the website URL and contract address to avoid scams. Users have until May 4th, 2022 to claim their tokens, after which any remaining tokens will be sent to the DAO treasury. The snapshot for all allocations - airdrop, contri...
ENSENS Web Update July 2023
Public roadmapWe now have a public roadmap that will keep track of completed, in progress and upcoming items. Check the ENS Labs roadmap.ENS roadmapLedger and Argent wallet supportExactly what it says on the tin!Ledger and Argent supportSmaller ImprovementsThe ENS Manager App will now display the grace period in the “more” tab:Grace periodUsers can now add their Telegram handle to their profile:Telegram handle in profileImprovements to the way the manager app handles canceled and replaced tra...
ENS$ENS Token Allocation (Claiming Opens Nov 8)
Since we announced that ENS would be launching a DAO and $ENS token to govern key components of the ENS protocol, we’ve had a lot of inquiries as to how the DAO will be structured and what the token airdrop to community members will look like. Here’s an overview of what we have planned.ENS Token and DAO OverviewThe core components of ENS are decentralized and self-running (e.g., no one can take away another person’s .ETH name), but there are a few things that require some human discretion. Du...
ENS$ENS Now Available for Claiming
We’re pleased to announce the launch of $ENS, the governance token of ENS. Here’s what you need to know.ENS Token & Claim SiteThe claim site is now open: claim.ens.domains. The ENS token contract is token.ensdao.eth: 0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72 Double check the website URL and contract address to avoid scams. Users have until May 4th, 2022 to claim their tokens, after which any remaining tokens will be sent to the DAO treasury. The snapshot for all allocations - airdrop, contri...
ENSENS Web Update July 2023
Public roadmapWe now have a public roadmap that will keep track of completed, in progress and upcoming items. Check the ENS Labs roadmap.ENS roadmapLedger and Argent wallet supportExactly what it says on the tin!Ledger and Argent supportSmaller ImprovementsThe ENS Manager App will now display the grace period in the “more” tab:Grace periodUsers can now add their Telegram handle to their profile:Telegram handle in profileImprovements to the way the manager app handles canceled and replaced tra...
Share Dialog
Share Dialog
Subscribe to ENS
Subscribe to ENS
>900 subscribers
>900 subscribers
No activity yet