자산 가져오기 | Token Metadata

이제 자산의 다양한 온체인 계정을 생성하고 민팅하는 방법을 알았으므로, 이를 가져오는 방법을 알아보겠습니다.

디지털 자산

이전 페이지에서 언급했듯이, 대체 가능하거나 그렇지 않은 자산은 여러 온체인 계정을 생성해야 합니다. 자산의 토큰 표준에 따라 일부 계정은 필요하지 않을 수 있습니다. 다음은 이러한 계정에 대한 간단한 개요입니다:

Mint 계정 (SPL Token 프로그램에서): 기본 SPL 토큰의 핵심 속성을 정의합니다. 다른 모든 계정이 이로부터 파생되므로 모든 자산의 진입점입니다.
Metadata 계정: 기본 SPL 토큰에 추가 데이터와 기능을 제공합니다.
Master Edition 또는 Edition 계정 (대체 불가능한 토큰만): 원본 NFT의 여러 복사본을 인쇄할 수 있게 해줍니다. NFT가 에디션 인쇄를 허용하지 않는 경우에도 Master Edition 계정은 대체 불가능성을 보장하기 위해 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이고 두 번째 크리에이터가 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만): 현재 토큰 위임자와 그 역할과 같은 프로그래머블 대체 불가능한 토큰에 대한 추가 토큰 관련 정보를 정의합니다.

대체 가능한 자산의 경우, 동일한 디지털 자산이 여러 토큰 계정을 통해 여러 소유자와 연결될 가능성이 높다는 점에 주목하세요. 따라서 동일한 디지털 자산에 대해 여러 토큰이 있는 디지털 자산이 있을 수 있습니다.

여기서도 토큰이 있는 디지털 자산을 가져오는 헬퍼 세트를 제공합니다.

토큰이 있는 디지털 자산 정의

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 계정의 공개 키에서 단일 토큰이 있는 디지털 자산을 가져옵니다. 이는 대체 가능한 자산에 대해 얼마나 많이 존재하는지에 관계없이 하나의 토큰이 있는 디지털 자산만 반환하므로 주로 대체 불가능한 자산과 관련이 있습니다.

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 계정의 공개 키에서 모든 토큰이 있는 디지털 자산을 가져옵니다. 이는 모든 토큰 계정을 가져오므로 대체 가능한 자산에 특히 관련이 있습니다.

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 계정 모두에서 모든 토큰이 있는 디지털 자산을 가져옵니다. 이는 주어진 소유자에 대해 하나 이상의 토큰 계정을 가진 대체 가능한 자산에 유용할 수 있습니다.

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