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

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:

• interleaving/
• mock-ledger/
• TODO: IVC/
• TODO: MCC/
• TODO: lookups/

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.
• 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