アセットの取得 | Token Metadata

アセットの様々なオンチェーンアカウントを作成およびミントする方法がわかったので、それらを取得する方法を学びましょう。

デジタルアセット

前のページで述べたように、アセット（Fungibleかどうかに関わらず）は複数のオンチェーンアカウントを作成する必要があります。アセットのトークン標準によっては、一部のアカウントが必要でない場合があります。これらのアカウントの概要は次のとおりです：

Mintアカウント（SPL Tokenプログラムから）：基盤となるSPLトークンの主要なプロパティを定義します。他のすべてのアカウントがこれから派生するため、これは任意のアセットへのエントリポイントです。
Metadataアカウント：基盤となるSPLトークンに追加のデータと機能を提供します。
Master EditionまたはEditionアカウント（非Fungibleのみ）：オリジナルNFTの複数のコピーを印刷することを可能にします。NFTがエディションの印刷を許可しない場合でも、Master Editionアカウントは、その非Fungibility性を保証するためにMintアカウントのMint authorityおよびFreeze authorityとして使用されるため、作成されます。

アセットの取得を簡単にするために、私たちのSDKは、アセットのすべての関連アカウントを一度に取得することを可能にする一連のヘルパーメソッドを提供しています。これらすべてのアカウントを保存するデータ型をデジタルアセットと呼びます。次のサブセクションでは、デジタルアセットを取得する様々な方法について説明します。

デジタルアセットの定義

import { PublicKey } from '@metaplex-foundation/umi'
import { Mint } from '@metaplex-foundation/mpl-toolbox'
import {
  Metadata,
  MasterEdition,
  Edition,
} from '@metaplex-foundation/mpl-token-metadata'

export type DigitalAsset = {
  publicKey: PublicKey
  mint: Mint
  metadata: Metadata
  edition?:
    | ({ isOriginal: true } & MasterEdition)
    | ({ isOriginal: false } & Edition)
}

Mintによる取得

このヘルパーは、Mintアカウントの公開キーから単一のデジタルアセットを取得します。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchDigitalAsset } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const mintAddress = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
8
9// Fetch a digital asset by its mint address
10const asset = await fetchDigitalAsset(umi, mintAddress);
11
12console.log('Asset:', asset.publicKey);
13console.log('Metadata:', asset.metadata.publicKey);
14console.log('Name:', asset.metadata.name);
15console.log('URI:', asset.metadata.uri);
16console.log('Seller Fee:', asset.metadata.sellerFeeBasisPoints);

1import { address } from '@solana/addresses';
2import { fetchDigitalAsset } from '@metaplex-foundation/mpl-token-metadata-kit';
3
4// Assuming rpc is set up
5// See getting-started for full setup
6
7const mintAddress = address('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
8
9// Fetch a digital asset by its mint address
10const asset = await fetchDigitalAsset(rpc, mintAddress);
11
12console.log('Asset:', asset.address);
13console.log('Name:', asset.metadata.name);
14console.log('URI:', asset.metadata.uri);
15console.log('Seller Fee:', asset.metadata.sellerFeeBasisPoints);
16if (asset.edition) {
17  console.log('Is Original:', asset.edition.isOriginal);
18}

Metadataによる取得

このヘルパーは、Metadataアカウントの公開キーから単一のデジタルアセットを取得します。Mintアドレスを見つけるために最初にMetadataアカウントの内容を取得する必要があるため、前のヘルパーよりわずかに効率が劣りますが、Metadata公開キーのみにアクセスできる場合、これは役立ちます。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchDigitalAssetByMetadata } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const metadataAddress = publicKey('Gz3vYbpsB2agTsAwedtvtTkQ1CG9Cpo6eTq59rrEGCKF');
8
9// Fetch a digital asset by its metadata address
10const asset = await fetchDigitalAssetByMetadata(umi, metadataAddress);
11
12console.log('Asset:', asset.publicKey);
13console.log('Metadata:', asset.metadata.publicKey);
14console.log('Name:', asset.metadata.name);
15console.log('URI:', asset.metadata.uri);

1import { address } from '@solana/addresses';
2import { fetchDigitalAssetByMetadata } from '@metaplex-foundation/mpl-token-metadata-kit';
3
4// Assuming rpc is set up
5// See getting-started for full setup
6
7const metadataAddress = address('Gz3vYbpsB2agTsAwedtvtTkQ1CG9Cpo6eTq59rrEGCKF');
8
9// Fetch a digital asset by its metadata address
10const asset = await fetchDigitalAssetByMetadata(rpc, metadataAddress);
11
12console.log('Asset:', asset.address);
13console.log('Name:', asset.metadata.name);
14console.log('URI:', asset.metadata.uri);

Mintリストによるすべての取得

このヘルパーは、提供されたリスト内のMint公開キーの数だけのデジタルアセットを取得します。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAsset } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const mints = [
8  publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK'),
9  publicKey('8TQdiAzdZZEaKtHGjvnLMXhVGjfNsqMgPGBQPPsWYgo8'),
10];
11
12// Fetch multiple digital assets by their mint addresses
13const assets = await fetchAllDigitalAsset(umi, mints);
14
15assets.forEach((asset) => {
16  console.log('Asset:', asset.publicKey);
17  console.log('Name:', asset.metadata.name);
18});

1import { address } from '@solana/addresses';
2import { fetchAllDigitalAsset } from '@metaplex-foundation/mpl-token-metadata-kit';
3
4// Assuming rpc is set up
5// See getting-started for full setup
6
7const mints = [
8  address('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK'),
9  address('8TQdiAzdZZEaKtHGjvnLMXhVGjfNsqMgPGBQPPsWYgo8'),
10];
11
12// Fetch multiple digital assets by their mint addresses
13const assets = await fetchAllDigitalAsset(rpc, mints);
14
15assets.forEach((asset) => {
16  console.log('Asset:', asset.address);
17  console.log('Name:', asset.metadata.name);
18});

作成者によるすべての取得

このヘルパーは、作成者によってすべてのデジタルアセットを取得します。作成者はMetadataアカウント内の5つの異なる位置にある可能性があるため、関心のある作成者の位置も提供する必要があります。例えば、NFTのセットで最初の作成者が作成者A、2番目の作成者がBであることがわかっている場合、位置1で作成者A、位置2で作成者Bを検索したいと思うでしょう。

このヘルパーはアカウントをフィルタリングするためのRPC呼び出しが必要であり、Umi SDKで利用可能です。Kit SDKの場合は、効率的なクエリのためにDAS（Digital Asset Standard）APIプロバイダーの使用を検討してください。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAssetByCreator } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const creator = publicKey('creatorAddress...');
8
9// Assets where the creator is first in the Creator array
10const assetsA = await fetchAllDigitalAssetByCreator(umi, creator);
11
12// Assets where the creator is second in the Creator array
13const assetsB = await fetchAllDigitalAssetByCreator(umi, creator, {
14  position: 2,
15});
16
17console.log('Assets with creator at position 1:', assetsA.length);
18assetsA.forEach((asset) => {
19  console.log('Name:', asset.metadata.name);
20});

所有者によるすべての取得

このヘルパーは、所有者によってすべてのデジタルアセットを取得します。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAssetByOwner } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const owner = publicKey('ownerAddress...');
8
9// Fetch all digital assets owned by a wallet
10const assets = await fetchAllDigitalAssetByOwner(umi, owner);
11
12assets.forEach((asset) => {
13  console.log('Name:', asset.metadata.name);
14  console.log('URI:', asset.metadata.uri);
15});

更新権限によるすべての取得

このヘルパーは、更新権限の公開キーからすべてのデジタルアセットを取得します。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAssetByUpdateAuthority } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const updateAuthority = publicKey('updateAuthorityAddress...');
8
9// Fetch all digital assets by update authority
10const assets = await fetchAllDigitalAssetByUpdateAuthority(umi, updateAuthority);
11
12console.log('Found', assets.length, 'assets');
13assets.forEach((asset) => {
14  console.log('Name:', asset.metadata.name);
15  console.log('Mint:', asset.publicKey);
16});

トークン付きデジタルアセット

上記で言及したデジタルアセットデータ構造は、アセットの所有者についての情報を提供しないことに注意してください。この最初の定義は、所有者に関係なく必要なオンチェーンアカウントのみに焦点を当てています。しかし、アセットのより完全な画像を提供するために、誰がそれを所有しているかを知る必要がある場合もあります。ここでトークン付きデジタルアセットデータ構造が登場します。これは、以下のアカウントも含むデジタルアセットデータ構造の拡張です：

Tokenアカウント（SPL Tokenプログラムから）：Mintアカウントとその所有者の関係を定義します。所有者が所有するトークンの数などの重要なデータを保存します。NFTの場合、数量は常に1です。
Token Recordアカウント（pNFTのみ）：現在のトークンデリゲートやその役割など、プログラマブル非Fungibleの追加のトークン関連情報を定義します。

Fungibleアセットの場合、同じデジタルアセットは複数のTokenアカウントを介して複数の所有者と関連付けられる可能性があることに注意してください。したがって、同じデジタルアセットに対して複数のトークン付きデジタルアセットが存在する可能性があります。

ここでも、トークン付きデジタルアセットを取得するための一連のヘルパーを提供します。

トークン付きデジタルアセットの定義

import { Token } from '@metaplex-foundation/mpl-toolbox'
import {
  DigitalAsset,
  TokenRecord,
} from '@metaplex-foundation/mpl-token-metadata'

export type DigitalAssetWithToken = DigitalAsset & {
  token: Token
  tokenRecord?: TokenRecord
}

Mintによる取得

このヘルパーは、Mintアカウントの公開キーから単一のトークン付きデジタルアセットを取得します。これは主に非Fungibleアセットに関連しています。Fungibleアセットにいくつ存在するかに関係なく、1つのトークン付きデジタルアセットのみを返すからです。

Kit SDKはトークンアドレスまたは所有者のいずれかを知っている必要があります。所有者がわかっている場合は、以下の「Mintと所有者による取得」ヘルパーを使用してください。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchDigitalAssetWithTokenByMint } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
8
9// Fetch a digital asset with its token account by mint address
10const asset = await fetchDigitalAssetWithTokenByMint(umi, mint);
11
12console.log('Asset:', asset.publicKey);
13console.log('Name:', asset.metadata.name);
14console.log('Token Owner:', asset.token.owner);
15console.log('Token Amount:', asset.token.amount);

Mintと所有者による取得

このヘルパーは前のヘルパーよりもパフォーマンスが良いですが、アセットの所有者を知っている必要があります。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchDigitalAssetWithAssociatedToken } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
8const owner = publicKey('ownerAddress...');
9
10// Fetch a digital asset with its associated token account
11const asset = await fetchDigitalAssetWithAssociatedToken(umi, mint, owner);
12
13console.log('Asset:', asset.publicKey);
14console.log('Name:', asset.metadata.name);
15console.log('Token Owner:', asset.token.owner);
16console.log('Token Amount:', asset.token.amount);

1import { address } from '@solana/addresses';
2import { fetchDigitalAssetWithAssociatedToken } from '@metaplex-foundation/mpl-token-metadata-kit';
3
4// Assuming rpc is set up
5// See getting-started for full setup
6
7const mintAddress = address('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
8const ownerAddress = address('ownerAddress...');
9
10// Fetch a digital asset with its associated token account
11const asset = await fetchDigitalAssetWithAssociatedToken(rpc, mintAddress, ownerAddress);
12
13console.log('Asset:', asset.address);
14console.log('Name:', asset.metadata.name);
15console.log('Token Owner:', asset.token.owner);
16console.log('Token Amount:', asset.token.amount);

所有者によるすべての取得

このヘルパーは、指定された所有者からすべてのトークン付きデジタルアセットを取得します。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAssetWithTokenByOwner } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const owner = publicKey('ownerAddress...');
8
9// Fetch all digital assets with their token accounts by owner
10const assets = await fetchAllDigitalAssetWithTokenByOwner(umi, owner);
11
12console.log('Found', assets.length, 'assets');
13assets.forEach((asset) => {
14  console.log('Name:', asset.metadata.name);
15  console.log('Token Amount:', asset.token.amount);
16});

Mintによるすべての取得

このヘルパーは、Mintアカウントの公開キーからすべてのトークン付きデジタルアセットを取得します。これはすべてのTokenアカウントを取得するため、Fungibleアセットに特に関連しています。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAssetWithTokenByMint } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
8
9// Fetch all token accounts for a given mint
10const assets = await fetchAllDigitalAssetWithTokenByMint(umi, mint);
11
12console.log('Found', assets.length, 'token accounts');
13assets.forEach((asset) => {
14  console.log('Owner:', asset.token.owner);
15  console.log('Amount:', asset.token.amount);
16});

所有者とMintによるすべての取得

このヘルパーは、所有者とMintアカウントの両方からすべてのトークン付きデジタルアセットを取得します。これは、指定された所有者に対して複数のTokenアカウントを持つFungibleアセットに役立ちます。

1import { publicKey } from '@metaplex-foundation/umi';
2import { fetchAllDigitalAssetWithTokenByOwnerAndMint } from '@metaplex-foundation/mpl-token-metadata';
3
4// Assuming umi is set up with mplTokenMetadata plugin
5// See getting-started for full setup
6
7const owner = publicKey('ownerAddress...');
8const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');
9
10// Fetch all token accounts for a given owner and mint
11const assets = await fetchAllDigitalAssetWithTokenByOwnerAndMint(umi, owner, mint);
12
13console.log('Found', assets.length, 'token accounts');
14assets.forEach((asset) => {
15  console.log('Token Address:', asset.token.publicKey);
16  console.log('Amount:', asset.token.amount);
17});