hopper_runtime/

segment.rs

//! Runtime-local segment primitive.
//!
//! `Segment` stores an absolute byte offset and size in two `u32` fields. It is
//! `Copy`, const-constructable, and carries no field name. The corresponding
//! `hopper_core::segment_map::StaticSegment` adds a name for schema and tooling
//! use.
//!
//! # Design
//!
//! Generated accessors can embed a `Segment` constant next to their layout
//! metadata:
//!
//! - macros emit `const BALANCE: Segment = Segment::body(0, 8);`
//! - call sites read `account.segment_mut_const::<u64>(&mut b, BALANCE)?`
//! - the compiler can propagate the constant through bounds checks and pointer
//!   arithmetic.
//!
//! `Segment` never appears in an on-chain layout, it is a compile-time
//! description only. Use `hopper_core::account::SegmentDescriptor` for
//! bytes that travel on the wire.

use crate::layout::HopperHeader;

/// Compile-time descriptor of a typed byte range inside an account.
///
/// The `u32` fields match Hopper's segment metadata encoding and keep the
/// descriptor eight bytes wide.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[repr(C)]
pub struct Segment {
    /// Absolute byte offset from the start of account data (includes
    /// the 16-byte Hopper header). This is what the access primitives
    /// want, so storing it absolute avoids a runtime addition.
    pub offset: u32,
    /// Byte size of the segment.
    pub size: u32,
}

impl Segment {
    /// Construct a segment from an absolute offset (measured from the
    /// start of account data, including the Hopper header).
    #[inline(always)]
    pub const fn new(offset: u32, size: u32) -> Self {
        Self { offset, size }
    }

    /// Construct a segment from a body-relative offset (offset measured
    /// past the 16-byte Hopper header). This is the form that macros
    /// most often emit: `#[hopper::state]` computes field offsets
    /// relative to the struct body, and body-relative is what
    /// `SegmentMap::SEGMENTS` stores.
    #[inline(always)]
    pub const fn body(body_offset: u32, size: u32) -> Self {
        Self {
            offset: HopperHeader::SIZE as u32 + body_offset,
            size,
        }
    }

    /// One-past-the-end byte offset, widened to `u64` so `offset + size`
    /// cannot wrap before containment and overlap comparisons.
    #[inline(always)]
    pub const fn end(&self) -> u64 {
        self.offset as u64 + self.size as u64
    }

    /// Whether two segments share any byte.
    #[inline(always)]
    pub const fn overlaps(&self, other: &Segment) -> bool {
        (self.offset as u64) < other.end() && (other.offset as u64) < self.end()
    }

    /// Whether this segment is contained fully within `container`.
    #[inline(always)]
    pub const fn contained_in(&self, container: &Segment) -> bool {
        self.offset >= container.offset && self.end() <= container.end()
    }
}

// ══════════════════════════════════════════════════════════════════════
//  TypedSegment<T, const OFFSET: u32>
// ══════════════════════════════════════════════════════════════════════
//
// Where `Segment` carries `(offset, size)` at runtime, `TypedSegment`
// folds **both** values into the type system: `T` determines the size
// via `size_of::<T>()`, and `OFFSET` is a const generic. The struct
// itself is a ZST, no memory at all. This is the runtime's
// const-generic segment implementation: at every
// call site the compiler substitutes the literal offset and literal
// size into the bounds check + pointer add, leaving pure
// `ptr + constant` arithmetic in the emitted BPF.
//
// Use `TypedSegment` when you know the layout at compile time (i.e.
// every `#[hopper::state]` field). Fall back to `Segment` when the
// offset is data-dependent (e.g. a user-provided index into a fixed
// array).

/// Compile-time typed segment descriptor: `T` is the overlay type,
/// `OFFSET` is the absolute byte offset from the start of account
/// data. Zero-sized.
///
/// ```ignore
/// // Matches Vault.balance at body offset 0, past the 16-byte header:
/// const VAULT_BALANCE: TypedSegment<WireU64, { HopperHeader::SIZE as u32 }>
///     = TypedSegment::new();
///
/// let bal = account.segment_ref_typed(&mut borrows, VAULT_BALANCE)?;
/// ```
#[derive(Copy, Clone, Debug, Default)]
pub struct TypedSegment<T: crate::Pod, const OFFSET: u32> {
    _marker: core::marker::PhantomData<fn() -> T>,
}

impl<T: crate::Pod, const OFFSET: u32> TypedSegment<T, OFFSET> {
    /// Construct the marker. Runs entirely at compile time.
    #[inline(always)]
    pub const fn new() -> Self {
        Self {
            _marker: core::marker::PhantomData,
        }
    }

    /// The absolute byte offset of this segment (`OFFSET` const-generic).
    #[inline(always)]
    pub const fn offset() -> u32 {
        OFFSET
    }

    /// The byte size of this segment (`size_of::<T>()`, folded at compile time).
    #[inline(always)]
    pub const fn size() -> u32 {
        core::mem::size_of::<T>() as u32
    }

    /// One-past-the-end byte offset, widened like [`Segment::end`].
    #[inline(always)]
    pub const fn end() -> u64 {
        OFFSET as u64 + core::mem::size_of::<T>() as u64
    }

    /// Lower to a runtime [`Segment`] when a heterogeneous collection
    /// of segments is needed (e.g. a validation pass that iterates).
    #[inline(always)]
    pub const fn as_segment() -> Segment {
        Segment::new(OFFSET, core::mem::size_of::<T>() as u32)
    }
}

// SAFETY: Proof that `TypedSegment` really is zero-sized.
const _: () = {
    assert!(
        core::mem::size_of::<TypedSegment<[u8; 8], 0>>() == 0,
        "TypedSegment must be zero-sized so it costs nothing to pass around",
    );
};

/// Generic field role for account field capability descriptors.
pub const FIELD_ROLE_DATA: u8 = 0;
/// Field carries authority or signer identity semantics.
pub const FIELD_ROLE_AUTHORITY: u8 = 1;
/// Field carries accounting or balance semantics.
pub const FIELD_ROLE_BALANCE: u8 = 2;
/// Field carries migration/versioning semantics.
pub const FIELD_ROLE_VERSION: u8 = 3;
/// Field is intended to become immutable after initialization.
pub const FIELD_POLICY_IMMUTABLE_AFTER_INIT: u8 = 1 << 0;
/// Field mutations should use checked arithmetic.
pub const FIELD_POLICY_CHECKED_MATH: u8 = 1 << 1;
/// Field mutations should be gated by an admin or authority proof.
pub const FIELD_POLICY_AUTHORITY_GATED: u8 = 1 << 2;

/// Zero-sized field capability: type, byte offset, semantic role, and policy.
///
/// This is the runtime half of proof-carrying field access. Macros and tooling
/// can emit these ZSTs for each account field, then require a matching
/// capability in higher-level mutation helpers without storing extra metadata
/// in the account body.
#[derive(Copy, Clone, Debug, Default)]
pub struct FieldCapability<T: crate::Pod, const OFFSET: u32, const ROLE: u8, const POLICY: u8> {
    _marker: core::marker::PhantomData<fn() -> T>,
}

impl<T: crate::Pod, const OFFSET: u32, const ROLE: u8, const POLICY: u8>
    FieldCapability<T, OFFSET, ROLE, POLICY>
{
    #[inline(always)]
    pub const fn new() -> Self {
        Self {
            _marker: core::marker::PhantomData,
        }
    }

    #[inline(always)]
    pub const fn role() -> u8 {
        ROLE
    }

    #[inline(always)]
    pub const fn policy() -> u8 {
        POLICY
    }

    #[inline(always)]
    pub const fn typed_segment() -> TypedSegment<T, OFFSET> {
        TypedSegment::new()
    }

    #[inline(always)]
    pub const fn as_segment() -> Segment {
        TypedSegment::<T, OFFSET>::as_segment()
    }

    #[inline(always)]
    pub const fn has_policy(flag: u8) -> bool {
        POLICY & flag != 0
    }
}

// SAFETY: Field capabilities must also remain ZSTs.
const _: () = {
    assert!(
        core::mem::size_of::<FieldCapability<[u8; 8], 0, FIELD_ROLE_DATA, 0>>() == 0,
        "FieldCapability must be zero-sized",
    );
};

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

    #[test]
    fn typed_segment_is_zero_sized() {
        assert_eq!(core::mem::size_of::<TypedSegment<[u8; 8], 16>>(), 0);
    }

    #[test]
    fn typed_segment_offset_and_size_fold() {
        const S: TypedSegment<[u8; 8], 16> = TypedSegment::new();
        // The values come from the type system directly.
        assert_eq!(TypedSegment::<[u8; 8], 16>::offset(), 16);
        assert_eq!(TypedSegment::<[u8; 8], 16>::size(), 8);
        assert_eq!(TypedSegment::<[u8; 8], 16>::end(), 24);
        let _ = S; // ensure const ctor works
    }

    #[test]
    fn typed_segment_lowers_to_runtime_segment() {
        const S: Segment = TypedSegment::<[u8; 8], 16>::as_segment();
        assert_eq!(S.offset, 16);
        assert_eq!(S.size, 8);
    }

    #[test]
    fn body_adds_header() {
        let s = Segment::body(0, 8);
        assert_eq!(s.offset, HopperHeader::SIZE as u32);
        assert_eq!(s.size, 8);
        assert_eq!(s.end(), HopperHeader::SIZE as u64 + 8);
    }

    #[test]
    fn overlaps_detects_shared_bytes() {
        let a = Segment::new(0, 16);
        let b = Segment::new(8, 16);
        let c = Segment::new(16, 16);
        assert!(a.overlaps(&b));
        assert!(!a.overlaps(&c)); // adjacent, no shared bytes
        assert!(b.overlaps(&c));
    }

    #[test]
    fn contained_in_reports_proper_nesting() {
        let outer = Segment::new(0, 32);
        let inner = Segment::new(8, 8);
        let equal = Segment::new(0, 32);
        let escape = Segment::new(24, 16);
        assert!(inner.contained_in(&outer));
        assert!(equal.contained_in(&outer));
        assert!(!escape.contained_in(&outer));
    }

    #[test]
    fn end_arithmetic_does_not_wrap_at_u32_max() {
        // Pre-fix, `end()` wrapped: offset u32::MAX + size 2 → end 1,
        // making this segment falsely "contained" in a small container
        // and falsely non-overlapping with its own bytes.
        let huge = Segment::new(u32::MAX, 2);
        let container = Segment::new(0, 32);
        assert_eq!(huge.end(), u32::MAX as u64 + 2);
        assert!(!huge.contained_in(&container));
        assert!(!huge.overlaps(&container));
        // And it does overlap a range that genuinely reaches it.
        let touching = Segment::new(u32::MAX, 1);
        assert!(huge.overlaps(&touching));
    }
}