solana_kit_mpl_bubblegum

Compressed NFT instruction builders, DAS API helpers, hashing, Merkle tree utilities, and PDA derivation for the Solana Kit Dart SDK.

Installation

Install the package directly:

dependencies:
  "solana_kit_mpl_bubblegum": ^0.6.0

If your app uses several Solana Kit packages together, you can also depend on the umbrella package instead:

dart pub add solana_kit

Inside this monorepo, Dart workspace resolution uses the local package automatically.

Usage

Create a V1 tree for compressed NFTs:

import 'package:solana_kit_addresses/solana_kit_addresses.dart';
import 'package:solana_kit_mpl_bubblegum/solana_kit_mpl_bubblegum.dart';

void main() {
  const merkleTree = Address('11111111111111111111111111111111');
  const payer = Address('11111111111111111111111111111112');

  final input = CreateTreeInput(
    merkleTree: merkleTree,
    payer: payer,
    treeCreator: payer,
    maxDepth: 14,
    maxBufferSize: 64,
  );
  final plan = getCreateTreeInstructionPlan(input);
  print(plan.kind);
}

Mint a compressed NFT with the V1 instruction plan:

import 'package:solana_kit_addresses/solana_kit_addresses.dart';
import 'package:solana_kit_mpl_bubblegum/solana_kit_mpl_bubblegum.dart';

void main() {
  const treeAddress = Address('11111111111111111111111111111111');
  const ownerAddress = Address('11111111111111111111111111111112');
  const payerAddress = Address('11111111111111111111111111111113');
  const treeDelegateAddress = Address('11111111111111111111111111111114');

  final input = MintV1Input(
    merkleTree: treeAddress,
    leafOwner: ownerAddress,
    leafDelegate: ownerAddress,
    payer: payerAddress,
    treeDelegate: treeDelegateAddress,
    name: 'My NFT',
    uri: 'https://example.com/metadata.json',
    creators: [Creator(address: payerAddress, verified: false, share: 100)],
  );
  final plan = getMintV1InstructionPlan(input);
  print(plan.kind);
}

Derive PDA addresses for tree authority and the bubblegum signer:

import 'package:solana_kit_mpl_bubblegum/solana_kit_mpl_bubblegum.dart';

void main() {
  print(mplBubblegumProgramAddress);
  print(tokenMetadataProgramAddress);
}

Look up a compressed NFT error by enum or code:

import 'package:solana_kit_mpl_bubblegum/solana_kit_mpl_bubblegum.dart';

void main() {
  final message = getMplBubblegumErrorMessage(
    MplBubblegumError.collectionMustHaveRoyaltiesPlugin,
  );
  print(message);

  if (isMplBubblegumError(0x17a9)) {
    print('matched bubblegum error');
  }
}

Proof data and validation

getAssetWithProof preserves the DAS owner and delegate, defaults an absent delegate to the owner, uses compression.leaf_id as the nonce, and converts the DAS node index to a leaf index. Custom DasApiClient implementations should populate DasAssetOwnership.owner and delegate.

MerkleTree.verify requires 32-byte roots, leaves, and proof nodes. It returns false for malformed nodes and leaf indices outside the range represented by the proof depth. The caller must obtain the expected root from a trusted source; checking a proof against a root supplied by the same untrusted party does not authenticate an asset.

Key APIs

getCreateTreeInstructionPlan, getCreateTreeV2InstructionPlan, getMintV1InstructionPlan, getMintV2InstructionPlan, getMintToCollectionV1InstructionPlan, getTransferInstructionPlan, getBurnInstructionPlan, getDelegateInstructionPlan
hashLeafV1, hashLeafV2, bubblegumHash for Keccak-256 hashing
findTreeAuthorityPda, findLeafAssetIdV2Pda, findBubblegumSignerPda for PDA derivation
HeliusDasClient, getAssetWithProof for DAS API access
mplBubblegumProgramAddress, tokenMetadataProgramAddress constants
isMplBubblegumError, getMplBubblegumErrorMessage for error handling

License

MIT