Skip to content

Instructions

Instructions

An Instruction is the fundamental building block of a Solana transaction. Each instruction invokes a Program to perform a specific operation. A transaction can contain multiple instructions, which are executed sequentially and atomically.

Instruction Structure

An instruction consists of three core components:

1. Program ID - The address of the program to invoke - Examples: System Program, Token Program, custom programs

2. Account List (Accounts) All accounts the instruction needs to access, each containing: - Pubkey: Account address - is_signer: Whether a signature is required - is_writable: Whether the account is writable

3. Instruction Data - Parameters passed to the program - A serialized byte array - The program executes different operations based on the data

Instruction Example

Transfer Instruction 

let instruction = solana_sdk::system_instruction::transfer(
    &sender_pubkey,
    &receiver_pubkey,
    lamports,
);

This instruction contains: - Program ID: System Program - Accounts: sender (writable, signer), receiver (writable) - Data: Transfer amount

Account Permissions

Permission flags for accounts in an instruction:

is_signer - Requires the account holder to sign - Used for authorization verification - Typically a user wallet or PDA

is_writable - Account data can be modified - Lamports balance may change - Read-only accounts can be accessed in parallel

Permission Example 

AccountMeta {
    pubkey: user_account,
    is_signer: true,   // Requires signature
    is_writable: true,  // Writable
}

Instruction Execution

Sequential Execution Instructions in a transaction are executed in the order they are defined: 1. First instruction 2. Second instruction 3. ...

If any instruction fails, the entire transaction is rolled back.

Account Locking During execution, Solana locks the accounts involved in instructions: - Writable accounts are exclusively locked - Read-only accounts can be shared across multiple instructions

This enables Solana to execute non-conflicting transactions in parallel.

Cross-Program Invocation (CPI)

Programs can invoke other programs within an instruction:

invoke(
    &instruction,
    &[account1, account2, account3],
)?;

CPI Characteristics - Call depth limited to 4 levels - The called program inherits the caller's permissions - Can sign via PDA

CPI Use Cases - Token transfers - Calling oracles for price data - Composing multiple DeFi protocols

Common Instruction Types

1. System Instructions - Create accounts - Transfer SOL - Allocate space - Assign owner

2. Token Instructions - Initialize tokens - Mint tokens - Transfer tokens - Burn tokens

3. Custom Instructions Developer-defined program instructions: 

pub enum MyInstruction {
    Initialize { amount: u64 },
    Deposit { amount: u64 },
    Withdraw { amount: u64 },
}

Instruction Data Serialization

Borsh Serialization Solana recommends using the Borsh format: 

#[derive(BorshSerialize, BorshDeserialize)]
pub struct InitializeData {
    pub amount: u64,
    pub authority: Pubkey,
}

Manual Serialization 

let mut data = vec![0]; // Instruction identifier
data.extend_from_slice(&amount.to_le_bytes());

Instruction Optimization

1. Reduce Account Count - Merge related accounts - Use PDAs to store multiple data items

2. Batch Operations - Handle multiple operations in a single instruction - Reduce CPI calls

3. Pre-load Accounts - Validate accounts in advance - Reduce redundant checks

Best Practices

1. Specify Account Permissions Clearly Only mark necessary accounts as writable or signer to improve parallelism.

2. Validate Input Check the following within your program: - Account owner - Account data validity - Permission correctness

3. Error Handling Return clear error messages: 

if !user.is_signer {
    return Err(ProgramError::MissingRequiredSignature);
}

  • Transaction: An atomic operation unit containing one or more instructions
  • Program: The target invoked by instructions, executing business logic
  • CPI (Cross-Program Invocation): Calling other programs within an instruction
  • Account: Data and state storage operated on by instructions