Attribute 플러그인

Attributes 플러그인은 Core Asset 또는 Collection 내에서 직접 온체인에 키-값 쌍을 저장합니다. 게임 스탯, 특성 및 온체인 프로그램이 읽어야 하는 모든 데이터에 완벽합니다.

요약

Attributes 플러그인은 온체인에 키-값 문자열 쌍을 저장하는 권한 관리 플러그인입니다. 오프체인 메타데이터와 달리 이러한 속성은 Solana 프로그램에서 읽을 수 있고 DAS에 의해 인덱싱됩니다.

• 모든 문자열 키-값 쌍을 온체인에 저장
• CPI를 통해 온체인 프로그램에서 읽기 가능
• 빠른 쿼리를 위해 DAS에 자동으로 인덱싱
• 업데이트 권한자가 변경 가능

범위 외

오프체인 메타데이터 속성 (URI의 JSON에 저장됨), 복잡한 데이터 유형 (문자열만 지원), 불변 속성 (모든 속성은 변경 가능).

빠른 시작

바로 가기: Asset에 추가 · 속성 업데이트

1. Attributes 플러그인 추가: addPlugin(umi, { asset, plugin: { type: 'Attributes', attributeList: [...] } })
2. 각 속성은 { key: string, value: string } 쌍
3. updatePlugin()으로 언제든지 업데이트
4. DAS를 통해 쿼리하거나 온체인에서 가져오기

일반적인 사용 사례

• 게임 캐릭터 스탯: 체력, XP, 레벨, 클래스 - 게임플레이 중 변경되는 데이터
• 접근 제어: 티어, 역할, 권한 - 프로그램이 인증을 위해 확인하는 데이터
• 동적 특성: 행동에 따라 특성이 변화하는 진화하는 NFT
• 스테이킹 상태: 스테이킹 상태, 획득한 보상, 스테이킹 시간 추적
• 업적 추적: 배지, 마일스톤, 완료 상태
• 임대/대출: 임대 기간, 차용자 정보, 반환 날짜 추적

호환 대상

인자

AttributeList

속성 목록은 Array[]로 구성되며 키-값 쌍 {key: "value"} 문자열 값 쌍의 객체입니다.

const attributeList = [
  { key: 'key0', value: 'value0' },
  { key: 'key1', value: 'value1' },
]

Asset에 Attributes 플러그인 추가

import { publicKey } from '@metaplex-foundation/umi'
import { addPlugin } from '@metaplex-foundation/mpl-core'
const asset = publicKey('11111111111111111111111111111111')
await addPlugin(umi, {
  asset: asset.publicKey,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'key0', value: 'value0' },
      { key: 'key1', value: 'value1' },
    ],
  },
}).sendAndConfirm(umi)

Asset의 Attributes 플러그인 업데이트

import { publicKey } from '@metaplex-foundation/umi'
import { updatePlugin } from '@metaplex-foundation/mpl-core'
const assetAddress = publicKey('11111111111111111111111111111111')
await updatePlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'key0', value: 'value0' },
      { key: 'key1', value: 'value1' },
    ],
  },
}).sendAndConfirm(umi)

일반적인 오류

Authority mismatch

플러그인 권한자 (보통 업데이트 권한자)만 속성을 추가하거나 업데이트할 수 있습니다. 올바른 키페어로 서명하고 있는지 확인하세요.

String too long

속성 키와 값은 크기가 제한됩니다. 간결하게 유지하세요.

참고 사항

• 권한 관리: 업데이트 권한자는 소유자 서명 없이 추가/업데이트 가능
• 모든 값은 문자열 - 필요에 따라 숫자/불리언 변환
• 업데이트는 전체 속성 목록을 대체 (부분 업데이트 없음)
• 속성은 계정 크기와 렌트 비용을 증가시킴
• DAS는 빠른 쿼리를 위해 속성을 인덱싱

빠른 참조

최소 코드

import { addPlugin } from '@metaplex-foundation/mpl-core'
await addPlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'level', value: '5' },
      { key: 'class', value: 'warrior' },
    ],
  },
}).sendAndConfirm(umi)

일반적인 속성 패턴

FAQ

온체인 속성과 오프체인 메타데이터 속성의 차이점은 무엇인가요?

온체인 속성 (이 플러그인)은 Solana에 저장되며 프로그램에서 읽을 수 있습니다. 오프체인 속성 (URI의 JSON)은 Arweave/IPFS에 저장되며 클라이언트에서만 읽을 수 있습니다.

온체인 프로그램이 이러한 속성을 읽을 수 있나요?

네. CPI를 사용하여 Asset 계정을 가져오고 Attributes 플러그인 데이터를 역직렬화할 수 있습니다.

속성이 DAS에 의해 인덱싱되나요?

네. DAS는 빠른 쿼리를 위해 속성 키-값 쌍을 자동으로 인덱싱합니다.

숫자나 불리언을 저장할 수 있나요?

값은 문자열만 가능합니다. 필요에 따라 변환하세요: { key: 'level', value: '5' }, { key: 'active', value: 'true' }.

단일 속성을 어떻게 업데이트하나요?

개별 속성을 업데이트할 수 없습니다. 현재 목록을 가져와서 수정한 후 전체 새 목록으로 업데이트하세요.

속성의 크기 제한은 무엇인가요?

하드 제한은 없지만, 더 큰 속성 목록은 렌트 비용을 증가시킵니다. 데이터를 간결하게 유지하세요.

소유자가 속성을 업데이트할 수 있나요?

아니요. Attributes 플러그인은 권한 관리이므로 업데이트 권한자만 수정할 수 있습니다 (소유자가 아닌).

관련 플러그인

• Update Delegate - 다른 사람에게 속성 업데이트 권한 부여
• ImmutableMetadata - 이름/URI 잠금 (속성은 여전히 변경 가능)
• AddBlocker - 새 플러그인 추가 방지

용어집