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 wincode to access
34//! its data, as in this example that again logs the [`clock`] sysvar.
35//!
36//! ```
37//! use solana_account_info::{AccountInfo, next_account_info};
38//! use solana_clock::Clock;
39//! use solana_msg::msg;
40//! use solana_program_error::{ProgramError, ProgramResult};
41//! use solana_pubkey::Pubkey;
42//! use solana_sdk_ids::sysvar::clock;
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//!     if !clock::check_id(clock_account.key) {
52//!         return Err(ProgramError::InvalidArgument);
53//!     }
54//!     let clock: Clock = wincode::deserialize(&clock_account.data.borrow())
55//!         .map_err(|_| ProgramError::InvalidArgument)?;
56//!     msg!("clock: {:#?}", clock);
57//!     Ok(())
58//! }
59//! ```
60//!
61//! When possible, programs should prefer to call `Sysvar::get` instead of
62//! deserializing with wincode, 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//! deserializing them may exhaust the program's compute budget. Some sysvars do
71//! not implement `Sysvar::get` and return an error. Some sysvars have custom deserializers
72//! that do not implement the `Sysvar` trait. These cases are documented in the
73//! modules for individual sysvars.
74//!
75//! All sysvar accounts are owned by the account identified by [`sysvar::ID`].
76//!
77//! [`sysvar::ID`]: https://docs.rs/solana-sdk-ids/latest/solana_sdk_ids/sysvar/constant.ID.html
78//!
79//! For more details see the Solana [documentation on sysvars][sysvardoc].
80//!
81//! [sysvardoc]: https://docs.solanalabs.com/runtime/sysvars
82
83pub use solana_get_sysvar::{get_sysvar, impl_get_sysvar as impl_sysvar_get, GetSysvar as Sysvar};
84
85pub mod clock;
86pub mod epoch_rewards;
87pub mod epoch_schedule;
88pub mod fees;
89pub mod last_restart_slot;
90pub mod program_stubs;
91pub mod recent_blockhashes;
92pub mod rent;
93pub mod rewards;
94pub mod slot_hashes;
95pub mod slot_history;
96pub mod stake_history;
solana_sysvar/lib.rs

solana_sysvar/
lib.rs
