Managing Collections

Summary

Managing collections for compressed NFTs uses the setCollectionV2 instruction to add, change, or remove MPL-Core collections on existing cNFTs. This page covers setting and removing collections after minting.

• Set an MPL-Core collection on an existing cNFT using setCollectionV2
• Remove a collection from a cNFT
• Change between collections (both authorities must sign)
• Collections must have the BubblegumV2 plugin enabled

A cNFT can be added to an MPL-Core Collection either on mint or later.

If you are not familiar with the concept of collections with regard to NFTs, they are special non-compressed NFTs that can be used to group other NFTs together. The data of the Collection is therefore used to describe the name and the branding of the entire collection. Since Bubblegum V2, it also allows additional features on collection level, like allowing freezing and thawing of cNFTs by a delegate without the need of interaction by the leaf owner. You can read more about MPL-Core Collections here. Note that it is possible to mint a Compressed NFT directly into a collection by using the MintV2 instruction documented here. That being said, if you have already minted a cNFT without a collection, let's see how we can set the collection on that cNFT. Unlike Bubblegum v1, which uses Metaplex Token Metadata Collections which have a "verified" boolean, Bubblegum V2 uses MPL-Core Collections which do not have that boolean.

The MPL-Core Collection has to contain the BubblegumV2 plugin.

The following sections show how to set and remove a collection from a cNFT in single-step transactions. It is also possible to do both operations in a single instruction when adding the coreCollection and newCoreCollection parameters. If both collection authorities are not the same wallet, both have to sign.

Set the Collection of a Compressed NFT

The setCollectionV2 instruction can be used to set the collection of a cNFT. It can also be used to remove the collection from a cNFT or change the collection of a cNFT.

import {
  getAssetWithProof,
  setCollectionV2,
  MetadataArgsV2Args
} from '@metaplex-foundation/mpl-bubblegum';
import {
  unwrapOption,
  none,
} from '@metaplex-foundation/umi';

const assetWithProof = await getAssetWithProof(umi, assetId, {truncateCanopy: true});

const collection = unwrapOption(assetWithProof.metadata.collection)

const metadata: MetadataArgsV2Args = {
  ...assetWithProof.metadata,
  collection: collection?.key ?? null,
};

const signature = await setCollectionV2(umi, {
  ...assetWithProof,
  newCollectionAuthority: newCollectionUpdateAuthority,
  metadata,
  newCoreCollection: newCoreCollection.publicKey,
}).sendAndConfirm(umi);

Remove the Collection of a Compressed NFT

The setCollectionV2 instruction can also be used to remove the collection from a cNFT.

import {
  getAssetWithProof,
  setCollectionV2,
  MetadataArgsV2Args
} from '@metaplex-foundation/mpl-bubblegum'
import {
  unwrapOption,
  none,
} from '@metaplex-foundation/umi';

const assetWithProof = await getAssetWithProof(umi, assetId, {truncateCanopy: true});

const collection = unwrapOption(assetWithProof.metadata.collection)

const signature = await setCollectionV2(umi, {
  ...assetWithProof,
  authority: collectionAuthoritySigner,
  coreCollection: collection!.key
}).sendAndConfirm(umi);

Inherited royalties

cNFTs minted with inherited seller fee basis points store the sentinel value 65535 on the leaf. This affects collection management:

• Removing a collection — setCollectionV2 rejects the operation while the leaf still uses the inherit sentinel. Update the cNFT to an explicit sellerFeeBasisPoints first via updateMetadataV2.
• Moving to another collection — Allowed when the destination collection has the Royalties plugin. The cNFT keeps the inherit sentinel and resolves royalties from the new collection.
• Moving to a collection without royalties — Rejected with CollectionMustHaveRoyaltiesPlugin.

Notes

• The MPL-Core collection must have the BubblegumV2 plugin enabled before cNFTs can be added to it.
• Unlike Bubblegum V1 (which uses Token Metadata collections with a "verified" boolean), V2 uses MPL-Core collections without verification flags.
• When changing between collections, both the old and new collection authorities must sign the transaction.
• cNFTs with inherited seller fees cannot be removed from a collection until royalties are set to an explicit value on the leaf.

FAQ

How do I add a cNFT to a collection after minting?

Use the setCollectionV2 instruction with the newCoreCollection parameter set to the collection's public key. The collection authority must sign.

Can I change the collection of a cNFT?

Yes. Use setCollectionV2 with both coreCollection (current) and newCoreCollection (new). Both collection authorities must sign if they are different accounts.

What is the BubblegumV2 plugin?

It is an MPL-Core collection plugin that enables Bubblegum V2 features like freeze/thaw, soulbound cNFTs, royalty enforcement, and permanent delegates on the collection level.

Can I remove a cNFT from a collection when it inherits royalties?

No. The program returns CannotRemoveFromCollectionWithInheritedSellerFee. Use updateMetadataV2 to set an explicit sellerFeeBasisPoints value first, then call setCollectionV2 to remove the collection.

Glossary