Expert · LESSON 05 OF 07
5. State compression and Bubblegum V2
By the end, you can explain merkle commitments, das evidence, proof freshness, v2 compatibility, and the separate issuer checks required for compressed credentials.
Look up Solana terms in the glossary
Optional reading history is saved only in this browser. It is not a scored checkpoint or exam result.
In this lesson9 field notes · practice · sources · checkpoint
Read a text version of this diagram
The diagram follows asset data through leaf hashing and sibling proofs to a Merkle root, then compares it with the intended tree. On-chain configuration and root differ from indexed DAS asset data and proof; record provider, cluster, request context, and proof freshness. Inclusion proves leaf membership only, not the issuer or exam result. DAS may resolve inherited royalties for display while the leaf retains its canonical currentMetadata. Preserve fresh proof-bearing state for the same asset and tree when building a write; rebuild after a stale-root rejection.
- ENCODE ASSET DATA
- HASH THE LEAF
- FETCH SIBLING PROOF
- REBUILD TREE ROOT
- VERIFY CLUSTER STATE
Why compress state
A normal Solana digital asset is represented by accounts whose state can be queried through ordinary account RPC. A compressed NFT takes a different route: its asset data is committed as a leaf in a Merkle tree rather than kept in a dedicated account for every asset. The tree account stores compact configuration and a changing root. This reduces per-asset account storage, but moves application work into proof construction, event history, and indexer availability. Compression changes where state is recorded and how an operation proves it is current; it does not make the asset private, make its media permanent, or remove all transaction and operational costs. Treat a cNFT as a distinct data and verification architecture.
From asset data to a Merkle root
The asset fields and creator information are encoded and hashed into a leaf according to the protocol schema. Sibling hashes along the path combine with that leaf until the calculation reaches the tree root. A verifier compares the calculated root with an accepted root for the tree. This compact commitment lets the program check a particular leaf without loading every asset record. The asset identifier is a PDA derived from the Merkle tree address and the leaf index; it is not a regular NFT mint address. Keep tree address, leaf index, schema version, data hash, creator hash, nonce, and root attached to the evidence used for verification. A matching root proves inclusion of the committed leaf under that tree state; it does not prove that every displayed field, issuer claim, or course result is honest.
Where the data and proof come from
Creation and update transactions include the asset data in the ledger history, while the tree account anchors the root and configuration. A Digital Asset Standard (DAS) API is an RPC extension implemented by compatible providers. Methods such as getAsset return indexed asset details; getAssetProof returns a proof and related tree values. Ordinary RPC endpoints do not all implement DAS, and provider indexes can lag, be incomplete, or interpret ledger history differently. Record the endpoint, cluster, request time, response context and any slot or sequence the response exposes. For a high-value decision, compare independent evidence and verify the leaf against a root on the intended cluster. Do not present an indexer’s metadata object as data read directly from a per-asset on-chain account.
A proof is a snapshot, not a permanent receipt
Every accepted update or transfer replaces the leaf commitment. A proof fetched before another tree update may no longer reconstruct the root accepted by the program. Fetch current asset state and proof together as close as practical to a write, bind both to the same asset and tree, and let the program reject stale evidence. Retry by fetching fresh evidence and rebuilding the instruction, never by blindly resubmitting an old proof. Concurrent Merkle Trees support multiple tree updates while retaining a bounded change history; tree configuration and canopy affect proof behavior, account requirements and transaction size. Proof nodes can make an instruction too large. Follow current SDK guidance, inspect the exact tree configuration, and simulate on the target cluster before building a user-facing write flow.
Bubblegum V1 and V2 are separate designs
Metaplex marks Bubblegum V1 as legacy and recommends V2 for new work. V2 has different instructions and leaf data; its assets are grouped with MPL Core collections. V1 and V2 trees are not interchangeable, and the current V2 FAQ says V2 does not support V1-style decompression. Therefore, never choose an SDK helper, tree, collection type, or transaction instruction from a copied V1 example without checking its version. Freeze, thaw, and soulbound features are available in V2 with collection-level plugin configuration, but those labels do not replace an authority audit. Inspect the collection and plugin configuration, identify who can change it, and simulate the exact transfer and burn behaviors the product promises. Credential passports in this Academy currently use the Core asset design documented in the credential lesson; this cNFT lesson describes a separate option and does not announce a migration.
Design a cNFT indexer that can be repaired
A production read path should preserve raw transaction signatures, slots, tree addresses, leaf indices, change sequence, raw instruction data, parser version, and provider provenance. Decode creation and leaf-replacement events using the matching Bubblegum version. Apply events idempotently, keep a replayable cursor, and distinguish “not found yet,” unsupported DAS method, indexer lag, malformed proof, stale root, and confirmed program rejection. Compare a provider’s current asset view with ledger-derived changes for sampled assets. If an indexer upgrade finds an unrecognized event, quarantine that record and preserve cursor coverage; do not advance past it while advertising complete results. Provide a rebuild path that can recompute the view from retained source evidence, then reconcile before activation. An endpoint response and a green dashboard are operational observations, not proof that the protocol accepted a user’s instruction.
Compare compressed and account-based assets honestly
Compression is useful when an application needs very large numbers of assets and can tolerate DAS/indexer dependencies, proof handling, and tree-level administration. Account-based assets are easier to find with ordinary account RPC and can integrate differently with wallets, marketplaces, and programs, but each asset account has a storage footprint. Bubblegum V2 collection and operation support differs from V1 and from MPL Core assets. Ecosystem support is a separate product requirement: in its June 19, 2026 overview snapshot, Metaplex listed display support for Phantom, Solflare, and Backpack, but not transfer support, and listed Magic Eden and Tensor as unsupported. Recheck the live compatibility page and test the exact wallet, cluster, and verification flow before launch; a support table is time-bound. For this Academy's low-volume, learner-facing passport, that evidence favors retaining the current MPL Core asset design unless measured scale makes compression valuable and a wallet pilot passes. Do not publish a permanent per-asset cost: tree depth, canopy, protocol fees, transaction fees, provider pricing, and application operations all matter and can change. Before selecting a model, write down the expected asset count, mutation rate, wallet/marketplace support, proof latency, required program integrations, recovery and audit needs, and what happens when the indexer is unavailable. Measure the complete workflow on the intended cluster and recheck current provider and protocol documentation.
Credential use needs separate policy and proof
A cNFT can carry a credential claim, but the Merkle proof only authenticates that leaf against a tree root; it does not establish that the student passed a trustworthy exam. A credential verifier must also validate the issuer identity, assessment result, wallet binding, course and level, curriculum revision, metadata policy, and revocation or correction process. If the requirement is non-transferability, verify the exact Bubblegum V2 collection plugin and authority state at the intended cluster and test transfer, burn, freeze and thaw paths. Explain publicly readable wallet and transaction history, storage dependencies, and wallet-loss consequences before minting. The Academy’s current credentials remain individually addressable MPL Core assets. Any later cNFT pilot would need its own architecture review, tested issuer claim format, user consent, and explicit comparison with the live Core collection; this lesson alone must not be interpreted as an implementation decision.
Preserve canonical metadata through writes
The Bubblegum V2 SDK exposes two metadata views with different jobs. `metadata` mirrors the DAS display fields; `currentMetadata` represents the leaf-canonical `MetadataArgsV2Args` used by mutation flows. In this fictional collection with inherited royalties, the display view resolves the collection rate to 500 basis points, while the leaf keeps the `65535` inheritance sentinel and an empty creators array. Both can be correct: collection configuration can resolve values for display without rewriting the leaf. For a name-only update, fetch a fresh `getAssetWithProof` result and preserve its `currentMetadata` and proof together in the documented `updateMetadataV2` flow. Do not reconstruct the write context from a rendered DAS display object or an old proof; first confirm the asset, tree, cluster, and current proof. This is a data-representation check, not evidence that an issuer approved a credential or graded an exam fairly.
A detail worth keeping.
Build a paper-only Merkle evidence walkthrough. Starting from one fictional leaf and sibling hashes, show how ordered hash pairs produce a root. Then mark which values come from a DAS provider, which are read from the tree account, which originate in ledger transactions, and which are application claims. Explain which values must be current for a write.
Work through an example
Review a fictional credential collection configuration against the promised transfer, burn and recovery behavior. Identify the authorities, exact Bubblegum version, tree type, collection type, provider requirements and upgrade/migration limits. Write a verifier failure table that never converts unavailable indexer evidence into an invalid or valid credential result.
Use a fictional Bubblegum V2 credential and synthetic evidence only. Produce a data-flow diagram, a proof verification checklist, and a compact evidence record containing cluster, tree, asset PDA, leaf index, root, proof source and timestamp. Tabletop an indexer-lag case, a stale-proof rejection, an unknown decoder event, a transfer attempt under a claimed soulbound collection, and a valid leaf whose exam eligibility is missing. Do not connect a wallet, generate keys, sign, submit, or mint.
GUIDED PRACTICE · EXPERT
Do the work, one step at a time.
Use fictional addresses and disposable test data. Do not enter a recovery phrase or private key. Most exercises work on paper or with a local test; only a lesson that clearly says “read-only Devnet” makes a public network request.
- Draw the asset-data → leaf-hash → sibling-proof → Merkle-root path and identify the tree account and indexed-service boundaries.
- Inspect a sample DAS response schema on paper; label the cluster, provider, asset PDA, tree, leaf index, root and proof without treating the response as authoritative by itself.
- Trace an update where the fetched proof becomes stale, then specify the fresh-data, re-build, simulation and rejection behavior.
- Compare Bubblegum V1, Bubblegum V2 and the Academy’s Core asset credentials by tree/collection model, proof needs, compatibility and transfer-control authority.
- Create an indexer replay and reconciliation checklist for unknown events, provider lag, proof mismatch and decoder upgrades.
- Present a credential-verification report that separates leaf inclusion from issuer identity, exam eligibility, wallet binding, curriculum revision and revocation policy.
- For a fictional inherited-royalty asset, label `metadata` as the resolved display view and `currentMetadata` as the leaf-canonical view; check that the proof is fresh for the same asset and tree; then state which values the documented name-only update flow should preserve. Do not connect a wallet, sign, or send the transaction.
Before you move on, check your reasoning
- Verify provider and cluster provenance.
- Recompute the leaf path to a checked root.
- Keep issuer, assessment and wallet-binding checks separate.
OPEN SELF-CHECK · UNGRADED
Pause and test your reasoning
Practice 1 of 4
A DAS endpoint returns asset metadata, but you must verify that a cNFT leaf belongs to its tree. What should you request next?
Reveal the answer and explanation
One best answer: Request and verify the proof.
getAsset returns indexed asset detail, while getAssetProof provides proof material. Verify the leaf against the intended cluster root and keep the provider and request context with your evidence.
Sources: Fetching Compressed NFTs · Bubblegum Overview
Practice 2 of 4
An indexer is briefly unavailable while a wallet checks an Academy credential. How should the wallet report it?
Reveal the answer and explanation
One best answer: Show an unknown result; retry an approved source with the cluster recorded.
An unavailable indexer cannot prove either inclusion or absence. Keep the outcome unknown until a compatible source supplies evidence, then verify the cluster, asset and proof before returning a credential result.
Sources: DAS API Overview · Fetching Compressed NFTs
Practice 3 of 4
Which design conclusion follows from Bubblegum V2 being a separate representation from the Academy’s current MPL Core passport?
Reveal the answer and explanation
One best answer: Treat cNFTs as a separate asset representation; evaluate migration explicitly before changing the Core passport design.
Bubblegum V2 is a separate asset option from the Academy’s current Core credentials. A Merkle proof establishes leaf inclusion, while exam eligibility and issuer policy require separate evidence.
Sources: Bubblegum V2 FAQ · Bubblegum Overview
Practice 4 of 4
A collection-resolved royalty appears in `metadata`, while `currentMetadata` keeps the 65535 sentinel. Which pair should a name-only mutation context preserve?
Reveal the answer and explanation
One best answer: The fresh proof and leaf-canonical `currentMetadata`.
DAS may resolve inherited royalty fields for display. The SDK distinguishes that view from leaf-canonical `currentMetadata`; keep it with proof data fetched fresh for the same asset and tree.
Sources: Bubblegum V2 JavaScript SDK · Bubblegum V2 FAQ
This practice is not scored, saved, or part of a certificate. Account-based lesson checkpoints and level exams remain separate.
Never enter a recovery phrase or private key into a learning site or lesson exercise.
READ THE SOURCE
Go deeper in the official docs
Reviewed on 2026-10-04. Protocol documentation can change; check the linked page’s current version as you use this material.
YOUR PROGRESS, SAVED
Ready for the checkpoint?
Make a free account to save your progress and unlock the quizzes.
Create free account