Core グループ

概要

Core Groups（GroupV1）は、コレクション、アセット、他のグループを上位のセットにまとめる分類アカウントです。例として、複数のコレクションを含むブランドの傘下や、スタンドアロンアセットのキュレーション用ディレクトリなどがあります。

• グループはコレクションと同様に独自の name と uri を保持します
• グループはベクトルごとに最大 256 件のコレクション、子グループ、親グループリンク、またはアセットを直接含めます
• グループに追加されたコレクションとアセットには、親グループのアドレスを列挙する Groups プラグイン が付与されます

ジャンプ先： グループを作成 · メンバーシップを管理 · グループを取得

コレクションとグループの違い

コレクションとグループは異なる問題を解決します。コレクションはメンバー NFT を管理し、グループはコレクション・アセット・子グループの上位分類を提供します。

シリーズ単位のロイヤリティ、凍結ルール、共有アートワークが必要な場合は コレクション を使います。ミント方法を変えずに複数のコレクションやスタンドアロンアセットを 1 つのラベルで整理する場合は グループ を使います。

GroupV1 アカウント

GroupV1 アカウントには次が保存されます：

オンチェーン制限（mpl-core より）：

• ベクトル（collections、groups、parentGroups、assets）あたり最大 256 エントリ
• グループあたり親グループは最大 8 件（MAX_GROUP_NESTING_DEPTH）

Groups プラグイン

コレクションまたはアセットをグループに追加すると、mpl-core はそのメンバーに Groups 権限管理プラグインが存在することを保証します。プラグインには親グループの公開鍵が保存されます。

グループの作成

createGroup / createGroupV1 で新しいグループアカウントをデプロイします：

1import { generateSigner } from '@metaplex-foundation/umi'
2import { createGroup } from '@metaplex-foundation/mpl-core'
3
4const group = generateSigner(umi)
5
6await createGroup(umi, {
7  group,
8  name: 'My Brand Directory',
9  uri: 'https://example.com/my-brand.json',
10  relationships: [],
11}).sendAndConfirm(umi)
12
13console.log('Group created:', group.publicKey)

作成時に relationships を渡すと、1 トランザクションでコレクション、子グループ、親グループ、アセットをリンクできます。各 relationship エントリは RelationshipKind を使用します：Collection、ChildGroup、ParentGroup、Asset。

グループメンバーシップの管理

特記がない限り、すべてのメンバーシップ変更は グループの update authority が署名します。

コレクションをグループに追加

1import { publicKey } from '@metaplex-foundation/umi'
2import { addCollectionsToGroup } from '@metaplex-foundation/mpl-core'
3
4const group = publicKey('GroupAddress...')
5const collection = publicKey('CollectionAddress...')
6
7await addCollectionsToGroup(umi, {
8  group,
9  authority: umi.identity,
10})
11  .addRemainingAccounts([
12    { pubkey: collection, isSigner: false, isWritable: true },
13  ])
14  .sendAndConfirm(umi)
15
16console.log('Collection added to group')

スタンドアロンアセットをグループに追加

1import { publicKey } from '@metaplex-foundation/umi'
2import { addAssetsToGroup } from '@metaplex-foundation/mpl-core'
3
4const group = publicKey('GroupAddress...')
5const asset = publicKey('AssetAddress...')
6
7await addAssetsToGroup(umi, {
8  group,
9  authority: umi.identity,
10})
11  .addRemainingAccounts([
12    { pubkey: asset, isSigner: false, isWritable: true },
13  ])
14  .sendAndConfirm(umi)
15
16console.log('Asset added to group')

グループのネスト

1import { addGroupsToGroup } from '@metaplex-foundation/mpl-core'
2
3// parentGroup and childGroup are existing GroupV1 accounts
4
5await addGroupsToGroup(umi, {
6  parentGroup: parentGroup.publicKey,
7  groups: [childGroup.publicKey],
8  authority: umi.identity,
9})
10  .addRemainingAccounts([
11    { pubkey: childGroup.publicKey, isSigner: false, isWritable: true },
12  ])
13  .sendAndConfirm(umi)
14
15console.log('Child group nested under parent')

親と子のベクトルは同期されます。親は groups に子を、子は parentGroups に親を記録します。

グループの取得

mpl-core SDK でオンチェーン状態を読み取ります：

1import { publicKey } from '@metaplex-foundation/umi'
2import { fetchGroupV1 } from '@metaplex-foundation/mpl-core'
3
4const groupAddress = publicKey('GroupAddress...')
5
6const group = await fetchGroupV1(umi, groupAddress)
7
8console.log(group.name)
9console.log(group.collections)
10console.log(group.groups)
11console.log(group.assets)

update authority 別にグループを一覧するには getGroupV1GpaBuilder（GPA クエリ）を使います。グループ数は通常少ないため問題になりにくいですが、大量の Asset を走査する場合は DAS を優先してください。

1import { publicKey } from '@metaplex-foundation/umi'
2import { getGroupV1GpaBuilder, Key } from '@metaplex-foundation/mpl-core'
3
4const updateAuthority = publicKey('UpdateAuthorityAddress...')
5
6const groups = await getGroupV1GpaBuilder(umi)
7  .whereField('updateAuthority', updateAuthority)
8  .whereField('key', Key.GroupV1)
9  .getDeserialized()
10
11for (const group of groups) {
12  console.log(group.publicKey, group.name)
13}

Notes

• グループはコレクションメンバーシップを自動的には辿りません。コレクションをグループに追加しても、そのコレクション内の NFT は group.assets に追加されません。グループ化されたコレクション内の NFT を扱う場合は、コレクションとそのアセットを個別に操作してください
• Groups プラグインは、少なくとも 1 つのグループに属している間、グループメンバー自体（コレクションアカウントまたは直接グループ化されたアセット）のバーンをブロックします。グループ化されたコレクション内のアセットをバーンしても、コレクションはグループから削除されません

Glossary

以下の用語は、このページで使用する Core Groups の概念を定義します。

クイックリファレンス

以下の表は、一般的なグループ操作の mpl-core プログラム ID と SDK ヘルパーを示します。

プログラム ID

mpl-core プログラム ID は mainnet と devnet で同じです。

SDK ヘルパー

作成、取得、更新、メンバーシップ操作には次の SDK 関数を使用します。

FAQ

コレクションとグループの違いは何ですか？

コレクションは共有メタデータとコレクションレベルのプラグインの下で Core Asset をまとめます。グループは、コレクション、スタンドアロンアセット、その他のグループを参照できる分類コンテナです。コレクションは「この NFT はどのシリーズに属するか？」に答え、グループは「このコレクションやアセットはどの上位セットに含まれるか？」に答えます。

コレクションは複数のグループに属せますか？

はい。コレクションをグループに追加すると、mpl-core は親グループのアドレスをコレクションの Groups プラグインに書き込みます。コレクションはオンチェーンのベクトル上限まで複数の親グループを列挙できます。

グループはネストできますか？

はい。グループは子グループを含み、親グループも列挙できます。親子リンクは両方のアカウントで同期されます。1 つのグループは最大 8 つの親グループに属せます。

グループ化されたコレクション内のアセットは自動的にグループに属しますか？

いいえ。グループメンバーシップは直接メンバーのみに保存されます。コレクションをグループに追加すると、そのコレクションが group.collections に追加され、コレクションに Groups プラグインが書き込まれます。そのコレクションにミントされた NFT は自動的に group.assets には追加されません。

スタンドアロンアセットをグループの直接メンバーにできますか？

はい。addAssetsToGroup を使って、コレクションなしでアセットを group.assets に直接追加できます。コレクション管理アセットも、適切な権限者が署名すれば明示的に追加できます。

誰がグループメンバーシップを変更できますか？

グループの update authority が追加・削除命令に署名します。コレクション管理アセットについては、コレクションの update authority（または認可されたデリゲート）がグループの代理としてそれらのアセットを追加・削除できます。