Asset 가져오기

이 가이드에서는 Metaplex Core SDK를 사용하여 Solana 블록체인에서 Core Asset과 Collection을 가져오는 방법을 설명합니다. 개별 Asset을 조회하거나 소유자 또는 Collection별로 쿼리하거나 인덱스 쿼리에 DAS를 사용할 수 있습니다.

요약

SDK 헬퍼 함수 또는 DAS API를 사용하여 Core Asset과 Collection을 가져옵니다. 사용 사례에 따라 적절한 방법을 선택하세요:

• 단일 Asset/Collection: 공개 키로 fetchAsset() 또는 fetchCollection() 사용
• 여러 Asset: fetchAssetsByOwner(), fetchAssetsByCollection() 또는 fetchAssetsByUpdateAuthority() 사용
• DAS API: 더 빠른 성능을 위한 인덱스 쿼리 사용(DAS 지원 RPC 필요)

범위 외

Token Metadata 가져오기(mpl-token-metadata 사용), 압축 NFT 가져오기(Bubblegum DAS 확장 사용), 오프체인 메타데이터 가져오기(URI 직접 페치).

빠른 시작

바로가기: 단일 Asset · 소유자별 · Collection별 · DAS API

1. 설치: npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
2. RPC 엔드포인트로 Umi 설정
3. Asset 주소로 fetchAsset(umi, publicKey) 호출
4. Asset 속성 접근: name, uri, owner, plugins

전제 조건

• RPC 연결이 구성된 Umi
• 가져올 Asset/Collection 주소(공개 키)
• 인덱스 쿼리용 DAS 지원 RPC(선택 사항이지만 권장)

단일 Asset 또는 Collection 가져오기

단일 Asset을 가져오려면 다음 함수를 사용할 수 있습니다:

1import { fetchAsset, fetchCollection, mplCore } from '@metaplex-foundation/mpl-core';
2import { publicKey } from '@metaplex-foundation/umi';
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
4
5// Initialize UMI
6const umi = createUmi('https://api.devnet.solana.com')
7  .use(mplCore())
8
9// Fetch a Core Asset
10const assetAddress = publicKey('AssetAddressHere...')
11const asset = await fetchAsset(umi, assetAddress)
12
13// Fetch a Core Collection
14const collectionAddress = publicKey('CollectionAddressHere...')
15const collection = await fetchCollection(umi, collectionAddress)
16
17console.log('Asset fetched:', asset)
18console.log('Name:', asset.name)
19console.log('Owner:', asset.owner)
20console.log('URI:', asset.uri)
21
22console.log('\nCollection fetched:', collection)
23console.log('Name:', collection.name)
24console.log('URI:', collection.uri)

import { fetchCollection } from '@metaplex-foundation/mpl-core'
const asset = await fetchCollection(umi, collection.publicKey, {
  skipDerivePlugins: false,
})
console.log(asset)

여러 Asset 가져오기

여러 Asset은 getProgramAccounts(GPA) 호출을 사용하여 가져올 수 있습니다. 이는 RPC 측면에서 상당히 비용이 많이 들고 느릴 수 있지만, Digital Asset Standard API를 사용하는 방법도 있습니다. 이 방법이 더 빠르지만 특정 RPC 제공자가 필요합니다.

소유자별 Asset 가져오기

import { publicKey } from '@metaplex-foundation/umi'
import { fetchAssetsByOwner } from '@metaplex-foundation/mpl-core'
const owner = publicKey('11111111111111111111111111111111')
const assetsByOwner = await fetchAssetsByOwner(umi, owner, {
  skipDerivePlugins: false,
})
console.log(assetsByOwner)

Collection별 Asset 가져오기

import { publicKey } from '@metaplex-foundation/umi'
import { fetchAssetsByCollection } from '@metaplex-foundation/mpl-core'
const collection = publicKey('11111111111111111111111111111111')
const assetsByCollection = await fetchAssetsByCollection(umi, collection, {
  skipDerivePlugins: false,
})
console.log(assetsByCollection)

DAS - Digital Asset Standard API

DAS 지원 RPC를 사용하면 인덱스화된 Asset을 활용하여 매우 빠른 페치와 데이터 조회가 가능합니다. DAS는 메타데이터, 오프체인 메타데이터, 컬렉션 데이터, 플러그인(Attributes 포함) 등 모든 것을 인덱스화합니다. Metaplex DAS API에 대해 자세히 알아보려면 여기를 참조하세요.

일반적인 오류

Asset not found

공개 키가 유효한 Core Asset을 가리키지 않습니다. 확인하세요:

• 주소가 정확하고 예상 네트워크(devnet 대 mainnet)에 있는지
• 계정이 존재하고 Core Asset(Token Metadata 아님)인지

RPC rate limit exceeded

GPA 쿼리는 비용이 많이 들 수 있습니다. 해결책:

• 인덱스 쿼리에 DAS 지원 RPC 사용
• 결과 제한을 위한 페이지네이션 추가
• 적절한 곳에서 결과 캐싱

참고 사항

• fetchAsset은 Collection에서 상속된 플러그인을 포함한 전체 Asset을 반환
• Asset 수준 플러그인만 가져오려면 skipDerivePlugins: true 설정(더 빠름)
• GPA 쿼리(fetchAssetsByOwner 등)는 메인넷에서 느릴 수 있음 - DAS 권장
• DAS는 오프체인 메타데이터를 반환하고 SDK 페치 함수는 온체인 데이터만 반환

빠른 참조

페치 함수

DAS vs GPA 비교

FAQ

여러 Asset을 가져올 때 GPA와 DAS 중 무엇을 사용해야 하나요?

가능한 한 DAS를 사용하세요. GPA 쿼리는 모든 프로그램 계정을 스캔하므로 메인넷에서 느리고 비용이 많이 들 수 있습니다. DAS는 더 빠르고 오프체인 메타데이터를 포함하는 인덱스 쿼리를 제공합니다.

Asset의 오프체인 메타데이터는 어떻게 가져오나요?

uri 필드에 메타데이터 URL이 포함되어 있습니다. 별도로 가져오세요:

const asset = await fetchAsset(umi, assetAddress)
const metadata = await fetch(asset.uri).then(res => res.json())

용어집