solana_sysvar/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![cfg_attr(feature = "frozen-abi", feature(min_specialization))]
3//! Access to special accounts with dynamically-updated data.
4//!
5//! Sysvars are special accounts that contain dynamically-updated data about the
6//! network cluster, the blockchain history, and the executing transaction. Each
7//! sysvar is defined in its own submodule within this module. The [`clock`],
8//! [`epoch_schedule`], and [`rent`] sysvars are most useful to on-chain
9//! programs.
10//!
11//! Simple sysvars implement the [`Sysvar::get`] method, which loads a sysvar
12//! directly from the runtime, as in this example that logs the `clock` sysvar:
13//!
14//! ```
15//! use solana_account_info::AccountInfo;
16//! use solana_msg::msg;
17//! use solana_sysvar::Sysvar;
18//! use solana_program_error::ProgramResult;
19//! use solana_pubkey::Pubkey;
20//!
21//! fn process_instruction(
22//!     program_id: &Pubkey,
23//!     accounts: &[AccountInfo],
24//!     instruction_data: &[u8],
25//! ) -> ProgramResult {
26//!     let clock = solana_clock::Clock::get()?;
27//!     msg!("clock: {:#?}", clock);
28//!     Ok(())
29//! }
30//! ```
31//!
32//! Since Solana sysvars are accounts, if the `AccountInfo` is provided to the
33//! program, then the program can deserialize the sysvar with
34//! [`SysvarSerialize::from_account_info`] to access its data, as in this example that
35//! again logs the [`clock`] sysvar.
36//!
37//! ```
38//! use solana_account_info::{AccountInfo, next_account_info};
39//! use solana_msg::msg;
40//! use solana_sysvar::{Sysvar, SysvarSerialize};
41//! use solana_program_error::ProgramResult;
42//! use solana_pubkey::Pubkey;
43//!
44//! fn process_instruction(
45//!     program_id: &Pubkey,
46//!     accounts: &[AccountInfo],
47//!     instruction_data: &[u8],
48//! ) -> ProgramResult {
49//!     let account_info_iter = &mut accounts.iter();
50//!     let clock_account = next_account_info(account_info_iter)?;
51//!     let clock = solana_clock::Clock::from_account_info(&clock_account)?;
52//!     msg!("clock: {:#?}", clock);
53//!     Ok(())
54//! }
55//! ```
56//!
57//! When possible, programs should prefer to call `Sysvar::get` instead of
58//! deserializing with `Sysvar::from_account_info`, as the latter imposes extra
59//! overhead of deserialization while also requiring the sysvar account address
60//! be passed to the program, wasting the limited space available to
61//! transactions. Deserializing sysvars that can instead be retrieved with
62//! `Sysvar::get` should be only be considered for compatibility with older
63//! programs that pass around sysvar accounts.
64//!
65//! Some sysvars are too large to deserialize within a program, and
66//! `Sysvar::from_account_info` returns an error, or the serialization attempt
67//! will exhaust the program's compute budget. Some sysvars do not implement
68//! `Sysvar::get` and return an error. Some sysvars have custom deserializers
69//! that do not implement the `Sysvar` trait. These cases are documented in the
70//! modules for individual sysvars.
71//!
72//! All sysvar accounts are owned by the account identified by [`sysvar::ID`].
73//!
74//! [`sysvar::ID`]: https://docs.rs/solana-sdk-ids/latest/solana_sdk_ids/sysvar/constant.ID.html
75//!
76//! For more details see the Solana [documentation on sysvars][sysvardoc].
77//!
78//! [sysvardoc]: https://docs.solanalabs.com/runtime/sysvars
79
80// hidden re-exports to make macros work
81pub mod __private {
82    #[cfg(target_os = "solana")]
83    pub use solana_define_syscall::definitions;
84    pub use {solana_program_entrypoint::SUCCESS, solana_program_error::ProgramError};
85}
86#[cfg(feature = "bincode")]
87use {solana_account_info::AccountInfo, solana_sysvar_id::SysvarId};
88use {solana_program_error::ProgramError, solana_pubkey::Pubkey};
89
90pub mod clock;
91pub mod epoch_rewards;
92pub mod epoch_schedule;
93pub mod fees;
94pub mod last_restart_slot;
95pub mod program_stubs;
96pub mod recent_blockhashes;
97pub mod rent;
98pub mod rewards;
99pub mod slot_hashes;
100pub mod slot_history;
101
102/// Return value indicating that the  `offset + length` is greater than the length of
103/// the sysvar data.
104//
105// Defined in the bpf loader as [`OFFSET_LENGTH_EXCEEDS_SYSVAR`](https://github.com/anza-xyz/agave/blob/master/programs/bpf_loader/src/syscalls/sysvar.rs#L172).
106const OFFSET_LENGTH_EXCEEDS_SYSVAR: u64 = 1;
107
108/// Return value indicating that the sysvar was not found.
109//
110// Defined in the bpf loader as [`SYSVAR_NOT_FOUND`](https://github.com/anza-xyz/agave/blob/master/programs/bpf_loader/src/syscalls/sysvar.rs#L171).
111const SYSVAR_NOT_FOUND: u64 = 2;
112
113/// Interface for loading a sysvar.
114pub trait Sysvar: Default + Sized {
115    /// Load the sysvar directly from the runtime.
116    ///
117    /// This is the preferred way to load a sysvar. Calling this method does not
118    /// incur any deserialization overhead, and does not require the sysvar
119    /// account to be passed to the program.
120    ///
121    /// Not all sysvars support this method. If not, it returns
122    /// [`ProgramError::UnsupportedSysvar`].
123    fn get() -> Result<Self, ProgramError> {
124        Err(ProgramError::UnsupportedSysvar)
125    }
126}
127
128#[cfg(feature = "bincode")]
129/// A type that holds sysvar data.
130pub trait SysvarSerialize:
131    Sysvar + SysvarId + serde::Serialize + serde::de::DeserializeOwned
132{
133    /// The size in bytes of the sysvar as serialized account data.
134    fn size_of() -> usize {
135        bincode::serialized_size(&Self::default()).unwrap() as usize
136    }
137
138    /// Deserializes the sysvar from its `AccountInfo`.
139    ///
140    /// # Errors
141    ///
142    /// If `account_info` does not have the same ID as the sysvar this function
143    /// returns [`ProgramError::InvalidArgument`].
144    fn from_account_info(account_info: &AccountInfo) -> Result<Self, ProgramError> {
145        if !Self::check_id(account_info.unsigned_key()) {
146            return Err(ProgramError::InvalidArgument);
147        }
148        bincode::deserialize(&account_info.data.borrow()).map_err(|_| ProgramError::InvalidArgument)
149    }
150
151    /// Serializes the sysvar to `AccountInfo`.
152    ///
153    /// # Errors
154    ///
155    /// Returns `None` if serialization failed.
156    fn to_account_info(&self, account_info: &mut AccountInfo) -> Option<()> {
157        bincode::serialize_into(&mut account_info.data.borrow_mut()[..], self).ok()
158    }
159}
160
161/// Implements the [`Sysvar::get`] method for both SBF and host targets.
162#[macro_export]
163macro_rules! impl_sysvar_get {
164    // DEPRECATED: This variant is only for the deprecated Fees sysvar and should be
165    // removed once Fees is no longer in use. It uses the old-style direct syscall
166    // approach instead of the new sol_get_sysvar syscall.
167    ($syscall_name:ident) => {
168        fn get() -> Result<Self, $crate::__private::ProgramError> {
169            let mut var = Self::default();
170            let var_addr = &mut var as *mut _ as *mut u8;
171
172            #[cfg(target_os = "solana")]
173            let result = unsafe { $crate::__private::definitions::$syscall_name(var_addr) };
174
175            #[cfg(not(target_os = "solana"))]
176            let result = $crate::program_stubs::$syscall_name(var_addr);
177
178            match result {
179                $crate::__private::SUCCESS => Ok(var),
180                // Unexpected errors are folded into `UnsupportedSysvar`.
181                _ => Err($crate::__private::ProgramError::UnsupportedSysvar),
182            }
183        }
184    };
185    ($sysvar_id:expr) => {
186        fn get() -> Result<Self, $crate::__private::ProgramError> {
187            // Allocate uninitialized memory for the sysvar struct
188            let mut uninit = core::mem::MaybeUninit::<Self>::uninit();
189            let size = core::mem::size_of::<Self>() as u64;
190            // Safety: we build a mutable slice pointing to the uninitialized
191            // buffer.  The `get_sysvar` syscall will fill exactly `size`
192            // bytes, after which the buffer is fully initialised.
193            let dst = unsafe {
194                core::slice::from_raw_parts_mut(uninit.as_mut_ptr() as *mut u8, size as usize)
195            };
196            // Attempt to load the sysvar data using the provided sysvar id.
197            $crate::get_sysvar(dst, &$sysvar_id, 0, size)?;
198            // Safety: `get_sysvar` succeeded and initialised the buffer.
199            let var = unsafe { uninit.assume_init() };
200            Ok(var)
201        }
202    };
203}
204
205/// Handler for retrieving a slice of sysvar data from the `sol_get_sysvar`
206/// syscall.
207pub fn get_sysvar(
208    dst: &mut [u8],
209    sysvar_id: &Pubkey,
210    offset: u64,
211    length: u64,
212) -> Result<(), solana_program_error::ProgramError> {
213    // Check that the provided destination buffer is large enough to hold the
214    // requested data.
215    if dst.len() < length as usize {
216        return Err(solana_program_error::ProgramError::InvalidArgument);
217    }
218
219    let sysvar_id = sysvar_id as *const _ as *const u8;
220    let var_addr = dst as *mut _ as *mut u8;
221
222    #[cfg(target_os = "solana")]
223    let result = unsafe {
224        solana_define_syscall::definitions::sol_get_sysvar(sysvar_id, var_addr, offset, length)
225    };
226
227    #[cfg(not(target_os = "solana"))]
228    let result = crate::program_stubs::sol_get_sysvar(sysvar_id, var_addr, offset, length);
229
230    match result {
231        solana_program_entrypoint::SUCCESS => Ok(()),
232        OFFSET_LENGTH_EXCEEDS_SYSVAR => Err(solana_program_error::ProgramError::InvalidArgument),
233        SYSVAR_NOT_FOUND => Err(solana_program_error::ProgramError::UnsupportedSysvar),
234        // Unexpected errors are folded into `UnsupportedSysvar`.
235        _ => Err(solana_program_error::ProgramError::UnsupportedSysvar),
236    }
237}
238
239#[cfg(test)]
240mod tests {
241    use {
242        super::*,
243        crate::program_stubs::{set_syscall_stubs, SyscallStubs},
244        serde_derive::{Deserialize, Serialize},
245        solana_program_entrypoint::SUCCESS,
246        solana_program_error::ProgramError,
247        solana_pubkey::Pubkey,
248        std::{cell::RefCell, rc::Rc},
249    };
250
251    #[repr(C)]
252    #[derive(Serialize, Deserialize, Debug, Default, PartialEq, Eq)]
253    struct TestSysvar {
254        something: Pubkey,
255    }
256    solana_pubkey::declare_id!("TestSysvar111111111111111111111111111111111");
257    impl solana_sysvar_id::SysvarId for TestSysvar {
258        fn id() -> solana_pubkey::Pubkey {
259            id()
260        }
261
262        fn check_id(pubkey: &solana_pubkey::Pubkey) -> bool {
263            check_id(pubkey)
264        }
265    }
266    impl Sysvar for TestSysvar {}
267    impl SysvarSerialize for TestSysvar {}
268
269    // NOTE tests that use this mock MUST carry the #[serial] attribute
270    struct MockGetSysvarSyscall {
271        data: Vec<u8>,
272    }
273    impl SyscallStubs for MockGetSysvarSyscall {
274        #[allow(clippy::arithmetic_side_effects)]
275        fn sol_get_sysvar(
276            &self,
277            _sysvar_id_addr: *const u8,
278            var_addr: *mut u8,
279            offset: u64,
280            length: u64,
281        ) -> u64 {
282            let slice = unsafe { std::slice::from_raw_parts_mut(var_addr, length as usize) };
283            slice.copy_from_slice(&self.data[offset as usize..(offset + length) as usize]);
284            SUCCESS
285        }
286    }
287    pub fn mock_get_sysvar_syscall(data: &[u8]) {
288        set_syscall_stubs(Box::new(MockGetSysvarSyscall {
289            data: data.to_vec(),
290        }));
291    }
292
293    /// Convert a value to its in-memory byte representation.
294    ///
295    /// Safety: This relies on the type's plain old data layout. Intended for tests.
296    pub fn to_bytes<T>(value: &T) -> Vec<u8> {
297        unsafe {
298            let size = core::mem::size_of::<T>();
299            let ptr = (value as *const T) as *const u8;
300            let mut data = vec![0u8; size];
301            std::ptr::copy_nonoverlapping(ptr, data.as_mut_ptr(), size);
302            data
303        }
304    }
305
306    #[test]
307    fn test_sysvar_account_info_to_from() {
308        let test_sysvar = TestSysvar::default();
309        let key = id();
310        let wrong_key = Pubkey::new_unique();
311        let owner = Pubkey::new_unique();
312        let mut lamports = 42;
313        let mut data = vec![0_u8; TestSysvar::size_of()];
314        let mut account_info =
315            AccountInfo::new(&key, false, true, &mut lamports, &mut data, &owner, false);
316
317        test_sysvar.to_account_info(&mut account_info).unwrap();
318        let new_test_sysvar = TestSysvar::from_account_info(&account_info).unwrap();
319        assert_eq!(test_sysvar, new_test_sysvar);
320
321        account_info.key = &wrong_key;
322        assert_eq!(
323            TestSysvar::from_account_info(&account_info),
324            Err(ProgramError::InvalidArgument)
325        );
326
327        let mut small_data = vec![];
328        account_info.data = Rc::new(RefCell::new(&mut small_data));
329        assert_eq!(test_sysvar.to_account_info(&mut account_info), None);
330    }
331}
solana_sysvar/lib.rs

solana_sysvar/
lib.rs
