hopper-native 0.4.3

//! Alignment-safe wire types for zero-copy account data.
//!
//! Account data APIs expose byte buffers without guaranteeing native-integer
//! alignment. Forming a `u64` reference at an unaligned address is undefined
//! behavior. Hopper's wire integers store little-endian bytes at alignment 1:
//!
//! - **Explicit endianness**: Types are named `LeU64` ("little-endian u64"),
//!   making the wire representation explicit at call sites.
//! - **Explicit arithmetic semantics**: the `checked_*`, `saturating_*`,
//!   and `wrapping_*` inherent methods spell out overflow behavior at the
//!   call site. The `+`/`-`/`*` operators mirror Rust's native integers
//!   (panic on overflow in debug, wrap in release). Prefer the explicit
//!   methods for on-chain balance math.
//! - **`const fn` constructors**: `LeU64::new(42)` works in const context,
//!   enabling compile-time constants for discriminators, seeds, etc.
//! - **`Pod` + `Projectable`**: All wire types satisfy both the substrate
//!   [`crate::Pod`] overlay contract and [`Projectable`], so
//!   `lens::read_field_pod::<LeU64>` and `project::<LeU64>` both work
//!   directly on account data without alignment issues.
//!
//! A `#[repr(C)]` struct composed entirely of these wire types and alignment-1
//! byte arrays can satisfy Hopper's zero-copy overlay contract.

use crate::project::Projectable;

// ---- Macro to generate integer wire types ----------------------------

macro_rules! le_integer {
    (
        $(#[$meta:meta])*
        $name:ident, $native:ty, $size:expr, unsigned
    ) => {
        $(#[$meta])*
        #[repr(transparent)]
        #[derive(Clone, Copy, Default, Eq, PartialEq, Hash)]
        pub struct $name([u8; $size]);

        impl $name {
            /// Zero value.
            pub const ZERO: Self = Self([0; $size]);

            /// Maximum representable value.
            pub const MAX: Self = Self(<$native>::MAX.to_le_bytes());

            /// Construct from a native integer (const-safe).
            #[inline(always)]
            pub const fn new(v: $native) -> Self {
                Self(v.to_le_bytes())
            }

            /// Read the native integer value.
            #[inline(always)]
            pub const fn get(self) -> $native {
                <$native>::from_le_bytes(self.0)
            }

            /// Raw little-endian bytes.
            #[inline(always)]
            pub const fn to_le_bytes(self) -> [u8; $size] {
                self.0
            }

            /// Construct from raw little-endian bytes.
            #[inline(always)]
            pub const fn from_le_bytes(bytes: [u8; $size]) -> Self {
                Self(bytes)
            }

            /// Checked addition. Returns `None` on overflow.
            #[inline(always)]
            pub const fn checked_add(self, rhs: Self) -> Option<Self> {
                match self.get().checked_add(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Checked subtraction. Returns `None` on underflow.
            #[inline(always)]
            pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
                match self.get().checked_sub(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Checked multiplication. Returns `None` on overflow.
            #[inline(always)]
            pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
                match self.get().checked_mul(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Checked division. Returns `None` on divide-by-zero.
            #[inline(always)]
            pub const fn checked_div(self, rhs: Self) -> Option<Self> {
                match self.get().checked_div(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Saturating addition (clamps at MAX instead of wrapping).
            #[inline(always)]
            pub const fn saturating_add(self, rhs: Self) -> Self {
                Self::new(self.get().saturating_add(rhs.get()))
            }

            /// Saturating subtraction (clamps at 0 instead of wrapping).
            #[inline(always)]
            pub const fn saturating_sub(self, rhs: Self) -> Self {
                Self::new(self.get().saturating_sub(rhs.get()))
            }

            /// Wrapping addition (use explicitly when wrapping is intended).
            #[inline(always)]
            pub const fn wrapping_add(self, rhs: Self) -> Self {
                Self::new(self.get().wrapping_add(rhs.get()))
            }

            /// Wrapping subtraction.
            #[inline(always)]
            pub const fn wrapping_sub(self, rhs: Self) -> Self {
                Self::new(self.get().wrapping_sub(rhs.get()))
            }

            /// Whether the value is zero.
            #[inline(always)]
            pub const fn is_zero(self) -> bool {
                self.get() == 0
            }
        }

        impl From<$native> for $name {
            #[inline(always)]
            fn from(v: $native) -> Self { Self::new(v) }
        }

        impl From<$name> for $native {
            #[inline(always)]
            fn from(v: $name) -> Self { v.get() }
        }

        impl PartialOrd for $name {
            #[inline(always)]
            fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
                Some(self.cmp(other))
            }
        }

        impl Ord for $name {
            #[inline(always)]
            fn cmp(&self, other: &Self) -> core::cmp::Ordering {
                self.get().cmp(&other.get())
            }
        }

        impl core::fmt::Debug for $name {
            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
                write!(f, "{}({})", stringify!($name), self.get())
            }
        }

        impl core::fmt::Display for $name {
            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
                write!(f, "{}", self.get())
            }
        }

        // SAFETY: $name is #[repr(transparent)] over [u8; N].
        // All bit patterns are valid (no padding, no alignment requirement).
        unsafe impl Projectable for $name {}
        // SAFETY: #[repr(transparent)] over [u8; N]: alignment 1, no padding,
        // every bit pattern valid, no internal pointers, the full substrate
        // Pod overlay contract.
        unsafe impl $crate::pod::Zeroable for $name {}
        unsafe impl $crate::pod::Pod for $name {}

        $crate::__wire_arith_ops!($name, $native);
    };

    // Signed variant -- same API but with signed native type.
    (
        $(#[$meta:meta])*
        $name:ident, $native:ty, $size:expr, signed
    ) => {
        $(#[$meta])*
        #[repr(transparent)]
        #[derive(Clone, Copy, Default, Eq, PartialEq, Hash)]
        pub struct $name([u8; $size]);

        impl $name {
            /// Zero value.
            pub const ZERO: Self = Self([0; $size]);

            /// Maximum representable value.
            pub const MAX: Self = Self(<$native>::MAX.to_le_bytes());

            /// Minimum representable value.
            pub const MIN: Self = Self(<$native>::MIN.to_le_bytes());

            /// Construct from a native integer (const-safe).
            #[inline(always)]
            pub const fn new(v: $native) -> Self {
                Self(v.to_le_bytes())
            }

            /// Read the native integer value.
            #[inline(always)]
            pub const fn get(self) -> $native {
                <$native>::from_le_bytes(self.0)
            }

            /// Raw little-endian bytes.
            #[inline(always)]
            pub const fn to_le_bytes(self) -> [u8; $size] {
                self.0
            }

            /// Construct from raw little-endian bytes.
            #[inline(always)]
            pub const fn from_le_bytes(bytes: [u8; $size]) -> Self {
                Self(bytes)
            }

            /// Checked addition.
            #[inline(always)]
            pub const fn checked_add(self, rhs: Self) -> Option<Self> {
                match self.get().checked_add(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Checked subtraction.
            #[inline(always)]
            pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
                match self.get().checked_sub(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Checked multiplication.
            #[inline(always)]
            pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
                match self.get().checked_mul(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Checked division.
            #[inline(always)]
            pub const fn checked_div(self, rhs: Self) -> Option<Self> {
                match self.get().checked_div(rhs.get()) {
                    Some(v) => Some(Self::new(v)),
                    None => None,
                }
            }

            /// Saturating addition.
            #[inline(always)]
            pub const fn saturating_add(self, rhs: Self) -> Self {
                Self::new(self.get().saturating_add(rhs.get()))
            }

            /// Saturating subtraction.
            #[inline(always)]
            pub const fn saturating_sub(self, rhs: Self) -> Self {
                Self::new(self.get().saturating_sub(rhs.get()))
            }

            /// Whether the value is zero.
            #[inline(always)]
            pub const fn is_zero(self) -> bool {
                self.get() == 0
            }

            /// Whether the value is negative.
            #[inline(always)]
            pub const fn is_negative(self) -> bool {
                self.get() < 0
            }

            /// Absolute value (wraps on MIN).
            #[inline(always)]
            pub const fn abs(self) -> Self {
                Self::new(self.get().wrapping_abs())
            }
        }

        impl From<$native> for $name {
            #[inline(always)]
            fn from(v: $native) -> Self { Self::new(v) }
        }

        impl From<$name> for $native {
            #[inline(always)]
            fn from(v: $name) -> Self { v.get() }
        }

        impl PartialOrd for $name {
            #[inline(always)]
            fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
                Some(self.cmp(other))
            }
        }

        impl Ord for $name {
            #[inline(always)]
            fn cmp(&self, other: &Self) -> core::cmp::Ordering {
                self.get().cmp(&other.get())
            }
        }

        impl core::fmt::Debug for $name {
            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
                write!(f, "{}({})", stringify!($name), self.get())
            }
        }

        impl core::fmt::Display for $name {
            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
                write!(f, "{}", self.get())
            }
        }

        unsafe impl Projectable for $name {}
        // SAFETY: #[repr(transparent)] over [u8; N]: alignment 1, no padding,
        // every bit pattern valid, no internal pointers.
        unsafe impl $crate::pod::Zeroable for $name {}
        unsafe impl $crate::pod::Pod for $name {}

        $crate::__wire_arith_ops!($name, $native);
    };
}

/// Internal: emit arithmetic operator impls for a wire integer type.
///
/// Mirrors Rust's native integer behavior: panic on overflow in debug,
/// wrap in release. Programs that need explicit semantics should use the
/// `checked_*`, `saturating_*`, or `wrapping_*` inherent methods.
#[doc(hidden)]
#[macro_export]
macro_rules! __wire_arith_ops {
    ($name:ident, $native:ty) => {
        impl core::ops::Add for $name {
            type Output = Self;
            #[inline(always)]
            fn add(self, rhs: Self) -> Self {
                Self::new(self.get() + rhs.get())
            }
        }
        impl core::ops::Sub for $name {
            type Output = Self;
            #[inline(always)]
            fn sub(self, rhs: Self) -> Self {
                Self::new(self.get() - rhs.get())
            }
        }
        impl core::ops::Mul for $name {
            type Output = Self;
            #[inline(always)]
            fn mul(self, rhs: Self) -> Self {
                Self::new(self.get() * rhs.get())
            }
        }
        impl core::ops::Div for $name {
            type Output = Self;
            #[inline(always)]
            fn div(self, rhs: Self) -> Self {
                Self::new(self.get() / rhs.get())
            }
        }
        impl core::ops::Rem for $name {
            type Output = Self;
            #[inline(always)]
            fn rem(self, rhs: Self) -> Self {
                Self::new(self.get() % rhs.get())
            }
        }
        impl core::ops::Add<$native> for $name {
            type Output = Self;
            #[inline(always)]
            fn add(self, rhs: $native) -> Self {
                Self::new(self.get() + rhs)
            }
        }
        impl core::ops::Sub<$native> for $name {
            type Output = Self;
            #[inline(always)]
            fn sub(self, rhs: $native) -> Self {
                Self::new(self.get() - rhs)
            }
        }
        impl core::ops::Mul<$native> for $name {
            type Output = Self;
            #[inline(always)]
            fn mul(self, rhs: $native) -> Self {
                Self::new(self.get() * rhs)
            }
        }
        impl core::ops::Div<$native> for $name {
            type Output = Self;
            #[inline(always)]
            fn div(self, rhs: $native) -> Self {
                Self::new(self.get() / rhs)
            }
        }
        impl core::ops::Rem<$native> for $name {
            type Output = Self;
            #[inline(always)]
            fn rem(self, rhs: $native) -> Self {
                Self::new(self.get() % rhs)
            }
        }
        impl core::ops::AddAssign for $name {
            #[inline(always)]
            fn add_assign(&mut self, rhs: Self) {
                *self = *self + rhs;
            }
        }
        impl core::ops::SubAssign for $name {
            #[inline(always)]
            fn sub_assign(&mut self, rhs: Self) {
                *self = *self - rhs;
            }
        }
        impl core::ops::MulAssign for $name {
            #[inline(always)]
            fn mul_assign(&mut self, rhs: Self) {
                *self = *self * rhs;
            }
        }
        impl core::ops::DivAssign for $name {
            #[inline(always)]
            fn div_assign(&mut self, rhs: Self) {
                *self = *self / rhs;
            }
        }
        impl core::ops::RemAssign for $name {
            #[inline(always)]
            fn rem_assign(&mut self, rhs: Self) {
                *self = *self % rhs;
            }
        }
        impl core::ops::AddAssign<$native> for $name {
            #[inline(always)]
            fn add_assign(&mut self, rhs: $native) {
                *self = *self + rhs;
            }
        }
        impl core::ops::SubAssign<$native> for $name {
            #[inline(always)]
            fn sub_assign(&mut self, rhs: $native) {
                *self = *self - rhs;
            }
        }
        impl core::ops::MulAssign<$native> for $name {
            #[inline(always)]
            fn mul_assign(&mut self, rhs: $native) {
                *self = *self * rhs;
            }
        }
        impl core::ops::DivAssign<$native> for $name {
            #[inline(always)]
            fn div_assign(&mut self, rhs: $native) {
                *self = *self / rhs;
            }
        }
        impl core::ops::RemAssign<$native> for $name {
            #[inline(always)]
            fn rem_assign(&mut self, rhs: $native) {
                *self = *self % rhs;
            }
        }
        impl PartialEq<$native> for $name {
            #[inline(always)]
            fn eq(&self, other: &$native) -> bool {
                self.get() == *other
            }
        }
        impl PartialOrd<$native> for $name {
            #[inline(always)]
            fn partial_cmp(&self, other: &$native) -> Option<core::cmp::Ordering> {
                Some(self.get().cmp(other))
            }
        }
    };
}

// ---- Unsigned wire types ---------------------------------------------

le_integer! {
    /// 64-bit unsigned little-endian integer. Alignment 1.
    ///
    /// The workhorse type for token amounts, lamport balances, timestamps,
    /// and most on-chain numeric fields. Use this instead of `u64` in any
    /// `#[repr(C)]` struct that will be projected from account data.
    LeU64, u64, 8, unsigned
}

le_integer! {
    /// 32-bit unsigned little-endian integer. Alignment 1.
    LeU32, u32, 4, unsigned
}

le_integer! {
    /// 16-bit unsigned little-endian integer. Alignment 1.
    LeU16, u16, 2, unsigned
}

// ---- Signed wire types -----------------------------------------------

le_integer! {
    /// 64-bit signed little-endian integer. Alignment 1.
    ///
    /// Used for timestamps (unix_timestamp is i64), deltas, and any
    /// signed arithmetic in account data.
    LeI64, i64, 8, signed
}

le_integer! {
    /// 32-bit signed little-endian integer. Alignment 1.
    LeI32, i32, 4, signed
}

le_integer! {
    /// 16-bit signed little-endian integer. Alignment 1.
    LeI16, i16, 2, signed
}

// ---- LeBool ----------------------------------------------------------

/// Boolean wire type. Alignment 1.
///
/// Stored as a single byte: 0 = false, nonzero = true.
/// [`LeBool::is_canonical`] returns true only for 0 or 1, which lets callers
/// reject non-canonical encodings.
#[repr(transparent)]
#[derive(Clone, Copy, Default, Eq, PartialEq, Hash)]
pub struct LeBool(u8);

impl LeBool {
    /// Canonical true value.
    pub const TRUE: Self = Self(1);

    /// Canonical false value.
    pub const FALSE: Self = Self(0);

    /// Construct from a Rust bool.
    #[inline(always)]
    pub const fn new(v: bool) -> Self {
        Self(v as u8)
    }

    /// Read as a Rust bool (0 = false, anything else = true).
    #[inline(always)]
    pub const fn get(self) -> bool {
        self.0 != 0
    }

    /// Raw byte value.
    #[inline(always)]
    pub const fn raw(self) -> u8 {
        self.0
    }

    /// Whether the byte is strictly 0 or 1 (canonical representation).
    ///
    /// Non-canonical values (2..=255) are technically "true" but may
    /// indicate data corruption or an incompatible writer.
    #[inline(always)]
    pub const fn is_canonical(self) -> bool {
        self.0 == 0 || self.0 == 1
    }
}

impl From<bool> for LeBool {
    #[inline(always)]
    fn from(v: bool) -> Self {
        Self::new(v)
    }
}

impl From<LeBool> for bool {
    #[inline(always)]
    fn from(v: LeBool) -> Self {
        v.get()
    }
}

impl core::fmt::Debug for LeBool {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "LeBool({})", self.get())
    }
}

impl core::fmt::Display for LeBool {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{}", self.get())
    }
}

// SAFETY: LeBool is #[repr(transparent)] over u8. All bit patterns valid
// (`get()` treats any nonzero byte as true; `is_canonical()` flags 2..=255).
unsafe impl Projectable for LeBool {}
// SAFETY: as above, alignment 1, no padding, every bit pattern valid.
unsafe impl crate::pod::Zeroable for LeBool {}
unsafe impl crate::pod::Pod for LeBool {}

// ---- LeU128 ----------------------------------------------------------

/// 128-bit unsigned little-endian integer. Alignment 1.
///
/// Useful for large amounts (e.g., total supply tracking) where u64
/// would overflow. Stored as 16 bytes in account data.
#[repr(transparent)]
#[derive(Clone, Copy, Default, Eq, PartialEq, Hash)]
pub struct LeU128([u8; 16]);

impl LeU128 {
    pub const ZERO: Self = Self([0; 16]);
    pub const MAX: Self = Self(u128::MAX.to_le_bytes());

    #[inline(always)]
    pub const fn new(v: u128) -> Self {
        Self(v.to_le_bytes())
    }

    #[inline(always)]
    pub const fn get(self) -> u128 {
        u128::from_le_bytes(self.0)
    }

    #[inline(always)]
    pub const fn to_le_bytes(self) -> [u8; 16] {
        self.0
    }

    #[inline(always)]
    pub const fn checked_add(self, rhs: Self) -> Option<Self> {
        match self.get().checked_add(rhs.get()) {
            Some(v) => Some(Self::new(v)),
            None => None,
        }
    }

    #[inline(always)]
    pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
        match self.get().checked_sub(rhs.get()) {
            Some(v) => Some(Self::new(v)),
            None => None,
        }
    }

    #[inline(always)]
    pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
        match self.get().checked_mul(rhs.get()) {
            Some(v) => Some(Self::new(v)),
            None => None,
        }
    }

    #[inline(always)]
    pub const fn saturating_add(self, rhs: Self) -> Self {
        Self::new(self.get().saturating_add(rhs.get()))
    }

    #[inline(always)]
    pub const fn saturating_sub(self, rhs: Self) -> Self {
        Self::new(self.get().saturating_sub(rhs.get()))
    }

    #[inline(always)]
    pub const fn is_zero(self) -> bool {
        self.get() == 0
    }
}

impl From<u128> for LeU128 {
    #[inline(always)]
    fn from(v: u128) -> Self {
        Self::new(v)
    }
}

impl From<LeU128> for u128 {
    #[inline(always)]
    fn from(v: LeU128) -> Self {
        v.get()
    }
}

impl PartialOrd for LeU128 {
    #[inline(always)]
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for LeU128 {
    #[inline(always)]
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        self.get().cmp(&other.get())
    }
}

impl core::fmt::Debug for LeU128 {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "LeU128({})", self.get())
    }
}

impl core::fmt::Display for LeU128 {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{}", self.get())
    }
}

unsafe impl Projectable for LeU128 {}
// SAFETY: #[repr(transparent)] over [u8; 16]: alignment 1, no padding,
// every bit pattern valid, no internal pointers.
unsafe impl crate::pod::Zeroable for LeU128 {}
unsafe impl crate::pod::Pod for LeU128 {}

__wire_arith_ops!(LeU128, u128);

#[cfg(test)]
mod tests {
    use super::*;

    fn require_pod<T: crate::pod::Pod>() {}

    /// Every wire type must satisfy the substrate `Pod` overlay contract so
    /// the Pod-bounded APIs (`lens::read_field_pod`, `segment_ref`) accept
    /// the crate's own alignment-1 types.
    #[test]
    fn wire_types_satisfy_substrate_pod() {
        require_pod::<LeU64>();
        require_pod::<LeU32>();
        require_pod::<LeU16>();
        require_pod::<LeI64>();
        require_pod::<LeI32>();
        require_pod::<LeI16>();
        require_pod::<LeBool>();
        require_pod::<LeU128>();
    }

    #[test]
    fn wire_roundtrip_and_checked_math() {
        let a = LeU64::new(u64::MAX - 1);
        assert_eq!(a.get(), u64::MAX - 1);
        assert_eq!(a.checked_add(LeU64::new(1)), Some(LeU64::MAX));
        assert_eq!(LeU64::MAX.checked_add(LeU64::new(1)), None);
        assert_eq!(LeU64::ZERO.checked_sub(LeU64::new(1)), None);
        assert!(LeBool::new(true).get());
        assert!(!LeBool::FALSE.get());
        assert!(LeBool::TRUE.is_canonical());
    }
}