Collection 관리

이 가이드에서는 Metaplex Core SDK를 사용하여 Solana에서 Core Collection을 생성하고 관리하는 방법을 설명합니다. Collection은 관련 Asset을 공유된 아이덴티티와 컬렉션 수준의 메타데이터 및 플러그인으로 그룹화합니다.

요약

Collection은 관련 Asset을 그룹화하는 Core 계정입니다. 컬렉션 메타데이터(이름, 이미지, 설명)를 저장하고 컬렉션 내 모든 Asset에 적용되는 플러그인을 보유할 수 있습니다.

• Collection은 Asset 그룹의 "표지"로 작동합니다
• Asset은 collection 필드를 통해 Collection을 참조합니다
• Collection 플러그인(Royalties 같은)은 모든 멤버 Asset에 적용될 수 있습니다
• Collection 생성에는 약 0.0015 SOL이 소요됩니다

범위 외

Token Metadata Collection(mpl-token-metadata 사용), 압축 NFT 컬렉션(Bubblegum 사용), 기존 컬렉션의 Core 마이그레이션.

빠른 시작

바로가기: Collection 생성 · 플러그인 포함 · 가져오기 · 업데이트

1. 설치: npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
2. 컬렉션 메타데이터 JSON을 업로드하여 URI 획득
3. createCollection(umi, { collection, name, uri }) 호출
4. Asset 생성 시 Collection 주소 전달

전제 조건

• 서명자와 RPC 연결이 구성된 Umi
• 트랜잭션 수수료용 SOL (컬렉션당 약 0.002 SOL)
• Arweave/IPFS에 업로드된 컬렉션 이미지가 포함된 메타데이터 JSON

Collection이란?

Collection은 같은 시리즈나 그룹에 속하는 Asset의 그룹입니다. Asset을 그룹화하려면 먼저 컬렉션 이름과 컬렉션 이미지 같은 해당 컬렉션 관련 메타데이터를 저장하는 Collection Asset을 생성해야 합니다. Collection Asset은 컬렉션의 표지 역할을 하며 컬렉션 전체 플러그인도 저장할 수 있습니다. Collection Asset에서 저장되고 접근 가능한 데이터는 다음과 같습니다:

Collection 생성

Core Collection을 생성하려면 CreateCollection 명령어를 다음과 같이 사용할 수 있습니다:

간단한 Collection 생성

다음 스니펫은 플러그인이나 특별한 것 없이 간단한 Collection을 생성합니다.

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { createCollection } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { generateSigner } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10// Generate a new keypair for the collection
11const collectionSigner = generateSigner(umi)
12
13// Create a new Collection
14await createCollection(umi, {
15  collection: collectionSigner,
16  name: 'My Collection',
17  uri: 'https://example.com/collection.json',
18}).sendAndConfirm(umi)
19
20console.log('Collection created:', collectionSigner.publicKey)

플러그인 포함 Collection 생성

다음 스니펫은 Royalties 플러그인이 첨부된 Collection을 생성합니다. 여기에 설명된 대로 추가 플러그인을 첨부할 수 있습니다.

import { generateSigner, publicKey } from '@metaplex-foundation/umi'
import { createCollection, ruleSet } from '@metaplex-foundation/mpl-core'
const collectionSigner = generateSigner(umi)
const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('22222222222222222222222222222222')
await createCollection(umi, {
  collection: collectionSigner,
  name: 'My NFT',
  uri: 'https://example.com/my-nft.json',
  plugins: [
    {
      type: 'Royalties',
      basisPoints: 500,
      creators: [
        {
          address: creator1,
          percentage: 20,
        },
        {
          address: creator2,
          percentage: 80,
        },
      ],
      ruleSet: ruleSet('None'), // 호환성 규칙 세트
    },
  ],
}).sendAndConfirm(umi)

Collection 가져오기

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

import { fetchCollectionV1 } from '@metaplex-foundation/mpl-core'
import { publicKey } from '@metaplex-foundation/umi'
const collectionId = publicKey('11111111111111111111111111111111')
const collection = await fetchCollection(umi, collectionId)
console.log(collection)

Collection 업데이트

Core Collection의 데이터를 업데이트하려면 UpdateCollection 명령어를 사용합니다. 예를 들어, 이 명령어를 사용하여 컬렉션의 이름을 변경할 수 있습니다.

import { publicKey } from '@metaplex-foundation/umi'
import { updateCollection } from '@metaplex-foundation/mpl-core'
const collectionAddress = publicKey('1111111111111111111111111111111')
await updateCollection(umi, {
  collection: collectionAddress,
  name: 'my-nft',
  uri: 'https://exmaple.com/new-uri',
}).sendAndConfirm(umi)

Collection 플러그인 업데이트

Core Collection에 첨부된 플러그인의 동작을 변경하려면 updateCollectionPlugin 명령어를 사용할 수 있습니다.

import { publicKey } from '@metaplex-foundation/umi'
import { updateCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
const collectionAddress = publicKey('1111111111111111111111111111111')
const newCreator = publicKey('5555555555555555555555555555555')
await updateCollectionPlugin(umi, {
  collection: collectionAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 400,
    creators: [{ address: newCreator, percentage: 100 }],
    ruleSet: ruleSet('None'),
  },
}).sendAndConfirm(umi)

일반적인 오류

Collection account already exists

Collection 키페어가 이미 사용되었습니다. 새 서명자를 생성하세요:

const collectionSigner = generateSigner(umi) // 고유해야 합니다

Authority mismatch

당신은 Collection의 Update Authority가 아닙니다. Collection의 updateAuthority 필드가 서명자와 일치하는지 확인하세요.

Insufficient funds

지불 지갑에 약 0.002 SOL이 필요합니다. 다음으로 자금을 추가하세요:

solana airdrop 1 <WALLET_ADDRESS> --url devnet

참고 사항

• collection 매개변수는 생성 시 새 키페어여야 합니다
• Collection 플러그인은 Asset 수준에서 재정의하지 않는 한 Asset에 상속됩니다
• 생성 후 Collection 상태를 확인하려면 fetchCollection을 사용하세요
• numMinted 카운터는 현재 크기가 아닌 지금까지 생성된 총 Asset 수를 추적합니다

빠른 참조

프로그램 ID

최소 코드

import { generateSigner } from '@metaplex-foundation/umi'
import { createCollection } from '@metaplex-foundation/mpl-core'
const collection = generateSigner(umi)
await createCollection(umi, { collection, name: 'My Collection', uri: 'https://...' }).sendAndConfirm(umi)

비용 내역

FAQ

Collection과 Asset의 차이점은 무엇인가요?

Collection은 Asset을 그룹화하는 컨테이너입니다. 자체 메타데이터(이름, 이미지)를 가지지만 Asset처럼 소유하거나 전송할 수 없습니다. Asset은 사용자가 소유하는 실제 NFT입니다.

기존 Asset을 Collection에 추가할 수 있나요?

네, newCollection 매개변수와 함께 update 명령어를 사용합니다. Asset의 Update Authority가 대상 Collection에 추가할 권한을 가져야 합니다.

NFT에 Collection이 필요한가요?

아니요. Asset은 Collection 없이 독립적으로 존재할 수 있습니다. 하지만 Collection을 사용하면 컬렉션 수준의 로열티, 더 쉬운 검색 가능성, 일괄 작업이 가능해집니다.

Collection에서 Asset을 제거할 수 있나요?

네, update 명령어를 사용하여 Asset의 Collection을 변경할 수 있습니다. Asset과 Collection 모두에서 적절한 권한이 필요합니다.

Collection을 삭제하면 어떻게 되나요?

Collection은 Asset을 포함하고 있는 동안에는 삭제할 수 없습니다. 먼저 모든 Asset을 제거한 다음 Collection 계정을 닫을 수 있습니다.

용어집