初級

モザイク情報の取得

Symbol上のすべてのモザイクには、供給量、可分性、振る舞いのフラグといったオンチェーンプロパティのセットがあります。

このチュートリアルでは、モザイクのプロパティと、それにリンクされているネームスペースのエイリアスを取得する方法を説明します。

前提条件

このチュートリアルはネットワークからデータを読み取るだけです。アカウントは必要ありません。

開始する前に、開発環境のセットアップを済ませておいてください。

完全なコード

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

Python JavaScript

import json
import os
import urllib.request

from symbolchain.sc import MosaicFlags

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

MOSAIC_ID = os.getenv('MOSAIC_ID', '72C0212E67A08BCE')
print(f'Mosaic ID: {MOSAIC_ID}')

try:
    # Fetch mosaic information
    mosaic_path = f'/mosaics/{MOSAIC_ID}'
    print(f'Fetching mosaic information from {mosaic_path}')
    with urllib.request.urlopen(f'{NODE_URL}{mosaic_path}') as response:
        response_json = json.loads(response.read().decode())
        mosaic = response_json['mosaic']
        print('Mosaic information:')
        print(f'  Mosaic ID: {mosaic["id"]}')
        print(f'  Supply: {mosaic["supply"]}')
        divisibility = mosaic['divisibility']
        print(f'  Divisibility: {divisibility}')
        flags = MosaicFlags(mosaic['flags'])
        print(f'  Flags: {flags.value} ({flags.name.lower()})')
        print(f'  Duration: {mosaic["duration"]}')
        print(f'  Start height: {mosaic["startHeight"]}')
        print(f'  Revision: {mosaic["revision"]}')

    # Display formatted supply
    supply = int(mosaic['supply'])
    whole = supply // (10 ** divisibility)
    fractional = supply % (10 ** divisibility)
    formatted = f'{whole}.{fractional:0{divisibility}d}'
    print(f'\nSupply in whole units: {formatted}')

    # Fetch namespace names linked to the mosaic
    print(f'\nFetching namespace names for mosaic {MOSAIC_ID}')
    request_body = json.dumps({'mosaicIds': [MOSAIC_ID]}).encode()
    request = urllib.request.Request(
        f'{NODE_URL}/namespaces/mosaic/names',
        data=request_body,
        headers={'Content-Type': 'application/json'}
    )
    with urllib.request.urlopen(request) as response:
        names_info = json.loads(response.read().decode())
        for entry in names_info['mosaicNames']:
            names = entry['names']
            if names:
                print(f'  Namespace aliases: {", ".join(names)}')
            else:
                print('  No namespace aliases linked')

except Exception as e:
    print(e)

Download source

import { models } from 'symbol-sdk/symbol';

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

const MOSAIC_ID = process.env.MOSAIC_ID || '72C0212E67A08BCE';
console.log('Mosaic ID:', MOSAIC_ID);

try {
    // Fetch mosaic information
    const mosaicPath = `/mosaics/${MOSAIC_ID}`;
    console.log('Fetching mosaic information from', mosaicPath);
    const mosaicResponse = await fetch(`${NODE_URL}${mosaicPath}`);
    if (!mosaicResponse.ok) {
        throw new Error(
            `HTTP error! status: ${mosaicResponse.status}`);
    }
    const mosaicJSON = await mosaicResponse.json();
    const mosaic = mosaicJSON.mosaic;
    console.log('Mosaic information:');
    console.log('  Mosaic ID:', mosaic.id);
    console.log('  Supply:', mosaic.supply);
    const divisibility = mosaic.divisibility;
    console.log('  Divisibility:', divisibility);
    const flags = new models.MosaicFlags(mosaic.flags);
    const flagNames = flags.toString()
        .replace(/MosaicFlags\./g, '').toLowerCase();
    console.log(`  Flags: ${mosaic.flags} (${flagNames})`);
    console.log('  Duration:', mosaic.duration);
    console.log('  Start height:', mosaic.startHeight);
    console.log('  Revision:', mosaic.revision);

    // Display formatted supply
    const supply = BigInt(mosaic.supply);
    const divisor = 10n ** BigInt(divisibility);
    const whole = supply / divisor;
    const fractional = supply % divisor;
    const fractionalStr = fractional.toString()
        .padStart(divisibility, '0');
    console.log(`\nSupply in whole units: ${whole}.${fractionalStr}`);

    // Fetch namespace names linked to the mosaic
    console.log(`\nFetching namespace names for mosaic ${MOSAIC_ID}`);
    const namesResponse = await fetch(
        `${NODE_URL}/namespaces/mosaic/names`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ mosaicIds: [MOSAIC_ID] })
        });
    const namesInfo = await namesResponse.json();
    for (const entry of namesInfo.mosaicNames) {
        if (entry.names.length > 0) {
            console.log('  Namespace aliases:', entry.names.join(', '));
        } else {
            console.log('  No namespace aliases linked');
        }
    }
} catch (e) {
    console.error(e.message);
}

Download source

このスニペットでは、 NODE_URL 環境変数を使用してSymbol APIノードを設定します。 値が指定されない場合は、デフォルトのテストネットノードが使用されます。

MOSAIC_ID 環境変数は、照会するモザイクを指定します。 設定されていない場合は、テストネット上のXYMのモザイク IDである 72C0212E67A08BCE がデフォルトで設定されます。

コード解説

モザイク情報の取得

Python JavaScript

    # Fetch mosaic information
    mosaic_path = f'/mosaics/{MOSAIC_ID}'
    print(f'Fetching mosaic information from {mosaic_path}')
    with urllib.request.urlopen(f'{NODE_URL}{mosaic_path}') as response:
        response_json = json.loads(response.read().decode())
        mosaic = response_json['mosaic']
        print('Mosaic information:')
        print(f'  Mosaic ID: {mosaic["id"]}')
        print(f'  Supply: {mosaic["supply"]}')
        divisibility = mosaic['divisibility']
        print(f'  Divisibility: {divisibility}')
        flags = MosaicFlags(mosaic['flags'])
        print(f'  Flags: {flags.value} ({flags.name.lower()})')
        print(f'  Duration: {mosaic["duration"]}')
        print(f'  Start height: {mosaic["startHeight"]}')
        print(f'  Revision: {mosaic["revision"]}')

    // Fetch mosaic information
    const mosaicPath = `/mosaics/${MOSAIC_ID}`;
    console.log('Fetching mosaic information from', mosaicPath);
    const mosaicResponse = await fetch(`${NODE_URL}${mosaicPath}`);
    if (!mosaicResponse.ok) {
        throw new Error(
            `HTTP error! status: ${mosaicResponse.status}`);
    }
    const mosaicJSON = await mosaicResponse.json();
    const mosaic = mosaicJSON.mosaic;
    console.log('Mosaic information:');
    console.log('  Mosaic ID:', mosaic.id);
    console.log('  Supply:', mosaic.supply);
    const divisibility = mosaic.divisibility;
    console.log('  Divisibility:', divisibility);
    const flags = new models.MosaicFlags(mosaic.flags);
    const flagNames = flags.toString()
        .replace(/MosaicFlags\./g, '').toLowerCase();
    console.log(`  Flags: ${mosaic.flags} (${flagNames})`);
    console.log('  Duration:', mosaic.duration);
    console.log('  Start height:', mosaic.startHeight);
    console.log('  Revision:', mosaic.revision);

/mosaics/{mosaicId} GET エンドポイントは、以下のモザイクの現在のプロパティを取得します。

• Supply (供給量): 現在流通している絶対（アトミック）単位の総数。 初期供給量と混同しないでください。
• Divisibility (可分性): モザイクがサポートする小数点以下の桁数。 例えば、XYMの可分性は 6 であり、1 XYMは1,000,000絶対単位に等しいことを意味します。
• Flags (フラグ): モザイクの振る舞いの制限をエンコードしたビットマスク。 各フラグは単一のビットを占有します： supply_mutable（供給量変更可能） (1)、 transferable（譲渡可能） (2)、 restrictable（制限可能） (4)、 および revokable（取り消し可能） (8)。 複数のフラグは加算的に組み合わされます。例えば、値が 6 の場合は transferable (2) + restrictable (4) を意味します。
• Duration (有効期限): モザイクが有効なままであるブロック数。 値が 0 の場合は、モザイクの有効期限が決して切れないことを意味します。
• Start height (開始ブロック高): モザイクが作成されたブロックの高さ。
• Revision (リビジョン): モザイク定義が変更されるたびに増加します。

供給量のフォーマット

Python JavaScript

    # Display formatted supply
    supply = int(mosaic['supply'])
    whole = supply // (10 ** divisibility)
    fractional = supply % (10 ** divisibility)
    formatted = f'{whole}.{fractional:0{divisibility}d}'
    print(f'\nSupply in whole units: {formatted}')

    // Display formatted supply
    const supply = BigInt(mosaic.supply);
    const divisor = 10n ** BigInt(divisibility);
    const whole = supply / divisor;
    const fractional = supply % divisor;
    const fractionalStr = fractional.toString()
        .padStart(divisibility, '0');
    console.log(`\nSupply in whole units: ${whole}.${fractionalStr}`);

APIによって返される供給量の値は、絶対量単位で表されます。 これを全体の単位に変換するために、コードはモザイクの可分性を使用して、供給量を整数部分と小数部分に分割します。

XYM（可分性 6 ）の場合、 8325447775994408 絶対単位の供給量は 8325447775.994408 全体単位に等しくなります。

ネームスペースエイリアスの取得

Python JavaScript

    # Fetch namespace names linked to the mosaic
    print(f'\nFetching namespace names for mosaic {MOSAIC_ID}')
    request_body = json.dumps({'mosaicIds': [MOSAIC_ID]}).encode()
    request = urllib.request.Request(
        f'{NODE_URL}/namespaces/mosaic/names',
        data=request_body,
        headers={'Content-Type': 'application/json'}
    )
    with urllib.request.urlopen(request) as response:
        names_info = json.loads(response.read().decode())
        for entry in names_info['mosaicNames']:
            names = entry['names']
            if names:
                print(f'  Namespace aliases: {", ".join(names)}')
            else:
                print('  No namespace aliases linked')

    // Fetch namespace names linked to the mosaic
    console.log(`\nFetching namespace names for mosaic ${MOSAIC_ID}`);
    const namesResponse = await fetch(
        `${NODE_URL}/namespaces/mosaic/names`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ mosaicIds: [MOSAIC_ID] })
        });
    const namesInfo = await namesResponse.json();
    for (const entry of namesInfo.mosaicNames) {
        if (entry.names.length > 0) {
            console.log('  Namespace aliases:', entry.names.join(', '));
        } else {
            console.log('  No namespace aliases linked');
        }
    }

モザイクは、人間が読めるネームスペースエイリアスにリンクさせることができます。 /namespaces/mosaic/names POST エンドポイントはモザイクIDを受け取り、現在それらにリンクされているネームスペース名を返します。

異なるネームスペースが同じモザイクにリンクしている場合、モザイクは複数のネームスペースエイリアスを持つことができます。 ネームスペースがリンクされていない場合、レスポンスはエイリアスが存在しないことを示します。

出力

以下に示す出力は、テストネット上のXYMモザイクを照会する、プログラムの典型的な実行結果に対応しています。

Using node https://reference.symboltest.net:3001
Mosaic ID: 72C0212E67A08BCE
Fetching mosaic information from /mosaics/72C0212E67A08BCE
Mosaic information:
  Mosaic ID: 72C0212E67A08BCE
  Supply: 8325492939035652
  Divisibility: 6
  Flags: 2 (transferable)
  Duration: 0
  Start height: 1
  Revision: 1

Supply in whole units: 8325492939.035652

Fetching namespace names for mosaic 72C0212E67A08BCE
  Namespace aliases: symbol.xym

出力の主なポイント:

• Mosaic ID (5行目): テストネット上のXYMモザイク識別子（ 72C0212E67A08BCE ）。
• Supply (6行目): 絶対単位での総供給量。
• Divisibility (7行目): 値 6 は、1 XYM = 1,000,000 (10⁶) 絶対単位であることを意味します。
• Flags (8行目): 値 2 は transferable（譲渡可能）に解決され、XYMがアカウント間で自由に送信できることを意味します。
• Duration (9行目): 値 0 は、XYMの有効期限が決して切れないことを意味します。
• Supply in whole units (13行目): モザイクの可分性を使用して、絶対単位から全体単位に変換された供給量。
• Namespace alias (16行目): モザイクは symbol.xym ネームスペースにリンクされています。

結論

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

ステップ	関連ドキュメント
モザイクプロパティの取得	/mosaics/{mosaicId} GET
ネームスペースエイリアスの取得

次のステップ

• モザイク定義の証明 を行い、データがチェーンに記録されているものと一致することを検証する
• アカウント残高の照会 を行い、アカウントがモザイクをどれだけ保持しているかを確認する