Hopper

Release status. Hopper 0.1.0 is the first public release line for the Hopper framework, CLI, and companion crates. APIs are still young, and the release surface is documented, release-checked, and scoped to the APIs exercised by this repository.

Hopper is a zero-copy state framework for Solana programs. It maps typed, fixed-layout views onto account bytes without a serialization round trip, while keeping the byte layout inspectable through headers, layout fingerprints, schema manifests, and CLI tooling.

The repository keeps framework crates, first-party examples, and release tooling together. Independent products such as the benchmark suite and SVM harness live separately so release claims stay reproducible and easy to audit.

What Hopper provides

• no_std / no_alloc framework crates for on-chain programs.
• Zero-copy typed account access over fixed-layout account bytes.
• Layout fingerprints and versioned headers for account compatibility checks.
• Segment-aware access helpers for field-level borrow tracking.
• Optional proc macros for faster authoring; the core framework remains usable without proc macros.
• Hopper Native by default for low-overhead account access with framework safety/DX, with explicit legacy Pinocchio and solana-program compatibility modes quarantined behind opt-in features.
• Schema, IDL, manager, and CLI tooling for inspecting and explaining account layouts.

Release Status

• Framework package target: hopper-framework = "0.1.0"; import it as hopper with hopper = { package = "hopper-framework", version = "0.1.0" }.
• Version-pinned docs.rs target: https://docs.rs/crate/hopper-framework/0.1.0.
• Source-backed CLI install: cargo install --path tools/hopper-cli from this repository.
• Public companion crate targets include hopper-native, hopper-runtime, hopper-core, hopper-schema, hopper-solana, hopper-token, hopper-token-2022, hopper-associated-token, hopper-system, hopper-memo, hopper-finance, hopper-lending, hopper-staking, hopper-vesting, hopper-distribute, hopper-multisig, hopper-anchor, hopper-manager, and hopper-sdk, all at 0.1.0.
• Benchmark numbers must be regenerated from the separate hopper-bench repo before any launch or comparison claim.
• Security-sensitive users should review AUDIT.md and docs/UNSAFE_INVARIANTS.md before deployment.

Quick Start

[dependencies]

hopper = { package = "hopper-framework", version = "0.1.0", features = ["proc-macros"] }

Until crates.io publication completes, use the source-backed dependency:

[dependencies]

hopper = { git = "https://github.com/BluefootLabs/Hopper-Solana-Zero-copy-State-Framework", package = "hopper-framework", features = ["proc-macros"] }

Install the CLI:

git clone https://github.com/BluefootLabs/Hopper-Solana-Zero-copy-State-Framework hopper

cd hopper

cargo install --path tools/hopper-cli

For local development inside this repository:

[dependencies]

hopper = { path = "../Hopper-Solana-Zero-copy-State-Framework", package = "hopper-framework", features = ["proc-macros"] }

Minimal layout example:

use hopper::prelude::*;

#[derive(Clone, Copy)]
#[repr(C)]
#[hopper::state(disc = 1, version = 1)]
pub struct Vault {
    pub authority: TypedAddress<Authority>,
    pub balance: WireU64,
    pub bump: u8,
}

#[hopper::program]
mod vault {
    use super::*;

    #[instruction(1)]
    pub fn deposit(ctx: Context<Deposit>, amount: u64) -> ProgramResult {
        let mut balance = ctx.vault_balance_mut()?;
        *balance = WireU64::new(balance.get() + amount);
        Ok(())
    }
}

Documentation map

• docs/GETTING_STARTED_SERIOUS.md: source-first setup and first serious program flow.
• docs/WRITING_HOPPER_PROGRAMS.md: Hopper authoring patterns and program structure.
• docs/POLICY_GUARANTEES.md: capability policy, sealed/raw/hybrid access, and the policy-vault example.
• docs/MIGRATION_FROM_ANCHOR.md: Anchor-to-Hopper migration notes.
• docs/MIGRATION_FROM_QUASAR.md: Quasar-to-Hopper migration notes.
• docs/DYNAMIC_TAILS_FROM_QUASAR.md: mapping Quasar bounded dynamic fields to Hopper fixed-body + dynamic-tail layouts.
• docs/QUASAR_PINOCCHIO_REPLACEMENT.md: what Hopper replaces from Quasar/Pinocchio and what benchmark claims still require same-provenance proof.
• docs/CLI_REFERENCE.md: lifecycle, schema, client, profiling, and manager command reference.
• docs/PUBLICATION_AUDIT.md: crate-by-crate publication and competitive-readiness audit.

Access model

Use Hopper's access tiers deliberately:

1. segment_ref_typed / generated field accessors - default hot path for field-level borrow leasing.
2. load / load_mut - validated whole-layout access.
3. segment_ref_const / dynamic segment_ref - advanced runtime-selected segment access.
4. raw_ref / raw_mut - unsafe typed escape hatch.
5. as_mut_ptr - full raw pointer escape for policy-controlled raw mode.

For variable-length account data, use #[hopper::state(dynamic_tail = T)] for small bounded payloads attached to one fixed layout, and named extension segments for larger/repeated regions that need independent borrow tracking or migration metadata.

Repository layout

The obsolete split repositories were folded back into this workspace with subtree history preserved and then archived/private on GitHub.

Sibling product repos:

• hopper-bench: benchmark harness and CU regression lab.
• hopper-svm: in-process Solana execution harness for Hopper test authors.

Backend features

Hopper Native is the default backend.

# Default backend from source

hopper = { package = "hopper-framework", version = "0.1.0" }



# Legacy Pinocchio migration/benchmark compatibility only

hopper = { package = "hopper-framework", version = "0.1.0", default-features = false, features = ["legacy-pinocchio-compat"] }



# solana-program compatibility backend

hopper = { package = "hopper-framework", version = "0.1.0", default-features = false, features = ["solana-program-backend"] }

Only one backend should be enabled for a program build.

legacy-pinocchio-compat is not Hopper's native execution story. It exists for migration tests and compatibility benchmarking. New programs should use the default Hopper Native backend.

Tooling

Useful development commands:

cargo metadata --no-deps --format-version 1

cargo test -p hopper-cli cmd::lint::tests -- --nocapture

cargo test -p hopper-framework --features proc-macros,metaplex --test constant_integration -- --nocapture

cargo test -p hopper-framework --features proc-macros,metaplex --test metaplex_context_integration -- --nocapture

The CLI source lives in tools/hopper-cli. It supports lifecycle commands, linting, schema/IDL export, manifest inspection, account decoding, client generation, manager workflows, and profile helpers.

Start with examples/hopper-policy-vault to see strict, sealed, raw, and hybrid handlers side by side. For in-process tests, use the sibling hopper-svm repo as a dev-dependency.

Benchmarks

The benchmark suite is maintained as a separate product repo:

https://github.com/BluefootLabs/hopper-bench

Do not copy old benchmark numbers from this README. Regenerate numbers from the benchmark repo before publishing performance claims.

Release-facing performance claims are Hopper-vs-Quasar only until the Anza Pinocchio target is measured from the same hopper-bench lockfile, SBF toolchain, Mollusk version, seed set, feature flags, release profile, and command line as the Hopper and Quasar columns.

Current positioning: Hopper targets low-overhead account access while adding framework safety, schema, lifecycle, CPI, and CLI tooling. Direct Pinocchio comparison claims wait for a same-provenance Pinocchio benchmark column.

Canonical reproduction command:

cd ../hopper-bench

./measure.sh all

Where Pinocchio Is Still The Right Choice

Use raw Pinocchio directly when a program wants the smallest possible substrate, manual account validation, and no framework-level schema, lifecycle, or tooling surface. Hopper is the framework-layer option for teams that want the same low-level access model plus explicit safety and developer ergonomics.

Safety posture

Hopper uses unsafe at the boundary where account bytes become typed views. The framework keeps those boundaries small and documented, but this is still a zero-copy framework and should be reviewed like one.

See:

• docs/UNSAFE_INVARIANTS.md
• AUDIT.md
• crates/hopper-core/tests/unsafe_boundary_tests.rs
• crates/hopper-core/tests/overlay_equivalence_tests.rs

License

Licensed under either of:

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.