magicsvm 0.2.0

A fast and lightweight Solana + MagicBlock VM simulator for testing solana programs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

<div align="center">
    <img src="https://raw.githubusercontent.com/magicblock-labs/magicsvm/master/magicsvm-logo.png" width="50%" height="50%">
</div>

# MagicSVM

MagicSVM is a fork of [LiteSVM](https://github.com/LiteSVM/litesvm) adapted for
[MagicBlock](https://www.magicblock.xyz/) [Ephemeral Rollups](https://docs.magicblock.gg/).
It keeps LiteSVM's fast, in-process Solana VM for testing programs and adds the
pieces needed to test programs that delegate accounts to, execute inside, and
commit state back from an Ephemeral Rollup without spinning up a validator or an
ER node.

## 📦 Installation

```toml
[dependencies]
magicsvm = { git = "https://github.com/magicblock-labs/magicsvm" }
```

## 🪄 Native Delegation

Use `MagicSVM` when a test needs to interact with both the base-layer and an ephemeral
rollup. `MagicSVM` loads all the necessary program so you can start testing right away.

```rust,ignore
use magicsvm::{MagicSVM, TransactionTarget};

let mut svm = MagicSVM::new();

// Normal Solana transactions and delegation-program instructions run on base.
svm.send_transaction_to(TransactionTarget::Base, base_tx).unwrap();

// Get the account from the base layer
svm.get_account_for(my_account, TransactionTarget::Base).unwrap();

// Rollup-local transactions run on the ephemeral ledger.
svm.send_transaction_to(TransactionTarget::Ephemeral, ephemeral_tx)
    .unwrap()

// Get the account from the rollup
svm.get_account_for(my_account, TransactionTarget::Ephemeral).unwrap();
```

## 📚 Docs

See the [tutorial](https://magicblock-labs.github.io/magicsvm/) for more info, including [a list of features](https://magicblock-labs.github.io/magicsvm/about.html#why-use-magicsvm).

Some other useful resources:

- [MagicSVM on Github](https://github.com/magicblock-labs/magicsvm)
- [MagicBlock docs](https://docs.magicblock.gg/) — Ephemeral Rollups concepts
- [MagicSVM API reference](https://docs.rs/magicsvm/latest/magicsvm/)
- [Upstream LiteSVM API reference](https://docs.rs/litesvm/latest/litesvm/)

## ⚡ Why use MagicSVM?

While many Solana developers use `solana-program-test` or `solana-test-validator` for testing, these solutions can be slow, cumbersome and difficult to use. `solana-program-test` runs a "banking stage" simulation that is overkill for most cases, while `solana-test-validator` runs a full local validator complete with networking, consensus, RPC, etc.

MagicSVM inherits LiteSVM's approach: it provides a lightweight wrapper around the Solana `SVM` (Solana Virtual Machine) that lets you send transactions and query state without the overhead of a full validator.

This makes testing dramatically faster: benchmarks show LiteSVM can be **10x or more faster** than `solana-program-test` and `solana-test-validator`.

It also makes for a much nicer developer experience. You get simple APIs for modifying account state, time travel, copying accounts from a live network and more.

On top of that, MagicSVM is geared toward [Ephemeral Rollups](https://docs.magicblock.gg/): it lets you exercise the delegation flow your programs rely on when running on MagicBlock, so you can test that logic in-process alongside the rest of your program.

See the [tutorial](https://magicblock-labs.github.io/magicsvm/) for more info.

## 🪲 Bugs and feature requests

Please open an issue if you find a bug or have a feature request.

## 📜 License

MagicSVM is licensed under the Apache 2.0 license.

## 🙏 Credits

MagicSVM is a fork of [LiteSVM](https://github.com/LiteSVM/litesvm) by [Kevin Heavey](https://github.com/kevinheavey) and contributors. LiteSVM draws heavily on [solana-program-test](https://crates.io/crates/solana-program-test) and is also inspired by [bankrun](https://github.com/kevinheavey/solana-bankrun), [Anchor Bankrun](https://github.com/kevinheavey/anchor-bankrun) and the work of [Joey Meere](https://github.com/joeymeere). Huge thanks to all of the upstream authors.