solana_program/sysvar/
mod.rs

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

solana_program/sysvar/
mod.rs
