hopper_native/
lib.rs

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

hopper_native/
lib.rs
