コンテンツにスキップ
上級

アカウントへのメタデータの追加⚓︎

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

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

この例では、キーペア username = alice をアカウントに関連付け、その後 bob に変更します。

%3AccountアカウントTCHBDE...HHE32IMetadataキー値usernamealice

前提条件⚓︎

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

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

完全なコード⚓︎

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

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

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

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'username_{int(time.time())}'
    scoped_metadata_key = metadata_generate_key(key_string)
    metadata_value = 'alice'.encode('utf8')

    # Create the embedded metadata transaction
    embedded_transaction = facade.transaction_factory.create_embedded({
        'type': 'account_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        '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}'
        '&metadataType=0'
    )
    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 = 'bob'.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': 'account_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        '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
    })

    # 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
import { PrivateKey } from 'symbol-sdk';
import {
    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());

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 = `username_${Date.now()}`;
    const scopedMetadataKey = metadataGenerateKey(keyString);
    const metadataValue = new TextEncoder().encode('alice');

    // Create the embedded metadata transaction
    const embeddedTransaction = facade.transactionFactory
        .createEmbedded({
            type: 'account_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            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 metadataPath = `/metadata?sourceAddress=${signerAddress}`
        + `&targetAddress=${signerAddress}`
        + `&scopedMetadataKey=${scopedKeyHex}`
        + '&metadataType=0';
    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('bob');
    const updateValue = metadataUpdateValue(currentValue, newValue);

    // Create the update transaction with XOR'd value
    const embeddedUpdate = facade.transactionFactory
        .createEmbedded({
            type: 'account_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            scopedMetadataKey,
            // valueSizeDelta is the difference in length
            // (can be negative)
            valueSizeDelta: newValue.length - currentValue.length,
            value: updateValue
        });

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

コード解説⚓︎

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

アカウントのセットアップ⚓︎

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

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

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

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

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

このチュートリアルでは、署名者が自身のアカウントにメタデータを追加します。 別のアカウントにメタデータを追加する場合は、対象となるアカウントがトランザクションに連署する必要があります。

ネットワーク時間と手数料の取得⚓︎

64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
    # 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}')

62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
    // 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);

転送トランザクション チュートリアルで説明されているプロセスに従い、ネットワーク時間と推奨手数料をそれぞれ /node/time GET および /network/fees/transaction GET から取得します。

メタデータの定義⚓︎

各アカウントメタデータエントリは、以下の3つによって一意に識別されます。

  • 署名者のアドレス: メタデータを追加するアカウント
  • ターゲットアカウントのアドレス: メタデータを付与するアカウント（このアカウントの署名が必要）

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

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

87
88
89
90
    # Define metadata key and value
    key_string = f'username_{int(time.time())}'
    scoped_metadata_key = metadata_generate_key(key_string)
    metadata_value = 'alice'.encode('utf8')

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

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

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

同じキーを持つ複数のエントリ

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

例えば、署名者のアドレスが異なれば、別のアカウントが同じターゲットアカウントに対して同じメタデータキーを競合なく使用できます。

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

埋め込みアカウントメタデータトランザクションの作成⚓︎

 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
    # Create the embedded metadata transaction
    embedded_transaction = facade.transaction_factory.create_embedded({
        'type': 'account_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        '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))

 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
    // Create the embedded metadata transaction
    const embeddedTransaction = facade.transactionFactory
        .createEmbedded({
            type: 'account_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            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));

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

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

アカウント所有者によってトランザクションが開始される場合でも、トランザクション形式を統一するためにアグリゲートが必要です。 このため、コードではアカウントメタデータトランザクションを 埋め込みトランザクション として定義します。

このトランザクションでは以下を指定します。

  • Type: account_metadata_transaction_v1 を使用します。

  • 署名者の公開鍵: メタデータエントリを作成するアカウント。 この例では、このアカウントがメタデータを受け取るアカウントでもあります。

  • ターゲットアドレス: メタデータを関連付けるアカウント。 ターゲットが署名者と異なる場合、ターゲットアカウントはアグリゲートトランザクションに連署する必要があります。

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

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

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

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

106
107
108
109
110
111
112
113
114
115
116
    # 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)

105
106
107
108
109
110
111
112
113
114
115
    // 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);

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

署名者が自身のアカウントを変更しているため、連署 は不要であり、アグリゲートは コンプリート として作成できるため、すぐに署名してアナウンスできます。

別のアカウントへのメタデータの追加

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

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

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

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

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

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

メタデータの取得⚓︎

132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
    # Fetch current metadata value from network
    metadata_path = (
        f'/metadata?sourceAddress={signer_address}'
        f'&targetAddress={signer_address}'
        f'&scopedMetadataKey={scoped_metadata_key:016X}'
        '&metadataType=0'
    )
    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")}')

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}`
        + '&metadataType=0';
    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'));

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

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

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

151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
    # XOR the current and new values
    new_value = 'bob'.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': 'account_metadata_transaction_v1',
        'signer_public_key': signer_key_pair.public_key,
        'target_address': signer_address,
        '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
    })

152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
    // XOR the current and new values
    const newValue = new TextEncoder().encode('bob');
    const updateValue = metadataUpdateValue(currentValue, newValue);

    // Create the update transaction with XOR'd value
    const embeddedUpdate = facade.transactionFactory
        .createEmbedded({
            type: 'account_metadata_transaction_v1',
            signerPublicKey: signerKeyPair.publicKey.toString(),
            targetAddress: signerAddress.toString(),
            scopedMetadataKey,
            // valueSizeDelta is the difference in length
            // (can be negative)
            valueSizeDelta: newValue.length - currentValue.length,
            value: updateValue
        });

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

メタデータの更新を実演するために、コードは同じメタデータキーを使用して別の account_metadata_transaction_v1 トランザクションを作成し、ユーザー名を alice から bob に変更します。

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

  • value_size_delta: 新しい値と現在の値の長さの差。 この例では、bob（3バイト）は alice（5バイト）より2バイト短いため、デルタは -2 になります。

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

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

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

メタデータエントリの削除

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

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

167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
    # 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')

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

出力⚓︎

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

 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
Using node https://reference.symboltest.net:3001
Signer address: TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I
Fetching current network time from /node/time
  Network time: 98406073135 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": 16708,
  "target_address": "988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE9",
  "scoped_metadata_key": "16705141506538718608",
  "value_size_delta": 5,
  "value": "616c696365"
}
Built aggregate transaction with hash: 976C555DD4FEEA2B48088457AC445A41FA28E13C88B12823844F5EC399B97144
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: confirmed
aggregate transaction confirmed in 11 seconds

--- Modifying existing metadata ---
Fetching current metadata from /metadata?sourceAddress=TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I&targetAddress=TCHBDENCLKEBILBPWP3JPB2XNY64OE7PYHHE32I&scopedMetadataKey=E7F71DA42B54B310&metadataType=0
  Current value: alice
Created embedded update transaction:
{
  "signer_public_key": "3B6A27BCCEB6A42D62A3A8D02A6F0D73653215771DE243A63AC048A18B59DA29",
  "version": 1,
  "network": 152,
  "type": 16708,
  "target_address": "988E1191A25A88142C2FB3F69787576E3DC713EFC1CE4DE9",
  "scoped_metadata_key": "16705141506538718608",
  "value_size_delta": -2,
  "value": "03030b6365"
}
Built aggregate transaction with hash: AA58533BB20A54FE0CF3AD44EC4CEA05C1BC6A47D817850DBB072D0CB254116F
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: confirmed
aggregate transaction confirmed in 31 seconds

出力の主なポイント:

  • 16行目 ("scoped_metadata_key"): 入力文字列からSHA3-256ハッシュを使用して生成された64ビットのキー。
  • 17行目 ("value_size_delta": 5): 新しいメタデータを作成する場合、これは値のバイト長に等しくなります（"alice" = 5バイト）。
  • 18行目 ("value": "616c696365"): 16進数でエンコードされたメタデータの値（UTF-8の "alice"）。
  • 20行目: エクスプローラーでメタデータの作成を確認するためのトランザクション ハッシュ。
  • 31行目 (Current value: alice): 更新前にネットワークから取得された値。
  • 40行目 ("value_size_delta": -2): 新しい値（"bob" = 3バイト）が現在の値（5バイト）より短いため、負の値になります。差は -2 です。
  • 41行目 ("value": "03030b6365"): 生の新しい値ではなく、現在の値と新しい値から計算された XOR 値。
  • 43行目: エクスプローラーでメタデータの更新を確認するためのトランザクションハッシュ。

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

結論⚓︎

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

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