smartledger-bsv 3.3.3 → 3.3.5

package/demos/README.md

@@ -0,0 +1,188 @@
+# 🚀 SmartLedger-BSV Demo Collection
+
+This directory contains interactive demonstrations of the SmartLedger-BSV smart contract framework capabilities.
+
+## 📋 Available Demos
+
+### 1. 🌐 **HTML Interactive Demo** (`smart_contract_demo.html`)
+**Web-based interactive demonstration with visual interface**
+
+- **Purpose:** Browser-based exploration of smart contract features
+- **Interface:** Modern web UI with tabs, buttons, and real-time output
+- **Best for:** Visual learners, presentations, and quick exploration
+
+**Features:**
+- 📚 **Basics Tab** - Library loading and feature overview
+- 🔒 **Covenant Builder** - Interactive covenant creation with multiple types
+- 🧾 **Preimage Parser** - BIP-143 transaction field extraction
+- 💎 **UTXO Generator** - Mock UTXO creation and management
+- 🛠️ **Script Tools** - Bitcoin Script building and analysis
+
+**Usage:**
+```bash
+# Serve locally (requires http-server or similar)
+npx http-server demos/
+# Then open http://localhost:8080/smart_contract_demo.html
+
+# Or open directly in browser
+open demos/smart_contract_demo.html
+```
+
+---
+
+### 2. 💻 **Node.js CLI Demo** (`smart_contract_demo.js`)
+**Command-line interactive demonstration for developers**
+
+- **Purpose:** Terminal-based smart contract development workflow
+- **Interface:** Interactive CLI with colored output and structured commands
+- **Best for:** Developers, automation, CI/CD integration
+
+**Features:**
+- 🎯 **Interactive Mode** - Full CLI experience with command history
+- ⚡ **Direct Commands** - Run specific features without interaction
+- 🎨 **Colored Output** - Enhanced readability with chalk (optional)
+- 📊 **Structured Logging** - Timestamped output with status indicators
+- 🔧 **Developer-Friendly** - Perfect for scripting and automation
+
+**Usage:**
+
+```bash
+# Interactive mode
+node demos/smart_contract_demo.js
+
+# Show help
+node demos/smart_contract_demo.js --help
+
+# Run specific features
+node demos/smart_contract_demo.js --feature basics
+node demos/smart_contract_demo.js --feature covenant
+node demos/smart_contract_demo.js --feature preimage
+node demos/smart_contract_demo.js --feature utxo
+node demos/smart_contract_demo.js --feature scripts
+```
+
+**Interactive Commands:**
+```
+smartledger-bsv> basics                    # Load library and run tests
+smartledger-bsv> covenant generate simple  # Generate simple covenant
+smartledger-bsv> covenant test             # Test current covenant  
+smartledger-bsv> preimage sample           # Generate sample transaction
+smartledger-bsv> utxo generate 50000       # Generate 50k sat UTXO
+smartledger-bsv> scripts build             # Build sample script
+smartledger-bsv> examples                  # Show real-world use cases
+smartledger-bsv> help                      # Show all commands
+smartledger-bsv> exit                      # Exit demo
+```
+
+---
+
+## 🎯 **Feature Comparison**
+
+| Feature | HTML Demo | Node.js Demo |
+|---------|-----------|--------------|
+| **Interface** | Visual web UI | Command-line interface |
+| **Interactivity** | Click-based | Type-based commands |
+| **Real-time Output** | Browser console + UI | Terminal with colors |
+| **Covenant Builder** | Form inputs + dropdowns | Command parameters |
+| **Script Analysis** | Visual results panel | Structured text output |
+| **UTXO Management** | Interactive forms | Command-driven |
+| **Automation** | Manual only | Scriptable commands |
+| **Dependencies** | Modern browser | Node.js (chalk optional) |
+| **Best Use Case** | Learning & exploration | Development & testing |
+
+---
+
+## 🔧 **Common Features Demonstrated**
+
+Both demos showcase the complete SmartLedger-BSV functionality:
+
+### **Core Capabilities**
+- ✅ **Private Key & Address Generation** - Create BSV wallets
+- ✅ **Transaction Building** - Construct valid BSV transactions  
+- ✅ **Script Creation** - Build custom Bitcoin Scripts
+- ✅ **UTXO Management** - Generate and spend test UTXOs
+- ✅ **Preimage Parsing** - Extract BIP-143 transaction fields
+- ✅ **Covenant Logic** - Create smart contract spending conditions
+
+### **Smart Contract Types**
+1. **Simple Covenants** - Basic spending restrictions
+2. **Timelock Covenants** - Time-based spending conditions using preimage validation
+3. **Multisig Covenants** - Multi-signature requirements
+4. **Conditional Covenants** - IF/ELSE spending paths
+
+### **Advanced Features**
+- 🧾 **BIP-143 Preimage Extraction** - Parse transaction preimages
+- 📊 **SIGHASH Analysis** - Understand signature hash types
+- 🔍 **Script Debugging** - Step-through script execution
+- ⚡ **Script Optimization** - Minimize script size and cost
+- 🧪 **Local Testing** - Verify scripts without blockchain access
+
+---
+
+## 🚀 **Quick Start Guide**
+
+### **For Visual Learners (HTML Demo)**
+1. Open `smart_contract_demo.html` in your browser
+2. Click "Load BSV Smart Contract Library"  
+3. Explore each tab (Basics → Covenant → Preimage → UTXO → Scripts)
+4. Try the real-world use case examples
+
+### **For Developers (Node.js Demo)**
+1. Run `node demos/smart_contract_demo.js`
+2. Type `basics` to load and test the library
+3. Try `covenant generate simple` to create your first covenant
+4. Use `help` to see all available commands
+5. Explore with `utxo generate`, `preimage sample`, etc.
+
+---
+
+## 📚 **Learning Path**
+
+**Recommended progression through the demos:**
+
+1. **🎯 Start Here:** `basics` - Understand core BSV functionality
+2. **🏗️ Build:** `covenant generate` - Create your first smart contract  
+3. **🔍 Analyze:** `preimage sample` - Understand transaction structure
+4. **💎 Manage:** `utxo generate` - Handle UTXOs and spending
+5. **🛠️ Script:** `scripts build` - Custom Bitcoin Script development
+6. **🎓 Advanced:** `examples` - Real-world smart contract patterns
+
+---
+
+## 🔗 **Related Documentation**
+
+- **[Usage Guide](../docs/SMARTLEDGER_BSV_USAGE_GUIDE.md)** - Complete API reference
+- **[Usage Answers](../docs/SMARTLEDGER_BSV_USAGE_ANSWERS.md)** - FAQ and troubleshooting
+- **[Smart Contract Guide](../docs/advanced/SMART_CONTRACT_GUIDE.md)** - Advanced development
+- **[Examples Directory](../examples/)** - Additional code samples
+- **[GitHub Repository](https://github.com/codenlighten/smartledger-bsv)** - Source code
+
+---
+
+## 🆘 **Support & Troubleshooting**
+
+### **Common Issues**
+
+**HTML Demo:**
+- **Bundle not found:** Ensure `../bsv.bundle.js` exists (run `npm run build`)
+- **CORS issues:** Serve via HTTP server, don't open file:// directly
+- **Console errors:** Check browser developer tools for detailed errors
+
+**Node.js Demo:**
+- **Module errors:** Run `npm install` to ensure dependencies
+- **Chalk missing:** Demo works without chalk (fallback to plain text)
+- **Permission denied:** Use `chmod +x demos/smart_contract_demo.js`
+
+### **Getting Help**
+
+- **Issues:** [GitHub Issues](https://github.com/codenlighten/smartledger-bsv/issues)
+- **Documentation:** Check the `docs/` directory for detailed guides
+- **Examples:** Browse `examples/` for working code samples
+
+---
+
+**Created by:** SmartLedger-BSV Development Team  
+**Version:** v3.3.4  
+**Last Updated:** October 30, 2025
+
+*Both demos provide identical functionality - choose the interface that works best for your workflow!* 🎉

package/demos/architecture_demo.js

@@ -0,0 +1,247 @@
+/**
+ * SmartLedger-BSV Legal Token Protocol (LTP) - Primitives-Only Architecture Demo
+ * 
+ * This demonstrates the key architectural difference:
+ * BEFORE: Library did blockchain publishing and storage
+ * AFTER: Library provides preparation primitives, external systems handle publishing
+ */
+
+const bsv = require('../index.js')
+
+console.log('🚀 SmartLedger-BSV LTP: Primitives-Only Architecture')
+console.log('==================================================\n')
+
+console.log('🔄 ARCHITECTURAL TRANSFORMATION DEMO')
+console.log('------------------------------------\n')
+
+// Demo keys and identities
+const issuerPrivateKey = new bsv.PrivateKey()
+const ownerDID = `did:bsv:${new bsv.PrivateKey().publicKey.toString()}`
+const obligorDID = `did:bsv:${new bsv.PrivateKey().publicKey.toString()}`
+
+console.log('📋 Participants:')
+console.log(`   Issuer DID: ${issuerPrivateKey.publicKey.toString()}`)
+console.log(`   Owner DID: ${ownerDID}`)
+console.log(`   Obligor DID: ${obligorDID}\n`)
+
+/**
+ * DEMONSTRATE CLAIM VALIDATION PRIMITIVES
+ */
+console.log('1️⃣ CLAIM VALIDATION - Primitives Only')
+console.log('=====================================')
+
+const propertyClaimData = {
+  type: 'PropertyTitle',
+  property: {
+    address: '123 Blockchain Street',
+    parcel_id: 'BLK-2024-001',
+    property_type: 'residential'
+  },
+  owner: ownerDID
+}
+
+// Get available schemas (unchanged utility)
+const availableSchemas = bsv.getClaimSchemaNames()
+console.log('📚 Available claim schemas:', availableSchemas.join(', '))
+
+// Create claim template (utility function)
+const claimTemplate = bsv.createClaimTemplate('PropertyTitle')
+console.log('📋 Claim template structure:')
+console.log('   Required fields:', Object.keys(claimTemplate).slice(0, 3).join(', '), '...')
+
+console.log('\n🔧 PRIMITIVES-ONLY APPROACH:')
+console.log('   ✅ Library validates claim structure')
+console.log('   ✅ Library provides canonicalization')
+console.log('   ✅ Library generates claim hash')
+console.log('   ❌ Library does NOT store claims')
+console.log('   ❌ Library does NOT publish to blockchain')
+
+// Demonstrate claim processing primitives
+const claimHash = bsv.hashClaim(propertyClaimData)
+const canonicalClaim = bsv.canonicalizeClaim(propertyClaimData)
+
+console.log('📊 Claim processing results:')
+console.log(`   Claim Hash: ${claimHash}`)
+console.log(`   Canonical Form: ${canonicalClaim.length} bytes`)
+console.log('')
+
+/**
+ * DEMONSTRATE RIGHT TOKEN PRIMITIVES
+ */
+console.log('2️⃣ RIGHT TOKEN - Preparation Primitives')
+console.log('=======================================')
+
+console.log('🔧 PRIMITIVES-ONLY APPROACH:')
+
+// Get available right types
+const rightTypes = bsv.getRightTypes()
+console.log('⚖️ Available right types:', Object.keys(rightTypes).slice(0, 4).join(', '), '...')
+
+// Prepare right token (doesn't create, just prepares structure)
+try {
+  const rightTokenPrep = bsv.prepareRightToken(
+    'PROPERTY_OWNERSHIP',
+    `did:bsv:${issuerPrivateKey.publicKey.toString()}`,
+    ownerDID,
+    propertyClaimData,
+    issuerPrivateKey,
+    {
+      jurisdiction: 'demo_jurisdiction',
+      validUntil: '2034-01-15'
+    }
+  )
+
+  console.log('🏠 Right token prepared:')
+  console.log(`   Token ID: ${rightTokenPrep.tokenId}`)
+  console.log(`   Right Type: ${rightTokenPrep.rightType}`)
+  console.log(`   Valid Until: ${rightTokenPrep.validUntil}`)
+  console.log(`   Jurisdiction: ${rightTokenPrep.jurisdiction}`)
+
+  // Prepare verification data
+  const verificationPrep = bsv.prepareRightTokenVerification(rightTokenPrep.token)
+  console.log(`   Verification Ready: ${verificationPrep.isValid ? 'YES' : 'NO'}`)
+
+  console.log('\n   ✅ Library prepares token structure')
+  console.log('   ✅ Library validates token format')
+  console.log('   ✅ Library signs token data')
+  console.log('   ❌ Library does NOT publish to blockchain')
+  console.log('   ❌ Library does NOT store in registry')
+
+} catch (error) {
+  console.log('⚠️ Right token preparation demo skipped (module loading)')
+  console.log('   Expected: Token preparation without blockchain publishing')
+}
+
+console.log('')
+
+/**
+ * DEMONSTRATE OBLIGATION PRIMITIVES
+ */
+console.log('3️⃣ OBLIGATION TOKEN - Management Primitives')
+console.log('===========================================')
+
+console.log('🔧 PRIMITIVES-ONLY APPROACH:')
+
+// Get obligation types and statuses
+try {
+  const obligationTypes = bsv.getObligationTypes()
+  const obligationStatuses = bsv.getObligationStatus()
+  
+  console.log('📊 Obligation framework:')
+  console.log(`   Types available: ${Object.keys(obligationTypes).length}`)
+  console.log(`   Status options: ${Object.keys(obligationStatuses).length}`)
+  console.log(`   Priority levels: ${Object.keys(bsv.getObligationPriority()).length}`)
+
+  console.log('\n   ✅ Library prepares obligation tokens')
+  console.log('   ✅ Library validates fulfillment data')
+  console.log('   ✅ Library tracks obligation status')
+  console.log('   ❌ Library does NOT execute payments')
+  console.log('   ❌ Library does NOT enforce obligations')
+
+} catch (error) {
+  console.log('⚠️ Obligation demo skipped (module loading)')
+  console.log('   Expected: Obligation management without execution')
+}
+
+console.log('')
+
+/**
+ * DEMONSTRATE REGISTRY PRIMITIVES
+ */
+console.log('4️⃣ REGISTRY MANAGEMENT - Preparation Primitives')
+console.log('===============================================')
+
+console.log('🔧 PRIMITIVES-ONLY APPROACH:')
+console.log('   ✅ Library prepares registry data structures')
+console.log('   ✅ Library formats token registration data')
+console.log('   ✅ Library validates registry queries')
+console.log('   ❌ Library does NOT store registry data')
+console.log('   ❌ Library does NOT manage database connections')
+
+// Simulate registry preparation
+console.log('📝 Registry operations prepared:')
+console.log('   • Token registration data formatted')
+console.log('   • Search query structure validated')
+console.log('   • Audit log format prepared')
+console.log('   • Statistics query template ready')
+console.log('')
+
+/**
+ * DEMONSTRATE BLOCKCHAIN ANCHORING PRIMITIVES
+ */
+console.log('5️⃣ BLOCKCHAIN ANCHORING - Commitment Primitives')
+console.log('===============================================')
+
+console.log('🔧 PRIMITIVES-ONLY APPROACH:')
+console.log('   ✅ Library prepares commitment hashes')
+console.log('   ✅ Library creates merkle tree structures')
+console.log('   ✅ Library validates anchor proofs')
+console.log('   ❌ Library does NOT publish transactions')
+console.log('   ❌ Library does NOT manage wallet keys')
+
+// Simulate anchor preparation
+console.log('⛓️ Blockchain operations prepared:')
+console.log('   • Token commitment hash: ready for transaction')
+console.log('   • Batch merkle root: ready for efficient anchoring')
+console.log('   • Verification proof: ready for anchor validation')
+console.log('   • Revocation format: ready for token cancellation')
+console.log('')
+
+/**
+ * SUMMARY OF ARCHITECTURAL BENEFITS
+ */
+console.log('🎯 PRIMITIVES-ONLY ARCHITECTURE BENEFITS')
+console.log('========================================')
+console.log('')
+console.log('🏗️ SEPARATION OF CONCERNS:')
+console.log('   📚 SmartLedger-BSV: Foundation library with crypto primitives')
+console.log('   🔧 External Apps: Handle UI, storage, and blockchain publishing')
+console.log('   ⚖️ Legal Framework: Validated structure and compliance tools')
+console.log('')
+console.log('💪 DEVELOPER BENEFITS:')
+console.log('   • Maximum flexibility in implementation choices')
+console.log('   • No vendor lock-in to specific platforms or blockchains')
+console.log('   • Clean separation between crypto/legal logic and app logic')
+console.log('   • Easy integration with existing systems and workflows')
+console.log('')
+console.log('⚡ LIBRARY ADVANTAGES:')
+console.log('   • Focused on what it does best: cryptography and validation')
+console.log('   • Smaller footprint and fewer dependencies')
+console.log('   • More predictable behavior and easier testing')
+console.log('   • Clear API boundaries and responsibilities')
+console.log('')
+console.log('🔗 INTEGRATION PATTERN:')
+console.log('   1. Use SmartLedger-BSV to prepare and validate legal tokens')
+console.log('   2. Use external systems for blockchain publishing')
+console.log('   3. Use external systems for storage and registries') 
+console.log('   4. Use external systems for user interfaces and workflows')
+console.log('')
+console.log('🚀 RESULT: Complete foundation for any Legal Token Protocol')
+console.log('   application while maintaining architectural flexibility!')
+
+/**
+ * SHOW EXAMPLE EXTERNAL SYSTEM INTEGRATION
+ */
+console.log('')
+console.log('📋 EXAMPLE: How External Systems Would Use These Primitives')
+console.log('=========================================================')
+console.log('')
+console.log('// External Application Code Example:')
+console.log('const bsv = require("smartledger-bsv")')
+console.log('const MyBlockchainAPI = require("my-blockchain-service")')
+console.log('const MyStorage = require("my-database-service")')
+console.log('')
+console.log('// 1. Use SmartLedger-BSV to prepare legal token')
+console.log('const tokenPrep = bsv.prepareRightToken(...)')
+console.log('')
+console.log('// 2. Use external service to publish to blockchain')
+console.log('const txResult = await MyBlockchainAPI.publish(tokenPrep.commitment)')
+console.log('')
+console.log('// 3. Use external service to store token data')
+console.log('const storeResult = await MyStorage.save(tokenPrep.token)')
+console.log('')
+console.log('// 4. Use SmartLedger-BSV to verify results')
+console.log('const verification = bsv.verifyTokenAnchor(token, txResult.txid)')
+console.log('')
+console.log('This pattern gives developers complete control while ensuring')
+console.log('cryptographic and legal correctness through SmartLedger-BSV!')