Skip to content
INTERMEDIATE

Linking and Unlinking Namespaces to Mosaics⚓︎

Namespaces can be linked to mosaics to create human-readable aliases that can be used instead of long hexadecimal mosaic IDs in transactions.

This tutorial shows how to link a namespace to a mosaic identifier and how to unlink it when no longer needed.

Prerequisites⚓︎

Before you start, make sure to:

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

Namespace and mosaic ownership required

Only the account that owns both the namespace and the mosaic can link them together.

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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
import json
import os
import time
import urllib.request

from symbolchain.CryptoTypes import PrivateKey
from symbolchain.facade.SymbolFacade import SymbolFacade
from symbolchain.sc import Amount
from symbolchain.symbol.IdGenerator import (
    generate_mosaic_alias_id,
    generate_namespace_path
)
from symbolchain.symbol.Network import NetworkTimestamp

NODE_URL = os.getenv('NODE_URL', 'https://reference.symboltest.net:3001')
print(f'Using node {NODE_URL}')


# Helper function to announce a transaction
def announce_transaction(payload, label):
    print(f'Announcing {label} to /transactions')
    request = urllib.request.Request(
        f'{NODE_URL}/transactions',
        data=payload.encode(),
        headers={'Content-Type': 'application/json'},
        method='PUT'
    )
    with urllib.request.urlopen(request) as announce_response:
        print(f'  Response: {announce_response.read().decode()}')


# Helper function to wait for transaction confirmation
def wait_for_confirmation(tx_hash, label):
    print(f'Waiting for {label} confirmation...')
    for attempt in range(60):
        time.sleep(1)
        try:
            url = f'{NODE_URL}/transactionStatus/{tx_hash}'
            with urllib.request.urlopen(url) as confirm_response:
                status = json.loads(confirm_response.read().decode())
                print(f"  Transaction status: {status['group']}")
                if status['group'] == 'confirmed':
                    print(f'{label} confirmed in {attempt} seconds')
                    return
                if status['group'] == 'failed':
                    raise RuntimeError(f"{label} failed: {status['code']}")
        except urllib.error.HTTPError:
            print('  Transaction status: unknown')
    raise TimeoutError(f'{label} not confirmed after 60 seconds')


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

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

namespace_name = os.getenv('NAMESPACE_NAME', 'my_namespace')
print(f'Namespace name: {namespace_name}')

namespace_id = generate_namespace_path(namespace_name)[-1]
print(f'Namespace ID: {namespace_id} ({hex(namespace_id)})')

# Target mosaic ID to link the namespace to
mosaic_id = int(os.getenv('MOSAIC_ID', '0x45C8C3733983AAC2'), 16)
print(f'Mosaic ID: {mosaic_id} ({hex(mosaic_id)})')

try:
    # Fetch current network time
    time_path = '/node/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())
        receive_timestamp = (
            response_json['communicationTimestamps']['receiveTimestamp'])
        timestamp = NetworkTimestamp(int(receive_timestamp))
        print(f'  Network time: {timestamp.timestamp} ms since nemesis')

    # Fetch recommended fees
    fee_path = '/network/fees/transaction'
    print(f'Fetching recommended fees from {fee_path}')
    with urllib.request.urlopen(f'{NODE_URL}{fee_path}') as response:
        response_json = json.loads(response.read().decode())
        median_multiplier = response_json['medianFeeMultiplier']
        minimum_multiplier = response_json['minFeeMultiplier']
        fee_multiplier = max(median_multiplier, minimum_multiplier)
        print(f'  Fee multiplier: {fee_multiplier}')

    # Build the alias transaction
    transaction = facade.transaction_factory.create({
        'type': 'mosaic_alias_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'namespace_id': namespace_id,
        'mosaic_id': mosaic_id,
        'alias_action': 'link'
    })
    transaction.fee = Amount(fee_multiplier * transaction.size)

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

    transaction_hash = facade.hash_transaction(transaction)
    print(f'Transaction hash: {transaction_hash}')

    # Announce and confirm transaction
    announce_transaction(json_payload, 'mosaic alias transaction')
    wait_for_confirmation(transaction_hash, 'mosaic alias transaction')

    # Retrieve the namespace to verify the alias
    namespace_path = f'/namespaces/{namespace_id:x}'
    print(f'Fetching namespace information from {namespace_path}')
    with urllib.request.urlopen(f'{NODE_URL}{namespace_path}') as response:
        response_json = json.loads(response.read().decode())
        namespace_info = response_json['namespace']
        print('Alias information:')
        alias_type = namespace_info['alias']['type']
        print(f'  Alias type: {alias_type}')
        if alias_type == 1:  # MOSAIC type
            aliased_mosaic_id = namespace_info['alias']['mosaicId']
            print(f'  Linked mosaic ID: {aliased_mosaic_id}')

    # Send a transfer using the alias instead of a raw mosaic ID
    print(f'Using alias in transfer: {namespace_name}')

    # Convert namespace to mosaic alias ID
    mosaic_alias_id = generate_mosaic_alias_id(namespace_name)
    print(f'Mosaic ID (alias):'
        f' {mosaic_alias_id} ({hex(mosaic_alias_id)})')

    test_transaction = facade.transaction_factory.create({
        'type': 'transfer_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'recipient_address':
            facade.network.public_key_to_address(
                signer_key_pair.public_key),
        'mosaics': [{
            'mosaic_id': mosaic_alias_id,
            'amount': 1
        }]
    })
    test_transaction.fee = Amount(fee_multiplier * test_transaction.size)
    test_json_payload = facade.transaction_factory.attach_signature(
        test_transaction,
        facade.sign_transaction(signer_key_pair, test_transaction))
    print('Test transaction:')
    print(json.dumps(test_transaction.to_json(), indent=2))
    test_transaction_hash = facade.hash_transaction(test_transaction)
    print(f'Transaction hash: {test_transaction_hash}')
    announce_transaction(test_json_payload, 'test transaction')
    wait_for_confirmation(test_transaction_hash, 'test transaction')

except Exception as e:
    print(e)

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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
import { PrivateKey } from 'symbol-sdk';
import {
    NetworkTimestamp,
    SymbolFacade,
    generateMosaicAliasId,
    generateNamespacePath,
    models
} from 'symbol-sdk/symbol';

const NODE_URL = process.env.NODE_URL ||
    'https://reference.symboltest.net:3001';
console.log('Using node', NODE_URL);

// Helper function to announce a transaction
async function announceTransaction(payload, label) {
    console.log(`Announcing ${label} to /transactions`);
    const response = await fetch(`${NODE_URL}/transactions`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: payload
    });
    console.log('  Response:', await response.text());
}

// Helper function to wait for transaction confirmation
async function waitForConfirmation(transactionHash, label) {
    console.log(`Waiting for ${label} confirmation...`);
    for (let attempt = 0; 60 > attempt; attempt++) {
        await new Promise(resolve => { setTimeout(resolve, 1000); });
        try {
            const response = await fetch(
                `${NODE_URL}/transactionStatus/${transactionHash}`);
            const status = await response.json();
            console.log('  Transaction status:', status.group);
            if ('confirmed' === status.group) {
                console.log(`${label} confirmed in`, attempt, 'seconds');
                return;
            }
            if ('failed' === status.group)
                throw new Error(`${label} failed: ${status.code}`);
        } catch (e) {
            if (e.message.includes('failed'))
                throw e;
            console.log('  Transaction status: unknown');
        }
    }
    throw new Error(`${label} not confirmed after 60 seconds`);
}


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

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

const namespaceName = process.env.NAMESPACE_NAME || 'my_namespace';
console.log('Namespace name:', namespaceName);

const nsPath = generateNamespacePath(namespaceName);
const namespaceId = nsPath[nsPath.length - 1];
console.log(
    'Namespace ID:',
    `${namespaceId} (0x${namespaceId.toString(16)})`);

// Target mosaic ID to link the namespace to
const mosaicId = BigInt(process.env.MOSAIC_ID || '0x45C8C3733983AAC2');
console.log('Mosaic ID:', `${mosaicId} (0x${mosaicId.toString(16)})`);

try {
    // Fetch current network time
    const timePath = '/node/time';
    console.log('Fetching current network time from', timePath);
    const timeResponse = await fetch(`${NODE_URL}${timePath}`);
    const timeJSON = await timeResponse.json();
    const receiveTimestamp =
        timeJSON.communicationTimestamps.receiveTimestamp;
    const timestamp = new NetworkTimestamp(receiveTimestamp);
    console.log('  Network time:', timestamp.timestamp,
        'ms since nemesis');

    // Fetch recommended fees
    const feePath = '/network/fees/transaction';
    console.log('Fetching recommended fees from', feePath);
    const feeResponse = await fetch(`${NODE_URL}${feePath}`);
    const feeJSON = await feeResponse.json();
    const medianMultiplier = feeJSON.medianFeeMultiplier;
    const minimumMultiplier = feeJSON.minFeeMultiplier;
    const feeMultiplier = Math.max(medianMultiplier, minimumMultiplier);
    console.log('  Fee multiplier:', feeMultiplier);

    // Build the alias transaction
    const transaction = facade.transactionFactory.create({
        type: 'mosaic_alias_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        namespaceId,
        mosaicId,
        aliasAction: 'link'
    });
    transaction.fee = new models.Amount(feeMultiplier * transaction.size);

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

    const transactionHash = facade.hashTransaction(transaction).toString();
    console.log('Transaction hash:', transactionHash);

    // Announce and confirm transaction
    await announceTransaction(jsonPayload, 'mosaic alias transaction');
    await waitForConfirmation(transactionHash, 'mosaic alias transaction');

    // Retrieve the namespace to verify the alias
    const namespacePath = `/namespaces/${namespaceId.toString(16)}`;
    console.log('Fetching namespace information from', namespacePath);
    const namespaceResponse = await fetch(`${NODE_URL}${namespacePath}`);
    const namespaceJSON = await namespaceResponse.json();
    const namespaceInfo = namespaceJSON.namespace;
    console.log('Alias information:');
    console.log('  Alias type:', namespaceInfo.alias.type);
    if (1 === namespaceInfo.alias.type) { // MOSAIC type
        console.log('  Linked mosaic ID:', namespaceInfo.alias.mosaicId);
    }

    // Send a transfer using the alias instead of a raw mosaic ID
    console.log('Using alias in transfer:', namespaceName);

    // Convert namespace to mosaic alias ID
    const mosaicAliasId = generateMosaicAliasId(namespaceName);
    console.log('  Mosaic ID (alias):',
        `${mosaicAliasId} (0x${mosaicAliasId.toString(16)})`);

    const test_transaction = facade.transactionFactory.create({
        type: 'transfer_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        recipientAddress: facade.network.publicKeyToAddress(
            signerKeyPair.publicKey).toString(),
        mosaics: [{
            mosaicId: mosaicAliasId,
            amount: 1n
        }]
    });
    test_transaction.fee = new models.Amount(
        feeMultiplier * test_transaction.size);
    const testJsonPayload =
        facade.transactionFactory.static.attachSignature(
            test_transaction,
            facade.signTransaction(signerKeyPair, test_transaction));
    console.log('Test transaction:');
    console.dir(test_transaction.toJson(), { colors: true });
    const testTransactionHash =
        facade.hashTransaction(test_transaction).toString();
    console.log('Transaction hash:', testTransactionHash);
    await announceTransaction(testJsonPayload, 'test transaction');
    await waitForConfirmation(testTransactionHash, 'test transaction');

} catch (e) {
    console.error(e.message);
}

Download source

Code Explanation⚓︎

Setting Up the Account⚓︎

52
53
54
55
56
57
58
59
60
SIGNER_PRIVATE_KEY = os.getenv(
    'SIGNER_PRIVATE_KEY',
    '0000000000000000000000000000000000000000000000000000000000000000')
signer_key_pair = SymbolFacade.KeyPair(PrivateKey(SIGNER_PRIVATE_KEY))

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

51
52
53
54
55
56
57
58
59
const SIGNER_PRIVATE_KEY = process.env.SIGNER_PRIVATE_KEY ||
    '0000000000000000000000000000000000000000000000000000000000000000';
const signerKeyPair = new SymbolFacade.KeyPair(
    new PrivateKey(SIGNER_PRIVATE_KEY));

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

The snippet reads the signer's private key from the SIGNER_PRIVATE_KEY environment variable, which defaults to a test key if not set. The signer's address is derived from the public key. This account must own both the namespace and the mosaic being linked.

Defining the Namespace and Target Mosaic⚓︎

62
63
64
65
66
67
68
69
70
namespace_name = os.getenv('NAMESPACE_NAME', 'my_namespace')
print(f'Namespace name: {namespace_name}')

namespace_id = generate_namespace_path(namespace_name)[-1]
print(f'Namespace ID: {namespace_id} ({hex(namespace_id)})')

# Target mosaic ID to link the namespace to
mosaic_id = int(os.getenv('MOSAIC_ID', '0x45C8C3733983AAC2'), 16)
print(f'Mosaic ID: {mosaic_id} ({hex(mosaic_id)})')

61
62
63
64
65
66
67
68
69
70
71
72
const namespaceName = process.env.NAMESPACE_NAME || 'my_namespace';
console.log('Namespace name:', namespaceName);

const nsPath = generateNamespacePath(namespaceName);
const namespaceId = nsPath[nsPath.length - 1];
console.log(
    'Namespace ID:',
    `${namespaceId} (0x${namespaceId.toString(16)})`);

// Target mosaic ID to link the namespace to
const mosaicId = BigInt(process.env.MOSAIC_ID || '0x45C8C3733983AAC2');
console.log('Mosaic ID:', `${mosaicId} (0x${mosaicId.toString(16)})`);

The code defines:

  • Namespace name: The namespace to link, read from the NAMESPACE_NAME environment variable, which defaults to my_namespace if not set. This name must match a namespace that your account already owns.

  • Namespace ID: The ID is generated from the namespace name using , which returns an array of IDs for each level in the hierarchy. The last element is selected to get the final namespace ID. Taking the last element works for both root namespaces and subnamespaces.

    For a root namespace like foo, the array contains one element. For a subnamespace like symbol.xym, it contains two elements, and the last one is the ID of xym under symbol.

    Subnamespace IDs are unique

    Subnamespace IDs are derived hierarchically, so two subnamespaces with the same leaf name but different parents produce different IDs. For example, the last element of the path for foo.xym and bar.xym will be different.

  • Mosaic ID: The hexadecimal identifier of the mosaic that the namespace will point to, read from the MOSAIC_ID environment variable. If not set, a default test mosaic ID is used.

Fetching Network Time and Fees⚓︎

73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
    # Fetch current network time
    time_path = '/node/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())
        receive_timestamp = (
            response_json['communicationTimestamps']['receiveTimestamp'])
        timestamp = NetworkTimestamp(int(receive_timestamp))
        print(f'  Network time: {timestamp.timestamp} ms since nemesis')

    # Fetch recommended fees
    fee_path = '/network/fees/transaction'
    print(f'Fetching recommended fees from {fee_path}')
    with urllib.request.urlopen(f'{NODE_URL}{fee_path}') as response:
        response_json = json.loads(response.read().decode())
        median_multiplier = response_json['medianFeeMultiplier']
        minimum_multiplier = response_json['minFeeMultiplier']
        fee_multiplier = max(median_multiplier, minimum_multiplier)
        print(f'  Fee multiplier: {fee_multiplier}')

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
    // Fetch current network time
    const timePath = '/node/time';
    console.log('Fetching current network time from', timePath);
    const timeResponse = await fetch(`${NODE_URL}${timePath}`);
    const timeJSON = await timeResponse.json();
    const receiveTimestamp =
        timeJSON.communicationTimestamps.receiveTimestamp;
    const timestamp = new NetworkTimestamp(receiveTimestamp);
    console.log('  Network time:', timestamp.timestamp,
        'ms since nemesis');

    // Fetch recommended fees
    const feePath = '/network/fees/transaction';
    console.log('Fetching recommended fees from', feePath);
    const feeResponse = await fetch(`${NODE_URL}${feePath}`);
    const feeJSON = await feeResponse.json();
    const medianMultiplier = feeJSON.medianFeeMultiplier;
    const minimumMultiplier = feeJSON.minFeeMultiplier;
    const feeMultiplier = Math.max(medianMultiplier, minimumMultiplier);
    console.log('  Fee multiplier:', feeMultiplier);

Network time and recommended fees are fetched from /node/time GET and /network/fees/transaction GET respectively, following the process described in the Transfer Transaction tutorial.

Building the Transaction⚓︎

 93
 94
 95
 96
 97
 98
 99
100
101
102
    # Build the alias transaction
    transaction = facade.transaction_factory.create({
        'type': 'mosaic_alias_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'namespace_id': namespace_id,
        'mosaic_id': mosaic_id,
        'alias_action': 'link'
    })
    transaction.fee = Amount(fee_multiplier * transaction.size)

 96
 97
 98
 99
100
101
102
103
104
105
    // Build the alias transaction
    const transaction = facade.transactionFactory.create({
        type: 'mosaic_alias_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        namespaceId,
        mosaicId,
        aliasAction: 'link'
    });
    transaction.fee = new models.Amount(feeMultiplier * transaction.size);

The mosaic alias transaction specifies:

  • Type: Mosaic alias transactions use the type MosaicAliasTransactionV1.

  • Signer public key: The account that owns the namespace and mosaic, and will pay the transaction fee.

  • Namespace ID: The identifier of the namespace being linked.

  • Mosaic ID: The identifier of the mosaic to link to the namespace.

  • Alias action: The value link creates the alias. To remove the alias later, use unlink instead.

Unlinking an alias

To unlink a namespace from a mosaic, announce another MosaicAliasTransactionV1 transaction with the same namespace ID and mosaic ID, but set the field to unlink.

The unlinking process does not remove the namespace or the mosaic, only the association between them. After unlinking, the namespace can be linked to a different mosaic or address.

Submitting the Transaction⚓︎

104
105
106
107
108
109
110
111
112
113
114
115
116
    # Sign transaction and generate final payload
    json_payload = facade.transaction_factory.attach_signature(
        transaction,
        facade.sign_transaction(signer_key_pair, transaction))
    print('Mosaic alias transaction:')
    print(json.dumps(transaction.to_json(), indent=2))

    transaction_hash = facade.hash_transaction(transaction)
    print(f'Transaction hash: {transaction_hash}')

    # Announce and confirm transaction
    announce_transaction(json_payload, 'mosaic alias transaction')
    wait_for_confirmation(transaction_hash, 'mosaic alias transaction')

107
108
109
110
111
112
113
114
115
116
117
118
119
    // Sign transaction and generate final payload
    const jsonPayload = facade.transactionFactory.static.attachSignature(
        transaction,
        facade.signTransaction(signerKeyPair, transaction));
    console.log('Built transaction:');
    console.dir(transaction.toJson(), { colors: true });

    const transactionHash = facade.hashTransaction(transaction).toString();
    console.log('Transaction hash:', transactionHash);

    // Announce and confirm transaction
    await announceTransaction(jsonPayload, 'mosaic alias transaction');
    await waitForConfirmation(transactionHash, 'mosaic alias transaction');

The transaction is signed and announced following the same process as in Creating a Transfer Transaction.

Verifying the Alias⚓︎

118
119
120
121
122
123
124
125
126
127
128
129
    # Retrieve the namespace to verify the alias
    namespace_path = f'/namespaces/{namespace_id:x}'
    print(f'Fetching namespace information from {namespace_path}')
    with urllib.request.urlopen(f'{NODE_URL}{namespace_path}') as response:
        response_json = json.loads(response.read().decode())
        namespace_info = response_json['namespace']
        print('Alias information:')
        alias_type = namespace_info['alias']['type']
        print(f'  Alias type: {alias_type}')
        if alias_type == 1:  # MOSAIC type
            aliased_mosaic_id = namespace_info['alias']['mosaicId']
            print(f'  Linked mosaic ID: {aliased_mosaic_id}')

121
122
123
124
125
126
127
128
129
130
131
    // Retrieve the namespace to verify the alias
    const namespacePath = `/namespaces/${namespaceId.toString(16)}`;
    console.log('Fetching namespace information from', namespacePath);
    const namespaceResponse = await fetch(`${NODE_URL}${namespacePath}`);
    const namespaceJSON = await namespaceResponse.json();
    const namespaceInfo = namespaceJSON.namespace;
    console.log('Alias information:');
    console.log('  Alias type:', namespaceInfo.alias.type);
    if (1 === namespaceInfo.alias.type) { // MOSAIC type
        console.log('  Linked mosaic ID:', namespaceInfo.alias.mosaicId);
    }

To verify the alias was created, the code retrieves the namespace information from the network using the /namespaces/{namespaceId} GET endpoint.

The response includes the alias type (mosaic) and the linked mosaic ID, confirming the namespace now points to the specified mosaic.

Using the Alias⚓︎

131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
    # Send a transfer using the alias instead of a raw mosaic ID
    print(f'Using alias in transfer: {namespace_name}')

    # Convert namespace to mosaic alias ID
    mosaic_alias_id = generate_mosaic_alias_id(namespace_name)
    print(f'Mosaic ID (alias):'
        f' {mosaic_alias_id} ({hex(mosaic_alias_id)})')

    test_transaction = facade.transaction_factory.create({
        'type': 'transfer_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'recipient_address':
            facade.network.public_key_to_address(
                signer_key_pair.public_key),
        'mosaics': [{
            'mosaic_id': mosaic_alias_id,
            'amount': 1
        }]
    })
    test_transaction.fee = Amount(fee_multiplier * test_transaction.size)
    test_json_payload = facade.transaction_factory.attach_signature(
        test_transaction,
        facade.sign_transaction(signer_key_pair, test_transaction))
    print('Test transaction:')
    print(json.dumps(test_transaction.to_json(), indent=2))
    test_transaction_hash = facade.hash_transaction(test_transaction)
    print(f'Transaction hash: {test_transaction_hash}')
    announce_transaction(test_json_payload, 'test transaction')
    wait_for_confirmation(test_transaction_hash, 'test transaction')

133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
    // Send a transfer using the alias instead of a raw mosaic ID
    console.log('Using alias in transfer:', namespaceName);

    // Convert namespace to mosaic alias ID
    const mosaicAliasId = generateMosaicAliasId(namespaceName);
    console.log('  Mosaic ID (alias):',
        `${mosaicAliasId} (0x${mosaicAliasId.toString(16)})`);

    const test_transaction = facade.transactionFactory.create({
        type: 'transfer_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        recipientAddress: facade.network.publicKeyToAddress(
            signerKeyPair.publicKey).toString(),
        mosaics: [{
            mosaicId: mosaicAliasId,
            amount: 1n
        }]
    });
    test_transaction.fee = new models.Amount(
        feeMultiplier * test_transaction.size);
    const testJsonPayload =
        facade.transactionFactory.static.attachSignature(
            test_transaction,
            facade.signTransaction(signerKeyPair, test_transaction));
    console.log('Test transaction:');
    console.dir(test_transaction.toJson(), { colors: true });
    const testTransactionHash =
        facade.hashTransaction(test_transaction).toString();
    console.log('Transaction hash:', testTransactionHash);
    await announceTransaction(testJsonPayload, 'test transaction');
    await waitForConfirmation(testTransactionHash, 'test transaction');

Once the namespace is linked to a mosaic, the namespace can be used in place of the mosaic ID in transactions. The code demonstrates creating a transfer transaction using the alias in the mosaics array instead of the full hexadecimal mosaic ID.

This example sends the mosaic back to the sender's own address.

To use a namespace as a mosaic ID, the namespace name is converted to its mosaic alias ID using .

The rest of the transaction is a conventional transfer transaction. For more details on how to sign, announce, and confirm transactions, see the Transfer Transaction tutorial.

Mosaic Resolution Receipt

When the network processes a transaction that uses a namespace alias as a mosaic ID, it generates a Mosaic Resolution Receipt. This receipt records the actual mosaic ID the alias pointed to at the time the transaction was confirmed.

This is important for historical auditability: since aliases can be changed or removed at any time, the receipt ensures that the resolved mosaic ID can always be verified, even if the alias has since been updated.

Resolution receipts can be queried using the /statements/resolutions/mosaic GET endpoint. For more details on receipts, see the Resolution Statements section in the Textbook.

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
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
Using node https://reference.symboltest.net:3001
Signer address: TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I
Namespace name: ns_1778514754.sub_1778514998
Namespace ID: 18182428759753405815 (0xfc54f69f52f2b577)
Mosaic ID: 507540378882865098 (0x70b2549187af7ca)
Fetching current network time from /node/time
  Network time: 111579658666 ms since nemesis
Fetching recommended fees from /network/fees/transaction
  Fee multiplier: 100
Mosaic alias transaction:
{
  "signature": "D969758584AA819BC7135E817368DBCAFEBFFBE39B7FE30807017F418C770B5D19FBD3E08CA2EE67D54DDBD4C1D3323965AFA87509174B737AAA4BA116AF2604",
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 1,
  "network": 152,
  "type": 17230,
  "fee": "14500",
  "deadline": "111586858666",
  "namespace_id": "18182428759753405815",
  "mosaic_id": "507540378882865098",
  "alias_action": 1
}
Transaction hash: 67D18EB6A8F09B8C94AA96D7EB06AE9D2700A6457AAAD2037BAF5DFB9F51E7DF
Announcing mosaic alias transaction to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for mosaic alias transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: confirmed
mosaic alias transaction confirmed in 7 seconds
Fetching namespace information from /namespaces/fc54f69f52f2b577
Alias information:
  Alias type: 1
  Linked mosaic ID: 070B2549187AF7CA
Using alias in transfer: ns_1778514754.sub_1778514998
Mosaic ID (alias): 18182428759753405815 (0xfc54f69f52f2b577)
Test transaction:
{
  "signature": "B5EBF90EE702EEBF4788401B4508036CD1E46EE43E383AF0932B4F83B77533BDD0B94670F82A0EB4BCAEAE7987D535599D1D4914FB077D2A55EF52ABB6738906",
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 1,
  "network": 152,
  "type": 16724,
  "fee": "17600",
  "deadline": "111586858666",
  "recipient_address": "988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE9",
  "mosaics": [
    {
      "mosaic_id": "18182428759753405815",
      "amount": "1"
    }
  ],
  "message": ""
}
Transaction hash: 631FAB32C1021560995B7619A0BCB92EA436CF525C3116C483B0A0B0E288D8B0
Announcing test transaction to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for test transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: confirmed
test transaction confirmed in 29 seconds

Some highlights from the output:

  • Namespace and target (lines 3, 5): The namespace and mosaic ID being linked.

  • Transaction hash (line 23): The transaction hash can be used to search for the transaction in the Symbol Testnet Explorer.

  • Alias verification (lines 32-33): The namespace information confirms the alias type is 1 (mosaic) and shows the linked mosaic ID.

  • Using the alias (line 35): A transfer transaction is created using the alias in the mosaics array, demonstrating that it can be used in place of the full mosaic ID.

    Different mosaic ID

    The mosaic ID used in the transfer differs from the original mosaic ID because it is the encoded namespace ID, not the mosaic ID itself. The network resolves the alias to the linked mosaic when processing the transaction.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Generate namespace ID
Build a mosaic alias transaction
Verify the alias /namespaces/{namespaceId} GET
Use the alias in a transfer
Query mosaic resolution receipts /statements/resolutions/mosaic GET