Crate pinapod 

Alignment-one, zero-copy representations for Solana account and instruction bytes.

PinaPod maps validated account bytes to Rust types whose stored layout is exactly the wire layout. The derive generates the representation, and every safe reader proves the representation’s invariants before it hands out a reference.

All representations have alignment one, so a stored field can be read at any byte offset without a copy or a relocation.

Safe readers validate tags, lengths, UTF-8, enum discriminants, nested values, and slice bounds before they return a reference.

Layouts

A fixed layout always occupies Type::SIZE bytes, so a field offset never moves and every access is direct after validation. A compact layout keeps fixed fields in a header and packs active string and vector bytes after that header, so the allocation tracks active data at the cost of a resize lifecycle.

Example

A derive generates a schema over these pod types. The pods themselves are the everyday API for writing and reading a bounded value:

use pinapod::PodString;
use pinapod::PodVec;

let mut display_name = PodString::<32>::default();
display_name.try_set("ifi")?;

let mut roles = PodVec::<u16, 8>::default();
roles.try_set([7_u16, 11])?;

assert_eq!(display_name.as_str(), "ifi");
assert_eq!(roles[0], 7);

The same containers appear in a schema as String<32> and Vec<u16, 8>, and the derive generates the alignment-one representation plus its reader and writer. The book walks through a full schema.

Pod types

Type	Stored size	Meaning
PodU16 through PodU128	2 through 16 bytes	Unsigned, little-endian integer
PodI16 through PodI128	2 through 16 bytes	Signed, little-endian integer
PodBool	1 byte	Boolean with a 0 or 1 byte
PodF32	4 bytes	IEEE-754 binary32 stored as its bit pattern
PodF64	8 bytes	IEEE-754 binary64 stored as its bit pattern
PodOption<T, PFX>	PFX + size_of::<T>()	Optional fixed representation
PodString<N, PFX>	PFX + N	UTF-8 string with at most N bytes
PodVec<T, N, PFX>	PFX + N * mapped element size	Vector with at most N mapped pod elements

The schema aliases choose common prefix widths, so ordinary declarations stay short:

• String<N> is PodString<N, 1>.
• Vec<T, N> is PodVec<T, N, 2>.

Features

Feature	Adds
fixed	Mappings for signed and unsigned fixed 1.30.0 values
floats	PodF32/PodF64 and mappings for native f32/f64
solana-address	A mapping for solana_address::Address
solana-program-error	Conversion from PinaPodError to ProgramError
wincode	Canonical SchemaRead and SchemaWrite implementations

No feature is enabled by default, so the core crate stays no_std and dependency-free.

Enable only what a program reads from or writes to the wire.

Errors

Variant	Meaning
BufferTooSmall	The supplied slice cannot contain the required header, value, or active tail
Overflow	A requested write exceeds a field capacity or checked arithmetic fails
InvalidBool	A stored boolean byte is not zero or one
InvalidTag	A stored option tag is not zero or one
InvalidDiscriminant	A stored enum value has no declared variant
InvalidLength	A stored length exceeds capacity or violates the read contract
InvalidUtf8	Active string bytes are not UTF-8

Safety model

Forming a reference over account bytes is a memory-safety operation rather than a data-quality check. ZcElem is the central unsafe contract: implementors guarantee alignment one, no padding, validity for every bit pattern, and a load-bearing ZcValidate.

Prefer #[derive(PinaPod)]. Manual implementations of PinaPodFixed, PinaPodCompact, ZcElem, and ZcField are an advanced raw API.

Documentation

The PinaPod book covers layout choices, migration steps, and the safety model. Use this API reference for item signatures.

This section is synchronized by mdt and expands from api-docs.t.md. Edit the provider, then run devenv shell docs:sync.

Re-exports

pub use error::PinaPodError;

pub use pod::PodString;

pub use pod::PodVec;

pub use traits::PinaPod;

pub use traits::PinaPodCompact;

pub use traits::PinaPodFixed;

pub use traits::PinaPodPatch;

pub use traits::ZcElem;

pub use traits::ZcField;

pub use traits::ZcValidate;

Modules

error

The error type shared by every PinaPod read, validation, and update.

pod

Alignment-one storage types for schema fields.

traits

The representation contracts that a PinaPod schema implements.

Type Aliases

String

Schema-friendly string with a one-byte length prefix.

Vec

Schema-friendly vector with a two-byte length prefix.

Derive Macros

PinaPod

Generates the PinaPod storage, reader, and writer for a struct or enum.