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 borrow;
57pub mod entrypoint;
58pub mod error;
59pub mod log;
60pub mod pda;
61pub mod pod;
62pub mod raw_account;
63pub mod raw_input;
64pub mod sha256;
65pub mod syscalls;
66
67// Additional modules.
68
69pub mod batch;
70// The compute-budget tracker needs the SIMD-0049 syscall, absent from the
71// September 27, 2026 public-cluster capture; on-chain builds get it through the
72// `remaining-compute-units-syscall` feature.
73#[cfg(any(not(target_os = "solana"), feature = "remaining-compute-units-syscall"))]
74pub mod budget;
75pub mod capability;
76pub mod hash;
77pub mod introspect;
78pub mod lazy;
79pub mod lens;
80pub mod mem;
81/// Cross-program projection lens traits (`Projectable`, `SafeProjectable`).
82///
83/// **Tier-C escape hatch.** The module
84/// stays compiled because other low-level helpers (wire overlays,
85/// typed return-data, the `expert` tier) use `Projectable` internally,
86/// but its public re-export is gated behind the default-on
87/// `legacy-projectable` feature. New code should prefer `Pod`-bounded
88/// helpers (`lens::read_field_pod`, the `ZeroCopy` trait family in
89/// `hopper-runtime`, `AccountView::segment_ref`/`segment_mut`).
90#[doc(hidden)]
91pub mod project;
92pub mod return_data;
93pub mod sysvar;
94pub mod verify;
95pub mod wire;
96
97// ── Safety tier modules ──────────────────────────────────────────────
98
99pub mod expert;
100pub mod raw;
101pub mod safe;
102
103// ── CPI modules (feature-gated) ─────────────────────────────────────
104
105#[cfg(feature = "cpi")]
106pub mod cpi;
107#[cfg(feature = "cpi")]
108pub mod instruction;
109#[cfg(feature = "cpi")]
110pub mod system;
111#[cfg(feature = "cpi")]
112pub mod token;
113
114// ── Re-exports ───────────────────────────────────────────────────────
115
116pub use account_view::AccountView;
117pub use address::Address;
118pub use borrow::{Ref, RefMut};
119pub use entrypoint::{BumpAllocator, HEAP_LENGTH, HEAP_RUNTIME_RESERVED, HEAP_START_ADDRESS};
120pub use error::ProgramError;
121pub use pod::{read_unaligned_value, Pod, ValuePod, Zeroable};
122pub use raw_account::RuntimeAccount;
123
124// Additional re-exports.
125#[cfg(any(not(target_os = "solana"), feature = "remaining-compute-units-syscall"))]
126pub use budget::CuBudget;
127pub use capability::{
128    ExecutableView, MutableView, OwnedView, ReadonlyView, SignerView, WritableView,
129};
130pub use lazy::LazyContext;
131pub use pda::verify_pda_strict;
132pub use pda::{find_bump_for_address, read_bump_from_account, verify_pda_from_stored_bump};
133#[cfg(feature = "legacy-projectable")]
134pub use project::Projectable;
135pub use return_data::ReturnData;
136pub use verify::{BalanceSnapshot, DataFingerprint, LamportSnapshot};
137pub use wire::{LeBool, LeI16, LeI32, LeI64, LeU128, LeU16, LeU32, LeU64};
138
139/// Result type for Solana program instructions.
140pub type ProgramResult = core::result::Result<(), ProgramError>;
141
142/// Maximum number of accounts in a single transaction.
143pub const MAX_TX_ACCOUNTS: usize = 254;
144
145/// Success return code for the BPF entrypoint.
146pub const SUCCESS: u64 = 0;
147
148/// Maximum permitted data increase during realloc (10 KiB).
149pub const MAX_PERMITTED_DATA_INCREASE: usize = 10_240;
150
151/// Borrow state value indicating the account is not currently borrowed.
152pub const NOT_BORROWED: u8 = u8::MAX;
153
154// ── Convenience re-exports ───────────────────────────────────────────
155
156#[cfg(feature = "cpi")]
157pub use instruction::{CpiAccount, InstructionAccount, InstructionView, Seed, Signer};
hopper_native/lib.rs

hopper_native/
lib.rs
