Solana Substreams Type Glossary

pub struct Block {
    pub previous_blockhash: String,
    pub blockhash: String,
    pub parent_slot: u64,
    pub transactions: Vec<ConfirmedTransaction>,
    pub rewards: Vec<Reward>,
    pub block_time: Option<UnixTimestamp>,
    pub block_height: Option<BlockHeight>,
    pub slot: u64,
}

pub struct ConfirmedTransaction {
    pub transaction: Option<Transaction>,
    pub meta: Option<TransactionStatusMeta>,
}

fn analyze_transaction_result(tx: &ConfirmedTransaction) -> TransactionAnalysis {
    let success = tx.meta
        .as_ref()
        .and_then(|m| m.err.as_ref())
        .is_none();
    
    let fee = tx.meta
        .as_ref()
        .map(|m| m.fee)
        .unwrap_or(0);
        
    let signature = tx.transaction
        .as_ref()
        .map(|t| t.signatures.get(0))
        .flatten()
        .cloned();
        
    TransactionAnalysis {
        succeeded: success,
        fee_paid: fee,
        primary_signature: signature
    }
}

pub struct Transaction {
    pub signatures: Vec<Vec<u8>>,
    pub message: Option<Message>,
}

fn verify_transaction(tx: &Transaction) -> TransactionVerification {
    // Check number of signatures matches required signatures
    let required_sigs = tx.message.as_ref()
        .and_then(|m| m.header.as_ref())
        .map(|h| h.num_required_signatures as usize)
        .unwrap_or(0);
        
    let has_all_signatures = tx.signatures.len() >= required_sigs;
    
    // Check if transaction is versioned
    let is_versioned = tx.message
        .as_ref()
        .map(|m| m.versioned)
        .unwrap_or(false);
        
    TransactionVerification {
        valid_signature_count: has_all_signatures,
        is_versioned,
        total_accounts: tx.message
            .as_ref()
            .map(|m| m.account_keys.len())
            .unwrap_or(0)
    }
}

pub struct Message {
    pub header: Option<MessageHeader>,
    pub account_keys: Vec<Vec<u8>>,
    pub recent_blockhash: Vec<u8>,
    pub instructions: Vec<CompiledInstruction>,
    pub versioned: bool,
    pub address_table_lookups: Vec<MessageAddressTableLookup>,
}

fn analyze_message_complexity(msg: &Message) -> MessageAnalysis {
    let account_count = msg.account_keys.len();
    let instruction_count = msg.instructions.len();
    let uses_lookup_tables = !msg.address_table_lookups.is_empty();
    
    let required_sigs = msg.header
        .as_ref()
        .map(|h| h.num_required_signatures)
        .unwrap_or(0);
        
    MessageAnalysis {
        complexity: if instruction_count > 4 { "High" } else { "Normal" },
        is_versioned: msg.versioned,
        total_accounts: account_count,
        required_signatures: required_sigs,
        uses_address_lookup: uses_lookup_tables
    }
}

pub struct MessageHeader {
    pub num_required_signatures: u32,
    pub num_readonly_signed_accounts: u32,
    pub num_readonly_unsigned_accounts: u32,
}

fn analyze_account_permissions(header: &MessageHeader) -> AccountAnalysis {
    let total_accounts = header.num_required_signatures + header.num_readonly_unsigned_accounts;
    let writable_accounts = header.num_required_signatures - header.num_readonly_signed_accounts;
    
    AccountAnalysis {
        total_accounts,
        writable_count: writable_accounts,
        readonly_count: header.num_readonly_signed_accounts + header.num_readonly_unsigned_accounts,
        requires_multiple_signers: header.num_required_signatures > 1
    }
}

pub struct MessageAddressTableLookup {
    pub account_key: Vec<u8>,
    pub writable_indexes: Vec<u8>,
    pub readonly_indexes: Vec<u8>,
}

fn resolve_lookup_table_accounts(
    lookup: &MessageAddressTableLookup,
    table_data: &AddressLookupTable
) -> LookupResult {
    let writable_accounts: Vec<Pubkey> = lookup.writable_indexes
        .iter()
        .map(|&idx| table_data.addresses[idx as usize])
        .collect();
        
    let readonly_accounts: Vec<Pubkey> = lookup.readonly_indexes
        .iter()
        .map(|&idx| table_data.addresses[idx as usize])
        .collect();
        
    LookupResult {
        table_account: Pubkey::new(&lookup.account_key),
        writable_accounts,
        readonly_accounts,
        total_accounts: writable_accounts.len() + readonly_accounts.len()
    }
}

pub struct TransactionStatusMeta {
    pub err: Option<TransactionError>,
    pub fee: u64,
    pub pre_balances: Vec<u64>,
    pub post_balances: Vec<u64>,
    pub inner_instructions: Vec<InnerInstructions>,
    pub inner_instructions_none: bool,
    pub log_messages: Vec<String>,
    pub log_messages_none: bool,
    pub pre_token_balances: Vec<TokenBalance>,
    pub post_token_balances: Vec<TokenBalance>,
    pub rewards: Vec<Reward>,
}

pub enum TransactionError {
    AccountInUse = 0,                    // Account is being processed in another transaction
    AccountLoadedTwice = 1,              // Account appears multiple times in a transaction
    AccountNotFound = 2,                 // Referenced account does not exist
    ProgramAccountNotFound = 3,          // Program account does not exist
    InsufficientFundsForFee = 4,        // Insufficient funds for transaction fee
    InvalidAccountForFee = 5,            // Fee payer account does not exist or is invalid
    AlreadyProcessed = 6,               // Transaction has already been processed
    BlockhashNotFound = 7,              // Blockhash referenced in transaction is too old
    InstructionError = 8,               // Error from instruction processing
    CallChainTooDeep = 9,              // Cross-program invocation chain too deep
    MissingSignatureForFee = 10,       // Transaction fee-paying account did not sign
    InvalidAccountIndex = 11,           // Referenced account index is invalid
    SignatureFailure = 12,             // Transaction signature verification failed
    InvalidProgramForExecution = 13,    // Program is not executable or invalid
    SanitizeFailure = 14,              // Transaction failed sanitization checks
    ClusterMaintenance = 15,           // Cluster is in maintenance mode
    AccountBorrowOutstanding = 16,     // Account has outstanding borrowed references
    WouldExceedMaxBlockCostLimit = 17, // Transaction would exceed block cost limit
    UnsupportedVersion = 18,           // Transaction version is unsupported
    InvalidWritableAccount = 19,       // Account marked writable but cannot be written to
    WouldExceedMaxAccountCostLimit = 20, // Transaction would exceed account cost limit
    WouldExceedAccountDataBlockLimit = 21, // Transaction would exceed account data block limit
    TooManyAccountLocks = 22,          // Transaction requires too many account locks
    AddressLookupTableNotFound = 23,   // Referenced address lookup table not found
    InvalidAddressLookupTableOwner = 24, // Invalid address lookup table owner
    InvalidAddressLookupTableData = 25,  // Invalid address lookup table data
    InvalidAddressLookupTableIndex = 26, // Invalid address lookup table index
    InvalidRentPayingAccount = 27,      // Account does not meet rent requirements
    WouldExceedMaxVoteCostLimit = 28,   // Transaction would exceed vote cost limit
    WouldExceedAccountDataTotalLimit = 29, // Transaction would exceed total account data limit
    DuplicateInstruction = 30,          // Duplicate instructions in transaction
    InsufficientFundsForRent = 31,      // Insufficient funds to pay rent
    MaxLoadedAccountsDataSizeExceeded = 32, // Would exceed max loaded accounts data size
    InvalidLoadedAccountsDataSizeLimit = 33, // Invalid loaded accounts data size limit
    
}

fn analyze_transaction_impact(meta: &TransactionStatusMeta) -> TransactionAnalysis {
    let succeeded = meta.err.is_none();
    let balance_changes: Vec<i64> = meta.pre_balances.iter()
        .zip(meta.post_balances.iter())
        .map(|(pre, post)| *post as i64 - *pre as i64)
        .collect();
        
    let token_transfers = meta.pre_token_balances.iter()
        .zip(meta.post_token_balances.iter())
        .filter(|(pre, post)| pre.amount != post.amount)
        .count();
        
    TransactionAnalysis {
        success: succeeded,
        fee_paid: meta.fee,
        sol_transfers: balance_changes,
        token_transfer_count: token_transfers,
        has_cpi: !meta.inner_instructions.is_empty()
    }
}

pub struct InnerInstructions {
    pub index: u32,
    pub instructions: Vec<InnerInstruction>,
}
 
pub struct InnerInstruction {
    pub program_id_index: u32,
    pub accounts: Vec<u8>,
    pub data: Vec<u8>,
    /// Invocation stack height of an inner instruction.
    /// Available since Solana v1.14.6
    pub stack_height: Option<u32>,
}

fn analyze_cpi_calls(inner_instructions: &InnerInstructions) -> CPIAnalysis {
    let total_calls = inner_instructions.instructions.len();
    let max_stack_height = inner_instructions.instructions
        .iter()
        .filter_map(|ix| ix.stack_height)
        .max()
        .unwrap_or(0);
        
    let unique_programs: HashSet<_> = inner_instructions.instructions
        .iter()
        .map(|ix| ix.program_id_index)
        .collect();
        
    CPIAnalysis {
        parent_ix_index: inner_instructions.index,
        total_cpi_calls: total_calls,
        max_call_depth: max_stack_height,
        unique_programs: unique_programs.len(),
    }
}

// Example of a typical DeFi swap inner instructions pattern
let swap_instructions = InnerInstructions {
    index: 0,  // Main swap instruction
    instructions: vec![
        InnerInstruction {
            program_id_index: 5,  // Token program
            accounts: vec![0, 1, 2],  // Source, destination, authority
            data: vec![/* transfer data */],
            stack_height: Some(1)
        },
        InnerInstruction {
            program_id_index: 5,  // Token program
            accounts: vec![3, 4, 2],  // Other token accounts
            data: vec![/* transfer data */],
            stack_height: Some(1)
        }
    ]
};

pub struct InnerInstruction {
    pub program_id_index: u32,
    pub accounts: Vec<u8>,
    pub data: Vec<u8>,
    /// Invocation stack height of an inner instruction.
    /// Available since Solana v1.14.6
    pub stack_height: Option<u32>,
}

fn decode_inner_instruction(
    ix: &InnerInstruction,
    tx_accounts: &[Pubkey]
) -> DecodedInstruction {
    let program_id = tx_accounts[ix.program_id_index as usize];
    let account_addresses: Vec<Pubkey> = ix.accounts
        .iter()
        .map(|&idx| tx_accounts[idx as usize])
        .collect();
        
    match program_id {
        spl_token::ID => decode_token_instruction(&ix.data, &account_addresses),
        system_program::ID => decode_system_instruction(&ix.data, &account_addresses),
        _ => DecodedInstruction::Unknown
    }
}

// Example of a token transfer inner instruction
let token_transfer = InnerInstruction {
    program_id_index: 5,  // Token program
    accounts: vec![
        1,  // Source account
        2,  // Destination account
        3,  // Authority
    ],
    data: vec![/* Transfer instruction data */],
    stack_height: Some(1)
};
 
// Example of a system program create account instruction
let create_account = InnerInstruction {
    program_id_index: 0,  // System program
    accounts: vec![
        4,  // Funding account
        5,  // New account
    ],
    data: vec![/* CreateAccount instruction data */],
    stack_height: Some(1)
};

pub struct CompiledInstruction {
    pub program_id_index: u32,
    pub accounts: Vec<u8>,
    pub data: Vec<u8>,
}

fn decode_instruction(
    ix: &CompiledInstruction,
    account_keys: &[Pubkey]
) -> ProgramInstruction {
    let program_id = &account_keys[ix.program_id_index as usize];
    let accounts: Vec<&Pubkey> = ix.accounts
        .iter()
        .map(|&idx| &account_keys[idx as usize])
        .collect();
        
    match *program_id {
        // System Program instructions
        system_program::ID => {
            SystemInstruction::decode(&ix.data, &accounts)
        },
        // Token Program instructions
        spl_token::ID => {
            TokenInstruction::decode(&ix.data, &accounts)
        },
        _ => ProgramInstruction::Unknown
    }
}

// Example: Token Transfer Instruction
let token_transfer = CompiledInstruction {
    program_id_index: 4,  // Token program
    accounts: vec![
        1,  // Source token account
        2,  // Destination token account
        3,  // Owner's wallet
    ],
    data: vec![
        3,  // Transfer instruction discriminator
        // ... amount data ...
    ]
};
 
// Example: Create Account Instruction
let create_account = CompiledInstruction {
    program_id_index: 0,  // System program
    accounts: vec![
        1,  // Funding account
        2,  // New account address
    ],
    data: vec![
        0,  // CreateAccount instruction discriminator
        // ... space and lamport data ...
    ]
};

pub struct TokenBalance {
    pub account_index: u32,
    pub mint: String,
    pub ui_token_amount: Option<UiTokenAmount>,
    pub owner: String,
    pub program_id: String,
}
 
pub struct UiTokenAmount {
    pub ui_amount: f64,
    pub decimals: u32,
    pub amount: String,
    pub ui_amount_string: String,
}

fn analyze_token_balance_change(
    pre: &TokenBalance,
    post: &TokenBalance
) -> TokenBalanceChange {
    let pre_amount = pre.ui_token_amount.as_ref()
        .map(|amt| amt.ui_amount)
        .unwrap_or(0.0);
    let post_amount = post.ui_token_amount.as_ref()
        .map(|amt| amt.ui_amount)
        .unwrap_or(0.0);
        
    TokenBalanceChange {
        token_mint: pre.mint.clone(),
        owner: pre.owner.clone(),
        amount_change: post_amount - pre_amount,
        decimals: pre.ui_token_amount.as_ref()
            .map(|amt| amt.decimals)
            .unwrap_or(0)
    }
}

// USDC Balance Example
let usdc_balance = TokenBalance {
    account_index: 3,
    mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v".to_string(),
    ui_token_amount: Some(UiTokenAmount {
        ui_amount: 100.50,
        decimals: 6,
        amount: "100500000".to_string(),
        ui_amount_string: "100.500000".to_string()
    }),
    owner: "DjPi4sP9hPwV5kJQcevwSaS7oKvM9gQhSBr5XbxmrTHr".to_string(),
    program_id: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".to_string()
};
 
// NFT Balance Example
let nft_balance = TokenBalance {
    account_index: 4,
    mint: "CQNKXw1rw2eWwi812Exk4cKUjKuomZ2156STGRyXd2Mp".to_string(),
    ui_token_amount: Some(UiTokenAmount {
        ui_amount: 1.0,
        decimals: 0,
        amount: "1".to_string(),
        ui_amount_string: "1".to_string()
    }),
    owner: "DjPi4sP9hPwV5kJQcevwSaS7oKvM9gQhSBr5XbxmrTHr".to_string(),
    program_id: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".to_string()
};

pub struct Rewards {
    pub rewards: Vec<Reward>,
}
 
pub struct Reward {
    pub pubkey: String,
    pub lamports: i64,
    pub post_balance: u64,
    pub reward_type: i32,
    pub commission: String,
}
 

pub enum RewardType {
    Unspecified = 0,  // Default/unknown reward type
    Fee = 1,          // Transaction fee rewards
    Rent = 2,         // Rent collection rewards
    Staking = 3,      // Staking rewards for validators/delegators
    Voting = 4,       // Voting rewards for governance participation
}

fn analyze_rewards(rewards: &[Reward]) -> RewardAnalysis {
    let mut analysis = RewardAnalysis::default();
    
    for reward in rewards {
        match reward.reward_type {
            0 => { // Fee rewards
                analysis.total_fee_rewards += reward.lamports;
            },
            2 => { // Staking rewards
                analysis.total_staking_rewards += reward.lamports;
                analysis.validator_commissions.push((
                    reward.pubkey.clone(),
                    reward.commission.parse().unwrap_or(0)
                ));
            },
            _ => {
                analysis.other_rewards += reward.lamports;
            }
        }
    }
    
    analysis
}

// Validator Staking Reward
let staking_reward = Reward {
    pubkey: "Va1idator1111111111111111111111111111111111".to_string(),
    lamports: 1_500_000,  // 0.0015 SOL
    post_balance: 100_000_000_000,  // 100 SOL
    reward_type: 2,  // Staking
    commission: "10".to_string()  // 10% commission
};
 
// Transaction Fee Reward
let fee_reward = Reward {
    pubkey: "Co11ector1111111111111111111111111111111111".to_string(),
    lamports: 5000,  // 0.000005 SOL
    post_balance: 50_000_000_000,  // 50 SOL
    reward_type: 0,  // Fee
    commission: "".to_string()
};

pub struct ReturnData {
    pub program_id: Vec<u8>,
    pub data: Vec<u8>,
}

fn process_return_data(return_data: &ReturnData) -> ProgramReturnValue {
    let program = Pubkey::new(&return_data.program_id);
    
    match program {
        // Token Swap Program
        token_swap::ID => {
            decode_swap_return_data(&return_data.data)
        },
        // Oracle Program
        oracle::ID => {
            decode_price_feed_data(&return_data.data)
        },
        // Custom Program
        _ => ProgramReturnValue::Unknown
    }
}
 
// Example decoder for swap return data
fn decode_swap_return_data(data: &[u8]) -> SwapResult {
    SwapResult {
        amount_out: u64::from_le_bytes(data[0..8].try_into().unwrap()),
        success: data[8] == 1
    }
}

// Oracle price feed return data
let oracle_return = ReturnData {
    program_id: oracle_program_id.to_bytes().to_vec(),
    data: vec![
        // Price in cents (15.50 USD)
        1550u32.to_le_bytes().to_vec(),
        // Confidence interval
        10u32.to_le_bytes().to_vec(),
        // Timestamp
        1234567890u64.to_le_bytes().to_vec()
    ].concat()
};
 
// Token swap return data
let swap_return = ReturnData {
    program_id: swap_program_id.to_bytes().to_vec(),
    data: vec![
        // Amount received from swap
        1000000u64.to_le_bytes().to_vec(),
        // Minimum amount met flag
        vec![1u8]
    ].concat()
};