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:

Starstream-specific executor and VM work lives under interleaving/. The underlying folding/IVC scheme, CCS, memory, and VM trace building blocks are implemented in Nightstream and consumed here through pinned workspace dependencies such as neo-fold, neo-ccs, neo-memory, and neo-vm-trace.

• interleaving/starstream-interleaving-spec/ - Transaction and interleaving semantics, public instance types (tied to a demo ledger implementation), and witness types. Plus a Wasm spec for the requirements on the UTXO zkVM.
• interleaving/starstream-interleaving-proof/ - Starstream interleaving proof circuit (CCS) and Nightstream folding-session integration with MCC middleware for Twist and Shout (implemented in Nightstream).
• interleaving/starstream-component-runtime/ - Component execution runtime and transaction session wiring (witness generation for proving, currently only for the interleaving).
• interleaving/starstream-runtime/ - Minimal runtime for testing Wasm to interleaving proof semantics. Will be replaced completely by starstream-component-runtime eventually.

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