smartledger-bsv 3.3.2 → 3.3.4

package/demos/preimage_separation_demo.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+
+/**
+ * UTXO Generator and Preimage Separation Demonstration
+ * 
+ * This example shows how to:
+ * 1. Generate authentic UTXOs using the UTXOGenerator
+ * 2. Create transactions and extract BIP-143 preimages
+ * 3. Separate preimage into individual fields with detailed analysis
+ * 4. Display each component with hex values and interpretations
+ */
+
+// Workaround for Node.js environment with minified BSV
+global.window = global.window || {};
+global.window.crypto = global.window.crypto || require('crypto').webcrypto || require('crypto');
+
+const bsv = require('../bsv.min.js');
+const SmartContract = bsv.SmartContract;
+
+console.log('🔧 UTXO Generator and Preimage Separation Demo');
+console.log('=' .repeat(60));
+
+async function demonstrateUTXOAndPreimage() {
+    try {
+        // Step 1: Generate authentic UTXOs
+        console.log('\n📦 Step 1: Generating Authentic UTXOs');
+        console.log('-'.repeat(40));
+        
+        // Create simple mock UTXOs for preimage demonstration
+        const demoPrivateKey = new bsv.PrivateKey();
+        const demoAddress = demoPrivateKey.toAddress();
+        
+        const utxos = [
+            {
+                txid: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+                vout: 0,
+                scriptPubKey: bsv.Script.buildPublicKeyHashOut(demoAddress).toHex(),
+                satoshis: 150000
+            },
+            {
+                txid: 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
+                vout: 1,
+                scriptPubKey: bsv.Script.buildPublicKeyHashOut(demoAddress).toHex(),
+                satoshis: 150000
+            }
+        ];
+        
+        console.log('✅ Mock UTXOs Created for Demo:');
+        console.log(`   Count: ${utxos.length}`);
+        console.log(`   Address: ${demoAddress.toString()}`);
+        console.log(`   Private Key (WIF): ${demoPrivateKey.toWIF()}`);
+        
+        utxos.forEach((utxo, index) => {
+            console.log(`\n   UTXO ${index + 1}:`);
+            console.log(`     TXID: ${utxo.txid}`);
+            console.log(`     VOUT: ${utxo.vout}`);
+            console.log(`     Satoshis: ${utxo.satoshis.toLocaleString()}`);
+            console.log(`     Script: ${utxo.script}`);
+        });
+        
+        // Step 2: Create a transaction using the UTXOs
+        console.log('\n\n🔨 Step 2: Creating Transaction from UTXOs');
+        console.log('-'.repeat(40));
+        
+        const privateKey = demoPrivateKey;
+        const address = demoAddress;
+        
+        // Create transaction spending first UTXO
+        const tx = new bsv.Transaction()
+            .from({
+                txId: utxos[0].txid,
+                outputIndex: utxos[0].vout,
+                scriptPubKey: utxos[0].scriptPubKey,
+                satoshis: utxos[0].satoshis
+            })
+            .to(address, 140000)  // Send to same address with fee
+            .change(address)      // Change back to same address
+            .sign(privateKey);
+        
+        console.log('✅ Transaction Created:');
+        console.log(`   Transaction ID: ${tx.id}`);
+        console.log(`   Inputs: ${tx.inputs.length}`);
+        console.log(`   Outputs: ${tx.outputs.length}`);
+        console.log(`   Fee: ${tx.getFee()} satoshis`);
+        
+        // Display transaction details
+        tx.inputs.forEach((input, index) => {
+            console.log(`\n   Input ${index + 1}:`);
+            console.log(`     Previous TXID: ${input.prevTxId.toString('hex')}`);
+            console.log(`     Output Index: ${input.outputIndex}`);
+            console.log(`     Script: ${input.script ? input.script.toString() : 'None'}`);
+        });
+        
+        tx.outputs.forEach((output, index) => {
+            console.log(`\n   Output ${index + 1}:`);
+            console.log(`     Satoshis: ${output.satoshis.toLocaleString()}`);
+            console.log(`     Script: ${output.script.toString()}`);
+            console.log(`     Address: ${output.script.toAddress().toString()}`);
+        });
+        
+        // Step 3: Generate BIP-143 Preimage
+        console.log('\n\n🔍 Step 3: Generating BIP-143 Preimage');
+        console.log('-'.repeat(40));
+        
+        const inputIndex = 0;
+        const sighashType = bsv.crypto.Signature.SIGHASH_ALL | bsv.crypto.Signature.SIGHASH_FORKID;
+        const subscript = bsv.Script.buildPublicKeyHashOut(address);
+        const satoshis = new bsv.crypto.BN(utxos[0].satoshis);
+        
+        const preimageBuffer = bsv.Transaction.sighash.sighashPreimage(
+            tx,
+            sighashType,
+            inputIndex,
+            subscript,
+            satoshis
+        );
+        
+        console.log('✅ Preimage Generated:');
+        console.log(`   Length: ${preimageBuffer.length} bytes`);
+        console.log(`   Hex: ${preimageBuffer.toString('hex')}`);
+        console.log(`   SIGHASH Type: 0x${sighashType.toString(16)}`);
+        
+        // Step 4: Separate Preimage into Individual Fields
+        console.log('\n\n🔬 Step 4: Preimage Field Separation Analysis');
+        console.log('='.repeat(60));
+        
+        // Create preimage analyzer
+        const preimage = new SmartContract.Preimage(preimageBuffer.toString('hex'));
+        
+        // Extract all fields using different strategies
+        console.log('\n📋 Field Extraction Strategy Comparison:');
+        console.log('-'.repeat(50));
+        
+        try {
+            const leftExtraction = preimage.extract('LEFT');
+            console.log('✅ LEFT extraction successful:', Object.keys(leftExtraction).length, 'fields');
+        } catch (error) {
+            console.log('❌ LEFT extraction failed:', error.message);
+        }
+        
+        try {
+            const rightExtraction = preimage.extract('RIGHT');
+            console.log('✅ RIGHT extraction successful:', Object.keys(rightExtraction).length, 'fields');
+        } catch (error) {
+            console.log('❌ RIGHT extraction failed:', error.message);
+        }
+        
+        try {
+            const dynamicExtraction = preimage.extract('DYNAMIC');
+            console.log('✅ DYNAMIC extraction successful:', Object.keys(dynamicExtraction).length, 'fields');
+        } catch (error) {
+            console.log('❌ DYNAMIC extraction failed:', error.message);
+        }
+        
+        // Manual field-by-field extraction with detailed analysis
+        console.log('\n\n🔍 Detailed Field-by-Field Analysis:');
+        console.log('='.repeat(60));
+        
+        const fields = [
+            'version',
+            'hashPrevouts', 
+            'hashSequence',
+            'outpoint',
+            'scriptCode',
+            'amount',
+            'sequence',
+            'hashOutputs',
+            'locktime',
+            'sighash'
+        ];
+        
+        let offset = 0;
+        const fieldDetails = {};
+        
+        fields.forEach((fieldName, index) => {
+            console.log(`\n${index + 1}. ${fieldName.toUpperCase()}:`);
+            console.log('-'.repeat(20));
+            
+            try {
+                const fieldBuffer = preimage.getField(fieldName);
+                fieldDetails[fieldName] = {
+                    buffer: fieldBuffer,
+                    hex: fieldBuffer.toString('hex'),
+                    length: fieldBuffer.length,
+                    offset: offset
+                };
+                
+                console.log(`   Hex Value: ${fieldBuffer.toString('hex')}`);
+                console.log(`   Length: ${fieldBuffer.length} bytes`);
+                console.log(`   Offset: ${offset}-${offset + fieldBuffer.length - 1}`);
+                
+                // Interpret field values where possible
+                switch (fieldName) {
+                    case 'version':
+                        const version = fieldBuffer.readUInt32LE(0);
+                        console.log(`   Interpreted: Version ${version}`);
+                        break;
+                        
+                    case 'amount':
+                        const amount = fieldBuffer.readBigUInt64LE(0);
+                        console.log(`   Interpreted: ${amount.toString()} satoshis (${(Number(amount) / 100000000).toFixed(8)} BSV)`);
+                        break;
+                        
+                    case 'sequence':
+                        const sequence = fieldBuffer.readUInt32LE(0);
+                        console.log(`   Interpreted: Sequence ${sequence} (0x${sequence.toString(16)})`);
+                        break;
+                        
+                    case 'locktime':
+                        const locktime = fieldBuffer.readUInt32LE(0);
+                        if (locktime < 500000000) {
+                            console.log(`   Interpreted: Block height ${locktime}`);
+                        } else {
+                            console.log(`   Interpreted: Unix timestamp ${locktime} (${new Date(locktime * 1000).toISOString()})`);
+                        }
+                        break;
+                        
+                    case 'sighash':
+                        const sighashValue = fieldBuffer.readUInt32LE(0);
+                        console.log(`   Interpreted: SIGHASH 0x${sighashValue.toString(16)}`);
+                        
+                        // Decode SIGHASH flags
+                        const flags = [];
+                        if (sighashValue & 0x01) flags.push('SIGHASH_ALL');
+                        if (sighashValue & 0x02) flags.push('SIGHASH_NONE');
+                        if (sighashValue & 0x03) flags.push('SIGHASH_SINGLE');
+                        if (sighashValue & 0x80) flags.push('SIGHASH_ANYONECANPAY');
+                        if (sighashValue & 0x40) flags.push('SIGHASH_FORKID');
+                        
+                        console.log(`   Flags: ${flags.join(' | ')}`);
+                        break;
+                        
+                    case 'outpoint':
+                        const txid = fieldBuffer.slice(0, 32).reverse().toString('hex');
+                        const vout = fieldBuffer.slice(32, 36).readUInt32LE(0);
+                        console.log(`   Interpreted: ${txid}:${vout}`);
+                        break;
+                        
+                    case 'scriptCode':
+                        try {
+                            const script = new bsv.Script(fieldBuffer);
+                            console.log(`   Interpreted: ${script.toString()}`);
+                        } catch (error) {
+                            console.log(`   Interpreted: Raw script data (${fieldBuffer.length} bytes)`);
+                        }
+                        break;
+                        
+                    default:
+                        if (fieldBuffer.length === 32) {
+                            console.log(`   Interpreted: 32-byte hash (likely SHA256)`);
+                        } else {
+                            console.log(`   Interpreted: Raw binary data`);
+                        }
+                }
+                
+                offset += fieldBuffer.length;
+                
+            } catch (error) {
+                console.log(`   ❌ Error extracting field: ${error.message}`);
+                fieldDetails[fieldName] = { error: error.message };
+            }
+        });
+        
+        // Step 5: Preimage Validation and Analysis
+        console.log('\n\n🔍 Step 5: Preimage Validation and Analysis');
+        console.log('='.repeat(60));
+        
+        // Get SIGHASH analysis
+        try {
+            const sighashInfo = preimage.getSighashInfo();
+            console.log('\n📊 SIGHASH Analysis:');
+            console.log(`   Has zero hashes: ${sighashInfo.hasZeroHashes ? '⚠️  YES' : '✅ NO'}`);
+            console.log(`   SIGHASH type detected: ${sighashInfo.type || 'Unknown'}`);
+            console.log(`   Is standard: ${sighashInfo.isStandard ? '✅ YES' : '❌ NO'}`);
+            
+            if (sighashInfo.warnings && sighashInfo.warnings.length > 0) {
+                console.log('\n⚠️  Warnings:');
+                sighashInfo.warnings.forEach(warning => {
+                    console.log(`   - ${warning}`);
+                });
+            }
+        } catch (error) {
+            console.log('❌ SIGHASH analysis failed:', error.message);
+        }
+        
+        // Verify preimage reconstruction
+        console.log('\n🔧 Preimage Reconstruction Verification:');
+        console.log('-'.repeat(40));
+        
+        let reconstructed = Buffer.alloc(0);
+        let reconstructionErrors = 0;
+        
+        fields.forEach(fieldName => {
+            if (fieldDetails[fieldName] && fieldDetails[fieldName].buffer) {
+                reconstructed = Buffer.concat([reconstructed, fieldDetails[fieldName].buffer]);
+            } else {
+                reconstructionErrors++;
+                console.log(`   ❌ Missing field: ${fieldName}`);
+            }
+        });
+        
+        const originalHex = preimageBuffer.toString('hex');
+        const reconstructedHex = reconstructed.toString('hex');
+        const matches = originalHex === reconstructedHex;
+        
+        console.log(`   Original length: ${preimageBuffer.length} bytes`);
+        console.log(`   Reconstructed length: ${reconstructed.length} bytes`);
+        console.log(`   Reconstruction errors: ${reconstructionErrors}`);
+        console.log(`   Fields match: ${matches ? '✅ YES' : '❌ NO'}`);
+        
+        if (!matches && reconstructionErrors === 0) {
+            console.log('\n🔍 Hex Comparison (first 200 chars):');
+            console.log(`   Original:      ${originalHex.substring(0, 200)}${originalHex.length > 200 ? '...' : ''}`);
+            console.log(`   Reconstructed: ${reconstructedHex.substring(0, 200)}${reconstructedHex.length > 200 ? '...' : ''}`);
+        }
+        
+        // Step 6: Summary and Statistics
+        console.log('\n\n📈 Step 6: Summary and Statistics');
+        console.log('='.repeat(60));
+        
+        const totalFields = fields.length;
+        const successfulFields = Object.keys(fieldDetails).filter(k => fieldDetails[k].buffer).length;
+        const totalBytes = Object.values(fieldDetails)
+            .filter(f => f.buffer)
+            .reduce((sum, f) => sum + f.buffer.length, 0);
+        
+        console.log('\n📊 Extraction Statistics:');
+        console.log(`   Total fields: ${totalFields}`);
+        console.log(`   Successfully extracted: ${successfulFields}`);
+        console.log(`   Success rate: ${((successfulFields / totalFields) * 100).toFixed(1)}%`);
+        console.log(`   Total bytes processed: ${totalBytes}`);
+        console.log(`   Average field size: ${(totalBytes / successfulFields).toFixed(1)} bytes`);
+        
+        console.log('\n📋 Field Size Distribution:');
+        Object.entries(fieldDetails)
+            .filter(([name, data]) => data.buffer)
+            .sort((a, b) => b[1].buffer.length - a[1].buffer.length)
+            .forEach(([name, data]) => {
+                const percentage = ((data.buffer.length / totalBytes) * 100).toFixed(1);
+                console.log(`   ${name.padEnd(15)}: ${data.buffer.length.toString().padStart(2)} bytes (${percentage.padStart(4)}%)`);
+            });
+        
+        // Final validation
+        console.log('\n✅ Demonstration Complete!');
+        console.log(`   UTXOs generated: ${utxos.length}`);
+        console.log(`   Transaction created: ${tx.id}`);
+        console.log(`   Preimage extracted: ${preimageBuffer.length} bytes`);
+        console.log(`   Fields separated: ${successfulFields}/${totalFields}`);
+        console.log(`   Reconstruction: ${matches ? 'Success' : 'Partial'}`);
+        
+        return {
+            utxos,
+            transaction: tx,
+            preimage: preimageBuffer,
+            fields: fieldDetails,
+            statistics: {
+                totalFields,
+                successfulFields,
+                totalBytes,
+                reconstructionMatches: matches
+            }
+        };
+        
+    } catch (error) {
+        console.error('\n❌ Demonstration failed:', error.message);
+        console.error('Stack trace:', error.stack);
+        throw error;
+    }
+}
+
+// Run the demonstration
+if (require.main === module) {
+    demonstrateUTXOAndPreimage()
+        .then(result => {
+            console.log('\n🎉 All operations completed successfully!');
+        })
+        .catch(error => {
+            console.error('\n💥 Demonstration failed:', error.message);
+            process.exit(1);
+        });
+}
+
+module.exports = { demonstrateUTXOAndPreimage };

package/demos/script_helper_demo.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+/**
+ * Script Helper Utilities Demo
+ * ============================
+ * 
+ * Demonstrates the SmartLedger-BSV Script Helper utilities for
+ * Bitcoin Script development and analysis.
+ * 
+ * Features demonstrated:
+ * - Script building and construction
+ * - ASM parsing and generation
+ * - Script analysis and optimization
+ * - Opcode utilities and mapping
+ * - Script debugging tools
+ */
+
+const bsv = require('../index.js');
+
+console.log('🛠️  SmartLedger-BSV Script Helper Demo');
+console.log('======================================\n');
+
+async function demonstrateScriptHelper() {
+  try {
+    // Check if custom script helper is available
+    let ScriptHelper;
+    try {
+      ScriptHelper = require('../lib/custom-script-helper.js');
+      console.log('✅ Custom Script Helper loaded');
+    } catch (e) {
+      console.log('ℹ️  Using built-in BSV Script utilities');
+      ScriptHelper = null;
+    }
+
+    // Test 1: Basic Script Construction
+    console.log('🏗️  Test 1: Basic Script Construction');
+    console.log('------------------------------------');
+    
+    // P2PKH script
+    const privateKey = bsv.PrivateKey.fromRandom();
+    const address = privateKey.toAddress();
+    const p2pkhScript = bsv.Script.buildPublicKeyHashOut(address);
+    
+    console.log('🔐 Generated Address:', address.toString());
+    console.log('📜 P2PKH Script ASM:', p2pkhScript.toString());
+    console.log('🔢 P2PKH Script Hex:', p2pkhScript.toHex());
+    console.log('📏 Script Size:', p2pkhScript.toBuffer().length, 'bytes');
+    console.log('');
+
+    // P2SH script
+    const redeemScript = bsv.Script.buildMultisigOut([privateKey.publicKey], 1);
+    const p2shScript = bsv.Script.buildScriptHashOut(redeemScript);
+    
+    console.log('🔄 Redeem Script ASM:', redeemScript.toString());
+    console.log('📦 P2SH Script ASM:', p2shScript.toString());
+    console.log('🔢 P2SH Script Hex:', p2shScript.toHex());
+    console.log('');
+
+    // Test 2: Script Analysis
+    console.log('🔍 Test 2: Script Analysis');
+    console.log('-------------------------');
+    
+    const scripts = [
+      { name: 'P2PKH', script: p2pkhScript },
+      { name: 'P2SH', script: p2shScript },
+      { name: 'Multisig', script: redeemScript }
+    ];
+    
+    scripts.forEach(({ name, script }) => {
+      console.log(`📊 ${name} Analysis:`);
+      console.log(`   📏 Size: ${script.toBuffer().length} bytes`);
+      console.log(`   🧩 Chunks: ${script.chunks.length}`);
+      console.log(`   📋 Push-only: ${script.isPushOnly()}`);
+      console.log(`   🔗 Has multisig: ${script.toString().includes('CHECKMULTISIG')}`);
+      console.log(`   ⏰ Has timelock: ${script.toString().includes('CHECKLOCKTIMEVERIFY')}`);
+      console.log('');
+    });
+
+    // Test 3: Custom Script Building
+    console.log('⚙️  Test 3: Custom Script Building');
+    console.log('---------------------------------');
+    
+    // Build a custom script with various operations
+    const customScript = new bsv.Script()
+      .add(bsv.Opcode.OP_DUP)
+      .add(bsv.Opcode.OP_HASH160)
+      .add(address.hashBuffer)
+      .add(bsv.Opcode.OP_EQUALVERIFY)
+      .add(bsv.Opcode.OP_CHECKSIG);
+    
+    console.log('🛠️  Custom Script ASM:', customScript.toString());
+    console.log('🔢 Custom Script Hex:', customScript.toHex());
+    
+    // Verify it matches P2PKH
+    const isEquivalent = customScript.toString() === p2pkhScript.toString();
+    console.log('🎯 Equivalent to P2PKH:', isEquivalent ? '✅' : '❌');
+    console.log('');
+
+    // Test 4: Script Parsing and Conversion
+    console.log('🔄 Test 4: Script Parsing and Conversion');
+    console.log('---------------------------------------');
+    
+    const testASM = 'OP_DUP OP_HASH160 OP_PUSHDATA1 0x14 0x' + address.hashBuffer.toString('hex') + ' OP_EQUALVERIFY OP_CHECKSIG';
+    console.log('📝 Input ASM:', testASM);
+    
+    try {
+      const parsedScript = bsv.Script.fromASM(testASM);
+      console.log('✅ Successfully parsed ASM');
+      console.log('📜 Parsed Script:', parsedScript.toString());
+      console.log('🔢 Script Hex:', parsedScript.toHex());
+      
+      // Convert back to ASM
+      const backToASM = parsedScript.toString();
+      console.log('🔄 Back to ASM:', backToASM);
+      console.log('🎯 Round-trip success:', testASM.includes('OP_DUP') && backToASM.includes('OP_DUP') ? '✅' : '❌');
+      
+    } catch (error) {
+      console.log('❌ ASM parsing error:', error.message);
+    }
+    console.log('');
+
+    // Test 5: Opcode Analysis
+    console.log('🔤 Test 5: Opcode Analysis');
+    console.log('-------------------------');
+    
+    const opcodes = [
+      bsv.Opcode.OP_0,
+      bsv.Opcode.OP_1,
+      bsv.Opcode.OP_DUP,
+      bsv.Opcode.OP_HASH160,
+      bsv.Opcode.OP_EQUAL,
+      bsv.Opcode.OP_CHECKSIG,
+      bsv.Opcode.OP_CHECKMULTISIG,
+      bsv.Opcode.OP_CHECKLOCKTIMEVERIFY
+    ];
+    
+    console.log('📋 Common Opcodes:');
+    opcodes.forEach(opcode => {
+      const name = bsv.Opcode.reverseMap[opcode] || `OP_${opcode}`;
+      console.log(`   ${opcode.toString().padStart(3)} = ${name}`);
+    });
+    console.log('');
+
+    // Test 6: Script Complexity Analysis
+    console.log('📊 Test 6: Script Complexity Analysis');
+    console.log('------------------------------------');
+    
+    const complexScripts = [
+      {
+        name: 'Simple P2PKH',
+        script: p2pkhScript,
+        expectedOps: 5
+      },
+      {
+        name: 'Multisig 1-of-1',
+        script: redeemScript,
+        expectedOps: 4
+      },
+      {
+        name: 'Time Lock',
+        script: new bsv.Script()
+          .add(144) // ~24 hours in blocks
+          .add(bsv.Opcode.OP_CHECKLOCKTIMEVERIFY)
+          .add(bsv.Opcode.OP_DROP)
+          .add(bsv.Opcode.OP_DUP)
+          .add(bsv.Opcode.OP_HASH160)
+          .add(address.hashBuffer)
+          .add(bsv.Opcode.OP_EQUALVERIFY)
+          .add(bsv.Opcode.OP_CHECKSIG),
+        expectedOps: 8
+      }
+    ];
+    
+    complexScripts.forEach(({ name, script, expectedOps }) => {
+      const chunks = script.chunks.length;
+      const size = script.toBuffer().length;
+      const complexity = chunks > 10 ? 'High' : chunks > 5 ? 'Medium' : 'Low';
+      
+      console.log(`🔍 ${name}:`);
+      console.log(`   📊 Chunks: ${chunks} (expected ~${expectedOps})`);
+      console.log(`   📏 Size: ${size} bytes`);
+      console.log(`   ⚡ Complexity: ${complexity}`);
+      console.log(`   💰 Est. fee (1 sat/byte): ${size} satoshis`);
+      console.log('');
+    });
+
+    // Test 7: Script Validation
+    console.log('✅ Test 7: Script Validation');
+    console.log('---------------------------');
+    
+    const validationTests = [
+      {
+        name: 'Valid P2PKH',
+        script: p2pkhScript,
+        shouldPass: true
+      },
+      {
+        name: 'Valid Multisig',
+        script: redeemScript,
+        shouldPass: true
+      },
+      {
+        name: 'Empty Script',
+        script: new bsv.Script(),
+        shouldPass: true
+      },
+      {
+        name: 'Invalid Opcode Script',
+        script: (() => {
+          try {
+            return new bsv.Script().add(255); // Invalid opcode
+          } catch (e) {
+            return null;
+          }
+        })(),
+        shouldPass: false
+      }
+    ];
+    
+    validationTests.forEach(({ name, script, shouldPass }) => {
+      if (!script) {
+        console.log(`⚠️  ${name}: Could not create (expected for invalid tests)`);
+        return;
+      }
+      
+      try {
+        const isValid = script.toBuffer().length >= 0; // Basic validation
+        console.log(`${isValid === shouldPass ? '✅' : '❌'} ${name}: ${isValid ? 'Valid' : 'Invalid'}`);
+      } catch (error) {
+        const failed = !shouldPass;
+        console.log(`${failed ? '✅' : '❌'} ${name}: Failed validation (${error.message.substring(0, 30)}...)`);
+      }
+    });
+    console.log('');
+
+    // Test 8: Performance Metrics
+    console.log('🚀 Test 8: Performance Metrics');
+    console.log('-----------------------------');
+    
+    const iterations = 1000;
+    
+    // Script creation performance
+    const createStart = Date.now();
+    for (let i = 0; i < iterations; i++) {
+      const tempKey = bsv.PrivateKey.fromRandom();
+      const tempAddr = tempKey.toAddress();
+      bsv.Script.buildPublicKeyHashOut(tempAddr);
+    }
+    const createEnd = Date.now();
+    const createTime = createEnd - createStart;
+    
+    // Script parsing performance
+    const parseStart = Date.now();
+    const testScript = p2pkhScript.toString();
+    for (let i = 0; i < iterations; i++) {
+      bsv.Script.fromASM(testScript);
+    }
+    const parseEnd = Date.now();
+    const parseTime = parseEnd - parseStart;
+    
+    console.log(`⏱️  Script Creation: ${createTime}ms for ${iterations} scripts`);
+    console.log(`📊 Creation Rate: ${(iterations * 1000 / createTime).toFixed(0)} scripts/second`);
+    console.log(`⏱️  Script Parsing: ${parseTime}ms for ${iterations} parses`);
+    console.log(`📊 Parsing Rate: ${(iterations * 1000 / parseTime).toFixed(0)} parses/second`);
+
+  } catch (error) {
+    console.error('❌ Demo error:', error.message);
+    console.error('📋 Stack:', error.stack);
+  }
+}
+
+// Run the demo
+demonstrateScriptHelper().then(() => {
+  console.log('\n🎉 Script Helper Demo completed!');
+  console.log('');
+  console.log('💡 Use Cases:');
+  console.log('  • Custom script development and testing');
+  console.log('  • Script analysis and optimization');
+  console.log('  • Educational Bitcoin Script learning');
+  console.log('  • Smart contract script generation');
+  console.log('  • Transaction script debugging');
+  console.log('  • Fee estimation for complex scripts');
+  console.log('');
+  console.log('🔧 Integration Tips:');
+  console.log('  • Use with SmartContract framework for covenants');
+  console.log('  • Combine with UTXOGenerator for complete testing');
+  console.log('  • Store optimized scripts for production use');
+  console.log('  • Validate scripts before blockchain deployment');
+});