hopper-core 0.1.0

//! # Hopper Core
//!
//! Core engine for Hopper, a zero-copy state framework for Solana.
//!
//! Typed account architecture, phased execution, composable validation,
//! zero-copy collections, layout evolution with deterministic fingerprints,
//! policy-aware capabilities, state receipts, and cross-program interfaces.
//! `no_std`, `no_alloc`, no proc macros required.
//!
//! ## Architecture
//!
//! - **Account memory**: Fixed, overlay, segmented, and arena layout styles
//! - **Execution**: `Frame`-based borrowed-state execution with phases
//! - **Validation**: Named rule groups, instruction-specific rule packs,
//!   post-mutation invariant checks, composable pipelines
//! - **Policy**: Declare instruction capabilities, auto-resolve validation
//!   requirements via `InstructionPolicy`
//! - **Receipts**: Structured mutation summaries combining snapshots, diffs,
//!   field masks, invariant results, and CPI tracking
//! - **Collections**: Zero-copy `FixedVec`, `RingBuffer`, `SlotMap`, `BitSet`,
//!   `Journal`, `Slab`, `PackedMap`
//! - **Segments**: Typed segment roles (Core, Extension, Journal, Index,
//!   Cache, Audit, Shard) for semantic classification
//! - **Fingerprints**: Deterministic layout_id from SHA-256, compile-time
//!   compatibility assertions, schema diffing
//! - **Evolution**: Append-only versioned layouts with migration helpers
//! - **Interfaces**: Cross-program read-only views with ABI proof
//!
//! Built on hopper-native. Compatible with jiminy account layouts.
//!
//! ## Feature flags
//!
//! `hopper-core` ships one hot-path core plus opt-in advanced subsystems.
//! The default feature set is `programs`, `hopper-native-backend`, `cpi`,
//! `collections`, and the `advanced` umbrella (`frame`, `receipt`, `policy`,
//! `graph`, `migrate`, `virtual-state`, `diff`, `explain`). Programs that
//! only touch raw fields and segments can disable every optional surface:
//!
//! ```toml
//! hopper-core = { version = "0.1", default-features = false,
//!                 features = ["programs", "hopper-native-backend", "cpi"] }
//! ```
//!
//! That lean configuration drops `frame`, `receipt`, `policy`, `graph`,
//! `migrate`, `virtual-state`, `diff`, `explain`, and `collections` from the
//! compile surface and leaves only the hot-path access model, validation
//! primitives, ABI, layout metadata, and CPI. Re-enable features individually
//! as the program grows.

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

#[cfg(test)]
extern crate std;

pub mod abi;
pub mod account;
pub mod accounts;
pub mod check;
#[cfg(feature = "collections")]
pub mod collections;
pub mod cpi;
pub mod dispatch;
pub mod event;
pub mod field_map;
pub mod invariant;
pub mod math;
pub mod segment_map;
pub mod state;
pub mod sysvar;
pub mod time;

// ── Advanced subsystems (feature-gated) ──────────────────────────
// These modules are real differentiators but sit outside the hot-path
// access model. Gating them lets lean programs compile only what they
// use, and communicates one clear core identity.
#[cfg(feature = "diff")]
pub mod diff;
#[cfg(feature = "frame")]
pub mod frame;
#[cfg(feature = "migrate")]
pub mod migrate;
#[cfg(feature = "policy")]
pub mod policy;
#[cfg(feature = "receipt")]
pub mod receipt;
#[cfg(feature = "virtual-state")]
pub mod virtual_state;

pub use field_map::*;

// -- Internal helpers (used by macros, not public API) ------------------------

/// Hidden re-export of hopper_runtime for macro hygiene.
/// Allows `$crate::__runtime` to resolve in macro expansions without
/// requiring the caller to have a direct `hopper_runtime` dependency.
#[doc(hidden)]
pub use hopper_runtime as __runtime;

/// Const SHA-256 helper for `hopper_layout!` layout ID generation.
///
/// When the `sha2-layout-id` feature is off (i.e. under `spartan`), this
/// falls back to a 32-byte buffer whose first 8 bytes are an FNV-1a-64
/// digest of the input. The remaining 24 bytes are derived by repeatedly
/// re-folding the same seed so macro sites that read beyond index 7 still
/// see a well-defined, deterministic value. This keeps the `hopper_layout!`
/// call site type-stable across feature flags.
#[doc(hidden)]
pub const fn __sha256_const(data: &[u8]) -> [u8; 32] {
    #[cfg(feature = "sha2-layout-id")]
    {
        sha2_const_stable::Sha256::new().update(data).finalize()
    }
    #[cfg(not(feature = "sha2-layout-id"))]
    {
        __fnv_expand_const(data)
    }
}

/// FNV-1a-64 const implementation used under `spartan`. Returns 32 bytes so
/// the macro surface is unchanged: bytes[0..8] carry the primary digest,
/// bytes[8..32] carry re-folded digests of the same input with a
/// differentiating byte mixed in per block. This preserves "32 bytes of
/// output" invariance without pretending the hash function is SHA-256.
#[doc(hidden)]
#[cfg(not(feature = "sha2-layout-id"))]
pub const fn __fnv_expand_const(data: &[u8]) -> [u8; 32] {
    const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
    const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
    let mut out = [0u8; 32];
    let mut block: u8 = 0;
    while block < 4 {
        let mut h: u64 = FNV_OFFSET ^ (block as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15);
        let mut i = 0;
        while i < data.len() {
            h ^= data[i] as u64;
            h = h.wrapping_mul(FNV_PRIME);
            i += 1;
        }
        let le = h.to_le_bytes();
        let base = (block as usize) * 8;
        out[base] = le[0];
        out[base + 1] = le[1];
        out[base + 2] = le[2];
        out[base + 3] = le[3];
        out[base + 4] = le[4];
        out[base + 5] = le[5];
        out[base + 6] = le[6];
        out[base + 7] = le[7];
        block += 1;
    }
    out
}

/// Const string equality helper for BUMP_OFFSET field scanning.
#[doc(hidden)]
pub const fn __str_eq(a: &str, b: &str) -> bool {
    let a = a.as_bytes();
    let b = b.as_bytes();
    if a.len() != b.len() {
        return false;
    }
    let mut i = 0;
    while i < a.len() {
        if a[i] != b[i] {
            return false;
        }
        i += 1;
    }
    true
}

/// Public const string equality (alias of `__str_eq` for internal crate use).
#[doc(hidden)]
pub const fn const_str_eq(a: &str, b: &str) -> bool {
    __str_eq(a, b)
}

/// Compute an Anchor-compatible 8-byte discriminator at compile time.
///
/// Anchor discriminators are `sha256("global:{instruction_name}")[0..8]`.
/// This function enables Hopper programs to interoperate with Anchor IDLs
/// and Quasar programs that use the same discriminator scheme.
///
/// Gated on the `anchor-compat` feature (default ON). The Anchor
/// discriminator is defined in terms of SHA-256, so this function is
/// compiled out under the `spartan` profile rather than silently
/// substituting a non-compatible hash.
///
/// ```ignore
/// const INIT_DISC: [u8; 8] = hopper_core::anchor_discriminator("initialize");
/// ```
#[cfg(feature = "anchor-compat")]
pub const fn anchor_discriminator(instruction_name: &str) -> [u8; 8] {
    let hash = sha2_const_stable::Sha256::new()
        .update(b"global:")
        .update(instruction_name.as_bytes())
        .finalize();
    [
        hash[0], hash[1], hash[2], hash[3], hash[4], hash[5], hash[6], hash[7],
    ]
}

/// Compute an Anchor-compatible 8-byte account discriminator at compile time.
///
/// Account discriminators are `sha256("account:{TypeName}")[0..8]`.
/// Gated on `anchor-compat`; see [`anchor_discriminator`] for rationale.
#[cfg(feature = "anchor-compat")]
pub const fn anchor_account_discriminator(type_name: &str) -> [u8; 8] {
    let hash = sha2_const_stable::Sha256::new()
        .update(b"account:")
        .update(type_name.as_bytes())
        .finalize();
    [
        hash[0], hash[1], hash[2], hash[3], hash[4], hash[5], hash[6], hash[7],
    ]
}

/// Narrow, hot-path-only prelude.
///
/// The finish-line audit demanded that Hopper's "core identity" stay
/// tight: **memory + access + layout**. Everything else, frame-based
/// execution, receipts, policies, validation graphs, migrations, virtual
/// state, diffing, explain, is opt-in power, not launch identity.
///
/// This prelude ships only the types and helpers a Hopper program needs
/// to declare state, bind accounts, check invariants, and make CPIs.
/// For the full surface (historical compatibility), use
/// [`prelude`](crate::prelude) which glob-imports this and then adds the
/// advanced subsystems on top.
pub mod prelude_core {
    // ── ABI primitives: typed addresses, role tags ──────────────────
    pub use crate::abi::{
        Authority, LayoutFingerprint, Mint, Program, Token, TokenAccount, TypedAddress,
        UntypedAddress,
    };

    // ── Account memory: headers, overlays, pod casts ────────────────
    pub use crate::account::{
        cast_unchecked, cast_unchecked_mut, pod_from_bytes, pod_from_bytes_mut, pod_read,
        pod_write, read_layout_id, write_header, zero_init, AccountHeader, AccountReader,
        FixedLayout, Pod, ReallocGuard, VerifiedAccount, VerifiedAccountMut, CLOSE_SENTINEL,
        HEADER_LEN,
    };

    // ── Account wrappers: typed instruction parameters ──────────────
    pub use crate::accounts::{
        hopper_entry, AccountMetaProvider, HopperAccount, HopperAccounts, HopperCtx, HopperIx,
        ProgramAccount, ProgramRef, SegmentedAccount, SignerAccount, UncheckedAccount,
        ValidateAccount,
    };

    // ── Checks: signer, owner, PDA, discriminator ───────────────────
    pub use crate::check::fast::{
        check_account_fast, check_authority_fast, check_executable_fast, check_signer_fast,
        check_writable_fast, HEADER_EXECUTABLE, HEADER_SIGNER, HEADER_SIGNER_WRITABLE,
        HEADER_WRITABLE,
    };
    pub use crate::check::modifier::{
        Account, AccountMut, FromAccount, HasView, HopperLayout, Mut, Signer,
    };
    pub use crate::check::{
        check_account, check_discriminator, check_executable, check_has_one, check_keys_eq,
        check_owner, check_owner_multi, check_program, check_rent_exempt, check_signer, check_size,
        check_writable, find_and_verify_pda, is_zero_address, keys_eq_fast, rent_exempt_min,
        verify_pda, verify_pda_cached,
    };

    // ── Dispatch and events: program plumbing ───────────────────────
    pub use crate::dispatch::{
        dispatch_instruction, dispatch_instruction_8, dispatch_instruction_u16, EVENT_CPI_PREFIX,
    };
    #[cfg(feature = "cpi")]
    pub use crate::event::emit_event_cpi;
    pub use crate::event::{emit_event, emit_event_tagged, emit_slices};

    // ── Field + segment metadata (compile-time layout truth) ────────
    pub use crate::field_map::{FieldInfo, FieldMap};
    pub use crate::segment_map::{assert_segment_field_alignment, SegmentMap, StaticSegment};
    pub use hopper_runtime::segment_borrow::{AccessKind, SegmentBorrow, SegmentBorrowRegistry};
    pub use hopper_runtime::Segment;

    // ── CPI plumbing ────────────────────────────────────────────────
    pub use crate::cpi::{HopperCpi, HopperCpiBuf};

    // ── Math + time + sysvar: everyday program helpers ──────────────
    pub use crate::invariant::{check_invariant, check_invariant_fn, InvariantSet};
    pub use crate::math::{
        bps_of, bps_of_ceil, checked_add, checked_div, checked_div_ceil, checked_mul,
        checked_mul_div, checked_mul_div_ceil, checked_pow, checked_sub, div_ceil, scale_amount,
        scale_amount_ceil, scale_bps, scale_fraction, to_u64,
    };
    pub use crate::state::check_state_transition;
    pub use crate::sysvar::{CachedClock, CachedRent, SysvarContext};
    pub use crate::time::{check_cooldown_elapsed, check_deadline_not_passed, check_staleness};

    // ── On-chain segment metadata (for segmented accounts) ──────────
    pub use crate::account::segment_role::{
        SegmentRole, SEG_ROLE_AUDIT, SEG_ROLE_CACHE, SEG_ROLE_CORE, SEG_ROLE_EXTENSION,
        SEG_ROLE_INDEX, SEG_ROLE_JOURNAL, SEG_ROLE_SHARD,
    };
    pub use crate::account::{
        segment_id, SegmentEntry, SegmentId, SegmentRegistry, SegmentRegistryMut,
    };

    // ── Anchor-compatible discriminators ────────────────────────────
    #[cfg(feature = "anchor-compat")]
    pub use crate::{anchor_account_discriminator, anchor_discriminator};

    // ── Collections: zero-copy containers (default-on feature) ──────
    #[cfg(feature = "collections")]
    pub use crate::collections::journal::{Journal, JournalReader};
    #[cfg(feature = "collections")]
    pub use crate::collections::slab::Slab;
    #[cfg(feature = "collections")]
    pub use crate::collections::{BitSet, FixedVec, PackedMap, RingBuffer, SlotMap, SortedVec};
}

/// Advanced subsystem prelude: everything outside the core identity.
///
/// Re-exports the feature-gated surfaces, frame, receipts, policies,
/// validation graphs, migrations, virtual state, diffs, explain,
/// additional check helpers, trust profiles. Each item respects the
/// feature flag that controls its module; disable the feature and the
/// item silently disappears from this prelude, keeping lean programs
/// compiling against [`prelude_core`] alone.
pub mod prelude_advanced {
    // Composite check guards (payer, authority, lamport conservation, …)
    pub use crate::check::guards::{
        check_lamport_conservation, check_writable_coherence, require_all_unique,
        require_authority, require_owned_writable, require_payer, require_unique_signers,
        require_unique_writable, snapshot_lamports,
    };
    pub use crate::check::trust::{
        load_foreign_with_profile, TrustFlags, TrustLevel, TrustProfile,
    };
    pub use crate::check::{
        check_no_subsequent_invocation, detect_flash_loan_bracket, require_top_level,
    };

    #[cfg(feature = "diff")]
    pub use crate::diff::{StateDiff, StateSnapshot};

    #[cfg(feature = "explain")]
    pub use crate::accounts::{AccountExplain, ContextExplain, ExplainAccount};

    #[cfg(feature = "migrate")]
    pub use crate::accounts::MigratingAccount;

    #[cfg(feature = "frame")]
    pub use crate::frame::args::{InstructionArgs, ValidateArgs};
    #[cfg(feature = "frame")]
    pub use crate::frame::phase::{ExecutionContext, PhasedFrame, ResolvedFrame, ValidatedFrame};
    #[cfg(feature = "frame")]
    pub use crate::frame::{Frame, FrameAccount, FrameAccountMut};

    #[cfg(feature = "graph")]
    pub use crate::check::graph::{
        require_all_unique_accounts, require_data_min, require_keys_equal, require_lamports_gte,
        require_owned_at, require_signer_at, require_unique, require_unique_signer_accounts,
        require_unique_writable_accounts, require_writable_at, AccountConstraint,
        PostMutationValidator, TransactionConstraint, TransitionRulePack, Validatable,
        ValidationBundle, ValidationContext, ValidationGraph, ValidationGroup,
    };

    #[cfg(feature = "migrate")]
    pub use crate::migrate::{migrate_append, MigrationKind};

    #[cfg(feature = "policy")]
    pub use crate::policy::{
        Capability, CapabilitySet, InstructionPolicy, PolicyPackDescriptor, PolicyRequirement,
        RequirementSet, ACCOUNT_CLOSE_CAPS, ACCOUNT_CLOSE_POLICY, ACCOUNT_INIT_CAPS,
        ACCOUNT_INIT_POLICY, AUTHORITY_CHANGE_CAPS, AUTHORITY_CHANGE_POLICY, EXTERNAL_CALL_CAPS,
        EXTERNAL_CALL_POLICY, JOURNAL_TOUCH_CAPS, JOURNAL_TOUCH_POLICY, MIGRATION_SENSITIVE_CAPS,
        MIGRATION_SENSITIVE_POLICY, NAMED_POLICY_PACKS, READ_ONLY_AUDIT_CAPS,
        READ_ONLY_AUDIT_POLICY, SHARD_MUTATION_CAPS, SHARD_MUTATION_POLICY, TREASURY_WRITE_CAPS,
        TREASURY_WRITE_POLICY,
    };

    #[cfg(feature = "receipt")]
    pub use crate::receipt::{
        CompatImpact, DecodedReceipt, FailureStage, Phase, ReceiptExplain, StateReceipt,
        FAILED_INVARIANT_NONE, RECEIPT_SIZE, RECEIPT_SIZE_LEGACY,
    };

    #[cfg(feature = "virtual-state")]
    pub use crate::virtual_state::{ShardedAccess, VirtualSlot, VirtualState};
}

/// Prelude re-exports for ergonomic usage.
///
/// Backwards-compatible: re-exports both [`prelude_core`] and
/// [`prelude_advanced`] so existing `use hopper::prelude::*;` code keeps
/// compiling. New code that wants the lean surface should reach for
/// [`prelude_core`] directly; feature-gated builds can rely on it
/// alone once the advanced subsystems are turned off.
pub mod prelude {
    pub use crate::abi::*;
    pub use crate::abi::{
        Authority, Mint, Program, Token, TokenAccount, TypedAddress, UntypedAddress,
    };
    pub use crate::abi::{FingerprintTransition, LayoutFingerprint};
    pub use crate::account::segment_role::{
        SegmentRole, SEG_ROLE_AUDIT, SEG_ROLE_CACHE, SEG_ROLE_CORE, SEG_ROLE_EXTENSION,
        SEG_ROLE_INDEX, SEG_ROLE_JOURNAL, SEG_ROLE_SHARD,
    };
    pub use crate::account::{
        cast_unchecked, cast_unchecked_mut, pod_from_bytes, pod_from_bytes_mut, pod_read,
        pod_write, read_layout_id, write_header, zero_init, AccountHeader, AccountReader,
        FixedLayout, Pod, ReallocGuard, VerifiedAccount, VerifiedAccountMut, CLOSE_SENTINEL,
        HEADER_LEN,
    };
    pub use crate::account::{
        segment_id, SegmentEntry, SegmentId, SegmentRegistry, SegmentRegistryMut,
    };
    #[cfg(feature = "migrate")]
    pub use crate::accounts::MigratingAccount;
    pub use crate::accounts::{
        hopper_entry, AccountMetaProvider, HopperAccount, HopperAccounts, HopperCtx, HopperIx,
        ProgramAccount, ProgramRef, SegmentedAccount, SignerAccount, UncheckedAccount,
        ValidateAccount,
    };
    #[cfg(feature = "explain")]
    pub use crate::accounts::{AccountExplain, ContextExplain, ExplainAccount};
    #[cfg(feature = "anchor-compat")]
    pub use crate::anchor_account_discriminator;
    #[cfg(feature = "anchor-compat")]
    pub use crate::anchor_discriminator;
    pub use crate::check::fast::{
        check_account_fast, check_authority_fast, check_executable_fast, check_signer_fast,
        check_writable_fast, HEADER_EXECUTABLE, HEADER_SIGNER, HEADER_SIGNER_WRITABLE,
        HEADER_WRITABLE,
    };
    #[cfg(feature = "graph")]
    pub use crate::check::graph::{
        require_all_unique_accounts, require_data_min, require_keys_equal, require_lamports_gte,
        require_owned_at, require_signer_at, require_unique, require_unique_signer_accounts,
        require_unique_writable_accounts, require_writable_at, AccountConstraint,
        PostMutationValidator, TransactionConstraint, TransitionRulePack, Validatable,
        ValidationBundle, ValidationContext, ValidationGraph, ValidationGroup,
    };
    pub use crate::check::guards::{
        check_lamport_conservation, check_writable_coherence, require_all_unique,
        require_authority, require_owned_writable, require_payer, require_unique_signers,
        require_unique_writable, snapshot_lamports,
    };
    pub use crate::check::modifier::{
        Account, AccountMut, FromAccount, HasView, HopperLayout, Mut, Signer,
    };
    pub use crate::check::trust::{
        load_foreign_with_profile, TrustFlags, TrustLevel, TrustProfile,
    };
    pub use crate::check::{
        check_account, check_discriminator, check_has_one, check_keys_eq,
        check_no_subsequent_invocation, check_owner, check_owner_multi, check_rent_exempt,
        check_signer, check_size, check_writable, detect_flash_loan_bracket, find_and_verify_pda,
        is_zero_address, keys_eq_fast, rent_exempt_min, require_top_level, verify_pda,
        verify_pda_cached,
    };
    #[cfg(feature = "collections")]
    pub use crate::collections::journal::{Journal, JournalReader};
    #[cfg(feature = "collections")]
    pub use crate::collections::slab::Slab;
    #[cfg(feature = "collections")]
    pub use crate::collections::{BitSet, FixedVec, PackedMap, RingBuffer, SlotMap, SortedVec};
    pub use crate::cpi::{HopperCpi, HopperCpiBuf};
    #[cfg(feature = "diff")]
    pub use crate::diff::{StateDiff, StateSnapshot};
    pub use crate::dispatch::{
        dispatch_instruction, dispatch_instruction_8, dispatch_instruction_u16, EVENT_CPI_PREFIX,
    };
    #[cfg(feature = "cpi")]
    pub use crate::event::emit_event_cpi;
    pub use crate::event::{emit_event, emit_event_tagged, emit_slices};
    pub use crate::field_map::{FieldInfo, FieldMap};
    #[cfg(feature = "frame")]
    pub use crate::frame::args::{InstructionArgs, ValidateArgs};
    #[cfg(feature = "frame")]
    pub use crate::frame::phase::{ExecutionContext, PhasedFrame, ResolvedFrame, ValidatedFrame};
    #[cfg(feature = "frame")]
    pub use crate::frame::{Frame, FrameAccount, FrameAccountMut};
    pub use crate::invariant::{check_invariant, check_invariant_fn, InvariantSet};
    pub use crate::math::{
        bps_of, bps_of_ceil, checked_add, checked_div, checked_div_ceil, checked_mul,
        checked_mul_div, checked_mul_div_ceil, checked_pow, checked_sub, div_ceil, scale_amount,
        scale_amount_ceil, scale_bps, scale_fraction, to_u64,
    };
    #[cfg(feature = "migrate")]
    pub use crate::migrate::{migrate_append, MigrationKind};
    #[cfg(feature = "policy")]
    pub use crate::policy::{
        Capability,
        CapabilitySet,
        InstructionPolicy,
        PolicyPackDescriptor,
        PolicyRequirement,
        RequirementSet,
        ACCOUNT_CLOSE_CAPS,
        ACCOUNT_CLOSE_POLICY,
        ACCOUNT_INIT_CAPS,
        ACCOUNT_INIT_POLICY,
        AUTHORITY_CHANGE_CAPS,
        AUTHORITY_CHANGE_POLICY,
        EXTERNAL_CALL_CAPS,
        EXTERNAL_CALL_POLICY,
        JOURNAL_TOUCH_CAPS,
        JOURNAL_TOUCH_POLICY,
        MIGRATION_SENSITIVE_CAPS,
        MIGRATION_SENSITIVE_POLICY,
        NAMED_POLICY_PACKS,
        READ_ONLY_AUDIT_CAPS,
        READ_ONLY_AUDIT_POLICY,
        SHARD_MUTATION_CAPS,
        SHARD_MUTATION_POLICY,
        TREASURY_WRITE_CAPS,
        // Named policy packs
        TREASURY_WRITE_POLICY,
    };
    #[cfg(feature = "receipt")]
    pub use crate::receipt::{
        CompatImpact, DecodedReceipt, FailureStage, Phase, ReceiptExplain, StateReceipt,
        FAILED_INVARIANT_NONE, RECEIPT_SIZE, RECEIPT_SIZE_LEGACY,
    };
    pub use crate::segment_map::{assert_segment_field_alignment, SegmentMap, StaticSegment};
    pub use crate::state::check_state_transition;
    pub use crate::sysvar::{CachedClock, CachedRent, SysvarContext};
    pub use crate::time::{check_cooldown_elapsed, check_deadline_not_passed, check_staleness};
    #[cfg(feature = "virtual-state")]
    pub use crate::virtual_state::{ShardedAccess, VirtualSlot, VirtualState};
    pub use hopper_runtime::segment_borrow::{AccessKind, SegmentBorrow, SegmentBorrowRegistry};
}