Crate hopper

Expand description

§Hopper

Fast zero-copy Solana framework. Start with the familiar account/context facade, then opt into layout, segment, receipt, policy, migration, and schema modules only when the program needs them. Unsafe is available when you need it, and it is spelled unsafe so you can find it again.

The goals, in priority order:

Safety by default. Every account byte you touch has been owner-checked, signer-checked, layout-checked, and borrow-checked before you see it. Unsafe is an opt-in escape hatch, never a default.
Low-overhead performance. Account data points directly at the runtime input region. No deserialization pass, no heap allocation, no hidden format machinery. If it costs compute, it is because you asked for it.
Framework-grade ergonomics. #[hopper::account], #[hopper::accounts], #[hopper::program], typed wrappers such as Account<'info, T> and Signer<'info>, and the facade modules under hopper::{account, cpi, token, system} keep the beginner surface small.
Schema that travels. Every layout, instruction, event, and error is emitted as inspectable compile-time metadata. Off-chain SDKs, IDLs, client generators, and diff tools consume it without parsing source.

§Layers

hopper::prelude: beginner and migration path. Same runtime, clean import story.
hopper::{account, context, cpi, system, token, associated_token, memo}: everyday program modules.
hopper::{layout, segment, receipt, migration, interface, schema, policy}: systems-mode modules for layout evolution, field leasing, manifests, and audited escape hatches.
hopper::internal: explicit lower-crate escape hatch.

§Crate map

hopper_core: wire types, account header, segment maps, validation, collections, and opt-in advanced subsystems (frame, receipt, policy, diff, migration) behind feature gates.
hopper_runtime: the runtime surface a program actually calls. Context, Account, Pod, guards, CPI, migrations, log macros, entrypoint bridges.
hopper_macros: declarative macros. hopper_layout!, hopper_check!, hopper_error!, hopper_init!, hopper_close!, hopper_require!, hopper_manifest!, hopper_segment!, hopper_validate!, hopper_virtual!, hopper_interface!, hopper_assert_compatible!, hopper_assert_fingerprint!.
hopper_macros_proc: proc-macro DX layer. #[hopper::state], #[hopper::pod], #[hopper::context], #[hopper::program], #[hopper::migrate], #[hopper::args], #[hopper::error], #[hopper::event], #[hopper::dynamic], #[hopper::dynamic_account].
hopper_solana: SPL Token/Mint readers, Token-2022 checks, CPI guards, Pyth oracle, TWAP, Ed25519/Merkle crypto, authority rotation.
hopper_system: System Program instruction builders.
hopper_token: SPL Token instruction builders.
hopper_token_2022: Token-2022 instruction builders plus extension screening helpers.
hopper_associated_token: ATA derivation and instruction builders.
hopper_schema: layout manifests, fingerprinting, field-level diffing, compatibility verdicts, Codama/IDL projections, client generation.

§Access model

Four reads, one rule: safety first, unsafe by name.

Safe full:    account.load::<T>()        / account.load_mut::<T>()
Safe segment: ctx.segment_ref::<T>(i,o)  / ctx.segment_mut::<T>(i,o)
Explicit raw: unsafe { account.raw_ref() / account.raw_mut() }
Cross-prog:   account.load_cross_program::<T>()

load and segment_ref are the defaults. raw_ref is the escape hatch. load_cross_program is the Hopper-specific verb for reading an account owned by another program (foreign-ownership checked at the type level).

§Quick start

Declare an account layout, bind it in a context, ship a handler.

use hopper::prelude::*;

#[account(disc = 1, version = 1)]
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Vault {
    pub authority: Address,
    pub balance: WireU64,
    pub bump: u8,
}

Vault is now a zero-copy account layout with a Hopper header, layout fingerprint, schema metadata, and typed Account<'info, Vault> access. No Borsh pass, no hidden writeback pass.

Re-exports§

pub use hopper_associated_token;
pub use hopper_core;
pub use hopper_runtime;
pub use hopper_schema;
pub use hopper_solana;
pub use hopper_system;
pub use hopper_token;
pub use hopper_token_2022;

Modules§

account: Beginner-facing account surface.
address: Hopper-owned address type for Solana programs.
associated_token: Associated Token Account helpers.
context: Typed instruction context and account-binding helpers.
cpi: Cross-program invocation helpers and generated instruction parts.
error: Hopper-owned program error type for Solana on-chain programs.
events: Event and log helpers.
guards: Validation guards for Hopper programs.
interface: Cross-program layout/interface pinning helpers.
layout: Advanced layout and header surface.
memo: SPL Memo helper surface.
migration: Layout migration helpers.
pda: PDA (Program Derived Address) helpers for Hopper programs.
policy: Policy engine surface for systems-mode programs.
prelude: Framework-mode prelude for authored Hopper programs.
receipt: Receipt helpers and receipt wire types.
receipts: State receipts and event emission.
schema: Schema, manifest, and IDL projection surface.
segment: Advanced segment and field-lease surface.
system: System Program helpers.
systems: Protocol-grade Hopper surface.
token: SPL Token helpers.
token_2022: SPL Token-2022 helpers.
utils: Small utilities. Re-exported at the crate root so use hopper::utils::hint::likely; just works. Small utilities for Hopper program authors.

Macros§

address: Compile-time base58 address literal.
const_assert_pod: Compile-time assertion for safe manual Pod implementations.
err: Return an error immediately. Parallel to Anchor’s err!.
error: Alias for err!. Anchor compatibility shim so ported code needs no rename. Functionally identical.
fast_entrypoint: Backward-compatible alias for the fast Hopper entrypoint macro.
hopper_accounts: Generate a typed instruction context struct with validated account parsing.
hopper_assert_compatible: Assert that two layout versions have compatible fingerprints.
hopper_assert_fingerprint: Assert that a layout’s fingerprint matches an expected value.
hopper_check: Composable account constraint checking.
hopper_close: Safely close an account with sentinel protection.
hopper_dispatch: Macro for instruction dispatch.
hopper_dynamic_fields: Explicit sugar for declaring bounded dynamic-tail fields.
hopper_dynamic_tail: Declare a dynamic-tail payload with bounded dynamic fields.
hopper_emit_cpi: Emit a Hopper event via self-CPI for reliable indexing.
hopper_entrypoint: Declare the explicit Hopper runtime entrypoint bridge.
hopper_error: Generate sequential error codes.
hopper_fast_entrypoint: Declare the fast two-argument Hopper entrypoint.
hopper_init: Initialize an account: allocate, assign, zero-init, write header.
hopper_interface: Declare a cross-program interface view.
hopper_invariant: Invariant checking macro.
hopper_layout: Define a zero-copy account layout.
hopper_lazy_entrypoint: Declare the Hopper lazy entrypoint.
hopper_load: Destructuring sugar for raw-dispatch handlers.
hopper_log: Cheap structured logging for hot handlers.
hopper_manifest: Generate a layout manifest for schema tooling.
hopper_register_discs: Discriminator registry – compile-time uniqueness enforcement.
hopper_require: Require a condition, returning a custom error if false.
hopper_segment: Declare a segmented account with typed segments.
hopper_unsafe_region: Auditable raw-pointer boundary.
hopper_validate: Build a validation pipeline declaratively.
hopper_verify_pda: PDA verification with BUMP_OFFSET optimization.
hopper_virtual: Declare a multi-account virtual state mapping.
interface_account_set: Declare a bounded multi-layout interface account resolver.
layout_migrations: Compose a layout’s LayoutMigration::MIGRATIONS chain from a list of #[hopper::migrate]-emitted edge constants.
lazy_entrypoint: Backward-compatible alias for the lazy Hopper entrypoint macro.
msg: Backend-neutral logging macro.
no_allocator
nostd_panic_handler
program_dispatch: Generate the small runtime bridge for a #[program] module.
program_entrypoint: Declare the canonical Hopper program entrypoint.
require: Early-return with an error if the condition is false.
require_eq: Assert two values are equal, returning an error on mismatch.
require_gt: Assert left > right strictly.
require_gte: Assert left >= right, returning the supplied error on underrun. Useful for lamport / balance checks.
require_keys_eq: Assert two public keys (or any byte slices convertible via [AsRef<[u8; 32]>]) are equal. Narrower than require_eq! but matches the ergonomic spelling ecosystem migrators coming from Anchor / Jiminy are familiar with.
require_keys_neq: Assert two public keys are not equal. Used for pinning distinct accounts (authority != user, source != destination). Same coercion and error semantics as require_keys_eq!.
require_lt: Assert left < right strictly. Anchor-parity sibling of require_gt!. Default error is ProgramError::InvalidArgument because a failed ordering check most often flags a bad user input.
require_lte: Assert left <= right. Anchor-parity sibling of require_gte!.
require_neq: Assert two values are not equal. Early-returns with the supplied error on match (or ProgramError::InvalidArgument in the short form). Symmetric with require_eq!.

Crate hopper

Crate hopper Copy item path

§Hopper

§Layers

§Crate map

§Access model

§Quick start

Re-exports§

Modules§

Macros§

Crate hopper