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
Write Bitcoin-secured smart contracts in TypeScript syntax.
StxScript is a TypeScript-inspired transpiler for Clarity, the smart contract language of Stacks — the Bitcoin layer where every transaction settles on Bitcoin. Write contracts with familiar types, generics, decorators, and match expressions; compile to valid, audit-ready Clarity. An ergonomic, typed on-ramp to Bitcoin DeFi for the developers who already speak TypeScript.
stxscript build mint.stx mint.clar
Source on the left. Clarity on the right.
A minted-token contract in StxScript, and the actual Bitcoin-settled Clarity the transpiler emits — taken verbatim from the project README. You write the left column; auditors and the Stacks node read the right.
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
Bitcoin's most defensive contract language, minus the learning curve.
Clarity is intentionally restrictive: no recursion, decidable semantics, no surprising runtime. Those properties are exactly what you want when a contract settles on Bitcoin — but Clarity's Lisp surface is unfamiliar to the millions of engineers who write TypeScript every day. As Bitcoin DeFi and Bitcoin-secured L2s grow, that gap is the bottleneck. StxScript closes it: TypeScript ergonomics on the way in, plain Clarity on the way out, 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.” That discipline matters when the target settles on Bitcoin: if you can write it in StxScript, you can read the resulting Clarity and predict exactly what it does on chain.
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.
Explore
Go deeper.
Language features →
Types, decorators, generics, traits, match, errors, maps, bitwise — each with the Clarity it emits.
How it works →
The four-stage transpiler pipeline and the deterministic StxScript-to-Clarity mapping.
Language reference →
Construct-by-construct: every declaration, type, and operator and its Clarity output.
Quickstart →
Install, scaffold, write, build, and deploy your first Clarity contract in five steps.
CLI reference →
build, fmt, lint, check, new, watch, doc, test, pkg — the whole command surface.
Use cases →
TypeScript teams, token & NFT contracts, typed-Clarity adoption, editor-driven dev.
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 Bitcoin/Stacks toolchain.
Two comparisons we can ground fairly — including the honest one against writing raw Clarity. 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.
More answers on the full FAQ page.
Ship to Bitcoin-secured Stacks this afternoon.
Install with pip, scaffold a token project, and transpile a working Clarity contract — settled on Bitcoin — before the next block.