Skip to content

Linking and Unlinking Namespaces to Addresses⚓︎

namespaces can be linked to addresses to create human-readable aliases that can be used instead of long hexadecimal addresses in transactions.

This tutorial shows how to link a namespace to an account address 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 ownership required

Only the account that owns the namespace can link it to an address. The target address does not need to cosign or approve the link.

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
import json
import os
import time
import urllib.request

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

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

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 address to link the namespace to
target_address = Address(
    os.getenv('TARGET_ADDRESS',
    'TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI'))
print(f'Target address: {target_address}')

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_mult = response_json['medianFeeMultiplier']
        minimum_mult = response_json['minFeeMultiplier']
        fee_mult = max(median_mult, minimum_mult)
        print(f'  Fee multiplier: {fee_mult}')

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

    # 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))

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

    # Announce transaction
    print('Announcing address alias transaction to /transactions')
    request = urllib.request.Request(
        f'{NODE_URL}/transactions',
        data=json_payload.encode(),
        headers={'Content-Type': 'application/json'},
        method='PUT'
    )
    with urllib.request.urlopen(request) as response:
        print(f'  Response: {response.read().decode()}')

    # Wait for confirmation
    print('Waiting for transaction confirmation...')
    for attempt in range(60):
        time.sleep(1)
        try:
            status_url = (
                f'{NODE_URL}/transactionStatus/{transaction_hash}')
            with urllib.request.urlopen(status_url) as response:
                status = json.loads(response.read().decode())
                print(f'  Transaction status: {status["group"]}')
            if status['group'] == 'confirmed':
                print('Address alias transaction confirmed in',
                    attempt, 'seconds')
                break
            if status['group'] == 'failed':
                raise Exception('Address alias transaction failed:',
                    status['code'])
        except urllib.error.HTTPError:
            print('  Transaction status: unknown')

    # 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 == 2:  # ADDRESS type
            aliased_address_hex = namespace_info['alias']['address']
            aliased_address = Address(bytes.fromhex(aliased_address_hex))
            print(f'  Linked address: {aliased_address}')

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

    # Encode the namespace ID as a recipient address (24 bytes)
    # Byte 0: network byte (Network Identifier | 0x01 to indicate alias)
    # Bytes 1-8: namespace ID in little-endian
    # Bytes 9-23: zero padding
    recipient_id = generate_namespace_path(namespace_name)[-1]
    recipient_address = Address(
        bytes([facade.network.identifier | 0x01]) +
        recipient_id.to_bytes(8, 'little') + bytes(15))

    transfer_tx = facade.transaction_factory.create({
        'type': 'transfer_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'recipient_address': recipient_address,
        'mosaics': [{
            'mosaic_id': generate_mosaic_alias_id('symbol.xym'),
            'amount': 1_000_000  # 1 XYM
        }]
    })
    print('Transfer transaction:')
    print(f'  Recipient address (alias): {recipient_address}')

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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
import { PrivateKey } from 'symbol-sdk';
import {
    SymbolFacade,
    NetworkTimestamp,
    models,
    generateNamespacePath,
    generateMosaicAliasId
} from 'symbol-sdk/symbol';

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

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 address to link the namespace to
const targetAddress = new SymbolFacade.Address(
    process.env.TARGET_ADDRESS ||
    'TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI');
console.log('Target address:', targetAddress.toString());

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 medianMult = feeJSON.medianFeeMultiplier;
    const minimumMult = feeJSON.minFeeMultiplier;
    const feeMult = Math.max(medianMult, minimumMult);
    console.log('  Fee multiplier:', feeMult);

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

    // 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 });

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

    // Announce transaction
    console.log('Announcing address alias transaction to /transactions');
    const announceResponse = await fetch(`${NODE_URL}/transactions`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: jsonPayload
    });
    console.log('  Response:', await announceResponse.text());

    // Wait for confirmation
    console.log('Waiting for transaction confirmation...');
    for (let attempt = 0; attempt < 60; attempt++) {
        await new Promise(resolve => setTimeout(resolve, 1000));

        try {
            const statusUrl =
                `${NODE_URL}/transactionStatus/${transactionHash}`;
            const statusResponse = await fetch(statusUrl);

            if (!statusResponse.ok) {
                console.log('  Transaction status: unknown');
                continue;
            }

            const status = await statusResponse.json();
            console.log('  Transaction status:', status.group);

            if (status.group === 'confirmed') {
                console.log('Address alias transaction confirmed in',
                    attempt, 'seconds');
                break;
            }

            if (status.group === 'failed') {
                throw new Error(
                    `Address alias transaction failed: ${status.code}`);
            }
        } catch (error) {
            if (error.message.includes('failed:')) {
                throw error;
            }
            console.log('  Transaction status: unknown');
        }
    }

    // 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 (namespaceInfo.alias.type === 2) { // ADDRESS type
        const aliasedAddress = new models.Address(
            Uint8Array.from(Buffer.from(
                namespaceInfo.alias.address, 'hex')));
        console.log('  Linked address:', aliasedAddress.toString());
    }

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

    // Encode the namespace ID as a recipient address (24 bytes)
    // Byte 0: network byte (Network Identifier | 0x01 to indicate alias)
    // Bytes 1-8: namespace ID in little-endian
    // Bytes 9-23: zero padding
    const recipientPath = generateNamespacePath(namespaceName);
    const recipientId = recipientPath[recipientPath.length - 1];
    const recipientBytes = new Uint8Array(24);
    recipientBytes[0] = facade.network.identifier | 0x01;
    // Convert namespace ID to little-endian bytes
    const recipientIdBytes = new Uint8Array(8);
    for (let i = 0; i < 8; i++) {
        recipientIdBytes[i] = Number(
            (recipientId >> BigInt(i * 8)) & 0xFFn);
    }
    recipientBytes.set(recipientIdBytes, 1);
    // Bytes 9-23 are already zero-filled
    const recipientAddress = new SymbolFacade.Address(recipientBytes);

    const transferTx = facade.transactionFactory.create({
        type: 'transfer_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        recipientAddress: recipientAddress,
        mosaics: [{
            mosaicId: generateMosaicAliasId('symbol.xym'),
            amount: 1_000_000n // 1 XYM
        }]
    });
    console.log('Transfer transaction:');
    console.log('  Recipient address (alias):',
        recipientAddress.toString());
} catch (e) {
    console.error(e.message);
}

Download source

Code Explanation⚓︎

Setting Up the Account⚓︎

18
19
20
21
22
23
24
25
26
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}')

14
15
16
17
18
19
20
21
22
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 the namespace being linked.

Defining the Namespace and Target Address⚓︎

28
29
30
31
32
33
34
35
36
37
38
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 address to link the namespace to
target_address = Address(
    os.getenv('TARGET_ADDRESS',
    'TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI'))
print(f'Target address: {target_address}')

24
25
26
27
28
29
30
31
32
33
34
35
36
37
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 address to link the namespace to
const targetAddress = new SymbolFacade.Address(
    process.env.TARGET_ADDRESS ||
    'TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI');
console.log('Target address:', targetAddress.toString());

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.

  • Target address: The address that the namespace will point to, read from the TARGET_ADDRESS environment variable. If not set, a default test address is used.

Fetching Network Time and Fees⚓︎

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
    # 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_mult = response_json['medianFeeMultiplier']
        minimum_mult = response_json['minFeeMultiplier']
        fee_mult = max(median_mult, minimum_mult)
        print(f'  Fee multiplier: {fee_mult}')

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
    // 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 medianMult = feeJSON.medianFeeMultiplier;
    const minimumMult = feeJSON.minFeeMultiplier;
    const feeMult = Math.max(medianMult, minimumMult);
    console.log('  Fee multiplier:', feeMult);

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⚓︎

61
62
63
64
65
66
67
68
69
70
    # Build the alias transaction
    transaction = facade.transaction_factory.create({
        'type': 'address_alias_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'namespace_id': namespace_id,
        'address': target_address,
        'alias_action': 'link'
    })
    transaction.fee = Amount(fee_mult * transaction.size)

61
62
63
64
65
66
67
68
69
70
    // Build the alias transaction
    const transaction = facade.transactionFactory.create({
        type: 'address_alias_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        namespaceId: namespaceId,
        address: targetAddress,
        aliasAction: 'link'
    });
    transaction.fee = new models.Amount(feeMult * transaction.size);

The address alias transaction specifies:

  • Type: Address alias transactions use the type address_alias_transaction_v1.

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

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

  • Address: The target address 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 an address, announce another address_alias_transaction_v1 transaction with the same namespace ID and address, but set the alias_action field to unlink.

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

Submitting the Transaction⚓︎

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
    # 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))

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

    # Announce transaction
    print('Announcing address alias transaction to /transactions')
    request = urllib.request.Request(
        f'{NODE_URL}/transactions',
        data=json_payload.encode(),
        headers={'Content-Type': 'application/json'},
        method='PUT'
    )
    with urllib.request.urlopen(request) as response:
        print(f'  Response: {response.read().decode()}')

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
    // 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 });

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

    // Announce transaction
    console.log('Announcing address alias transaction to /transactions');
    const announceResponse = await fetch(`${NODE_URL}/transactions`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: jsonPayload
    });
    console.log('  Response:', await announceResponse.text());

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

 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
    # Wait for confirmation
    print('Waiting for transaction confirmation...')
    for attempt in range(60):
        time.sleep(1)
        try:
            status_url = (
                f'{NODE_URL}/transactionStatus/{transaction_hash}')
            with urllib.request.urlopen(status_url) as response:
                status = json.loads(response.read().decode())
                print(f'  Transaction status: {status["group"]}')
            if status['group'] == 'confirmed':
                print('Address alias transaction confirmed in',
                    attempt, 'seconds')
                break
            if status['group'] == 'failed':
                raise Exception('Address alias transaction failed:',
                    status['code'])
        except urllib.error.HTTPError:
            print('  Transaction status: unknown')

 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
    // Wait for confirmation
    console.log('Waiting for transaction confirmation...');
    for (let attempt = 0; attempt < 60; attempt++) {
        await new Promise(resolve => setTimeout(resolve, 1000));

        try {
            const statusUrl =
                `${NODE_URL}/transactionStatus/${transactionHash}`;
            const statusResponse = await fetch(statusUrl);

            if (!statusResponse.ok) {
                console.log('  Transaction status: unknown');
                continue;
            }

            const status = await statusResponse.json();
            console.log('  Transaction status:', status.group);

            if (status.group === 'confirmed') {
                console.log('Address alias transaction confirmed in',
                    attempt, 'seconds');
                break;
            }

            if (status.group === 'failed') {
                throw new Error(
                    `Address alias transaction failed: ${status.code}`);
            }
        } catch (error) {
            if (error.message.includes('failed:')) {
                throw error;
            }
            console.log('  Transaction status: unknown');
        }
    }

The code then waits for the transaction to be confirmed by polling the /transactionStatus/{hash} GET endpoint until the status changes to confirmed.

Verifying the Alias⚓︎

113
114
115
116
117
118
119
120
121
122
123
124
125
126
    # 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 == 2:  # ADDRESS type
            aliased_address_hex = namespace_info['alias']['address']
            aliased_address = Address(bytes.fromhex(aliased_address_hex))
            print(f'  Linked address: {aliased_address}')

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
    // 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 (namespaceInfo.alias.type === 2) { // ADDRESS type
        const aliasedAddress = new models.Address(
            Uint8Array.from(Buffer.from(
                namespaceInfo.alias.address, 'hex')));
        console.log('  Linked address:', aliasedAddress.toString());
    }

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 (address) and the linked address, confirming the namespace now points to the specified address.

Using the Alias⚓︎

128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
    # Send a transfer using the alias instead of a raw address
    print(f'Using alias in transfer: {namespace_name}')

    # Encode the namespace ID as a recipient address (24 bytes)
    # Byte 0: network byte (Network Identifier | 0x01 to indicate alias)
    # Bytes 1-8: namespace ID in little-endian
    # Bytes 9-23: zero padding
    recipient_id = generate_namespace_path(namespace_name)[-1]
    recipient_address = Address(
        bytes([facade.network.identifier | 0x01]) +
        recipient_id.to_bytes(8, 'little') + bytes(15))

    transfer_tx = facade.transaction_factory.create({
        'type': 'transfer_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'recipient_address': recipient_address,
        'mosaics': [{
            'mosaic_id': generate_mosaic_alias_id('symbol.xym'),
            'amount': 1_000_000  # 1 XYM
        }]
    })
    print('Transfer transaction:')
    print(f'  Recipient address (alias): {recipient_address}')

148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
    // Send a transfer using the alias instead of a raw address
    console.log('Using alias in transfer:', namespaceName);

    // Encode the namespace ID as a recipient address (24 bytes)
    // Byte 0: network byte (Network Identifier | 0x01 to indicate alias)
    // Bytes 1-8: namespace ID in little-endian
    // Bytes 9-23: zero padding
    const recipientPath = generateNamespacePath(namespaceName);
    const recipientId = recipientPath[recipientPath.length - 1];
    const recipientBytes = new Uint8Array(24);
    recipientBytes[0] = facade.network.identifier | 0x01;
    // Convert namespace ID to little-endian bytes
    const recipientIdBytes = new Uint8Array(8);
    for (let i = 0; i < 8; i++) {
        recipientIdBytes[i] = Number(
            (recipientId >> BigInt(i * 8)) & 0xFFn);
    }
    recipientBytes.set(recipientIdBytes, 1);
    // Bytes 9-23 are already zero-filled
    const recipientAddress = new SymbolFacade.Address(recipientBytes);

    const transferTx = facade.transactionFactory.create({
        type: 'transfer_transaction_v1',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        recipientAddress: recipientAddress,
        mosaics: [{
            mosaicId: generateMosaicAliasId('symbol.xym'),
            amount: 1_000_000n // 1 XYM
        }]
    });
    console.log('Transfer transaction:');
    console.log('  Recipient address (alias):',
        recipientAddress.toString());

Once the namespace is linked to an address, the namespace can be used in place of the address in transactions. The code demonstrates creating a transfer transaction using the alias as the recipient address instead of the full hexadecimal address.

For simplicity, this example creates the transaction but does not announce it or wait for its confirmation.

To use a namespace as a recipient address, the namespace ID must be encoded into a 24-byte address. The namespace ID is obtained using the last component, as described in the previous section.

At this level, the SDK does not expose a dedicated helper for this operation, so the encoding is done manually with the following structure:

  • Byte 0: Network byte with alias flag set (network_identifier | 0x01)
  • Bytes 1-8: Namespace ID in little-endian byte order
  • Bytes 9-23: Zero padding

For more details on how to announce transfer transactions, see the Transfer Transaction tutorial.

Address Resolution Receipt

When the network processes a transaction that uses a namespace alias as a recipient address, it generates an Address Resolution Receipt. This receipt records the actual address 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 address can always be verified, even if the alias has since been updated.

Resolution receipts can be queried using the /statements/resolutions/address 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
Using node https://reference.symboltest.net:3001
Signer address: TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I
Namespace name: nsaddr_1770541301
Namespace ID: 12901002700615428842 (0xb309919a9089aaea)
Target address: TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI
Fetching current network time from /node/time
  Network time: 103291999249 ms since nemesis
Fetching recommended fees from /network/fees/transaction
  Fee multiplier: 100
Built transaction:
{
  "signature": "88D2148FB1938012BE845D221363768ECBE903032940F37E7227728FD655B73D02B1A78E03F23C25E8F6F1B746C61E8BE3623C5D5F1E5D57BEBBA9A7F56B6604",
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 1,
  "network": 152,
  "type": 16974,
  "fee": "16100",
  "deadline": "103299199249",
  "namespace_id": "12901002700615428842",
  "address": "98AD8BAAB80B1DC684542EC175259711AB2C41D2FE4DA9AD",
  "alias_action": 1
}
Transaction hash: 8312500644961DA08EF4899AE5160C2B810A8B506B74C58D3F4FCF257C309827
Announcing address alias transaction to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: confirmed
Address alias transaction confirmed in 17 seconds
Fetching namespace information from /namespaces/b309919a9089aaea
Alias information:
  Alias type: 2
  Linked address: TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI
Using alias in transfer: nsaddr_1770541301
Transfer transaction:
  Recipient address (alias): THVKVCMQTKIQTMYAAAAAAAAAAAAAAAAAAAAAAAA

Some highlights from the output:

  • Namespace and target (lines 3, 5): The namespace nsaddr_1770541301 is being linked to the target address TCWYXKVYBMO4NBCUF3AXKJMXCGVSYQOS7ZG2TLI.

  • 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 2 (address) and shows the linked address.

  • Using the alias (line 36): A transfer transaction is created using the alias as the recipient, demonstrating that it can be used in place of the full address.

    Different recipient address

    The recipient address differs from the target address because it is the encoded namespace ID, not the target address itself. The network resolves the alias to the linked address when processing the transaction.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Generate namespace ID
Build an address alias transaction
Verify the alias /namespaces/{namespaceId} GET
Query address resolution receipts /statements/resolutions/address GET