🚀 Complete Bitcoin SV development framework with legally-recognizable DID:web + W3C VC-JWT toolkit, Legal Token Protocol (LTP), Global Digital Attestation Framework (GDAF), StatusList2021 revocation, and 16 flexible loading options. Standards-based crede
npm install @smartledger/bsv🚀 Complete Bitcoin SV Development Framework with W3C Verifiable Credentials, DID:web, Legal Compliance, and 16 Flexible Loading Options
The most comprehensive and flexible Bitcoin SV library available. NEW in v3.4.0: Legally-recognizable DID:web + VC-JWT toolkit with ES256/ES256K support, StatusList2021 revocation, and BSV anchoring. Choose from 16 different distribution methods: standalone modules, complete bundle, or mix-and-match approach.
``bashInstall SmartLedger BSV v3.4.0
npm install @smartledger/bsv@3.4.0
$3
javascript
const bsv = require('@smartledger/bsv')// Generate DID:web issuer keys
const keys = await bsv.DIDWeb.generateIssuerKeys({ alg: 'ES256' })
// Build DID documents (.well-known/did.json and jwks.json)
const docs = bsv.DIDWeb.buildDidWebDocuments({
domain: 'example.com',
p256: { jwk: keys.publicJwk, kid: keys.kid },
controllerName: 'Example Corp'
})
// Deploy docs.didDocument to https://example.com/.well-known/did.json
// Deploy docs.jwks to https://example.com/.well-known/jwks.json
// Issue a Verifiable Credential as JWT
const result = await bsv.VcJwt.issueVcJwt({
issuerDid: docs.did,
subjectId: 'did:example:alice',
types: ['VerifiableCredential', 'AgeCredential'],
credentialSubject: {
ageOver: 18,
country: 'US'
},
privateJwk: keys.privateJwk,
alg: 'ES256',
kid: keys.kid
})
console.log('VC-JWT:', result.jwt)
// Verify the credential
const verification = await bsv.VcJwt.verifyVcJwt(result.jwt, {
didResolver: async (did) => {
// In production, fetch https://example.com/.well-known/jwks.json
return { jwks: docs.jwks }
},
expectedIssuerDid: docs.did
})
console.log('Valid:', verification.valid)
// Anchor hash to BSV (no PII on-chain)
const hash = bsv.Anchor.sha256Hex(result.jwt)
const anchorPayload = bsv.Anchor.buildAnchorPayload({
kind: 'VC_ANCHOR_SHA256',
hash: hash,
issuerDid: docs.did
})
// Include anchorPayload.json in OP_RETURN
// Later: verify with bsv.Anchor.verifyAnchorHash(originalData, anchorHash)
// Create revocation list (100k credentials)
const statusList = await bsv.StatusList.createStatusList({
issuerDid: docs.did,
privateJwk: keys.privateJwk
})
// Revoke a credential
const updated = await bsv.StatusList.updateStatusList({
listVcJwt: statusList.listVcJwt,
index: 42,
status: 'revoked',
privateJwk: keys.privateJwk
})
// Check revocation status
const status = bsv.StatusList.getCredentialStatusEntry({
listVcJwt: updated.listVcJwt,
index: 42
})
console.log('Status:', status) // 'revoked'
`🎯 16 Loading Options - Choose Your Approach
$3
| Module | Size | Use Case | CDN |
|--------|------|----------|-----|
| bsv.min.js | 449KB | Core BSV + SmartContract | |
| bsv.bundle.js | 885KB | Everything in one file | unpkg.com/@smartledger/bsv@3.4.0/bsv.bundle.js |$3
| Module | Size | Use Case | CDN |
|--------|------|----------|-----|
| 🟢 bsv-didweb.min.js | 418KB | DID:web generation | unpkg.com/@smartledger/bsv@3.4.0/bsv-didweb.min.js |
| 🟢 bsv-vcjwt.min.js | 418KB | VC-JWT issue/verify | unpkg.com/@smartledger/bsv@3.4.0/bsv-vcjwt.min.js |
| 🟢 bsv-statuslist.min.js | 486KB | StatusList2021 revocation | unpkg.com/@smartledger/bsv@3.4.0/bsv-statuslist.min.js |
| 🟢 bsv-anchor.min.js | 417KB | BSV anchoring (hash-only) | unpkg.com/@smartledger/bsv@3.4.0/bsv-anchor.min.js |$3
| Module | Size | Use Case | CDN |
|--------|------|----------|-----|
| bsv-smartcontract.min.js | 451KB | Complete covenant framework | unpkg.com/@smartledger/bsv@3.4.0/bsv-smartcontract.min.js |
| bsv-covenant.min.js | 32KB | Covenant operations | unpkg.com/@smartledger/bsv@3.4.0/bsv-covenant.min.js |
| bsv-script-helper.min.js | 27KB | Custom script tools | unpkg.com/@smartledger/bsv@3.4.0/bsv-script-helper.min.js |
| bsv-security.min.js | 290KB | Security enhancements | unpkg.com/@smartledger/bsv@3.4.0/bsv-security.min.js |$3
| Module | Size | Use Case | CDN |
|--------|------|----------|-----|
| bsv-ltp.min.js | 817KB | Legal Token Protocol | unpkg.com/@smartledger/bsv@3.4.0/bsv-ltp.min.js |
| bsv-gdaf.min.js | 604KB | Digital Identity & Attestation | unpkg.com/@smartledger/bsv@3.4.0/bsv-gdaf.min.js |$3
| Module | Size | Use Case | CDN |
|--------|------|----------|-----|
| bsv-shamir.min.js | 433KB | Threshold Cryptography | unpkg.com/@smartledger/bsv@3.4.0/bsv-shamir.min.js |$3
| Module | Size | Use Case | CDN |
|--------|------|----------|-----|
| bsv-ecies.min.js | 71KB | Encryption | unpkg.com/@smartledger/bsv@3.4.0/bsv-ecies.min.js |
| bsv-message.min.js | 26KB | Message signing | unpkg.com/@smartledger/bsv@3.4.0/bsv-message.min.js |
| bsv-mnemonic.min.js | 670KB | HD wallets | unpkg.com/@smartledger/bsv@3.4.0/bsv-mnemonic.min.js |⚡ 2-Minute Quick Start
Get started with Bitcoin SV development in under 2 minutes:
`bash
Install via npm
npm install @smartledger/bsvOr include in HTML
`> 🔧 v3.4.0 Update: Added legally-recognizable W3C Verifiable Credentials with DID:web + VC-JWT toolkit. ES256/ES256K support, StatusList2021 revocation, and privacy-preserving BSV anchoring. Complete CLI tooling included!
Basic Transaction (30 seconds):
javascript
const bsv = require('@smartledger/bsv'); // Node.js
// const bsv = window.bsv; // Browser// 1. Generate keys
const privateKey = new bsv.PrivateKey();
const address = privateKey.toAddress();
// 2. Create transaction
const tx = new bsv.Transaction()
.from(utxo) // Add input
.to(targetAddress, 50000) // Send 50,000 satoshis
.change(address) // Send change back
.sign(privateKey); // Sign transaction
console.log('Transaction ID:', tx.id);
`🆕 Legal Token Development (60 seconds):
javascript
// Create legal property token
const propertyToken = bsv.createPropertyToken({
propertyType: 'real_estate',
jurisdiction: 'us_delaware',
legalDescription: 'Lot 15, Block 3, Subdivision ABC',
ownerIdentity: ownerDID
});// Generate W3C Verifiable Credential
const credential = bsv.createEmailCredential(
issuerDID, subjectDID, 'user@example.com', issuerPrivateKey
);
// Threshold cryptography for secure key management
const shares = bsv.splitSecret('private_key_backup', 5, 3); // 5 shares, 3 needed
`🆕 Smart Contract Development (90 seconds):
javascript
// Generate authentic UTXOs for testing
const utxoGenerator = new bsv.SmartContract.UTXOGenerator();
const utxos = utxoGenerator.createRealUTXOs(2, 100000);// Create BIP-143 preimage and extract fields
const preimage = new bsv.SmartContract.Preimage(preimageHex);
const amount = preimage.getField('amount');
// Build covenant with JavaScript-to-Script translation
const covenant = bsv.SmartContract.createCovenantBuilder()
.extractField('amount')
.push(50000)
.greaterThanOrEqual()
.verify()
.build();
`Next Steps:
- 📖 SmartContract Guide
- ⚖️ Legal Token Protocol Guide
- 🌐 Digital Identity Guide
- � Threshold Cryptography Guide
- �️ UTXO Manager Guide
- 💡 Examples Directory
🔧 API Reference
| Component | Method | Purpose | Example |
|-----------|--------|---------|---------|
| Core |
| Generate private key | const key = new bsv.PrivateKey() |
| | new Transaction() | Create transaction | const tx = new bsv.Transaction() |
| | Script.fromASM() | Parse script | const script = bsv.Script.fromASM('OP_DUP') |
| Covenant | CovenantInterface() | Covenant development | const covenant = new bsv.CovenantInterface() |
| | createCovenantTransaction() | Covenant transaction | covenant.createCovenantTransaction(config) |
| | getPreimage() | BIP143 preimage | covenant.getPreimage(tx, 0, script, sats) |
| Custom Scripts | CustomScriptHelper() | Script utilities | const helper = new bsv.CustomScriptHelper() |
| | createSignature() | Manual signature | helper.createSignature(tx, key, 0, script, sats) |
| | createMultisigScript() | Multi-signature | helper.createMultisigScript([pk1, pk2], 2) |
| Debug Tools | SmartContract.examineStack() | Analyze script | SmartContract.examineStack(script) |
| | interpretScript() | Execute script | SmartContract.interpretScript(script) |
| | getScriptMetrics() | Performance data | SmartContract.getScriptMetrics(script) |
| Security | SmartVerify.verify() | Enhanced verification | SmartVerify.verify(sig, hash, pubkey) |
| | EllipticFixed.sign() | Secure signing | EllipticFixed.sign(hash, privateKey) |> 💡 Tip: All methods include comprehensive error handling and validation. See documentation links for detailed guides.
📚 Quick Start Examples
$3
`html
`$3
html
`$3
html
`$3
html
`$3
html
`🎯 Key Features
$3
- ✅ Legal Token Protocol: Compliant tokenization of real-world assets → Legal Guide
- ✅ Digital Identity Framework: W3C Verifiable Credentials and DIDs → Identity Guide
- ✅ Threshold Cryptography: Shamir Secret Sharing for secure key management → Cryptography Guide
- ✅ Complete Smart Contract Suite: 23+ production-ready covenant features → SmartContract Guide$3
- ✅ Complete BSV API: Full Bitcoin SV blockchain operations → API Reference
- ✅ Security Hardened: SmartLedger elliptic curve fixes and enhanced validation → Security Features
- ✅ Browser + Node.js: Universal compatibility with proper polyfills → Loading Options
- ✅ TypeScript Ready: Complete type definitions included
- ✅ Ultra-Low Fees: 0.01 sats/byte configuration (91% fee reduction)$3
- 🔧 JavaScript-to-Script: High-level covenant development with 121 opcode mapping → Covenant Guide
- 🔧 UTXO Generator: Create authentic test UTXOs for development → UTXO Guide
- 🔧 Preimage Parser: Complete BIP-143 field extraction and manipulation → Preimage Tools
- � Debug Framework: Script interpreter, stack examiner, and optimizer → Debug Examples
- � PUSHTX Integration: nChain techniques for advanced covenant patterns → PUSHTX Insights$3
- 📦 12 Modular Options: Load only what you need (27KB to 885KB) → Loading Strategy
- 📦 Standalone Modules: Independent legal, identity, and crypto modules → Standalone Test
- 📦 Complete Bundle: Everything in one file for convenience → Bundle Demo
- 📦 CDN Ready: All modules available via unpkg and jsDelivr
- 📦 Webpack Optimized: Tree-shakeable and build-tool friendly⚡ Installation & Usage
> 💡 Quick Start: Jump to 2-Minute Quick Start for instant setup examples
$3
bash
Main package
npm install @smartledger/bsvAlternative package name (legacy)
npm install smartledger-bsv
`> 📖 Next Steps: After installation, see Loading Options to choose your distribution method
$3
javascript
const bsv = require('@smartledger/bsv');// Basic transaction
const privateKey = new bsv.PrivateKey();
const publicKey = privateKey.toPublicKey();
const address = privateKey.toAddress();
// SmartContract debugging
const script = bsv.Script.fromASM('OP_1 OP_2 OP_ADD OP_3 OP_EQUAL');
const metrics = bsv.SmartContract.getScriptMetrics(script);
const stackInfo = bsv.SmartContract.examineStack(script);
// Covenant development
const covenant = new bsv.CovenantInterface();
const contractTx = covenant.createCovenantTransaction({
inputs: [...],
outputs: [...]
});
`$3
#### 1. Minimal Setup - Core + Script Helper (476KB)
html
`#### 2. DeFi Development - Core + Covenants + Debug (932KB)
html
`#### 3. Security First - Core + Enhanced Security (739KB)
html
`#### 4. Everything Bundle - One File Solution (764KB)
html
`
🔨 Basic Usage
$3
javascript
const bsv = require('@smartledger/bsv');// Create transaction with optimized fees
const transaction = new bsv.Transaction()
.from({
txId: 'prev_tx_id',
outputIndex: 0,
script: 'prev_locking_script',
satoshis: 100000
})
.to('1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', 95000)
.feePerKb(10) // Ultra-low fee: 0.01 sats/byte
.sign(privateKey);
console.log('Transaction ID:', transaction.id);
console.log('Fee rate: 0.01 sats/byte (91% reduction)');
`$3
javascript
// Advanced UTXO state management
const utxoManager = {
createWithChange: (inputs, outputs, changeAddress) => {
const tx = new bsv.Transaction()
.from(inputs)
.to(outputs.address, outputs.amount)
.change(changeAddress)
.feePerKb(10);
// Automatic change output creation and UTXO state update
return tx;
}
};
`🆕 Advanced Features (Unique to SmartLedger-BSV)
$3
javascript
const bsv = require('@smartledger/bsv');// Create property rights token
const propertyToken = bsv.createPropertyToken({
propertyType: 'real_estate',
jurisdiction: 'us_delaware',
legalDescription: 'Lot 15, Block 3, Subdivision ABC',
ownerIdentity: ownerDID,
attestations: [titleAttestation, valuationAttestation]
});
// Create obligation token
const obligation = bsv.createObligationToken({
obligationType: 'payment',
amount: 100000, // satoshis
dueDate: '2025-12-31',
creditor: creditorDID,
debtor: debtorDID
});
// Validate legal compliance
const compliance = bsv.validateLegalCompliance(propertyToken, 'us_delaware');
console.log('Legally compliant:', compliance.isValid);
`$3
javascript
// Simple Interface - Direct from bsv object
const issuerDID = bsv.createDID(privateKey.toPublicKey());// Create W3C Verifiable Credentials
const emailCredential = bsv.createEmailCredential(
issuerDID, subjectDID, 'user@example.com', issuerPrivateKey
);
// Generate zero-knowledge proofs
const proof = bsv.generateSelectiveProof(
emailCredential,
['credentialSubject.verified'],
nonce
);
// Verify age without revealing exact age
const ageProof = bsv.generateAgeProof(credential, 18);
const isAdult = bsv.verifyAgeProof(ageProof, 18, issuerDID);
// Advanced Interface for complex applications
const gdaf = new bsv.GDAF({
anchor: { network: 'mainnet' },
attestationSigner: { customConfig: true }
});
`$3
javascript
// Split secret into threshold shares
const secret = 'my_private_key_backup';
const shares = bsv.splitSecret(secret, 5, 3); // 5 shares, need 3 to reconstructconsole.log('Generated', shares.length, 'shares');
shares.forEach((share, i) => {
console.log(
Share ${i + 1}:, share);
});// Reconstruct secret from any 3 shares
const reconstructed = bsv.reconstructSecret([shares[0], shares[2], shares[4]]);
console.log('Secret recovered:', reconstructed === secret);
// Validate share integrity
shares.forEach((share, i) => {
const isValid = bsv.validateShare(share);
console.log(
Share ${i + 1} valid:, isValid);
});// Use cases: Key backup, multi-party security, recovery systems
`🔒 Covenant Framework
$3
javascript
const { CovenantBuilder, CovenantTemplates } = require('@smartledger/bsv/lib/smart_contract');// Write covenant logic in JavaScript
const valueLock = CovenantTemplates.valueLock('50c3000000000000');
const script = valueLock.build();
console.log(script.cleanedASM);
// Output: OP_SIZE 34 OP_SUB OP_SPLIT OP_DROP OP_8 OP_SPLIT OP_DROP 50c3000000000000 OP_EQUALVERIFY OP_1
// Custom covenant builder
const custom = new CovenantBuilder()
.comment('Validate preimage value field')
.extractField('value')
.push('50c3000000000000')
.equalVerify()
.push(1);
`$3
javascript
const SmartContract = require('@smartledger/bsv/lib/smart_contract');// Simulate script execution in JavaScript
const result = SmartContract.simulateScript(['OP_1', 'OP_2', 'OP_ADD', 'OP_3', 'OP_EQUAL']);
console.log(result.finalStack); // ['01'] - TRUE
// Get comprehensive opcode information
const opcodes = SmartContract.getOpcodeMap();
console.log(Object.keys(opcodes).length); // 121 opcodes mapped
`$3
javascript
const { CovenantPreimage } = require('@smartledger/bsv/lib/covenant-interface');// Enhanced preimage parsing with field-by-field access
const preimage = new CovenantPreimage(preimageHex);
console.log('Version:', preimage.nVersionValue); // uint32 accessor
console.log('Amount:', preimage.amountValue); // BigInt accessor
console.log('Valid structure:', preimage.isValid); // Boolean validation
`$3
javascript
const { CovenantInterface } = require('@smartledger/bsv/lib/covenant-interface');
const covenant = new CovenantInterface();// Create PUSHTX covenant with in-script signature generation
const pushtxCovenant = covenant.createAdvancedCovenant('pushtx', {
publicKey: '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
enforceOutputs: true,
sighashType: 0x41
});
`$3
javascript
// Create perpetual covenant that enforces rules across all future transactions
const pels = covenant.createAdvancedCovenant('perpetual', {
publicKeyHash: '751e76e8199196d454941c45d1b3a323f1433bd6',
feeDeduction: 512,
enforceScript: true,
enforceValue: true
});
`🛠️ Custom Scripts
$3
javascript
const { CustomScriptHelper } = require('@smartledger/bsv/lib/custom-script-helper');
const helper = new CustomScriptHelper();// Create 2-of-3 multisig script
const multisigScript = helper.createMultisigScript([
publicKey1, publicKey2, publicKey3
], 2);
`$3
javascript
// Create timelock script (block height)
const timelockScript = helper.createTimelockScript(
publicKey,
750000, // block height
'block'
);
`� Examples
$3
- Advanced Covenant Demo: Complete covenant showcase
- Custom Script Tests: Script development examples
- Covenant Resolution: Working covenant patterns$3
- Advanced Covenant Development: Complete BIP143 + PUSHTX guide
- Custom Script Development: Script creation patterns
- Covenant Development Resolved: Problem solutions🔧 CDN Bundles
| Bundle | Size | Description |
|--------|------|-------------|
|
| 684KB | Complete library with all features |
| bsv.min.js | 364KB | Minified production version |
| bsv-ecies.min.js | 145KB | ECIES encryption only |
| bsv-message.min.js | 120KB | Message signing only |
| bsv-mnemonic.min.js | 98KB | Mnemonic handling only |🔐 Security
$3
- Elliptic Curve Fix: Updated to secure elliptic@6.6.1
- Parameter Fixing: Public key, ephemeral key, sighash flag validation
- DER Canonicalization: Transaction malleability prevention
- Preimage Validation: Complete BIP143 structure verification📝 Changelog
$3
- ✅ Complete JavaScript-to-Bitcoin Script translation system
- ✅ 121 Bitcoin Script opcodes mapped to JavaScript functions
- ✅ High-level CovenantBuilder API for rapid development
- ✅ Real-time script simulation and debugging capabilities
- ✅ Template-based covenant patterns library
- ✅ Automatic ASM generation from JavaScript operations
- ✅ Enhanced documentation and comprehensive examples$3
- ✅ Enhanced covenant interface with BIP143 + PUSHTX support
- ✅ Perpetually Enforcing Locking Scripts (PELS) implementation
- ✅ Transaction introspection with preimage analysis
- ✅ Comprehensive documentation and examples$3
- ✅ Complete custom script development API
- ✅ Multi-signature, timelock, and conditional script support
- ✅ Transaction signature API gap resolution$3
- ✅ 0.01 sats/byte fee configuration (91% reduction)
- ✅ Advanced UTXO state management
- ✅ Change output optimization📄 License
---
📚 Complete Documentation
$3
- 2-Minute Quick Start - Get up and running fast
- Loading Options - Choose your distribution method
- API Reference - Quick method lookup
- Installation Guide - npm, CDN, and browser setup$3
- Advanced Covenant Development - Complete BIP143 + PUSHTX guide
- Custom Script Development - Multi-sig, timelock, and custom patterns
- Covenant Development Resolved - Solutions to common issues
- PUSHTX Key Insights - nChain research implementation$3
- SmartContract Integration - Debug tools and analysis
- Examples Directory - Working code samples
- Test Suite - Comprehensive testing examples
- Build System - Webpack configurations$3
| Use Case | Recommended Load | Size | Features |
|--------------|---------------------|----------|--------------|
| Simple Transactions |
bsv.min.js | 449KB | Core BSV + SmartContract |
| DeFi Development | Core + Covenant + Debug | 932KB | Advanced contracts + tools |
| Enterprise Apps | bsv.bundle.js | 764KB | Everything included |
| Mobile/Lightweight | Core + Script Helper | 476KB | Essential tools only |
| Research/Analysis | Core + SmartContract | 900KB | Full debug capabilities |$3
From Quick Start → Deep Dive:
- Basic Transaction → Transaction API
- Covenant Example → Advanced Covenant Guide
- API Reference → Method Documentation
From Examples → Implementation:
- Covenant Examples → Production Guide
- Script Examples → Custom Script Guide
- Test Files → Integration Examples
From Concepts → Code:
- PUSHTX Theory → Covenant Implementation
- Security Features → Implementation
- Debug Tools → Usage Examples
$3
1. Start: 2-Minute Quick Start
2. Practice: Examples Directory
3. Build: Custom Script Guide
4. Advanced: Covenant Development
5. Deploy: Production Guidelines
---
� Complete Documentation
$3
- 📋 UTXO Manager Guide - Complete UTXO management and mock generation
- 🔒 Smart Contract Guide - Comprehensive covenant development
- 🛠️ Custom Script Development - Build custom Bitcoin scripts
- 🚀 Advanced Covenant Development - Production-ready covenants$3
- ⚖️ Legal Token Protocol Guide - Property rights & obligation tokens
- 🌐 Digital Attestation Guide - DIDs & verifiable credentials
- 🔐 Shamir Secret Sharing Guide - Threshold cryptography & key backup
- 🛡️ Security Features - Enhanced validation & smart verification$3
- 📝 Module Reference - All 12 modules explained
- 🔍 Documentation Review Report - Comprehensive analysis
- 📋 API Reference - Complete API documentation
- 🔧 Integration Guide - Smart contract integration$3
- � Interactive Demos - NEW! HTML & Node.js smart contract demos
- �📁 Examples Directory - Working code examples
- 🎯 Basic Examples - Simple transactions & addresses
- 🔒 Covenant Examples - Smart contract patterns
- 📊 Advanced Examples - Production patterns🎮 Try the Interactive Demos:
`bash
Terminal-based interactive demo
npm run demoOr run specific features
npm run demo:basics # Library basics & tests
npm run demo:covenant # Covenant builder
npm run demo:preimage # BIP-143 preimage parser
npm run demo:utxo # UTXO generator
npm run demo:scripts # Script toolsWeb-based demo (open in browser)
npm run demo:web
``---
This project is licensed under the MIT License - see the LICENSE file for details.
We welcome contributions to SmartLedger-BSV! Please see our Contributing Guide for details.
- GitHub: github.com/codenlighten/smartledger-bsv
- NPM: @smartledger/bsv
- Issues: GitHub Issues
- Documentation: Complete Docs
---
SmartLedger-BSV v3.3.4 - Complete Bitcoin SV Development Framework
Built with ❤️ for the Bitcoin SV ecosystem • 9 Loading Options • Enterprise Ready