Skip to main content

Module zerocopy

hopper_runtime

Module zerocopy 

Source
Expand description

Unified zero-copy trait family.

The Hopper Safety Audit’s “structural” recommendation was to consolidate Pod, FixedLayout, Projectable, SafeProjectable, LayoutContract, header metadata, and schema export into one coherent trait stack. This module delivers the foundation:

  • ZeroCopy, the canonical “safe to overlay on raw bytes” marker. Equivalent-in-contract to Pod, which (under the default hopper-native-backend + bytemuck features) is a sub-trait of bytemuck::Pod + bytemuck::Zeroable. ZeroCopy is implemented for every Pod type via a blanket impl, so existing layouts participate automatically.

  • WireLayout, a ZeroCopy type with a fixed wire size. Declared once via const WIRE_SIZE = size_of::<Self>() by default; macros may override if the in-memory and on-wire sizes diverge (none do today, but the hook is there for future compressed / tagged encodings).

  • AccountLayout, a WireLayout that also carries Hopper’s account header identity (disc, version, wire fingerprint, schema epoch, type offset). This is the audit’s proposed top-level trait, matching its exact member list so the contract is frozen-in-place for migrations and client generation.

§Why three traits, not one

The layering mirrors a real capability hierarchy. Every account layout is a wire layout; every wire layout is zero-copy; but not every zero-copy type is a full account layout (u64, WireBool, TypedAddress<T> are zero-copy but carry no header). Splitting the traits lets generic helpers demand just what they need.

§Relation to LayoutContract

The existing crate::layout::LayoutContract trait predates this module. LayoutContract and AccountLayout intentionally overlap: both describe “a Hopper layout with disc/version/layout_id”. AccountLayout is the audit-blessed name with the richer member list; LayoutContract is kept for backward compatibility and gets a blanket impl so any type deriving the latter automatically satisfies the former. New authoring surfaces (the proposed #[hopper::state] v2 expansion) should reach for AccountLayout.

Traits§

AccountLayout
Hopper account layout identity, the top of the unified trait stack.
WireLayout
A ZeroCopy type with a compile-time-known wire size.
ZeroCopy
Canonical marker for types that may be overlaid on raw bytes.