b-open-io/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.ts with @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 support
• references/scrypt-guide.md — sCrypt installation, decorators, testing, deployment, advanced patterns
• references/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