get-sysvar: extract sol_get_sysvar from solana-sysvar

Author: grod220

Cargo.lock

@@ -35,6 +35,7 @@ members = [
     "frozen-abi",
     "frozen-abi-macro",
     "genesis-config",
+    "get-sysvar",
     "hard-forks",
     "hash",
     "hash-512",
@@ -262,6 +263,7 @@ solana-file-download = { path = "file-download", version = "3.0.0" }
 solana-frozen-abi = { path = "frozen-abi", version = "3.5.0" }
 solana-frozen-abi-macro = { path = "frozen-abi-macro", version = "3.5.0", default-features = false }
 solana-genesis-config = { path = "genesis-config", version = "4.0.0" }
+solana-get-sysvar = { path = "get-sysvar", version = "0.0.0" }
 solana-hard-forks = { path = "hard-forks", version = "3.1.0", default-features = false }
 solana-hash = { path = "hash", version = "4.4.0", default-features = false }
 solana-hash-512 = { path = "hash-512", version = "1.1.0", default-features = false }

Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "solana-get-sysvar"
+description = "Reads Solana sysvar account data from the runtime."
+documentation = "https://docs.rs/solana-get-sysvar"
+version = "0.0.0"
+authors = { workspace = true }
+repository = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+edition = { workspace = true }
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+all-features = true
+
+[features]
+default = []
+std = []
+
+[dependencies]
+solana-address = { workspace = true }
+solana-program-error = { workspace = true }
+
+[target.'cfg(target_os = "solana")'.dependencies]
+solana-define-syscall = { workspace = true }
+
+[lints]
+workspace = true

get-sysvar/Cargo.toml

@@ -0,0 +1,102 @@
+//! Access to the `sol_get_sysvar` syscall, used to fetch sysvar data from the runtime.
+//!
+//! On-chain calls go directly to the syscall. Off-chain calls are routed through a
+//! stub which test harnesses can install with [`set_get_sysvar_stub`] to serve mock
+//! sysvar data.
+#![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
+#[cfg(all(not(target_os = "solana"), feature = "std"))]
+extern crate std;
+
+use {solana_address::Address, solana_program_error::ProgramError};
+
+#[cfg(all(not(target_os = "solana"), feature = "std"))]
+mod stubs;
+
+#[cfg(all(not(target_os = "solana"), feature = "std"))]
+pub use stubs::{clear_get_sysvar_stub, set_get_sysvar_stub, GetSysvarStub};
+
+/// Syscall success code.
+//
+// Defined in solana-program-entrypoint as [`SUCCESS`](https://github.com/anza-xyz/solana-sdk/blob/program-entrypoint@v2.2.1/program-entrypoint/src/lib.rs#L35).
+const SUCCESS: u64 = 0;
+/// Return value indicating that the  `offset + length` is greater than the length of
+/// the sysvar data.
+//
+// Defined in the Agave syscalls crate as [`OFFSET_LENGTH_EXCEEDS_SYSVAR`](https://github.com/anza-xyz/agave/blob/v4.0.2/syscalls/src/sysvar.rs#L180).
+const OFFSET_LENGTH_EXCEEDS_SYSVAR: u64 = 1;
+
+/// Return value indicating that the sysvar was not found.
+//
+// Defined in the Agave syscalls crate as [`SYSVAR_NOT_FOUND`](https://github.com/anza-xyz/agave/blob/v4.0.2/syscalls/src/sysvar.rs#L179).
+const SYSVAR_NOT_FOUND: u64 = 2;
+
+/// Handler for retrieving a slice of sysvar data from the `sol_get_sysvar`
+/// syscall.
+pub fn get_sysvar(
+    dst: &mut [u8],
+    sysvar_id: &Address,
+    offset: u64,
+    length: u64,
+) -> Result<(), ProgramError> {
+    // Check that the provided destination buffer is large enough to hold the requested data
+    if dst.len() < length as usize {
+        return Err(ProgramError::InvalidArgument);
+    }
+
+    let sysvar_id = sysvar_id as *const _ as *const u8;
+    let var_addr = dst as *mut _ as *mut u8;
+
+    match sol_get_sysvar(sysvar_id, var_addr, offset, length) {
+        SUCCESS => Ok(()),
+        OFFSET_LENGTH_EXCEEDS_SYSVAR => Err(ProgramError::InvalidArgument),
+        _ => Err(ProgramError::UnsupportedSysvar),
+    }
+}
+
+/// Internal helper for retrieving sysvar data directly into a raw buffer.
+///
+/// # Safety
+///
+/// This function bypasses the slice-length check that `get_sysvar` performs.
+/// The caller must ensure that `var_addr` points to a writable buffer of at
+/// least `length` bytes. This is typically used with `MaybeUninit` to load
+/// compact representations of sysvars.
+#[doc(hidden)]
+pub unsafe fn get_sysvar_unchecked(
+    var_addr: *mut u8,
+    sysvar_id: *const u8,
+    offset: u64,
+    length: u64,
+) -> Result<(), ProgramError> {
+    match sol_get_sysvar(sysvar_id, var_addr, offset, length) {
+        SUCCESS => Ok(()),
+        OFFSET_LENGTH_EXCEEDS_SYSVAR => Err(ProgramError::InvalidArgument),
+        SYSVAR_NOT_FOUND => Err(ProgramError::UnsupportedSysvar),
+        // Unexpected errors are folded into `UnsupportedSysvar`.
+        _ => Err(ProgramError::UnsupportedSysvar),
+    }
+}
+
+// Dispatch to the syscall backend available for this target and feature set
+fn sol_get_sysvar(sysvar_id: *const u8, var_addr: *mut u8, offset: u64, length: u64) -> u64 {
+    // On-chain programs call the runtime syscall directly
+    #[cfg(target_os = "solana")]
+    unsafe {
+        solana_define_syscall::definitions::sol_get_sysvar(sysvar_id, var_addr, offset, length)
+    }
+
+    // Off-chain std builds route through the host-test stub registry
+    #[cfg(all(not(target_os = "solana"), feature = "std"))]
+    {
+        stubs::sol_get_sysvar(sysvar_id, var_addr, offset, length)
+    }
+
+    // Off-chain no-std builds have neither runtime syscalls nor host stubs.
+    #[cfg(all(not(target_os = "solana"), not(feature = "std")))]
+    {
+        let _ = (sysvar_id, var_addr, offset, length);
+        solana_program_error::UNSUPPORTED_SYSVAR
+    }
+}

get-sysvar/src/lib.rs

@@ -0,0 +1,46 @@
+use std::sync::{Arc, RwLock};
+
+/// Off-chain stub implementation of the `sol_get_sysvar` syscall.
+pub trait GetSysvarStub: Sync + Send {
+    /// Write `length` bytes from the sysvar identified by `sysvar_id_addr`,
+    /// starting at `offset`, into `var_addr`.
+    ///
+    /// Return `0` on success. Return the runtime syscall error code for
+    /// unsupported sysvars or invalid ranges.
+    fn sol_get_sysvar(
+        &self,
+        sysvar_id_addr: *const u8,
+        var_addr: *mut u8,
+        offset: u64,
+        length: u64,
+    ) -> u64;
+}
+
+static GET_SYSVAR_STUB: RwLock<Option<Arc<dyn GetSysvarStub>>> = RwLock::new(None);
+
+/// Install the process-global `sol_get_sysvar` stub, returning the previous one.
+pub fn set_get_sysvar_stub(stub: Arc<dyn GetSysvarStub>) -> Option<Arc<dyn GetSysvarStub>> {
+    replace_get_sysvar_stub(Some(stub))
+}
+
+/// Clear the process-global `sol_get_sysvar` stub.
+pub fn clear_get_sysvar_stub() -> Option<Arc<dyn GetSysvarStub>> {
+    replace_get_sysvar_stub(None)
+}
+
+fn replace_get_sysvar_stub(stub: Option<Arc<dyn GetSysvarStub>>) -> Option<Arc<dyn GetSysvarStub>> {
+    std::mem::replace(&mut *GET_SYSVAR_STUB.write().unwrap(), stub)
+}
+
+pub(crate) fn sol_get_sysvar(
+    sysvar_id_addr: *const u8,
+    var_addr: *mut u8,
+    offset: u64,
+    length: u64,
+) -> u64 {
+    let stub = GET_SYSVAR_STUB.read().unwrap().clone();
+    match stub {
+        Some(stub) => stub.sol_get_sysvar(sysvar_id_addr, var_addr, offset, length),
+        None => solana_program_error::UNSUPPORTED_SYSVAR,
+    }
+}

get-sysvar/src/stubs.rs

@@ -20,6 +20,7 @@ no_std_crates=(
   -p solana-epoch-schedule
   -p solana-epoch-stake
   -p solana-fee-calculator
+  -p solana-get-sysvar
   -p solana-hash
   -p solana-instruction-view
   -p solana-keccak-hasher

scripts/check-no-std.sh

@@ -39,6 +39,7 @@ all_crate_dirs=(
   frozen-abi
   frozen-abi-macro
   genesis-config
+  get-sysvar
   hard-forks
   hash
   hash-512

scripts/patch-crates-functions.sh

@@ -61,6 +61,7 @@ solana-epoch-schedule = { workspace = true, features = ["sysvar"] }
 solana-fee-calculator = { workspace = true }
 solana-frozen-abi = { workspace = true, optional = true, features = ["frozen-abi"] }
 solana-frozen-abi-macro = { workspace = true, optional = true }
+solana-get-sysvar = { workspace = true, features = ["std"] }
 solana-hash = { workspace = true, features = ["bytemuck"] }
 solana-last-restart-slot = { workspace = true, features = ["sysvar"] }
 solana-program-entrypoint = { workspace = true }

sysvar/Cargo.toml

@@ -188,6 +188,14 @@ mod tests {
         let got = Clock::get().unwrap();
         assert_eq!(got, expected);
 
-        let _ = crate::program_stubs::set_syscall_stubs(prev);
+        // Restore the process-global stub to the state this test replaced.
+        match prev {
+            Some(prev) => {
+                solana_get_sysvar::set_get_sysvar_stub(prev);
+            }
+            None => {
+                solana_get_sysvar::clear_get_sysvar_stub();
+            }
+        }
     }
 }