hopper_native/
lib.rs

1//! Hopper Native -- sovereign raw backend for Solana.
2//!
3//! Direct syscall-native runtime layer purpose-built for zero-copy state
4//! frameworks. A sovereign substrate with genuinely novel features no other
5//! framework provides:
6//!
7//! - **Alignment-safe wire types**: `LeU64`, `LeU32`, `LeBool` etc. --
8//!   alignment-1 types with checked arithmetic by default, explicit
9//!   endianness, const constructors. The foundation for safe zero-copy
10//!   structs. (`wire`)
11//! - **Verified CPI**: `LamportSnapshot`, `DataFingerprint` -- snapshot
12//!   state before CPI, verify post-conditions after. First framework to
13//!   provide substrate-level CPI result verification. (`verify`)
14//! - **Cross-program lenses**: `read_address()`, `read_le_u64()` -- read
15//!   specific fields from foreign program accounts by byte offset without
16//!   importing their types at compile time. (`lens`)
17//! - **Instruction introspection**: `is_cpi()`, `require_top_level()`,
18//!   `require_ed25519_instruction()` -- CPI guard and precompile
19//!   signature verification patterns. (`introspect`)
20//! - **SVM-optimized memory**: `memcpy`, `memset`, `memcmp` -- dispatch
21//!   to the VM's JIT-compiled intrinsics instead of Rust's libc. (`mem`)
22//! - **Lazy account parsing**: `LazyContext` -- dispatch on instruction
23//!   data before touching any accounts, parse only what you need. (`lazy`)
24//! - **Compile-time capability types**: `SignerView`, `WritableView`,
25//!   `MutableView`, `OwnedView` -- prove account roles in the type system
26//!   with zero runtime cost after boundary validation. (`capability`)
27//! - **Zero-copy struct projection**: `project::<T>()` with bounds,
28//!   alignment, and discriminator checks in one operation. (`project`)
29//! - **CU budget tracking**: `CuBudget` snapshots and `cu_trace!` macro
30//!   for structured profiling. (`budget`)
31//! - **Hash syscall wrappers**: `sha256`, `keccak256` -- zero-alloc
32//!   multi-part hashing via direct syscalls. (`hash`)
33//! - **Typed CPI return data**: `invoke_and_read::<T>()` -- CPI +
34//!   deserialization in one step. (`return_data`)
35//! - **Chainable validation**: `account.check_signer()?.check_writable()?`
36//!   -- Steel-inspired fluent validation, improved and built in. (`account_view`)
37//! - **Packed flags**: `account.flags()`, `account.expect_flags(SIGNER|WRITABLE)`
38//!   -- check multiple account properties in a single comparison. (`account_view`)
39//! - **Full sysvar access**: Clock, Rent, EpochSchedule with computed
40//!   helpers. (`sysvar`)
41//! - **Batch operations**: `close_and_transfer`, `realloc_checked`,
42//!   `require_account_type` with proper atomicity. (`batch`)
43//!
44//! `no_std`, `no_alloc`, zero external runtime dependencies.
45
46#![no_std]
47#![deny(unsafe_op_in_unsafe_fn)]
48
49// ── Core modules (always available) ──────────────────────────────────
50
51pub mod account_view;
52pub mod address;
53pub mod borrow;
54pub mod entrypoint;
55pub mod error;
56pub mod log;
57pub mod pda;
58pub mod pod;
59pub mod raw_account;
60pub mod raw_input;
61pub mod syscalls;
62
63// ── Innovation modules ───────────────────────────────────────────────
64
65pub mod batch;
66pub mod budget;
67pub mod capability;
68pub mod hash;
69pub mod introspect;
70pub mod lazy;
71pub mod lens;
72pub mod mem;
73/// Cross-program projection lens traits (`Projectable`, `SafeProjectable`).
74///
75/// **Tier-C escape hatch** per the Hopper Safety Audit. The module
76/// stays compiled because other low-level helpers (wire overlays,
77/// typed return-data, the `expert` tier) use `Projectable` internally,
78/// but its public re-export is gated behind the default-on
79/// `legacy-projectable` feature. New code should prefer `Pod`-bounded
80/// helpers (`lens::read_field_pod`, the `ZeroCopy` trait family in
81/// `hopper-runtime`, `AccountView::segment_ref`/`segment_mut`).
82#[doc(hidden)]
83pub mod project;
84pub mod return_data;
85pub mod sysvar;
86pub mod verify;
87pub mod wire;
88
89// ── Safety tier modules ──────────────────────────────────────────────
90
91pub mod expert;
92pub mod raw;
93pub mod safe;
94
95// ── CPI modules (feature-gated) ─────────────────────────────────────
96
97#[cfg(feature = "cpi")]
98pub mod cpi;
99#[cfg(feature = "cpi")]
100pub mod instruction;
101#[cfg(feature = "cpi")]
102pub mod system;
103#[cfg(feature = "cpi")]
104pub mod token;
105
106// ── Re-exports ───────────────────────────────────────────────────────
107
108pub use account_view::AccountView;
109pub use address::Address;
110pub use borrow::{Ref, RefMut};
111pub use error::ProgramError;
112pub use pod::Pod;
113
114// Re-export bytemuck so downstream macros can reference it through
115// the hopper dependency chain without every user adding bytemuck to
116// their own Cargo.toml. `#[hopper::state]` / `#[hopper::pod]` emit
117// `#[derive(::hopper::__runtime::__hopper_native::bytemuck::Pod, ...)]`
118// which resolves here.
119#[cfg(feature = "bytemuck")]
120#[doc(hidden)]
121pub use bytemuck;
122pub use raw_account::RuntimeAccount;
123
124// Innovation re-exports.
125pub use budget::CuBudget;
126pub use capability::{
127    ExecutableView, MutableView, OwnedView, ReadonlyView, SignerView, WritableView,
128};
129pub use lazy::LazyContext;
130pub use pda::verify_pda_strict;
131pub use pda::{find_bump_for_address, read_bump_from_account, verify_pda_from_stored_bump};
132#[cfg(feature = "legacy-projectable")]
133pub use project::Projectable;
134pub use return_data::ReturnData;
135pub use verify::{BalanceSnapshot, DataFingerprint, LamportSnapshot};
136pub use wire::{LeBool, LeI16, LeI32, LeI64, LeU128, LeU16, LeU32, LeU64};
137
138/// Result type for Solana program instructions.
139pub type ProgramResult = core::result::Result<(), ProgramError>;
140
141/// Maximum number of accounts in a single transaction.
142pub const MAX_TX_ACCOUNTS: usize = 254;
143
144/// Success return code for the BPF entrypoint.
145pub const SUCCESS: u64 = 0;
146
147/// Maximum permitted data increase during realloc (10 KiB).
148pub const MAX_PERMITTED_DATA_INCREASE: usize = 10_240;
149
150/// Borrow state value indicating the account is not currently borrowed.
151pub const NOT_BORROWED: u8 = u8::MAX;
152
153// ── Convenience re-exports ───────────────────────────────────────────
154
155#[cfg(feature = "cpi")]
156pub use instruction::{CpiAccount, InstructionAccount, InstructionView, Seed, Signer};
hopper_native/lib.rs

hopper_native/
lib.rs
