clarify

Author: rustopian

sdk/pinocchio/src/sysvars/slot_hashes/raw.rs

@@ -8,16 +8,19 @@
 
 use super::*;
 
-/// Validates that a buffer is properly sized for `SlotHashes` data.
+/// Validates buffer format for `SlotHashes` data and calculates entry capacity.
 ///
-/// Does not ensure the buffer doesn't exceed available sysvar data
-/// from the given offset. A later syscall will fail in this case.
+/// Validates that the buffer follows the correct format:
+/// - If `offset == 0`: Buffer must have `8 + (N × 40)` format (header + entries)
+/// - If `offset != 0`: Buffer must be a multiple of 40 bytes (entries only)
 ///
-/// This function assumes the mainnet slot hashes sysvar length of `MAX_SIZE` (20,488).
+/// Does not validate that `offset + buffer_len ≤ MAX_SIZE`; this is checked
+/// separately in `validate_fetch_offset`, and the syscall will fail anyway if
+/// `offset + buffer_len > MAX_SIZE`.
 ///
-/// Returns the number of entries that will be copied into the buffer.
+/// Returns the number of entries that can fit in the buffer.
 #[inline(always)]
-pub(crate) fn validate_buffer_size(
+pub(crate) fn validate_and_get_buffer_capacity(
     buffer_len: usize,
     offset: usize,
 ) -> Result<usize, ProgramError> {
@@ -78,24 +81,25 @@ pub fn validate_fetch_offset(offset: usize, buffer_len: usize) -> Result<(), Pro
 ///
 /// # Returns
 ///
-/// Since `num_entries` is used, it is returned for caller's convenience, as the
-/// caller will almost certainly want to use this information.
+/// Returns the number of entries:
+/// - If `offset == 0`: The actual entry count read from the sysvar header
+/// - If `offset != 0`: The number of entries that can fit in the buffer
+///
+/// The return value helps callers understand the structure of the copied data.
 #[inline(always)]
 pub fn fetch_into(buffer: &mut [u8], offset: usize) -> Result<usize, ProgramError> {
-    let num_entries = validate_buffer_size(buffer.len(), offset)?;
+    let num_entries = validate_and_get_buffer_capacity(buffer.len(), offset)?;
 
     validate_fetch_offset(offset, buffer.len())?;
 
-    // SAFETY: `buffer.len()` and `offset` are both validated above. It is possible
-    // that the two added together are greater than `MAX_SIZE`, but the syscall will
-    // fail in that case.
+    // SAFETY: Buffer format and offset alignment validated above.
     unsafe { fetch_into_unchecked(buffer, offset) }?;
 
     if offset == 0 {
-        // If header is preset, read entries from it
+        // Buffer includes header: return actual entry count from sysvar data
         Ok(read_entry_count_from_bytes(buffer).unwrap_or(0))
     } else {
-        // Otherwise, return the number of entries that can fit in the buffer
+        // Buffer excludes header: return calculated entry capacity
         Ok(num_entries)
     }
 }

sdk/pinocchio/src/sysvars/slot_hashes/test_raw.rs

@@ -10,73 +10,95 @@ fn test_validate_buffer_size() {
 
     // Too small to fit header
     let small_len = 4;
-    assert!(raw::validate_buffer_size(small_len, 0).is_err());
+    assert!(raw::validate_and_get_buffer_capacity(small_len, 0).is_err());
 
     // Misaligned: header + partial entry
     let misaligned_len = NUM_ENTRIES_SIZE + 39;
-    assert!(raw::validate_buffer_size(misaligned_len, 0).is_err());
+    assert!(raw::validate_and_get_buffer_capacity(misaligned_len, 0).is_err());
 
     // Valid cases with offset = 0
     let valid_empty_len = NUM_ENTRIES_SIZE;
-    assert_eq!(raw::validate_buffer_size(valid_empty_len, 0).unwrap(), 0);
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(valid_empty_len, 0).unwrap(),
+        0
+    );
 
     let valid_one_len = NUM_ENTRIES_SIZE + ENTRY_SIZE;
-    assert_eq!(raw::validate_buffer_size(valid_one_len, 0).unwrap(), 1);
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(valid_one_len, 0).unwrap(),
+        1
+    );
 
     let valid_max_len = NUM_ENTRIES_SIZE + MAX_ENTRIES * ENTRY_SIZE;
     assert_eq!(
-        raw::validate_buffer_size(valid_max_len, 0).unwrap(),
+        raw::validate_and_get_buffer_capacity(valid_max_len, 0).unwrap(),
         MAX_ENTRIES
     );
 
     // Edge case: exactly at the boundary (MAX_SIZE)
-    assert_eq!(raw::validate_buffer_size(MAX_SIZE, 0).unwrap(), MAX_ENTRIES);
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(MAX_SIZE, 0).unwrap(),
+        MAX_ENTRIES
+    );
 
     // ===== Tests with offset != 0 (buffer doesn't include header) =====
 
     // Valid cases with non-zero offset - buffer contains only entry data
 
     // Buffer for exactly 1 entry
-    assert_eq!(raw::validate_buffer_size(ENTRY_SIZE, 8).unwrap(), 1);
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(ENTRY_SIZE, 8).unwrap(),
+        1
+    );
 
     // Buffer for exactly 2 entries
-    assert_eq!(raw::validate_buffer_size(2 * ENTRY_SIZE, 8).unwrap(), 2);
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(2 * ENTRY_SIZE, 8).unwrap(),
+        2
+    );
 
     // Buffer for maximum entries (without header space)
     assert_eq!(
-        raw::validate_buffer_size(MAX_ENTRIES * ENTRY_SIZE, 8).unwrap(),
+        raw::validate_and_get_buffer_capacity(MAX_ENTRIES * ENTRY_SIZE, 8).unwrap(),
         MAX_ENTRIES
     );
 
     // Buffer for 10 entries
-    assert_eq!(raw::validate_buffer_size(10 * ENTRY_SIZE, 48).unwrap(), 10);
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(10 * ENTRY_SIZE, 48).unwrap(),
+        10
+    );
 
     // Error cases with non-zero offset
 
     // Misaligned buffer - not a multiple of ENTRY_SIZE
-    assert!(raw::validate_buffer_size(ENTRY_SIZE + 1, 8).is_err());
-    assert!(raw::validate_buffer_size(ENTRY_SIZE - 1, 8).is_err());
-    assert!(raw::validate_buffer_size(39, 8).is_err()); // 39 is not divisible by 40
+    assert!(raw::validate_and_get_buffer_capacity(ENTRY_SIZE + 1, 8).is_err());
+    assert!(raw::validate_and_get_buffer_capacity(ENTRY_SIZE - 1, 8).is_err());
+    assert!(raw::validate_and_get_buffer_capacity(39, 8).is_err()); // 39 is not divisible by 40
 
     // Large buffers that would exceed MAX_SIZE - these now pass validate_buffer_size
     // (the syscall will fail later, but that's acceptable)
     assert_eq!(
-        raw::validate_buffer_size((MAX_ENTRIES + 1) * ENTRY_SIZE, 8).unwrap(),
+        raw::validate_and_get_buffer_capacity((MAX_ENTRIES + 1) * ENTRY_SIZE, 8).unwrap(),
         MAX_ENTRIES + 1
     );
     assert_eq!(
-        raw::validate_buffer_size((MAX_ENTRIES + 10) * ENTRY_SIZE, 48).unwrap(),
+        raw::validate_and_get_buffer_capacity((MAX_ENTRIES + 10) * ENTRY_SIZE, 48).unwrap(),
         MAX_ENTRIES + 10
     );
 
     // Empty buffer with offset (valid - 0 entries)
-    assert_eq!(raw::validate_buffer_size(0, 8).unwrap(), 0);
+    assert_eq!(raw::validate_and_get_buffer_capacity(0, 8).unwrap(), 0);
 
     // ===== Additional edge cases =====
 
     // Large offset values (should still work for buffer size validation)
-    assert_eq!(raw::validate_buffer_size(5 * ENTRY_SIZE, 1000).unwrap(), 5);
-    assert!(raw::validate_buffer_size(5 * ENTRY_SIZE + 1, 2000).is_err()); // misaligned
+    assert_eq!(
+        raw::validate_and_get_buffer_capacity(5 * ENTRY_SIZE, 1000).unwrap(),
+        5
+    );
+    assert!(raw::validate_and_get_buffer_capacity(5 * ENTRY_SIZE + 1, 2000).is_err());
+    // misaligned
 }
 
 #[test]