Home · How it works

Four stages from .stx to deployable Clarity.

StxScript runs entirely at build time. It never executes on-chain — the Stacks blockchain runs only the Clarity it emits, and every one of those transactions settles on Bitcoin. That keeps the security model unchanged: StxScript is a source language, not a new VM. The transpiler itself is a linear pipeline: parse, build a typed tree, check it, and generate Clarity.

transpile pipeline build time only

  contract.stx
       │
       ▼
  ┌───────────┐   ┌───────────┐   ┌──────────────────┐   ┌──────────────┐
  │  1. PARSE ├──▶│  2. AST   ├──▶│ 3. SEMANTIC CHECK├──▶│ 4. CODEGEN   │
  │ Lark LALR │   │  typed    │   │ types·scope·trait│   │ idiomatic    │
  └───────────┘   └───────────┘   └──────────────────┘   └──────┬───────┘
                                                                 │
                                                                 ▼
                                                          contract.clar
                                                    (deploy to Stacks unchanged)

stage 01

Parsing

Lark · LALR grammar

A Lark-based LALR grammar parses .stx source into a parse tree. The grammar file is the single source of truth for what StxScript accepts — if it does not parse, it is not StxScript.

stage 02

AST generation

Typed abstract syntax tree

The parse tree is lowered into a typed AST. Every node knows what it is and what types its children must be, which is what makes the next stage possible.

stage 03

Semantic analysis

Type check · scope · traits

Type checking, scope validation, and trait compliance run here. This is where StxScript catches mistakes that raw Clarity would only reject at deploy time — before you spend a block on them.

stage 04

Code generation

Idiomatic Clarity output

The checked AST is emitted as indented, idiomatic Clarity. The output is the deployable artifact: readable, auditable, and identical to what an experienced Clarity developer would write by hand.

What compiles to what

Codegen is deterministic. Each StxScript construct emits a known Clarity form — the reason the output is auditable.

StxScript	Clarity output
let / const with type	define-data-var / define-constant
@public function	define-public
@readonly function	define-read-only
plain function	define-private
map balances<principal, uint>;	define-map + map-get?/map-set/map-delete
match on Optional / Response	nested if + unwrap / default-to
value ?? fallback	default-to
try!(expr)	try!
@implements(Token)	impl-trait + trait conformance check
generic function<T>	monomorphized concrete functions

See the full construct-by-construct breakdown in the language reference, or jump straight to the quickstart.