Bubblegum decoder

carbon-bubblegum-decoder decodes the instructions and accounts of the Bubblegum program (BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY): 17 instructions, 2 account types. It is generated with Codama from the program's IDL; see decoders for how decoders plug into a pipeline.

Other NFT and metadata decoders: Metaplex Core, Metaplex Token Metadata. To decode several in one pipeline, see nFT and metadata decoders.

The serde feature derives Serialize/Deserialize on every type, postgres adds tables and processors for Postgres, and graphql adds a schema for the GraphQL server.

Usage#

This program crawls recent Bubblegum transactions from the public RPC and prints every decoded MintV1 instruction. Add the dependencies:

cargo add carbon-core@2.0.0 carbon-bubblegum-decoder@2.0.0 carbon-rpc-transaction-crawler-datasource@2.0.0 carbon-log-metrics@2.0.0 env_logger tokio --features tokio/full

use {
    carbon_core::{
        error::CarbonResult, instruction::InstructionProcessorInputType, pipeline::Pipeline,
        processor::Processor,
    },
    carbon_log_metrics::LogMetrics,
    carbon_bubblegum_decoder::{instructions::BubblegumInstruction, BubblegumDecoder, PROGRAM_ID},
    carbon_rpc_transaction_crawler_datasource::{ConnectionConfig, Filters, RpcTransactionCrawler},
    std::sync::Arc,
};

#[tokio::main]
async fn main() -> CarbonResult<()> {
    env_logger::init();

    // Fetches the program's recent transactions over JSON-RPC, newest first.
    let datasource = RpcTransactionCrawler::new(
        "https://api.mainnet-beta.solana.com".to_string(),
        PROGRAM_ID,
        ConnectionConfig::default(),
        Filters::new(None, None, None),
        None,
    );

    Pipeline::builder()
        .datasource(datasource)
        .metrics(Arc::new(LogMetrics::new()))
        .instruction(BubblegumDecoder, InstructionLogger)
        .build()?
        .run()
        .await
}

struct InstructionLogger;

impl Processor<InstructionProcessorInputType<'_, BubblegumInstruction>> for InstructionLogger {
    async fn process(
        &mut self,
        input: &InstructionProcessorInputType<'_, BubblegumInstruction>,
    ) -> CarbonResult<()> {
        let signature = input.metadata.transaction_metadata.signature;
        if let BubblegumInstruction::MintV1 { data, accounts, .. } = input.decoded_instruction {
            println!("mint_v1 {signature}: {data:?} tree_authority={}", accounts.tree_authority);
        }
        Ok(())
    }
}

RUST_LOG=info cargo run

Each MintV1 instruction prints one line with the transaction signature and the decoded MintV1 data. The public endpoint rate-limits requests, so the first lines can take a while; use your own RPC URL for anything beyond a test. See stream with RPC for the crawler options.

Decode accounts#

The transaction crawler emits transactions only. To decode accounts, use a datasource that emits account updates. This program subscribes to the program's accounts with programSubscribe on the public WebSocket endpoint and prints every decoded TreeConfig account as it changes. Add the datasource and the Solana RPC types it takes:

cargo add carbon-rpc-program-subscribe-datasource@2.0.0 solana-client@4.2.2

use {
    carbon_core::{
        account::AccountProcessorInputType, error::CarbonResult, pipeline::Pipeline,
        processor::Processor,
    },
    carbon_log_metrics::LogMetrics,
    carbon_bubblegum_decoder::{accounts::BubblegumAccount, BubblegumDecoder, PROGRAM_ID},
    carbon_rpc_program_subscribe_datasource::{Filters, RpcProgramSubscribe},
    solana_client::rpc_config::{RpcAccountInfoConfig, RpcProgramAccountsConfig, UiAccountEncoding},
    std::sync::Arc,
};

#[tokio::main]
async fn main() -> CarbonResult<()> {
    env_logger::init();

    // Streams every change to an account owned by the program (programSubscribe).
    let config = RpcProgramAccountsConfig {
        account_config: RpcAccountInfoConfig {
            encoding: Some(UiAccountEncoding::Base64),
            ..Default::default()
        },
        ..Default::default()
    };
    let datasource = RpcProgramSubscribe::new(
        "wss://api.mainnet-beta.solana.com".to_string(),
        Filters::new(PROGRAM_ID, Some(config)),
    );

    Pipeline::builder()
        .datasource(datasource)
        .metrics(Arc::new(LogMetrics::new()))
        .account(BubblegumDecoder, AccountLogger)
        .build()?
        .run()
        .await
}

struct AccountLogger;

impl Processor<AccountProcessorInputType<'_, BubblegumAccount>> for AccountLogger {
    async fn process(
        &mut self,
        input: &AccountProcessorInputType<'_, BubblegumAccount>,
    ) -> CarbonResult<()> {
        if let BubblegumAccount::TreeConfig(tree_config) = &input.decoded_account.data {
            println!("tree_config {}: {tree_config:?}", input.metadata.pubkey);
        }
        Ok(())
    }
}

RUST_LOG=info cargo run

Each update to a TreeConfig account prints its address and decoded fields; the program runs until you stop it. Cargo resolves solana-client to 4.2.2, the exact version the datasource pins, so both use the same RpcProgramAccountsConfig type. To load every existing account once instead of streaming changes, see load account state.

Instructions#

Variants of BubblegumInstruction. Each is BubblegumInstruction::<Variant> { program_id, data, accounts }, where data and accounts are the types listed under the variant, exported from carbon_bubblegum_decoder::instructions. Discriminators are the leading bytes of the instruction data, in hex.

How an instruction decodes. The decoder returns a variant only when all of these hold; otherwise the instruction is skipped and no processor is called:

1. The instruction's program ID is BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY.
2. The data starts with the variant's discriminator, and the rest deserializes into its data type.
3. The instruction has at least as many accounts as the variant requires (the "Required accounts" count under each variant).

Accounts. They are matched by position, in the order listed. An account marked optional is None only when the instruction ends before it; Anchor programs pass the program ID as a placeholder for an omitted optional account, so check for Some(PROGRAM_ID) too. Accounts after the listed ones are in accounts.remaining as AccountMetas. The decoder doesn't record whether an account signed or was writable: read that from input.raw_instruction.accounts[i].is_signer and .is_writable, which follow the same order. It doesn't check signer, writable, owner or PDA constraints either; the program enforced those when the transaction executed, so a decoded instruction from a successful transaction already satisfied them.

Burn#

Discriminator 746e1d386bdb2a5d · data Burn · accounts BurnInstructionAccounts.

Required accounts: 7; extras go to remaining.

Fields of BurnInstructionAccounts, in account order:

CancelRedeem#

Discriminator 6f4ce83227af30f2 · data CancelRedeem · accounts CancelRedeemInstructionAccounts.

Required accounts: 7; extras go to remaining.

Fields of CancelRedeemInstructionAccounts, in account order:

CreateTree#

Discriminator a553888e59ca2fdc · data CreateTree · accounts CreateTreeInstructionAccounts.

Required accounts: 7; extras go to remaining.

Fields of CreateTreeInstructionAccounts, in account order:

DecompressV1#

Discriminator 36554c46e4faa451 · data DecompressV1 · accounts DecompressV1InstructionAccounts.

Required accounts: 13; extras go to remaining.

Fields of DecompressV1InstructionAccounts, in account order:

Delegate#

Discriminator 5a934bb255580489 · data Delegate · accounts DelegateInstructionAccounts.

Required accounts: 8; extras go to remaining.

Fields of DelegateInstructionAccounts, in account order:

MintToCollectionV1#

Discriminator 9912b22fc59e560f · data MintToCollectionV1 · accounts MintToCollectionV1InstructionAccounts.

Required accounts: 16; extras go to remaining.

Fields of MintToCollectionV1InstructionAccounts, in account order:

MintV1#

Discriminator 9162c076b8937668 · data MintV1 · accounts MintV1InstructionAccounts.

Required accounts: 9; extras go to remaining.

Fields of MintV1InstructionAccounts, in account order:

Redeem#

Discriminator b80c569546c461e1 · data Redeem · accounts RedeemInstructionAccounts.

Required accounts: 8; extras go to remaining.

Fields of RedeemInstructionAccounts, in account order:

SetAndVerifyCollection#

Discriminator ebf279d89eeab4ea · data SetAndVerifyCollection · accounts SetAndVerifyCollectionInstructionAccounts.

Required accounts: 16; extras go to remaining.

Fields of SetAndVerifyCollectionInstructionAccounts, in account order:

SetDecompressibleState#

Discriminator 52689806956f640d · data SetDecompressibleState · accounts SetDecompressibleStateInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of SetDecompressibleStateInstructionAccounts, in account order:

SetTreeDelegate#

Discriminator fd764225be319a66 · data SetTreeDelegate · accounts SetTreeDelegateInstructionAccounts.

No data fields.

Required accounts: 5; extras go to remaining.

Fields of SetTreeDelegateInstructionAccounts, in account order:

Transfer#

Discriminator a334c8e78c0345ba · data Transfer · accounts TransferInstructionAccounts.

Required accounts: 8; extras go to remaining.

Fields of TransferInstructionAccounts, in account order:

UnverifyCollection#

Discriminator fafb2a6a2989baa8 · data UnverifyCollection · accounts UnverifyCollectionInstructionAccounts.

Required accounts: 16; extras go to remaining.

Fields of UnverifyCollectionInstructionAccounts, in account order:

UnverifyCreator#

Discriminator 6bb2392769737098 · data UnverifyCreator · accounts UnverifyCreatorInstructionAccounts.

Required accounts: 9; extras go to remaining.

Fields of UnverifyCreatorInstructionAccounts, in account order:

UpdateMetadata#

Discriminator aab62bef614ee1ba · data UpdateMetadata · accounts UpdateMetadataInstructionAccounts.

Required accounts: 13; extras go to remaining.

Fields of UpdateMetadataInstructionAccounts, in account order:

VerifyCollection#

Discriminator 387165fd4f377aa9 · data VerifyCollection · accounts VerifyCollectionInstructionAccounts.

Required accounts: 16; extras go to remaining.

Fields of VerifyCollectionInstructionAccounts, in account order:

VerifyCreator#

Discriminator 34116084470455c2 · data VerifyCreator · accounts VerifyCreatorInstructionAccounts.

Required accounts: 9; extras go to remaining.

Fields of VerifyCreatorInstructionAccounts, in account order:

Accounts#

Variants of BubblegumAccount. Each wraps a boxed struct from carbon_bubblegum_decoder::accounts::<module>. decode_account only considers accounts owned by PROGRAM_ID and returns the first variant that matches.

TreeConfig#

Discriminator 7af5aff8ab2200cf · accounts::tree_config::TreeConfig.

Voucher#

Discriminator bfcc95ead5a50d41 · accounts::voucher::Voucher.

Types#

Types used by the instructions, accounts and events above, exported from carbon_bubblegum_decoder::types.

BubblegumEventType#

Enum types::BubblegumEventType.

Collection#

Struct types::Collection.

Creator#

Struct types::Creator.

DecompressibleState#

Enum types::DecompressibleState.

LeafSchema#

Enum types::LeafSchema.

MetadataArgs#

Struct types::MetadataArgs.

TokenProgramVersion#

Enum types::TokenProgramVersion.

TokenStandard#

Enum types::TokenStandard.

UpdateArgs#

Struct types::UpdateArgs.

UseMethod#

Enum types::UseMethod.

Uses#

Struct types::Uses.

Version#

Enum types::Version.