hopper_runtime/
option_byte.rs

1//! Zero-copy, tag-validated optional values for instruction args.
2//!
3//! Rust's `Option<T>` has niche-optimizing layout rules that make it
4//! unsafe to pointer-cast from raw instruction bytes. `Option<u8>` is
5//! two bytes with an undefined tag range; `Option<&T>` uses null for
6//! `None`. Neither is a layout the caller controls.
7//!
8//! `OptionByte<T>` is the Hopper replacement for args. Layout:
9//!
10//! ```text
11//! #[repr(C)]
12//! { tag: u8, value: T }
13//! ```
14//!
15//! `tag == 0` is `None`, `tag == 1` is `Some`. Any other tag byte is
16//! a protocol error and [`OptionByte::get`] surfaces it as
17//! `ProgramError::InvalidInstructionData`. This mirrors Quasar's
18//! `OptionZc<T>::validate_zc` contract with one fewer type parameter
19//! and no `MaybeUninit` escape hatch.
20//!
21//! ## Usage
22//!
23//! ```ignore
24//! #[hopper::args]
25//! #[repr(C)]
26//! pub struct SwapArgs {
27//!     pub amount: u64,
28//!     pub referrer: OptionByte<[u8; 32]>,
29//!     pub slippage_bps: u16,
30//! }
31//!
32//! fn handler(ctx: Context<Swap>, args: &SwapArgs) -> ProgramResult {
33//!     if let Some(referrer) = args.referrer.get()? {
34//!         // referrer is &[u8; 32]
35//!     }
36//!     Ok(())
37//! }
38//! ```
39
40use crate::{error::ProgramError, result::ProgramResult};
41
42/// Zero-copy tagged optional. See module docs for the layout and
43/// usage contract.
44#[repr(C)]
45#[derive(Copy, Clone)]
46pub struct OptionByte<T: Copy> {
47    tag: u8,
48    value: T,
49}
50
51impl<T: Copy> OptionByte<T> {
52    /// Construct a `None` variant. Because the struct is `#[repr(C)]`
53    /// with a Pod value field, the `value` payload must still be
54    /// bitwise valid; the caller provides a default value that is
55    /// ignored by [`OptionByte::get`].
56    #[inline(always)]
57    pub const fn none(default_value: T) -> Self {
58        Self { tag: 0, value: default_value }
59    }
60
61    /// Construct a `Some(value)` variant.
62    #[inline(always)]
63    pub const fn some(value: T) -> Self {
64        Self { tag: 1, value }
65    }
66
67    /// The tag byte as the sender encoded it. Callers should never
68    /// inspect this directly; use [`OptionByte::get`] so the tag is
69    /// validated first.
70    #[inline(always)]
71    pub const fn raw_tag(&self) -> u8 {
72        self.tag
73    }
74
75    /// Validate the tag byte and return the appropriate Rust `Option`.
76    ///
77    /// Returns `Err(ProgramError::InvalidInstructionData)` when the
78    /// tag is neither `0` nor `1`. Any other byte indicates malformed
79    /// instruction data and is the exact surface a Quasar `OptionZc`
80    /// would flag in `validate_zc`.
81    #[inline]
82    pub fn get(&self) -> Result<Option<&T>, ProgramError> {
83        match self.tag {
84            0 => Ok(None),
85            1 => Ok(Some(&self.value)),
86            _ => Err(ProgramError::InvalidInstructionData),
87        }
88    }
89
90    /// Validate-only: confirms the tag byte is 0 or 1. Useful for
91    /// callers who want to reject malformed input early without
92    /// taking a reference to the payload.
93    #[inline]
94    pub fn validate_tag(&self) -> ProgramResult {
95        match self.tag {
96            0 | 1 => Ok(()),
97            _ => Err(ProgramError::InvalidInstructionData),
98        }
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    /// 8-byte-aligned scratch buffer for the pointer-cast tests below.
107    /// `[u8; 9]` on the stack has alignment 1, which means a raw
108    /// reinterpret to `&OptionByte<u64>` (alignment 8) trips the
109    /// rustc 1.78+ debug-build "misaligned pointer dereference"
110    /// check on whichever fraction of stack frames don't happen to
111    /// land on an 8-aligned address. Wrapping the bytes in a
112    /// repr(align(8)) struct removes the alignment lottery.
113    #[repr(C, align(8))]
114    struct AlignedNine([u8; 9]);
115
116    #[test]
117    fn none_reads_as_none() {
118        let o: OptionByte<u64> = OptionByte::none(0);
119        assert!(o.get().unwrap().is_none());
120    }
121
122    #[test]
123    fn some_reads_back() {
124        let o = OptionByte::some(42u64);
125        assert_eq!(*o.get().unwrap().unwrap(), 42);
126    }
127
128    #[test]
129    fn malformed_tag_rejects() {
130        // Simulate a pointer-cast from hostile bytes: a 0xFF tag is
131        // neither 0 nor 1.
132        let mut buf = AlignedNine([0u8; 9]);
133        buf.0[0] = 0xFF;
134        let o: &OptionByte<u64> = unsafe { &*(buf.0.as_ptr() as *const OptionByte<u64>) };
135        assert_eq!(o.get().unwrap_err(), ProgramError::InvalidInstructionData);
136        assert_eq!(o.validate_tag().unwrap_err(), ProgramError::InvalidInstructionData);
137    }
138
139    #[test]
140    fn zero_tag_ignores_value_payload() {
141        // A None with garbage value bytes still decodes cleanly.
142        let mut buf = AlignedNine([0u8; 9]);
143        buf.0[1..9].copy_from_slice(&0x1234_5678_9ABC_DEF0u64.to_le_bytes());
144        let o: &OptionByte<u64> = unsafe { &*(buf.0.as_ptr() as *const OptionByte<u64>) };
145        assert!(o.get().unwrap().is_none());
146    }
147}
hopper_runtime/option_byte.rs

hopper_runtime/
option_byte.rs
