Skip to content

Registering a Subnamespace⚓︎

INTERMEDIATE

Subnamespaces (also called "child" namespaces) extend the hierarchical structure of Namespaces.

This tutorial shows how to register a subnamespace under an existing root namespace.

To learn how to register a root namespace instead, read the Registering a Root Namespace guide.

Prerequisites⚓︎

Before you start, make sure to:

Additionally, review the Transfer XEM tutorial to understand how transactions are announced and confirmed.

Full Code⚓︎

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
import json
import os
import time
import urllib.request

from symbolchain.CryptoTypes import PrivateKey
from symbolchain.facade.NemFacade import NemFacade
from symbolchain.nc import Amount
from symbolchain.nem.FeeCalculator import (
    calculate_namespace_rental_fee,
    calculate_transaction_fee
)
from symbolchain.nem.Network import NetworkTimestamp

NODE_URL = os.getenv('NODE_URL', 'http://libertalia.nemtest.net:7890')
print(f'Using node {NODE_URL}')

SIGNER_PRIVATE_KEY = os.getenv(
    'SIGNER_PRIVATE_KEY',
    '0000000000000000000000000000000000000000000000000000000000000000')
signer_key_pair = NemFacade.KeyPair(PrivateKey(SIGNER_PRIVATE_KEY))

facade = NemFacade('testnet')
signer_address = facade.network.public_key_to_address(
    signer_key_pair.public_key)
print(f'Signer address: {signer_address}')

try:
    # Fetch current network time
    time_path = '/time-sync/network-time'
    print(f'Fetching current network time from {time_path}')
    with urllib.request.urlopen(f'{NODE_URL}{time_path}') as response:
        response_json = json.loads(response.read().decode())
        network_time = response_json['receiveTimeStamp'] // 1000
        print(f'  Network time: {network_time} s since the nemesis block')

    # Derived fields from network time
    timestamp = NetworkTimestamp(network_time)
    deadline = timestamp.add_hours(2)

    # Choose the subnamespace name
    root_namespace_name = os.getenv('ROOT_NAMESPACE', 'ns_root')
    child_namespace_name = os.getenv(
        'SUBNAMESPACE', f'sub_{int(time.time())}')
    full_namespace_name = (
        f'{root_namespace_name}.{child_namespace_name}')
    print(f'Creating subnamespace: {full_namespace_name}')

    # Build the transaction
    rental_fee = calculate_namespace_rental_fee(False)
    print(f'  Namespace lease fee: {rental_fee / 1_000_000} XEM')

    transaction = facade.transaction_factory.create({
        'type': 'namespace_registration_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'timestamp': timestamp.timestamp,
        'deadline': deadline.timestamp,
        'rental_fee_sink': 'TAMESPACEWH4MKFMBCVFERDPOOP4FK7MTDJEYP35',
        'rental_fee': rental_fee,
        'parent_name': root_namespace_name,
        'name': child_namespace_name
    })

    fee = calculate_transaction_fee(transaction)
    transaction.fee = Amount(fee)
    print(f'  Transaction fee: {fee / 1_000_000} XEM')

    # Sign transaction and generate final payload
    signature = facade.sign_transaction(signer_key_pair, transaction)
    json_payload = facade.transaction_factory.attach_signature(
        transaction, signature)
    print('Built transaction:')
    print(json.dumps(transaction.to_json(), indent=2))

    # Announce the transaction
    announce_path = '/transaction/announce'
    print(f'Announcing namespace registration to {announce_path}')
    announce_request = urllib.request.Request(
        f'{NODE_URL}{announce_path}',
        data=json_payload.encode(),
        headers={'Content-Type': 'application/json'},
        method='POST'
    )
    with urllib.request.urlopen(announce_request) as response:
        announce_result = json.loads(response.read().decode())
    print(f'  Result: {announce_result['message']}')

    # Wait for confirmation
    if 'SUCCESS' == announce_result['message']:
        status_path = (
            f'/transaction/get?hash={
                facade.hash_transaction(transaction)}')
        print(f'Waiting for confirmation from {status_path}')
        is_confirmed = False
        for attempt in range(120):
            try:
                with urllib.request.urlopen(
                    f'{NODE_URL}{status_path}'
                ) as response:
                    confirmed = json.loads(response.read().decode())
                    height = confirmed['meta']['height']
                    print(f'Transaction confirmed in block {height}')
                    is_confirmed = True
                    break
            except urllib.error.HTTPError:
                print('  Transaction status: pending')
            time.sleep(1)
        if not is_confirmed:
            print('Confirmation took too long.')
    else:
        print(f'Transaction rejected: {announce_result['message']}')
    # Retrieve the namespace
    namespace_path = f'/namespace?namespace={full_namespace_name}'
    print(f'Fetching namespace information from {namespace_path}')
    with urllib.request.urlopen(
        f'{NODE_URL}{namespace_path}'
    ) as response:
        namespace_info = json.loads(response.read().decode())
        print('Namespace information:')
        print(f'  Name: {namespace_info["fqn"]}')
        print(f'  Owner: {namespace_info["owner"]}')
        print(f'  Registration height: {namespace_info["height"]}')

except urllib.error.URLError as e:
    print(e.reason)

Download source

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
import { PrivateKey } from 'symbol-sdk';
import {
    NemFacade,
    NetworkTimestamp,
    calculateNamespaceRentalFee,
    calculateTransactionFee,
    models
} from 'symbol-sdk/nem';

const NODE_URL = process.env.NODE_URL ||
    'http://libertalia.nemtest.net:7890';
console.log('Using node', NODE_URL);

const SIGNER_PRIVATE_KEY = process.env.SIGNER_PRIVATE_KEY ||
    '0000000000000000000000000000000000000000000000000000000000000000';
const signerKeyPair = new NemFacade.KeyPair(
    new PrivateKey(SIGNER_PRIVATE_KEY));

const facade = new NemFacade('testnet');
const signerAddress = facade.network.publicKeyToAddress(
    signerKeyPair.publicKey);
console.log('Signer address:', signerAddress.toString());

try {
    // Fetch current network time
    const timePath = '/time-sync/network-time';
    console.log('Fetching current network time from', timePath);
    const timeResponse = await fetch(`${NODE_URL}${timePath}`);
    const timeJSON = await timeResponse.json();
    const networkTime = Math.floor(timeJSON.receiveTimeStamp / 1000);
    console.log('  Network time:', networkTime,
        's since the nemesis block');

    // Derived fields from network time
    const timestamp = new NetworkTimestamp(networkTime);
    const deadline = timestamp.addHours(2);

    // Choose the subnamespace name
    const rootNamespaceName = process.env.ROOT_NAMESPACE || 'ns_root';
    const childNamespaceName = process.env.SUBNAMESPACE ||
        `sub_${Math.floor(Date.now() / 1000)}`;
    const fullNamespaceName =
        `${rootNamespaceName}.${childNamespaceName}`;
    console.log('Creating subnamespace:', fullNamespaceName);

    // Build the transaction
    const rentalFee = calculateNamespaceRentalFee(false);
    console.log('  Namespace lease fee:',
        `${Number(rentalFee) / 1_000_000} XEM`);

    const transaction = facade.transactionFactory.create({
        type: 'namespace_registration_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        timestamp: timestamp.timestamp,
        deadline: deadline.timestamp,
        rentalFeeSink: 'TAMESPACEWH4MKFMBCVFERDPOOP4FK7MTDJEYP35',
        rentalFee,
        parentName: rootNamespaceName,
        name: childNamespaceName
    });

    const fee = calculateTransactionFee(transaction);
    transaction.fee = new models.Amount(fee);
    console.log(`  Transaction fee: ${Number(fee) / 1_000_000} XEM`);

    // Sign transaction and generate final payload
    const signature = facade.signTransaction(signerKeyPair, transaction);
    const jsonPayload = facade.transactionFactory.static.attachSignature(
        transaction, signature);
    console.log('Built transaction:');
    console.dir(transaction.toJson(), { colors: true });

    // Announce the transaction
    const announcePath = '/transaction/announce';
    console.log('Announcing namespace registration to', announcePath);
    const announceResponse = await fetch(`${NODE_URL}${announcePath}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: jsonPayload
    });
    const announceResult = await announceResponse.json();
    console.log('  Result:', announceResult.message);

    // Wait for confirmation
    if ('SUCCESS' === announceResult.message) {
        const transactionHash = facade.hashTransaction(transaction)
            .toString();
        const statusPath = `/transaction/get?hash=${transactionHash}`;
        console.log('Waiting for confirmation from', statusPath);

        let isConfirmed = false;
        for (let attempt = 1; 120 >= attempt; ++attempt) {
            const response = await fetch(`${NODE_URL}${statusPath}`);

            if (response.ok) {
                const confirmed = await response.json();
                console.log('Transaction confirmed in block',
                    confirmed.meta.height);
                isConfirmed = true;
                break;
            }
            console.log('  Transaction status: pending');
            await new Promise(resolve => { setTimeout(resolve, 1000); });
        }
        if (!isConfirmed)
            console.warn('Confirmation took too long.');
    } else {
        console.log('Transaction rejected:', announceResult.message);
    }
    // Retrieve the namespace
    const namespacePath = `/namespace?namespace=${fullNamespaceName}`;
    console.log('Fetching namespace information from', namespacePath);
    const namespaceResponse = await fetch(`${NODE_URL}${namespacePath}`);
    const namespaceInfo = await namespaceResponse.json();
    console.log('Namespace information:');
    console.log('  Name:', namespaceInfo.fqn);
    console.log('  Owner:', namespaceInfo.owner);
    console.log('  Registration height:', namespaceInfo.height);

} catch (e) {
    console.error(e.message, '| Cause:', e.cause?.code ?? 'unknown');
}

Download source

Code Explanation⚓︎

The code follows the same pattern as the Registering a Root Namespace tutorial. This section focuses only on the key differences.

For detailed explanations of the common steps (setting up the account, fetching network time, announcing) and the transaction descriptor fields shared with a root namespace, see Registering a Root Namespace.

Choosing the Subnamespace Name⚓︎

41
42
43
44
45
46
47
    # Choose the subnamespace name
    root_namespace_name = os.getenv('ROOT_NAMESPACE', 'ns_root')
    child_namespace_name = os.getenv(
        'SUBNAMESPACE', f'sub_{int(time.time())}')
    full_namespace_name = (
        f'{root_namespace_name}.{child_namespace_name}')
    print(f'Creating subnamespace: {full_namespace_name}')

38
39
40
41
42
43
44
    // Choose the subnamespace name
    const rootNamespaceName = process.env.ROOT_NAMESPACE || 'ns_root';
    const childNamespaceName = process.env.SUBNAMESPACE ||
        `sub_${Math.floor(Date.now() / 1000)}`;
    const fullNamespaceName =
        `${rootNamespaceName}.${childNamespaceName}`;
    console.log('Creating subnamespace:', fullNamespaceName);

A subnamespace is identified by its full name, which joins the parent namespace name and the child name with a dot, such as ns_root.product. See Name in the Textbook for the naming rules.

To avoid collisions across multiple runs of the tutorial, a timestamp is added to the child name. In practice, however, programs would use a fixed name for their subnamespaces. You can force the tutorial to use fixed names through the ROOT_NAMESPACE and SUBNAMESPACE environment variables.

Use a parent namespace owned by the signer

By default, the code uses the test account referenced by SIGNER_PRIVATE_KEY and a parent namespace named ns_root.

If you come from the Registering a Root Namespace tutorial, set the SIGNER_PRIVATE_KEY and ROOT_NAMESPACE environment variables to match the account and namespace you created there, or any other namespace that the signer owns.

Building the Transaction⚓︎

49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
    # Build the transaction
    rental_fee = calculate_namespace_rental_fee(False)
    print(f'  Namespace lease fee: {rental_fee / 1_000_000} XEM')

    transaction = facade.transaction_factory.create({
        'type': 'namespace_registration_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'timestamp': timestamp.timestamp,
        'deadline': deadline.timestamp,
        'rental_fee_sink': 'TAMESPACEWH4MKFMBCVFERDPOOP4FK7MTDJEYP35',
        'rental_fee': rental_fee,
        'parent_name': root_namespace_name,
        'name': child_namespace_name
    })

    fee = calculate_transaction_fee(transaction)
    transaction.fee = Amount(fee)
    print(f'  Transaction fee: {fee / 1_000_000} XEM')

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
    // Build the transaction
    const rentalFee = calculateNamespaceRentalFee(false);
    console.log('  Namespace lease fee:',
        `${Number(rentalFee) / 1_000_000} XEM`);

    const transaction = facade.transactionFactory.create({
        type: 'namespace_registration_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        timestamp: timestamp.timestamp,
        deadline: deadline.timestamp,
        rentalFeeSink: 'TAMESPACEWH4MKFMBCVFERDPOOP4FK7MTDJEYP35',
        rentalFee,
        parentName: rootNamespaceName,
        name: childNamespaceName
    });

    const fee = calculateTransactionFee(transaction);
    transaction.fee = new models.Amount(fee);
    console.log(`  Transaction fee: ${Number(fee) / 1_000_000} XEM`);

The main difference when registering a subnamespace is in the transaction descriptor:

  • : The name of the parent namespace, defined in the previous step. It can be a root namespace or another subnamespace.

  • : The name of the subnamespace, chosen in the previous step.

    Note that this is just the name of the subnamespace, not the full path. For example, to create company.product, where company is the root, you would set and .

  • : The lease fee, which is 10 XEM for subnamespaces, paid to the same sink account as root namespaces.

    The SDK's helper returns the required amount. The argument requests the fee for a subnamespace.

The transaction is then signed, announced, and confirmed following the same process as in the Registering a Root Namespace tutorial.

Retrieving the Subnamespace⚓︎

112
113
114
115
116
117
118
119
120
121
122
    # Retrieve the namespace
    namespace_path = f'/namespace?namespace={full_namespace_name}'
    print(f'Fetching namespace information from {namespace_path}')
    with urllib.request.urlopen(
        f'{NODE_URL}{namespace_path}'
    ) as response:
        namespace_info = json.loads(response.read().decode())
        print('Namespace information:')
        print(f'  Name: {namespace_info["fqn"]}')
        print(f'  Owner: {namespace_info["owner"]}')
        print(f'  Registration height: {namespace_info["height"]}')

110
111
112
113
114
115
116
117
118
    // Retrieve the namespace
    const namespacePath = `/namespace?namespace=${fullNamespaceName}`;
    console.log('Fetching namespace information from', namespacePath);
    const namespaceResponse = await fetch(`${NODE_URL}${namespacePath}`);
    const namespaceInfo = await namespaceResponse.json();
    console.log('Namespace information:');
    console.log('  Name:', namespaceInfo.fqn);
    console.log('  Owner:', namespaceInfo.owner);
    console.log('  Registration height:', namespaceInfo.height);

To verify the subnamespace was registered, the code retrieves it from the network using the /namespace GET endpoint and displays its properties.

The subnamespace is queried by its full name, which joins the parent and child names with a dot (for example, ns_root.sub_1783411728).

A successful response confirms the subnamespace is registered and active.

The response also shows the registration height, which is the block in which the root namespace was registered, because subnamespaces inherit their root namespace's lease.

Subnamespace duration

A subnamespace expires when its root namespace expires and cannot be renewed on its own. Renewing the root namespace also renews the subnamespace.

Output⚓︎

The output shown below corresponds to a typical run of the program.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
Using node http://libertalia.nemtest.net:7890
Signer address: TBONKWCOWBZYZB2I5JD3LSDBQVBYHB757VN3SKPP
Fetching current network time from /time-sync/network-time
  Network time: 355824143 s since the nemesis block
Creating subnamespace: ns_root.sub_1783411728
  Namespace lease fee: 10.0 XEM
  Transaction fee: 0.15 XEM
Built transaction:
{
  "type": 8193,
  "version": 1,
  "network": 152,
  "timestamp": 355824143,
  "signer_public_key": "462EE976890916E54FA825D26BDD0235F5EB5B6A143C199AB0AE5EE9328E08CE",
  "signature": "EB8065E0D51173189950A7F28863135AA2E308B1F9A32840BCF48E85F15E0DD0AC48D8B6999D2BEDDC4B934842F93C9C4B4AFF28820CFA3B7EE73FE09B3D2303",
  "fee": "150000",
  "deadline": 355831343,
  "rental_fee_sink": "54414D4553504143455748344D4B464D42435646455244504F4F5034464B374D54444A4559503335",
  "rental_fee": "10000000",
  "name": "7375625f31373833343131373238",
  "parent_name": "6e735f726f6f74"
}
Announcing namespace registration to /transaction/announce
  Result: SUCCESS
Waiting for confirmation from /transaction/get?hash=79C4412BC6A9AA73DB37AD01ECDC84A17926FB5E152979FFDCCFE567EC4F63ED
  Transaction status: pending
  Transaction status: pending
  Transaction status: pending
Transaction confirmed in block 690650
Fetching namespace information from /namespace?namespace=ns_root.sub_1783411728
Namespace information:
  Name: ns_root.sub_1783411728
  Owner: TBONKWCOWBZYZB2I5JD3LSDBQVBYHB757VN3SKPP
  Registration height: 690649

Some highlights from the output:

  • Full namespace path (line 5): ns_root.sub_1783411728 combines the parent namespace ns_root with the subnamespace name set in the transaction.

  • Lease fee and transaction fee (lines 6-7): The lease fee is 10 XEM because this is a subnamespace (root namespaces pay 100 XEM instead), while the transaction fee is 0.15 XEM.

  • Namespace information (lines 32-34): The registered subnamespace, its owner (the signer's address), and the registration height, which is the block at which the root namespace's lease began, inherited by the subnamespace.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Build a subnamespace registration transaction , NamespaceRegistrationTransactionV1
Calculate the lease fee
Retrieve the subnamespace /namespace GET

Next Steps⚓︎

Now that you have a subnamespace, you can:

  • Register additional subnamespaces to expand your hierarchical structure
  • Define mosaics under the subnamespace to create custom assets