SPL Token decoder

carbon-token-program-decoder decodes the instructions and accounts of the SPL Token program (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA): 28 instructions, 3 account types. 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, Stake Program, System Program, Token-2022. To decode several in one pipeline, see core and SPL program decoders.

Guide: Index token transfers.

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 SPL Token transactions from the public RPC and prints every decoded TransferChecked instruction. Add the dependencies:

cargo add carbon-core@2.0.0 carbon-token-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_token_program_decoder::{
        instructions::TokenProgramInstruction, TokenProgramDecoder, 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(TokenProgramDecoder, InstructionLogger)
        .build()?
        .run()
        .await
}

struct InstructionLogger;

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

RUST_LOG=info cargo run

Each TransferChecked instruction prints one line with the transaction signature and the decoded TransferChecked 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 Mint 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_token_program_decoder::{accounts::TokenProgramAccount, TokenProgramDecoder, 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 {
        // Mint accounts are 82 bytes; without a filter this streams every token account.
        filters: Some(vec![RpcFilterType::DataSize(82)]),
        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(TokenProgramDecoder, AccountLogger)
        .build()?
        .run()
        .await
}

struct AccountLogger;

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

RUST_LOG=info cargo run

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

AmountToUiAmount#

From the program's IDL:

Convert an Amount of tokens to a UiAmount string, using the given mint. In this version of the program, the mint can only specify the number of decimals.
Fails on an invalid mint.
Return data can be fetched using sol_get_return_data and deserialized with String::from_utf8.

Discriminator 17 · data AmountToUiAmount · accounts AmountToUiAmountInstructionAccounts.

Required accounts: 1; extras go to remaining.

Fields of AmountToUiAmountInstructionAccounts, in account order:

Approve#

From the program's IDL:

Approves a delegate. A delegate is given the authority over tokens on behalf of the source account's owner.

Discriminator 04 · data Approve · accounts ApproveInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of ApproveInstructionAccounts, in account order:

ApproveChecked#

From the program's IDL:

Approves a delegate. A delegate is given the authority over tokens on behalf of the source account's owner.
This instruction differs from Approve in that the token mint and decimals value is checked by the caller. This may be useful when creating transactions offline or within a hardware wallet.

Discriminator 0d · data ApproveChecked · accounts ApproveCheckedInstructionAccounts.

Required accounts: 4; extras go to remaining.

Fields of ApproveCheckedInstructionAccounts, in account order:

Batch#

From the program's IDL:

Executes a batch of instructions. The instructions to be executed are specified in sequence on the instruction data.

Discriminator ff · data Batch · accounts BatchInstructionAccounts.

No named accounts.

Burn#

From the program's IDL:

Burns tokens by removing them from an account. Burn does not support accounts associated with the native mint, use CloseAccount instead.

Discriminator 08 · data Burn · accounts BurnInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of BurnInstructionAccounts, in account order:

BurnChecked#

From the program's IDL:

Burns tokens by removing them from an account. BurnChecked does not support accounts associated with the native mint, use CloseAccount instead. This instruction differs from Burn in that the decimals value is checked by the caller. This may be useful when creating transactions offline or within a hardware wallet.

Discriminator 0f · data BurnChecked · accounts BurnCheckedInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of BurnCheckedInstructionAccounts, in account order:

CloseAccount#

From the program's IDL:

Close an account by transferring all its SOL to the destination account.
Non-native accounts may only be closed if its token amount is zero.

Discriminator 09 · data CloseAccount · accounts CloseAccountInstructionAccounts.

No data fields.

Required accounts: 3; extras go to remaining.

Fields of CloseAccountInstructionAccounts, in account order:

FreezeAccount#

From the program's IDL:

Freeze an Initialized account using the Mint's freeze_authority (if set).

Discriminator 0a · data FreezeAccount · accounts FreezeAccountInstructionAccounts.

No data fields.

Required accounts: 3; extras go to remaining.

Fields of FreezeAccountInstructionAccounts, in account order:

GetAccountDataSize#

From the program's IDL:

Gets the required size of an account for the given mint as a little-endian u64.
Return data can be fetched using sol_get_return_data and deserializing the return data as a little-endian u64.

Discriminator 15 · data GetAccountDataSize · accounts GetAccountDataSizeInstructionAccounts.

No data fields.

Required accounts: 1; extras go to remaining.

Fields of GetAccountDataSizeInstructionAccounts, in account order:

InitializeAccount#

From the program's IDL:

Initializes a new account to hold tokens. If this account is associated with the native mint then the token balance of the initialized account will be equal to the amount of SOL in the account. If this account is associated with another mint, that mint must be initialized before this command can succeed.
The InitializeAccount instruction requires no signers and MUST be included within the same Transaction as the system program's CreateAccount instruction that creates the account being initialized.
Otherwise another party can acquire ownership of the uninitialized account.

Discriminator 01 · data InitializeAccount · accounts InitializeAccountInstructionAccounts.

No data fields.

Required accounts: 4; extras go to remaining.

Fields of InitializeAccountInstructionAccounts, in account order:

InitializeAccount2#

From the program's IDL:

Like InitializeAccount, but the owner pubkey is passed via instruction data rather than the accounts list. This variant may be preferable when using Cross Program Invocation from an instruction that does not need the owner's AccountInfo otherwise.

Discriminator 10 · data InitializeAccount2 · accounts InitializeAccount2InstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of InitializeAccount2InstructionAccounts, in account order:

InitializeAccount3#

From the program's IDL:

Like InitializeAccount2, but does not require the Rent sysvar to be provided.

Discriminator 12 · data InitializeAccount3 · accounts InitializeAccount3InstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of InitializeAccount3InstructionAccounts, in account order:

InitializeImmutableOwner#

From the program's IDL:

Initialize the Immutable Owner extension for the given token account
Fails if the account has already been initialized, so must be called before InitializeAccount.
No-ops in this version of the program, but is included for compatibility with the Associated Token Account program.

Discriminator 16 · data InitializeImmutableOwner · accounts InitializeImmutableOwnerInstructionAccounts.

No data fields.

Required accounts: 1; extras go to remaining.

Fields of InitializeImmutableOwnerInstructionAccounts, in account order:

InitializeMint#

From the program's IDL:

Initializes a new mint and optionally deposits all the newly minted tokens in an account.
The InitializeMint instruction requires no signers and MUST be included within the same Transaction as the system program's CreateAccount instruction that creates the account being initialized.
Otherwise another party can acquire ownership of the uninitialized account.

Discriminator 00 · data InitializeMint · accounts InitializeMintInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of InitializeMintInstructionAccounts, in account order:

InitializeMint2#

From the program's IDL:

Like [InitializeMint], but does not require the Rent sysvar to be provided.

Discriminator 14 · data InitializeMint2 · accounts InitializeMint2InstructionAccounts.

Required accounts: 1; extras go to remaining.

Fields of InitializeMint2InstructionAccounts, in account order:

InitializeMultisig#

From the program's IDL:

Initializes a multisignature account with N provided signers.
Multisignature accounts can used in place of any single owner/delegate accounts in any token instruction that require an owner/delegate to be present. The variant field represents the number of signers (M) required to validate this multisignature account.
The InitializeMultisig instruction requires no signers and MUST be included within the same Transaction as the system program's CreateAccount instruction that creates the account being initialized.
Otherwise another party can acquire ownership of the uninitialized account.

Discriminator 02 · data InitializeMultisig · accounts InitializeMultisigInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of InitializeMultisigInstructionAccounts, in account order:

InitializeMultisig2#

From the program's IDL:

Like InitializeMultisig, but does not require the Rent sysvar to be provided.

Discriminator 13 · data InitializeMultisig2 · accounts InitializeMultisig2InstructionAccounts.

Required accounts: 1; extras go to remaining.

Fields of InitializeMultisig2InstructionAccounts, in account order:

MintTo#

From the program's IDL:

Mints new tokens to an account. The native mint does not support minting.

Discriminator 07 · data MintTo · accounts MintToInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of MintToInstructionAccounts, in account order:

MintToChecked#

From the program's IDL:

Mints new tokens to an account. The native mint does not support minting.
This instruction differs from MintTo in that the decimals value is checked by the caller. This may be useful when creating transactions offline or within a hardware wallet.

Discriminator 0e · data MintToChecked · accounts MintToCheckedInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of MintToCheckedInstructionAccounts, in account order:

Revoke#

From the program's IDL:

Revokes the delegate's authority.

Discriminator 05 · data Revoke · accounts RevokeInstructionAccounts.

No data fields.

Required accounts: 2; extras go to remaining.

Fields of RevokeInstructionAccounts, in account order:

SetAuthority#

From the program's IDL:

Sets a new authority of a mint or account.

Discriminator 06 · data SetAuthority · accounts SetAuthorityInstructionAccounts.

Required accounts: 2; extras go to remaining.

Fields of SetAuthorityInstructionAccounts, in account order:

SyncNative#

From the program's IDL:

Given a wrapped / native token account (a token account containing SOL) updates its amount field based on the account's underlying lamports.
This is useful if a non-wrapped SOL account uses system_instruction::transfer to move lamports to a wrapped token account, and needs to have its token amount field updated.

Discriminator 11 · data SyncNative · accounts SyncNativeInstructionAccounts.

No data fields.

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

Fields of SyncNativeInstructionAccounts, in account order:

ThawAccount#

From the program's IDL:

Thaw a Frozen account using the Mint's freeze_authority (if set).

Discriminator 0b · data ThawAccount · accounts ThawAccountInstructionAccounts.

No data fields.

Required accounts: 3; extras go to remaining.

Fields of ThawAccountInstructionAccounts, in account order:

Transfer#

From the program's IDL:

Transfers tokens from one account to another either directly or via a delegate. If this account is associated with the native mint then equal amounts of SOL and Tokens will be transferred to the destination account.

Discriminator 03 · data Transfer · accounts TransferInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of TransferInstructionAccounts, in account order:

TransferChecked#

From the program's IDL:

Transfers tokens from one account to another either directly or via a delegate. If this account is associated with the native mint then equal amounts of SOL and Tokens will be transferred to the destination account.
This instruction differs from Transfer in that the token mint and decimals value is checked by the caller. This may be useful when creating transactions offline or within a hardware wallet.

Discriminator 0c · data TransferChecked · accounts TransferCheckedInstructionAccounts.

Required accounts: 4; extras go to remaining.

Fields of TransferCheckedInstructionAccounts, in account order:

UiAmountToAmount#

From the program's IDL:

Convert a UiAmount of tokens to a little-endian u64 raw Amount, using the given mint. In this version of the program, the mint can only specify the number of decimals.
Return data can be fetched using sol_get_return_data and deserializing the return data as a little-endian u64.

Discriminator 18 · data UiAmountToAmount · accounts UiAmountToAmountInstructionAccounts.

Required accounts: 1; extras go to remaining.

Fields of UiAmountToAmountInstructionAccounts, in account order:

UnwrapLamports#

From the program's IDL:

Transfer lamports from a native SOL account to a destination account.

Discriminator 2d · data UnwrapLamports · accounts UnwrapLamportsInstructionAccounts.

Required accounts: 3; extras go to remaining.

Fields of UnwrapLamportsInstructionAccounts, in account order:

WithdrawExcessLamports#

From the program's IDL:

Rescue SOL sent to any TokenProgram-owned account by sending them to any other account, leaving behind only lamports for rent exemption.

Discriminator 26 · data WithdrawExcessLamports · accounts WithdrawExcessLamportsInstructionAccounts.

No data fields.

Required accounts: 3; extras go to remaining.

Fields of WithdrawExcessLamportsInstructionAccounts, in account order:

Accounts#

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

Mint#

Unpacked with spl_token_interface::state::Mint::unpack · accounts::mint::Mint.

Multisig#

Unpacked with spl_token_interface::state::Multisig::unpack · accounts::multisig::Multisig.

Token#

Unpacked with spl_token_interface::state::Account::unpack · accounts::token::Token.

Types#

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

AccountState#

Enum types::AccountState.

AuthorityType#

Enum types::AuthorityType.

BatchItem#

Struct types::BatchItem.