How Compression Works

State compression stores a large set of records as leaves in a merkle tree. Only the root hash (and optional canopy nodes) live on-chain; updaters supply proofs that a leaf change is valid without storing every leaf in a Solana account.

Recipe

On-chain:  MerkleTreeAccount { root, canopy[], change_log }
Off-chain: Full tree / leaf data indexed by provider
Per update: leaf + merkle proof + valid root transition

const proof = await dasRpc("getAssetProof", { id: assetId });
// proof.proof = sibling hashes from leaf to root

When to reach for this:

• Understanding why cNFT transfers need DAS proofs
• Sizing concurrent merkle trees for collection capacity
• Debugging failed Bubblegum transactions (stale proof, wrong root)
• Evaluating indexer dependency for your product

Working Example

// Conceptual merkle update for leaf transfer
type MerkleProof = {
  root: string;
  proof: string[]; // sibling hashes bottom-up
  node_index: number;
  leaf: string;
};
 
async function explainProof(assetId: string) {
  const proof = await dasRpc<MerkleProof>("getAssetProof", { id: assetId });
  console.log("Current root:", proof.root);
  console.log("Proof depth:", proof.proof.length);
  console.log("Leaf hash:", proof.leaf);
  // Bubblegum verifies proof against on-chain tree account root
  // then replaces leaf (ownership) with new hash
}

// On-chain SPL Account Compression verifies proof and applies leaf replace
// Bubblegum wraps metadata semantics around compression CPIs
// Programs rarely reimplement proof verification - delegate to compression program

What this demonstrates:

• Proof length ≈ tree depth − canopy depth
• Root on-chain must match proof root at transaction build time
• Leaf content hash encodes cNFT ownership and metadata fields

Deep Dive

How It Works

1. Tree creation allocates Concurrent Merkle Tree account with chosen maxDepth and maxBufferSize
2. Mint appends leaf hash at next index; program verifies append proof
3. Transfer replaces leaf data (new owner) with replace proof
4. Canopy stores upper proof nodes on-chain to reduce transaction size
5. Indexers reconstruct state and serve proofs via DAS

On-Chain vs Off-Chain

Tree Sizing

Choose depth for peak supply + headroom; deeper trees cost more rent.

Gotchas

• Stale proof after concurrent mints - root changed. Fix: fetch fresh proof immediately before signing.
• Undersized tree depth - cannot mint past capacity. Fix: plan peak supply at createTree.
• Zero canopy on deep tree - tx too large. Fix: set canopy depth per Metaplex recommendations for your depth.
• Assuming leaf in wallet account - no SPL token account for cNFT. Fix: ownership is leaf state, read via DAS.
• Self-hosting proofs without indexer - heavy infrastructure. Fix: use DAS provider or run merkle indexer.

Alternatives

FAQs

Related

• State Compression Basics - intro
• Reading Compressed Assets (DAS) - proof fetch
• Transferring cNFTs - proof in txs

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.