FAQ

Summary

This page answers the most common questions about Bubblegum V2 compressed NFTs, including costs, transaction errors, and differences from V1.

• Find required parameters for leaf-mutating instructions using getAssetWithProof
• Resolve "Transaction too large" errors with truncateCanopy or Address Lookup Tables
• Understand tree costs and capacity before creating a tree
• Bubblegum V2 is not backward-compatible with V1 trees or decompression

What is Bubblegum V2?

Bubblegum V2 is a new iteration of the Bubblegum program that introduces several improvements and new features. It is part of the known Bubblegum program, but the instructions and data structures are different. With Bubblegum V2 cNFTs are grouped into collections using MPL-Core Collections instead of Metaplex Token Metadata Collections. It also introduces new features like freezing, thawing, and soulbound NFTs and additional features like:

• Freeze and Thaw Functionality: Project creators can now freeze and thaw cNFTs, providing greater control over their assets for various use cases such as preventing transfers during specific events or implementing vesting mechanics.
• MPL-Core Collections Integration: Bubblegum V2 NFTs can now be added to MPL-Core collections instead of being limited to token metadata collections, allowing for greater flexibility and integration with the broader Metaplex ecosystem.
• Royalty Enforcement: Since Bubblegum V2 is using MPL-Core Collections, it is possible to enforce royalties on cNFTs e.g. using a ProgramDenyList.
• Soulbound NFTs: cNFTs can now be made soulbound (non-transferrable), permanently binding them to their owner's wallet. This is perfect for credentials, proof of attendance, identity verification, and more. It requires the PermanentFreezeDelegate plugin to be enabled on the collection.
• Allow Permanent Transfer: The permanent transfer delegate can now transfer the cNFT to a new owner without interaction of the leaf owner if the PermanentTransferDelegate plugin is enabled on the collection.

How do I find the arguments needed for operations such as transfer, delegate, burn, etc?

Whenever we use an instruction that ends up replacing a leaf in the Bubblegum Tree — such as transfer, delegate, burn, etc. — the program requires a bunch of parameters that are used to ensure the current leaf is valid and can be updated. This is because the data of Compressed NFTs is not available inside onchain accounts and therefore additional parameters such as the Proof, the Leaf Index, the Nonce and more are required for the program to fill the pieces.

All of that information can be retrieved from the Metaplex DAS API using both the getAsset and the getAssetProof RPC methods. However, the RPC responses from these methods and the parameters expected by the instructions are not exactly the same and parsing from one to the other is not trivial.

Fortunately, our SDKs provide a helper method that will do all the heavy lifting for us, as we can see in the code examples below. It accepts the Asset ID of the Compressed NFT and returns a bunch of parameters that can be directly injected into instructions that replace the leaf — such as burn, transfer, update, etc.

That being said, if you ever needed to do that parsing yourself, here is a quick breakdown of the parameters expected by the instructions and how to retrieve them from the Metaplex DAS API. Here we will assume the result of the getAsset and getAssetProof RPC methods are accessible via the rpcAsset and rpcAssetProof variables respectively.

• Leaf Owner: Accessible via rpcAsset.ownership.owner.
• Leaf Delegate: Accessible via rpcAsset.ownership.delegate and should default to rpcAsset.ownership.owner when null.
• Merkle Tree: Accessible via rpcAsset.compression.tree or rpcAssetProof.tree_id.
• Root: Accessible via rpcAssetProof.root.
• Data Hash: Accessible via rpcAsset.compression.data_hash.
• Creator Hash: Accessible via rpcAsset.compression.creator_hash.
• Nonce: Accessible via rpcAsset.compression.leaf_id.
• Index: Accessible via rpcAssetProof.node_index - 2^max_depth where max_depth is the maximum depth of the tree and can be inferred from the length of the rpcAssetProof.proof array.
• Proof: Accessible via rpcAssetProof.proof.
• Metadata: Currently needs to be reconstructed from various fields in the rpcAsset response.

import { getAssetWithProof, transfer } from '@metaplex-foundation/mpl-bubblegum'

const assetWithProof = await getAssetWithProof(umi, assetId, 
// {  truncateCanopy: true } // optional to prune the proofs 
);
await transferV2(umi, {
  ...assetWithProof,
  leafOwner: leafOwnerA, // As a signer.
  newLeafOwner: leafOwnerB.publicKey,
}).sendAndConfirm(umi);

await transferV2(umi, {
  ...assetWithProof,
  leafOwner: leafOwnerA, // As a signer.
  newLeafOwner: leafOwnerB.publicKey,
}).sendAndConfirm(umi)

How to Resolve "Transaction too large" Errors

When performing leaf-replacing operations like transfers or burns, you may encounter a "Transaction too large" error. To resolve this, consider the following solutions:

1. Use the truncateCanopy option: Pass { truncateCanopy: true } to the getAssetWithProof function:

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

   This option retrieves the Merkle Tree configuration and optimizes the assetWithProof by removing unnecessary proofs based on the Canopy. While it adds an extra RPC call, it significantly reduces the transaction size.

2. Utilize versioned transactions and Address Lookup Tables: Another approach is to implement versioned transactions and Address Lookup Tables. This method can help manage transaction size more effectively.

By applying these techniques, you can overcome transaction size limitations and successfully execute your operations.

How much does it cost to create a compressed NFT tree?

Tree costs depend on the configured depth and canopy. Here are some reference costs:

These costs are the one-time rent for the tree account. Once paid, minting cNFTs into the tree only costs transaction fees.

What is the difference between Bubblegum V1 and V2?

Bubblegum V2 adds several new features compared to V1:

• Freeze/Thaw: Ability to freeze and thaw cNFTs via leaf delegates or permanent freeze delegates
• Soulbound NFTs: Make cNFTs non-transferable using the permanent freeze delegate
• MPL-Core Collections: Uses MPL-Core collections instead of Token Metadata collections
• Royalty Enforcement: Enforced royalties via MPL-Core collection plugins
• Permanent Delegates: Permanent transfer, freeze, and burn delegates at the collection level
• LeafSchemaV2: New leaf format with collection hash, asset data hash, and flags

V1 trees and V2 trees are not interchangeable. V2 trees require V2 instructions.

Do I need a special RPC provider?

Yes. Compressed NFTs require an RPC provider that supports the Metaplex DAS API for indexing and fetching cNFT data. Not all RPCs support this extension. See the RPC Providers page for a list of compatible providers.

Can I decompress a cNFT back to a regular NFT?

Decompression is only available for Bubblegum V1 assets. Bubblegum V2 does not support decompression. V2 cNFTs remain compressed.

How many cNFTs can I store in one tree?

The maximum number of cNFTs is 2^maxDepth. A depth-14 tree holds 16,384 cNFTs, depth-20 holds ~1 million, depth-24 holds ~16 million, and depth-30 holds over 1 billion. See the tree capacity table for all options.