@smartledger/bsv 3.2.0 → 3.2.1

package/lib/smart_contract/API_REFERENCE.md

@@ -6,12 +6,13 @@
 
 1. [Quick Start](#quick-start)
 2. [Core Classes](#core-classes)
-3. [Interface Functions (29 Total)](#interface-functions)
+3. [Interface Functions (52 Total)](#interface-functions)
 4. [JavaScript-to-Script Framework](#javascript-to-script-framework)
 5. [CovenantBuilder API (61 Methods)](#covenantbuilder-api)
 6. [Opcode Mapping System](#opcode-mapping-system)
-7. [Real-World Examples](#real-world-examples)
-8. [Error Handling](#error-handling)
+7. [Debug and Analysis Tools](#debug-and-analysis-tools)
+8. [Real-World Examples](#real-world-examples)
+9. [Error Handling](#error-handling)
 
 ---
 
@@ -598,6 +599,113 @@ console.log('Result stack:', newStack)  // ['05'] (2 + 3 = 5)
 
 ---
 
+## Debug and Analysis Tools
+
+### Stack Examination
+
+**Examine stack states during script execution**
+
+```javascript
+// Examine stack evolution step-by-step
+const lockingScript = "76a914" + "89abcdef".repeat(5) + "88ac"  // P2PKH
+const unlockingScript = "47" + "30440220".repeat(4) + "01"      // Signature
+
+const success = SmartContract.examineStack(lockingScript, unlockingScript)
+// Outputs:
+// 🔍 STACK EXAMINATION TOOL
+// 🧩 Step 1: PUSH (signature)
+// Stack: ['30440220...']
+// 🧩 Step 2: OP_DUP
+// Stack: ['30440220...', '30440220...']
+// ... continues through all opcodes
+```
+
+### Script Debugging
+
+**Interactive script debugging with step-by-step execution**
+
+```javascript
+// Parse script from ASM or HEX
+const unlocking = SmartContract.parseScript("OP_1 OP_2")
+const locking = SmartContract.parseScript("OP_ADD OP_3 OP_EQUAL")
+
+// Debug with full verification
+SmartContract.debugScriptExecution(unlocking, locking, {
+  stepMode: false  // Set to true for interactive step-by-step
+})
+// Outputs:
+// 🔍 SCRIPT INTERPRETER DEBUGGER (FULL RUN)
+// 🔐 Locking Script: OP_ADD OP_3 OP_EQUAL
+// 🔓 Unlocking Script: OP_1 OP_2
+// ✅ Result: TRUE (Success)
+```
+
+### Stack State Analysis
+
+**Manual stack inspection and formatting**
+
+```javascript
+const stack = [Buffer.from('01', 'hex'), Buffer.from('02', 'hex')]
+const altstack = [Buffer.from('ff', 'hex')]
+
+SmartContract.printStack(stack, altstack)
+// Output:
+// Stack: ['01', '02']
+// AltStack: ['ff']
+```
+
+### Advanced Script Analysis
+
+**Comprehensive script analysis and optimization**
+
+```javascript
+// Analyze script complexity and find optimizations
+const script = bsv.Script.fromASM("OP_DUP OP_DUP OP_DROP OP_HASH160")
+
+const analysis = SmartContract.analyzeComplexity(script)
+console.log('Complexity score:', analysis.score)
+console.log('Optimization suggestions:', analysis.suggestions)
+
+const optimized = SmartContract.optimizeScript(script)
+console.log('Original ASM:', script.toASM())
+console.log('Optimized ASM:', optimized.toASM())
+
+// Explain script in human-readable format
+const explanation = SmartContract.explainScript(script)
+console.log('Script explanation:', explanation)
+```
+
+### Batch Testing
+
+**Test multiple scripts efficiently**
+
+```javascript
+const scripts = [
+  {
+    name: 'P2PKH Test',
+    unlocking: '47304402...',
+    locking: '76a914...88ac',
+    expectedResult: true
+  },
+  {
+    name: 'Multi-sig Test',
+    unlocking: '004730440...',
+    locking: '52210...53ae',
+    expectedResult: true
+  }
+]
+
+const results = SmartContract.batchTestScripts(scripts, {
+  verbose: true,
+  stopOnFailure: false
+})
+
+console.log('Batch test results:', results)
+// { passed: 2, failed: 0, results: [...] }
+```
+
+---
+
 ## Real-World Examples
 
 ### Example 1: Value-Preserving Covenant

package/lib/smart_contract/index.js

@@ -15,6 +15,9 @@
  * - ScriptTester: Local script execution and debugging capabilities
  * - CovenantBuilder: JavaScript-to-Bitcoin Script covenant generator
  * - OpcodeMap: Comprehensive Bitcoin Script opcode mapping
+ * - ScriptUtils: Script analysis, conversion, and optimization utilities
+ * - StackExaminer: Stack state examination and step-by-step execution debugging
+ * - ScriptInterpreter: Interactive script debugging with full verification support
  */
 
 'use strict'
@@ -31,7 +34,9 @@ var SmartContract = {
   CovenantBuilder: require('./covenant_builder').CovenantBuilder,
   CovenantTemplates: require('./covenant_builder').CovenantTemplates,
   OpcodeMap: require('./opcode_map'),
-  ScriptUtils: require('./script_utils')
+  ScriptUtils: require('./script_utils'),
+  StackExaminer: require('./stack_examiner'),
+  ScriptInterpreter: require('./script_interpreter')
 }
 
 // Convenience constructor methods
@@ -184,6 +189,36 @@ SmartContract.batchTestScripts = function(scripts, options) {
   return SmartContract.ScriptUtils.batchTestScripts(scripts, options)
 }
 
+// Debug and analysis tools
+SmartContract.examineStack = function(lockingHex, unlockingHex) {
+  return SmartContract.StackExaminer.runScript(lockingHex, unlockingHex)
+}
+
+SmartContract.debugScriptExecution = function(unlockingScript, lockingScript, options) {
+  options = options || {}
+  if (options.stepMode) {
+    return SmartContract.ScriptInterpreter.stepThroughScript(
+      SmartContract.ScriptInterpreter.parseScript(unlockingScript + ' ' + lockingScript),
+      new bsv.Transaction(),
+      true
+    )
+  } else {
+    return SmartContract.ScriptInterpreter.runFullEvaluation(
+      SmartContract.ScriptInterpreter.parseScript(unlockingScript),
+      SmartContract.ScriptInterpreter.parseScript(lockingScript),
+      new bsv.Transaction()
+    )
+  }
+}
+
+SmartContract.parseScript = function(scriptInput) {
+  return SmartContract.ScriptInterpreter.parseScript(scriptInput)
+}
+
+SmartContract.printStack = function(stack, altstack) {
+  return SmartContract.ScriptInterpreter.printStack(stack, altstack)
+}
+
 // Quick covenant creation utility
 SmartContract.createQuickCovenant = function(type, params) {
   const builder = SmartContract.createCovenantBuilder()
@@ -305,6 +340,10 @@ SmartContract.features = {
   BATCH_TESTING: true,
   QUICK_COVENANTS: true,
   SCRIPT_EXPLANATIONS: true,
+  STACK_EXAMINATION: true,
+  SCRIPT_DEBUGGING: true,
+  STEP_BY_STEP_EXECUTION: true,
+  INTERACTIVE_DEBUGGING: true,
   PRODUCTION_READY: true
 }
 

package/lib/smart_contract/script_interpreter.js

@@ -0,0 +1,236 @@
+/**
+ * script_interpreter_debugger.js
+ * ---------------------------------------------------------------
+ * Universal Bitcoin Script Interpreter Debugger for BSV
+ * Browser + Node.js compatible
+ * ---------------------------------------------------------------
+ * Usage:
+ *   node script_interpreter_debugger.js [options]
+ *
+ * Options:
+ *   --unlocking <hex|asm>     Unlocking script (input scriptSig)
+ *   --locking <hex|asm>       Locking script (output scriptPubKey)
+ *   --combined <hex|asm>      Combined script (unlocking + locking)
+ *   --step                    Step through opcode-by-opcode
+ *   --truth                   Run full verification (TRUE/FALSE)
+ *
+ * Examples:
+ *   node script_interpreter_debugger.js --locking "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac" --unlocking "4104abcd1234...ac" --truth
+ *   node script_interpreter_debugger.js --combined "OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG" --step
+ */
+
+// Browser-safe requires
+let readline = null;
+try {
+  // Only require readline in Node.js environment
+  if (typeof window === 'undefined' && typeof require !== 'undefined') {
+    readline = require("readline");
+  }
+} catch (err) {
+  // Gracefully handle missing readline in browser
+  readline = null;
+}
+
+const bsv = (typeof window !== 'undefined' && window.bsv) ? window.bsv : require("../../index.js");
+
+// Debug: Show Script Interpreter module structure (uncomment to inspect)
+// const ScriptInterpreter = bsv.Script.Interpreter;
+// console.log("Script Interpreter Module:", ScriptInterpreter);
+/**
+ * Parse input as either ASM or HEX.
+ */
+function parseScript(input) {
+  if (!input) return new bsv.Script();
+  const trimmed = input.trim();
+  const isHex = /^[0-9a-fA-F]+$/.test(trimmed.replace(/\s+/g, ""));
+  try {
+    return isHex
+      ? bsv.Script.fromHex(trimmed)
+      : bsv.Script.fromASM(trimmed);
+  } catch (err) {
+    console.error("❌ Error parsing script:", err.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Display stack contents in readable format.
+ */
+function printStack(stack, altstack = []) {
+  const fmt = (b) => (b.length ? b.toString("hex") : "(empty)");
+  const top = stack.map(fmt);
+  console.log("Stack:", top.length ? top : ["(empty)"]);
+  if (altstack.length) console.log("AltStack:", altstack.map(fmt));
+}
+
+/**
+ * Execute script step-by-step with optional interactivity.
+ */
+async function stepThroughScript(combinedScript, tx, verbose = true) {
+  const interpreter = new bsv.Script.Interpreter();
+  interpreter.script = combinedScript;
+  interpreter.tx = tx;
+  interpreter.nIn = 0;
+  interpreter.flags = bsv.Script.Interpreter.SCRIPT_ENABLE_SIGHASH_FORKID;
+
+  const chunks = combinedScript.chunks;
+  
+  // Browser compatibility check for readline
+  let rl = null;
+  if (readline && typeof process !== 'undefined' && process.stdin) {
+    rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+  }
+
+  console.log("===========================================");
+  console.log("🔍 SCRIPT INTERPRETER DEBUGGER (STEP MODE)");
+  console.log("===========================================\n");
+  console.log("Script:", combinedScript.toASM());
+  console.log("-------------------------------------------");
+
+  for (let i = 0; i < chunks.length; i++) {
+    const chunk = chunks[i];
+    const opname = bsv.Opcode.reverseMap[chunk.opcodenum] || "PUSH";
+
+    if (verbose && rl) {
+      await new Promise((resolve) =>
+        rl.question(`\n[${i + 1}/${chunks.length}] Step (${opname}) — press Enter to execute...`, resolve)
+      );
+    } else if (verbose) {
+      console.log(`\n[${i + 1}/${chunks.length}] Step (${opname})`);
+    }
+
+    try {
+      // Check if step method exists (compatibility check)
+      if (typeof interpreter.step === 'function') {
+        interpreter.step();
+      } else {
+        console.log("⚠️ Step-by-step execution not supported in this BSV version");
+        console.log("💡 Consider using runFullEvaluation instead");
+        break;
+      }
+      
+      console.log(`🧩 Executed: ${opname}`);
+      printStack(interpreter.stack, interpreter.altstack);
+    } catch (err) {
+      console.log(`⚠️  Error executing ${opname}: ${err.message}`);
+      break;
+    }
+  }
+
+  if (rl) rl.close();
+  console.log("\n===========================================");
+  console.log("✅ Final Stack State:");
+  printStack(interpreter.stack || [], interpreter.altstack || []);
+  console.log("===========================================");
+}
+
+/**
+ * Run complete truth evaluation (non-interactive)
+ */
+function runFullEvaluation(unlockingScript, lockingScript, tx) {
+  console.log("===========================================");
+  console.log("🔍 SCRIPT INTERPRETER DEBUGGER (FULL RUN)");
+  console.log("===========================================\n");
+
+  const interpreter = new bsv.Script.Interpreter();
+  
+  // For smartledger-bsv, need to provide satoshisBN parameter
+  const satoshisBN = new bsv.crypto.BN(100000); // 100,000 satoshis
+  
+  const verified = interpreter.verify(
+    unlockingScript,
+    lockingScript,
+    tx,
+    0,
+    bsv.Script.Interpreter.SCRIPT_ENABLE_SIGHASH_FORKID,
+    satoshisBN
+  );
+
+  console.log("🔐 Locking Script:", lockingScript.toASM());
+  console.log("🔓 Unlocking Script:", unlockingScript.toASM());
+  console.log("-------------------------------------------");
+  console.log("✅ Result:", verified ? "TRUE (Success)" : "❌ FALSE (Failure)");
+  console.log("Final Stack:", interpreter.stack.map((b) => b.toString("hex")));
+  console.log("AltStack:", interpreter.altstack.map((b) => b.toString("hex")));
+  console.log("===========================================");
+}
+
+/**
+ * Main entrypoint
+ */
+async function main() {
+  // Browser compatibility check
+  if (typeof process === 'undefined' || !process.argv) {
+    console.log("⚙️ CLI mode not available in browser environment");
+    return;
+  }
+
+  const args = process.argv.slice(2);
+  const getArg = (name) => {
+    const idx = args.indexOf(name);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+  };
+
+  const unlockingInput = getArg("--unlocking");
+  const lockingInput = getArg("--locking");
+  const combinedInput = getArg("--combined");
+  const stepMode = args.includes("--step");
+  const truthMode = args.includes("--truth");
+
+  // Build scripts
+  let unlockingScript, lockingScript, combinedScript;
+  if (combinedInput) {
+    combinedScript = parseScript(combinedInput);
+  } else {
+    unlockingScript = parseScript(unlockingInput);
+    lockingScript = parseScript(lockingInput);
+    const combinedBuf = Buffer.concat([
+      unlockingScript.toBuffer(),
+      lockingScript.toBuffer(),
+    ]);
+    combinedScript = bsv.Script.fromBuffer(combinedBuf);
+  }
+
+  // Dummy TX context for interpreter
+  const tx = new bsv.Transaction();
+  
+  // Create proper input with UTXO information
+  const dummyInput = new bsv.Transaction.Input({
+    prevTxId: '0'.repeat(64),
+    outputIndex: 0,
+    script: bsv.Script.empty(),
+    satoshis: 100000,
+    output: new bsv.Transaction.Output({
+      satoshis: 100000,
+      script: bsv.Script.empty()
+    })
+  });
+  
+  tx.addInput(dummyInput);
+  tx.addOutput(new bsv.Transaction.Output({ satoshis: 100000, script: bsv.Script.empty() }));
+
+  if (stepMode) {
+    await stepThroughScript(combinedScript, tx, true);
+  } else if (truthMode) {
+    runFullEvaluation(unlockingScript || bsv.Script.empty(), lockingScript || bsv.Script.empty(), tx);
+  } else {
+    console.log("⚙️  No mode specified. Use --step or --truth");
+  }
+}
+
+// Export functions for module usage
+module.exports = {
+  parseScript,
+  printStack,
+  stepThroughScript,
+  runFullEvaluation,
+  main
+};
+
+// CLI execution
+if (typeof require !== 'undefined' && require.main === module) {
+  main();
+}

package/lib/smart_contract/script_utils.js

@@ -176,7 +176,7 @@ function scriptMetrics(script) {
     }
     
     const asm = validation.asm
-    const operations = asm.split(' ')
+    const operations = asm.split(' ').filter(op => op.length > 0) // Filter out empty strings
     const size = validation.size
     
     // Analyze operation types
@@ -199,9 +199,11 @@ function scriptMetrics(script) {
     })
     
     return {
-      size: size,
+      length: size,                    // Changed from 'size' to 'length' for consistency
+      size: size,                      // Keep both for compatibility
       operations: operations.length,
-      opcodes: opcodeCount,
+      opcodeCount: opcodeCount,        // Changed from 'opcodes' for clarity
+      opcodes: opcodeCount,            // Keep both for compatibility
       dataElements: dataCount,
       estimatedCost: executionCost,
       complexity: executionCost > 50 ? 'high' : executionCost > 10 ? 'medium' : 'low',
@@ -287,13 +289,23 @@ function optimizeScript(script) {
     const originalSize = estimateScriptSize(asm)
     const optimizedSize = estimateScriptSize(optimizedASM)
     
+    // Create script object from optimized ASM
+    let optimizedScript = null
+    try {
+      optimizedScript = bsv.Script.fromASM(optimizedASM)
+    } catch (err) {
+      // If we can't create a script object, that's okay
+      optimizedScript = null
+    }
+    
     return {
       original: asm,
       optimized: optimizedASM,
       originalSize: originalSize,
       optimizedSize: optimizedSize,
       savings: originalSize - optimizedSize,
-      improvement: originalSize > 0 ? ((originalSize - optimizedSize) / originalSize * 100).toFixed(1) + '%' : '0%'
+      improvement: originalSize > 0 ? ((originalSize - optimizedSize) / originalSize * 100).toFixed(1) + '%' : '0%',
+      script: optimizedScript  // Add the script object
     }
   } catch (error) {
     return { error: error.message }

package/lib/smart_contract/stack_examiner.js

@@ -0,0 +1,129 @@
+/**
+ * Stack Examination Tool (Browser + Node.js compatible)
+ * -----------------------------------------
+ * Run with:
+ *   node stack_examiner.js <locking_script_hex> <unlocking_script_hex>
+ *
+ * Example:
+ *   node stack_examiner.js "76a91489abcdefabbaabbaabbaabbaabbaabbaabbaabba88ac" "512103abcdef..."
+ *
+ * Browser usage:
+ *   const examiner = require('./stack_examiner.js');
+ *   examiner.runScript(lockingHex, unlockingHex);
+ */
+
+// Browser-safe require
+const bsv = (typeof window !== 'undefined' && window.bsv) ? window.bsv : require('../../index.js');
+const util = require('util');
+
+function bufferToHexArray(stack) {
+  return stack.map((buf) => buf.toString('hex'));
+}
+
+/**
+ * Executes a locking/unlocking script and prints intermediate stack states.
+ */
+function runScript(lockingHex, unlockingHex) {
+  console.log("===========================================");
+  console.log("🔍 STACK EXAMINATION TOOL");
+  console.log("===========================================\n");
+
+  console.log("🔐 Locking Script:", lockingHex);
+  console.log("🔓 Unlocking Script:", unlockingHex);
+  console.log("-------------------------------------------");
+
+  try {
+    const lockingScript = bsv.Script.fromHex(lockingHex);
+    const unlockingScript = bsv.Script.fromHex(unlockingHex);
+
+    const combined = bsv.Script.fromBuffer(
+      Buffer.concat([unlockingScript.toBuffer(), lockingScript.toBuffer()])
+    );
+
+    const interpreter = new bsv.Script.Interpreter();
+    const tx = new bsv.Transaction();
+    
+    // Create proper transaction context
+    const dummyInput = new bsv.Transaction.Input({
+      prevTxId: '0'.repeat(64),
+      outputIndex: 0,
+      script: bsv.Script.empty()
+    });
+    
+    tx.addInput(dummyInput);
+    tx.addOutput(new bsv.Transaction.Output({ 
+      satoshis: 100000, 
+      script: lockingScript 
+    }));
+
+    const scriptChunks = combined.chunks;
+    const sandbox = new bsv.Script.Interpreter();
+    sandbox.script = combined;
+    sandbox.tx = tx;
+    sandbox.nIn = 0;
+    sandbox.flags = bsv.Script.Interpreter.SCRIPT_ENABLE_SIGHASH_FORKID;
+
+    // Step through each opcode
+    for (let i = 0; i < scriptChunks.length; i++) {
+      const chunk = scriptChunks[i];
+      try {
+        // Check if step method exists (compatibility check)
+        if (typeof sandbox.step === 'function') {
+          sandbox.step();
+        } else {
+          console.log("⚠️ Step-by-step execution not supported in this BSV version");
+          break;
+        }
+        
+        console.log(`\n🧩 Step ${i + 1}: ${bsv.Opcode.reverseMap[chunk.opcodenum] || 'PUSH'}`);
+        console.log("Stack:", bufferToHexArray(sandbox.stack));
+        console.log("AltStack:", bufferToHexArray(sandbox.altstack));
+      } catch (err) {
+        console.log(`⚠️ Error executing opcode ${i + 1}:`, err.message);
+        break;
+      }
+    }
+
+    // Final verification with proper satoshis parameter
+    const satoshisBN = new bsv.crypto.BN(100000);
+    const verified = interpreter.verify(
+      unlockingScript,
+      lockingScript,
+      tx,
+      0,
+      bsv.Script.Interpreter.SCRIPT_ENABLE_SIGHASH_FORKID,
+      satoshisBN
+    );
+
+    console.log("\n===========================================");
+    console.log("✅ Final Result:", verified ? "TRUE (Success)" : "❌ FALSE (Failure)");
+    console.log("Final Stack:", bufferToHexArray(sandbox.stack || []));
+    console.log("AltStack:", bufferToHexArray(sandbox.altstack || []));
+    console.log("===========================================");
+    
+    return verified;
+  } catch (err) {
+    console.error("❌ Error in script execution:", err.message);
+    return false;
+  }
+}
+
+// ============================================
+// CLI Entrypoint
+// ============================================
+if (typeof require !== 'undefined' && require.main === module) {
+  if (process.argv.length < 4) {
+    console.log("Usage: node stack_examiner.js <locking_script_hex> <unlocking_script_hex>");
+    process.exit(1);
+  }
+
+  const locking = process.argv[2];
+  const unlocking = process.argv[3];
+  runScript(locking, unlocking);
+}
+
+// Export for module usage
+module.exports = {
+  runScript,
+  bufferToHexArray
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smartledger/bsv",
-  "version": "3.2.0",
-  "description": "Advanced Bitcoin SV library with JavaScript-to-Bitcoin Script framework - Complete BSV API + BIP143 preimage parsing + 121 opcode mapping + covenant builder + nChain PUSHTX techniques + custom script development",
+  "version": "3.2.1",
+  "description": "Advanced Bitcoin SV library with JavaScript-to-Bitcoin Script framework - Complete BSV API + BIP143 preimage parsing + 121 opcode mapping + covenant builder + nChain PUSHTX techniques + custom script development + integrated debugging tools",
   "author": "SmartLedger Technology <hello@smartledger.technology> (https://smartledger.technology)",
   "homepage": "https://github.com/codenlighten/smartledger-bsv#readme",
   "bugs": {