[mkdocs] docs: add namespace concept by zero4862 · Pull Request #844 · NemProject/nem

zero4862 · 2026-04-29T14:42:45Z

Adapts Namespace concept to NEM technology.

Differences with Symbol:

Role: Every mosaic lives under a namespace in NEM; optional alias for an account or mosaic in Symbol.
Mosaic lifecycle coupling: NEM mosaics become inactive when their parent namespace expires; Symbol mosaics persist independently and only the alias breaks.
Root name length: 16 chars on NEM vs 64 chars on Symbol. Subnamespace levels are 64 in both.
Duration: Fixed 525600 blocks (~1 year) on NEM vs 30 days to 5 years on Symbol.
Renewal window: Restricted to the last 43200 blocks before expiration on NEM; any time during the lease on Symbol.
Lease fee: Fixed on NEM vs duration-proportional XYM on Symbol.
Subnamespace cap: NEM has no explicit cap beyond the 3-level depth limit; Symbol caps at 256 subnamespaces per root.
Metadata: NEM does not not support metadata.

zero4862 · 2026-04-29T14:48:25Z

+
+Subnamespace
+:   A namespace that belongs to a parent namespace, either the root or another subnamespace.
+    Subnamespaces expire when the root namespace expires (see [Duration](#duration)).


In Symbol, we say:

A namespace that belongs to a parent root namespace. Subnamespaces expire when the parent namespace expires (see Duration)

What's marked in bold seems not accurate:

parent root -> parent: A subnamespace could be defined under another subnamespace, not necessarily the parent root.

parent namespace -> *root namespace: Since the parent subnamespace could be another subnamepace, we might want to say root namespace instead.

Agreed, can you add this to the Symbol PR too?

zero4862 · 2026-04-29T14:53:02Z

+
+Namespaces let an account group related mosaics under a meaningful prefix like `mycompany.tokens`.
+
+The account that registers a root namespace is called its _owner_.


To review in Symbol:

creator vs owner: We define the concept of "owner" here, while Symbol it uses "creator" and "owner". We should standardize this terminology (guides already use "owner"). "Creator" can be interpreted as the account that originally registered the namespace, whereas "owner" I think it reflects more accurately the account that has leased the namespace.

create namespace vs register namespace: Replaced "create namespace" with "register namespace" for the same reason.

Good thinking, yes. Can you create the PR for Symbol?

Yes, I can tackle this after completing all the textbook concepts, so I can evaluate the effort of updating Symbol all at once.

zero4862 · 2026-04-29T14:55:23Z

+    "Grace Period" -> Registered [label="\nRenewal" constraint=false];
+    "Grace Period" -> "Available Again" [label="Release"];


To review in Symbol:

Changed here "Deletion" for "Release". It matches better "Register". "Delete" matches better "Create".

Agreed. Can you add it to the Symbol PR?

zero4862 · 2026-04-29T14:56:40Z

+    Registering or renewing any kind of namespace requires announcing a transaction, which also has an associated fee.
+    However, this transaction fee is typically negligible compared to the lease fee.
+
+## Reserved Names


Added this new section (reserved names), we could add a similar one in Symbol.

Yes please! :D

segfaultxavi

Minor changes only.

segfaultxavi · 2026-04-30T10:41:37Z

+
+Namespaces let an account group related mosaics under a meaningful prefix like `mycompany.tokens`.
+
+The account that registers a root namespace is called its _owner_.


Good thinking, yes. Can you create the PR for Symbol?

segfaultxavi · 2026-04-30T10:47:04Z

+
+Subnamespace
+:   A namespace that belongs to a parent namespace, either the root or another subnamespace.
+    Subnamespaces expire when the root namespace expires (see [Duration](#duration)).


Agreed, can you add this to the Symbol PR too?

segfaultxavi · 2026-04-30T10:51:47Z

+
+`nem`, `user`, `account`, `org`, `com`, `biz`, `net`, `edu`, `mil`, `gov`, `info`.
+
+The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`.


There's a colon to separate namespaces here, but previously you said it was periods. Which one is it?

NEM namespaces are not used to name mosaics (like in Symbol), but to organize them. Mosaics have their own name. In nem:xem, nem is the namespace name and xem is the mosaic name, separated by a colon.

Subnamespaces are separated by a dot. Example: company.tokens:gold, where company is the namespace, tokens the subnamespace and gold the mosaic name.

Got it. I had not idea.
Then definitely you cannot use this example here without explaining what the colon means.
I understand you will probably explain it in the Mosaics page, but you need to provide at least a minimal explanation here and a link to where the colon is fully explained.

Something like:

Suggested change

The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`.

The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`

(note that the colon separates the namespace from the [currency name](./mosaics.md#fully-qualified-name)).

segfaultxavi · 2026-04-30T10:53:38Z

+    "Grace Period" -> Registered [label="\nRenewal" constraint=false];
+    "Grace Period" -> "Available Again" [label="Release"];


Agreed. Can you add it to the Symbol PR?

segfaultxavi · 2026-04-30T10:55:11Z

+    Registering or renewing any kind of namespace requires announcing a transaction, which also has an associated fee.
+    However, this transaction fee is typically negligible compared to the lease fee.
+
+## Reserved Names


Yes please! :D

segfaultxavi · 2026-04-30T12:15:06Z

+
+`nem`, `user`, `account`, `org`, `com`, `biz`, `net`, `edu`, `mil`, `gov`, `info`.
+
+The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`.


Got it. I had not idea.
Then definitely you cannot use this example here without explaining what the colon means.
I understand you will probably explain it in the Mosaics page, but you need to provide at least a minimal explanation here and a link to where the colon is fully explained.

Something like:

Suggested change

The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`.

The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`

(note that the colon separates the namespace from the [currency name](./mosaics.md#fully-qualified-name)).

zero4862 commented Apr 29, 2026

View reviewed changes

Comment thread mkdocs/pages/en/textbook/namespaces.md

zero4862 force-pushed the docs-namespace-concept branch from 4b2e104 to c33a002 Compare April 29, 2026 15:28

zero4862 marked this pull request as ready for review April 29, 2026 15:36

segfaultxavi self-requested a review April 30, 2026 10:04

segfaultxavi requested changes Apr 30, 2026

View reviewed changes

segfaultxavi reviewed Apr 30, 2026

View reviewed changes

Comment thread mkdocs/pages/en/textbook/namespaces.md Outdated

zero4862 added 2 commits April 30, 2026 12:39

[mkdocs] docs: add namespace concept

8714493

[mkdocs] docs: apply comments

765f950

zero4862 force-pushed the docs-namespace-concept branch from 12f78fe to 765f950 Compare April 30, 2026 11:40

zero4862 requested a review from segfaultxavi April 30, 2026 11:41

segfaultxavi requested changes Apr 30, 2026

View reviewed changes

[mkdocs] docs: apply comments

b0bb9bb

zero4862 requested a review from segfaultxavi April 30, 2026 16:28


		Namespaces let an account group related mosaics under a meaningful prefix like `mycompany.tokens`.

		The account that registers a root namespace is called its _owner_.

		"Grace Period" -> Registered [label="\nRenewal" constraint=false];
		"Grace Period" -> "Available Again" [label="Release"];


		`nem`, `user`, `account`, `org`, `com`, `biz`, `net`, `edu`, `mil`, `gov`, `info`.

		The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`.

	The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`.
	The `nem` namespace, in particular, is used by the system to host the native currency `nem:xem`
	(note that the colon separates the namespace from the [currency name](./mosaics.md#fully-qualified-name)).

Conversation

zero4862 commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zero4862 Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zero4862 Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zero4862 Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

segfaultxavi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zero4862 Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zero4862 commented Apr 29, 2026 •

edited

Loading

zero4862 Apr 29, 2026 •

edited

Loading

zero4862 Apr 29, 2026 •

edited

Loading

zero4862 Apr 29, 2026 •

edited

Loading

zero4862 Apr 30, 2026 •

edited

Loading