Namespaces & Names

What Are Namespaces and Names?

When creating an account, token, or asset, a name can be assigned to it. For instance, upon creating an asset called “Self Portrait” in the “bobby.walsh” Signature Chain (SigChain), it can be referenced by the string “bobby.walsh:Self Portrait”. However, you can also assign more globally-accessible names to these objects using namespaces and namespaced names.

For our example, consider that we create a namespace “bobbywalshartgallery”, and within that gallery, we create a name “Self Portrait” that points to the same address on the blockchain belonging to the asset “bobby.walsh:Self Portrait”. This way, instead of giving out the SigChain username “bobby.walsh”, the business “bobbywalshartgallery” can be the public point of access, allowing people to reference the Self Portrait asset as “bobbywalshartgallery::Self Portrait”.

How are they used?

When names are referenced with a SigChain, a single colon (“:”) is used, while when names are referenced as part of a namespace, two colons (“::”) are used. So, the namespace is a globally-accessible container for names, and the names within it are pointers to objects on any SigChain. Please also note that creating a namespace in Nexus incurs a fee (currently 1,000 NXS), while creating names within that namespace only costs 1 NXS.

Creating Namespaces and Names in Nexus

The following guides describe creating namespaces and namespaced names on the Nexus blockchain. Examples of creating namespaces and associated names are given using both the interface provided by the Nexus Wallet and API.

To begin with, consider our example above, an asset “bobby.walsh:Self Portrait”. In the wallet, it looks like this:


1. If the ownership of this asset is going to be transferred by Bobby Walsh's Art Gallery business, Bobby doesn't necessarily want to give out his SigChain username. The first thing he must do is create a namespace for his business. The image below shows the User screen where namespaces can be created. Note the tab name on the left (Namespaces) and the button Create new namespace.


2. Upon clicking the Create new namespace button, the following dialog is displayed. This shows the name field filled in for the bobbywalshartgallery. Note that the name of a namespace can only contain lowercase letters, numbers, and periods.


3. Next, the wallet prompts for the SigChain PIN to confirm creation of the namespace.


4. Upon creation of the namespace, a success prompt is displayed. Click Dismiss to close the prompt.


5. Upon dismissing the success prompt, the list of namespaces is displayed. The image below shows the namespace that was just created.


Now that the namespace has been created, the name pointing to the asset in our example (“Self Portrait”) can be created.

1. First, click the pane displaying the “Self Portrait” asset in the Assets tab of the Users screen. It displays the following, from which the asset's address can be copied to the clipboard.


2. Next, click the Names tab of the Users screen. The following will be displayed, showing all names associated with this SigChain.


3. Click the Create new name button to begin the process of creating a namespaced name. A dialog is displayed to allow creation of a new name. When dialog appears, click the NAMESPACED button at the top of the dialog to specify creation of a name in a namespace.


4. This image shows the fields filled in for our namespaced name example, “bobbywalshartgallery::Self Portrait”. First, select a namespace owned by the currently logged-in SigChain. Then fill in the field for the name. Note that the namespace is provided in the NAME field, and to enter a name in the field, the cursor must be placed after the namespace placeholder. Finally, provide the asset address retrieved above to point the new name to the specific asset in question. A 1 NXS fee will be charged for creation of the namespaced name.


5. Upon clicking the CREATE NAME button, a confirmation prompt requiring entry of the SigChain's PIN appears. Entry of the PIN results in the namespaced name being created, and the following success prompt being displayed.


Upon dismissing the success prompt, the Names tab of the Users screen is displayed again, and the new namespaced name is visible in the list of names. Note that to the right of the namespaced name is an indicator, NAMESPACED, to highlight this as a namespaced name, distinct from a local name.

Clicking on the new namespaced name results in an information screen being displayed showing the details on the namespaced name.


From the Name Details screen, the namespaced name can be edited to point to a different account, token, or asset by clicking the pencil icon at the top-right of the screen. The following screen displays, with the current destination address being highlighted. This address can be changed, and then click the UPDATE NAME button. Note that a fee of 1 NXS is charged for changing the destination address of a namespaced name.


Also, from the Name Details screen shown previously, the Transfer ownership button can be pressed to begin the process of transferring the namespaced name to a different SigChain. The destination SigChain's username or address can be used to transfer ownership of the namespaced name to it.


Now, as proof that the namespaced name points to the desired asset, from the wallet console, the following command can be entered, and information pertaining to the asset is returned.


Consider that the Nexus API can be used to programmatically create namespaces and namespaced names. The following screens will demonstrate this by using the Nexus wallet console. This shows how the API commands could be issued from a DApp to achieve the same ends.

1. First, log into the SigChain that will contain the namespace and namespaced name. Then, the following command can be issued to create the namespace. Of course, the pin parameter must be the PIN of the SigChain.


2. The following API command is then issued to create the namespaced name. The register_address parameter contains the Address hash that was retrieved from the target asset's property screen. (See step 1 in the preceding section showing how to use the wallet to create namespace and namespaced names.)


3. Now, the name can be programmatically retrieved using the following command.


4. More importantly, the underlying asset itself can be programmatically retrieved by issuing the following API command.


For more information on available API methods, refer to the GitHub API documentation. Please use our Forum, Slack, Telegram or Discord support channels at the bottom of the page for further inquiries and support.