System Program decoder

carbon-system-program-decoder decodes the instructions and accounts of the System Program program (11111111111111111111111111111111): 13 instructions, 1 account type. It is generated with Codama from the program's IDL; see decoders for how decoders plug into a pipeline.

Other core and SPL decoders: Address Lookup Table, Associated Token Account, SPL Memo, SPL Name Service, SPL Token, Stake Program, Token-2022. To decode several in one pipeline, see core and SPL program 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 System Program transactions from the public RPC and prints every decoded TransferSol instruction. Add the dependencies:

cargo add carbon-core@2.0.0 carbon-system-program-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_system_program_decoder::{
        instructions::SystemProgramInstruction, SystemProgramDecoder, 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(SystemProgramDecoder, InstructionLogger)
        .build()?
        .run()
        .await
}

struct InstructionLogger;

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

RUST_LOG=info cargo run

Each TransferSol instruction prints one line with the transaction signature and the decoded TransferSol 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 Nonce 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_system_program_decoder::{
        accounts::SystemProgramAccount, SystemProgramDecoder, PROGRAM_ID,
    },
    carbon_rpc_program_subscribe_datasource::{Filters, RpcProgramSubscribe},
    solana_client::{
        rpc_config::{RpcAccountInfoConfig, RpcProgramAccountsConfig, UiAccountEncoding},
        rpc_filter::RpcFilterType,
    },
    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 {
        // Nonce accounts are 80 bytes; without a filter this streams every wallet.
        filters: Some(vec![RpcFilterType::DataSize(80)]),
        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(SystemProgramDecoder, AccountLogger)
        .build()?
        .run()
        .await
}

struct AccountLogger;

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

RUST_LOG=info cargo run

Each update to a Nonce 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 SystemProgramInstruction. Each is SystemProgramInstruction::<Variant> { program_id, data, accounts }, where data and accounts are the types listed under the variant, exported from carbon_system_program_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 11111111111111111111111111111111.
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.

AdvanceNonceAccount#

Discriminator 04000000 · data AdvanceNonceAccount · accounts AdvanceNonceAccountInstructionAccounts.

No data fields.

Required accounts: 3; extras go to remaining.

Fields of AdvanceNonceAccountInstructionAccounts, in account order:

Allocate#

Discriminator 08000000 · data Allocate · accounts AllocateInstructionAccounts.

Required accounts: 1; extras go to remaining.

Fields of AllocateInstructionAccounts, in account order:

AllocateWithSeed#

Discriminator 09000000 · data AllocateWithSeed · accounts AllocateWithSeedInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of AllocateWithSeedInstructionAccounts, in account order:

Assign#

Discriminator 01000000 · data Assign · accounts AssignInstructionAccounts.

Required accounts: 1; extras go to remaining.

Fields of AssignInstructionAccounts, in account order:

AssignWithSeed#

Discriminator 0a000000 · data AssignWithSeed · accounts AssignWithSeedInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of AssignWithSeedInstructionAccounts, in account order:

AuthorizeNonceAccount#

Discriminator 07000000 · data AuthorizeNonceAccount · accounts AuthorizeNonceAccountInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of AuthorizeNonceAccountInstructionAccounts, in account order:

CreateAccount#

Discriminator 00000000 · data CreateAccount · accounts CreateAccountInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of CreateAccountInstructionAccounts, in account order:

CreateAccountWithSeed#

Discriminator 03000000 · data CreateAccountWithSeed · accounts CreateAccountWithSeedInstructionAccounts.

Required accounts: 2 (3 listed); extras go to remaining.

Fields of CreateAccountWithSeedInstructionAccounts, in account order:

InitializeNonceAccount#

Discriminator 06000000 · data InitializeNonceAccount · accounts InitializeNonceAccountInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of InitializeNonceAccountInstructionAccounts, in account order:

TransferSol#

Discriminator 02000000 · data TransferSol · accounts TransferSolInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of TransferSolInstructionAccounts, in account order:

TransferSolWithSeed#

Discriminator 0b000000 · data TransferSolWithSeed · accounts TransferSolWithSeedInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of TransferSolWithSeedInstructionAccounts, in account order:

UpgradeNonceAccount#

Discriminator 0c000000 · data UpgradeNonceAccount · accounts UpgradeNonceAccountInstructionAccounts.

No data fields.

Required accounts: 1; extras go to remaining.

Fields of UpgradeNonceAccountInstructionAccounts, in account order:

WithdrawNonceAccount#

Discriminator 05000000 · data WithdrawNonceAccount · accounts WithdrawNonceAccountInstructionAccounts.

Required accounts: 5; extras go to remaining.

Fields of WithdrawNonceAccountInstructionAccounts, in account order:

Accounts#

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

Nonce#

No discriminator (matched by Borsh layout) · accounts::nonce::Nonce.

Types#

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

NonceState#

Enum types::NonceState.

NonceVersion#

Enum types::NonceVersion.