Skip to content
stxscript. GitHub

About

A better front-end for a language we already trust.

StxScript started from a simple observation. Clarity is a thoughtful, deliberately constrained language — its decidability, lack of recursion, and post-conditions are features, not bugs. But its surface syntax dates from the Lisp tradition, and most developers walking onto Stacks today come from TypeScript, Rust, or Swift. The gap between the two is friction, not flaw.

Why a transpiler instead of a new VM

The temptation when you find a language hard to read is to build a new one. We resisted. Building a new VM means reinventing security properties Clarity already proves: decidable execution, no reentrancy by construction, predictable gas. Clarity earned those properties through years of careful design and adversarial review. Starting over throws that work away.

A transpiler keeps the runtime exactly where it is. The Stacks blockchain executes Clarity bytecode — and only Clarity bytecode. StxScript runs zero code at execution time. It is a build-time tool that produces the Clarity you would have written by hand, with the same security envelope, deployed through the same tooling.

The cost of that decision: every feature in StxScript must have a Clarity counterpart. We do not invent control flow Clarity cannot express. We do not add closures-over-anything, untyped generics, or runtime polymorphism. Anything in StxScript that looks like a TypeScript convenience either compiles away (generics, type aliases) or maps to a Clarity primitive (decorators to define-public/define-read-only, match expressions to nested if and Optional unwraps).

The four-stage pipeline

The README is precise about the transpiler architecture, and it is worth repeating here because the pipeline is the project:

  1. Parsing — a Lark-based LALR grammar. The grammar lives in working_grammar.lark and is the single source of truth for what StxScript accepts.
  2. AST generation — a typed abstract syntax tree. Every node knows what it is and what types its children have to be.
  3. Semantic analysis — type checking, scope validation, trait compliance. This is where StxScript catches the things Clarity would only complain about at deploy time.
  4. Code generation — optimized Clarity output. Indented, idiomatic, auditable.

The fact that the pipeline is four stages, not one, is what makes the project tractable. Each stage has a small, well-defined contract with the next. You can read the AST visitor without holding the grammar in your head; you can read the codegen without holding the analyzer in your head.

Design principles that fell out of the choice

1. The Clarity output is a deliverable, not an intermediate

Some transpilers emit minified, machine-friendly output that no human is supposed to read. StxScript is the opposite. The Clarity files stxscript build writes are committed alongside the source. Auditors read both. Reviewers can diff the Clarity between PRs without first running the transpiler.

2. The type system never lies

StxScript’s types are not annotations. They are checked, and they map directly to Clarity types — uint to uint, buffer<32> to (buff 32), Response<T, E> to (response T E). If the StxScript type checker accepts your program, the Clarity output will pass type-check too. There is no escape hatch that lets the source “forget” what the target requires.

3. Static analysis is the user’s friend

Clarity will refuse to deploy invalid contracts — that is the safety net. StxScript moves as many of those refusals earlier as it can. stxscript check catches syntax. stxscript lint catches common semantic mistakes. The LSP catches both in your editor. The deploy step should not be where you discover a typo.

4. Tooling is part of the language

The README lists nine CLI commands: build, fmt, lint, check, new, watch, doc, test, and pkg. That is a deliberate coverage decision. A language without formatting is a language with bikeshedding PRs. A language without a watch mode is a language whose users alt-tab to terminals every five seconds. A language without templates is a language whose first contract takes a week. StxScript ships the boring tools because the boring tools determine whether anyone keeps using the language past day three.

What this is and is not

StxScript is a source language for Clarity. It is not a framework, not a runtime, not a competing chain. There is no token, no protocol, no validator network. There is a pip package, a CLI, an LSP, and a VS Code extension. Everything else is documentation and tests.

That narrow scope is on purpose. The project either succeeds at being a better way to write Clarity, or it does not. There is no second business model to fall back on, and no roadmap of features that would dilute the focus.

Who is building it

StxScript is a cryptuon project, released under the MIT license. Source is on GitHub at github.com/cryptuon/stxscript. As of v0.3.0 the test suite has 146 passing tests and the language covers the features listed on the home page. The path forward is more language coverage, more idioms in the codegen, and longer fuzz runs against the semantic analyzer.

How to engage

If you write Clarity today and want a more comfortable source language: pip install stxscript, run stxscript new my-token --template token, and try the resulting contract. If you find a case where the Clarity output is wrong, surprising, or ugly: open an issue with the StxScript source and the Clarity output side by side. That is the highest-signal feedback the project can receive.