Static types that map 1:1 to Clarity
int, uint, bool, string, principal, buffer, Optional, Response, List, Map, tuples. Every type has a direct Clarity equivalent — no runtime surprises.
v0.3.0 · 146 passing tests · MIT
A transpiler for StxScript to Clarity, making Stacks smart contract development easy.
Write contracts with TypeScript-flavored syntax — types, generics, decorators, match expressions. Compile to valid, auditable Clarity that runs on the Stacks blockchain.
stxscript build mint.stx mint.clar
Source on the left. Clarity on the right.
A minted-token contract in StxScript, and the actual Clarity the transpiler emits — taken verbatim from the project README.
mint.stx — StxScript input
const TOKEN_NAME: string = "MyToken";
const MAX_SUPPLY: uint = 1000000u;
let total_supply: uint = 0u;
map balances<principal, uint>;
@public
function mint(amount: uint): Response<bool, uint> {
if (total_supply + amount > MAX_SUPPLY) {
return err(1u);
}
total_supply = total_supply + amount;
return ok(true);
}
@readonly
function get_balance(account: principal): uint {
match balances.get(account) {
some(balance) => balance,
none => 0u
}
} mint.clar — Clarity output deployable
(define-constant TOKEN_NAME u"MyToken")
(define-constant MAX_SUPPLY u1000000)
(define-data-var total_supply uint u0)
(define-map balances principal uint)
(define-public (mint (amount uint))
(if (> (+ (var-get total_supply) amount) MAX_SUPPLY)
(err u1)
(begin
(var-set total_supply (+ (var-get total_supply) amount))
(ok true))))
(define-read-only (get-balance (account principal))
(default-to u0 (map-get? balances account)))The transpile pipeline runs in four stages: parse → AST → semantic analysis → codegen. Every StxScript construct has a documented Clarity mapping — auditors can read both files side by side.
The gap
Clarity is a great target. It is a tough source.
Clarity is intentionally restrictive: no recursion, decidable semantics, no surprising runtime. Those properties make it a good smart contract language. They do not make it a fun day-to-day editing experience. StxScript closes that gap without giving up any of Clarity’s guarantees.
Read like TypeScript
Function signatures, generics, decorators
Public/read-only become @public/@readonly. Generics like function identity<T>(x: T): T compile away.
The mental model is "TypeScript without anything Clarity cannot do."
Audit like Clarity
Output is plain, indented Clarity
The codegen pass emits the Clarity an experienced developer would write by hand. You ship both files — auditors trace line-for-line between source and target.
Catch errors early
Static analysis before testnet
The semantic analyzer enforces types, scopes, and trait compliance at compile time. stxscript check and
stxscript lint surface mistakes before you spend a Stacks block on them.
Language features
Every feature has a Clarity counterpart.
StxScript exposes exactly the surface area that Clarity supports — no leaky abstractions, no “runtime polyfills.” If you can write it in StxScript, you can read the resulting Clarity and predict what it does.
Familiar function syntax with decorators
Use @public, @readonly to mark visibility. Lambda expressions like (x: uint) => x * 2u become real Clarity expressions, not closures-over-anything.
Type aliases and generics
Write type Amount = uint; and function identity<T>(x: T): T. Generics resolve at compile time to monomorphic Clarity — the runtime sees plain types.
if/else, match, for, while
Match expressions destructure Optional and Response. Loops are bounded and lower to fold/map under the hood, staying within Clarity’s guarantees.
Response, unwrap (!), default (??), try!
Sugared error handling that desugars to the Clarity primitives you would write by hand — but without the brace-counting.
Interfaces with @implements
Define traits, declare @implements(Token), and let the semantic analyzer verify the contract conforms before you ever deploy.
First-class maps
Declare map balances<principal, uint>; and use balances.get(addr) / balances.set(addr, v). Generates define-map and map-get?/map-set/map-delete.
Imports and cross-contract calls
A module system so you can split contracts across files without fighting Clarity’s flat-file model.
Full bitwise operator set
&, |, ^, ~, <<, >>. The kind of detail Clarity supports but no language sugar previously exposed cleanly.
Install
Three commands to your first contract.
step 01
Install
StxScript ships as a Python 3.10+ package. pip gets you the CLI, formatter, linter, and language server.
$ pip install stxscript step 02
Scaffold
Pick a template: basic, token, nft, or defi. The scaffold lays out source, tests, and project files.
$ stxscript new my-token \
--template token step 03
Build
Transpile a single file to Clarity, or run stxscript watch for auto-rebuild while you iterate.
$ stxscript build \
contract.stx contract.clar The full CLI surface
Reproduced verbatim from the README’s CLI table.
| Command | What it does |
|---|---|
| stxscript build <input> [output] | Transpile StxScript to Clarity |
| stxscript fmt <files> | Format code |
| stxscript lint <files> | Static analysis |
| stxscript check <files> | Syntax validation |
| stxscript new <name> | Create new project (basic/token/nft/defi templates) |
| stxscript watch <path> | Watch mode with auto-rebuild |
| stxscript doc <input> | Generate documentation |
| stxscript test [path] | Run contract tests |
| stxscript pkg <command> | Package management (init/add/remove/install/list) |
Honest comparisons
Where StxScript fits in the Stacks toolchain.
Two comparisons we can ground fairly. If you want a different breakdown, file an issue and we will add one.
StxScript vs writing Clarity directly
→Clarity by hand is the baseline. StxScript adds syntax sugar, a type system, and tooling — at the cost of a build step. Pick StxScript when the developer experience savings outweigh the extra layer.
StxScript alongside Clarinet
→Clarinet is the canonical Stacks dev environment. It is not a competitor — it is complementary. Use StxScript as your source language, drop the generated Clarity into a Clarinet project.
Editor support
LSP-first, editor-agnostic.
VS Code extension
Syntax highlighting, snippets, integrated LSP. Drop the extension in and you get diagnostics, autocomplete, hover info, and go-to-definition out of the box.
stxscript-lsp
A standalone language server. Run it directly and point any LSP-aware editor at it — diagnostics, autocomplete, hover info, go-to-definition.
Vim, Sublime, Emacs
LSP client configuration is documented in the project. Bring your own editor — the language server does the heavy lifting.
FAQ
Questions developers ask first.
+ What exactly does StxScript compile to?
Valid Clarity source code. You can read it, audit it, and deploy it with the standard Stacks tooling. The transpiler is a four-stage pipeline: Lark-based LALR parsing, typed AST generation, semantic analysis (type checking, scope, trait compliance), and Clarity code generation.
+ Do I have to learn anything new?
If you know TypeScript, Rust, or any modern typed language, the surface syntax will feel familiar. The interesting work is learning what subset of those features maps cleanly to Clarity — and StxScript only exposes the parts that do.
+ Is the output Clarity readable?
Yes, that is a deliberate design goal. The transpiler emits indented, documented Clarity that an auditor can read alongside the StxScript source. You ship both.
+ How do I install it?
pip install stxscript. StxScript itself is written in Python (3.10+), so a single pip install gets you the build CLI, the formatter, the linter, the language server, and the project scaffolder.
+ What templates are available?
stxscript new <name> --template <kind> currently ships basic, token, nft, and defi templates. They are starter projects, not frameworks.
+ Is there an IDE story?
There is a VS Code extension with syntax highlighting, snippets, and integrated LSP, plus an LSP server (stxscript-lsp) that any LSP client can connect to. Vim/Neovim, Sublime, and Emacs are documented.
+ Is StxScript trying to replace Clarinet?
No. Clarinet is a test and dev environment for Clarity contracts. StxScript is a source language that produces Clarity. They sit at different layers — and StxScript ships its own stxscript test command for contract tests, so the two are complementary.
+ What is the current status?
Version 0.3.0 with 146 passing tests as reported in the README. CLI commands cover build, fmt, lint, check, new, watch, doc, test, and pkg.
Write your first contract this afternoon.
Install with pip, scaffold a token project, and ship a working Clarity contract before the next block.