smart-contracts
BSV Smart Contracts
Write, compile, test, and deploy Bitcoin SV smart contracts using high-level languages that compile to Bitcoin Script.
When to Use
- Author smart contracts in TypeScript, Go, Rust, Python, Solidity, or Move
- Compile high-level code to Bitcoin Script
- Build stateful contracts (counters, auctions, tokens) using OP_PUSH_TX
- Create spending conditions (escrow, multisig, timelocks, covenants)
- Test contracts locally before deployment
- Deploy contracts to BSV mainnet
For raw @bsv/sdk ScriptTemplate work (BitCom protocol templates like AIP, MAP, SIGMA), use the create-script-template skill instead. This skill is for contract logic — spending conditions, covenants, and stateful on-chain programs.
Framework Selection
Two frameworks compile high-level languages to Bitcoin Script:
| Runar | sCrypt | |
|---|---|---|
| Languages | TypeScript, Go, Rust, Python, Solidity, Move | TypeScript (eDSL) |
| Model | Multi-compiler with conformance suite | Single compiler |
| Stateful | StatefulSmartContract + OP_PUSH_TX |
SmartContract with @prop(true) |
| Testing | TestContract API with Script VM |
Built-in test framework |
| Deployment | runar-sdk providers + signers |
scrypt-ts deploy API |
| IDE | Full IDE support (valid TS/Go/Rust) | VS Code extension |
| Playground | https://runar.run | https://playground.scrypt.io |
| Install | pnpm add runar-lang runar-compiler runar-cli |
npx scrypt-cli project my-app |
| Builtins | 53+ functions (crypto, math, EC, post-quantum, BLAKE3) | Standard Bitcoin Script ops |
| Codegen | SDK wrappers in TS, Go, Rust, Python from one compile | N/A |
| Maturity | v0.3.0 (23 examples, 28 conformance tests) | Production |
| Source | https://github.com/icellan/runar | https://github.com/sCrypt-Inc/scrypt-ts |
Decision guide:
- Multiple language teams or cross-compiler verification needed → Runar
- Production deployment with mature tooling → sCrypt
- Post-quantum or advanced cryptographic primitives → Runar (has WOTS+, SLH-DSA, Schnorr ZKP examples)
- Quick prototyping with TypeScript only → either works
Contract Types
Stateless (Spending Conditions)
All properties are immutable. The contract is satisfied in a single transaction. Both frameworks compile P2PKH to the same Bitcoin Script: OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG.
Stateful (On-Chain State Machines)
Mutable properties persist across transactions via OP_PUSH_TX. Runar handles preimage verification automatically in StatefulSmartContract. sCrypt requires explicit buildStateOutput + hashOutputs verification in each public method.
In Runar, this.addOutput(satoshis, ...mutableFields) creates continuation outputs — pass only MUTABLE state values (readonly props are embedded in the script). Access this.txPreimage for BIP-143 preimage data (e.g., substr(this.txPreimage, 68n, 32n) for the outpoint txid). The compiler auto-adds _changePKH, _changeAmount, and txPreimage params to the ABI.
Key Syntax Differences
| Feature | Runar | sCrypt |
|---|---|---|
| Immutable prop | readonly keyword |
@prop() decorator |
| Mutable prop | No keyword | @prop(true) decorator |
| Public method | public keyword |
@method() decorator |
| Constructor super | super(prop1, prop2) |
super(...arguments) |
| Sig check | checkSig(sig, pk) |
this.checkSig(sig, pk) |
| State persistence | Automatic | Manual buildStateOutput |
| File extension | .runar.ts |
.ts |
See references/contract-patterns.md for complete side-by-side code examples of P2PKH, Escrow, Counter, Covenant, and more.
Common Patterns
| Pattern | Use Case | Stateful |
|---|---|---|
| P2PKH | Standard payments | No |
| Escrow | Multi-party authorization | No |
| Counter | On-chain state machine | Yes |
| Auction | Bidding with deadline | Yes |
| Covenant Vault | Spending constraints | No |
| Fungible Token | Split/merge token supply | Yes |
| NFT | Transfer/burn ownership | Yes |
| Oracle Price Feed | Rabin signature verification | No |
| Hash Time Lock | Atomic swaps | No |
| Multi-Sig (M-of-N) | Corporate treasury, shared custody | No |
| BLAKE3 Hash Lock | Modern hash verification | No |
| Post-Quantum Wallet | WOTS+, SLH-DSA signatures | No |
| TicTacToe | On-chain game logic | Yes |
See references/runar-guide.md and references/scrypt-guide.md for complete examples of each pattern.
Development Workflow
1. Write
Create a contract file:
- Runar:
MyContract.runar.ts(or.runar.go,.runar.rs,.runar.py) - sCrypt:
MyContract.tswith@method()decorators
2. Compile
# Runar
npx runar compile MyContract.runar.ts
# sCrypt
npx scrypt-cli compile
3. Test
// Runar — TestContract API with pre-generated test keys
import { TestContract, ALICE, BOB } from 'runar-testing';
// Addr type = 20-byte hex pubKeyHash, NOT Base58Check address
const contract = TestContract.fromSource(source, { pubKeyHash: ALICE.pubKeyHash });
// Test keys have: privKey, pubKey, pubKeyHash (hex), address (base58), wif, testSig
const result = contract.call('unlock', { sig: ALICE.testSig, pubKey: ALICE.pubKey });
expect(result.success).toBe(true);
// sCrypt — built-in testing
const instance = new P2PKH(pubKeyHash);
await instance.connect(getDefaultSigner());
const deployTx = await instance.deploy(1000);
const callTx = await instance.methods.unlock(sig, pubKey);
4. Deploy
// Runar — SDK deployment
import { Contract, WocProvider, LocalSigner } from 'runar-sdk';
const provider = new WocProvider('mainnet');
const signer = new LocalSigner(privateKey);
const contract = new Contract(artifact, provider, signer);
const deployTx = await contract.deploy([constructorArg], { satoshis: 1000 });
// sCrypt — deploy API
await instance.connect(new TestWallet(privateKey, provider));
const tx = await instance.deploy(satoshis);
Integration with @bsv/sdk
Both frameworks produce standard Bitcoin Script. The compiled output integrates with @bsv/sdk transaction building:
import { Transaction, P2PKH } from '@bsv/sdk';
// Use compiled contract script as locking script in any @bsv/sdk transaction
For raw script template authoring (BitCom protocols), see the create-script-template skill.
For script validation and opcode analysis, see the validate-bsv-script skill.
Additional Resources
Reference Files
For detailed framework-specific guides, consult:
references/runar-guide.md— Runar installation, language reference, compilation pipeline, all contract patterns, deployment SDK, multi-language supportreferences/scrypt-guide.md— sCrypt installation, decorators, testing, deployment, advanced patternsreferences/contract-patterns.md— Side-by-side implementations of common patterns in both frameworks
External Resources
- Runar Playground: https://runar.run
- Runar Source: https://github.com/icellan/runar
- Runar Docs: https://runar.build
- sCrypt Docs: https://docs.scrypt.io
- sCrypt Playground: https://playground.scrypt.io