hopper-native 0.1.0

Hopper's sovereign raw backend for Solana. Zero-copy account access, direct syscall layer, CPI infrastructure, PDA helpers, and entrypoint glue. no_std, no_alloc, no external runtime dependencies.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

//! Hopper Native -- sovereign raw backend for Solana.
//!
//! Direct syscall-native runtime layer purpose-built for zero-copy state
//! frameworks. A sovereign substrate with genuinely novel features no other
//! framework provides:
//!
//! - **Alignment-safe wire types**: `LeU64`, `LeU32`, `LeBool` etc. --
//!   alignment-1 types with checked arithmetic by default, explicit
//!   endianness, const constructors. The foundation for safe zero-copy
//!   structs. (`wire`)
//! - **Verified CPI**: `LamportSnapshot`, `DataFingerprint` -- snapshot
//!   state before CPI, verify post-conditions after. First framework to
//!   provide substrate-level CPI result verification. (`verify`)
//! - **Cross-program lenses**: `read_address()`, `read_le_u64()` -- read
//!   specific fields from foreign program accounts by byte offset without
//!   importing their types at compile time. (`lens`)
//! - **Instruction introspection**: `is_cpi()`, `require_top_level()`,
//!   `require_ed25519_instruction()` -- CPI guard and precompile
//!   signature verification patterns. (`introspect`)
//! - **SVM-optimized memory**: `memcpy`, `memset`, `memcmp` -- dispatch
//!   to the VM's JIT-compiled intrinsics instead of Rust's libc. (`mem`)
//! - **Lazy account parsing**: `LazyContext` -- dispatch on instruction
//!   data before touching any accounts, parse only what you need. (`lazy`)
//! - **Compile-time capability types**: `SignerView`, `WritableView`,
//!   `MutableView`, `OwnedView` -- prove account roles in the type system
//!   with zero runtime cost after boundary validation. (`capability`)
//! - **Zero-copy struct projection**: `project::<T>()` with bounds,
//!   alignment, and discriminator checks in one operation. (`project`)
//! - **CU budget tracking**: `CuBudget` snapshots and `cu_trace!` macro
//!   for structured profiling. (`budget`)
//! - **Hash syscall wrappers**: `sha256`, `keccak256` -- zero-alloc
//!   multi-part hashing via direct syscalls. (`hash`)
//! - **Typed CPI return data**: `invoke_and_read::<T>()` -- CPI +
//!   deserialization in one step. (`return_data`)
//! - **Chainable validation**: `account.check_signer()?.check_writable()?`
//!   -- Steel-inspired fluent validation, improved and built in. (`account_view`)
//! - **Packed flags**: `account.flags()`, `account.expect_flags(SIGNER|WRITABLE)`
//!   -- check multiple account properties in a single comparison. (`account_view`)
//! - **Full sysvar access**: Clock, Rent, EpochSchedule with computed
//!   helpers. (`sysvar`)
//! - **Batch operations**: `close_and_transfer`, `realloc_checked`,
//!   `require_account_type` with proper atomicity. (`batch`)
//!
//! `no_std`, `no_alloc`, zero external runtime dependencies.

#![no_std]
#![deny(unsafe_op_in_unsafe_fn)]

// ── Core modules (always available) ──────────────────────────────────

pub mod account_view;
pub mod address;
pub mod borrow;
pub mod entrypoint;
pub mod error;
pub mod log;
pub mod pda;
pub mod pod;
pub mod raw_account;
pub mod raw_input;
pub mod syscalls;

// ── Innovation modules ───────────────────────────────────────────────

pub mod batch;
pub mod budget;
pub mod capability;
pub mod hash;
pub mod introspect;
pub mod lazy;
pub mod lens;
pub mod mem;
/// Cross-program projection lens traits (`Projectable`, `SafeProjectable`).
///
/// **Tier-C escape hatch** per the Hopper Safety Audit. The module
/// stays compiled because other low-level helpers (wire overlays,
/// typed return-data, the `expert` tier) use `Projectable` internally,
/// but its public re-export is gated behind the default-on
/// `legacy-projectable` feature. New code should prefer `Pod`-bounded
/// helpers (`lens::read_field_pod`, the `ZeroCopy` trait family in
/// `hopper-runtime`, `AccountView::segment_ref`/`segment_mut`).
#[doc(hidden)]
pub mod project;
pub mod return_data;
pub mod sysvar;
pub mod verify;
pub mod wire;

// ── Safety tier modules ──────────────────────────────────────────────

pub mod expert;
pub mod raw;
pub mod safe;

// ── CPI modules (feature-gated) ─────────────────────────────────────

#[cfg(feature = "cpi")]
pub mod cpi;
#[cfg(feature = "cpi")]
pub mod instruction;
#[cfg(feature = "cpi")]
pub mod system;
#[cfg(feature = "cpi")]
pub mod token;

// ── Re-exports ───────────────────────────────────────────────────────

pub use account_view::AccountView;
pub use address::Address;
pub use borrow::{Ref, RefMut};
pub use error::ProgramError;
pub use pod::Pod;

// Re-export bytemuck so downstream macros can reference it through
// the hopper dependency chain without every user adding bytemuck to
// their own Cargo.toml. `#[hopper::state]` / `#[hopper::pod]` emit
// `#[derive(::hopper::__runtime::__hopper_native::bytemuck::Pod, ...)]`
// which resolves here.
#[cfg(feature = "bytemuck")]
#[doc(hidden)]
pub use bytemuck;
pub use raw_account::RuntimeAccount;

// Innovation re-exports.
pub use budget::CuBudget;
pub use capability::{
    ExecutableView, MutableView, OwnedView, ReadonlyView, SignerView, WritableView,
};
pub use lazy::LazyContext;
pub use pda::verify_pda_strict;
pub use pda::{find_bump_for_address, read_bump_from_account, verify_pda_from_stored_bump};
#[cfg(feature = "legacy-projectable")]
pub use project::Projectable;
pub use return_data::ReturnData;
pub use verify::{BalanceSnapshot, DataFingerprint, LamportSnapshot};
pub use wire::{LeBool, LeI16, LeI32, LeI64, LeU128, LeU16, LeU32, LeU64};

/// Result type for Solana program instructions.
pub type ProgramResult = core::result::Result<(), ProgramError>;

/// Maximum number of accounts in a single transaction.
pub const MAX_TX_ACCOUNTS: usize = 254;

/// Success return code for the BPF entrypoint.
pub const SUCCESS: u64 = 0;

/// Maximum permitted data increase during realloc (10 KiB).
pub const MAX_PERMITTED_DATA_INCREASE: usize = 10_240;

/// Borrow state value indicating the account is not currently borrowed.
pub const NOT_BORROWED: u8 = u8::MAX;

// ── Convenience re-exports ───────────────────────────────────────────

#[cfg(feature = "cpi")]
pub use instruction::{CpiAccount, InstructionAccount, InstructionView, Seed, Signer};