Struct Instruction

pub struct Instruction {
    pub program_id: Pubkey,
    pub accounts: Vec<AccountMeta>,
    pub data: Vec<u8>,
}

A directive for a single invocation of a Solana program.

An instruction specifies which program it is calling, which accounts it may read or modify, and additional data that serves as input to the program. One or more instructions are included in transactions submitted by Solana clients. Instructions are also used to describe cross-program invocations.

During execution, a program will receive a list of account data as one of its arguments, in the same order as specified during Instruction construction.

While Solana is agnostic to the format of the instruction data, it has built-in support for serialization via borsh and bincode.

Specifying account metadata

When constructing an Instruction, a list of all accounts that may be read or written during the execution of that instruction must be supplied as AccountMeta values.

Any account whose data may be mutated by the program during execution must be specified as writable. During execution, writing to an account that was not specified as writable will cause the transaction to fail. Writing to an account that is not owned by the program will cause the transaction to fail.

Any account whose lamport balance may be mutated by the program during execution must be specified as writable. During execution, mutating the lamports of an account that was not specified as writable will cause the transaction to fail. While subtracting lamports from an account not owned by the program will cause the transaction to fail, adding lamports to any account is allowed, as long is it is mutable.

Accounts that are not read or written by the program may still be specified in an Instruction’s account list. These will affect scheduling of program execution by the runtime, but will otherwise be ignored.

When building a transaction, the Solana runtime coalesces all accounts used by all instructions in that transaction, along with accounts and permissions required by the runtime, into a single account list. Some accounts and account permissions required by the runtime to process a transaction are not required to be included in an Instructions account list. These include:

• The program ID — it is a separate field of Instruction
• The transaction’s fee-paying account — it is added during Message construction. A program may still require the fee payer as part of the account list if it directly references it.

Programs may require signatures from some accounts, in which case they should be specified as signers during Instruction construction. The program must still validate during execution that the account is a signer.

Fields

program_id: Pubkey

Pubkey of the program that executes this instruction.

accounts: Vec<AccountMeta>

Metadata describing accounts that should be passed to the program.

data: Vec<u8>

Opaque data passed to the program for its own interpretation.

Implementations

impl Instruction

pub fn new_with_borsh<T>( program_id: Pubkey, data: &T, accounts: Vec<AccountMeta>, ) -> Instruction

where T: BorshSerialize,

Create a new instruction from a value, encoded with borsh.

program_id is the address of the program that will execute the instruction. accounts contains a description of all accounts that may be accessed by the program.

Borsh serialization is often preferred over bincode as it has a stable specification and an implementation in JavaScript, neither of which are true of bincode.

Examples

#[derive(BorshSerialize, BorshDeserialize)]
pub struct MyInstruction {
    pub lamports: u64,
}

pub fn create_instruction(
    program_id: &Pubkey,
    from: &Pubkey,
    to: &Pubkey,
    lamports: u64,
) -> Instruction {
    let instr = MyInstruction { lamports };

    Instruction::new_with_borsh(
        *program_id,
        &instr,
        vec![
            AccountMeta::new(*from, true),
            AccountMeta::new(*to, false),
        ],
   )
}

pub fn new_with_bincode<T>( program_id: Pubkey, data: &T, accounts: Vec<AccountMeta>, ) -> Instruction

where T: Serialize,

Create a new instruction from a value, encoded with bincode.

program_id is the address of the program that will execute the instruction. accounts contains a description of all accounts that may be accessed by the program.

Examples

#[derive(Serialize, Deserialize)]
pub struct MyInstruction {
    pub lamports: u64,
}

pub fn create_instruction(
    program_id: &Pubkey,
    from: &Pubkey,
    to: &Pubkey,
    lamports: u64,
) -> Instruction {
    let instr = MyInstruction { lamports };

    Instruction::new_with_bincode(
        *program_id,
        &instr,
        vec![
            AccountMeta::new(*from, true),
            AccountMeta::new(*to, false),
        ],
   )
}

pub fn new_with_bytes( program_id: Pubkey, data: &[u8], accounts: Vec<AccountMeta>, ) -> Instruction

Create a new instruction from a byte slice.

program_id is the address of the program that will execute the instruction. accounts contains a description of all accounts that may be accessed by the program.

The caller is responsible for ensuring the correct encoding of data as expected by the callee program.

Examples

#[derive(BorshSerialize, BorshDeserialize)]
pub struct MyInstruction {
    pub lamports: u64,
}

pub fn create_instruction(
    program_id: &Pubkey,
    from: &Pubkey,
    to: &Pubkey,
    lamports: u64,
) -> Result<Instruction, Error> {
    let instr = MyInstruction { lamports };

    let mut instr_in_bytes: Vec<u8> = Vec::new();
    instr.serialize(&mut instr_in_bytes)?;

    Ok(Instruction::new_with_bytes(
        *program_id,
        &instr_in_bytes,
        vec![
            AccountMeta::new(*from, true),
            AccountMeta::new(*to, false),
        ],
   ))
}

Trait Implementations

impl Clone for Instruction

fn clone(&self) -> Instruction

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Instruction

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Instruction

fn deserialize<__D>( __deserializer: __D, ) -> Result<Instruction, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Instruction

fn eq(&self, other: &Instruction) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Instruction

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Instruction

impl StructuralPartialEq for Instruction