HPSVM

📍 Overview

hpsvm is a fast and lightweight library for testing Solana programs. It works by creating an in-process Solana VM optimized for program developers. This makes it much faster to run and compile than alternatives like solana-program-test and solana-test-validator. In a further break from tradition, it has an ergonomic API with sane defaults and extensive configurability for those who want it.

hpsvm is optimized for low-overhead, in-process test execution. It does not try to emulate Sealevel-style concurrent scheduling inside a single VM instance. State-committing APIs such as send_transaction intentionally mutate one in-memory test environment in place.

This is a pure Rust library, making it ideal for Rust-native Solana development workflows.

✨ Features

• 🚀 High Performance: In-process VM avoids validator process and RPC overhead, so tests run significantly faster than external validators
• 🛠️ Easy to Use: Simple API with sensible defaults and comprehensive configuration options
• 🔧 Pure Rust: No external dependencies or runtime requirements beyond Rust
• 📊 Comprehensive Testing: Supports transactions, account management, and program execution
• 🔄 Configurable: Extensive options for customizing the test environment
• 📚 Well Documented: Full API documentation and examples

🚀 Getting Started

Prerequisites

• Rust
• Solana CLI (for building test programs)

🔧 Installation

Add hpsvm as a development dependency to your Solana program project:

cargo add --dev hpsvm

To read through live RPC state while keeping execution local, enable the fork feature:

cargo add --dev hpsvm --features fork

🤖 Quick Example

Here's a minimal example that demonstrates creating a test environment, airdropping SOL, and executing a transfer transaction:

use hpsvm::HPSVM;
use solana_address::Address;
use solana_keypair::Keypair;
use solana_message::Message;
use solana_signer::Signer;
use solana_system_interface::instruction::transfer;
use solana_transaction::Transaction;

// Create keypairs for testing
let from_keypair = Keypair::new();
let from = from_keypair.pubkey();
let to = Address::new_unique();

// Initialize the SVM with default configuration
let mut svm = HPSVM::new();

// Airdrop SOL to the sender account
svm.airdrop(&from, 10_000).unwrap();

// Create a transfer instruction
let instruction = transfer(&from, &to, 64);

// Build and sign the transaction
let tx = Transaction::new(
    &[&from_keypair],
    Message::new(&[instruction], Some(&from)),
    svm.latest_blockhash(),
);

// Execute the transaction
let tx_result = svm.send_transaction(tx).unwrap();

// Verify the results
let from_account = svm.get_account(&from).unwrap();
let to_account = svm.get_account(&to).unwrap();
assert_eq!(from_account.lamports, 4936);  // 10000 - 64 - fee
assert_eq!(to_account.lamports, 64);

📖 Usage

For more advanced usage, including custom configurations, program deployment, and complex transaction scenarios, see the full documentation.

Architecture Highlights

hpsvm keeps the HPSVM facade stable while exposing a few sharper seams for advanced test harnesses:

• transact computes an ExecutionOutcome without mutating the VM, and commit_transaction applies it explicitly when you want to persist the result.
• with_account_source lets the VM read missing accounts from an external source while keeping local writes in the in-memory overlay.
• block_env exposes the current blockhash and slot snapshot, and with_inspector installs lightweight top-level execution observers.

use hpsvm::HPSVM;
use solana_address::Address;
use solana_keypair::Keypair;
use solana_message::Message;
use solana_signer::Signer;
use solana_system_interface::instruction::transfer;
use solana_transaction::Transaction;

let mut svm = HPSVM::new();
let payer = Keypair::new();
let recipient = Address::new_unique();

svm.airdrop(&payer.pubkey(), 10_000).unwrap();

let tx = Transaction::new(
    &[&payer],
    Message::new(&[transfer(&payer.pubkey(), &recipient, 64)], Some(&payer.pubkey())),
    svm.latest_blockhash(),
);

let outcome = svm.transact(tx);
assert!(outcome.status().is_ok());
assert_eq!(svm.get_balance(&recipient), None);

let commit = svm.commit_transaction(outcome);
assert!(commit.is_ok());
assert_eq!(svm.get_balance(&recipient), Some(64));
assert_eq!(svm.block_env().latest_blockhash, svm.latest_blockhash());

Forking RPC State

hpsvm can read missing accounts through a configured account source. The fork feature provides an RPC-backed source with a bounded, TTL-aware local cache:

# #[cfg(feature = "fork")]
# fn main() {
use hpsvm::{HPSVM, fork::RpcForkSource};

let source = RpcForkSource::builder()
    .with_rpc_url("http://127.0.0.1:8899")
    .with_slot(1)
    .build();

let svm = HPSVM::builder().with_account_source(source).build().unwrap();
# }
# #[cfg(not(feature = "fork"))]
# fn main() {}

Top-Level Instruction Inspection

Use with_inspector when you need lightweight transaction observation without reaching into the lower-level invocation callback APIs:

use std::sync::{
    Arc,
    atomic::{AtomicUsize, Ordering},
};

use hpsvm::{HPSVM, Inspector};
use solana_address::Address;

#[derive(Default)]
struct CountingInspector {
    seen: Arc<AtomicUsize>,
}

impl Inspector for CountingInspector {
    fn on_instruction(&self, _svm: &HPSVM, _index: usize, _program_id: &Address) {
        self.seen.fetch_add(1, Ordering::SeqCst);
    }
}

let inspector = CountingInspector::default();
let observed = Arc::clone(&inspector.seen);
let _svm = HPSVM::new().with_inspector(inspector);

assert_eq!(observed.load(Ordering::SeqCst), 0);

🖥️ Command-line fixtures

The hpsvm-cli crate ships an hpsvm binary for recording, replaying, and A/B-comparing transaction fixtures. A fixture bundles a transaction, the accounts it needs, the programs it calls, and a recorded baseline snapshot, so a program's behaviour can be frozen and checked in CI.

cargo install hpsvm-cli

Record a fixture

fixture record executes a signed transaction against the pre-state you supply and writes a fixture containing the observed baseline:

hpsvm fixture record \
  --transaction tx.bin \
  --accounts accounts.json \
  --output fixtures/transfer-64.json \
  --name transfer-64 \
  --tag transfers

--transaction holds a wincode-serialized VersionedTransaction. Use --transaction-encoding base64 or --transaction-encoding hex when the bytes travel as text instead. --accounts is a JSON array of pre-execution accounts:

[
  {
    "address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
    "lamports": 10000,
    "owner": "11111111111111111111111111111111",
    "executable": false,
    "rent_epoch": 0,
    "data": []
  }
]

Each address accepts either a base58 string or a 32-byte array, and the shape matches input.pre_accounts inside an existing fixture — so pre-accounts can be copied straight out of one. Programs the transaction calls are bound with --program <program-id>=<path-to-elf>, which is repeatable. Further options include --loader, --slot, --sigverify, --log-bytes-limit, --compute-unit-limit, and --ignore-compute-units for fixtures that should tolerate compute-unit drift. A .json output path writes the JSON codec; a .bin path writes the binary codec.

Replay and compare

hpsvm fixture run fixtures/transfer-64.json
hpsvm fixture run fixtures/
hpsvm fixture inspect fixtures/transfer-64.json

run replays a fixture — or every fixture in a directory, in sorted order — and exits non-zero on the first failure. inspect prints the fixture as JSON.

compare replays the same fixture twice, once per program build, and diffs the two execution snapshots. This is the A/B check for a program rewrite — both mappings bind the fixture's program id, each to a different ELF:

hpsvm fixture compare fixtures/transfer-64.json \
  --baseline-program 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin=target/old.so \
  --candidate-program 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin=target/new.so

By default the comparison uses the checks stored in the fixture. Override them with --config, whose JSON body is a compares list:

{ "compares": ["Status", "Fee", "Accounts"] }

Pass --ignore-compute-units to drop the compute-unit check while keeping the rest.

Compute-unit reports

hpsvm cu report fixtures/transfer-64.json \
  --output-dir cu \
  --baseline-dir cu \
  --must-pass

This writes a Markdown summary (cu-report.md) and a JSON baseline sidecar (cu-report.baseline.json) into --output-dir. --baseline-dir is read-only: it supplies the previous sidecar to compute per-case compute-unit deltas against, so pointing it at the same directory makes the first run establish a baseline and later runs report drift:

| Name       | Compute Units | Delta        | Pass |
| transfer-64 |          150 | +0 (+0.00%) | PASS |

Add --must-pass to fail the command as soon as a case's recorded expectations no longer hold.

🛠️ Developing hpsvm

Building Test Programs

The test suite uses Solana programs that need to be built first:

cd crates/hpsvm/test_programs
cargo build-sbf

Running Tests

The test suite loads four SBF programs from crates/hpsvm/test_programs/target/deploy/. They are gitignored build artifacts, so build them once after checkout (CI does this automatically):

cd crates/hpsvm/test_programs && cargo build-sbf

just test-all checks for them first and reports exactly which artifact is missing. If cargo build-sbf itself fails on macOS, see the note at the end of this section.

Run the full test suite:

cargo test

Running Benchmarks

cargo bench

Build the benchmark helper program and profile the public HPSVM surface:

HPSVM_HOTPATH=1 cargo bench -p hpsvm --features hotpath --bench core_interfaces

Profile the steady-state transaction execution hot path:

HPSVM_HOTPATH=1 cargo bench -p hpsvm --features hotpath --bench max_perf

Export a deeper trace summary for the steady-state SBF execution path:

just bench-hotpath-trace

core_interfaces covers the main public APIs: new, set_account, get_account, expire_blockhash, add_program, add_program_from_file, airdrop, send_transaction, simulate_transaction, transact + commit_transaction, plan_transaction_batch, and send_transaction_batch.

When HPSVM_HOTPATH=1 is set, hotpath reports are written to target/hotpath/*.json. Use HPSVM_HOTPATH_LIMIT to cap the number of reported functions, or HOTPATH_OUTPUT_PATH to override the default report path.

When HPSVM_TRACE_METRICS=1 is combined with the register-tracing feature, just bench-hotpath-trace also writes target/hotpath/max_perf.trace.json and target/hotpath/simple_bench.trace.json. These summaries report per-program invocation counts, CPI depth, register-frame counts, and instruction-account counts so you can tell whether the execute_instruction hotspot is dominated by nested CPIs or a single SBF program body in both the steady-state loop and the repeated transaction-loop benchmark.

To compare default runtime benchmarks without hotpath overhead:

just bench-runtime
just bench-runtime-baseline-compare

This writes compact Criterion reports to target/runtime-benchmarks/*.json and a markdown summary to target/runtime-benchmarks/summary.md. Use this runtime baseline before treating a hotpath-only delta as a real VM slowdown.

To refresh the committed default runtime baselines:

just bench-runtime-baseline-refresh

To refresh the committed hotpath baselines:

just bench-baseline-refresh

To compare a fresh benchmark run with the committed baselines:

just bench-hotpath
just bench-baseline-compare

Code Quality

Format code:

cargo fmt

Lint code:

cargo clippy

Troubleshooting cargo build-sbf

On macOS the anza platform-tools rustc can emit proc-macro dylibs that dyld rejects with mis-aligned LINKEDIT string pool, which cargo then reports as can't find crate for borsh_derive or can't find crate for bytemuck_derive. This is a toolchain bug and reproduces in a two-crate scratch project, so it is not caused by this repository. Build the test programs on another host and copy crates/hpsvm/test_programs/target/deploy back.

🙏 Acknowledgments

• Initially forked from litesvm
• Built for the Solana ecosystem
• Inspired by the need for faster, more ergonomic testing tools
• Thanks to the Solana community for their contributions and feedback