Skip to content
hopper
Get started
Model / layers

Hopper layers

A map of the framework, runtime, schema, SPL, CLI, and example layers.

<- Docs index
This reference covers Hopper 0.5.0, published on crates.io. See the release status for package verification, dated benchmarks, and remaining audit work.

Hopper is one framework with progressive disclosure. The framework path, the account-migration path, and the systems-mode path share the same runtime, schema machinery, layout-identity model, and CPI machinery. Default/headered layouts carry the 16-byte Hopper header; opt-in compact layouts use the explicit [disc][body] contract and keep their fingerprint in manifest/IDL metadata.

Level 1: Framework Mode

Use this for new programs, tutorials, and ports that should feel like a normal Solana framework before they expose the deeper machinery.

use hopper::prelude::*;

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

Framework mode centers these pieces:

  • #[account], #[derive(Accounts)], Ctx<T>, and #[program].
  • Account<'info, T>, InitAccount<'info, T>, Signer<'info>, and Program<'info, P>.
  • hopper::account, hopper::context, hopper::cpi, hopper::system, hopper::token, hopper::token_2022, hopper::associated_token, and hopper::memo.

This path is published as hopper-lang and imported as hopper:

hopper = { package = "hopper-lang", version = "0.5.0", features = ["proc-macros"] }

See release status for registry availability. Use a local path when developing against a source checkout.

There is no separate beginner crate. The main framework crate is the canonical facade, and it grows into the same systems layer when needed.

Level 2: Structured State

Use this when account compatibility, local schema export, client generation, or publication of a losslessly representable Solana IDL v0.1 projection through Program Metadata matters. That projection is distinct from Hopper's richer public IDL. Hopper does not currently ship a generic manifest/effect registry publisher.

  • hopper::layout exposes headers, layout contracts, fingerprints, field maps, and wire types.
  • hopper::schema exposes manifests, IDL projection, resolver metadata, and generated client inputs.
  • #[hopper::account] auto-detects bounded String<'a, N> and Vec<'a, T, N> fields while lowering to Hopper's fixed-body + compact-tail model. Address / Pubkey vectors keep borrowed views; other TailElement vectors return HopperVec<T, N> values.
  • #[hopper::dynamic_account] plus #[tail(...)] remains the explicit systems-mode spelling for the same compact-tail model.
  • hopper_dynamic_tail! and hopper_dynamic_fields! attach explicit bounded dynamic payloads to fixed zero-copy layouts for custom TailCodec tails.
  • declare_program! consumes a manifest and generates typed CPI builders plus static account/effect specs.

This is the right layer for serious applications that still want one-account state contracts and predictable upgrade paths.

Level 3: Systems Mode

Use this when the program needs field leases, segmented layouts, policy receipts, explicit migrations, or foreign layout contracts.

  • hopper::systems::* is an import path for explicit state, policy, and migration APIs.
  • hopper::segment exposes segment registries, segment roles, field-level borrow tracking, and typed segment references.
  • hopper::receipt exposes execution receipts and tagged event receipts.
  • hopper::policy exposes capability policies and policy packs.
  • hopper::migration exposes layout migration edges and pending migration application.
  • hopper::interface exposes foreign manifest and interface helpers for cross-program reads.
  • hopper::internal is an explicit lower-crate escape hatch for authors who are deliberately working below the framework facade.

The systems layer publishes as hopper-systems. The source still lives in crates/hopper-core for now to preserve history and keep this rename focused; the package name is the public ecosystem name.

Level 4: Substrate Mode

Use this when a handler or benchmark target deliberately wants raw Hopper Native control.

  • hopper::substrate exports Hopper Runtime account, instruction, and result types.
  • With the Hopper Native backend, it also exports raw account views, raw input parsing, syscall modules, hashes, PDA helpers, memory helpers, CU budget probes, return data, and CPI verification primitives.
  • Review and measure handlers that use this surface. It is not the first-contact import path for normal application code.

Mental Mapping

Concept Hopper path
Program state #[hopper::account] or #[hopper::state]
Context/accounts #[derive(Accounts)], #[hopper::accounts], typed wrappers
Signer hopper::account::Signer<'info>
Typed account hopper::account::Account<'info, T>
Dynamic string/vector #[hopper::account] pretty fields, #[hopper::dynamic_account], or explicit hopper_dynamic_fields!
CPI declare_program!, hopper::cpi, SPL facade modules
Upgrade/migration layout fingerprints, hopper::migration, schema manifests
Advanced safety segment leases, receipts, policy graphs, Kani-checked invariants

Import Guide

Prefer the smallest import surface that matches the job:

use hopper::prelude::*;              // main app framework surface
use hopper::systems::*;              // state, policy, and migration APIs
use hopper::substrate::*;            // raw Hopper Native substrate surface
use hopper::{layout, segment};       // explicit systems modules
use hopper::{schema, cpi, token};     // tooling, CPI, and token facades

The public modules are additive. New users start with the main prelude and only open the systems modules when the design calls for them.

Previous
Architecture
Next
Writing programs