impl-plan.md

Implementation plan

• See Starstream language specification for details on the language currently implemented.
• See Codebase structure for details on the components in this repository.

TODOs

Components:

• define grammar
• strip down parser and ast - @rvcas
• revamp snapshot test organization - @rvcas
• ditch op codes and make a tree-walking interpreter (ast nodes) - @SpaceManiac
• compile stripped down lang to wasm - @SpaceManiac
• single-binary CLI - @SpaceManiac
• formatter, including snapshot tests, included in CLI - @rvcas
• tree sitter grammar - @SpaceManiac
• type system setup
  • basics specs - @SpaceManiac
  • return lsp diagnostics to be displayed in editor - @rvcas
  • Algorithm W and typed AST - @rvcas
• LSP server, included in CLI - @rvcas
• vscode extension (incl. highlighting and LSP launcher) - @SpaceManiac dogfooding
  • run LSP with cargo run
  • compile & use wasm LSP
• web sandbox - @SpaceManiac
  • basic editor
  • highlighting and LSP via VSC web ext
  • compile to Wasm and show disassembly
  • when language has some form of print(), run reference interpreter
  • when Wasm ABI is known enough, run Wasm module
• zed extension - @rvcas dogfooding

Language features:

• else if
• functions
• function call expressions
• if expressions
• block expressions
• make let const and add let mut
• type annotations on let bindings
• coordination script exports
• mock ledger
  • sandbox shows current "input" ledger state (starts empty)
  • sandbox allows calling coordination scripts with arguments, can pass existing UTXOs as input (JS console?)
  • sandbox shows "output" ledger state after running, with "save" button that copies it to the "input"
• base-level ABI stuff
  • underlying callable ABI
• abi elements
  • plain methods
  • errors
    • throw(?) expr
    • fail the transaction
  • events
    • declarations
    • emit expr
    • displayed as part of run output in sandbox and elsewhere
  • effects
    • declarations
    • raise expr
    • try/with blocks
• runtime expr for system imports
• UTXO elements
  • storage blocks to declare UTXO state (Wasm globals)
  • basic main fns
  • private method fns
  • public method pub fns ?
  • abi impl blocks
  • coroutine support (yield/resume)
• UTXO handles
  • generic Utxo handle
  • utxo UtxoName handle types
  • abi AbiName handle types
  • table-driven provable downcasting
• tokens stuff
• standard integer primitive types
  • bool
  • (i|u)(8|16|32|64)
  • char (is it u32 or Field<21>?)
  • f32 and f64 (determinism/proving trouble)
  • literals infer their type from context
• variable privacy
  • disclose builtin
  • check that if conditions are disclosed
  • check that variables across yield points are disclosed
• typedefs
  • basic type A = B;
  • export pub type A = B; to WIT
• linear/affine typing
• struct types
  • remember structural typing (see spec)
  • tuples
  • wasm codegen support as WIT records
• enum (tagged union) types
  • wasm codegen support as WIT variants
  • builtin Option<T>, Result<T, E> (WIT support)
• patterns and pattern matching
  • exhaustive patterns in arguments?
  • support literals in pattern
  • patterns in let LHS (structs make sense, enums not so much)
  • exhaustiveness checking for match
  • improve diagnostics for pattern/type mismatches
  • flag inconsistent match arm return values (fallthrough semantics)
• heap types
  • maybe defer until components support GC?
  • string and string literals (WIT support)
  • builtin container List<T> (WIT support)
• extra WIT functionality
  • owned and borrowed resource handles
  • flags types
  • declare intent to export a particular WIT world, compiler errors if it's not satisfied
• imports
  • import hardcoded WIT declarations for runtime functions
  • import externals from arbitrary .wit files
    • how to advertise the need for these to be fulfilled by a runtime extension?
    • by path
    • by WIT package expression, follows standard(?) search path
  • embed library code from component .wasm
  • import utxo, tokens, and script fns from other Starstream contracts
  • embed library fns from other .star files
• fields and foreign field arithmetic (important for interop)
  • maybe Field<N> or Int<N>, UInt<N>
  • how to implement?

Research:

• try out Verus as a way to verify the reference interpreter
• specify (roughly) the Wasm ABI that the compiler must target (maybe use WIT?)
  • this is what lookups takes as input.
  • Wasm + the rough shape of external calls
    • how resource types (utxos, tokens) are named
    • how freestanding functions are named
• library/module/interop stuff
  • import ./another_file.star
  • import ./external_module.wasm (wasm target only?)
  • JavaScript bindings (WIT?) so dApps can call into Starstream contracts compiled to Wasm
• debugger
• proving and ZK
  • memory consistency checks (or how to handle memory)
  • lookups