clone_solana_message/
lib.rs

1#![cfg_attr(docsrs, feature(doc_auto_cfg))]
2#![cfg_attr(feature = "frozen-abi", feature(min_specialization))]
3//! Sequences of [`Instruction`]s executed within a single transaction.
4//!
5//! [`Instruction`]: https://docs.rs/solana-instruction/latest/clone_solana_instruction/struct.Instruction.html
6//!
7//! In Solana, programs execute instructions, and clients submit sequences
8//! of instructions to the network to be atomically executed as [`Transaction`]s.
9//!
10//! [`Transaction`]: https://docs.rs/solana-sdk/latest/solana-sdk/transaction/struct.Transaction.html
11//!
12//! A [`Message`] is the compact internal encoding of a transaction, as
13//! transmitted across the network and stored in, and operated on, by the
14//! runtime. It contains a flat array of all accounts accessed by all
15//! instructions in the message, a [`MessageHeader`] that describes the layout
16//! of that account array, a [recent blockhash], and a compact encoding of the
17//! message's instructions.
18//!
19//! [recent blockhash]: https://solana.com/docs/core/transactions#recent-blockhash
20//!
21//! Clients most often deal with `Instruction`s and `Transaction`s, with
22//! `Message`s being created by `Transaction` constructors.
23//!
24//! To ensure reliable network delivery, serialized messages must fit into the
25//! IPv6 MTU size, conservatively assumed to be 1280 bytes. Thus constrained,
26//! care must be taken in the amount of data consumed by instructions, and the
27//! number of accounts they require to function.
28//!
29//! This module defines two versions of `Message` in their own modules:
30//! [`legacy`] and [`v0`]. `legacy` is reexported here and is the current
31//! version as of Solana 1.10.0. `v0` is a [future message format] that encodes
32//! more account keys into a transaction than the legacy format. The
33//! [`VersionedMessage`] type is a thin wrapper around either message version.
34//!
35//! [future message format]: https://docs.solanalabs.com/proposals/versioned-transactions
36//!
37//! Despite living in the `solana-program` crate, there is no way to access the
38//! runtime's messages from within a Solana program, and only the legacy message
39//! types continue to be exposed to Solana programs, for backwards compatibility
40//! reasons.
41
42pub mod compiled_instruction;
43mod compiled_keys;
44pub mod inner_instruction;
45pub mod legacy;
46#[cfg(feature = "frozen-abi")]
47use clone_solana_frozen_abi_macro::AbiExample;
48#[cfg(feature = "serde")]
49use serde_derive::{Deserialize, Serialize};
50
51#[cfg(not(target_os = "solana"))]
52#[path = ""]
53mod non_bpf_modules {
54    mod account_keys;
55    mod address_loader;
56    mod sanitized;
57    mod versions;
58
59    pub use {account_keys::*, address_loader::*, sanitized::*, versions::*};
60}
61
62#[cfg(not(target_os = "solana"))]
63pub use non_bpf_modules::*;
64pub use {compiled_keys::CompileError, legacy::Message};
65
66/// The length of a message header in bytes.
67pub const MESSAGE_HEADER_LENGTH: usize = 3;
68
69/// Describes the organization of a `Message`'s account keys.
70///
71/// Every [`Instruction`] specifies which accounts it may reference, or
72/// otherwise requires specific permissions of. Those specifications are:
73/// whether the account is read-only, or read-write; and whether the account
74/// must have signed the transaction containing the instruction.
75///
76/// Whereas individual `Instruction`s contain a list of all accounts they may
77/// access, along with their required permissions, a `Message` contains a
78/// single shared flat list of _all_ accounts required by _all_ instructions in
79/// a transaction. When building a `Message`, this flat list is created and
80/// `Instruction`s are converted to [`CompiledInstruction`]s. Those
81/// `CompiledInstruction`s then reference by index the accounts they require in
82/// the single shared account list.
83///
84/// [`Instruction`]: https://docs.rs/solana-instruction/latest/clone_solana_instruction/struct.Instruction.html
85/// [`CompiledInstruction`]: crate::compiled_instruction::CompiledInstruction
86///
87/// The shared account list is ordered by the permissions required of the accounts:
88///
89/// - accounts that are writable and signers
90/// - accounts that are read-only and signers
91/// - accounts that are writable and not signers
92/// - accounts that are read-only and not signers
93///
94/// Given this ordering, the fields of `MessageHeader` describe which accounts
95/// in a transaction require which permissions.
96///
97/// When multiple transactions access the same read-only accounts, the runtime
98/// may process them in parallel, in a single [PoH] entry. Transactions that
99/// access the same read-write accounts are processed sequentially.
100///
101/// [PoH]: https://docs.solanalabs.com/consensus/synchronization
102#[cfg_attr(feature = "frozen-abi", derive(AbiExample))]
103#[cfg_attr(
104    feature = "serde",
105    derive(Deserialize, Serialize),
106    serde(rename_all = "camelCase")
107)]
108#[derive(Default, Debug, PartialEq, Eq, Clone, Copy)]
109pub struct MessageHeader {
110    /// The number of signatures required for this message to be considered
111    /// valid. The signers of those signatures must match the first
112    /// `num_required_signatures` of [`Message::account_keys`].
113    // NOTE: Serialization-related changes must be paired with the direct read at sigverify.
114    pub num_required_signatures: u8,
115
116    /// The last `num_readonly_signed_accounts` of the signed keys are read-only
117    /// accounts.
118    pub num_readonly_signed_accounts: u8,
119
120    /// The last `num_readonly_unsigned_accounts` of the unsigned keys are
121    /// read-only accounts.
122    pub num_readonly_unsigned_accounts: u8,
123}
124
125/// The definition of address lookup table accounts.
126///
127/// As used by the `crate::v0` message format.
128#[derive(Debug, PartialEq, Eq, Clone)]
129pub struct AddressLookupTableAccount {
130    pub key: clone_solana_pubkey::Pubkey,
131    pub addresses: Vec<clone_solana_pubkey::Pubkey>,
132}
clone_solana_message/lib.rs

clone_solana_message/
lib.rs
