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.

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.2"

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 optional HTTP server is not compiled for normal library users. Enable it only when you need the API server:

svmscope = { version = "0.2", features = ["server"] }

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.

Build and send the transaction inside the Rust test

You no longer need to run the TypeScript tests, copy a signature, and then start svmscope. The Rust test can build the Anchor instruction from the program IDL, sign it, send it to solana-test-validator, wait for it to land, and immediately receive a replay of the exact pre-transaction state.

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 = { path = "../svmscope" }
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.

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>

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

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.

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 app

The web UI is a visual layer over this same library — paste a signature, click through the CPI tree, edit named account fields, run suites, freeze fixtures. The server feature (off by default — library consumers never compile axum) builds the HTTP API: cargo run --bin server --features server → http://127.0.0.1:3000, GET /api lists the surface. A typed TypeScript client lives in sdk/.

Deploy your own

The server reads HOST, PORT, and SVMSCOPE_RPC_URL from the environment:

docker build -t svmscope . && docker run -p 3000:3000 -e SVMSCOPE_RPC_URL=https://your-rpc svmscope

Or on render.com: New → Blueprint → connect the repo (reads render.yaml) → deploy. The public mainnet RPC is heavily rate-limited; use your own endpoint for anything hosted.

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