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:

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

See references/contract-patterns.md for complete side-by-side code examples of P2PKH, Escrow, Counter, Covenant, and more.

Common Patterns

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