Skip to content

Adding Metadata to a Namespace⚓︎

Namespaces, like accounts and mosaics, can store metadata as key-value pairs.

This tutorial shows how to add metadata to a namespace, retrieve it from the network, and update existing values.

In this example, the pair description = My first namespace is attached to a namespace and then changed to Updated namespace:

%3NamespaceNamespacetestnamespaceMetadataKeyValuedescriptionMy first namespace

Prerequisites⚓︎

Before you start, make sure to:

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

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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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.Metadata import (
    metadata_generate_key,
    metadata_update_value
)
from symbolchain.symbol.Network import NetworkTimestamp
from symbolchain.symbol.IdGenerator import generate_namespace_id

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 response:
        print(f'  Response: {response.read().decode()}')


# Helper function to wait for transaction confirmation
def wait_for_confirmation(transaction_hash, label):
    print(f'Waiting for {label} confirmation...')
    for attempt in range(60):
        time.sleep(1)
        try:
            url = f'{NODE_URL}/transactionStatus/{transaction_hash}'
            with urllib.request.urlopen(url) as response:
                status = json.loads(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 Exception(f'{label} failed: {status["code"]}')
        except urllib.error.HTTPError:
            print('  Transaction status: unknown')
    raise Exception(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}')

# Get namespace name from environment or use default
NAMESPACE_NAME = os.getenv('NAMESPACE_NAME', 'testnamespace')
namespace_id = generate_namespace_id(NAMESPACE_NAME)
print(f'Namespace name: {NAMESPACE_NAME}')
print(f'Namespace ID: {namespace_id} ({hex(namespace_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_mult = response_json['medianFeeMultiplier']
        minimum_mult = response_json['minFeeMultiplier']
        fee_mult = max(median_mult, minimum_mult)
        print(f'  Fee multiplier: {fee_mult}')

    # --- ADDING NEW METADATA ---
    print('\n--- Adding new metadata ---')

    # Define metadata key and value
    key_string = f'description_{int(time.time())}'
    scoped_metadata_key = metadata_generate_key(key_string)
    metadata_value = 'My first namespace'.encode('utf8')

    # Create the embedded metadata transaction
    embedded_transaction = facade.transaction_factory.create_embedded({
        'type': 'namespace_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        'target_namespace_id': namespace_id,
        'scoped_metadata_key': scoped_metadata_key,
        # When creating new metadata, value_size_delta
        # equals the value length
        'value_size_delta': len(metadata_value),
        'value': metadata_value
    })
    print('Created embedded metadata transaction:')
    print(json.dumps(embedded_transaction.to_json(), indent=2))

    # Build the aggregate transaction
    embedded_transactions = [embedded_transaction]
    transaction = facade.transaction_factory.create({
        'type': 'aggregate_complete_transaction_v3',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'transactions_hash': facade.hash_embedded_transactions(
            embedded_transactions),
        'transactions': embedded_transactions
    })
    transaction.fee = Amount(fee_mult * transaction.size)

    # Sign and generate final payload
    signature = facade.sign_transaction(signer_key_pair, transaction)
    json_payload = facade.transaction_factory.attach_signature(
        transaction, signature)

    # Announce and wait for confirmation
    transaction_hash = facade.hash_transaction(transaction)
    print(f'Built aggregate transaction with hash: {transaction_hash}')
    announce_transaction(json_payload, 'aggregate transaction')
    wait_for_confirmation(transaction_hash, 'aggregate transaction')

    # --- MODIFYING EXISTING METADATA ---
    print('\n--- Modifying existing metadata ---')

    # Fetch current metadata value from network
    metadata_path = (
        f'/metadata?sourceAddress={signer_address}'
        f'&targetAddress={signer_address}'
        f'&scopedMetadataKey={scoped_metadata_key:016X}'
        f'&targetId={namespace_id:016X}'
        '&metadataType=2'
    )
    print(f'Fetching current metadata from {metadata_path}')
    with urllib.request.urlopen(
            f'{NODE_URL}{metadata_path}') as response:
        response_json = json.loads(response.read().decode())

    # Get the metadata entry
    if not response_json['data']:
        raise Exception('Metadata entry not found')
    metadata_entry = response_json['data'][0]['metadataEntry']
    current_value = bytes.fromhex(metadata_entry['value'])
    print(f'  Current value: {current_value.decode("utf8")}')

    # XOR the current and new values
    new_value = 'Updated namespace'.encode('utf8')
    update_value = metadata_update_value(current_value, new_value)

    # Create the update transaction with XOR'd value
    embedded_update = facade.transaction_factory.create_embedded({
        'type': 'namespace_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        'target_namespace_id': namespace_id,
        'scoped_metadata_key': scoped_metadata_key,
        # value_size_delta is the difference in length
        # (can be negative)
        'value_size_delta': len(new_value) - len(current_value),
        'value': update_value
    })
    print('Created embedded update transaction:')
    print(json.dumps(embedded_update.to_json(), indent=2))

    # Build the aggregate for the update
    embedded_transactions = [embedded_update]
    update_transaction = facade.transaction_factory.create({
        'type': 'aggregate_complete_transaction_v3',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'transactions_hash': facade.hash_embedded_transactions(
            embedded_transactions),
        'transactions': embedded_transactions
    })
    update_transaction.fee = Amount(fee_mult * update_transaction.size)

    # Sign and announce the update
    signature = facade.sign_transaction(
        signer_key_pair, update_transaction)
    json_payload = facade.transaction_factory.attach_signature(
        update_transaction, signature)

    # Announce and wait for confirmation
    update_hash = facade.hash_transaction(update_transaction)
    print(f'Built aggregate transaction with hash: {update_hash}')
    announce_transaction(json_payload, 'aggregate transaction')
    wait_for_confirmation(update_hash, 'aggregate 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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
import { PrivateKey } from 'symbol-sdk';
import {
    generateNamespaceId,
    metadataGenerateKey,
    metadataUpdateValue,
    models,
    NetworkTimestamp,
    SymbolFacade
} 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; attempt < 60; 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 (status.group === 'confirmed') {
                console.log(`${label} confirmed in`, attempt, 'seconds');
                return;
            }
            if (status.group === 'failed') {
                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());

// Get namespace name from environment or use default
const NAMESPACE_NAME = process.env.NAMESPACE_NAME || 'testnamespace';
const namespaceId = generateNamespaceId(NAMESPACE_NAME);
console.log('Namespace name:', NAMESPACE_NAME);
console.log('Namespace ID:',
    namespaceId.toString(), `(0x${namespaceId.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 timestamp = new NetworkTimestamp(
        timeJSON.communicationTimestamps.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);

    // --- ADDING NEW METADATA ---
    console.log('\n--- Adding new metadata ---');

    // Define metadata key and value
    const keyString = `description_${Date.now()}`;
    const scopedMetadataKey = metadataGenerateKey(keyString);
    const metadataValue = new TextEncoder().encode('My first namespace');

    // Create the embedded metadata transaction
    const embeddedTransaction = facade.transactionFactory
        .createEmbedded({
            type: 'namespace_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            targetNamespaceId: namespaceId,
            scopedMetadataKey,
            // When creating new metadata, valueSizeDelta
            // equals value length
            valueSizeDelta: metadataValue.length,
            value: metadataValue
        });
    console.log('Created embedded metadata transaction:');
    console.log(JSON.stringify(embeddedTransaction.toJson(), null, 2));

    // Build the aggregate transaction
    const embeddedTransactions = [embeddedTransaction];
    const transaction = facade.transactionFactory.create({
        type: 'aggregate_complete_transaction_v3',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        transactionsHash: facade.static.hashEmbeddedTransactions(
            embeddedTransactions),
        transactions: embeddedTransactions
    });
    transaction.fee = new models.Amount(feeMult * transaction.size);

    // Sign and generate final payload
    const signature = facade.signTransaction(signerKeyPair, transaction);
    const jsonPayload = facade.transactionFactory.static.attachSignature(
        transaction, signature);

    // Announce and wait for confirmation
    const transactionHash =
        facade.hashTransaction(transaction).toString();
    console.log(
        'Built aggregate transaction with hash:', transactionHash);
    await announceTransaction(jsonPayload, 'aggregate transaction');
    await waitForConfirmation(transactionHash, 'aggregate transaction');

    // --- MODIFYING EXISTING METADATA ---
    console.log('\n--- Modifying existing metadata ---');

    // Fetch current metadata value from network
    const scopedKeyHex = scopedMetadataKey.toString(16)
        .toUpperCase().padStart(16, '0');
    const namespaceIdHex = namespaceId.toString(16)
        .toUpperCase().padStart(16, '0');
    const metadataPath = `/metadata`
        + `?sourceAddress=${signerAddress}`
        + `&targetAddress=${signerAddress}`
        + `&scopedMetadataKey=${scopedKeyHex}`
        + `&targetId=${namespaceIdHex}`
        + '&metadataType=2';
    console.log('Fetching current metadata from', metadataPath);
    const metadataResponse = await fetch(`${NODE_URL}${metadataPath}`);
    const metadataJSON = await metadataResponse.json();

    // Get the metadata entry
    if (!metadataJSON.data.length) {
        throw new Error('Metadata entry not found');
    }
    const metadataEntry = metadataJSON.data[0].metadataEntry;
    const currentValue = Buffer.from(metadataEntry.value, 'hex');
    console.log('  Current value:', currentValue.toString('utf8'));

    // XOR the current and new values
    const newValue = new TextEncoder().encode('Updated namespace');
    const updateValue = metadataUpdateValue(currentValue, newValue);

    // Create the update transaction with XOR'd value
    const embeddedUpdate = facade.transactionFactory
        .createEmbedded({
            type: 'namespace_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            targetNamespaceId: namespaceId,
            scopedMetadataKey,
            // valueSizeDelta is the difference in length
            // (can be negative)
            valueSizeDelta: newValue.length - currentValue.length,
            value: updateValue
        });
    console.log('Created embedded update transaction:');
    console.log(JSON.stringify(embeddedUpdate.toJson(), null, 2));

    // Build the aggregate for the update
    const updateEmbedded = [embeddedUpdate];
    const updateTransaction = facade.transactionFactory.create({
        type: 'aggregate_complete_transaction_v3',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        transactionsHash: facade.static.hashEmbeddedTransactions(
            updateEmbedded),
        transactions: updateEmbedded
    });
    updateTransaction.fee = new models.Amount(
        feeMult * updateTransaction.size);

    // Sign and announce the update
    const updateSignature = facade.signTransaction(
        signerKeyPair, updateTransaction);
    const updatePayload = facade.transactionFactory.static
        .attachSignature(updateTransaction, updateSignature);

    // Announce and wait for confirmation
    const updateHash =
        facade.hashTransaction(updateTransaction).toString();
    console.log(
        'Built aggregate transaction with hash:', updateHash);
    await announceTransaction(updatePayload, 'aggregate transaction');
    await waitForConfirmation(updateHash, 'aggregate transaction');

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

Download source

Code Explanation⚓︎

This tutorial demonstrates adding new metadata to a namespace and then updating that metadata.

Setting Up the Account and Namespace⚓︎

54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
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}')

# Get namespace name from environment or use default
NAMESPACE_NAME = os.getenv('NAMESPACE_NAME', 'testnamespace')
namespace_id = generate_namespace_id(NAMESPACE_NAME)
print(f'Namespace name: {NAMESPACE_NAME}')
print(f'Namespace ID: {namespace_id} ({hex(namespace_id)})')

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
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());

// Get namespace name from environment or use default
const NAMESPACE_NAME = process.env.NAMESPACE_NAME || 'testnamespace';
const namespaceId = generateNamespaceId(NAMESPACE_NAME);
console.log('Namespace name:', NAMESPACE_NAME);
console.log('Namespace ID:',
    namespaceId.toString(), `(0x${namespaceId.toString(16)})`);

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.

The namespace name is read from the NAMESPACE_NAME environment variable, which defaults to testnamespace if not set. The namespace ID is computed from the name using .

Namespace must exist

The namespace must already be registered and owned by the signer account, or the transaction adding the metadata will be rejected.

See Registering a Root Namespace to learn how to do it.

Fetching Network Time and Fees⚓︎

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

70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
    // 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 timestamp = new NetworkTimestamp(
        timeJSON.communicationTimestamps.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.

Defining the Metadata⚓︎

Each namespace metadata entry is uniquely identified by:

  • The signer's address: the account adding the metadata
  • The target account's address: the namespace owner, whose signature is required
  • The target namespace ID

  • A scoped metadata key: a 64-bit value chosen by the metadata creator

    The SDK provides a helper function that generates this key from a human-readable string using SHA3-256 hashing. This approach makes keys more meaningful and reduces the chance of collisions.

94
95
96
97
    # Define metadata key and value
    key_string = f'description_{int(time.time())}'
    scoped_metadata_key = metadata_generate_key(key_string)
    metadata_value = 'My first namespace'.encode('utf8')

93
94
95
96
    // Define metadata key and value
    const keyString = `description_${Date.now()}`;
    const scopedMetadataKey = metadataGenerateKey(keyString);
    const metadataValue = new TextEncoder().encode('My first namespace');

In this example, the key is derived from the string description. For demonstration purposes, a timestamp is appended to the key string, so each time the code is executed a new entry is added to the namespace. In practice, you would use a fixed key that identifies the specific metadata entry you want to create or update.

The metadata value can be any sequence of up to 1024 bytes. In this example, the value is the string My first namespace encoded in UTF-8.

Multiple entries with the same key

The key is only one of the 4 parts that identify a metadata entry, so a change in any part produces a different entry.

For example, different accounts can use the same scoped metadata key on the same namespace without conflict, because the signer's address is different.

Each entry is independent and can only be updated by the account that originally created it.

Creating the Embedded Namespace Metadata Transaction⚓︎

 99
100
101
102
103
104
105
106
107
108
109
110
111
112
    # Create the embedded metadata transaction
    embedded_transaction = facade.transaction_factory.create_embedded({
        'type': 'namespace_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        'target_namespace_id': namespace_id,
        'scoped_metadata_key': scoped_metadata_key,
        # When creating new metadata, value_size_delta
        # equals the value length
        'value_size_delta': len(metadata_value),
        'value': metadata_value
    })
    print('Created embedded metadata transaction:')
    print(json.dumps(embedded_transaction.to_json(), indent=2))

 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
    // Create the embedded metadata transaction
    const embeddedTransaction = facade.transactionFactory
        .createEmbedded({
            type: 'namespace_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            targetNamespaceId: namespaceId,
            scopedMetadataKey,
            // When creating new metadata, valueSizeDelta
            // equals value length
            valueSizeDelta: metadataValue.length,
            value: metadataValue
        });
    console.log('Created embedded metadata transaction:');
    console.log(JSON.stringify(embeddedTransaction.toJson(), null, 2));

A namespace metadata transaction attaches a key-value pair to a namespace on the blockchain. The same transaction type handles both adding new metadata entries and updating existing ones.

Symbol requires these transactions to be inside an aggregate transaction that includes both the signer account and the namespace owner's signature. This prevents unwanted metadata from being attached to a namespace without its owner's permission.

In this tutorial, the signer is also the namespace owner so only one signature is needed. However, the transaction still needs to be inside an aggregate, so the code defines the namespace metadata transaction as an embedded transaction with these properties:

  • Type: Use namespace_metadata_transaction_v1.

  • Signer public key: The account creating the metadata entry.

  • Target address: The namespace owner's address. When the signer differs from the namespace owner, the owner must cosign the aggregate transaction.

  • Target namespace ID: The namespace to attach the metadata to.

  • Scoped metadata key: The 64-bit key used to identify this metadata entry.

  • Value size delta: When creating new metadata, set this to the byte length of the value. When updating existing metadata, set this to the difference between the new and current value lengths.

  • Value: The metadata content as bytes. When creating new metadata, provide the raw value. When updating, provide a computed value (explained in the Modifying Existing Metadata section).

Building the Aggregate Transaction⚓︎

114
115
116
117
118
119
120
121
122
123
124
    # Build the aggregate transaction
    embedded_transactions = [embedded_transaction]
    transaction = facade.transaction_factory.create({
        'type': 'aggregate_complete_transaction_v3',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'transactions_hash': facade.hash_embedded_transactions(
            embedded_transactions),
        'transactions': embedded_transactions
    })
    transaction.fee = Amount(fee_mult * transaction.size)

114
115
116
117
118
119
120
121
122
123
124
    // Build the aggregate transaction
    const embeddedTransactions = [embeddedTransaction];
    const transaction = facade.transactionFactory.create({
        type: 'aggregate_complete_transaction_v3',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        transactionsHash: facade.static.hashEmbeddedTransactions(
            embeddedTransactions),
        transactions: embeddedTransactions
    });
    transaction.fee = new models.Amount(feeMult * transaction.size);

The code adds the embedded namespace metadata transaction to an aggregate transaction.

Since the signer is the namespace owner, no cosignatures are required and the aggregate can be created as complete, allowing it to be signed and announced immediately.

Adding metadata by a different account

If the signer is different from the namespace owner, the owner must cosign the aggregate transaction to approve the metadata entry.

For details on collecting cosignatures on-chain, see the Bonded Aggregate tutorial.

Submitting the Aggregate Transaction⚓︎

126
127
128
129
130
131
132
133
134
135
    # Sign and generate final payload
    signature = facade.sign_transaction(signer_key_pair, transaction)
    json_payload = facade.transaction_factory.attach_signature(
        transaction, signature)

    # Announce and wait for confirmation
    transaction_hash = facade.hash_transaction(transaction)
    print(f'Built aggregate transaction with hash: {transaction_hash}')
    announce_transaction(json_payload, 'aggregate transaction')
    wait_for_confirmation(transaction_hash, 'aggregate transaction')

126
127
128
129
130
131
132
133
134
135
136
137
    // Sign and generate final payload
    const signature = facade.signTransaction(signerKeyPair, transaction);
    const jsonPayload = facade.transactionFactory.static.attachSignature(
        transaction, signature);

    // Announce and wait for confirmation
    const transactionHash =
        facade.hashTransaction(transaction).toString();
    console.log(
        'Built aggregate transaction with hash:', transactionHash);
    await announceTransaction(jsonPayload, 'aggregate transaction');
    await waitForConfirmation(transactionHash, 'aggregate transaction');

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

Retrieving Metadata⚓︎

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
    # Fetch current metadata value from network
    metadata_path = (
        f'/metadata?sourceAddress={signer_address}'
        f'&targetAddress={signer_address}'
        f'&scopedMetadataKey={scoped_metadata_key:016X}'
        f'&targetId={namespace_id:016X}'
        '&metadataType=2'
    )
    print(f'Fetching current metadata from {metadata_path}')
    with urllib.request.urlopen(
            f'{NODE_URL}{metadata_path}') as response:
        response_json = json.loads(response.read().decode())

    # Get the metadata entry
    if not response_json['data']:
        raise Exception('Metadata entry not found')
    metadata_entry = response_json['data'][0]['metadataEntry']
    current_value = bytes.fromhex(metadata_entry['value'])
    print(f'  Current value: {current_value.decode("utf8")}')

142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
    // Fetch current metadata value from network
    const scopedKeyHex = scopedMetadataKey.toString(16)
        .toUpperCase().padStart(16, '0');
    const namespaceIdHex = namespaceId.toString(16)
        .toUpperCase().padStart(16, '0');
    const metadataPath = `/metadata`
        + `?sourceAddress=${signerAddress}`
        + `&targetAddress=${signerAddress}`
        + `&scopedMetadataKey=${scopedKeyHex}`
        + `&targetId=${namespaceIdHex}`
        + '&metadataType=2';
    console.log('Fetching current metadata from', metadataPath);
    const metadataResponse = await fetch(`${NODE_URL}${metadataPath}`);
    const metadataJSON = await metadataResponse.json();

    // Get the metadata entry
    if (!metadataJSON.data.length) {
        throw new Error('Metadata entry not found');
    }
    const metadataEntry = metadataJSON.data[0].metadataEntry;
    const currentValue = Buffer.from(metadataEntry.value, 'hex');
    console.log('  Current value:', currentValue.toString('utf8'));

To retrieve the current value of a metadata entry, the code uses the /metadata GET endpoint with filters for sourceAddress, targetAddress, scopedMetadataKey, targetId (the namespace ID), and metadataType (2 for namespace metadata).

The endpoint returns the list of entries matching the filters, which in this case contains a single item.

Modifying Existing Metadata⚓︎

160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
    # XOR the current and new values
    new_value = 'Updated namespace'.encode('utf8')
    update_value = metadata_update_value(current_value, new_value)

    # Create the update transaction with XOR'd value
    embedded_update = facade.transaction_factory.create_embedded({
        'type': 'namespace_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        'target_namespace_id': namespace_id,
        'scoped_metadata_key': scoped_metadata_key,
        # value_size_delta is the difference in length
        # (can be negative)
        'value_size_delta': len(new_value) - len(current_value),
        'value': update_value
    })
    print('Created embedded update transaction:')
    print(json.dumps(embedded_update.to_json(), indent=2))

165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
    // XOR the current and new values
    const newValue = new TextEncoder().encode('Updated namespace');
    const updateValue = metadataUpdateValue(currentValue, newValue);

    // Create the update transaction with XOR'd value
    const embeddedUpdate = facade.transactionFactory
        .createEmbedded({
            type: 'namespace_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            targetNamespaceId: namespaceId,
            scopedMetadataKey,
            // valueSizeDelta is the difference in length
            // (can be negative)
            valueSizeDelta: newValue.length - currentValue.length,
            value: updateValue
        });
    console.log('Created embedded update transaction:');
    console.log(JSON.stringify(embeddedUpdate.toJson(), null, 2));

Updating an existing metadata entry requires the current value, retrieved from the network as previously shown.

To demonstrate updating metadata, the code changes the description from My first namespace to Updated namespace by creating another namespace_metadata_transaction_v1 transaction with the same scoped metadata key.

Modifying an existing metadata value differs from creating a new one in that the updated value must be defined in terms of the current value, using the following fields:

  • value_size_delta: The difference in length between the new and current values. In this example, the delta is -1 because Updated namespace (17 bytes) is one byte shorter than My first namespace (18 bytes).

  • value: The XOR'd bytes computed by comparing the current and new values byte-by-byte.

    The SDK provides a helper function that handles the XOR calculation. The XOR operation compares each byte: matching bytes become zero, and differing bytes capture the change.

Note that value_size_delta represents the difference in final value lengths (new vs current), not the length of the XOR'd bytes themselves.

Deleting a metadata entry

To delete a metadata entry, set value_size_delta to the negative of the current value length and provide the current value as value. The XOR produces an empty result, which removes the entry from the network.

As with the initial metadata creation, this metadata modification is wrapped in an aggregate transaction and then signed and announced.

179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
    # Build the aggregate for the update
    embedded_transactions = [embedded_update]
    update_transaction = facade.transaction_factory.create({
        'type': 'aggregate_complete_transaction_v3',
        'signer_public_key': signer_key_pair.public_key,
        'deadline': timestamp.add_hours(2).timestamp,
        'transactions_hash': facade.hash_embedded_transactions(
            embedded_transactions),
        'transactions': embedded_transactions
    })
    update_transaction.fee = Amount(fee_mult * update_transaction.size)

    # Sign and announce the update
    signature = facade.sign_transaction(
        signer_key_pair, update_transaction)
    json_payload = facade.transaction_factory.attach_signature(
        update_transaction, signature)

    # Announce and wait for confirmation
    update_hash = facade.hash_transaction(update_transaction)
    print(f'Built aggregate transaction with hash: {update_hash}')
    announce_transaction(json_payload, 'aggregate transaction')
    wait_for_confirmation(update_hash, 'aggregate transaction')

185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
    // Build the aggregate for the update
    const updateEmbedded = [embeddedUpdate];
    const updateTransaction = facade.transactionFactory.create({
        type: 'aggregate_complete_transaction_v3',
        signerPublicKey: signerKeyPair.publicKey.toString(),
        deadline: timestamp.addHours(2).timestamp,
        transactionsHash: facade.static.hashEmbeddedTransactions(
            updateEmbedded),
        transactions: updateEmbedded
    });
    updateTransaction.fee = new models.Amount(
        feeMult * updateTransaction.size);

    // Sign and announce the update
    const updateSignature = facade.signTransaction(
        signerKeyPair, updateTransaction);
    const updatePayload = facade.transactionFactory.static
        .attachSignature(updateTransaction, updateSignature);

    // Announce and wait for confirmation
    const updateHash =
        facade.hashTransaction(updateTransaction).toString();
    console.log(
        'Built aggregate transaction with hash:', updateHash);
    await announceTransaction(updatePayload, 'aggregate transaction');
    await waitForConfirmation(updateHash, 'aggregate transaction');

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_1768809538
Namespace ID: 13058489397075111804 (0xb53912eb77ddef7c)
Fetching current network time from /node/time
  Network time: 103372720119 ms since nemesis
Fetching recommended fees from /network/fees/transaction
  Fee multiplier: 100

--- Adding new metadata ---
Created embedded metadata transaction:
{
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 1,
  "network": 152,
  "type": 17220,
  "target_address": "988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE9",
  "scoped_metadata_key": "14762970678993106057",
  "target_namespace_id": "13058489397075111804",
  "value_size_delta": 18,
  "value": "4d79206669727374206e616d657370616365"
}
Built aggregate transaction with hash: C435EE593381F459F59F2651C900273AA4FE54B9D8C14812872B736F9FABEB16
Announcing aggregate transaction to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for aggregate transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: confirmed
aggregate transaction confirmed in 20 seconds

--- Modifying existing metadata ---
Fetching current metadata from /metadata?sourceAddress=TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I&targetAddress=TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I&scopedMetadataKey=CCE09B9D6EE43489&targetId=B53912EB77DDEF7C&metadataType=2
  Current value: My first namespace
Created embedded update transaction:
{
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 1,
  "network": 152,
  "type": 17220,
  "target_address": "988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE9",
  "scoped_metadata_key": "14762970678993106057",
  "target_namespace_id": "13058489397075111804",
  "value_size_delta": -1,
  "value": "180944071d1717544e0f0c08160311020665"
}
Built aggregate transaction with hash: 28D0C39811C1C4907DCB6C2DFB52B5B2207053DBBB14B52F807FC4B417D8D368
Announcing aggregate transaction to /transactions
  Response: {"message":"packet 9 was pushed to the network via /transactions"}
Waiting for aggregate transaction confirmation...
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: unconfirmed
  Transaction status: confirmed
aggregate transaction confirmed in 8 seconds

Key points in the output:

  • Line 3 (Namespace name): The namespace receiving the metadata.
  • Line 4 (Namespace ID): The computed namespace ID in decimal and hexadecimal formats.
  • Line 18 ("scoped_metadata_key"): The 64-bit key generated from the input string using SHA3-256 hashing.
  • Line 19 ("target_namespace_id"): The namespace receiving the metadata.
  • Line 20 ("value_size_delta": 18): When creating new metadata, this equals the byte length of the value ("My first namespace" = 18 bytes).
  • Line 23: The transaction hash for looking up the metadata creation in the explorer.
  • Line 37 (Current value: My first namespace): Retrieved from the network before updating.
  • Line 47 ("value_size_delta": -1): Negative because the new value ("Updated namespace" = 17 bytes) is shorter than the current value (18 bytes).
  • Line 48 ("value"): The XOR'd value computed from the current and new values, not the raw new value.
  • Line 50: The transaction hash for looking up the metadata update in the explorer.

The transaction hashes can be used to search for the transactions in the Symbol Testnet Explorer.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Define metadata key and value
Create a namespace metadata transaction
Retrieve metadata /metadata GET
Modify existing metadata