KaspaScript is a Rust compiler workspace for deterministic Kaspa contract artifacts. It exists to make covenant-era contract construction inspectable: source becomes typed IR, IR becomes target-gated txscript bytes, and every protocol-sensitive claim is pinned to a source. Kernel packages now also emit a capability profile for wallets, SDKs, indexers, and agents.
The project is built for reviewers, tooling, and coding agents that need stable compiler surfaces: golden artifacts, explicit target gates, bytecode verification, and no hidden transaction behavior.
Current status:
- Verified compiler and golden test suite for the V1 txscript subset.
- First Kaspa programmability kernel crate and v0 package command.
- Toccata upgrade prep is tracked, but mainnet activation remains unclaimed.
Read the status roadmap: docs/PROJECT_STATUS.md.
Kernel package schema:
docs/KERNEL_PACKAGE_SCHEMA.md.
Project site: https://gryszzz.github.io/Kaspa-Script/.
┌───────────┐ ┌────────┐ ┌────────┐ ┌─────┐
│ Source.ks │ -> │ Lexer │ -> │ Parser │ -> │ AST │
└───────────┘ └────────┘ └────────┘ └─────┘
│
v
┌──────────┐ ┌────────────────┐ ┌───────────┐
│ Artifact │ <- │ Kaspa txscript │ <- │ Typed IR │
└──────────┘ │ backend/gates │ └───────────┘
└────────────────┘ ^
^ │
│ ┌──────────────┐
└──────────── │ Semantics │
└──────────────┘
┌────────────────────────────────────────────────────────┐
│ Programmability Kernel │
│ contract blueprints, capability profile, wallet │
│ previews, indexer schema, source evidence, Toccata fee │
│ policy, readiness reports │
└────────────────────────────────────────────────────────┘
Optimization passes are planned; today the compiler favors verifiable lowering
and deterministic emission over speculative transformation.
| Stage | Role |
|---|---|
| Lexer | Position-tagged token stream with line, column, and byte spans. |
| Parser | Contract AST for params, spend paths, calls, arrays, fields, and expressions. |
| Semantic Analysis | Collects type, scope, finality, builtin, and target-safety errors. |
| Typed IR | Opcode-agnostic instruction layer for contract verification and backend selection. |
| Backend Gates | Emits only source-grounded txscript for verified-tn12; gates preview surfaces. |
| Artifact | Deterministic JSON containing bytecode, source hash, target, KIP requirements, and warnings. |
| Kernel | Packages Kaspa-native contract blueprints with capability profiles, wallet previews, covenant lineage schema, fee policy, and network readiness. |
contract Escrow {
params {
buyer: PublicKey,
seller: PublicKey,
arbiter: PublicKey,
timeout: BlockHeight,
finality_depth: 10,
}
spend release(sig_a: Signature, sig_b: Signature) {
require multisig(2, [buyer, seller, arbiter], [sig_a, sig_b]);
require output(0).value >= input(0).value;
}
spend refund(sig: Signature) {
require sig.verify(buyer);
require block.height >= timeout;
require output(0).script == buyer;
}
}
Artifact metadata:
{
"backend": "kaspa-txscript",
"target": "verified-tn12",
"compiler_version": "0.1.0",
"finality_depth": 10,
"kip_requirements": [10],
"warnings": []
}IR preview:
IR contracts: 1
contract Escrow
spend release: 10 instructions
spend refund: 9 instructions
Compile output:
$ kaspascript compile escrow.ks
escrow.artifact.jsonKaspaScript treats compilation as an auditable system boundary.
| Principle | Meaning |
|---|---|
| Deterministic artifacts | The same source must produce the same bytecode and source hash every time. |
| No hidden behavior | The compiler and SDK do not inject invisible fees, treasury outputs, or implicit spend paths. |
| Source-grounded protocol support | Backend opcodes and KIP claims must cite pinned Kaspa sources before they can be verified. |
| Upgrade-safe targets | verified-tn12, tn10-toccata, toccata-preview, and future-mainnet are separate target gates. |
| Verification first | Unsupported behavior fails before bytecode emission; preview behavior must warn explicitly. |
The compiler refuses to guess. Uncertain protocol support is a gate, not a branch.
| Area | Status |
|---|---|
| Lexer, parser, AST | Complete V1 front end with source positions. |
| Semantic analysis | Collects all errors instead of stopping at the first failure. |
| Typed IR | Opcode-agnostic lowering for verified V1 patterns. |
| Kaspa txscript backend | Emits deterministic bytes for source-grounded opcodes. |
| CLI | Target-aware compile, inspect, verify, Toccata status/fee commands, and kernel package/check/preview workflows. |
| Golden artifacts | JSON, hex, and ASM snapshots for every example contract. |
| Kernel package goldens | v0 .kernel.json snapshots for escrow and vault. |
| SDK preview model | Compile API plus finality-depth checks; not a real Kaspa transaction builder yet. |
| TN12 test harness | Feature-gated live RPC/wallet preflight with gated proof files. |
| Programmability kernel | kaspascript-kernel crate plus kaspascript kernel package <contract.ks> for bytecode, capability profiles, wallet previews, indexer schema, readiness levels, source snapshots, and fee estimates. |
| Surface | Evidence |
|---|---|
| Base txscript opcodes | Pinned rusty-kaspa txscript sources. |
| Canonical pushes | Pinned rusty-kaspa script builder behavior. |
| KIP-10 introspection | input / output value and script opcodes. |
| KIP-15 sequencing | Verified as a block-header commitment, not a script opcode. |
| Surface | Gate |
|---|---|
block.height template values |
Verified opcode, but transaction instantiation is still preview. |
| Covenant IDs | No pinned txscript opcode yet. |
| ZK verification | No pinned txscript verifier opcode yet. |
| Script-level sequencing access | KIP-15 is not script-visible in pinned sources. |
| Future mainnet target | Locked until mainnet sources are pinned. |
| Area | Direction |
|---|---|
| Optimization passes | Deterministic IR transforms after verification invariants are fixed. |
| Real transaction builder | Rusty Kaspa transaction construction and submission. |
| WASM SDK | Stable compiler bindings for TypeScript tooling. |
| Contract registry tooling | Artifact fingerprinting and bytecode inspection workflows. |
$ kaspascript --help
KaspaScript is a source-grounded Kaspa contract compiler and programmability kernel...$ kaspascript toccata status
upgrade: Toccata
rusty_kaspa_release: v2.0.0 (2026-06-05T12:09:13Z)
mainnet_activation: DAA 474165565 estimated 2026-06-30T16:15:00Z
kaspa_script_readiness: blocked-for-production-mainnet
guide: https://github.com/kaspanet/rusty-kaspa/blob/v2.0.0/docs/toccata-guide.md
fee_policy: 100 sompi * max(compute grams, 2 * transaction bytes)$ kaspascript toccata targets
target: verified-tn12
readiness: verified
network: tn12
use: deterministic txscript packages for the source-grounded V1 subset$ kaspascript compile escrow.ks --target verified-tn12
escrow.artifact.json$ kaspascript inspect escrow.ks
IR contracts: 1
contract Escrow
spend release: 10 instructions
spend refund: 9 instructions$ kaspascript kernel check escrow.ks --target verified-tn12 --compute-grams 1000 --tx-bytes 400
contract: Escrow
target: verified-tn12
readiness: verified
ready: true
minimum_standard_fee_sompi: 100000$ kaspascript kernel preview escrow.ks --target verified-tn12 --transition release
contract: Escrow
target: verified-tn12
transition: release
classification: CovenantStateTransition$ kaspascript kernel package escrow.ks --target verified-tn12 --compute-grams 1000 --tx-bytes 400
escrow.kernel.json$ kaspascript toccata fee --compute-grams 1000 --tx-bytes 400
policy: toccata-rpc-minimum-standard-fee
minimum_standard_fee_sompi: 100000
formula: max(compute_grams, tx_bytes * 2) * 100 sompiEvery report-style command also supports --json for agents and CI:
$ kaspascript doctor escrow.ks --target future-mainnet --jsonThe report payloads are versioned contracts. JSON Schemas live in
docs/schemas, and golden report snapshots live in
tests/golden/cli. Start with
docs/CLI_REPORT_SCHEMAS.md.
$ kaspascript verify escrow.artifact.json
backend: kaspa-txscript
target: verified-tn12
compiler: 0.1.0
bytecode_bytes: 75
finality_depth: Some(10)
kip_requirements: [10]| Pattern | Description | Target status |
|---|---|---|
| Escrow | 2-of-3 release path with timeout refund and output value checks. | Verified TN12 |
| Timelock | Signature spend gated by OP_CHECKLOCKTIMEVERIFY. |
Verified TN12 |
| Multisig | Static threshold signatures lowered to OP_CHECKMULTISIG. |
Verified TN12 |
| Atomic swap | Hash preimage-style claim path plus refund timeout. | Verified TN12 |
| Covenant vault | Finality-aware vault pattern using verified txscript constraints today; covenant lineage remains future-gated. | Partial / gated |
| DAGSafe channel | Hash-committed cooperative close, timeout refund, and mediated close using verified script primitives. | Verified TN12 |
| DAGSafeVault kernel blueprint | UTXO covenant state-machine package with wallet previews, indexer schema, TN10 readiness report, and mainnet activation guard. | Kernel / TN10-gated |
Examples live in tests/contracts; committed outputs live in tests/golden.
KaspaScript keeps bytecode generation measurable.
| Check | Coverage |
|---|---|
| Determinism | Escrow compiles 1000 times with identical bytecode and source hash. |
| Golden snapshots | Each example checks artifact JSON, expected hex, and expected ASM; escrow and vault also check v0 kernel package JSON. |
| Negative tests | Wrong signature type, invalid input index, bad finality depth, and unsupported covenant features fail. |
| Fuzz smoke | Random lexer/parser input must not panic. |
| Clippy | Workspace is clean under -D warnings. |
For the current Toccata/DAGKnight preparation notes, see
docs/KASPA_UPGRADE_PREP.md. That brief records
the latest upstream KIP and Rusty Kaspa checkpoints without unlocking
unsupported bytecode paths prematurely.
For the moving Rusty Kaspa architecture watch, see
docs/RUSTY_KASPA_UPSTREAM_WATCH.md.
For the new framework layer, see
docs/KASPA_PROGRAMMABILITY_KERNEL.md.
For the kernel package JSON shape, see
docs/KERNEL_PACKAGE_SCHEMA.md.
For the completion roadmap, see
docs/PROJECT_STATUS.md.
The crate compatibility spike is in
docs/TOCCATA_CRATE_COMPATIBILITY.md.
kaspascript/
├── compiler/
│ ├── lexer/ tokenization with line/column/byte spans
│ ├── parser/ AST construction and Pratt expressions
│ ├── semantic/ scope, type, builtin, and finality checks
│ ├── ir/ opcode-agnostic contract IR
│ ├── codegen/ target gates, txscript backend, artifacts
│ └── protocol/ target manifests and feature gates
├── kernel/ Kaspa-native app kernel: blueprints, wallet preview, indexer schema
├── sdk/ Rust compile API and preview transaction model
├── cli/ kaspascript command-line interface
├── tests/
│ ├── contracts/ verified example contracts
│ └── golden/ artifact JSON, hex, and ASM snapshots
├── docs/ source-grounded protocol audit
└── contracts/ future-gated design fixtures
$ cargo test --workspace
# unit, integration, fuzz-smoke, determinism, and golden tests
$ cargo clippy --workspace --all-targets -- -D warnings
# warning-clean workspace
$ cargo test --features tn12-integration -- --ignored
# live TN12 RPC/wallet preflight and gated proof files
$ cargo bench -p kaspascript-codegen --bench escrow
# escrow full-pipeline benchmarkSee docs/TESTNET.md for the exact TN12 setup, required environment
variables, and proof-file format.
Current benchmark target: full escrow compile pipeline under 1 ms on a typical developer machine.
KaspaScript does not claim live mainnet smart-contract support.
Verified protocol evidence currently covers base Kaspa txscript behavior and KIP-10 transaction introspection from pinned Kaspa sources. Covenant IDs, ZK verification opcodes, and script-visible sequencing remain gated until primary Kaspa sources define them.
Read the audit: docs/kaspa-source-audit.md.
Support Dev <3 : kaspa:qpv7fcvdlz6th4hqjtm9qkkms2dw0raem963x3hm8glu3kjgj7922vy69hv85