Struct solana_sdk::instruction::Instruction

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

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, Global>

Metadata describing accounts that should be passed to the program.

data: Vec<u8, Global>

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, Global>
) -> Instructionwhere
    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 prefered 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, Global>
) -> Instructionwhere
    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, Global>
) -> 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> {
    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),
        ],
   ))
}

pub fn new<T>(
    program_id: Pubkey,
    data: &T,
    accounts: Vec<AccountMeta, Global>
) -> Instructionwhere
    T: Serialize,

👎Deprecated since 1.6.0: Please use another Instruction constructor instead, such as Instruction::new_with_borsh

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 FromWasmAbi for Instruction

type Abi = u32

The wasm ABI type that this converts from when coming back out from the ABI boundary.

unsafe fn from_abi(js: u32) -> Instruction

Recover a Self from Self::Abi.

impl IntoWasmAbi for Instruction

type Abi = u32

The wasm ABI type that this converts into when crossing the ABI boundary.

fn into_abi(self) -> u32

Convert self into Self::Abi so that it can be sent across the wasm ABI boundary.

impl OptionFromWasmAbi for Instruction

fn is_none(abi: &<Instruction as FromWasmAbi>::Abi) -> bool

Tests whether the argument is a “none” instance. If so it will be deserialized as None, and otherwise it will be passed to FromWasmAbi.

impl OptionIntoWasmAbi for Instruction

fn none() -> <Instruction as IntoWasmAbi>::Abi

Returns an ABI instance indicating “none”, which JS will interpret as the None branch of this option.

impl PartialEq<Instruction> for Instruction

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl RefFromWasmAbi for Instruction

type Abi = u32

The wasm ABI type references to Self are recovered from.

type Anchor = Ref<'static, Instruction>

The type that holds the reference to Self for the duration of the invocation of the function that has an &Self parameter. This is required to ensure that the lifetimes don’t persist beyond one function call, and so that they remain anonymous.

unsafe fn ref_from_abi(
    js: <Instruction as RefFromWasmAbi>::Abi
) -> <Instruction as RefFromWasmAbi>::Anchor

Recover a Self::Anchor from Self::Abi.

impl RefMutFromWasmAbi for Instruction

type Abi = u32

Same as RefFromWasmAbi::Abi

type Anchor = RefMut<'static, Instruction>

Same as RefFromWasmAbi::Anchor

unsafe fn ref_mut_from_abi(
    js: <Instruction as RefMutFromWasmAbi>::Abi
) -> <Instruction as RefMutFromWasmAbi>::Anchor

Same as RefFromWasmAbi::ref_from_abi

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 StructuralPartialEq for Instruction