Starstream

Starstream is a language that uses coroutines as its core primitive that is optimised to run in a zkVM (such as Nightstream). The end goal is a language and VM that can be used across any blockchain that chooses to include it.

Unique features of Starstream:

• Native folding scheme support for both on variable updates & function application (only VM that provides both)
• UTXO-based (only zkVM-optimized language development with this property)
• Coroutines as its core primitive (only blockchain VM that does this)

Learn more:

• Basic overview: video and slides.
• Technical overview: video and slides.

Starstream working group on Discord: https://discord.gg/9eZaheySZE.

References

• Language spec
• Design document - Background and motivation
• Implementation plan - Todo list and completed/finished feature info

Getting started

Read more about how to use Starstream on the documentation website: https://lfdt-nightstream.github.io/Starstream/#getting-started

To begin working on Starstream from this repository:

• Use ./starstream to build and run the command-line interface and show its help message with more information.
• Use cargo test to run the tests.
• See website/ for how to build it and its organization.
• See vscode-starstream/ for build instructions. Use VSCode's "Launch extension" mode to debug.
• Use Zed to build and install zed-starstream/ as a development extension.

Compile a file

./starstream wasm -c $your_source.star -o $your_module.wasm
# Can view disassembly using:
wasm-dis $your_module.wasm  # from binaryen/emscripten
wasm2wat $your_module.wasm  # from wabt

For multi-contract projects, use ./starstream build instead — see the CLI docs for the full command set (check, docs, build, lsp).

Codebase structure

The Starstream DSL implementation and documentation website live in this repository.

Starstream is being built bit-by-bit, starting with full tooling for a simple language and adding each feature across the whole stack.

Concerns are separated into several crates. The 'compiler' turns source code into a validated AST, which is then interpreted directly or compiled further to a target such as WebAssembly.

Compiler:

• starstream-types/ - Common AST types.
  • Used as the interface between parsing and code generation.
• starstream-compiler/ - Starstream language implementation.
  • parser/ - Parser from Starstream source code to AST.
  • formatter.rs - Opinionated auto-formatter.
  • TODO: type checker.
• starstream-interpreter/ - AST-walking reference interpreter.
  • Implements the language spec in an easy-to-audit way.
  • Not optimized, but used as a comparison point for other targets.
• starstream-to-wasm/ - Compiler from Starstream source to WebAssembly modules.

Tooling:

• tree-sitter-starstream/ - Tree-sitter definitions including grammar for syntax highlighting and analysis.
• starstream-language-server/ - LSP server implementation.
• starstream-language-server-web/ - Compiles the language server to WebAssembly (Web Worker only, uses wasm-bindgen).
• starstream-sandbox-web/ - Compiles starstream-to-wasm/ to Wasm for use in the web sandbox (freestanding).

Executor and VM:

The guest execution is based on wasmtime, and the proving side is implemented in Nightstream under the neo-wasm crate, alongside the underlying folding/IVC scheme. This includes both core wasm instrumentation/tracing generation and the CCS/relation that gets folded.

The host/embedder side of the WASM execution is split between

• starstream-runtime/ - Component ABI bindings, contract linking, and UTXO instance management
• starstream-ledger/ - Ledger-backed execution: resolves transaction inputs, loads UTXO state, runs coordination scripts, and collects transaction outputs.

With the Starstream specific proving side in:

• starstream-interleaving-prover/ - Defines the circuit/relation that constrains all the Starstream host interactions the guest can/must do. The folding scheme and related apis are in Nightstream.
• starstream-proving-runtime/ - Defines host event (starstream effects) bindings for wasm proofs, which encode which functions and which arguments have to be included in the transcript of host call operations, computed out of custom tags and the component ABI convention.
• starstream-interleaving-spec/ - Has a Quint model of the semantics of the interleaving circuit.

Interfaces:

• website/ - Documentation website and web sandbox.
• starstream-cli/ - Unified Starstream compiler and tooling CLI.
  • Frontend to Wasm compiler, formatter, language server, and so on.
  • Run ./starstream --help for usage instructions, or see the CLI docs for the full command reference.
• vscode-starstream/ - Extension for Visual Studio Code.
  • TODO: Publish to marketplace & OpenVSIX.
• zed-starstream/ - Extension for Zed.
  • TODO: Publish.

Tests

# Run all tests
cargo test

Snapshot tests

We co-locate snapshot tests with the parsers they exercise. Each module (expression, statement, program, …) exposes a tiny helper macro that:

• takes an indoc! snippet for readability,
• parses it with the module’s own parser() function, and
• records the full Debug output of the AST using insta::assert_debug_snapshot!.

Snapshots live under starstream-compiler/src/parser/**/snapshots/ right next to the code. The snapshot headers include the literal source (via the Insta description field), so reviews don’t need to cross-reference input files.

# run unit + snapshot tests
cargo test

# (optional) focused snapshot cycle
cargo insta test
cargo insta review
cargo insta accept

# clean up renamed/removed snapshots in one go
cargo insta test --unreferenced delete --accept

Because the helpers sit in the modules themselves, adding a new grammar rule is as simple as writing another #[test] in that module and feeding the helper macro a snippet.

Formalities

• Code of Conduct
• Contributing guidelines
• Security policy
• Maintainers list
• License: Apache-2.0 or MIT at your option