docs/_core/naming/manage.md

layout	permalink
core	/:collection/:path.html

Manage BNS Names

{:.no_toc}

This section teaches you how to manage your namespace, it contains the following sections:

• TOC {:toc}

Overview of management

Once you register a BNS name, you have the power to change its zone file hash, change its public key hash, destroy it (i.e. render it unresolvable), or renew it. The BNS consensus rules ensure that only you, as the owner of the name's private key, have the ability to carry out these operations.

Each of these operations are executed by sending a specially-formatted blockchain transaction to the blockchain, which BNS nodes read and process. The operations are listed below:

Transaction Type	Description
NAME_UPDATE	This changes the name's zone file hash. Any 20-byte string is allowed.
NAME_TRANSFER	This changes the name's public key hash. In addition, the current owner has the option to atomically clear the name's zone file hash (so the new owner won't "receive" the zone file).
NAME_REVOKE	This renders a name unresolvable. You should do this if your private key is compromised.
NAME_RENEWAL	This pushes back the name's expiration date (if it has one), and optionally both sets a new zone file hash and a new public key hash.

The reference BNS clients--- blockstack.js and the Blockstack Browser---can handle creating and sending all of these transactions for you.

NAME_UPDATE (live example)

A NAME_UPDATE transaction changes the name's zone file hash. You would send one of these transactions if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it.

A NAME_UPDATE transaction is generated from the name, a recent consensus hash, and the new zone file hash. The reference clients gather this information automatically. See the [transaction format]({{ site.baseurl }}/core/wire-format.html) document for details on how to construct this transaction.

NAME_TRANSFER (live example)

A NAME_TRANSFER transaction changes the name's public key hash. You would send one of these transactions if you wanted to:

• Change your private key
• Send the name to someone else

When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file.

The NAME_TRANSFER transaction is generated from the name, a recent consensus hash, and the new public key hash. The reference clients gather this information automatically. See the [transaction format]({{ site.baseurl }}/core/wire-format.html) document for details on how to construct this transaction.

NAME_REVOKE (live example)

A NAME_REVOKE transaction makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving.

You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. It is rarely used in practice.

The NAME_REVOKE operation is generated using only the name. See the [transaction format]({{ site.baseurl }}/core/wire-format.html) document for details on how to construct it.

NAME_RENEWAL (live example)

Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a NAME_RENEWAL every so often to keep your name.

A NAME_RENEWAL costs both transaction fees and registration fees. You will pay the registration cost of your name to the namespace's designated burn address when you renew it. You can find this fee using the /v1/prices/names/{name} endpoint.

When a name expires, it enters a month-long "grace period" (5000 blocks). It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name.

If your name is in a namespace where names do not expire, then you never need to use this transaction.

When you send a NAME_RENEWAL, you have the option of also setting a new public key hash and a new zone file hash. See the [transaction format]({{ site.baseurl }}/core/wire-format.html) document for details on how to construct this transaction.