diff --git a/docs/src/developing/programming-model/accounts.md b/docs/src/developing/programming-model/accounts.md index a53b3e697f..283252806e 100644 --- a/docs/src/developing/programming-model/accounts.md +++ b/docs/src/developing/programming-model/accounts.md @@ -106,11 +106,14 @@ To check an account's validity, the program should either check the account's address against a known value or check that the account is indeed owned correctly (usually owned by the program itself). -One example is when programs read a sysvar. Unless the program checks the -address or owner, it's impossible to be sure whether it's a real and valid -sysvar merely by successful deserialization. Accordingly, the Solana SDK [checks -the sysvar's validity during +One example is when programs use a sysvar account. Unless the program checks the +account's address or owner, it's impossible to be sure whether it's a real and +valid sysvar account merely by successful deserialization of the account's data. +Accordingly, the Solana SDK [checks the sysvar account's validity during deserialization](https://github.com/solana-labs/solana/blob/a95675a7ce1651f7b59443eb146b356bc4b3f374/sdk/program/src/sysvar/mod.rs#L65). +A alternative and safer way to read a sysvar is via the sysvar's [`get()` +function](https://github.com/solana-labs/solana/blob/64bfc14a75671e4ec3fe969ded01a599645080eb/sdk/program/src/sysvar/mod.rs#L73) +which doesn't require these checks. If the program always modifies the account in question, the address/owner check isn't required because modifying an unowned (could be the malicious account with diff --git a/docs/src/developing/runtime-facilities/sysvars.md b/docs/src/developing/runtime-facilities/sysvars.md index 1c2f05dacd..6eb4265fad 100644 --- a/docs/src/developing/runtime-facilities/sysvars.md +++ b/docs/src/developing/runtime-facilities/sysvars.md @@ -9,11 +9,24 @@ known addresses published along with the account layouts in the crate](https://docs.rs/solana-program/VERSION_FOR_DOCS_RS/solana_program/sysvar/index.html), and outlined below. -To include sysvar data in program operations, pass the sysvar account address in -the list of accounts in a transaction. The account can be read in your -instruction processor like any other account. Access to sysvars accounts is +There are two ways for a program to access a sysvar. + +The first is to query the sysvar at runtime via the sysvar's `get()` function: + +``` +let clock = Clock::get() +``` + +The second is to pass the sysvar to the program as an account by including its address as one of the accounts in the `Instruction` and then deserializing the data during execution. Access to sysvars accounts is always _readonly_. +``` +let clock_sysvar_info = next_account_info(account_info_iter)?; +let clock = Clock::from_account_info(&clock_sysvar_info)?; +``` + +The first method is more efficient and does not require that the sysvar account be passed to the program, or specified in the `Instruction` the program is processing. + ## Clock The Clock sysvar contains data on cluster time, including the current slot, diff --git a/docs/src/terminology.md b/docs/src/terminology.md index b20ed9c731..ea358deed3 100644 --- a/docs/src/terminology.md +++ b/docs/src/terminology.md @@ -255,7 +255,7 @@ Tokens forfeit to the [cluster](terminology.md#cluster) if malicious [validator] ## sysvar -A synthetic [account](terminology.md#account) provided by the runtime to allow programs to access network state such as current tick height, rewards [points](terminology.md#point) values, etc. +A synthetic [account](terminology.md#account) maintained by the runtime and provided to programs which provide cluster state such as current tick height, rewards [points](terminology.md#point) values, etc. Sysvars can either be [passed to the program as an account or queried by the program via a syscall](developing/runtime-facilities/sysvars.md). ## thin client