Namespace

Namespaces allow you to create an on-chain unique place for your business and your assets on the blockchain.

Name

Namespaces function similarly to internet domains. Creating a namespace starts with choosing a name that you will use to refer to an account or asset. The name must be unique in the network, and may have a maximum length of 64 characters, and the allowed characters are a, b, c, …, z, 0, 1, 2, …, 9, _ , -.

Subnamespaces

On the internet, a domain can have a sub-domain. In Catapult, namespaces can have subnamespaces to identify and organize assets.

../_images/namespace-setup.png

Organizing assets with namespaces

Namespaces can have up to 3 levels, a namespace and its two levels of subnamespace domains. A subnamespace does not have a duration by its own; it inherits the duration from its parent namespace.

You can create multiple subnamespaces with the same name in different namespaces. For example, you can create the subnamespaces foo.bar and foo2.bar, but the combination rootnamespace + subnamespace must remain unique.

Alias

AliasTransactions link namespaces to accounts and mosaics. An alias or its linked asset can be used interchangeably when sending a transaction. Using the alias makes long addresses rememberable and mosaics recognizable.

The creator of the namespace can link the namespace to an account or mosaic. This link will be editable, so the creator may unlink a previously set alias and link the namespace to a different asset.

The block receipts store the resolution of the alias for a given transaction.

Restrictions:

  • An account or mosaic can be linked to many namespaces but one namespace can only be linked to one account or mosaic.
  • An account can assign a namespace to any account that permits receiving AddressAliasTransaction.
  • An account can only link the alias to a mosaicId when the account is the creator of the mosaic.

Duration

At the time of the namespace registration, you must set the number of confirmed blocks you would like to rent the namespace for.

The maximum namespace duration is 365 days. By default, the network is configured to generate a block every 15 seconds. You can use the following formula to convert approximately days to blocks:

duration ≈ numberOfDays * 86400 / blockGenerationTargetTimeInSeconds
../_images/namespace-life-cycle.png

Namespace life-cycle

During the renting period, the namespace owner can create subnamespaces, alias accounts and mosaics. The owner can also extend the rental by sending a NamespaceRegistrationTransaction with the desired number of additional blocks.

The network can define a grace period that enables the namespace owner to renew the namespace past the expiration date before it becomes publicly available for registration.

When the grace period ends, the namespace is deleted. At this point, the namespace becomes available for its registration again.

Permissions by namespace status
Action Available Registration Period Grace Period
Register a new namespace ✔️
Renew the namespace ✔️ ✔️
Create subnamespaces ✔️
Link an alias to an address or mosaic ✔️
Send a transaction using an alias ✔️

Note

Only namespaces created during the nemesis block can have perpetual duration.

Rental fee

To create a namespace or to extend its duration, accounts have to pay a rental fee in addition to the transaction fee. Both fees will be deducted from the account’s balance after the announcement of a valid NamespaceRegistrationTransaction.

The default namespace rental fees are configurable per network, but the network dynamically adjusts the namespace rental fees over time.

Default values
Property Value
Registering a namespace 0.000001 cat.currency per block
Extending a namespace duration 0.000001 cat.currency per block
Creating a subnamespace 0.0001 cat.currency

To calculate the effective rental fee, the network multiplies the default value set in the configuration by the median network multiplier over last maxRollbackBlocks. In case there are zero multipliers, these are replaced by the defaultDynamicFeeMultiplier before the median calculation.

Guides

Transaction schemas

NamespaceRegistrationTransaction

Announce a NamespaceRegistrationTransaction to register and re-rent a namespace.

Version: 0x01

EntityType: 0x414E

Inlines:

Property Type Description
duration BlockDuration Number of confirmed blocks you would like to rent the namespace for. Duration is allowed to lie up to 365 days. Required for root namespaces.
parentId NamespaceId Parent namespace identifier. Required for subnamespaces.
id NamespaceId Namespace identifier.
registrationType NamespaceRegistrationType Namespace registration type.
nameSize uint8 Namespace name size in bytes.
name array(bytes, namespaceNameSize) Namespace name. Must be unique and may have a maximum length of 64 characters. Allowed characters are a, b, c, …, z, 0, 1, 2, …, 9, _ , -.

AddressAliasTransaction

Announce an AliasTransaction to attach a namespace to an account. A namespace can be assigned to any account present in the network.

Version: 0x01

EntityType: 0x424E

Inlines:

Property Type Description
namespaceId NamespaceId Identifier of the namespace that will become an alias.
address Address Aliased address.
aliasAction AliasAction Alias action.

MosaicAliasTransaction

Announce an AliasTransaction to attach a namespace to a mosaic. Setting an alias to a mosaic is only possible if the account announcing the transaction has created the namespace and mosaic involved.

Version: 0x01

EntityType: 0x434E

Inlines:

Property Type Description
namespaceId NamespaceId Identifier of the namespace that will become an alias.
mosaicId MosaicId Aliased mosaic identifier.
aliasAction AliasAction Alias action.

NamespaceRegistrationType

Enumeration: uint8

Id Description
0 Root namespace.
1 Child namespace.

AliasAction

Enumeration: uint8

Id Description
0x00 Link alias.
0x01 Unlink alias.

Continue: Metadata.