A client-side playground for the Bitcoin Transaction Schema Language (BTSL) — a declarative validation schema for PSBT workflows.
Parse BTSL schemas, bind parameters against live on-chain data, generate JavaScript code, and export unsigned PSBTs ready for signing.
All operations run entirely in your browser. No private keys are ever involved.
If you use a multi-folder layout (e.g. btsl/), btsl-packages may sit next to this project as another local directory — not something this repo installs from npm or git by default. That folder is where an eventual split into publishable libraries (planned under the @btsl/* npm scope) is described; see ../btsl-packages/ARCHITECTURE.md when present. This repository is self-contained: the playground and the reference engine ship in lib/btsl/ here.
BTSL is a declarative language that specifies what a valid Bitcoin transaction should look like before anyone signs it. It separates construction logic from validation logic, enabling independent verification of transaction invariants (fees, change, output structure) by any signer or auditor.
BTSL does not modify the PSBT format or introduce new consensus rules. It operates above BIP174/BIP370 as a pure validation layer.
Local spec copy: docs/spec/ mirrors the current markdown from the btsl-standard repo (btsl-spec-v1.0.md, btsl-implementation-guide-v1.0.md, btsl-checker-predicates-v1.0.md) for offline reading and diffing against this codebase. It is not consumed by the app build; refresh it when the upstream spec changes.
The Validator tab runs runCheckerPipeline (lib/btsl/checker-pipeline.ts) against the BTSL v1.0.0 spec §9.3.1 checker predicates: S-1/S-2 (ERR_13), I-1…I-4, I-3 (ERR_11), O-1/O-2, A-1…A-5 (algebraic phase), with error codes aligned to §5.3. Field-level helpers live in lib/btsl/checker-predicates.ts.
The playground implements Maker (construction) and Validator (Checker, §9.3.1) from the spec:
Schema Input → Parameter Binding → Code Generation → PSBT Output
└→ Validator tab: paste PSBT, replay calc, field-level + algebraic checks
- Schema Input — Paste or select a BTSL schema from the built-in catalog.
- Parameter Binding — Fill
@PARAMvalues (UTXOs, addresses, fee rate). UTXOs are fetched live from Blockstream API, fee rates from Mempool.space. - Code Generation — Generates standalone JavaScript that constructs the PSBT via
bitcoinjs-lib, runscalc, evaluatesASSERT, and performs the zero-trust audit (balance check, dust check, weight check). - PSBT Output — Export the unsigned PSBT as Base64 or Hex. Import into Sparrow, Coldcard, bitcoin-cli, or any BIP174-compatible signer.
- Validator — Same bindings (and optional
.paramsmerge) plus a PSBT: independent chain fetch for inputs, O-1/O-2, ASSERT replay, balance and dust checks per §9.3.1.
| Example | Pattern | Spec Section |
|---|---|---|
| Simple Payment | From(@PUBKEY) + CHANGE |
§6.5 |
| TRI-COUNT | Multi-input shared settlement | §6.1 |
| Multisig 1-of-2 / 2-of-2 | P2WSH SCRIPT_DEFS + witness_data | §6.2 |
| OP_RETURN Deploy | OP_RETURN + CHANGE | §6.3 |
| Taproot Vault | P2TR + DEPENDS_ON workflow | §6.4 |
pnpm install
pnpm devOpen http://localhost:3000.
pnpm testParser corpus tests validate all built-in examples and error cases against deterministic snapshots.
The playground tracks BTSL v1.0: Maker (PSBT construction, calc, generated audit helpers) and Checker / Validator (runCheckerPipeline, §9.3.1 — shape, field-level I-/O- predicates, chain-certified inputs, algebraic replay, ASSERT). Behavior is intended to match the normative spec; report gaps against docs/spec/ or the upstream btsl-standard repo.