Tests pt.1

Author: grod220

Cargo.lock

@@ -7,16 +7,12 @@ repository = { workspace = true }
 homepage = { workspace = true }
 license = { workspace = true }
 
-[features]
-serde = ["dep:serde"]
-
 [dependencies]
-solana-address = "1.0.0"
 wincode = { git = "https://github.com/anza-xyz/wincode.git", branch = "master", default-features = false, features = ["derive"] }
-serde = { version = "1.0", features = ["derive"], optional = true }
 
 [dev-dependencies]
 bincode = "1.3.3"
 proptest = "1.9.0"
 solana-pubkey = "3.0.0"
 solana-stake-interface = { path = "../../interface", features = ["bincode"] }
+test-case = "3.3.1"

pinocchio/interface/Cargo.toml

@@ -1,25 +1,19 @@
-//! Error types for stake state parsing.
-
 use crate::state::StakeStateV2Tag;
 
 #[derive(Debug)]
 pub enum StakeStateError {
-    /// Input is shorter than 200 bytes.
-    UnexpectedEof,
-
-    /// The discriminant tag is not a valid variant
+    /// The discriminant tag is not a valid variant (must be 0-3).
     InvalidTag(u32),
-
     /// An invalid state transition was attempted.
     InvalidTransition {
         from: StakeStateV2Tag,
         to: StakeStateV2Tag,
     },
-
-    /// Pass-through for wincode read errors.
+    /// Pass-through for wincode read errors when borrowing layout structs.
     Read(wincode::ReadError),
-
-    /// Pass-through for wincode write errors.
+    /// Input buffer is shorter than 200 bytes.
+    UnexpectedEof,
+    /// Pass-through for wincode write errors when serializing layout structs.
     Write(wincode::WriteError),
 }
 

pinocchio/interface/src/error.rs

@@ -1,8 +1,10 @@
+//! High-level entrypoint for reading and writing stake account state.
 use {
     super::{view::StakeStateV2View, writer::StakeStateV2Writer},
     crate::error::StakeStateError,
 };
 
+/// Main entrypoint for parsing stake account data. Provides zero-copy access to the stake account state.
 pub struct StakeStateV2;
 
 impl StakeStateV2 {

pinocchio/interface/src/state/entrypoint.rs

@@ -17,8 +17,14 @@ pub struct Authorized {
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default, SchemaWrite, SchemaRead)]
 #[wincode(assert_zero_copy)]
 pub struct Lockup {
+    /// `UnixTimestamp` at which this stake will allow withdrawal, unless the
+    ///   transaction is signed by the custodian
     pub unix_timestamp: PodI64,
+    /// epoch height at which this stake will allow withdrawal, unless the
+    ///   transaction is signed by the custodian
     pub epoch: PodU64,
+    /// custodian signature on a transaction exempts the operation from
+    ///  lockup constraints
     pub custodian: PodAddress,
 }
 
@@ -35,10 +41,15 @@ pub struct Meta {
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default, SchemaWrite, SchemaRead)]
 #[wincode(assert_zero_copy)]
 pub struct Delegation {
+    /// to whom the stake is delegated
     pub voter_pubkey: PodAddress,
+    /// activated stake amount, set at delegate() time
     pub stake: PodU64,
+    /// epoch at which this stake was activated, `std::u64::MAX` if is a bootstrap stake
     pub activation_epoch: PodU64,
+    /// epoch the stake was deactivated, `std::u64::MAX` if not deactivated
     pub deactivation_epoch: PodU64,
+    /// Legacy bytes from legacy warmup/cooldown rate encoding (deprecated).
     pub _reserved: [u8; 8],
 }
 
@@ -47,12 +58,12 @@ pub struct Delegation {
 #[wincode(assert_zero_copy)]
 pub struct Stake {
     pub delegation: Delegation,
+    /// credits observed is credits from vote account state when delegated or redeemed
     pub credits_observed: PodU64,
 }
 
 #[repr(u32)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, SchemaRead, SchemaWrite)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize))]
 #[wincode(tag_encoding = "u32")]
 pub enum StakeStateV2Tag {
     #[wincode(tag = 0)]
@@ -91,11 +102,7 @@ impl StakeStateV2Tag {
     }
 }
 
-/// Raw 200-byte stake account data.
-///
-/// # Layout
-///
-/// A stake account is always 200 bytes with this structure:
+/// Raw 200-byte stake account data with this structure:
 ///
 /// ```text
 /// ┌────────┬──────┬────────────┐

pinocchio/interface/src/state/layout.rs

@@ -1,4 +1,4 @@
-//! Zero-copy stake state types
+//! Zero-copy stake state types.
 
 mod entrypoint;
 mod layout;

pinocchio/interface/src/state/mod.rs

@@ -1,35 +1,17 @@
 //! Alignment-1 ("pod") primitives for zero-copy deserialization.
 //!
-//! # Why alignment-1?
-//!
 //! Solana account data is a raw `&[u8]` with no alignment guarantees.
 //! Standard Rust primitives like `u64` require 8-byte alignment, so you can't
 //! safely cast `&[u8]` to `&u64` without risking undefined behavior.
 //!
 //! These "pod" (plain old data) types wrap byte arrays and provide safe
 //! get/set methods that handle little-endian conversion. They have alignment 1,
 //! so they can be safely referenced from any byte offset.
-//!
-//! # Layout
-//!
-//! All types use `#[repr(transparent)]` to ensure the struct has the same
-//! memory layout as its inner byte array.
-
-use {
-    solana_address::Address,
-    wincode::{SchemaRead, SchemaWrite},
-};
+use wincode::{SchemaRead, SchemaWrite};
 
 /// Macro to define an alignment-1 little-endian integer wrapper.
-///
-/// Generates:
-/// - `#[repr(transparent)]` wrapper over `[u8; N]`
-/// - `Default` (all zeros)
-/// - `const fn from_primitive`
-/// - `get/set/as_bytes`
-/// - `From<prim> for Pod*` and `From<Pod*> for prim`
 #[macro_export]
-macro_rules! impl_pod_int_le {
+macro_rules! impl_pod_int {
     (
         $(#[$meta:meta])*
         $name:ident, $prim:ty, $n:expr
@@ -41,170 +23,57 @@ macro_rules! impl_pod_int_le {
         pub struct $name(pub [u8; $n]);
 
         impl $name {
-            /// Creates from a native primitive value, stored as little-endian bytes.
-            #[inline(always)]
             pub const fn from_primitive(v: $prim) -> Self {
                 Self(v.to_le_bytes())
             }
 
-            /// Reads the value as a native primitive.
-            #[inline(always)]
             pub fn get(self) -> $prim {
                 <$prim>::from_le_bytes(self.0)
             }
 
-            /// Writes a native primitive value.
-            #[inline(always)]
             pub fn set(&mut self, v: $prim) {
                 self.0 = v.to_le_bytes();
             }
 
-            /// Returns the raw little-endian bytes.
-            #[inline(always)]
             pub fn as_bytes(&self) -> &[u8; $n] {
                 &self.0
             }
 
-            /// Returns the raw little-endian bytes as a mutable slice.
-            #[inline(always)]
             pub fn as_mut_slice(&mut self) -> &mut [u8] {
                 &mut self.0
             }
         }
 
         impl From<$prim> for $name {
-            #[inline(always)]
             fn from(v: $prim) -> Self {
                 Self::from_primitive(v)
             }
         }
 
         impl From<$name> for $prim {
-            #[inline(always)]
             fn from(v: $name) -> Self {
                 v.get()
             }
         }
     };
 }
 
-impl_pod_int_le!(
-    /// A `u32` stored as 4 little-endian bytes with alignment 1.
-    PodU32, u32, 4
-);
-
-impl_pod_int_le!(
-    /// A `u64` stored as 8 little-endian bytes with alignment 1.
-    PodU64, u64, 8
-);
+impl_pod_int!(PodU32, u32, 4);
+impl_pod_int!(PodU64, u64, 8);
+impl_pod_int!(PodI64, i64, 8);
 
-impl_pod_int_le!(
-    /// An `i64` stored as 8 little-endian bytes with alignment 1.
-    PodI64, i64, 8
-);
-
-/// An `Address` (pubkey) stored as 32 bytes with alignment 1.
+/// An `Address` stored as 32 bytes with alignment 1.
 #[repr(transparent)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Default, SchemaWrite, SchemaRead)]
 #[wincode(assert_zero_copy)]
 pub struct PodAddress(pub [u8; 32]);
 
 impl PodAddress {
-    /// Converts to a native `Address`.
-    #[inline(always)]
-    pub fn to_address(self) -> Address {
-        Address::new_from_array(self.0)
-    }
-
-    /// Returns the raw bytes.
-    #[inline(always)]
     pub fn as_bytes(&self) -> &[u8; 32] {
         &self.0
     }
 
-    /// Creates from raw bytes.
-    #[inline(always)]
     pub const fn from_bytes(bytes: [u8; 32]) -> Self {
         Self(bytes)
     }
-
-    /// Creates from a native `Address`.
-    #[inline(always)]
-    pub fn from_address(addr: Address) -> Self {
-        Self(addr.to_bytes())
-    }
-}
-
-impl From<Address> for PodAddress {
-    #[inline(always)]
-    fn from(addr: Address) -> Self {
-        Self::from_address(addr)
-    }
-}
-
-impl From<PodAddress> for Address {
-    #[inline(always)]
-    fn from(p: PodAddress) -> Self {
-        p.to_address()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn pod_u32_le_layout() {
-        let p = PodU32::from_primitive(1);
-        assert_eq!(p.0, [1, 0, 0, 0]);
-        assert_eq!(p.get(), 1);
-
-        let x: u32 = p.into();
-        assert_eq!(x, 1);
-
-        let p2: PodU32 = 42u32.into();
-        assert_eq!(p2.get(), 42);
-    }
-
-    #[test]
-    fn pod_u64_le_layout() {
-        let p = PodU64::from_primitive(1);
-        assert_eq!(p.0, [1, 0, 0, 0, 0, 0, 0, 0]);
-        assert_eq!(p.get(), 1);
-
-        let x: u64 = p.into();
-        assert_eq!(x, 1);
-
-        let mut p2: PodU64 = 0u64.into();
-        p2.set(u64::MAX);
-        assert_eq!(p2.get(), u64::MAX);
-    }
-
-    #[test]
-    fn pod_i64_le_layout() {
-        let p = PodI64::from_primitive(-1);
-        assert_eq!(p.get(), -1);
-
-        let x: i64 = p.into();
-        assert_eq!(x, -1);
-
-        let mut p2: PodI64 = 0i64.into();
-        p2.set(i64::MIN);
-        assert_eq!(p2.get(), i64::MIN);
-    }
-
-    #[test]
-    fn pod_address_roundtrip() {
-        let bytes = [7u8; 32];
-        let p = PodAddress::from_bytes(bytes);
-        assert_eq!(p.as_bytes(), &bytes);
-
-        let addr = p.to_address();
-        let p2 = PodAddress::from_address(addr);
-        assert_eq!(p2.as_bytes(), &bytes);
-
-        let addr2: Address = p2.into();
-        let p3: PodAddress = addr2.into();
-        assert_eq!(p3.as_bytes(), &bytes);
-    }
 }

pinocchio/interface/src/state/pod.rs

@@ -11,7 +11,8 @@ use {
     wincode::ZeroCopy,
 };
 
-/// Mutable handle to stake account data.
+/// Mutable handle for stake account state transitions.
+#[derive(Debug)]
 pub struct StakeStateV2Writer<'a> {
     data: &'a mut [u8],
 }