コンテンツにスキップ

ネームスペースへのメタデータの追加⚓︎

上級

ネームスペース は、アカウント や モザイク と同様に、キーと値のペアとして メタデータ を保存できます。

このチュートリアルでは、ネームスペースにメタデータを追加し、ネットワークから取得し、既存の値を更新する方法を説明します。

この例では、ペア description = My first namespace をネームスペースに関連付け、その後 Updated namespace に変更します。

NamespaceネームスペースtestnamespaceMetadataキー値descriptionMy first namespace

前提条件⚓︎

開始する前に、以下を確認してください。

さらに、トランザクションがどのようにアナウンスされ承認されるかを理解するために 転送トランザクション チュートリアルを、アグリゲートトランザクション の仕組みを理解するために コンプリートアグリゲートトランザクション チュートリアルを復習しておいてください。

完全なコード⚓︎

このチュートリアルの完全なコード一覧を以下に示します。 詳細な手順ごとの説明は次のセクションで行います。

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

from symbolchain.CryptoTypes import PrivateKey
from symbolchain.facade.SymbolFacade import SymbolFacade
from symbolchain.symbol.IdGenerator import generate_namespace_id
from symbolchain.symbol.Metadata import (
    metadata_generate_key,
    metadata_update_value
)

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}')

# 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} (0x{namespace_id:016X})')

try:
    # 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}')

    # --- 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.create_embedded_transaction_from_descriptor(
            {
                'type': 'namespace_metadata_transaction_v1',
                '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
            },
            signer_key_pair.public_key))
    print('Created embedded metadata transaction:')
    print(json.dumps(embedded_transaction.to_json(), indent=2))

    # Build the aggregate transaction
    embedded_transactions = [embedded_transaction]
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_complete_transaction_v3',
            'transactions_hash': facade.hash_embedded_transactions(
                embedded_transactions),
            'transactions': embedded_transactions
        },
        signer_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60)

    # 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 RuntimeError('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.create_embedded_transaction_from_descriptor(
        {
            'type': 'namespace_metadata_transaction_v1',
            '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
        },
        signer_key_pair.public_key)
    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.create_transaction_from_descriptor(
        {
            'type': 'aggregate_complete_transaction_v3',
            'transactions_hash': facade.hash_embedded_transactions(
                embedded_transactions),
            'transactions': embedded_transactions
        },
        signer_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60)

    # 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
import { PrivateKey } from 'symbol-sdk';
import {
    SymbolFacade,
    descriptors,
    generateNamespaceId,
    metadataGenerateKey,
    metadataUpdateValue,
    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); });
        const response = await fetch(
            `${NODE_URL}/transactionStatus/${transactionHash}`);
        if (!response.ok) {
            if (404 === response.status) {
                console.log('  Transaction status: unknown');
                continue;
            }
            throw new Error(`HTTP ${response.status}`);
        }
        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}`);
    }
    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);
const namespaceIdHex = namespaceId.toString(16)
    .toUpperCase().padStart(16, '0');
console.log('Namespace name:', NAMESPACE_NAME);
console.log('Namespace ID:',
    namespaceId.toString(), `(0x${namespaceIdHex})`);

try {
    // 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);

    // --- 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.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.NamespaceMetadataTransactionV1Descriptor(
                signerAddress,
                scopedMetadataKey,
                // When creating new metadata, valueSizeDelta
                // equals value length
                new models.NamespaceId(namespaceId),
                metadataValue.length,
                metadataValue),
            signerKeyPair.publicKey);
    console.log('Created embedded metadata transaction:');
    console.log(JSON.stringify(embeddedTransaction.toJson(), null, 2));

    // Build the aggregate transaction
    const embeddedTransactions = [embeddedTransaction];
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateCompleteTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(embeddedTransactions),
            embeddedTransactions,
            undefined),
        signerKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60);

    // 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 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.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.NamespaceMetadataTransactionV1Descriptor(
                signerAddress,
                scopedMetadataKey,
                new models.NamespaceId(namespaceId),
                // valueSizeDelta is the difference in length
                // (can be negative)
                newValue.length - currentValue.length,
                updateValue),
            signerKeyPair.publicKey);
    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.createTransactionFromTypedDescriptor(
        new descriptors.AggregateCompleteTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(updateEmbedded),
            updateEmbedded,
            undefined),
        signerKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60);

    // 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

  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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
//JAVA 21+
//DEPS org.symbol:symbol-sdk:3.3.1

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.StandardCharsets;
import java.util.List;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import org.symbol.sdk.CryptoTypes;
import org.symbol.sdk.facade.SymbolFacade;
import org.symbol.sdk.symbol.Address;
import org.symbol.sdk.symbol.IdGenerator;
import org.symbol.sdk.symbol.KeyPair;
import org.symbol.sdk.symbol.Metadata;
import org.symbol.sdk.symbol.SymbolTransactionFactory;
import org.symbol.sdk.symbol.descriptors.*;
import org.symbol.sdk.symbol.models.*;

public final class NamespaceMetadata {
    private static final ObjectMapper JSON_MAPPER = new ObjectMapper();

    private static final HttpClient HTTP_CLIENT =
        HttpClient.newHttpClient();

    private final String nodeUrl = System.getenv().getOrDefault(
        "NODE_URL", "https://reference.symboltest.net:3001");

    private final SymbolFacade facade = new SymbolFacade("testnet");

    // Helper function to announce a transaction
    private void announceTransaction(
        final String payload,
        final String label
    ) throws IOException, InterruptedException {
        System.out.printf("Announcing %s to /transactions%n", label);
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + "/transactions"))
            .header("Content-Type", "application/json")
            .PUT(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        final HttpResponse<String> response = HTTP_CLIENT.send(
            request, BodyHandlers.ofString());
        System.out.printf("  Response: %s%n", response.body());
    }

    // Helper function to wait for transaction confirmation
    private void waitForConfirmation(
        final String transactionHash,
        final String label
    ) throws IOException, InterruptedException {
        System.out.printf("Waiting for %s confirmation...%n", label);
        for (int attempt = 0; 60 > attempt; ++attempt) {
            Thread.sleep(1000);
            final String statusPath =
                "/transactionStatus/" + transactionHash;
            final HttpRequest statusRequest = HttpRequest.newBuilder(
                URI.create(nodeUrl + statusPath)).GET().build();
            final HttpResponse<String> statusResponse = HTTP_CLIENT
                .send(statusRequest, BodyHandlers.ofString());
            if (404 == statusResponse.statusCode()) {
                System.out.println("  Transaction status: unknown");
                continue;
            }
            if (2 != statusResponse.statusCode() / 100)
                throw new IOException(
                    "HTTP " + statusResponse.statusCode());

            final JsonNode status =
                JSON_MAPPER.readTree(statusResponse.body());
            final String group = status.get("group").asText();
            System.out.printf("  Transaction status: %s%n", group);
            if ("confirmed".equals(group)) {
                System.out.printf("%s confirmed in %d seconds%n",
                    label, attempt);
                return;
            }
            if ("failed".equals(group))
                throw new IOException(String.format("%s failed: %s",
                    label, status.get("code").asText()));
        }
        throw new IOException(String.format(
            "%s not confirmed after 60 seconds", label));
    }

    public static void main(final String[] args) {
        try {
            new NamespaceMetadata().run();
        } catch (final Exception ex) {
            System.out.println(null == ex.getMessage()
                ? ex.toString()
                : ex.getMessage());
        }
    }

    private void run() throws IOException, InterruptedException {
        System.out.printf("Using node %s%n", nodeUrl);


        final String signerPrivateKey = System.getenv().getOrDefault(
            "SIGNER_PRIVATE_KEY", "0".repeat(64));
        final KeyPair signerKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(signerPrivateKey));

        final Address signerAddress = facade.network.publicKeyToAddress(
            signerKeyPair.getPublicKey());
        System.out.printf("Signer address: %s%n", signerAddress);

        // Get namespace name from environment or use default
        final String namespaceName = System.getenv().getOrDefault(
            "NAMESPACE_NAME", "testnamespace");
        final long namespaceId = IdGenerator.generateNamespaceId(
            namespaceName);
        System.out.printf("Namespace name: %s%n", namespaceName);
        System.out.printf("Namespace ID: %s (0x%016X)%n",
            Long.toUnsignedString(namespaceId), namespaceId);

        // Fetch recommended fees
        final String feePath = "/network/fees/transaction";
        System.out.printf("Fetching recommended fees from %s%n", feePath);
        final JsonNode feeJson = getJson(feePath);
        final long feeMultiplier = Math.max(
            feeJson.get("medianFeeMultiplier").asLong(),
            feeJson.get("minFeeMultiplier").asLong());
        System.out.printf("  Fee multiplier: %d%n", feeMultiplier);

        // --- ADDING NEW METADATA ---
        System.out.println("\n--- Adding new metadata ---");

        // Define metadata key and value
        final String keyString = "description_"
            + System.currentTimeMillis();
        final long scopedMetadataKey = Metadata.generateKey(keyString);
        final byte[] metadataValue =
            "My first namespace".getBytes(StandardCharsets.UTF_8);

        // Create the embedded metadata transaction
        final EmbeddedTransaction embeddedTransaction =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new NamespaceMetadataTransactionV1Descriptor(
                    signerAddress,
                    scopedMetadataKey,
                    new NamespaceId(namespaceId),
                    // When creating new metadata, valueSizeDelta
                    // equals value length
                    metadataValue.length,
                    metadataValue),
                signerKeyPair.getPublicKey());
        System.out.println("Created embedded metadata transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(embeddedTransaction.toJson()));

        // Build the aggregate transaction
        final List<EmbeddedTransaction> embeddedTransactions =
            List.of(embeddedTransaction);
        final Transaction transaction =
            facade.createTransactionFromTypedDescriptor(
                new AggregateCompleteTransactionV3Descriptor(
                    SymbolFacade.hashEmbeddedTransactions(
                        embeddedTransactions),
                    embeddedTransactions,
                    null),
                signerKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60);

        // Sign and generate final payload
        final CryptoTypes.Signature signature = facade.signTransaction(
            signerKeyPair, transaction);
        String jsonPayload = SymbolTransactionFactory.attachSignature(
            transaction, signature);

        // Announce and wait for confirmation
        final String transactionHash =
            facade.hashTransaction(transaction).toString();
        System.out.printf(
            "Built aggregate transaction with hash: %s%n",
            transactionHash);
        announceTransaction(jsonPayload, "aggregate transaction");
        waitForConfirmation(transactionHash, "aggregate transaction");

        // --- MODIFYING EXISTING METADATA ---
        System.out.println("\n--- Modifying existing metadata ---");

        // Fetch current metadata value from network
        final String scopedKeyHex = "%016X".formatted(
            scopedMetadataKey);
        final String namespaceIdHex = "%016X".formatted(namespaceId);
        final String metadataPath = "/metadata"
            + "?sourceAddress=" + signerAddress
            + "&targetAddress=" + signerAddress
            + "&scopedMetadataKey=" + scopedKeyHex
            + "&targetId=" + namespaceIdHex
            + "&metadataType=2";
        System.out.printf("Fetching current metadata from %s%n",
            metadataPath);
        final JsonNode metadataJson = getJson(metadataPath);

        // Get the metadata entry
        if (metadataJson.get("data").isEmpty())
            throw new IOException("Metadata entry not found");
        final JsonNode metadataEntry = metadataJson.get("data").get(0)
            .get("metadataEntry");
        final byte[] currentValue = java.util.HexFormat.of()
            .parseHex(metadataEntry.get("value").asText());
        System.out.printf("  Current value: %s%n",
            new String(currentValue, StandardCharsets.UTF_8));

        // XOR the current and new values
        final byte[] newValue =
            "Updated namespace".getBytes(StandardCharsets.UTF_8);
        final byte[] updateValue = Metadata.updateValue(
            currentValue, newValue);

        // Create the update transaction with XOR'd value
        final EmbeddedTransaction embeddedUpdate =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new NamespaceMetadataTransactionV1Descriptor(
                    signerAddress,
                    scopedMetadataKey,
                    new NamespaceId(namespaceId),
                    // valueSizeDelta is the difference in length
                    // (can be negative)
                    newValue.length - currentValue.length,
                    updateValue),
                signerKeyPair.getPublicKey());
        System.out.println("Created embedded update transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(embeddedUpdate.toJson()));

        // Build the aggregate for the update
        final List<EmbeddedTransaction> updateEmbedded =
            List.of(embeddedUpdate);
        final Transaction updateTransaction =
            facade.createTransactionFromTypedDescriptor(
                new AggregateCompleteTransactionV3Descriptor(
                    SymbolFacade.hashEmbeddedTransactions(updateEmbedded),
                    updateEmbedded,
                    null),
                signerKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60);

        // Sign and announce the update
        final CryptoTypes.Signature updateSignature =
            facade.signTransaction(signerKeyPair, updateTransaction);
        jsonPayload = SymbolTransactionFactory.attachSignature(
            updateTransaction, updateSignature);

        // Announce and wait for confirmation
        final String updateHash =
            facade.hashTransaction(updateTransaction).toString();
        System.out.printf(
            "Built aggregate transaction with hash: %s%n", updateHash);
        announceTransaction(jsonPayload, "aggregate transaction");
        waitForConfirmation(updateHash, "aggregate transaction");

    }

    private JsonNode getJson(final String path)
        throws IOException, InterruptedException {
        final HttpRequest request = HttpRequest.newBuilder(
            URI.create(nodeUrl + path)).GET().build();
        final HttpResponse<String> response = HTTP_CLIENT.send(
            request, BodyHandlers.ofString());
        return JSON_MAPPER.readTree(response.body());
    }
}

Download source

コード解説⚓︎

このチュートリアルでは、ネームスペースに新しいメタデータを追加し、その後そのメタデータを更新する方法を実演します。

アカウントとネームスペースのセットアップ⚓︎

52
53
54
55
56
57
58
59
60
61
62
63
64
65
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} (0x{namespace_id:016X})')

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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);
const namespaceIdHex = namespaceId.toString(16)
    .toUpperCase().padStart(16, '0');
console.log('Namespace name:', NAMESPACE_NAME);
console.log('Namespace ID:',
    namespaceId.toString(), `(0x${namespaceIdHex})`);

106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
        final String signerPrivateKey = System.getenv().getOrDefault(
            "SIGNER_PRIVATE_KEY", "0".repeat(64));
        final KeyPair signerKeyPair = new KeyPair(
            new CryptoTypes.PrivateKey(signerPrivateKey));

        final Address signerAddress = facade.network.publicKeyToAddress(
            signerKeyPair.getPublicKey());
        System.out.printf("Signer address: %s%n", signerAddress);

        // Get namespace name from environment or use default
        final String namespaceName = System.getenv().getOrDefault(
            "NAMESPACE_NAME", "testnamespace");
        final long namespaceId = IdGenerator.generateNamespaceId(
            namespaceName);
        System.out.printf("Namespace name: %s%n", namespaceName);
        System.out.printf("Namespace ID: %s (0x%016X)%n",
            Long.toUnsignedString(namespaceId), namespaceId);

このスニペットは、署名者の 秘密鍵 を SIGNER_PRIVATE_KEY 環境変数から読み取ります。設定されていない場合はデフォルトのテストキーが使用されます。 署名者の アドレス は 公開鍵 から派生します。

ネームスペース名は NAMESPACE_NAME 環境変数から読み取られ、設定されていない場合は testnamespace がデフォルトとなります。 ネームスペース ID は、名前から を使用して計算されます。

メモ

ネームスペースはあらかじめ登録され、署名者アカウントによって所有されている必要があります。そうでない場合、メタデータを追加するトランザクションは拒否されます。

作成方法については ルートネームスペースの登録 を参照してください。

68
69
70
71
72
73
74
75
76
    # 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}')

72
73
74
75
76
77
78
79
80
    // 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);

124
125
126
127
128
129
130
131
        // Fetch recommended fees
        final String feePath = "/network/fees/transaction";
        System.out.printf("Fetching recommended fees from %s%n", feePath);
        final JsonNode feeJson = getJson(feePath);
        final long feeMultiplier = Math.max(
            feeJson.get("medianFeeMultiplier").asLong(),
            feeJson.get("minFeeMultiplier").asLong());
        System.out.printf("  Fee multiplier: %d%n", feeMultiplier);

転送トランザクション チュートリアルで説明されているプロセスに従い、推奨手数料を /network/fees/transaction GET から取得します。

メタデータの定義⚓︎

各ネームスペースメタデータエントリは、以下の4つによって一意に識別されます。

  • 署名者のアドレス: メタデータを追加するアカウント。
  • ターゲットアカウントのアドレス: ネームスペース所有者（このアカウントの署名が必要）。
  • ターゲットネームスペース ID

  • スコープ指定されたメタデータキー: メタデータ作成者によって選択される64ビットの値。

    SDKは、人間が読み取り可能な文字列からSHA3-256ハッシュを使用してこのキーを生成する ヘルパー関数を提供しています。 この方法により、キーがより意味のあるものになり、衝突の可能性が低減します。

81
82
83
84
    # 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')

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

136
137
138
139
140
141
        // Define metadata key and value
        final String keyString = "description_"
            + System.currentTimeMillis();
        final long scopedMetadataKey = Metadata.generateKey(keyString);
        final byte[] metadataValue =
            "My first namespace".getBytes(StandardCharsets.UTF_8);

この例では、キーは文字列 description から派生します。 デモンストレーションのためにキー文字列にはタイムスタンプが付加されているため、コードを実行するたびに新しいエントリがネームスペースに追加されます。 実際には、作成または更新したい特定のメタデータエントリを識別する固定キーを使用します。

メタデータの値は、最大1024バイトまでの任意のシーケンスにすることができます。 この例では、値はUTF-8でエンコードされた文字列 My first namespace です。

メモ

キーはメタデータエントリを識別する4つの要素のうちの1つにすぎないため、いずれかの要素が変更されると別のエントリになります。

例えば、署名者のアドレスが異なれば、異なるアカウントが同じネームスペースに対して同じスコープ指定メタデータキーを競合なく使用できます。

各エントリは独立しており、最初に作成したアカウントのみが更新できます。

埋め込みネームスペースメタデータトランザクションの作成⚓︎

 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
    # Create the embedded metadata transaction
    embedded_transaction = (
        facade.create_embedded_transaction_from_descriptor(
            {
                'type': 'namespace_metadata_transaction_v1',
                '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
            },
            signer_key_pair.public_key))
    print('Created embedded metadata transaction:')
    print(json.dumps(embedded_transaction.to_json(), indent=2))

 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
    // Create the embedded metadata transaction
    const embeddedTransaction =
        facade.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.NamespaceMetadataTransactionV1Descriptor(
                signerAddress,
                scopedMetadataKey,
                // When creating new metadata, valueSizeDelta
                // equals value length
                new models.NamespaceId(namespaceId),
                metadataValue.length,
                metadataValue),
            signerKeyPair.publicKey);
    console.log('Created embedded metadata transaction:');
    console.log(JSON.stringify(embeddedTransaction.toJson(), null, 2));

143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
        // Create the embedded metadata transaction
        final EmbeddedTransaction embeddedTransaction =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new NamespaceMetadataTransactionV1Descriptor(
                    signerAddress,
                    scopedMetadataKey,
                    new NamespaceId(namespaceId),
                    // When creating new metadata, valueSizeDelta
                    // equals value length
                    metadataValue.length,
                    metadataValue),
                signerKeyPair.getPublicKey());
        System.out.println("Created embedded metadata transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(embeddedTransaction.toJson()));

ネームスペースメタデータトランザクションは、ブロックチェーン上のネームスペースにキーと値のペアを関連付けます。 同じトランザクションタイプで、新しいメタデータエントリの追加と既存の更新の両方を処理します。

Symbolでは、これらのトランザクションを署名者アカウントとネームスペース所有者の両方の署名を含む アグリゲートトランザクション 内に含める必要があります。 これにより、所有者の許可なく不要なメタデータがネームスペースに関連付けられるのを防ぎます。

このチュートリアルでは、署名者がネームスペース所有者でもあるため、必要な署名は1つだけです。 しかし、トランザクションは依然としてアグリゲート内にある必要があるため、コードではネームスペースメタデータトランザクションを 埋め込みトランザクション として定義します。 トランザクションの記述子には以下を指定します。

  • Type: NamespaceMetadataTransactionV1 を使用します。

  • ターゲットアドレス: ネームスペース所有者のアドレス。 署名者がネームスペース所有者と異なる場合、所有者はアグリゲートトランザクションに 連署 する必要があります。

  • ターゲットネームスペース ID: メタデータを関連付けるネームスペース。

  • スコープ指定されたメタデータキー: このメタデータエントリを識別するために使用される64ビットのキー。

  • 値のサイズの差分 (Value size delta): 新しいメタデータを作成する場合は、値のバイト長に設定します。 既存のメタデータを更新する場合は、新しい値と現在の値の長さの差分に設定します。

  • 値: バイト形式のメタデータ内容。 新しいメタデータを作成する場合は、生の値を指定します。 更新する場合は、計算された値を指定します（既存のメタデータの変更 セクションで説明します）。

署名者の公開鍵は に別の引数として渡します。

アグリゲートトランザクションの構築⚓︎

103
104
105
106
107
108
109
110
111
112
113
114
    # Build the aggregate transaction
    embedded_transactions = [embedded_transaction]
    transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_complete_transaction_v3',
            'transactions_hash': facade.hash_embedded_transactions(
                embedded_transactions),
            'transactions': embedded_transactions
        },
        signer_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60)

105
106
107
108
109
110
111
112
113
114
    // Build the aggregate transaction
    const embeddedTransactions = [embeddedTransaction];
    const transaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateCompleteTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(embeddedTransactions),
            embeddedTransactions,
            undefined),
        signerKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60);

159
160
161
162
163
164
165
166
167
168
169
170
171
        // Build the aggregate transaction
        final List<EmbeddedTransaction> embeddedTransactions =
            List.of(embeddedTransaction);
        final Transaction transaction =
            facade.createTransactionFromTypedDescriptor(
                new AggregateCompleteTransactionV3Descriptor(
                    SymbolFacade.hashEmbeddedTransactions(
                        embeddedTransactions),
                    embeddedTransactions,
                    null),
                signerKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60);

埋め込みトランザクション を アグリゲートトランザクション に追加します。

署名者がネームスペースの所有者であるため、 連署 は不要であり、アグリゲートは コンプリート として作成できるため、すぐに署名してアナウンスできます。

メモ

署名者がネームスペース所有者と異なる場合、メタデータエントリを承認するために所有者がアグリゲートトランザクションに連署する必要があります。

オンチェーンで連署を収集する詳細については、ボンデッドアグリゲートトランザクション チュートリアルを参照してください。

アグリゲートトランザクションの送信⚓︎

116
117
118
119
120
121
122
123
124
125
    # 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')

116
117
118
119
120
121
122
123
124
125
126
127
    // 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');

173
174
175
176
177
178
179
180
181
182
183
184
185
186
        // Sign and generate final payload
        final CryptoTypes.Signature signature = facade.signTransaction(
            signerKeyPair, transaction);
        String jsonPayload = SymbolTransactionFactory.attachSignature(
            transaction, signature);

        // Announce and wait for confirmation
        final String transactionHash =
            facade.hashTransaction(transaction).toString();
        System.out.printf(
            "Built aggregate transaction with hash: %s%n",
            transactionHash);
        announceTransaction(jsonPayload, "aggregate transaction");
        waitForConfirmation(transactionHash, "aggregate transaction");

アグリゲートトランザクションは、コンプリートアグリゲートトランザクション チュートリアルと同じプロセスに従って署名され、アナウンスされます。

メタデータの取得⚓︎

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
    # 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 RuntimeError('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")}')

132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
    // Fetch current metadata value from network
    const scopedKeyHex = scopedMetadataKey.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'));

191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
        // Fetch current metadata value from network
        final String scopedKeyHex = "%016X".formatted(
            scopedMetadataKey);
        final String namespaceIdHex = "%016X".formatted(namespaceId);
        final String metadataPath = "/metadata"
            + "?sourceAddress=" + signerAddress
            + "&targetAddress=" + signerAddress
            + "&scopedMetadataKey=" + scopedKeyHex
            + "&targetId=" + namespaceIdHex
            + "&metadataType=2";
        System.out.printf("Fetching current metadata from %s%n",
            metadataPath);
        final JsonNode metadataJson = getJson(metadataPath);

        // Get the metadata entry
        if (metadataJson.get("data").isEmpty())
            throw new IOException("Metadata entry not found");
        final JsonNode metadataEntry = metadataJson.get("data").get(0)
            .get("metadataEntry");
        final byte[] currentValue = java.util.HexFormat.of()
            .parseHex(metadataEntry.get("value").asText());
        System.out.printf("  Current value: %s%n",
            new String(currentValue, StandardCharsets.UTF_8));

メタデータエントリの現在の値を取得するために、コードは sourceAddress、targetAddress、scopedMetadataKey、targetId（ネームスペース ID）、および metadataType（ネームスペースメタデータの場合は 2）のフィルタを指定して /metadata GET エンドポイントを使用します。

エンドポイントはフィルタに一致するエントリのリストを返します。この例では単一のアイテムが含まれます。

既存のメタデータの変更⚓︎

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
    # 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.create_embedded_transaction_from_descriptor(
        {
            'type': 'namespace_metadata_transaction_v1',
            '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
        },
        signer_key_pair.public_key)
    print('Created embedded update transaction:')
    print(json.dumps(embedded_update.to_json(), indent=2))

152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
    // 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.createEmbeddedTransactionFromTypedDescriptor(
            new descriptors.NamespaceMetadataTransactionV1Descriptor(
                signerAddress,
                scopedMetadataKey,
                new models.NamespaceId(namespaceId),
                // valueSizeDelta is the difference in length
                // (can be negative)
                newValue.length - currentValue.length,
                updateValue),
            signerKeyPair.publicKey);
    console.log('Created embedded update transaction:');
    console.log(JSON.stringify(embeddedUpdate.toJson(), null, 2));

215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
        // XOR the current and new values
        final byte[] newValue =
            "Updated namespace".getBytes(StandardCharsets.UTF_8);
        final byte[] updateValue = Metadata.updateValue(
            currentValue, newValue);

        // Create the update transaction with XOR'd value
        final EmbeddedTransaction embeddedUpdate =
            facade.createEmbeddedTransactionFromTypedDescriptor(
                new NamespaceMetadataTransactionV1Descriptor(
                    signerAddress,
                    scopedMetadataKey,
                    new NamespaceId(namespaceId),
                    // valueSizeDelta is the difference in length
                    // (can be negative)
                    newValue.length - currentValue.length,
                    updateValue),
                signerKeyPair.getPublicKey());
        System.out.println("Created embedded update transaction:");
        System.out.println(JSON_MAPPER.writerWithDefaultPrettyPrinter()
            .writeValueAsString(embeddedUpdate.toJson()));

既存のメタデータエントリを更新するには、前述のようにネットワークから取得した現在の値が必要です。

メタデータの更新を実演するために、コードは同じスコープ指定メタデータキーを使用して別の NamespaceMetadataTransactionV1 トランザクションを作成し、説明を My first namespace から Updated namespace に変更します。

既存のメタデータ値を変更することは、新しい値が現在の値を基準として以下のフィールドを使用して定義される必要があるという点で、新規作成とは異なります。

  • value_size_delta: 新しい値と現在の値の長さの差。 この例では、Updated namespace（17バイト）は My first namespace（18バイト）より1バイト短いため、デルタは -1 になります。

  • value: 現在の値と新しい値をバイトごとに比較して計算された XOR されたバイト。

    SDKは XOR 計算を処理する ヘルパー関数を提供しています。 XOR 操作は各バイトを比較します。一致するバイトはゼロになり、異なるバイトが変更箇所を捉えます。

value_size_delta は、XOR されたバイト自体の長さではなく、最終的な値の長さの差（新 vs 旧）を表すことに注意してください。

ヒント

メタデータエントリを削除するには、value_size_delta を現在の値の長さの負の値に設定し、現在の値を value として提供します。XOR によって空の結果が生成され、ネットワークからエントリが削除されます。

最初のメタデータ作成 と同様に、このメタデータの変更はアグリゲートトランザクションにラップされ、署名してアナウンスされます。

170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
    # Build the aggregate for the update
    embedded_transactions = [embedded_update]
    update_transaction = facade.create_transaction_from_descriptor(
        {
            'type': 'aggregate_complete_transaction_v3',
            'transactions_hash': facade.hash_embedded_transactions(
                embedded_transactions),
            'transactions': embedded_transactions
        },
        signer_key_pair.public_key,
        fee_multiplier,
        2 * 60 * 60)

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

171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
    // Build the aggregate for the update
    const updateEmbedded = [embeddedUpdate];
    const updateTransaction = facade.createTransactionFromTypedDescriptor(
        new descriptors.AggregateCompleteTransactionV3Descriptor(
            facade.static.hashEmbeddedTransactions(updateEmbedded),
            updateEmbedded,
            undefined),
        signerKeyPair.publicKey,
        feeMultiplier,
        2 * 60 * 60);

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

237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
        // Build the aggregate for the update
        final List<EmbeddedTransaction> updateEmbedded =
            List.of(embeddedUpdate);
        final Transaction updateTransaction =
            facade.createTransactionFromTypedDescriptor(
                new AggregateCompleteTransactionV3Descriptor(
                    SymbolFacade.hashEmbeddedTransactions(updateEmbedded),
                    updateEmbedded,
                    null),
                signerKeyPair.getPublicKey(),
                feeMultiplier,
                2 * 60 * 60);

        // Sign and announce the update
        final CryptoTypes.Signature updateSignature =
            facade.signTransaction(signerKeyPair, updateTransaction);
        jsonPayload = SymbolTransactionFactory.attachSignature(
            updateTransaction, updateSignature);

        // Announce and wait for confirmation
        final String updateHash =
            facade.hashTransaction(updateTransaction).toString();
        System.out.printf(
            "Built aggregate transaction with hash: %s%n", updateHash);
        announceTransaction(jsonPayload, "aggregate transaction");
        waitForConfirmation(updateHash, "aggregate transaction");

出力⚓︎

以下に示す出力は、プログラムの典型的な実行結果に対応しています。

 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
Using node https://reference.symboltest.net:3001
Signer address: TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I
Namespace name: ns_1768809538
Namespace ID: 13058489397075111804 (0xB53912EB77DDEF7C)
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

出力の主なポイント:

  • 3行目 (Namespace name): メタデータを受け取るネームスペース。
  • 4行目 (Namespace ID): 計算されたネームスペース ID（10進数および16進数形式）。
  • 16行目 ("scoped_metadata_key"): 入力文字列からSHA3-256ハッシュを使用して生成された64ビットのキー。
  • 17行目 ("target_namespace_id"): メタデータを受け取るネームスペース。
  • 18行目 ("value_size_delta": 18): 新しいメタデータを作成する場合、これは値のバイト長に等しくなります（"My first namespace" = 18バイト）。
  • 21行目: エクスプローラーでメタデータの作成を確認するためのトランザクション ハッシュ。
  • 35行目 (Current value: My first namespace): 更新前にネットワークから取得された値。
  • 45行目 ("value_size_delta": -1): 新しい値（"Updated namespace" = 17バイト）が現在の値（18バイト）より短いため、負の値になります。
  • 46行目 ("value"): 生の新しい値ではなく、現在の値と新しい値から計算された XOR 値。
  • 48行目: エクスプローラーでメタデータの更新を確認するためのトランザクションハッシュ。

トランザクションハッシュを使用して、Symbol Testnet Explorer でトランザクションを検索できます。

結論⚓︎

このチュートリアルでは、以下の方法を説明しました。

ステップ 関連ドキュメント
メタデータのキーと値の定義
ネームスペースメタデータトランザクションの作成 , NamespaceMetadataTransactionV1
メタデータの取得 /metadata GET
既存のメタデータの変更