svmscope

Start from a real transaction. Decode it, replay it locally in an embedded SVM, mutate state and time-travel, freeze it into a fixture, and assert on it forever.

📦 Full working example: github.com/alizeeshan1234/svmscope_example — an Anchor program plus a Rust project that consumes the published crate end-to-end.

The Solana testing stack has unit testing (LiteSVM), instruction testing (Mollusk), and integration testing from current mainnet state (Surfpool). svmscope covers the fourth quadrant: post-mortem and regression testing from a historical transaction — a real signature already encodes its entire world (accounts, programs, state), so one signature replaces a hundred lines of test setup.

Add it to a Rust project

svmscope is a testing tool, so add it as a dev-dependency:

cargo add --dev svmscope

[dev-dependencies]
svmscope = "0.4"

Then point it at a real transaction and replay it locally — no validator, no setup:

use svmscope::{Check, Mutation, Scope};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let scope = Scope::new("https://api.mainnet-beta.solana.com");

// Reconstruct the transaction's world once — every account, every program ELF.
let mut replay = scope.replay("<signature>")?;
assert!(replay.run()?.result.success);

// Then ask "what if?" — a reverting replay is data, not an error.
let out = replay.verify(
    "draining the vault makes the claim revert",
    &[Mutation::lamports("<vault-address>", 0)],
    &[Check::revert_contains("InsufficientFunds")],
)?;
assert!(out.pass);
# Ok(())
# }

That's the whole loop: reconstruct once, replay and mutate forever. The rest of this README goes deeper — building and submitting transactions, freezing offline fixtures, and the full assertion DSL.

The library has no features to configure — the HTTP API server lives in its own workspace crate (server/), so library consumers never compile axum/tokio.

Library quickstart

use svmscope::{Check, Cmp, Mutation, Scope};

let scope = Scope::new("https://api.mainnet-beta.solana.com");
let signature = "a mainnet transaction signature";
let (vault, user) = ("the vault's address", "the user's address");

// Decode: the full CPI tree, every instruction named from its on-chain IDL.
let analysis = scope.analyze(signature)?;

// Reconstruct the transaction's world once — every account, every program ELF.
// All RPC happens here; every run below is local, instant, and free.
let mut replay = scope.replay(signature)?;
assert!(replay.run()?.result.success);

// What-if, with declarative checks (a reverting replay is data, not an Err):
let outcome = replay.verify(
    "draining the vault makes the claim revert",
    &[Mutation::lamports(vault, 0)],
    &[
        Check::revert_contains("InsufficientFunds"),
        Check::account(user).token_delta(Cmp::eq(0)).build(),
    ],
)?;
assert!(outcome.pass);

// Time is just the Clock sysvar — warp it. A vesting claim that reverts
// today succeeds at +30 days.
replay.advance_seconds(30 * 86_400);
let future = replay.run()?;

// Freeze the whole world into one JSON file: accounts, ELFs, IDLs, and the
// recorded on-chain outcome. It replays identically forever, offline.
std::fs::write("fixtures/claim.json", scope.capture(signature)?.to_json()?)?;
# Ok::<(), Box<dyn std::error::Error>>(())

The main API is available directly from the crate root. Import Scope, Replay, Mutation, Check, Cmp, Scenario, Fixture, and result types as svmscope::Type; implementation modules are intentionally private. The idl, report, and spec modules are public for IDL inspection, HTML reports, and the JSON scenario format respectively.

Four ways to mutate state

A what-if is one or more Mutations applied before the replay. Named-field mutations are the headline — flip an oracle price, a token balance, a vesting cliff by name, with no byte offsets, resolved through the same SPL-layout/IDL decoding the assertion DSL uses:

use svmscope::{Mutation, Scope};
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let scope = Scope::new("https://api.mainnet-beta.solana.com");
# let mut replay = scope.replay("<signature>")?;
# let (pool, vault, oracle, config) = ("<pool>", "<vault>", "<oracle>", "<config>");
let out = replay.simulate(&[
    // 1. Set a NAMED field — the mutation-side twin of
    //    Check::account(pool).field("reserve_a", …). A typo'd name errors
    //    listing the real fields; an out-of-range value is a hard error.
    Mutation::field(pool, "reserve_a", 1_000_000),

    // 2. Set an account's SOL balance.
    Mutation::lamports(vault, 0),

    // 3. Patch a slice at a raw byte offset (when no layout is known).
    Mutation::patch(oracle, 8, 1_000_000_u64.to_le_bytes().to_vec()),

    // 4. Replace an account's data wholesale.
    Mutation::data(config, vec![0u8; 128]),
])?;
assert!(out.result.success || out.result.error.is_some());
# Ok(())
# }

The JSON scenario suites below express the same mutations declaratively: {"kind":"field","field":"reserve_a","value":…}, {"kind":"lamports",…}, and {"kind":"data","offset":…,"bytes_hex":…}.

Build and send the transaction inside the Rust test

You can also start from scratch instead of an existing signature. A Rust test can build an Anchor instruction from the program IDL, sign it, send it to a local solana-test-validator, wait for it to land, and immediately receive a replay of the exact pre-transaction state — no copying signatures out of a separate test suite.

1. Build and deploy the Anchor program

Terminal 1 (leave it running):

solana-test-validator --reset

Terminal 2:

anchor build
anchor deploy --provider.cluster localnet
mkdir -p tests/fixtures
solana-keygen new --no-bip39-passphrase -o tests/fixtures/payer.json
solana airdrop 10 "$(solana address -k tests/fixtures/payer.json)" --url localhost
anchor keys list

Keep the generated target/idl/<program>.json. The local validator must already have the program deployed before svmscope constructs the replay because the replay captures the deployed ELF and all input accounts. Put the address printed by anchor keys list in YOUR_PROGRAM_ID. If the instruction updates state, initialize that state/PDA first and put its address in YOUR_EXISTING_STATE_ACCOUNT.

2. Add the test dependencies

[dev-dependencies]
svmscope = "0.4"
serde_json = "1"
solana-address = "2.6"
solana-keypair = "3.1"
solana-signer = "3.0"

3. Construct, submit, capture, mutate, and time-travel

use std::str::FromStr;

use serde_json::json;
use solana_address::Address;
use solana_keypair::read_keypair_file;
use solana_signer::Signer;
use svmscope::{Mutation, Scope};

fn invokes_program_and_replays_it() -> Result<(), Box<dyn std::error::Error>> {
    let scope = Scope::new("http://127.0.0.1:8899");
    let program_id = Address::from_str("YOUR_PROGRAM_ID")?;
    let state = Address::from_str("YOUR_EXISTING_STATE_ACCOUNT")?;
    let payer = read_keypair_file("tests/fixtures/payer.json")?;
    let idl = serde_json::from_str(&std::fs::read_to_string(
        "target/idl/your_program.json",
    )?)?;

    let mut captured = scope
        .program_with_idl(program_id, idl)
        .method("setValue")?
        .payer(&payer)
        // Names must match the IDL. Nested accounts may use "group.account".
        .account("authority", payer.pubkey())
        .account("state", state)
        .args(json!({ "value": 42 }))?
        .send_and_capture()?;

    // This signature was created here; nothing is copied from a TS test.
    println!("landed transaction: {}", captured.signature);
    assert!(captured.replay.recorded().is_some());

    // Re-execute locally from the state captured immediately before submission.
    let baseline = captured.replay.run()?;
    assert!(baseline.result.success);

    // Mutations and time travel now reuse that in-memory replay with no RPC.
    let changed = captured
        .replay
        .simulate(&[Mutation::lamports(state.to_string(), 0)])?;
    println!("after mutation: {:?}", changed.result.error);

    captured.replay.advance_seconds(30 * 86_400);
    let future = captured.replay.run()?;
    println!("after 30 days: {}", future.result.success);

    // Optional: freeze this newly created transaction for offline CI.
    let fixture = captured.replay.to_fixture()?;
    std::fs::write("fixtures/set_value.json", fixture.to_json()?)?;

    Ok(())
}

Use .account_signer("accountName", &keypair) when an IDL account must sign, or .signer(&keypair) when its address was supplied separately. Fixed-address accounts in modern Anchor IDLs, such as the System Program, are filled automatically. PDAs are addresses, not signers: derive them in the test and pass the result with .account(...).

Argument values are JSON and are Borsh-encoded in IDL order. Supported values include booleans; signed and unsigned integers through 128 bits; floats; strings; public keys; bytes; vectors; options; fixed arrays; and IDL-defined structs and enums. Pass integers larger than JSON's exact numeric range as decimal strings, and bytes either as [0, 1, 255] or a "0x..." string.

send_and_capture waits up to 20 seconds. A program revert is still a landed transaction and returns Ok(CapturedTransaction) with captured.replay.recorded().unwrap().success == false. Err is reserved for an RPC failure, timeout, malformed IDL/accounts/arguments, or transaction-building failure.

If you already construct a VersionedTransaction yourself, use the lower-level path directly:

let captured = scope.send_and_capture(signed_versioned_transaction)?;

Offline fixture use

Capture a transaction once while connected to RPC, then load it without any network access in tests or CI:

use svmscope::{Check, Fixture, Replay, Scenario};

let fixture = Fixture::from_json(&std::fs::read_to_string("fixtures/claim.json")?)?;
let replay = Replay::from_fixture(&fixture)?;
let outcomes = replay.run_suite(&[
    Scenario::new("matches mainnet").check(Check::matches_onchain()),
    Scenario::new("still succeeds").check(Check::success()),
])?;

assert!(outcomes.iter().all(|outcome| outcome.pass));
# Ok::<(), Box<dyn std::error::Error>>(())

The three things it does

1. Post-mortem a transaction. Paste a failed mainnet signature: the CPI tree arrives with instructions, arguments, and accounts named (resolved from the on-chain Anchor IDL or known native layouts), balance and token diffs, per-program compute units, and — on replay — the failure explained in plain language ("SlippageToleranceExceeded", not Custom(6001)). Then change one thing and run it again.

2. Test against reality. scope.replay(sig) rebuilds the transaction's world inside LiteSVM — no validator, no ports, no devnet dance. Mutate lamports or bytes, flip runtime feature gates, warp the clock by slots/epochs/seconds or to an absolute point, and assert on outcomes and resulting state with a mollusk-style Check DSL, including named fields: Check::account(pool).field("reserve_a", Cmp::gt(0)).

3. Regression-test it in CI, offline. scope.capture(sig) freezes everything — transaction, accounts, program binaries, IDLs, and the actual on-chain outcome — into one portable JSON fixture. Replay::from_fixture rebuilds the world with zero RPC: deterministic suites in CI with no key, no drift, no flakes, and Check::matches_onchain() as the "does it still behave like mainnet" primitive.

4. Profile the compute. replay.profile(&[]) traces every BPF instruction the transaction executes — every program frame, every CPI — and attributes them to functions, syscalls and call stacks: a flamegraph of where the compute units went. Nothing else on Solana shows this. Mainnet programs are stripped, so their functions read as function_<pc> with exact boundaries and shape; pass the .debug file cargo build-sbf --debug writes next to your own .so and every function gets its Rust name.

Errors are typed and self-explanatory: a typo'd mutation address is a hard Error::MutationTargetMissing, never a fake "revert" your test happily accepts; an unknown field name errors listing the available fields.

Run the examples against any transaction:

cargo run --example post_mortem -- <signature>
cargo run --example what_if    -- <signature> <account>
cargo run --example fixture_ci -- <signature>

For a full real-world consumer — an Anchor program (counter + SOL vesting) plus a standalone Rust project that depends on the published crate and drives the entire build → submit → capture → replay → mutate → time-travel → freeze workflow, with a 129-test offline suite and validator-gated online tests — see the svmscope_example repo.

The CLI

The same engine, on the command line:

cargo run -- <SIGNATURE>                          # decode + replay
cargo run -- <SIGNATURE> --mutate <ADDR>:<LAMPORTS>  # + a what-if
cargo run -- freeze <SIGNATURE> -o fixture.json   # capture a fixture
cargo run -- test suite.json                      # run a scenario suite (CI-ready)
cargo run -- report suite.json -o report.html     # shareable HTML report
cargo run -- upgrade fixture.json                 # re-capture an old fixture as v2
cargo run -- debug <SIGNATURE>                    # step debugger: every instruction and CPI, state diffs, failing step
cargo run -- profile <SIGNATURE>                  # compute profiler: instructions per function, per frame, per syscall
cargo run -- profile <SIGNATURE> --symbols <PROGRAM>=target/deploy/my_program.debug   # …with Rust function names

Every command takes --cluster <mainnet|devnet|testnet|localnet> or --rpc <url>.

$ cargo run -- <SIGNATURE>

#0  Route V2  (JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4)
    └─ [2] Swap  (BiSoNHVpsVZW2F7rx2eQ59yQwKxzU5NvBcmKshCSUypi)
        └─ [3] Transfer  (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA)

-- compute units per program --
JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4  178113 CU

-- replay --
REPLAY: failed ❌  error: InstructionError(4, Custom(6024))

That's the real Jupiter program executing locally. Swaps often fail on replay with a slippage error — not a bug, but the honest consequence of state drift: replays run against current reconstructed state, and pool prices have moved since the original slot. That's exactly why fixtures exist: freeze once, and the replay is pinned forever.

Profile the compute

Every Solana developer has stared at consumed 187,342 of 200,000 compute units with no idea which function ate it. The profiler answers that for any transaction, mainnet or local:

$ cargo run -- profile <SIGNATURE>

replay: ok ✅ · 58,501 CU charged · 34,556 BPF instructions across 9 program frames

-- compute per program --
     37487  pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA
     12968  ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL
      5660  pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ
       ...

== frame 9 · pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA · 22051 instructions · 37487 CU · 15436 CU beyond instructions ==
        self     total  calls      ~CU  function
        4492      5525      1     7636  function_105164
        2612      2612      2     4440  function_7339
        1319      1319     60     2242  function_93342
   syscalls:
          86  sol_memcmp_
          75  sol_memcpy_

Hosted: svmscope.vercel.app has a Profile tab — paste a signature and the flamegraph is the first thing on screen; /flame/<signature> is a shareable link to one.

How it works: LiteSVM records every BPF instruction each program frame executes; the profiler folds that trace into call stacks (function boundaries come from the program's own call graph, so they are exact), counts syscalls by name, and attaches the runtime's measured compute per frame — exclusive of the CPIs it made — from the consumed log lines. The folded stacks are flamegraph input; the hosted debugger draws them.

Names: every mainnet program is stripped, so its functions have no symbol names — but the trace says what each one did, and the profiler labels them from that evidence: Buy handler, instruction dispatch, CPI → Token Program: Transfer, PDA derivation, emits event, hashing, error: SlippageExceeded. Functions that only compute stay fn@<pc>. For your own program, build with cargo build-sbf --debug, deploy that .so, keep the .debug beside it, and pass --symbols <program>=<path>.debug (or upload it in the debugger UI): every function gets its Rust name. If the build you have is not the one on chain (a plain release deploy, symbols from a --debug build), pass both files — --symbols <program>=<path>.debug,<path>.so — and functions are matched by code shape instead of address; the same-build case still maps by address and refuses a mismatched entrypoint.

Library: let (result, mut profile) = replay.profile(&[])?; profile.symbolize(program, &std::fs::read("my.debug")?)?; — Profile is frames: Vec<FrameProfile> with functions, syscalls, stacks (folded, a;b;c → count) and compute_units per frame. The profiler feature is on by default; default-features = false drops it.

Scenario suites (JSON)

Suites also exist as a JSON format — the same one the web UI exports and svmscope test runs. Reference a fixture for the deterministic, offline path:

{
  "fixture": "fixture.json",
  "scenarios": [
    { "name": "baseline replays faithfully", "expect": "success" },
    {
      "name": "draining the pool reverts",
      "expect": "revert",
      "mutations": [{ "kind": "data", "address": "<POOL>", "offset": 64, "bytes_hex": "0000000000000000" }],
      "asserts": [{ "address": "<POOL>", "kind": "field", "field": "amount", "op": "==", "value": 0 }]
    }
  ]
}

$ cargo run -- test suite.json
svmscope test — fixture 4RHX…oJWt (16 accounts, 5 programs) [deterministic, offline]
  PASS  baseline replays faithfully  (expect: succeeds; got: succeeded)
  PASS  draining the pool reverts  (expect: reverts; got: reverted (Custom(6004)))
2/2 passed

Assert kinds: lamports, u64 (at an offset), token_amount, lamports_delta, token_delta, and named fields — "field": "pool.reserveA" resolved through SPL layouts or the program's IDL (field_delta for changes). v2 fixtures carry their IDLs, so named-field asserts work fully offline.

How it works

Decode — walks getTransaction: the CPI tree from innerInstructions + stackHeight, diffs from pre/postBalances, compute from the logs, Address Lookup Table resolution, instruction/account/field naming from on-chain IDLs (Anchor and the Program Metadata program) or built-in native layouts.
Reconstruct — getMultipleAccounts for every touched account; programs resolve through the upgradeable loader's programdata pointer to the raw ELF; closed accounts (drained fee payers, closed token accounts) are rebuilt from the transaction's own metadata; pre-transaction SPL balances are rewound so swaps replay faithfully.
Replay — everything loads into a pristine LiteSVM per run (sigverify/blockhash checks off — the original blockhash can't be valid in a fresh SVM), the clock anchored to the transaction's real slot and block time. There is no validator to wait for, so runs are microseconds and trivially parallel.
Time travel — programs read time from the Clock sysvar; we own it. Warps move slot, epoch, and timestamp coherently (432k slots/epoch, ~400ms/slot), so a program checking all three sees a consistent world.

Live demo

A hosted web UI over this same library — paste a signature, click through the CPI tree, edit named account fields, run suites, freeze fixtures — is at svmscope.vercel.app.

Optional HTTP server

A small HTTP API over the engine lives in the server/ workspace crate (svmscope-server — deployment infrastructure, not published to crates.io). It reads HOST, PORT, and SVMSCOPE_RPC_URL from the environment:

cargo run -p svmscope-server   # → http://127.0.0.1:3000, GET /api lists the surface

A typed TypeScript client lives in sdk/. Point it at your own RPC endpoint — the public mainnet RPC is heavily rate-limited.

Roadmap

Decode, reconstruct, replay, mutate, time-travel, feature gates
Hermetic fixtures (v2: IDLs + recorded outcome captured — offline named-field asserts and matches_onchain)
Typed errors; mutations validated up front (no silently-passing revert tests)
Scope/Replay library API — fetch once, replay forever
Mollusk-style Check DSL with named-field assertions
Codama/Shank IDL support (named fields for native & Pinocchio programs)
Named-field mutations — Mutation::field(addr, "count", 99)
Async/trait RPC abstraction
Anchor event decoding; archival state at the exact slot; cross-account invariants

See VISION.md for the full architecture.

Built with

Rust · litesvm · solana-client · thiserror · serde_json

License

MIT — see LICENSE.

svmscope 0.5.1