Refactor API

Author: grod220

Cargo.lock

@@ -8,8 +8,7 @@ homepage = { workspace = true }
 license = { workspace = true }
 
 [dependencies]
-# TODO: Waiting on 0.3.0 to be released
-wincode = { git = "https://github.com/anza-xyz/wincode.git", rev = "fa70c7c7c13885085f743e4f01deb1a4de0b64fb", default-features = false, features = ["derive"] }
+wincode = { git = "https://github.com/anza-xyz/wincode.git", rev = "6feb75ff4c5b26275b0ee8bc4a12ea906d996a02", default-features = false, features = ["derive"] }
 
 [dev-dependencies]
 bincode = "1.3.3"

pinocchio/interface/Cargo.toml

@@ -2,18 +2,20 @@ use crate::state::StakeStateV2Tag;
 
 #[derive(Debug)]
 pub enum StakeStateError {
-    /// The discriminant tag is not a valid variant (must be 0-3).
+    /// Field access invalid for the current state.
+    InvalidStateAccess(StakeStateV2Tag),
+    /// Tag is not a valid variant (0-3).
     InvalidTag(u32),
-    /// An invalid state transition was attempted.
+    /// Invalid state transition attempted.
     InvalidTransition {
         from: StakeStateV2Tag,
         to: StakeStateV2Tag,
     },
-    /// Pass-through for wincode read errors when borrowing layout structs.
+    /// Wincode deserialization error.
     Read(wincode::ReadError),
-    /// Input buffer is shorter than 200 bytes.
+    /// Buffer shorter than 200 bytes.
     UnexpectedEof,
-    /// Pass-through for wincode write errors when serializing layout structs.
+    /// Wincode serialization error.
     Write(wincode::WriteError),
 }
 

pinocchio/interface/src/error.rs

@@ -1,2 +1,5 @@
+#![no_std]
+
 pub mod error;
+pub mod pod;
 pub mod state;

pinocchio/interface/src/lib.rs

@@ -10,7 +10,6 @@
 use wincode::{SchemaRead, SchemaWrite};
 
 /// Macro to define an alignment-1 little-endian integer wrapper.
-#[macro_export]
 macro_rules! impl_pod_int {
     (
         $(#[$meta:meta])*

pinocchio/interface/src/state/pod.rs pinocchio/interface/src/pod.rspinocchio/interface/src/state/pod.rs renamed to pinocchio/interface/src/pod.rs

@@ -0,0 +1,242 @@
+//! Zero-copy stake state types.
+
+use {
+    crate::{
+        error::StakeStateError,
+        pod::{PodAddress, PodI64, PodU32, PodU64},
+    },
+    core::mem::size_of,
+    wincode::{SchemaRead, SchemaWrite, ZeroCopy},
+};
+
+#[repr(C)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, SchemaWrite, SchemaRead)]
+#[wincode(assert_zero_copy)]
+pub struct Authorized {
+    pub staker: PodAddress,
+    pub withdrawer: PodAddress,
+}
+
+#[repr(C)]
+#[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,
+}
+
+#[repr(C)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, SchemaWrite, SchemaRead, Default)]
+#[wincode(assert_zero_copy)]
+pub struct Meta {
+    pub rent_exempt_reserve: PodU64,
+    pub authorized: Authorized,
+    pub lockup: Lockup,
+}
+
+#[repr(C)]
+#[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, `u64::MAX` if is a bootstrap stake.
+    pub activation_epoch: PodU64,
+    /// Epoch the stake was deactivated, `u64::MAX` if not deactivated.
+    pub deactivation_epoch: PodU64,
+    /// Reserved bytes (formerly warmup/cooldown rate).
+    /// Deprecated in the runtime but preserved for ABI compatibility.
+    pub _reserved: [u8; 8],
+}
+
+#[repr(C)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, SchemaWrite, SchemaRead, Default)]
+#[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,
+}
+
+/// Discriminant tag for stake account state (first 4 bytes).
+#[repr(u32)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StakeStateV2Tag {
+    Uninitialized = 0,
+    Initialized = 1,
+    Stake = 2,
+    RewardsPool = 3,
+}
+
+impl StakeStateV2Tag {
+    pub const TAG_LEN: usize = size_of::<PodU32>();
+
+    #[inline]
+    pub(crate) fn from_u32(v: u32) -> Result<Self, StakeStateError> {
+        match v {
+            0 => Ok(Self::Uninitialized),
+            1 => Ok(Self::Initialized),
+            2 => Ok(Self::Stake),
+            3 => Ok(Self::RewardsPool),
+            other => Err(StakeStateError::InvalidTag(other)),
+        }
+    }
+
+    #[inline]
+    pub fn from_bytes(bytes: &[u8]) -> Result<Self, StakeStateError> {
+        if bytes.len() < 4 {
+            return Err(StakeStateError::UnexpectedEof);
+        }
+        let raw = u32::from_le_bytes(bytes[..4].try_into().unwrap());
+        Self::from_u32(raw)
+    }
+}
+
+/// 200-byte stake account layout:
+///
+/// ```text
+/// ┌────────┬──────┬────────────┐
+/// │ Offset │ Size │ Field      │
+/// ├────────┼──────┼────────────┤
+/// │   0    │  4   │ Tag        │
+/// │   4    │ 120  │ Meta       │
+/// │  124   │  72  │ Stake      │
+/// │  196   │  1   │ StakeFlags │
+/// │  197   │  3   │ Padding    │
+/// └────────┴──────┴────────────┘
+/// ```
+///
+/// All fields are alignment-1 for safe zero-copy from unaligned byte slices.
+#[repr(C)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, SchemaWrite, SchemaRead)]
+#[wincode(assert_zero_copy)]
+pub struct StakeStateV2 {
+    tag: PodU32,
+    meta: Meta,
+    stake: Stake,
+    stake_flags: u8,
+    padding: [u8; 3],
+}
+
+// compile-time size check
+const _: () = assert!(size_of::<StakeStateV2>() == 200);
+
+impl StakeStateV2 {
+    /// The fixed size of a stake account in bytes.
+    pub const LEN: usize = size_of::<StakeStateV2>();
+
+    /// Parse stake account data into a read-only reference.
+    pub fn from_bytes(data: &[u8]) -> Result<&Self, StakeStateError> {
+        if data.len() < Self::LEN {
+            return Err(StakeStateError::UnexpectedEof);
+        }
+        let state = <Self as ZeroCopy>::from_bytes(data)?;
+        StakeStateV2Tag::from_u32(state.tag.get())?;
+        Ok(state)
+    }
+
+    /// Parse stake account data into a mutable reference.
+    pub fn from_bytes_mut(data: &mut [u8]) -> Result<&mut Self, StakeStateError> {
+        if data.len() < Self::LEN {
+            return Err(StakeStateError::UnexpectedEof);
+        }
+        let state = <Self as ZeroCopy>::from_bytes_mut(data)?;
+        StakeStateV2Tag::from_u32(state.tag.get())?;
+        Ok(state)
+    }
+
+    /// Returns the state tag (infallible since validated at construction).
+    #[inline]
+    pub fn tag(&self) -> StakeStateV2Tag {
+        StakeStateV2Tag::from_u32(self.tag.get()).unwrap()
+    }
+
+    /// Returns a reference to `Meta` if in the `Initialized` or `Stake` state.
+    #[inline]
+    pub fn meta(&self) -> Option<&Meta> {
+        match self.tag() {
+            StakeStateV2Tag::Initialized | StakeStateV2Tag::Stake => Some(&self.meta),
+            _ => None,
+        }
+    }
+
+    /// Returns a reference to `Stake` if in the `Stake` state.
+    #[inline]
+    pub fn stake(&self) -> Option<&Stake> {
+        match self.tag() {
+            StakeStateV2Tag::Stake => Some(&self.stake),
+            _ => None,
+        }
+    }
+
+    /// Returns a mutable reference to `Meta` if in the `Initialized` or `Stake` state.
+    #[inline]
+    pub fn meta_mut(&mut self) -> Result<&mut Meta, StakeStateError> {
+        match self.tag() {
+            StakeStateV2Tag::Initialized | StakeStateV2Tag::Stake => Ok(&mut self.meta),
+            tag => Err(StakeStateError::InvalidStateAccess(tag)),
+        }
+    }
+
+    /// Returns a mutable reference to `Stake` if in the `Stake` state.
+    #[inline]
+    pub fn stake_mut(&mut self) -> Result<&mut Stake, StakeStateError> {
+        match self.tag() {
+            StakeStateV2Tag::Stake => Ok(&mut self.stake),
+            tag => Err(StakeStateError::InvalidStateAccess(tag)),
+        }
+    }
+
+    /// Transition from `Uninitialized` to `Initialized`.
+    /// Clears the stake and tail regions.
+    pub fn initialize(&mut self, meta: Meta) -> Result<(), StakeStateError> {
+        let from = self.tag();
+        if from != StakeStateV2Tag::Uninitialized {
+            return Err(StakeStateError::InvalidTransition {
+                from,
+                to: StakeStateV2Tag::Initialized,
+            });
+        }
+
+        self.stake = Stake::default();
+        self.stake_flags = 0;
+        self.padding.fill(0);
+        self.meta = meta;
+        self.tag.set(StakeStateV2Tag::Initialized as u32);
+
+        Ok(())
+    }
+
+    /// Transition to `Stake` state from `Initialized` or `Stake`.
+    /// - From `Initialized`: clears tail region to zero.
+    /// - From `Stake`: preserves existing tail region.
+    pub fn delegate(&mut self, meta: Meta, stake: Stake) -> Result<(), StakeStateError> {
+        let from = self.tag();
+        if !matches!(from, StakeStateV2Tag::Initialized | StakeStateV2Tag::Stake) {
+            return Err(StakeStateError::InvalidTransition {
+                from,
+                to: StakeStateV2Tag::Stake,
+            });
+        }
+
+        if from == StakeStateV2Tag::Initialized {
+            self.stake_flags = 0;
+            self.padding.fill(0);
+        }
+
+        self.meta = meta;
+        self.stake = stake;
+        self.tag.set(StakeStateV2Tag::Stake as u32);
+
+        Ok(())
+    }
+}