VM Tooling & Test Harness

Source: crates/vm-tooling, crates/vm-test-harness

Overview

Ashen ships two developer utilities for contract work:

• vm-tooling: CLI for validation, disassembly, tracing, gas profiling, and tier predecode.
• vm-test-harness: in-memory host for running Zig/Rust contracts without a full node.

vm-tooling CLI

Binary: vm-tooling (crate: crates/vm-tooling).

Common Commands

Deploy manifest

vm-tooling deploy-manifest --out deploy.json

ELF validation

vm-tooling elf-validate --elf contract.elf --manifest deploy.json

Disassembly

vm-tooling disasm --file contract.elf --start 0x0 --len 256

Trace execution

vm-tooling trace --file contract.elf --entry 0x0 --gas 1000000 --calldata-hex 0x...

Gas schedule dump

vm-tooling gas --json

Code cache stats

vm-tooling cache-stats --max-entries 1024 --max-bytes 268435456

Predecode to tier

vm-tooling predecode --elf contract.elf --tier jit --out contract.jit
vm-tooling predecode --elf contract.elf --tier aot --out contract.aot

Gas profiling

vm-tooling gas-profile --file contract.elf --gas 1000000 --trace-out gas.json

Gas budgets

vm-tooling gas-budget-check --config .gas-budgets.toml --contracts-dir contracts/

Conformance corpus

vm-tooling corpus-freeze --out corpus/ --cases 1000
vm-tooling corpus-run --dir corpus/ --tier interpreter

vm-test-harness

Crate: crates/vm-test-harness.

It provides a lightweight host for executing contracts with deterministic storage, events, and result parsing.

Example

use vm_test_harness::{ContractHarness, TestHost, TestAccounts};
use vm_test_harness::{assert_call_ok, build_calldata};

let accounts = TestAccounts::default();
let mut host = TestHost::new();
host.seed_default_balances(&accounts);

let harness = ContractHarness::from_zig_artifact(
    "contracts/my_token/zig-out/bin/my_token",
)
.expect("artifact exists")
.expect("load contract");

let calldata = build_calldata(*b"MINT", &accounts.alice);
let result = harness.call(&mut host, &accounts.alice, b"my_token", &calldata, 1_000_000);
assert_call_ok(&result, "mint should succeed");

Assertions and Fixtures

The harness includes helpers for:

• Event emission checks
• Storage assertions
• Host state fixtures
• ABI-compatible calldata builders

Related Docs

• docs/design/gas-profiler-flame-graphs.md
• docs/design/simulation-mode.md
• docs/design/cross-contract-call-tracing.md