Struct HPSVM 

pub struct HPSVM { /* private fields */ }

Implementations

impl HPSVM

pub fn new() -> Self

Creates the basic test environment.

pub fn builder() -> HpsvmBuilder

Create a typed builder for explicit, compile-time-checked environment assembly.

pub fn with_inspector<I: Inspector + 'static>(self, inspector: I) -> Self

Installs an execution inspector that observes top-level transaction activity.

pub fn new_debuggable(enable_register_tracing: bool) -> Self

Available on crate feature register-tracing only.

Create a test environment with debugging features.

This constructor allows enabling low-level VM debugging capabilities, such as register tracing, which are baked into program executables at load time and cannot be changed afterwards.

When enable_register_tracing is true:

• Programs are loaded with register tracing support
• A default DefaultRegisterTracingCallback is installed
• Trace data is written to SBF_TRACE_DIR (or target/sbf/trace by default)

pub const fn set_compute_budget(&mut self, compute_budget: ComputeBudget)

Advanced reconfiguration. Replaces the runtime compute budget and invalidates any previously transacted but uncommitted outcomes.

pub const fn set_sigverify(&mut self, sigverify: bool)

Advanced reconfiguration. Enables or disables signature verification for future transactions and invalidates any previously transacted but uncommitted outcomes.

pub const fn set_blockhash_check(&mut self, check: bool)

Advanced reconfiguration. Enables or disables blockhash checking for future transactions and invalidates any previously transacted but uncommitted outcomes.

pub fn set_sysvars(&mut self)

pub fn set_feature_set( &mut self, feature_set: FeatureSet, ) -> Result<(), HPSVMError>

Advanced reconfiguration. Replaces the active feature set, rebuilds any materialized feature-dependent state, and invalidates previously transacted but uncommitted outcomes.

pub fn set_feature_accounts(&mut self)

pub fn set_builtins(&mut self)

pub fn set_lamports(&mut self, lamports: u64)

pub fn set_default_programs(&mut self)

pub fn set_spl_programs(&mut self)

pub fn set_transaction_history(&mut self, capacity: usize)

Advanced reconfiguration. Changes the transaction history capacity. Set this to 0 to disable history and allow duplicate transactions.

pub fn set_account_source(&mut self, source: impl AccountSource + 'static)

Advanced reconfiguration. Installs a read-through account source for future lookups and invalidates previously transacted but uncommitted outcomes.

pub const fn set_log_bytes_limit(&mut self, limit: Option<usize>)

Advanced reconfiguration. Adjusts the log truncation limit for future execution and invalidates previously transacted but uncommitted outcomes.

pub fn set_precompiles(&mut self)

pub fn minimum_balance_for_rent_exemption(&self, data_len: usize) -> u64

Returns minimum balance required to make an account with specified data length rent exempt.

pub fn get_account(&self, address: &Address) -> Option<Account>

Returns all information associated with the account of the provided pubkey.

pub fn try_get_account( &self, address: &Address, ) -> Result<Option<Account>, AccountSourceError>

Returns account data while preserving failures from a configured external source.

pub fn set_account( &mut self, address: Address, data: Account, ) -> Result<(), HPSVMError>

⚠️ ADVANCED USE ONLY ⚠️

Sets all information associated with the account of the provided pubkey.

This writes directly into the in-memory test state. It does not execute the owning program or replay the full transaction pipeline, so it is best used for fixtures, snapshots, and explicit state surgery between transactions. Prefer airdrop or send_transaction when you want a protocol-consistent state transition.

pub const fn accounts(&self) -> AccountsView<'_>

⚠️ ADVANCED USE ONLY ⚠️

Returns a read-only view of the internal accounts database.

This provides read-only access to the accounts database for advanced inspection. Use get_account for normal account retrieval.

Examples

use hpsvm::HPSVM;

let svm = HPSVM::new();

// Read-only access to accounts data
let accounts = svm.accounts();
// ... inspect internal state if needed

pub fn get_balance(&self, address: &Address) -> Option<u64>

Gets the balance of the provided account pubkey.

pub const fn latest_blockhash(&self) -> Hash

Gets the latest blockhash.

pub const fn block_env(&self) -> BlockEnv

Gets the current block environment.

pub fn set_sysvar<T>(&mut self, sysvar: &T) -> Result<(), HPSVMError>

where T: Sysvar + SysvarId + SysvarSerialize,

⚠️ ADVANCED USE ONLY ⚠️

Sets the sysvar in the test environment.

This is a direct override intended for tests that need to manipulate runtime context. It bypasses transaction execution.

Returns an error if serialization fails or if the sysvar account update is rejected by the internal accounts database.

pub fn get_sysvar<T>(&self) -> T

where T: Sysvar + SysvarId + DeserializeOwned,

Gets a sysvar from the test environment.

pub fn get_transaction( &self, signature: &Signature, ) -> Option<&TransactionResult>

Gets a transaction from the transaction history.

pub fn airdrop_pubkey(&self) -> Address

Returns the pubkey of the internal airdrop account.

pub fn airdrop(&mut self, address: &Address, lamports: u64) -> TransactionResult

Airdrops lamports by submitting an internal system transfer transaction.

Unlike set_account, this goes through the normal execution pipeline instead of mutating balances directly.

pub fn add_builtin( &mut self, program_id: Address, entrypoint: BuiltinFunctionWithContext, )

Adds a builtin program to the test environment.

pub fn add_program_from_file( &mut self, program_id: impl Into<Address>, path: impl AsRef<Path>, ) -> Result<(), HPSVMError>

Adds an SBF program to the test environment from the file specified.

pub fn add_program( &mut self, program_id: impl Into<Address>, program_bytes: &[u8], ) -> Result<(), HPSVMError>

Adds an SBF program to the test environment.

Uses BPFLoaderUpgradeable by default for the loader.

pub fn add_program_with_loader( &mut self, program_id: impl Into<Address>, program_bytes: &[u8], loader_id: Address, ) -> Result<(), HPSVMError>

Adds an SBF program with a specific loader to match mainnet CU behavior.

Use bpf_loader::id() for BPFLoader2, bpf_loader_deprecated::id() for BPFLoader1, or bpf_loader_upgradeable::id() for the upgradeable loader.

pub fn send_transaction( &mut self, tx: impl Into<VersionedTransaction>, ) -> TransactionResult

Submits a signed transaction and commits its post-state to this VM instance.

This updates accounts, transaction history, and other in-memory runtime state, so it intentionally requires &mut self. hpsvm is optimized for fast, in-process testing of a single mutable environment rather than Sealevel-style concurrent scheduling within one instance.

pub fn process_instruction_case( &self, case: &InstructionCase, ) -> Result<ExecutionOutcome, HPSVMError>

Executes a single instruction case against a cloned VM without mutating this instance.

pub fn process_instruction( &mut self, instruction: Instruction, ) -> TransactionResult

Processes one instruction as a synthetic transaction and commits its post-state.

This is a convenience for instruction-level harnesses that do not need to construct and sign a full transaction. Signature verification is bypassed for this synthetic transaction only; blockhash and runtime behavior still use this VM’s current environment.

pub fn process_instruction_with_accounts( &mut self, instruction: Instruction, pre_accounts: impl IntoIterator<Item = (Address, Account)>, ) -> Result<TransactionMetadata, FailedTransactionMetadata>

Processes one instruction after first writing the provided account states.

Explicit accounts are written to the VM before execution, then the instruction post-state is committed just like HPSVM::process_instruction.

pub fn process_instruction_chain( &mut self, instructions: impl IntoIterator<Item = Instruction>, ) -> TransactionResult

Processes multiple instructions atomically and commits their post-state.

pub fn process_instruction_chain_with_accounts( &mut self, instructions: impl IntoIterator<Item = Instruction>, pre_accounts: impl IntoIterator<Item = (Address, Account)>, ) -> TransactionResult

Processes multiple instructions atomically after first writing explicit account states.

pub fn simulate_instruction( &self, instruction: Instruction, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

Simulates one instruction without committing post-state.

pub fn simulate_instruction_with_accounts( &self, instruction: Instruction, pre_accounts: impl IntoIterator<Item = (Address, Account)>, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

Simulates one instruction with explicit temporary account states.

pub fn simulate_instruction_chain( &self, instructions: impl IntoIterator<Item = Instruction>, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

Simulates multiple instructions atomically without committing post-state.

pub fn simulate_instruction_chain_with_accounts( &self, instructions: impl IntoIterator<Item = Instruction>, pre_accounts: impl IntoIterator<Item = (Address, Account)>, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

Simulates multiple instructions atomically with explicit temporary account states.

pub fn try_transact( &self, tx: impl Into<VersionedTransaction>, ) -> Result<ExecutionOutcome, HPSVMError>

Executes a signed transaction without committing its post-state.

The returned ExecutionOutcome is bound to this VM instance and its current state version. Commit it back to the same HPSVM before any intervening state or config mutation. Otherwise HPSVM::commit_transaction returns ResanitizationNeeded.

pub fn transact(&self, tx: impl Into<VersionedTransaction>) -> ExecutionOutcome

pub fn commit_transaction( &mut self, outcome: ExecutionOutcome, ) -> TransactionResult

Commits a previously transacted execution outcome to this VM instance.

Outcomes are valid only for the VM instance and state version that produced them. If this VM mutated after HPSVM::transact created the outcome, or if the outcome came from a different VM instance, this returns ResanitizationNeeded.

pub fn plan_transaction_batch<T>( &self, txs: impl IntoIterator<Item = T>, ) -> Result<TransactionBatchPlan, TransactionBatchError>

where T: Into<VersionedTransaction>,

Plans a conflict-aware transaction batch without committing any state.

The returned stages contain indexes into the original input order. Stages are built greedily from account read/write conflicts and form the basis for higher-level batch schedulers.

pub fn send_transaction_batch<T>( &mut self, txs: impl IntoIterator<Item = T>, ) -> Result<TransactionBatchExecutionResult, TransactionBatchError>

where T: Into<VersionedTransaction>,

Submits a batch of transactions and returns a conflict-aware schedule.

Execution results are returned in the original input order. Transactions in the same conflict-free stage are executed against cloned snapshots in parallel, then their disjoint account deltas are merged back into this VM before the next stage begins.

pub fn simulate_transaction( &self, tx: impl Into<VersionedTransaction>, ) -> Result<SimulatedTransactionInfo, FailedTransactionMetadata>

Simulates a transaction without committing post-state.

pub fn expire_blockhash(&mut self)

Expires the current blockhash.

pub fn warp_to_slot(&mut self, slot: u64)

Warps the clock to the specified slot.

pub const fn get_compute_budget(&self) -> Option<ComputeBudget>

Gets the current compute budget.

pub const fn get_sigverify(&self) -> bool

pub fn get_feature_set(&self) -> Arc<FeatureSet>

Available on crate feature internal-test only.

pub fn set_invocation_inspect_callback<C: InvocationInspectCallback + 'static>( &mut self, callback: C, )

Available on crate feature invocation-inspect-callback only.

pub fn register_custom_syscall( &mut self, name: &str, syscall: BuiltinFunction<InvokeContext<'static, 'static>>, ) -> Result<(), HPSVMError>

Advanced reconfiguration. Registers a custom syscall in both program runtime environments (v1 and v2).

This can be called on a freshly constructed HPSVM::new() instance or on an existing environment after programs have already been loaded. The runtime environments are refreshed and cached programs are rebuilt so subsequent executions see the new syscall.

Returns an error if runtime refresh, syscall registration, or program cache rebuilding fails.

Trait Implementations

impl Clone for HPSVM

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HPSVM

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HPSVM

fn default() -> Self

Returns the “default value” for a type.

impl InvokeContextCallback for HPSVM

Available on crate feature precompiles only.

fn is_precompile(&self, program_id: &Address) -> bool

Returns true if the program_id corresponds to a precompiled program

fn process_precompile( &self, program_id: &Address, data: &[u8], instruction_data_slices: Vec<&[u8]>, ) -> Result<(), PrecompileError>

Calls the precompiled program corresponding to the given program ID.

fn get_epoch_stake(&self) -> u64

Returns the total current epoch stake for the network.

fn get_epoch_stake_for_vote_account(&self, _vote_address: &Address) -> u64

Returns the current epoch stake for the given vote account.