Virtuals decoder

carbon-virtuals-decoder decodes the instructions, accounts and events of the Virtuals program (5U3EU2ubXtK84QcRjWVmYt9RaDyA8gKxdUrPFXmZyaki): 8 instructions, 1 account type, 4 events. It is generated with Codama from the program's IDL; see decoders for how decoders plug into a pipeline.

Other launchpad decoders: Boop, Meteora DBC, Moonshot, Pump.fun, Raydium Launchpad, Vertigo, Wavebreak. To decode several in one pipeline, see launchpad 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 Virtuals transactions from the public RPC and prints every decoded Buy instruction. Add the dependencies:

cargo add carbon-core@2.0.0 carbon-virtuals-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_virtuals_decoder::{instructions::VirtualsInstruction, VirtualsDecoder, 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(VirtualsDecoder, InstructionLogger)
        .build()?
        .run()
        .await
}

struct InstructionLogger;

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

RUST_LOG=info cargo run

Each Buy instruction prints one line with the transaction signature and the decoded Buy 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.

Events published with Anchor's emit_cpi! arrive as the CpiEvent instruction. Match them with VirtualsInstruction::CpiEvent { data: CpiEvent::BuyEvent(event), .. } (import instructions::CpiEvent); see Events. If CpiEvent never arrives, the program logs its events with emit! instead: decode them with decode_log_events.

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 VirtualsPool 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_virtuals_decoder::{accounts::VirtualsAccount, VirtualsDecoder, 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(VirtualsDecoder, AccountLogger)
        .build()?
        .run()
        .await
}

struct AccountLogger;

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

RUST_LOG=info cargo run

Each update to a VirtualsPool 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 VirtualsInstruction. Each is VirtualsInstruction::<Variant> { program_id, data, accounts }, where data and accounts are the types listed under the variant, exported from carbon_virtuals_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 5U3EU2ubXtK84QcRjWVmYt9RaDyA8gKxdUrPFXmZyaki.
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.

Buy#

Discriminator 66063d1201daebea · data Buy · accounts BuyInstructionAccounts.

Required accounts: 10; extras go to remaining.

Fields of BuyInstructionAccounts, in account order:

ClaimFees#

Discriminator 52fbe99c0c34b8ca · data ClaimFees · accounts ClaimFeesInstructionAccounts.

No data fields.

Required accounts: 28; extras go to remaining.

Fields of ClaimFeesInstructionAccounts, in account order:

CreateMeteoraPool#

Discriminator f6fe2125e1b029e8 · data CreateMeteoraPool · accounts CreateMeteoraPoolInstructionAccounts.

No data fields.

Required accounts: 36; extras go to remaining.

Fields of CreateMeteoraPoolInstructionAccounts, in account order:

Initialize#

From the program's IDL:

Initialize Pool

This is where Virtuals creates a new mint address and pool and mints the initial 1,000,000,000 tokens. This enabels Virtuals to premine addresses and
\ sell\ them to customers without any delays of mining the address. While this instruction could be permissioned, it is currently permissionless. As such, we make sure to handle all the necessary checks such as: address suffix, zero supply, 6 decimals, correct mint authority.

Discriminator afaf6d1f0d989bed · data Initialize · accounts InitializeInstructionAccounts.

No data fields.

Required accounts: 9; extras go to remaining.

Fields of InitializeInstructionAccounts, in account order:

InitializeMeteoraAccounts#

Discriminator 350c769efdefb9d6 · data InitializeMeteoraAccounts · accounts InitializeMeteoraAccountsInstructionAccounts.

No data fields.

Required accounts: 36; extras go to remaining.

Fields of InitializeMeteoraAccountsInstructionAccounts, in account order:

Launch#

From the program's IDL:

This is where a user comes along and purchases a mint address and pool. The user will provide a name, symbol and URI containing offchain metadata. The contract will initialize a new onchain metadata account containing these values, then revoke the mint authority.

Discriminator 99f15de116454a3d · data Launch · accounts LaunchInstructionAccounts.

Required accounts: 12; extras go to remaining.

Fields of LaunchInstructionAccounts, in account order:

Sell#

Discriminator 33e685a4017f83ad · data Sell · accounts SellInstructionAccounts.

Required accounts: 10; extras go to remaining.

Fields of SellInstructionAccounts, in account order:

UpdatePoolCreator#

Discriminator 71e1a6b95ee7601c · data UpdatePoolCreator · accounts UpdatePoolCreatorInstructionAccounts.

No data fields.

Required accounts: 10; extras go to remaining.

Fields of UpdatePoolCreatorInstructionAccounts, in account order:

CpiEvent#

Anchor self-CPI that carries one of the program's events. data is the CpiEvent enum.

Discriminator e445a52e51cb9a1d · data CpiEvent · accounts CpiEventInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of CpiEventInstructionAccounts, in account order:

Accounts#

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

VirtualsPool#

Discriminator 477605cb05628774 · accounts::virtuals_pool::VirtualsPool.

Events#

Variants of instructions::CpiEvent, decoded from the CpiEvent instruction. Each wraps a struct from carbon_virtuals_decoder::events::<module>. The discriminator is the 8-byte event discriminator that follows the e445a52e51cb9a1d CPI-event tag.

BuyEvent#

Discriminator 67f4521f2cf57777 · events::buy_event::BuyEventEvent.

GraduationEvent#

Discriminator 0af6df7f30629537 · events::graduation_event::GraduationEventEvent.

LaunchEvent#

Discriminator 1bc12f82735cef5e · events::launch_event::LaunchEventEvent.

SellEvent#

Discriminator 3e2f370aa503dc2a · events::sell_event::SellEventEvent.

Types#

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

BuyEvent#

Struct types::BuyEvent. Same fields as the BuyEvent event.

GraduationEvent#

Struct types::GraduationEvent. Same fields as the GraduationEvent event.

LaunchEvent#

Struct types::LaunchEvent. Same fields as the LaunchEvent event.

PoolState#

Enum types::PoolState.

SellEvent#

Struct types::SellEvent. Same fields as the SellEvent event.