Module segment_map 

Compile-time segment mapping for zero-copy account layouts.

SegmentMap provides a static description of the byte regions within a struct layout. This is separate from SegmentRegistry (which manages on-chain dynamic segment metadata, written into the account body at runtime). SegmentMap is compile-time knowledge that proc macros (or hand-written impls) generate from struct definitions.

When to use which

• SegmentMap + StaticSegment - fixed-layout structs annotated with #[hopper::state]. The segment list is known at compile time; lookups fold to const loads.
• SegmentRegistry + SegmentDescriptor - accounts whose segment count grows on-chain (extension-heavy patterns, Token-2022-style mints, dynamic plug-ins). The segment table lives inside the account body and is walked at runtime.

Most Hopper programs use the compile-time path. The runtime registry exists for genuinely dynamic layouts.

Design Philosophy

Segment offsets are evaluated at compile time and stored as constants. This means segment lookups compile down to a const load, no string matching, no branching, no heap. The generated code is the same shape as raw Pinocchio pointer arithmetic.

Example

// Generated by #[hopper::state] or hand-written:
impl SegmentMap for Vault {
    const SEGMENTS: &'static [StaticSegment] = &[
        StaticSegment::new("authority", 0, 32),
        StaticSegment::new("balance", 32, 8),
        StaticSegment::new("bump", 40, 1),
    ];
}

// Look up a segment:
let seg = Vault::segment("balance").unwrap();
assert_eq!(seg.offset, 32);
assert_eq!(seg.size, 8);

Structs

StaticSegment

A compile-time constant segment descriptor.

Traits

SegmentMap

Compile-time segment layout for a zero-copy struct.

Functions

assert_segment_field_alignment

Compile-time assertion that a type’s SegmentMap and FieldMap are isomorphic: same count, same names, same offsets, same sizes.