Module prelude

Source

Expand description

One-import path for authored Hopper programs.

Re-exports§

pub use crate::guards::require;
pub use crate::guards::require_address;
pub use crate::guards::require_data_len;
pub use crate::guards::require_disc;
pub use crate::guards::require_eq;
pub use crate::guards::require_gt;
pub use crate::guards::require_gte;
pub use crate::guards::require_has_data;
pub use crate::guards::require_keys_eq;
pub use crate::guards::require_keys_neq;
pub use crate::guards::require_layout;
pub use crate::guards::require_neq;
pub use crate::guards::require_owner;
pub use crate::guards::require_payer;
pub use crate::guards::require_signer;
pub use crate::guards::require_unique_2;
pub use crate::guards::require_unique_3;
pub use crate::guards::require_version;
pub use crate::guards::require_writable;
pub use crate::receipts::emit_receipt;
pub use crate::receipts::emit_tagged_receipt;
pub use crate::receipts::emit_typed_receipt;
pub use crate::receipts::set_return_data;
pub use crate::receipts::Receipt;
pub use hopper_associated_token;
pub use hopper_system;
pub use hopper_token;
pub use hopper_token_2022;
pub use hopper_memo;

Modules§

associated_token_instructions
error: Hopper-owned program error type for Solana on-chain programs.
system_instructions: Compatibility re-exports.
token_2022_instructions
token_instructions: SPL Token instruction builders exported by Hopper.

Macros§

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_check: Composable account constraint checking.
hopper_close: Safely close an account with sentinel protection.
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: create via CPI, 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_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_validate: Build a validation pipeline declaratively.
hopper_verify_pda: PDA verification with BUMP_OFFSET optimization.
hopper_virtual: Declare a multi-account virtual state mapping.
lazy_entrypoint: Backward-compatible alias for the lazy Hopper entrypoint macro.
no_allocator
nostd_panic_handler
program_entrypoint: Declare the canonical Hopper program entrypoint.
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!.

Structs§

Account: A typed, owner-validated account (immutable).
AccountConstraint: A builder for constructing validation constraints on a single account.
AccountExplain: Human-readable explanation of a single account.
AccountHeader: The 16-byte account header, overlay-safe.
AccountMut: A typed, owner-validated account (mutable).
AccountReader: Header-aware read-only account reader.
AccountView: Zero-copy view over a Solana account.
Address: A Solana address (public key): 32 bytes, transparent layout.
Authority: Marker: an authority/signer address.
BitSet: Compact bit array overlaid on a byte slice.
CachedClock: Cached Clock sysvar fields.
CachedRent: Cached Rent sysvar fields.
CapabilitySet: A set of capabilities declared for an instruction.
Context: Execution context for a Hopper instruction handler.
ContextExplain: Human-readable explanation of a context.
DecodedReceipt: Decoded receipt from wire bytes. Useful for CLI and off-chain tooling.
ExecutionContext: Mutable execution context available during the Execute phase.
FieldInfo: Descriptor for one field in a Hopper layout.
FieldMut: Mutable typed view over a field’s bytes.
FieldRef: Immutable typed view over a field’s bytes.
FingerprintTransition: Pair of fingerprints for asserting version transitions.
FixedVec: Bounded dynamic array overlaid on a byte slice.
Frame: Execution frame holding the instruction’s accounts and data.
FrameAccount: Immutable account view within a Frame.
FrameAccountMut: Mutable account view within a Frame.
HopperAccount: A layout-bound, owner-validated account.
HopperCpi: Stack-allocated CPI call with compile-time-known account count and data size.
HopperCpiBuf: Variable-data CPI builder – const accounts, runtime data length.
HopperCtx: Typed instruction context carrying validated accounts, bumps, and metadata.
HopperHeader: The canonical 16-byte header at the start of every Hopper account.
InstructionAccount: Metadata for an account referenced in a CPI instruction.
InstructionPolicy: Instruction policy – maps capabilities to validation requirements.
InstructionView: A cross-program instruction to invoke.
InterfaceMint: Polymorphic SPL Token / Token-2022 mint overlay.
InterfaceTokenAccount: Polymorphic SPL Token / Token-2022 token-account overlay.
InvariantSet: Batch invariant checker.
Journal: An append-only journal of fixed-size entries.
JournalReader: Read-only journal view.
LayoutFingerprint: An 8-byte deterministic layout fingerprint.
LayoutInfo: Runtime metadata snapshot of an account’s layout identity.
Memo: SPL Memo CPI builder.
MigratingAccount: An account undergoing migration from layout From to layout To.
Mint: Marker: a mint address.
Mut: Writable wrapper – validates that the account is writable.
PackedMap: Packed key->value map overlaid on a byte slice.
PhasedFrame: A phased execution context that enforces ordering via type state.
PolicyPackDescriptor: Descriptor for a named policy pack with full metadata.
PostMutationValidator: Collects post-mutation checks that run after instruction execution.
Program: Marker: a program address (executable).
ProgramAccount: A generic program-owned account.
ProgramRef: A verified executable program reference.
ReallocGuard: Per-instruction realloc budget guard.
ReceiptExplain: Human-readable explanation of a decoded receipt.
RequirementSet: A set of active policy requirements.
ResolvedFrame: A frame that has been resolved with typed account references.
RingBuffer: Fixed-capacity circular buffer overlaid on a byte slice.
Seed: A single PDA seed for CPI signing.
SegmentBorrow: A single active segment borrow.
SegmentBorrowRegistry: Instruction-scoped segment borrow registry.
SegmentEntry: A segment entry in the registry.
SegmentRegistry: Read-only view over a segmented account’s registry.
SegmentRegistryMut: Mutable view over a segmented account’s registry.
SegmentedAccount: A segmented account with role-aware region access.
ShardedAccess: A sharded collection that distributes entries across multiple accounts.
Signer: A PDA signer: a set of seeds that derive the signing PDA.
SignerAccount: A verified signer account.
Slab: A fixed-size slab allocator over a byte slice.
SlotMap: Fixed-slot map overlaid on a byte slice.
SortedVec: Sorted bounded dynamic array – zero-copy with O(log n) binary search.
StateDiff: A diff between two states of account data.
StateReceipt: A structured record of a state mutation.
StateSnapshot: A stack-allocated snapshot of account data.
StaticSegment: A compile-time constant segment descriptor.
SysvarContext: Combined sysvar context for a single instruction.
TokenAccount: Marker: a token account address.
TransactionConstraint: Transaction-level constraint that validates global properties.
TransitionRulePack: Associates validation rules with specific instruction tags.
TrustFlags: Policy flags for additional constraints.
TrustProfile: A foreign-account trust profile.
TypedAddress: A 32-byte public key tagged with a phantom layout type.
UncheckedAccount: An unchecked account. No validation is performed.
UntypedAddress: An untyped 32-byte address (interop bridge).
ValidatedFrame: A frame whose accounts have been validated.
ValidationBundle: A bundle that composes multiple ValidationGroups into a single check.
ValidationContext: Context passed to each validation node.
ValidationGraph: A stack-allocated validation graph with up to N nodes.
ValidationGroup: A named group of validation rules.
VerifiedAccount: Immutable verified account – proof that validation passed.
VerifiedAccountMut: Mutable verified account – proof that validation passed, with write access.
VirtualSlot: A mapping from virtual slot index to account index.
VirtualState: A virtual state assembly mapping N slots to accounts.
WireBool: Boolean wire type stored as a single byte.
WireI16: 16-bit signed little-endian wire integer.
WireI32: 32-bit signed little-endian wire integer.
WireI64: 64-bit signed little-endian wire integer.
WireI128: 128-bit signed little-endian wire integer.
WireU16: 16-bit unsigned little-endian wire integer.
WireU32: 32-bit unsigned little-endian wire integer.
WireU64: 64-bit unsigned little-endian wire integer.
WireU128: 128-bit unsigned little-endian wire integer.

Enums§

AccessKind: Read or write access intent for a segment borrow.
Capability: Instruction capability flags.
CompatImpact: Compatibility impact level encoded in a receipt.
FailureStage: Stage of instruction execution at which a failure was recorded.
MigrationKind: The kind of migration.
Phase: Instruction execution phase encoded in a receipt.
PolicyRequirement: What validation is required when a capability is active.
ProgramError: Errors that a Solana program can return.
SegmentRole: Segment role classification.
TokenProgramKind: Which token program owns this account.
TrustLevel: Trust level for foreign account validation.

Constants§

ACCOUNT_CLOSE_CAPS: Capabilities for an account close instruction.
ACCOUNT_CLOSE_POLICY: Capabilities for an account close instruction.
ACCOUNT_INIT_CAPS: Capabilities for an account init instruction.
ACCOUNT_INIT_POLICY: Capabilities for an account initialization instruction.
ATA_PROGRAM_ID: Associated Token Account program.
AUTHORITY_CHANGE_CAPS: Capabilities for an authority change instruction.
AUTHORITY_CHANGE_POLICY: Capabilities for an instruction that modifies authority/permissions.
CLOSE_SENTINEL: Sentinel byte written to byte 0 when an account is closed. Prevents account revival attacks.
EVENT_CPI_PREFIX: Event CPI prefix. Programs should check for this at dispatch entry and return Ok(()) to allow self-CPI events to pass through.
EXTERNAL_CALL_CAPS: Capabilities for a CPI-invoking instruction.
EXTERNAL_CALL_POLICY: Capabilities for an instruction that makes external calls via CPI.
FAILED_INVARIANT_NONE: Sentinel value for failed_invariant_idx meaning “no invariant was associated with the failure”.
HEADER_EXECUTABLE: Non-duplicate + executable.
HEADER_LEN: Header length in bytes.
HEADER_SIGNER: Non-duplicate + signer.
HEADER_SIGNER_WRITABLE: Non-duplicate + signer + writable.
HEADER_WRITABLE: Non-duplicate + writable.
JOURNAL_TOUCH_CAPS: Capabilities for a journal-writing instruction.
JOURNAL_TOUCH_POLICY: Capabilities for an instruction that appends to a journal segment.
MAX_MEMO_SIGNERS: Maximum signer accounts a single memo invocation may cite.
MEMO_PROGRAM_ID: SPL Memo v2 program id: MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr.
MIGRATION_SENSITIVE_CAPS: Capabilities for a migration/realloc instruction.
MIGRATION_SENSITIVE_POLICY: Capabilities for an instruction that reallocates an account (migration-sensitive).
NAMED_POLICY_PACKS: All named policy packs with full descriptors, in order.
READ_ONLY_AUDIT_CAPS: Capabilities for a read-only audit instruction.
READ_ONLY_AUDIT_POLICY: Capabilities for a read-only audit/inspection instruction.
RECEIPT_SIZE: Receipt summary size in bytes.
RECEIPT_SIZE_LEGACY: Legacy receipt size, kept as a named constant for readers that want to quickly check if they received the shorter pre-0.2 receipt and ignore the failure-payload suffix.
SEG_ROLE_AUDIT
SEG_ROLE_CACHE
SEG_ROLE_CORE: Segment role flags – convenience constants for SegmentEntry::new().
SEG_ROLE_EXTENSION
SEG_ROLE_INDEX
SEG_ROLE_JOURNAL
SEG_ROLE_SHARD
SHARD_MUTATION_CAPS: Capabilities for a shard-modifying instruction.
SHARD_MUTATION_POLICY: Capabilities for an instruction that modifies shard data in a sharded account.
SYSTEM_PROGRAM_ID: System program address: 11111111111111111111111111111111
TOKEN_2022_PROGRAM_ID: Token-2022 program.
TOKEN_PROGRAM_ID: SPL Token program address.
TREASURY_WRITE_CAPS: Capabilities for a treasury write instruction.
TREASURY_WRITE_POLICY: Capabilities for an instruction that writes to treasury/vault balances.

Traits§

AccountMetaProvider: Trait for types that provide static metadata about themselves.
ExplainAccount: Trait for accounts that can produce a structured explanation.
FieldMap: Trait for layouts that expose field metadata in wire order.
FixedLayout: Trait for types with a compile-time known wire size.
FromAccount: Trait for types that can be constructed from an AccountView with validation.
HasView: Helper trait for types that hold an &AccountView.
HopperAccounts: Trait implemented by account structs (manually or via derive).
HopperIx: Trait defining a Hopper instruction.
HopperLayout: Trait implemented by hopper_layout! types providing layout metadata.
InstructionArgs: Trait for parsing instruction data into a typed args struct.
LayoutContract: A compile-time layout contract binding type identity to wire format.
Pod: Marker for types that can be safely overlaid on raw account bytes.
SegmentMap: Compile-time segment layout for a zero-copy struct.
TailCodec: Canonical serializer for dynamic-tail payloads.
TransparentAddress: Marker trait for types that are #[repr(transparent)] over [u8; 32].
Validatable: Trait for validation runnables (groups and graphs).
ValidateAccount: Trait for accounts that can self-validate.
ValidateArgs: Trait for args that can be validated independently of accounts.
WireType: Marker trait for types safe to use as zero-copy wire fields.

Functions§

assert_segment_field_alignment: Compile-time assertion that a type’s SegmentMap and FieldMap are isomorphic: same count, same names, same offsets, same sizes.
bps_of: Basis-point fee (floor): amount * bps / 10_000.
bps_of_ceil: Basis-point fee (ceiling): ceil(amount * bps / 10_000).
cast_unchecked^⚠: Raw unchecked cast from bytes to an immutable reference.
cast_unchecked_mut^⚠: Raw unchecked cast from bytes to a mutable reference.
check_account: Combined account check: owner + discriminator + minimum size.
check_account_fast: Fast single-compare account validation.
check_authority_fast: Validate a signer + writable account (authority) with single u32 compare.
check_cooldown_elapsed: Check that enough time has elapsed since the last operation.
check_deadline_not_passed: Check that a deadline has NOT passed (now < deadline).
check_discriminator: Check that the discriminator byte matches.
check_executable_fast: Validate an executable (program) account with single u32 compare.
check_has_one: Check has_one: a stored address in account data matches another account’s address.
check_invariant: Check a single invariant condition.
check_invariant_fn: Check a single invariant with a closure (lazy evaluation).
check_keys_eq: Check that two account addresses are equal.
check_lamport_conservation: Verify SOL conservation: total lamports before == total lamports after.
check_no_subsequent_invocation: Ensure our program is not invoked after the current instruction.
check_owner: Check that an account is owned by the expected program.
check_owner_multi: Check that an account is owned by one of the given program IDs.
check_rent_exempt: Check that an account is rent exempt.
check_signer: Check that an account is a signer.
check_signer_fast: Validate a signer account with single u32 compare.
check_size: Check minimum data size.
check_staleness: Check that data is not stale (updated recently enough).
check_state_transition: Check that a state transition is valid.
check_writable: Check that an account is writable.
check_writable_coherence: Validate that every writable account in the slice is also a signer OR is owned by our program.
check_writable_fast: Validate a writable account with single u32 compare.
checked_add: Checked addition.
checked_div: Checked division (returns error on divide by zero).
checked_div_ceil: Checked ceiling division: ceil(a / b).
checked_mul: Checked multiplication.
checked_mul_div: Compute (a * b) / c with u128 intermediate to prevent overflow.
checked_mul_div_ceil: Compute ceil((a * b) / c) with u128 intermediate.
checked_pow: Checked exponentiation via repeated squaring.
checked_sub: Checked subtraction.
cpi_invoke: Invoke a CPI with full validation.
cpi_invoke_signed: Invoke a signed CPI with full validation.
cpi_set_return_data: Set return data for the current instruction.
detect_flash_loan_bracket: Detect flash-loan bracket: same program called before AND after current.
dispatch_instruction: Read a 1-byte dispatch tag from instruction data.
dispatch_instruction_8: Read an 8-byte discriminator (Anchor/Quasar compatible).
dispatch_instruction_u16: Read a 2-byte dispatch tag (for programs with >256 instructions).
div_ceil: Compute ceil(a / b) without overflow (for u64).
emit_event: Emit a Pod event via sol_log_data.
emit_event_tagged: Emit event with a discriminator prefix for easy client-side filtering.
emit_slices: Emit one or more byte slices as a single sol_log_data entry.
find_and_verify_pda: Find a PDA and verify it matches the account, returning the bump.
hopper_entry: Typed instruction entry point.
init_header: Initialize an account’s header from a layout contract type.
interface_transfer_checked: Polymorphic TransferChecked CPI that dispatches to the program that owns the source token account.
interface_transfer_checked_signed: PDA-signing variant of interface_transfer_checked.
is_zero_address: Check if a 32-byte address is all zeros (the default/system address).
keys_eq_fast: Fast 32-byte key equality check using 4x u64 comparisons.
load_foreign_with_profile: Load a foreign account with a trust profile, returning a typed overlay.
migrate_append: Migrate an account in-place by appending new fields.
pod_from_bytes: Zero-copy cast from bytes to an immutable reference.
pod_from_bytes_mut: Zero-copy cast from bytes to a mutable reference.
pod_read: Copy a Pod value from bytes (alignment-safe).
pod_write: Write a Pod value to bytes (alignment-safe).
read_disc: Read the discriminator from account data (byte 0).
read_layout_id: Read the 8-byte layout_id from account data (bytes 4..12).
read_version: Read the version from account data (byte 1).
rent_exempt_min: Rent-exempt minimum lamports for a given data size.
require_all_unique: Verify that all accounts in a slice have unique addresses.
require_all_unique_accounts: Validate that all account addresses are unique.
require_authority: Validate an authority account: must be signer, owned by expected program.
require_data_min: Validate minimum instruction data length.
require_keys_equal: Validate two accounts have the same key (e.g., stored address == provided account).
require_lamports_gte: Validate that an account has at least min lamports.
require_owned_at: Validate that a specific account is owned by the program.
require_owned_writable: Validate a writable program-owned account.
require_signer_at: Validate that a specific account is a signer.
require_top_level: Require that the current instruction is top-level (not a CPI).
require_unique: Validate two accounts are different (no duplicates).
require_unique_signer_accounts: Validate that no duplicated account is used as a signer.
require_unique_signers: Verify that no duplicated account is used as a signer.
require_unique_writable: Verify that no duplicated account is writable.
require_unique_writable_accounts: Validate that no duplicated account is writable.
require_writable_at: Validate that a specific account is writable.
scale_amount: Scale a token amount between different decimal precisions (floor).
scale_amount_ceil: Scale a token amount between decimal precisions, rounding up.
scale_bps: Scale a value in basis points (BPS). value * bps / 10_000, with overflow protection via u128 intermediate.
scale_fraction: Scale a value by a fraction (numerator / denominator).
segment_id: Compute a segment ID from a name (const FNV-1a hash, truncated to 4 bytes).
snapshot_lamports: Snapshot lamport values for conservation checking.
to_u64: Safe narrowing cast from u128 to u64.
verify_pda: Verify a PDA with bump, using the cheap create_program_address path.
verify_pda_cached: Verify a PDA by reading the bump from account data at a known offset.
write_header: Write a complete Hopper header to the beginning of data.
zero_init: Zero-initialize a byte slice. Must be called before write_header.

Type Aliases§

ProgramResult: Result type returned by all Hopper instruction handlers.
SegmentId: A 4-byte segment identifier, computed from a name at compile time.
Token: Alias for TokenAccount.

Module prelude

Module prelude Copy item path

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Module prelude