https://github.com/tangle-network/microvm-blueprint
Infrastructure-layer microVM lifecycle blueprint for Tangle
https://github.com/tangle-network/microvm-blueprint
Last synced: 3 months ago
JSON representation
Infrastructure-layer microVM lifecycle blueprint for Tangle
- Host: GitHub
- URL: https://github.com/tangle-network/microvm-blueprint
- Owner: tangle-network
- Created: 2026-03-02T23:41:43.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-03T21:31:31.000Z (4 months ago)
- Last Synced: 2026-03-11T09:10:26.645Z (3 months ago)
- Language: Rust
- Size: 91.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# microvm-blueprint
[](https://discord.gg/cv8EfJu3Tn)
[](https://twitter.com/tangle_network)
Infrastructure-layer blueprint for microVM lifecycle orchestration on Tangle, built with [blueprint-sdk](https://github.com/tangle-network/blueprint).
## Workspace
- `microvm-runtime`: infrastructure runtime contracts and provider adapters (`VmProvider`/`VmQuery`), including in-memory and Firecracker adapter surfaces.
- `microvm-blueprint-lib`: reusable blueprint job/query wiring that consumes `microvm-runtime` contracts.
- `microvm-blueprint-bin`: runnable binary wiring the `BlueprintRunner` with Tangle producer/consumer and a read-only query background service.
## Lifecycle jobs (state-changing only)
On-chain job functions dispatched through blueprint-sdk's `Router` with `TangleLayer`:
| Job ID | Function | Description |
|--------|----------|-------------|
| 0 | `create_vm` | Provision a new microVM |
| 1 | `start_vm` | Start a stopped/created microVM |
| 2 | `stop_vm` | Stop a running microVM |
| 3 | `snapshot_vm` | Capture microVM state |
| 4 | `destroy_vm` | Tear down a microVM |
Job arguments are ABI-decoded from Tangle calldata via `TangleArg`; results are ABI-encoded back via `TangleResult`.
## Query surfaces (read-only only)
Read-only HTTP endpoints run as a `BackgroundService` alongside the `BlueprintRunner`:
- `GET /health`
- `GET /vms`
- `GET /vms/{vm_id}`
- `GET /vms/{vm_id}/snapshots`
No state-changing operations are exposed as HTTP endpoints.
## Run
```bash
cargo run -p microvm-blueprint-bin
```
The binary requires a Tangle environment configuration (see `BlueprintEnvironment::load()`).
Provider selection is controlled by `MICROVM_PROVIDER`:
- `in-memory` (default)
- `firecracker` (requires `--features firecracker`)
Firecracker provider expects host paths (override via env as needed):
- `MICROVM_FIRECRACKER_BIN`
- `MICROVM_FIRECRACKER_KERNEL`
- `MICROVM_FIRECRACKER_ROOTFS`
## Validate
```bash
cargo check
cargo test --all
```
## Incremental engineering workflow
- Main branch remains stable; all feature work lands via short-lived branches.
- Keep job/query boundaries strict: state changes in jobs, reads via query surfaces.
- Every change should include tests or explicit rationale when tests are not yet applicable.
- Prefer small, reviewable PRs with one architectural concern each.
See [CONTRIBUTING.md](CONTRIBUTING.md) for branch, commit, and PR conventions.
## References
This blueprint's structure and wiring patterns were derived from:
| Source | What was referenced |
|--------|---------------------|
| [`blueprint`](https://github.com/tangle-network/blueprint) SDK `examples/incredible-squaring/` | Crate layout (`-lib`/`-bin`), `Router` + `TangleLayer` wiring, `#[debug_job]` macro, `TangleArg`/`TangleResult` extractors, `BackgroundService` trait, `BlueprintRunner::builder()` pattern |
| [`ai-agent-sandbox-blueprint`](https://github.com/user/ai-agent-sandbox-blueprint) | Job ID constants as `u8`, `router()` export pattern, background HTTP API alongside runner, `BlueprintEnvironment::load()` / `TangleProducer` / `TangleConsumer` wiring |
| [`ai-trading-blueprints`](https://github.com/user/ai-trading-blueprints) | Multi-crate workspace conventions, job function signatures with `Result, String>` error pattern, provider trait separation |
Canonical file paths inspected:
- `/home/drew/code/blueprint/examples/incredible-squaring/incredible-squaring-lib/src/lib.rs`
- `/home/drew/code/blueprint/examples/incredible-squaring/incredible-squaring-bin/src/main.rs`
- `/home/drew/code/ai-agent-sandbox-blueprint/ai-agent-sandbox-blueprint-lib/src/lib.rs`
- `/home/drew/code/ai-agent-sandbox-blueprint/ai-agent-sandbox-blueprint-bin/src/main.rs`
- `/home/drew/code/ai-trading-blueprints/trading-blueprint-lib/src/lib.rs`
- `/home/drew/code/ai-trading-blueprints/trading-blueprint-bin/src/main.rs`