Skip to main content

Name Wrapper: how does expiry work?

How expiry works on a wrapped name, how subname expiry is set, and what the parent name's expiry controls.

Important: don't lock names or burn Fuses. Locked names may have upgrade limits under ENSv2; migration is the recommended path. [More on ENSv2]

To burn any Fuses on a name, you must also set an expiry on it. This expiry determines how long any burned Fuses are active for, and may also determine whether the name itself has expired.

If the name is a .eth 2LD, then the expiry will automatically be set to the same expiry in the .eth Registrar. But for all other names, the parent can choose what expiry to set for a child name.

Max expiry for subnames

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. Its owner can set the expiry of any subname up to 5 years — say one is set to 2 years. The owner of that subname can then set the expiry of its own subnames up to 2 years, or less.

Nested names, each inheriting its max expiry from the parent

The parent can set a different expiry for different subnames too, just as it can burn different Fuses for different subnames.

Renewals

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.

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.

If you are running a subname registrar and you want subname owners to be able to renew for themselves, you can use either option, or both.

Special cases for .eth 2LDs

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 about 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.

Expiry implications

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 (end of grace period for .eth 2LDs) is reached, all Fuses will be reset, but the name will otherwise be unaffected.

When a name is Emancipated or Locked, the expiry has an important additional effect. In this scenario, when the expiry (end of grace period for .eth 2LDs) has been reached, the name itself will expire, and the owner loses ownership of the name.

Did this answer your question?